/ Hex Artifact Content
Login

Artifact 4c41b702bf6a105a485dfb61065f941c8cb0357d:


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 34 32 20 32 30 30 38 2f  in,v 1.342 2008/
05f0: 30 36 2f 32 30 20 31 34 3a 35 39 3a 35 31 20 64  06/20 14:59:51 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 0a 2f 2a 0a 2a 2a 20  (void);.../*.** 
1680: 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61  CAPI3REF: Databa
1690: 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 48 61  se Connection Ha
16a0: 6e 64 6c 65 20 7b 46 31 32 30 30 30 7d 0a 2a 2a  ndle {F12000}.**
16b0: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61 74 61   KEYWORDS: {data
16c0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 7d  base connection}
16d0: 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   {database conne
16e0: 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 61  ctions}.**.** Ea
16f0: 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20 64  ch open SQLite d
1700: 61 74 61 62 61 73 65 20 69 73 20 72 65 70 72 65  atabase is repre
1710: 73 65 6e 74 65 64 20 62 79 20 70 6f 69 6e 74 65  sented by pointe
1720: 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65  r to an instance
1730: 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 70 61 71 75   of the.** opaqu
1740: 65 20 73 74 72 75 63 74 75 72 65 20 6e 61 6d 65  e structure name
1750: 64 20 22 73 71 6c 69 74 65 33 22 2e 20 20 49 74  d "sqlite3".  It
1760: 20 69 73 20 75 73 65 66 75 6c 20 74 6f 20 74 68   is useful to th
1770: 69 6e 6b 20 6f 66 20 61 6e 20 73 71 6c 69 74 65  ink of an sqlite
1780: 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 61 73 20  3.** pointer as 
1790: 61 6e 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20  an object.  The 
17a0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
17b0: 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  , [sqlite3_open1
17c0: 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  6()], and.** [sq
17d0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
17e0: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
17f0: 69 74 73 20 63 6f 6e 73 74 72 75 63 74 6f 72 73  its constructors
1800: 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
1810: 5f 63 6c 6f 73 65 28 29 5d 20 69 73 20 69 74 73  _close()] is its
1820: 20 64 65 73 74 72 75 63 74 6f 72 2e 20 20 54 68   destructor.  Th
1830: 65 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68  ere are many oth
1840: 65 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  er interfaces.**
1850: 20 28 73 75 63 68 20 61 73 20 5b 73 71 6c 69 74   (such as [sqlit
1860: 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1870: 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  , [sqlite3_creat
1880: 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61  e_function()], a
1890: 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nd.** [sqlite3_b
18a0: 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74  usy_timeout()] t
18b0: 6f 20 6e 61 6d 65 20 62 75 74 20 74 68 72 65 65  o name but three
18c0: 29 20 74 68 61 74 20 61 72 65 20 6d 65 74 68 6f  ) that are metho
18d0: 64 73 20 6f 6e 20 74 68 69 73 0a 2a 2a 20 6f 62  ds on this.** ob
18e0: 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  ject..*/.typedef
18f0: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 20   struct sqlite3 
1900: 73 71 6c 69 74 65 33 3b 0a 0a 0a 2f 2a 0a 2a 2a  sqlite3;.../*.**
1910: 20 43 41 50 49 33 52 45 46 3a 20 36 34 2d 42 69   CAPI3REF: 64-Bi
1920: 74 20 49 6e 74 65 67 65 72 20 54 79 70 65 73 20  t Integer Types 
1930: 7b 46 31 30 32 30 30 7d 0a 2a 2a 20 4b 45 59 57  {F10200}.** KEYW
1940: 4f 52 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74  ORDS: sqlite_int
1950: 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  64 sqlite_uint64
1960: 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74  .**.** Because t
1970: 68 65 72 65 20 69 73 20 6e 6f 20 63 72 6f 73 73  here is no cross
1980: 2d 70 6c 61 74 66 6f 72 6d 20 77 61 79 20 74 6f  -platform way to
1990: 20 73 70 65 63 69 66 79 20 36 34 2d 62 69 74 20   specify 64-bit 
19a0: 69 6e 74 65 67 65 72 20 74 79 70 65 73 0a 2a 2a  integer types.**
19b0: 20 53 51 4c 69 74 65 20 69 6e 63 6c 75 64 65 73   SQLite includes
19c0: 20 74 79 70 65 64 65 66 73 20 66 6f 72 20 36 34   typedefs for 64
19d0: 2d 62 69 74 20 73 69 67 6e 65 64 20 61 6e 64 20  -bit signed and 
19e0: 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  unsigned integer
19f0: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  s..**.** The sql
1a00: 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73  ite3_int64 and s
1a10: 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 61 72  qlite3_uint64 ar
1a20: 65 20 74 68 65 20 70 72 65 66 65 72 72 65 64 20  e the preferred 
1a30: 74 79 70 65 0a 2a 2a 20 64 65 66 69 6e 69 74 69  type.** definiti
1a40: 6f 6e 73 2e 20 20 54 68 65 20 73 71 6c 69 74 65  ons.  The sqlite
1a50: 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74  _int64 and sqlit
1a60: 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20 61  e_uint64 types a
1a70: 72 65 0a 2a 2a 20 73 75 70 70 6f 72 74 65 64 20  re.** supported 
1a80: 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f  for backwards co
1a90: 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79  mpatibility only
1aa0: 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
1ab0: 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 32 30  TS:.**.** {F1020
1ac0: 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 5f 69  1} The [sqlite_i
1ad0: 6e 74 36 34 5d 20 61 6e 64 20 5b 73 71 6c 69 74  nt64] and [sqlit
1ae0: 65 33 5f 69 6e 74 36 34 5d 20 74 79 70 65 73 20  e3_int64] types 
1af0: 73 70 65 63 69 66 79 20 61 0a 2a 2a 20 20 20 20  specify a.**    
1b00: 20 20 20 20 20 20 36 34 2d 62 69 74 20 73 69 67        64-bit sig
1b10: 6e 65 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a  ned integer..**.
1b20: 2a 2a 20 7b 46 31 30 32 30 32 7d 20 54 68 65 20  ** {F10202} The 
1b30: 5b 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 5d 20  [sqlite_uint64] 
1b40: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 75 69 6e  and [sqlite3_uin
1b50: 74 36 34 5d 20 74 79 70 65 73 20 73 70 65 63 69  t64] types speci
1b60: 66 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  fy.**          a
1b70: 20 36 34 2d 62 69 74 20 75 6e 73 69 67 6e 65 64   64-bit unsigned
1b80: 20 69 6e 74 65 67 65 72 2e 0a 2a 2f 0a 23 69 66   integer..*/.#if
1b90: 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34  def SQLITE_INT64
1ba0: 5f 54 59 50 45 0a 20 20 74 79 70 65 64 65 66 20  _TYPE.  typedef 
1bb0: 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50  SQLITE_INT64_TYP
1bc0: 45 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a  E sqlite_int64;.
1bd0: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e    typedef unsign
1be0: 65 64 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f  ed SQLITE_INT64_
1bf0: 54 59 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74  TYPE sqlite_uint
1c00: 36 34 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e 65  64;.#elif define
1c10: 64 28 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64  d(_MSC_VER) || d
1c20: 65 66 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44  efined(__BORLAND
1c30: 43 5f 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f  C__).  typedef _
1c40: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e  _int64 sqlite_in
1c50: 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75  t64;.  typedef u
1c60: 6e 73 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20  nsigned __int64 
1c70: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23  sqlite_uint64;.#
1c80: 65 6c 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c  else.  typedef l
1c90: 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c  ong long int sql
1ca0: 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70  ite_int64;.  typ
1cb0: 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f  edef unsigned lo
1cc0: 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69  ng long int sqli
1cd0: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69  te_uint64;.#endi
1ce0: 66 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65  f.typedef sqlite
1cf0: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69  _int64 sqlite3_i
1d00: 6e 74 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71  nt64;.typedef sq
1d10: 6c 69 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69  lite_uint64 sqli
1d20: 74 65 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a  te3_uint64;../*.
1d30: 2a 2a 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20  ** If compiling 
1d40: 66 6f 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20  for a processor 
1d50: 74 68 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74  that lacks float
1d60: 69 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72  ing point suppor
1d70: 74 2c 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65  t,.** substitute
1d80: 20 69 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f   integer for flo
1d90: 61 74 69 6e 67 2d 70 6f 69 6e 74 0a 2a 2f 0a 23  ating-point.*/.#
1da0: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49  ifdef SQLITE_OMI
1db0: 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54  T_FLOATING_POINT
1dc0: 0a 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65  .# define double
1dd0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23   sqlite3_int64.#
1de0: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  endif../*.** CAP
1df0: 49 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41  I3REF: Closing A
1e00: 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
1e10: 74 69 6f 6e 20 7b 46 31 32 30 31 30 7d 0a 2a 2a  tion {F12010}.**
1e20: 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
1e30: 20 69 73 20 74 68 65 20 64 65 73 74 72 75 63 74   is the destruct
1e40: 6f 72 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69  or for the [sqli
1e50: 74 65 33 5d 20 6f 62 6a 65 63 74 2e 20 20 0a 2a  te3] object.  .*
1e60: 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e  *.** Application
1e70: 73 20 73 68 6f 75 6c 64 20 5b 73 71 6c 69 74 65  s should [sqlite
1e80: 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e  3_finalize | fin
1e90: 61 6c 69 7a 65 5d 20 61 6c 6c 0a 2a 2a 20 5b 70  alize] all.** [p
1ea0: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1eb0: 74 73 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  ts] and.** [sqli
1ec0: 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c  te3_blob_close |
1ed0: 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 73 71 6c   close] all [sql
1ee0: 69 74 65 33 5f 62 6c 6f 62 20 7c 20 42 4c 4f 42  ite3_blob | BLOB
1ef0: 73 5d 20 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65  s] .** associate
1f00: 64 20 77 69 74 68 20 74 68 65 20 5b 73 71 6c 69  d with the [sqli
1f10: 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 72 69 6f  te3] object prio
1f20: 72 0a 2a 2a 20 74 6f 20 61 74 74 65 6d 70 74 69  r.** to attempti
1f30: 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65 20  ng to close the 
1f40: 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
1f50: 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  .  The.** [sqlit
1f60: 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 29 5d 20  e3_next_stmt()] 
1f70: 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65  interface can be
1f80: 20 75 73 65 64 20 74 6f 20 6c 6f 63 61 74 65 20   used to locate 
1f90: 61 6c 6c 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  all.** [prepared
1fa0: 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 61 73 73   statements] ass
1fb0: 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20 5b  ociated with a [
1fc0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1fd0: 69 6f 6e 5d 0a 2a 2a 20 69 66 20 64 65 73 69 72  ion].** if desir
1fe0: 65 64 2e 20 20 54 79 70 69 63 61 6c 20 63 6f 64  ed.  Typical cod
1ff0: 65 20 6d 69 67 68 74 20 6c 6f 6f 6b 20 6c 69 6b  e might look lik
2000: 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  e this:.**.** <b
2010: 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
2020: 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ** sqlite3_stmt 
2030: 2a 70 53 74 6d 74 3b 0a 2a 2a 20 77 68 69 6c 65  *pStmt;.** while
2040: 28 20 28 70 53 74 6d 74 20 3d 20 73 71 6c 69 74  ( (pStmt = sqlit
2050: 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 64 62 2c  e3_next_stmt(db,
2060: 20 30 29 29 21 3d 30 20 29 7b 0a 2a 2a 20 26 6e   0))!=0 ){.** &n
2070: 62 73 70 3b 20 20 20 73 71 6c 69 74 65 33 5f 66  bsp;   sqlite3_f
2080: 69 6e 61 6c 69 7a 65 28 70 53 74 6d 74 29 3b 0a  inalize(pStmt);.
2090: 2a 2a 20 7d 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  ** }.** </pre></
20a0: 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
20b0: 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 63 6c  * If [sqlite3_cl
20c0: 6f 73 65 28 29 5d 20 69 73 20 69 6e 76 6f 6b 65  ose()] is invoke
20d0: 64 20 77 68 69 6c 65 20 61 20 74 72 61 6e 73 61  d while a transa
20e0: 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2c  ction is opened,
20f0: 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73 61 63 74  .** the transact
2100: 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ion is automatic
2110: 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ally rolled back
2120: 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
2130: 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 30 31  TS:.**.** {F1201
2140: 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
2150: 63 6c 6f 73 65 28 29 5d 20 69 6e 74 65 72 66 61  close()] interfa
2160: 63 65 20 64 65 73 74 72 6f 79 73 20 61 6e 20 5b  ce destroys an [
2170: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 0a  sqlite3] object.
2180: 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c 6c 6f  **          allo
2190: 63 61 74 65 64 20 62 79 20 61 20 70 72 69 6f 72  cated by a prior
21a0: 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
21b0: 33 5f 6f 70 65 6e 28 29 5d 2c 0a 2a 2a 20 20 20  3_open()],.**   
21c0: 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
21d0: 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72 20 5b 73  open16()], or [s
21e0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
21f0: 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 30 31 32  ]..**.** {F12012
2200: 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
2210: 6c 6f 73 65 28 29 5d 20 66 75 6e 63 74 69 6f 6e  lose()] function
2220: 20 72 65 6c 65 61 73 65 73 20 61 6c 6c 20 6d 65   releases all me
2230: 6d 6f 72 79 20 75 73 65 64 20 62 79 20 74 68 65  mory used by the
2240: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e  .**          con
2250: 6e 65 63 74 69 6f 6e 20 61 6e 64 20 63 6c 6f 73  nection and clos
2260: 65 73 20 61 6c 6c 20 6f 70 65 6e 20 66 69 6c 65  es all open file
2270: 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 30 31 33  s..**.** {F12013
2280: 7d 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73  } If the databas
2290: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6f 6e  e connection con
22a0: 74 61 69 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20  tains.**        
22b0: 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74    [prepared stat
22c0: 65 6d 65 6e 74 73 5d 20 74 68 61 74 20 68 61 76  ements] that hav
22d0: 65 20 6e 6f 74 20 62 65 65 6e 0a 2a 2a 20 20 20  e not been.**   
22e0: 20 20 20 20 20 20 20 66 69 6e 61 6c 69 7a 65 64         finalized
22f0: 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   by [sqlite3_fin
2300: 61 6c 69 7a 65 28 29 5d 2c 20 74 68 65 6e 20 5b  alize()], then [
2310: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d  sqlite3_close()]
2320: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74  .**          ret
2330: 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53  urns [SQLITE_BUS
2340: 59 5d 20 61 6e 64 20 6c 65 61 76 65 73 20 74 68  Y] and leaves th
2350: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65  e connection ope
2360: 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 30 31 34  n..**.** {F12014
2370: 7d 20 47 69 76 69 6e 67 20 73 71 6c 69 74 65 33  } Giving sqlite3
2380: 5f 63 6c 6f 73 65 28 29 20 61 20 4e 55 4c 4c 20  _close() a NULL 
2390: 70 6f 69 6e 74 65 72 20 69 73 20 61 20 68 61 72  pointer is a har
23a0: 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a  mless no-op..**.
23b0: 2a 2a 20 7b 46 31 32 30 31 39 7d 20 57 68 65 6e  ** {F12019} When
23c0: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
23d0: 29 5d 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e  )] is invoked on
23e0: 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
23f0: 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 20 20 20 20  nection].**     
2400: 20 20 20 20 20 74 68 61 74 20 68 61 73 20 61 20       that has a 
2410: 70 65 6e 64 69 6e 67 20 74 72 61 6e 73 61 63 74  pending transact
2420: 69 6f 6e 2c 20 74 68 65 20 74 72 61 6e 73 61 63  ion, the transac
2430: 74 69 6f 6e 20 73 68 61 6c 6c 20 62 65 0a 2a 2a  tion shall be.**
2440: 20 20 20 20 20 20 20 20 20 20 72 6f 6c 6c 65 64            rolled
2450: 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d   back..**.** LIM
2460: 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20  ITATIONS:.**.** 
2470: 7b 55 31 32 30 31 35 7d 20 54 68 65 20 70 61 72  {U12015} The par
2480: 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
2490: 65 33 5f 63 6c 6f 73 65 28 29 5d 20 6d 75 73 74  e3_close()] must
24a0: 20 62 65 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d   be an [sqlite3]
24b0: 20 6f 62 6a 65 63 74 0a 2a 2a 20 20 20 20 20 20   object.**      
24c0: 20 20 20 20 70 6f 69 6e 74 65 72 20 70 72 65 76      pointer prev
24d0: 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20  iously obtained 
24e0: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70  from [sqlite3_op
24f0: 65 6e 28 29 5d 20 6f 72 20 74 68 65 20 0a 2a 2a  en()] or the .**
2500: 20 20 20 20 20 20 20 20 20 20 65 71 75 69 76 61            equiva
2510: 6c 65 6e 74 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a  lent, or NULL..*
2520: 2a 0a 2a 2a 20 7b 55 31 32 30 31 36 7d 20 54 68  *.** {U12016} Th
2530: 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  e parameter to [
2540: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d  sqlite3_close()]
2550: 20 6d 75 73 74 20 6e 6f 74 20 68 61 76 65 20 62   must not have b
2560: 65 65 6e 20 70 72 65 76 69 6f 75 73 6c 79 0a 2a  een previously.*
2570: 2a 20 20 20 20 20 20 20 20 20 20 63 6c 6f 73 65  *          close
2580: 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  d..*/.int sqlite
2590: 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 20  3_close(sqlite3 
25a0: 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74  *);../*.** The t
25b0: 79 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61  ype for a callba
25c0: 63 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20  ck function..** 
25d0: 54 68 69 73 20 69 73 20 6c 65 67 61 63 79 20 61  This is legacy a
25e0: 6e 64 20 64 65 70 72 65 63 61 74 65 64 2e 20 20  nd deprecated.  
25f0: 49 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66  It is included f
2600: 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a  or historical.**
2610: 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61   compatibility a
2620: 6e 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65  nd is not docume
2630: 6e 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  nted..*/.typedef
2640: 20 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63   int (*sqlite3_c
2650: 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69  allback)(void*,i
2660: 6e 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a  nt,char**, char*
2670: 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
2680: 52 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75  REF: One-Step Qu
2690: 65 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e  ery Execution In
26a0: 74 65 72 66 61 63 65 20 7b 46 31 32 31 30 30 7d  terface {F12100}
26b0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
26c0: 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66  e3_exec() interf
26d0: 61 63 65 20 69 73 20 61 20 63 6f 6e 76 65 6e 69  ace is a conveni
26e0: 65 6e 74 20 77 61 79 20 6f 66 20 72 75 6e 6e 69  ent way of runni
26f0: 6e 67 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72  ng.** one or mor
2700: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
2710: 20 77 69 74 68 6f 75 74 20 61 20 6c 6f 74 20 6f   without a lot o
2720: 66 20 43 20 63 6f 64 65 2e 20 20 54 68 65 0a 2a  f C code.  The.*
2730: 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  * SQL statements
2740: 20 61 72 65 20 70 61 73 73 65 64 20 69 6e 20 61   are passed in a
2750: 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  s the second par
2760: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c  ameter to.** sql
2770: 69 74 65 33 5f 65 78 65 63 28 29 2e 20 20 54 68  ite3_exec().  Th
2780: 65 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65  e statements are
2790: 20 65 76 61 6c 75 61 74 65 64 20 6f 6e 65 20 62   evaluated one b
27a0: 79 20 6f 6e 65 0a 2a 2a 20 75 6e 74 69 6c 20 65  y one.** until e
27b0: 69 74 68 65 72 20 61 6e 20 65 72 72 6f 72 20 6f  ither an error o
27c0: 72 20 61 6e 20 69 6e 74 65 72 72 75 70 74 20 69  r an interrupt i
27d0: 73 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 6f 72  s encountered or
27e0: 0a 2a 2a 20 75 6e 74 69 6c 20 74 68 65 79 20 61  .** until they a
27f0: 72 65 20 61 6c 6c 20 64 6f 6e 65 2e 20 20 54 68  re all done.  Th
2800: 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
2810: 69 73 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 0a 2a  is an optional.*
2820: 2a 20 63 61 6c 6c 62 61 63 6b 20 74 68 61 74 20  * callback that 
2830: 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 65 20  is invoked once 
2840: 66 6f 72 20 65 61 63 68 20 72 6f 77 20 6f 66 20  for each row of 
2850: 61 6e 79 20 71 75 65 72 79 20 72 65 73 75 6c 74  any query result
2860: 73 0a 2a 2a 20 70 72 6f 64 75 63 65 64 20 62 79  s.** produced by
2870: 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
2880: 6e 74 73 2e 20 20 54 68 65 20 35 74 68 20 70 61  nts.  The 5th pa
2890: 72 61 6d 65 74 65 72 20 74 65 6c 6c 73 20 77 68  rameter tells wh
28a0: 65 72 65 0a 2a 2a 20 74 6f 20 77 72 69 74 65 20  ere.** to write 
28b0: 61 6e 79 20 65 72 72 6f 72 20 6d 65 73 73 61 67  any error messag
28c0: 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 65 72  es..**.** The er
28d0: 72 6f 72 20 6d 65 73 73 61 67 65 20 70 61 73 73  ror message pass
28e0: 65 64 20 62 61 63 6b 20 74 68 72 6f 75 67 68 20  ed back through 
28f0: 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  the 5th paramete
2900: 72 20 69 73 20 68 65 6c 64 0a 2a 2a 20 69 6e 20  r is held.** in 
2910: 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
2920: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
2930: 6c 6c 6f 63 28 29 5d 2e 20 20 54 6f 20 61 76 6f  lloc()].  To avo
2940: 69 64 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b  id a memory leak
2950: 2c 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 69 6e 67  ,.** the calling
2960: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
2970: 75 6c 64 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65  uld call [sqlite
2980: 33 5f 66 72 65 65 28 29 5d 20 6f 6e 20 61 6e 79  3_free()] on any
2990: 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67   error.** messag
29a0: 65 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f 75  e returned throu
29b0: 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61 6d  gh the 5th param
29c0: 65 74 65 72 20 77 68 65 6e 20 69 74 20 68 61 73  eter when it has
29d0: 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 0a   finished using.
29e0: 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  ** the error mes
29f0: 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  sage..**.** If t
2a00: 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
2a10: 20 69 6e 20 74 68 65 20 32 6e 64 20 70 61 72 61   in the 2nd para
2a20: 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 6f 72  meter is NULL or
2a30: 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
2a40: 0a 2a 2a 20 6f 72 20 61 20 73 74 72 69 6e 67 20  .** or a string 
2a50: 63 6f 6e 74 61 69 6e 69 6e 67 20 6f 6e 6c 79 20  containing only 
2a60: 77 68 69 74 65 73 70 61 63 65 20 61 6e 64 20 63  whitespace and c
2a70: 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20 53 51  omments, then SQ
2a80: 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20  L.** statements 
2a90: 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 61 6e  are evaluated an
2aa0: 64 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  d the database i
2ab0: 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a  s unchanged..**.
2ac0: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65  ** The sqlite3_e
2ad0: 78 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 20  xec() interface 
2ae0: 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 69  is implemented i
2af0: 6e 20 74 65 72 6d 73 20 6f 66 0a 2a 2a 20 5b 73  n terms of.** [s
2b00: 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2b10: 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73  2()], [sqlite3_s
2b20: 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c  tep()], and [sql
2b30: 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
2b40: 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  ..** The sqlite3
2b50: 5f 65 78 65 63 28 29 20 72 6f 75 74 69 6e 65 20  _exec() routine 
2b60: 64 6f 65 73 20 6e 6f 74 68 69 6e 67 20 74 6f 20  does nothing to 
2b70: 74 68 65 20 64 61 74 61 62 61 73 65 20 74 68 61  the database tha
2b80: 74 20 63 61 6e 6e 6f 74 20 62 65 20 64 6f 6e 65  t cannot be done
2b90: 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  .** by [sqlite3_
2ba0: 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b  prepare_v2()], [
2bb0: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c  sqlite3_step()],
2bc0: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66 69   and [sqlite3_fi
2bd0: 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  nalize()]..**.**
2be0: 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 20   INVARIANTS:.** 
2bf0: 0a 2a 2a 20 7b 46 31 32 31 30 31 7d 20 41 20 73  .** {F12101} A s
2c00: 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61  uccessful invoca
2c10: 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33  tion of [sqlite3
2c20: 5f 65 78 65 63 28 44 2c 53 2c 43 2c 41 2c 45 29  _exec(D,S,C,A,E)
2c30: 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 68  ].**          sh
2c40: 61 6c 6c 20 65 76 61 6c 75 61 74 65 20 61 6c 6c  all evaluate all
2c50: 20 6f 66 20 74 68 65 20 55 54 46 2d 38 20 65 6e   of the UTF-8 en
2c60: 63 6f 64 65 64 2c 20 73 65 6d 69 63 6f 6c 6f 6e  coded, semicolon
2c70: 2d 73 65 70 61 72 61 74 65 64 2c 0a 2a 2a 20 20  -separated,.**  
2c80: 20 20 20 20 20 20 20 20 53 51 4c 20 73 74 61 74          SQL stat
2c90: 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65  ements in the ze
2ca0: 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74  ro-terminated st
2cb0: 72 69 6e 67 20 53 20 77 69 74 68 69 6e 20 74 68  ring S within th
2cc0: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f  e.**          co
2cd0: 6e 74 65 78 74 20 6f 66 20 74 68 65 20 44 20 5b  ntext of the D [
2ce0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2cf0: 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  ion]..**.** {F12
2d00: 31 30 32 7d 20 49 66 20 74 68 65 20 53 20 70 61  102} If the S pa
2d10: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
2d20: 74 65 33 5f 65 78 65 63 28 44 2c 53 2c 43 2c 41  te3_exec(D,S,C,A
2d30: 2c 45 29 5d 20 69 73 20 4e 55 4c 4c 20 74 68 65  ,E)] is NULL the
2d40: 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  n.**          th
2d50: 65 20 61 63 74 69 6f 6e 73 20 6f 66 20 74 68 65  e actions of the
2d60: 20 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c   interface shall
2d70: 20 62 65 20 74 68 65 20 73 61 6d 65 20 61 73 20   be the same as 
2d80: 69 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  if the.**       
2d90: 20 20 20 53 20 70 61 72 61 6d 65 74 65 72 20 77     S parameter w
2da0: 68 65 72 65 20 61 6e 20 65 6d 70 74 79 20 73 74  here an empty st
2db0: 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  ring..**.** {F12
2dc0: 31 30 34 7d 20 54 68 65 20 72 65 74 75 72 6e 20  104} The return 
2dd0: 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65  value of [sqlite
2de0: 33 5f 65 78 65 63 28 29 5d 20 73 68 61 6c 6c 20  3_exec()] shall 
2df0: 62 65 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69  be [SQLITE_OK] i
2e00: 66 20 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20  f all.**        
2e10: 20 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73    SQL statements
2e20: 20 72 75 6e 20 73 75 63 63 65 73 73 66 75 6c 6c   run successfull
2e30: 79 20 61 6e 64 20 74 6f 20 63 6f 6d 70 6c 65 74  y and to complet
2e40: 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31  ion..**.** {F121
2e50: 30 35 7d 20 54 68 65 20 72 65 74 75 72 6e 20 76  05} The return v
2e60: 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33  alue of [sqlite3
2e70: 5f 65 78 65 63 28 29 5d 20 73 68 61 6c 6c 20 62  _exec()] shall b
2e80: 65 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65  e an appropriate
2e90: 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 6f   .**          no
2ea0: 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f  n-zero [error co
2eb0: 64 65 5d 20 69 66 20 61 6e 79 20 53 51 4c 20 73  de] if any SQL s
2ec0: 74 61 74 65 6d 65 6e 74 20 66 61 69 6c 73 2e 0a  tatement fails..
2ed0: 2a 2a 0a 2a 2a 20 7b 46 31 32 31 30 37 7d 20 49  **.** {F12107} I
2ee0: 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66  f one or more of
2ef0: 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
2f00: 6e 74 73 20 68 61 6e 64 65 64 20 74 6f 20 5b 73  nts handed to [s
2f10: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 0a 2a  qlite3_exec()].*
2f20: 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72  *          retur
2f30: 6e 20 72 65 73 75 6c 74 73 20 61 6e 64 20 74 68  n results and th
2f40: 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
2f50: 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65  is not NULL, the
2f60: 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  n.**          th
2f70: 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
2f80: 69 6f 6e 20 73 70 65 63 69 66 69 65 64 20 62 79  ion specified by
2f90: 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74   the 3rd paramet
2fa0: 65 72 20 73 68 61 6c 6c 20 62 65 0a 2a 2a 20 20  er shall be.**  
2fb0: 20 20 20 20 20 20 20 20 69 6e 76 6f 6b 65 64 20          invoked 
2fc0: 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20 72 6f  once for each ro
2fd0: 77 20 6f 66 20 72 65 73 75 6c 74 2e 0a 2a 2a 0a  w of result..**.
2fe0: 2a 2a 20 7b 46 31 32 31 31 30 7d 20 49 66 20 74  ** {F12110} If t
2ff0: 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
3000: 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 76  rns a non-zero v
3010: 61 6c 75 65 20 74 68 65 6e 20 5b 73 71 6c 69 74  alue then [sqlit
3020: 65 33 5f 65 78 65 63 28 29 5d 0a 2a 2a 20 20 20  e3_exec()].**   
3030: 20 20 20 20 20 20 20 73 68 61 6c 6c 20 61 62 6f         shall abo
3040: 72 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  rt the SQL state
3050: 6d 65 6e 74 20 69 74 20 69 73 20 63 75 72 72 65  ment it is curre
3060: 6e 74 6c 79 20 65 76 61 6c 75 61 74 69 6e 67 2c  ntly evaluating,
3070: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 6b 69  .**          ski
3080: 70 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74  p all subsequent
3090: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2c   SQL statements,
30a0: 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c   and return [SQL
30b0: 49 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a  ITE_ABORT]..**.*
30c0: 2a 20 7b 46 31 32 31 31 33 7d 20 54 68 65 20 5b  * {F12113} The [
30d0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20  sqlite3_exec()] 
30e0: 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20 70 61  routine shall pa
30f0: 73 73 20 69 74 73 20 34 74 68 20 70 61 72 61 6d  ss its 4th param
3100: 65 74 65 72 20 74 68 72 6f 75 67 68 0a 2a 2a 20  eter through.** 
3110: 20 20 20 20 20 20 20 20 20 61 73 20 74 68 65 20           as the 
3120: 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 6f 66  1st parameter of
3130: 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a   the callback..*
3140: 2a 0a 2a 2a 20 7b 46 31 32 31 31 36 7d 20 54 68  *.** {F12116} Th
3150: 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  e [sqlite3_exec(
3160: 29 5d 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20  )] routine sets 
3170: 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
3180: 72 20 6f 66 20 69 74 73 0a 2a 2a 20 20 20 20 20  r of its.**     
3190: 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 20 74 6f       callback to
31a0: 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   be the number o
31b0: 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65  f columns in the
31c0: 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 0a   current row of.
31d0: 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 73 75  **          resu
31e0: 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31 31  lt..**.** {F1211
31f0: 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  9} The [sqlite3_
3200: 65 78 65 63 28 29 5d 20 72 6f 75 74 69 6e 65 20  exec()] routine 
3210: 73 65 74 73 20 74 68 65 20 33 72 64 20 70 61 72  sets the 3rd par
3220: 61 6d 65 74 65 72 20 6f 66 20 69 74 73 20 0a 2a  ameter of its .*
3230: 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c 62  *          callb
3240: 61 63 6b 20 74 6f 20 62 65 20 61 6e 20 61 72 72  ack to be an arr
3250: 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74  ay of pointers t
3260: 6f 20 73 74 72 69 6e 67 73 20 68 6f 6c 64 69 6e  o strings holdin
3270: 67 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  g the.**        
3280: 20 20 76 61 6c 75 65 73 20 66 6f 72 20 65 61 63    values for eac
3290: 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20  h column in the 
32a0: 63 75 72 72 65 6e 74 20 72 65 73 75 6c 74 20 73  current result s
32b0: 65 74 20 72 6f 77 20 61 73 0a 2a 2a 20 20 20 20  et row as.**    
32c0: 20 20 20 20 20 20 6f 62 74 61 69 6e 65 64 20 66        obtained f
32d0: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  rom [sqlite3_col
32e0: 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a  umn_text()]..**.
32f0: 2a 2a 20 7b 46 31 32 31 32 32 7d 20 54 68 65 20  ** {F12122} The 
3300: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
3310: 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 74 68   routine sets th
3320: 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
3330: 6f 66 20 69 74 73 0a 2a 2a 20 20 20 20 20 20 20  of its.**       
3340: 20 20 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 62     callback to b
3350: 65 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f  e an array of po
3360: 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67  inters to string
3370: 73 20 68 6f 6c 64 69 6e 67 20 74 68 65 0a 2a 2a  s holding the.**
3380: 20 20 20 20 20 20 20 20 20 20 6e 61 6d 65 73 20            names 
3390: 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  of result column
33a0: 73 20 61 73 20 6f 62 74 61 69 6e 65 64 20 66 72  s as obtained fr
33b0: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  om [sqlite3_colu
33c0: 6d 6e 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a  mn_name()]..**.*
33d0: 2a 20 7b 46 31 32 31 32 35 7d 20 49 66 20 74 68  * {F12125} If th
33e0: 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
33f0: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  to [sqlite3_exec
3400: 28 29 5d 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e  ()] is NULL then
3410: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
3420: 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 6e 65  lite3_exec()] ne
3430: 76 65 72 20 69 6e 76 6f 6b 65 73 20 61 20 63 61  ver invokes a ca
3440: 6c 6c 62 61 63 6b 2e 20 20 41 6c 6c 20 71 75 65  llback.  All que
3450: 72 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  ry.**          r
3460: 65 73 75 6c 74 73 20 61 72 65 20 73 69 6c 65 6e  esults are silen
3470: 74 6c 79 20 64 69 73 63 61 72 64 65 64 2e 0a 2a  tly discarded..*
3480: 2a 0a 2a 2a 20 7b 46 31 32 31 33 31 7d 20 49 66  *.** {F12131} If
3490: 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
34a0: 20 77 68 69 6c 65 20 70 61 72 73 69 6e 67 20 6f   while parsing o
34b0: 72 20 65 76 61 6c 75 61 74 69 6e 67 20 61 6e 79  r evaluating any
34c0: 20 6f 66 20 74 68 65 20 53 51 4c 0a 2a 2a 20 20   of the SQL.**  
34d0: 20 20 20 20 20 20 20 20 68 61 6e 64 65 64 20 69          handed i
34e0: 6e 20 74 68 65 20 53 20 70 61 72 61 6d 65 74 65  n the S paramete
34f0: 72 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 65 78  r of [sqlite3_ex
3500: 65 63 28 44 2c 53 2c 43 2c 41 2c 45 29 5d 20 61  ec(D,S,C,A,E)] a
3510: 6e 64 20 69 66 0a 2a 2a 20 20 20 20 20 20 20 20  nd if.**        
3520: 20 20 74 68 65 20 45 20 70 61 72 61 6d 65 74 65    the E paramete
3530: 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74  r is not NULL, t
3540: 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  hen [sqlite3_exe
3550: 63 28 29 5d 20 73 68 61 6c 6c 20 73 74 6f 72 65  c()] shall store
3560: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20  .**          in 
3570: 2a 45 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74  *E an appropriat
3580: 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  e error message 
3590: 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d  written into mem
35a0: 6f 72 79 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20  ory obtained.** 
35b0: 20 20 20 20 20 20 20 20 20 66 72 6f 6d 20 5b 73           from [s
35c0: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
35d0: 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31 33 34 7d  ..**.** {F12134}
35e0: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 78   The [sqlite3_ex
35f0: 65 63 28 44 2c 53 2c 43 2c 41 2c 45 29 5d 20 72  ec(D,S,C,A,E)] r
3600: 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20 73 65 74  outine shall set
3610: 20 74 68 65 20 76 61 6c 75 65 20 6f 66 0a 2a 2a   the value of.**
3620: 20 20 20 20 20 20 20 20 20 20 2a 45 20 74 6f 20            *E to 
3630: 4e 55 4c 4c 20 69 66 20 45 20 69 73 20 6e 6f 74  NULL if E is not
3640: 20 4e 55 4c 4c 20 61 6e 64 20 74 68 65 72 65 20   NULL and there 
3650: 61 72 65 20 6e 6f 20 65 72 72 6f 72 73 2e 0a 2a  are no errors..*
3660: 2a 0a 2a 2a 20 7b 46 31 32 31 33 37 7d 20 54 68  *.** {F12137} Th
3670: 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  e [sqlite3_exec(
3680: 44 2c 53 2c 43 2c 41 2c 45 29 5d 20 66 75 6e 63  D,S,C,A,E)] func
3690: 74 69 6f 6e 20 73 68 61 6c 6c 20 73 65 74 20 74  tion shall set t
36a0: 68 65 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a  he error code.**
36b0: 20 20 20 20 20 20 20 20 20 20 61 6e 64 20 6d 65            and me
36c0: 73 73 61 67 65 20 61 63 63 65 73 73 69 62 6c 65  ssage accessible
36d0: 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 65 72   via [sqlite3_er
36e0: 72 63 6f 64 65 28 29 5d 2c 0a 2a 2a 20 20 20 20  rcode()],.**    
36f0: 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 65        [sqlite3_e
3700: 72 72 6d 73 67 28 29 5d 2c 20 61 6e 64 20 5b 73  rrmsg()], and [s
3710: 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
3720: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31 33  )]..**.** {F1213
3730: 38 7d 20 49 66 20 74 68 65 20 53 20 70 61 72 61  8} If the S para
3740: 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
3750: 33 5f 65 78 65 63 28 44 2c 53 2c 43 2c 41 2c 45  3_exec(D,S,C,A,E
3760: 29 5d 20 69 73 20 61 20 6e 75 6c 6c 20 6f 72 20  )] is a null or 
3770: 65 6d 70 74 79 0a 2a 2a 20 20 20 20 20 20 20 20  empty.**        
3780: 20 20 73 74 72 69 6e 67 20 6f 72 20 63 6f 6e 74    string or cont
3790: 61 69 6e 73 20 6e 6f 74 68 69 6e 67 20 6f 74 68  ains nothing oth
37a0: 65 72 20 74 68 61 6e 20 77 68 69 74 65 73 70 61  er than whitespa
37b0: 63 65 2c 20 63 6f 6d 6d 65 6e 74 73 2c 20 61 6e  ce, comments, an
37c0: 64 2f 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  d/or.**         
37d0: 20 73 65 6d 69 63 6f 6c 6f 6e 73 2c 20 74 68 65   semicolons, the
37e0: 6e 20 72 65 73 75 6c 74 73 20 6f 66 20 5b 73 71  n results of [sq
37f0: 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d  lite3_errcode()]
3800: 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  ,.**          [s
3810: 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
3820: 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65  , and [sqlite3_e
3830: 72 72 6d 73 67 31 36 28 29 5d 0a 2a 2a 20 20 20  rrmsg16()].**   
3840: 20 20 20 20 20 20 20 73 68 61 6c 6c 20 72 65 73         shall res
3850: 65 74 20 74 6f 20 69 6e 64 69 63 61 74 65 20 6e  et to indicate n
3860: 6f 20 65 72 72 6f 72 73 2e 0a 2a 2a 0a 2a 2a 20  o errors..**.** 
3870: 4c 49 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a  LIMITATIONS:.**.
3880: 2a 2a 20 7b 55 31 32 31 34 31 7d 20 54 68 65 20  ** {U12141} The 
3890: 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
38a0: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  to [sqlite3_exec
38b0: 28 29 5d 20 6d 75 73 74 20 62 65 20 61 6e 20 76  ()] must be an v
38c0: 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e 0a 2a 2a  alid and open.**
38d0: 20 20 20 20 20 20 20 20 20 20 5b 64 61 74 61 62            [datab
38e0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
38f0: 0a 2a 2a 0a 2a 2a 20 7b 55 31 32 31 34 32 7d 20  .**.** {U12142} 
3900: 54 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  The database con
3910: 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  nection must not
3920: 20 62 65 20 63 6c 6f 73 65 64 20 77 68 69 6c 65   be closed while
3930: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
3940: 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 69 73  lite3_exec()] is
3950: 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 0a 2a 2a   running..** .**
3960: 20 7b 55 31 32 31 34 33 7d 20 54 68 65 20 63 61   {U12143} The ca
3970: 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 73  lling function s
3980: 68 6f 75 6c 64 20 75 73 65 20 5b 73 71 6c 69 74  hould use [sqlit
3990: 65 33 5f 66 72 65 65 28 29 5d 20 74 6f 20 66 72  e3_free()] to fr
39a0: 65 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  ee.**          t
39b0: 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 2a  he memory that *
39c0: 65 72 72 6d 73 67 20 69 73 20 6c 65 66 74 20 70  errmsg is left p
39d0: 6f 69 6e 74 69 6e 67 20 61 74 20 6f 6e 63 65 20  ointing at once 
39e0: 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 20 20 20  the error.**    
39f0: 20 20 20 20 20 20 6d 65 73 73 61 67 65 20 69 73        message is
3a00: 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65   no longer neede
3a10: 64 2e 0a 2a 2a 0a 2a 2a 20 7b 55 31 32 31 34 35  d..**.** {U12145
3a20: 7d 20 54 68 65 20 53 51 4c 20 73 74 61 74 65 6d  } The SQL statem
3a30: 65 6e 74 20 74 65 78 74 20 69 6e 20 74 68 65 20  ent text in the 
3a40: 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  2nd parameter to
3a50: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
3a60: 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 75  ].**          mu
3a70: 73 74 20 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e  st remain unchan
3a80: 67 65 64 20 77 68 69 6c 65 20 5b 73 71 6c 69 74  ged while [sqlit
3a90: 65 33 5f 65 78 65 63 28 29 5d 20 69 73 20 72 75  e3_exec()] is ru
3aa0: 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71  nning..*/.int sq
3ab0: 6c 69 74 65 33 5f 65 78 65 63 28 0a 20 20 73 71  lite3_exec(.  sq
3ac0: 6c 69 74 65 33 2a 2c 20 20 20 20 20 20 20 20 20  lite3*,         
3ad0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3ae0: 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f           /* An o
3af0: 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  pen database */.
3b00: 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71    const char *sq
3b10: 6c 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  l,              
3b20: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
3b30: 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61  SQL to be evalua
3b40: 74 65 64 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 63  ted */.  int (*c
3b50: 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69  allback)(void*,i
3b60: 6e 74 2c 63 68 61 72 2a 2a 2c 63 68 61 72 2a 2a  nt,char**,char**
3b70: 29 2c 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20  ),  /* Callback 
3b80: 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f  function */.  vo
3b90: 69 64 20 2a 2c 20 20 20 20 20 20 20 20 20 20 20  id *,           
3ba0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3bb0: 20 20 20 20 20 20 20 20 20 2f 2a 20 31 73 74 20           /* 1st 
3bc0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c  argument to call
3bd0: 62 61 63 6b 20 2a 2f 0a 20 20 63 68 61 72 20 2a  back */.  char *
3be0: 2a 65 72 72 6d 73 67 20 20 20 20 20 20 20 20 20  *errmsg         
3bf0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3c00: 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73       /* Error ms
3c10: 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a  g written here *
3c20: 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.);../*.** CAPI
3c30: 33 52 45 46 3a 20 52 65 73 75 6c 74 20 43 6f 64  3REF: Result Cod
3c40: 65 73 20 7b 46 31 30 32 31 30 7d 0a 2a 2a 20 4b  es {F10210}.** K
3c50: 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f  EYWORDS: SQLITE_
3c60: 4f 4b 20 7b 65 72 72 6f 72 20 63 6f 64 65 7d 20  OK {error code} 
3c70: 7b 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a  {error codes}.**
3c80: 0a 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74 65 20  .** Many SQLite 
3c90: 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
3ca0: 20 61 6e 20 69 6e 74 65 67 65 72 20 72 65 73 75   an integer resu
3cb0: 6c 74 20 63 6f 64 65 20 66 72 6f 6d 20 74 68 65  lt code from the
3cc0: 20 73 65 74 20 73 68 6f 77 6e 0a 2a 2a 20 68 65   set shown.** he
3cd0: 72 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 69  re in order to i
3ce0: 6e 64 69 63 61 74 65 73 20 73 75 63 63 65 73 73  ndicates success
3cf0: 20 6f 72 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a   or failure..**.
3d00: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51  ** See also: [SQ
3d10: 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20  LITE_IOERR_READ 
3d20: 7c 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  | extended resul
3d30: 74 20 63 6f 64 65 73 5d 0a 2a 2f 0a 23 64 65 66  t codes].*/.#def
3d40: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20  ine SQLITE_OK   
3d50: 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 53          0   /* S
3d60: 75 63 63 65 73 73 66 75 6c 20 72 65 73 75 6c 74  uccessful result
3d70: 20 2a 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67   */./* beginning
3d80: 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20  -of-error-codes 
3d90: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
3da0: 45 5f 45 52 52 4f 52 20 20 20 20 20 20 20 20 31  E_ERROR        1
3db0: 20 20 20 2f 2a 20 53 51 4c 20 65 72 72 6f 72 20     /* SQL error 
3dc0: 6f 72 20 6d 69 73 73 69 6e 67 20 64 61 74 61 62  or missing datab
3dd0: 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ase */.#define S
3de0: 51 4c 49 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20  QLITE_INTERNAL  
3df0: 20 20 20 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e     2   /* Intern
3e00: 61 6c 20 6c 6f 67 69 63 20 65 72 72 6f 72 20 69  al logic error i
3e10: 6e 20 53 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66  n SQLite */.#def
3e20: 69 6e 65 20 53 51 4c 49 54 45 5f 50 45 52 4d 20  ine SQLITE_PERM 
3e30: 20 20 20 20 20 20 20 20 33 20 20 20 2f 2a 20 41          3   /* A
3e40: 63 63 65 73 73 20 70 65 72 6d 69 73 73 69 6f 6e  ccess permission
3e50: 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69   denied */.#defi
3e60: 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20  ne SQLITE_ABORT 
3e70: 20 20 20 20 20 20 20 34 20 20 20 2f 2a 20 43 61         4   /* Ca
3e80: 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72  llback routine r
3e90: 65 71 75 65 73 74 65 64 20 61 6e 20 61 62 6f 72  equested an abor
3ea0: 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
3eb0: 49 54 45 5f 42 55 53 59 20 20 20 20 20 20 20 20  ITE_BUSY        
3ec0: 20 35 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61   5   /* The data
3ed0: 62 61 73 65 20 66 69 6c 65 20 69 73 20 6c 6f 63  base file is loc
3ee0: 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ked */.#define S
3ef0: 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20  QLITE_LOCKED    
3f00: 20 20 20 36 20 20 20 2f 2a 20 41 20 74 61 62 6c     6   /* A tabl
3f10: 65 20 69 6e 20 74 68 65 20 64 61 74 61 62 61 73  e in the databas
3f20: 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23  e is locked */.#
3f30: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
3f40: 4d 45 4d 20 20 20 20 20 20 20 20 37 20 20 20 2f  MEM        7   /
3f50: 2a 20 41 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69  * A malloc() fai
3f60: 6c 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  led */.#define S
3f70: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20  QLITE_READONLY  
3f80: 20 20 20 38 20 20 20 2f 2a 20 41 74 74 65 6d 70     8   /* Attemp
3f90: 74 20 74 6f 20 77 72 69 74 65 20 61 20 72 65 61  t to write a rea
3fa0: 64 6f 6e 6c 79 20 64 61 74 61 62 61 73 65 20 2a  donly database *
3fb0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3fc0: 5f 49 4e 54 45 52 52 55 50 54 20 20 20 20 39 20  _INTERRUPT    9 
3fd0: 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74    /* Operation t
3fe0: 65 72 6d 69 6e 61 74 65 64 20 62 79 20 73 71 6c  erminated by sql
3ff0: 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
4000: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4010: 45 5f 49 4f 45 52 52 20 20 20 20 20 20 20 31 30  E_IOERR       10
4020: 20 20 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20     /* Some kind 
4030: 6f 66 20 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f  of disk I/O erro
4040: 72 20 6f 63 63 75 72 72 65 64 20 2a 2f 0a 23 64  r occurred */.#d
4050: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52  efine SQLITE_COR
4060: 52 55 50 54 20 20 20 20 20 31 31 20 20 20 2f 2a  RUPT     11   /*
4070: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 64 69   The database di
4080: 73 6b 20 69 6d 61 67 65 20 69 73 20 6d 61 6c 66  sk image is malf
4090: 6f 72 6d 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  ormed */.#define
40a0: 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44   SQLITE_NOTFOUND
40b0: 20 20 20 20 31 32 20 20 20 2f 2a 20 4e 4f 54 20      12   /* NOT 
40c0: 55 53 45 44 2e 20 54 61 62 6c 65 20 6f 72 20 72  USED. Table or r
40d0: 65 63 6f 72 64 20 6e 6f 74 20 66 6f 75 6e 64 20  ecord not found 
40e0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
40f0: 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 31 33  E_FULL        13
4100: 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20     /* Insertion 
4110: 66 61 69 6c 65 64 20 62 65 63 61 75 73 65 20 64  failed because d
4120: 61 74 61 62 61 73 65 20 69 73 20 66 75 6c 6c 20  atabase is full 
4130: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4140: 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 34  E_CANTOPEN    14
4150: 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20     /* Unable to 
4160: 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  open the databas
4170: 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e  e file */.#defin
4180: 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f  e SQLITE_PROTOCO
4190: 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 4e 4f 54  L    15   /* NOT
41a0: 20 55 53 45 44 2e 20 44 61 74 61 62 61 73 65 20   USED. Database 
41b0: 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65 72  lock protocol er
41c0: 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ror */.#define S
41d0: 51 4c 49 54 45 5f 45 4d 50 54 59 20 20 20 20 20  QLITE_EMPTY     
41e0: 20 20 31 36 20 20 20 2f 2a 20 44 61 74 61 62 61    16   /* Databa
41f0: 73 65 20 69 73 20 65 6d 70 74 79 20 2a 2f 0a 23  se is empty */.#
4200: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 43  define SQLITE_SC
4210: 48 45 4d 41 20 20 20 20 20 20 31 37 20 20 20 2f  HEMA      17   /
4220: 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20 73  * The database s
4230: 63 68 65 6d 61 20 63 68 61 6e 67 65 64 20 2a 2f  chema changed */
4240: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4250: 54 4f 4f 42 49 47 20 20 20 20 20 20 31 38 20 20  TOOBIG      18  
4260: 20 2f 2a 20 53 74 72 69 6e 67 20 6f 72 20 42 4c   /* String or BL
4270: 4f 42 20 65 78 63 65 65 64 73 20 73 69 7a 65 20  OB exceeds size 
4280: 6c 69 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e 65  limit */.#define
4290: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
42a0: 4e 54 20 20 31 39 20 20 20 2f 2a 20 41 62 6f 72  NT  19   /* Abor
42b0: 74 20 64 75 65 20 74 6f 20 63 6f 6e 73 74 72 61  t due to constra
42c0: 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f  int violation */
42d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
42e0: 4d 49 53 4d 41 54 43 48 20 20 20 20 32 30 20 20  MISMATCH    20  
42f0: 20 2f 2a 20 44 61 74 61 20 74 79 70 65 20 6d 69   /* Data type mi
4300: 73 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66 69 6e  smatch */.#defin
4310: 65 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20  e SQLITE_MISUSE 
4320: 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4c 69 62       21   /* Lib
4330: 72 61 72 79 20 75 73 65 64 20 69 6e 63 6f 72 72  rary used incorr
4340: 65 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65  ectly */.#define
4350: 20 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20 20   SQLITE_NOLFS   
4360: 20 20 20 20 32 32 20 20 20 2f 2a 20 55 73 65 73      22   /* Uses
4370: 20 4f 53 20 66 65 61 74 75 72 65 73 20 6e 6f 74   OS features not
4380: 20 73 75 70 70 6f 72 74 65 64 20 6f 6e 20 68 6f   supported on ho
4390: 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  st */.#define SQ
43a0: 4c 49 54 45 5f 41 55 54 48 20 20 20 20 20 20 20  LITE_AUTH       
43b0: 20 32 33 20 20 20 2f 2a 20 41 75 74 68 6f 72 69   23   /* Authori
43c0: 7a 61 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f  zation denied */
43d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
43e0: 46 4f 52 4d 41 54 20 20 20 20 20 20 32 34 20 20  FORMAT      24  
43f0: 20 2f 2a 20 41 75 78 69 6c 69 61 72 79 20 64 61   /* Auxiliary da
4400: 74 61 62 61 73 65 20 66 6f 72 6d 61 74 20 65 72  tabase format er
4410: 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ror */.#define S
4420: 51 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20 20  QLITE_RANGE     
4430: 20 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70 61    25   /* 2nd pa
4440: 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
4450: 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20 72  e3_bind out of r
4460: 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ange */.#define 
4470: 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20 20  SQLITE_NOTADB   
4480: 20 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65 20     26   /* File 
4490: 6f 70 65 6e 65 64 20 74 68 61 74 20 69 73 20 6e  opened that is n
44a0: 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66 69  ot a database fi
44b0: 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  le */.#define SQ
44c0: 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20 20  LITE_ROW        
44d0: 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65 33   100  /* sqlite3
44e0: 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f 74  _step() has anot
44f0: 68 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a 2f  her row ready */
4500: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4510: 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31 20  DONE        101 
4520: 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70   /* sqlite3_step
4530: 28 29 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  () has finished 
4540: 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20  executing */./* 
4550: 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64  end-of-error-cod
4560: 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  es */../*.** CAP
4570: 49 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64 20  I3REF: Extended 
4580: 52 65 73 75 6c 74 20 43 6f 64 65 73 20 7b 46 31  Result Codes {F1
4590: 30 32 32 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  0220}.** KEYWORD
45a0: 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 65 72 72  S: {extended err
45b0: 6f 72 20 63 6f 64 65 7d 20 7b 65 78 74 65 6e 64  or code} {extend
45c0: 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a  ed error codes}.
45d0: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78  ** KEYWORDS: {ex
45e0: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
45f0: 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74  des}.**.** In it
4600: 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67  s default config
4610: 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20  uration, SQLite 
4620: 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72 65 74  API routines ret
4630: 75 72 6e 20 6f 6e 65 20 6f 66 20 32 36 20 69 6e  urn one of 26 in
4640: 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  teger.** [SQLITE
4650: 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64  _OK | result cod
4660: 65 73 5d 2e 20 20 48 6f 77 65 76 65 72 2c 20 65  es].  However, e
4670: 78 70 65 72 69 65 6e 63 65 20 68 61 73 20 73 68  xperience has sh
4680: 6f 77 6e 20 74 68 61 74 0a 2a 2a 20 6d 61 6e 79  own that.** many
4690: 20 6f 66 20 74 68 65 73 65 20 72 65 73 75 6c 74   of these result
46a0: 20 63 6f 64 65 73 20 61 72 65 20 74 6f 6f 20 63   codes are too c
46b0: 6f 75 72 73 65 2d 67 72 61 69 6e 65 64 2e 20 20  ourse-grained.  
46c0: 54 68 65 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76  They do not prov
46d0: 69 64 65 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69  ide as.** much i
46e0: 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74  nformation about
46f0: 20 70 72 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f   problems as pro
4700: 67 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c  grammers might l
4710: 69 6b 65 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f  ike.  In an effo
4720: 72 74 20 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73  rt to.** address
4730: 20 74 68 69 73 2c 20 6e 65 77 65 72 20 76 65 72   this, newer ver
4740: 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
4750: 28 76 65 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61  (version 3.3.8 a
4760: 6e 64 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 64  nd later) includ
4770: 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f 72  e.** support for
4780: 20 61 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 75   additional resu
4790: 6c 74 20 63 6f 64 65 73 20 74 68 61 74 20 70 72  lt codes that pr
47a0: 6f 76 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69  ovide more detai
47b0: 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a  led information.
47c0: 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f 72 73 2e  ** about errors.
47d0: 20 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 65   The extended re
47e0: 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 65  sult codes are e
47f0: 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c  nabled or disabl
4800: 65 64 0a 2a 2a 20 66 6f 72 20 65 61 63 68 20 64  ed.** for each d
4810: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
4820: 6f 6e 20 75 73 69 6e 67 20 74 68 65 20 5b 73 71  on using the [sq
4830: 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72  lite3_extended_r
4840: 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 5d 0a 2a  esult_codes()].*
4850: 2a 20 41 50 49 2e 0a 2a 2a 20 0a 2a 2a 20 53 6f  * API..** .** So
4860: 6d 65 20 6f 66 20 74 68 65 20 61 76 61 69 6c 61  me of the availa
4870: 62 6c 65 20 65 78 74 65 6e 64 65 64 20 72 65 73  ble extended res
4880: 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 6c 69  ult codes are li
4890: 73 74 65 64 20 68 65 72 65 2e 0a 2a 2a 20 4f 6e  sted here..** On
48a0: 65 20 6d 61 79 20 65 78 70 65 63 74 20 74 68 65  e may expect the
48b0: 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 65 6e   number of exten
48c0: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
48d0: 20 77 69 6c 6c 20 62 65 20 65 78 70 61 6e 64 0a   will be expand.
48e0: 2a 2a 20 6f 76 65 72 20 74 69 6d 65 2e 20 20 53  ** over time.  S
48f0: 6f 66 74 77 61 72 65 20 74 68 61 74 20 75 73 65  oftware that use
4900: 73 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  s extended resul
4910: 74 20 63 6f 64 65 73 20 73 68 6f 75 6c 64 20 65  t codes should e
4920: 78 70 65 63 74 0a 2a 2a 20 74 6f 20 73 65 65 20  xpect.** to see 
4930: 6e 65 77 20 72 65 73 75 6c 74 20 63 6f 64 65 73  new result codes
4940: 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
4950: 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ses of SQLite..*
4960: 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f  *.** The SQLITE_
4970: 4f 4b 20 72 65 73 75 6c 74 20 63 6f 64 65 20 77  OK result code w
4980: 69 6c 6c 20 6e 65 76 65 72 20 62 65 20 65 78 74  ill never be ext
4990: 65 6e 64 65 64 2e 20 20 49 74 20 77 69 6c 6c 20  ended.  It will 
49a0: 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20 65 78 61  always.** be exa
49b0: 63 74 6c 79 20 7a 65 72 6f 2e 0a 2a 2a 20 0a 2a  ctly zero..** .*
49c0: 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
49d0: 0a 2a 2a 20 7b 46 31 30 32 32 33 7d 20 54 68 65  .** {F10223} The
49e0: 20 73 79 6d 62 6f 6c 69 63 20 6e 61 6d 65 20 66   symbolic name f
49f0: 6f 72 20 61 6e 20 65 78 74 65 6e 64 65 64 20 72  or an extended r
4a00: 65 73 75 6c 74 20 63 6f 64 65 20 61 6c 77 61 79  esult code alway
4a10: 73 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 20 20  s contains.**   
4a20: 20 20 20 20 20 20 20 61 20 72 65 6c 61 74 65 64         a related
4a30: 20 70 72 69 6d 61 72 79 20 72 65 73 75 6c 74 20   primary result 
4a40: 63 6f 64 65 20 61 73 20 61 20 70 72 65 66 69 78  code as a prefix
4a50: 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 32 32 34 7d  ..**.** {F10224}
4a60: 20 50 72 69 6d 61 72 79 20 72 65 73 75 6c 74 20   Primary result 
4a70: 63 6f 64 65 20 6e 61 6d 65 73 20 63 6f 6e 74 61  code names conta
4a80: 69 6e 20 61 20 73 69 6e 67 6c 65 20 22 5f 22 20  in a single "_" 
4a90: 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 0a 2a 2a  character..**.**
4aa0: 20 7b 46 31 30 32 32 35 7d 20 45 78 74 65 6e 64   {F10225} Extend
4ab0: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 20 6e  ed result code n
4ac0: 61 6d 65 73 20 63 6f 6e 74 61 69 6e 20 74 77 6f  ames contain two
4ad0: 20 6f 72 20 6d 6f 72 65 20 22 5f 22 20 63 68 61   or more "_" cha
4ae0: 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b  racters..**.** {
4af0: 46 31 30 32 32 36 7d 20 54 68 65 20 6e 75 6d 65  F10226} The nume
4b00: 72 69 63 20 76 61 6c 75 65 20 6f 66 20 61 6e 20  ric value of an 
4b10: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
4b20: 63 6f 64 65 20 63 6f 6e 74 61 69 6e 73 20 74 68  code contains th
4b30: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 75  e.**          nu
4b40: 6d 65 72 69 63 20 76 61 6c 75 65 20 6f 66 20 69  meric value of i
4b50: 74 73 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  ts corresponding
4b60: 20 70 72 69 6d 61 72 79 20 72 65 73 75 6c 74 20   primary result 
4b70: 63 6f 64 65 20 69 6e 0a 2a 2a 20 20 20 20 20 20  code in.**      
4b80: 20 20 20 20 69 74 73 20 6c 65 61 73 74 20 73 69      its least si
4b90: 67 6e 69 66 69 63 61 6e 74 20 38 20 62 69 74 73  gnificant 8 bits
4ba0: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
4bb0: 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20  ITE_IOERR_READ  
4bc0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
4bd0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c  ITE_IOERR | (1<<
4be0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4bf0: 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52  TE_IOERR_SHORT_R
4c00: 45 41 44 20 20 20 20 20 20 20 20 28 53 51 4c 49  EAD        (SQLI
4c10: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38  TE_IOERR | (2<<8
4c20: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
4c30: 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20  E_IOERR_WRITE   
4c40: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
4c50: 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29  E_IOERR | (3<<8)
4c60: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
4c70: 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20  _IOERR_FSYNC    
4c80: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
4c90: 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29  _IOERR | (4<<8))
4ca0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4cb0: 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20  IOERR_DIR_FSYNC 
4cc0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
4cd0: 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a  IOERR | (5<<8)).
4ce0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4cf0: 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20  OERR_TRUNCATE   
4d00: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
4d10: 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23  OERR | (6<<8)).#
4d20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
4d30: 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 20 20  ERR_FSTAT       
4d40: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
4d50: 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64  ERR | (7<<8)).#d
4d60: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4d70: 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20  RR_UNLOCK       
4d80: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4d90: 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65  RR | (8<<8)).#de
4da0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4db0: 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20  R_RDLOCK        
4dc0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4dd0: 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66  R | (9<<8)).#def
4de0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4df0: 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20  _DELETE         
4e00: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
4e10: 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66   | (10<<8)).#def
4e20: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4e30: 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20  _BLOCKED        
4e40: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
4e50: 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66   | (11<<8)).#def
4e60: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4e70: 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20  _NOMEM          
4e80: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
4e90: 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66   | (12<<8)).#def
4ea0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4eb0: 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 20 20  _ACCESS         
4ec0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
4ed0: 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66   | (13<<8)).#def
4ee0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4ef0: 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f  _CHECKRESERVEDLO
4f00: 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52  CK (SQLITE_IOERR
4f10: 20 7c 20 28 31 34 3c 3c 38 29 29 0a 0a 2f 2a 0a   | (14<<8))../*.
4f20: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61  ** CAPI3REF: Fla
4f30: 67 73 20 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e  gs For File Open
4f40: 20 4f 70 65 72 61 74 69 6f 6e 73 20 7b 46 31 30   Operations {F10
4f50: 32 33 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  230}.**.** These
4f60: 20 62 69 74 20 76 61 6c 75 65 73 20 61 72 65 20   bit values are 
4f70: 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65  intended for use
4f80: 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20 70   in the.** 3rd p
4f90: 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
4fa0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
4fb0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61 6e  ()] interface an
4fc0: 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74 68 20  d.** in the 4th 
4fd0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
4fe0: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6f 66   xOpen method of
4ff0: 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
5000: 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f  _vfs] object..*/
5010: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5020: 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20  OPEN_READONLY   
5030: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31        0x00000001
5040: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5050: 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 20  OPEN_READWRITE  
5060: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32        0x00000002
5070: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5080: 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20 20 20  OPEN_CREATE     
5090: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34        0x00000004
50a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
50b0: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
50c0: 53 45 20 20 20 20 30 78 30 30 30 30 30 30 30 38  SE    0x00000008
50d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
50e0: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 20  OPEN_EXCLUSIVE  
50f0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30        0x00000010
5100: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5110: 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20  OPEN_MAIN_DB    
5120: 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30        0x00000100
5130: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5140: 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20  OPEN_TEMP_DB    
5150: 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30        0x00000200
5160: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5170: 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44  OPEN_TRANSIENT_D
5180: 42 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30  B     0x00000400
5190: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
51a0: 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41  OPEN_MAIN_JOURNA
51b0: 4c 20 20 20 20 20 30 78 30 30 30 30 30 38 30 30  L     0x00000800
51c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
51d0: 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41  OPEN_TEMP_JOURNA
51e0: 4c 20 20 20 20 20 30 78 30 30 30 30 31 30 30 30  L     0x00001000
51f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5200: 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20  OPEN_SUBJOURNAL 
5210: 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30 30        0x00002000
5220: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5230: 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52  OPEN_MASTER_JOUR
5240: 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30 30 30  NAL   0x00004000
5250: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
5260: 3a 20 44 65 76 69 63 65 20 43 68 61 72 61 63 74  : Device Charact
5270: 65 72 69 73 74 69 63 73 20 7b 46 31 30 32 34 30  eristics {F10240
5280: 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76  }.**.** The xDev
5290: 69 63 65 43 61 70 61 62 69 6c 69 74 69 65 73 20  iceCapabilities 
52a0: 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73  method of the [s
52b0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
52c0: 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74  s].** object ret
52d0: 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20  urns an integer 
52e0: 77 68 69 63 68 20 69 73 20 61 20 76 65 63 74 6f  which is a vecto
52f0: 72 20 6f 66 20 74 68 65 20 74 68 65 73 65 0a 2a  r of the these.*
5300: 2a 20 62 69 74 20 76 61 6c 75 65 73 20 65 78 70  * bit values exp
5310: 72 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72  ressing I/O char
5320: 61 63 74 65 72 69 73 74 69 63 73 20 6f 66 20 74  acteristics of t
5330: 68 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a  he mass storage.
5340: 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 68  ** device that h
5350: 6f 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74 68  olds the file th
5360: 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  at the [sqlite3_
5370: 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72  io_methods].** r
5380: 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20  efers to..**.** 
5390: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
53a0: 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79  _ATOMIC property
53b0: 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20   means that all 
53c0: 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79  writes of.** any
53d0: 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63   size are atomic
53e0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
53f0: 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61  CAP_ATOMICnnn va
5400: 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61  lues.** mean tha
5410: 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63  t writes of bloc
5420: 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20  ks that are nnn 
5430: 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e  bytes in size an
5440: 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64  d.** are aligned
5450: 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77   to an address w
5460: 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67  hich is an integ
5470: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a  er multiple of.*
5480: 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63  * nnn are atomic
5490: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
54a0: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
54b0: 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74  value means.** t
54c0: 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73  hat when data is
54d0: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66   appended to a f
54e0: 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73  ile, the data is
54f0: 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72   appended.** fir
5500: 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65  st then the size
5510: 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   of the file is 
5520: 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20  extended, never 
5530: 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79  the other.** way
5540: 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51   around.  The SQ
5550: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
5560: 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d  NTIAL property m
5570: 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66  eans that.** inf
5580: 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74  ormation is writ
5590: 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74  ten to disk in t
55a0: 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73  he same order as
55b0: 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72   calls.** to xWr
55c0: 69 74 65 28 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e  ite()..*/.#defin
55d0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
55e0: 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20 20 30  TOMIC          0
55f0: 78 30 30 30 30 30 30 30 31 0a 23 64 65 66 69 6e  x00000001.#defin
5600: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
5610: 54 4f 4d 49 43 35 31 32 20 20 20 20 20 20 20 30  TOMIC512       0
5620: 78 30 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e  x00000002.#defin
5630: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
5640: 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20 30  TOMIC1K        0
5650: 78 30 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e  x00000004.#defin
5660: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
5670: 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 20 20 30  TOMIC2K        0
5680: 78 30 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e  x00000008.#defin
5690: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
56a0: 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 20 30  TOMIC4K        0
56b0: 78 30 30 30 30 30 30 31 30 0a 23 64 65 66 69 6e  x00000010.#defin
56c0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
56d0: 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20 30  TOMIC8K        0
56e0: 78 30 30 30 30 30 30 32 30 0a 23 64 65 66 69 6e  x00000020.#defin
56f0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
5700: 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 20 20 30  TOMIC16K       0
5710: 78 30 30 30 30 30 30 34 30 0a 23 64 65 66 69 6e  x00000040.#defin
5720: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
5730: 54 4f 4d 49 43 33 32 4b 20 20 20 20 20 20 20 30  TOMIC32K       0
5740: 78 30 30 30 30 30 30 38 30 0a 23 64 65 66 69 6e  x00000080.#defin
5750: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
5760: 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 20 20 30  TOMIC64K       0
5770: 78 30 30 30 30 30 31 30 30 0a 23 64 65 66 69 6e  x00000100.#defin
5780: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
5790: 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20 30  AFE_APPEND     0
57a0: 78 30 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e  x00000200.#defin
57b0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
57c0: 45 51 55 45 4e 54 49 41 4c 20 20 20 20 20 20 30  EQUENTIAL      0
57d0: 78 30 30 30 30 30 34 30 30 0a 0a 2f 2a 0a 2a 2a  x00000400../*.**
57e0: 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20   CAPI3REF: File 
57f0: 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 20 7b  Locking Levels {
5800: 46 31 30 32 35 30 7d 0a 2a 2a 0a 2a 2a 20 53 51  F10250}.**.** SQ
5810: 4c 69 74 65 20 75 73 65 73 20 6f 6e 65 20 6f 66  Lite uses one of
5820: 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76   these integer v
5830: 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63  alues as the sec
5840: 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  ond.** argument 
5850: 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b 65  to calls it make
5860: 73 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28 29  s to the xLock()
5870: 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 6d   and xUnlock() m
5880: 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e 20  ethods.** of an 
5890: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
58a0: 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a  ods] object..*/.
58b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
58c0: 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20 20  OCK_NONE        
58d0: 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    0.#define SQLI
58e0: 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20 20  TE_LOCK_SHARED  
58f0: 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
5900: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45  SQLITE_LOCK_RESE
5910: 52 56 45 44 20 20 20 20 20 20 32 0a 23 64 65 66  RVED      2.#def
5920: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
5930: 50 45 4e 44 49 4e 47 20 20 20 20 20 20 20 33 0a  PENDING       3.
5940: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
5950: 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 20 20  OCK_EXCLUSIVE   
5960: 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33    4../*.** CAPI3
5970: 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a 61  REF: Synchroniza
5980: 74 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 73 20  tion Type Flags 
5990: 7b 46 31 30 32 36 30 7d 0a 2a 2a 0a 2a 2a 20 57  {F10260}.**.** W
59a0: 68 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b  hen SQLite invok
59b0: 65 73 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d  es the xSync() m
59c0: 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b  ethod of an.** [
59d0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
59e0: 64 73 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73  ds] object it us
59f0: 65 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  es a combination
5a00: 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74   of.** these int
5a10: 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74  eger values as t
5a20: 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
5a30: 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74  nt..**.** When t
5a40: 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44  he SQLITE_SYNC_D
5a50: 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20  ATAONLY flag is 
5a60: 75 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74  used, it means t
5a70: 68 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20  hat the.** sync 
5a80: 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e  operation only n
5a90: 65 65 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61  eeds to flush da
5aa0: 74 61 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61  ta to mass stora
5ab0: 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e  ge.  Inode.** in
5ac0: 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e  formation need n
5ad0: 6f 74 20 62 65 20 66 6c 75 73 68 65 64 2e 20 54  ot be flushed. T
5ae0: 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  he SQLITE_SYNC_N
5af0: 4f 52 4d 41 4c 20 66 6c 61 67 20 6d 65 61 6e 73  ORMAL flag means
5b00: 20 0a 2a 2a 20 74 6f 20 75 73 65 20 6e 6f 72 6d   .** to use norm
5b10: 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d 61 6e  al fsync() seman
5b20: 74 69 63 73 2e 20 54 68 65 20 53 51 4c 49 54 45  tics. The SQLITE
5b30: 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 20  _SYNC_FULL flag 
5b40: 6d 65 61 6e 73 20 0a 2a 2a 20 74 6f 20 75 73 65  means .** to use
5b50: 20 4d 61 63 20 4f 53 2d 58 20 73 74 79 6c 65 20   Mac OS-X style 
5b60: 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64  fullsync instead
5b70: 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2f 0a   of fsync()..*/.
5b80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
5b90: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20  YNC_NORMAL      
5ba0: 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e    0x00002.#defin
5bb0: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  e SQLITE_SYNC_FU
5bc0: 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 30  LL          0x00
5bd0: 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  003.#define SQLI
5be0: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
5bf0: 20 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a 0a        0x00010...
5c00: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
5c10: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65  OS Interface Ope
5c20: 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65 20 7b 46  n File Handle {F
5c30: 31 31 31 31 30 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20  11110}.**.** An 
5c40: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
5c50: 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73  bject represents
5c60: 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 69 6e   an open file in
5c70: 20 74 68 65 20 4f 53 0a 2a 2a 20 69 6e 74 65 72   the OS.** inter
5c80: 66 61 63 65 20 6c 61 79 65 72 2e 20 20 49 6e 64  face layer.  Ind
5c90: 69 76 69 64 75 61 6c 20 4f 53 20 69 6e 74 65 72  ividual OS inter
5ca0: 66 61 63 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  face implementat
5cb0: 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e  ions will.** wan
5cc0: 74 20 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68  t to subclass th
5cd0: 69 73 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70  is object by app
5ce0: 65 6e 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61  ending additiona
5cf0: 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20  l fields.** for 
5d00: 74 68 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20  their own use.  
5d10: 54 68 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74  The pMethods ent
5d20: 72 79 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ry is a pointer 
5d30: 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65  to an.** [sqlite
5d40: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
5d50: 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65  ject that define
5d60: 73 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65  s methods for pe
5d70: 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20  rforming.** I/O 
5d80: 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68  operations on th
5d90: 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a  e open file..*/.
5da0: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
5db0: 71 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69  qlite3_file sqli
5dc0: 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74  te3_file;.struct
5dd0: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a   sqlite3_file {.
5de0: 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73    const struct s
5df0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
5e00: 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a  s *pMethods;  /*
5e10: 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20   Methods for an 
5e20: 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a  open file */.};.
5e30: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
5e40: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 46 69   OS Interface Fi
5e50: 6c 65 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f  le Virtual Metho
5e60: 64 73 20 4f 62 6a 65 63 74 20 7b 46 31 31 31 32  ds Object {F1112
5e70: 30 7d 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66  0}.**.** Every f
5e80: 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74 68  ile opened by th
5e90: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  e [sqlite3_vfs] 
5ea0: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 63 6f 6e  xOpen method con
5eb0: 74 61 69 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  tains a pointer 
5ec0: 74 6f 0a 2a 2a 20 61 6e 20 69 6e 73 74 61 6e 63  to.** an instanc
5ed0: 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
5ee0: 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 64  .  This object d
5ef0: 65 66 69 6e 65 73 20 74 68 65 0a 2a 2a 20 6d 65  efines the.** me
5f00: 74 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65  thods used to pe
5f10: 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70  rform various op
5f20: 65 72 61 74 69 6f 6e 73 20 61 67 61 69 6e 73 74  erations against
5f30: 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a   the open file..
5f40: 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20  **.** The flags 
5f50: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 53 79 6e  argument to xSyn
5f60: 63 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66 20  c may be one of 
5f70: 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52  [SQLITE_SYNC_NOR
5f80: 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49  MAL] or.** [SQLI
5f90: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20  TE_SYNC_FULL].  
5fa0: 54 68 65 20 66 69 72 73 74 20 63 68 6f 69 63 65  The first choice
5fb0: 20 69 73 20 74 68 65 20 6e 6f 72 6d 61 6c 20 66   is the normal f
5fc0: 73 79 6e 63 28 29 2e 0a 2a 20 20 54 68 65 20 73  sync()..*  The s
5fd0: 65 63 6f 6e 64 20 63 68 6f 69 63 65 20 69 73 20  econd choice is 
5fe0: 61 6e 0a 2a 2a 20 4f 53 2d 58 20 73 74 79 6c 65  an.** OS-X style
5ff0: 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54 68 65 20   fullsync.  The 
6000: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41  SQLITE_SYNC_DATA
6010: 20 66 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65   flag may be ORe
6020: 64 20 69 6e 20 74 6f 0a 2a 2a 20 69 6e 64 69 63  d in to.** indic
6030: 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74 68  ate that only th
6040: 65 20 64 61 74 61 20 6f 66 20 74 68 65 20 66 69  e data of the fi
6050: 6c 65 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69  le and not its i
6060: 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65  node needs to be
6070: 0a 2a 2a 20 73 79 6e 63 65 64 2e 0a 2a 2a 20 0a  .** synced..** .
6080: 2a 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20 76  ** The integer v
6090: 61 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29  alues to xLock()
60a0: 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61   and xUnlock() a
60b0: 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c  re one of.** <ul
60c0: 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  >.** <li> [SQLIT
60d0: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a  E_LOCK_NONE],.**
60e0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
60f0: 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c  CK_SHARED],.** <
6100: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
6110: 5f 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c  _RESERVED],.** <
6120: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
6130: 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a  _PENDING], or.**
6140: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
6150: 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a  CK_EXCLUSIVE]..*
6160: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b  * </ul>.** xLock
6170: 28 29 20 69 6e 63 72 65 61 73 65 73 20 74 68 65  () increases the
6180: 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29   lock. xUnlock()
6190: 20 64 65 63 72 65 61 73 65 73 20 74 68 65 20 6c   decreases the l
61a0: 6f 63 6b 2e 20 20 0a 2a 2a 20 54 68 65 20 78 43  ock.  .** The xC
61b0: 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b  heckReservedLock
61c0: 28 29 20 6d 65 74 68 6f 64 20 6c 6f 6f 6b 73 0a  () method looks.
61d0: 2a 2a 20 74 6f 20 73 65 65 20 69 66 20 61 6e 79  ** to see if any
61e0: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
61f0: 74 69 6f 6e 2c 20 65 69 74 68 65 72 20 69 6e 20  tion, either in 
6200: 74 68 69 73 0a 2a 2a 20 70 72 6f 63 65 73 73 20  this.** process 
6210: 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65 72  or in some other
6220: 20 70 72 6f 63 65 73 73 2c 20 69 73 20 68 6f 6c   process, is hol
6230: 64 69 6e 67 20 61 6e 20 52 45 53 45 52 56 45 44  ding an RESERVED
6240: 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72  ,.** PENDING, or
6250: 20 45 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20   EXCLUSIVE lock 
6260: 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 49 74  on the file.  It
6270: 20 72 65 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a   returns true.**
6280: 20 69 66 20 73 75 63 68 20 61 20 6c 6f 63 6b 20   if such a lock 
6290: 65 78 69 73 74 73 20 61 6e 64 20 66 61 6c 73 65  exists and false
62a0: 20 69 66 20 6e 6f 74 2e 0a 2a 2a 20 0a 2a 2a 20   if not..** .** 
62b0: 54 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  The xFileControl
62c0: 28 29 20 6d 65 74 68 6f 64 20 69 73 20 61 20 67  () method is a g
62d0: 65 6e 65 72 69 63 20 69 6e 74 65 72 66 61 63 65  eneric interface
62e0: 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 63 75 73   that allows cus
62f0: 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d 70 6c 65  tom.** VFS imple
6300: 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f 20 64 69  mentations to di
6310: 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f 6c 20 61  rectly control a
6320: 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75 73 69 6e  n open file usin
6330: 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  g the.** [sqlite
6340: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
6350: 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68  ] interface.  Th
6360: 65 20 73 65 63 6f 6e 64 20 22 6f 70 22 20 61 72  e second "op" ar
6370: 67 75 6d 65 6e 74 0a 2a 2a 20 69 73 20 61 6e 20  gument.** is an 
6380: 69 6e 74 65 67 65 72 20 6f 70 63 6f 64 65 2e 20  integer opcode. 
6390: 20 20 54 68 65 20 74 68 69 72 64 0a 2a 2a 20 61    The third.** a
63a0: 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65 6e  rgument is a gen
63b0: 65 72 69 63 20 70 6f 69 6e 74 65 72 20 77 68 69  eric pointer whi
63c0: 63 68 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74  ch is intended t
63d0: 6f 20 62 65 20 61 20 70 6f 69 6e 74 65 72 0a 2a  o be a pointer.*
63e0: 2a 20 74 6f 20 61 20 73 74 72 75 63 74 75 72 65  * to a structure
63f0: 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 69   that may contai
6400: 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 73  n arguments or s
6410: 70 61 63 65 20 69 6e 20 77 68 69 63 68 20 74 6f  pace in which to
6420: 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72 6e  .** write return
6430: 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74   values.  Potent
6440: 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46 69  ial uses for xFi
6450: 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68  leControl() migh
6460: 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  t be.** function
6470: 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63  s to enable bloc
6480: 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 20  king locks with 
6490: 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 61  timeouts, to cha
64a0: 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69  nge the.** locki
64b0: 6e 67 20 73 74 72 61 74 65 67 79 20 28 66 6f 72  ng strategy (for
64c0: 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 20   example to use 
64d0: 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c  dot-file locks),
64e0: 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61   to inquire.** a
64f0: 62 6f 75 74 20 74 68 65 20 73 74 61 74 75 73 20  bout the status 
6500: 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f  of a lock, or to
6510: 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63   break stale loc
6520: 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65 0a  ks.  The SQLite.
6530: 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65 73  ** core reserves
6540: 20 6f 70 63 6f 64 65 73 20 6c 65 73 73 20 74 68   opcodes less th
6550: 61 6e 20 31 30 30 20 66 6f 72 20 69 74 73 20 6f  an 100 for its o
6560: 77 6e 20 75 73 65 2e 20 0a 2a 2a 20 41 20 5b 53  wn use. .** A [S
6570: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b  QLITE_FCNTL_LOCK
6580: 53 54 41 54 45 20 7c 20 6c 69 73 74 20 6f 66 20  STATE | list of 
6590: 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 74 68  opcodes] less th
65a0: 61 6e 20 31 30 30 20 69 73 20 61 76 61 69 6c 61  an 100 is availa
65b0: 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74  ble..** Applicat
65c0: 69 6f 6e 73 20 74 68 61 74 20 64 65 66 69 6e 65  ions that define
65d0: 20 61 20 63 75 73 74 6f 6d 20 78 46 69 6c 65 43   a custom xFileC
65e0: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68  ontrol method sh
65f0: 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 65 73  ould use opcodes
6600: 20 0a 2a 2a 20 67 72 65 61 74 65 72 20 74 68 61   .** greater tha
6610: 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 64 20 63  n 100 to avoid c
6620: 6f 6e 66 6c 69 63 74 73 2e 0a 2a 2a 0a 2a 2a 20  onflicts..**.** 
6630: 54 68 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28  The xSectorSize(
6640: 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  ) method returns
6650: 20 74 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65   the sector size
6660: 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63   of the.** devic
6670: 65 20 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73  e that underlies
6680: 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20   the file.  The 
6690: 73 65 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74  sector size is t
66a0: 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72  he.** minimum wr
66b0: 69 74 65 20 74 68 61 74 20 63 61 6e 20 62 65 20  ite that can be 
66c0: 70 65 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75  performed withou
66d0: 74 20 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20  t disturbing.** 
66e0: 6f 74 68 65 72 20 62 79 74 65 73 20 69 6e 20 74  other bytes in t
66f0: 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44  he file.  The xD
6700: 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73  eviceCharacteris
6710: 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64  tics().** method
6720: 20 72 65 74 75 72 6e 73 20 61 20 62 69 74 20 76   returns a bit v
6730: 65 63 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67  ector describing
6740: 20 62 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68   behaviors of th
6750: 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20  e.** underlying 
6760: 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75  device:.**.** <u
6770: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
6780: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d  TE_IOCAP_ATOMIC]
6790: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
67a0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32  _IOCAP_ATOMIC512
67b0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
67c0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b  E_IOCAP_ATOMIC1K
67d0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
67e0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b  E_IOCAP_ATOMIC2K
67f0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
6800: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b  E_IOCAP_ATOMIC4K
6810: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
6820: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b  E_IOCAP_ATOMIC8K
6830: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
6840: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36  E_IOCAP_ATOMIC16
6850: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
6860: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33  TE_IOCAP_ATOMIC3
6870: 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  2K].** <li> [SQL
6880: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6890: 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  64K].** <li> [SQ
68a0: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f  LITE_IOCAP_SAFE_
68b0: 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20  APPEND].** <li> 
68c0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45  [SQLITE_IOCAP_SE
68d0: 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75  QUENTIAL].** </u
68e0: 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  l>.**.** The SQL
68f0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6900: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
6910: 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20  that all writes 
6920: 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61  of.** any size a
6930: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20  re atomic.  The 
6940: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6950: 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a  MICnnn values.**
6960: 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65   mean that write
6970: 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74  s of blocks that
6980: 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69   are nnn bytes i
6990: 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72  n size and.** ar
69a0: 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
69b0: 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73  address which is
69c0: 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74   an integer mult
69d0: 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61  iple of.** nnn a
69e0: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20  re atomic.  The 
69f0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46  SQLITE_IOCAP_SAF
6a00: 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d  E_APPEND value m
6a10: 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65  eans.** that whe
6a20: 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64  n data is append
6a30: 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68  ed to a file, th
6a40: 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64  e data is append
6a50: 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e  ed.** first then
6a60: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
6a70: 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65   file is extende
6a80: 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68  d, never the oth
6a90: 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64  er.** way around
6aa0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
6ab0: 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70  CAP_SEQUENTIAL p
6ac0: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
6ad0: 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  at.** informatio
6ae0: 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20  n is written to 
6af0: 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65  disk in the same
6b00: 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a   order as calls.
6b10: 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a  ** to xWrite()..
6b20: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
6b30: 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74  t sqlite3_io_met
6b40: 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f  hods sqlite3_io_
6b50: 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20  methods;.struct 
6b60: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
6b70: 64 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73  ds {.  int iVers
6b80: 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c  ion;.  int (*xCl
6b90: 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ose)(sqlite3_fil
6ba0: 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65  e*);.  int (*xRe
6bb0: 61 64 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ad)(sqlite3_file
6bc0: 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41  *, void*, int iA
6bd0: 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  mt, sqlite3_int6
6be0: 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20  4 iOfst);.  int 
6bf0: 28 2a 78 57 72 69 74 65 29 28 73 71 6c 69 74 65  (*xWrite)(sqlite
6c00: 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76  3_file*, const v
6c10: 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20  oid*, int iAmt, 
6c20: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f  sqlite3_int64 iO
6c30: 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54  fst);.  int (*xT
6c40: 72 75 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33  runcate)(sqlite3
6c50: 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f  _file*, sqlite3_
6c60: 69 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69  int64 size);.  i
6c70: 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69  nt (*xSync)(sqli
6c80: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66  te3_file*, int f
6c90: 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78  lags);.  int (*x
6ca0: 46 69 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65  FileSize)(sqlite
6cb0: 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33  3_file*, sqlite3
6cc0: 5f 69 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a  _int64 *pSize);.
6cd0: 20 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73    int (*xLock)(s
6ce0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
6cf0: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c  t);.  int (*xUnl
6d00: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
6d10: 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20  e*, int);.  int 
6d20: 28 2a 78 43 68 65 63 6b 52 65 73 65 72 76 65 64  (*xCheckReserved
6d30: 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69  Lock)(sqlite3_fi
6d40: 6c 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75  le*, int *pResOu
6d50: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c  t);.  int (*xFil
6d60: 65 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65  eControl)(sqlite
6d70: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c  3_file*, int op,
6d80: 20 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20   void *pArg);.  
6d90: 69 6e 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a  int (*xSectorSiz
6da0: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
6db0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69  );.  int (*xDevi
6dc0: 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63  ceCharacteristic
6dd0: 73 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  s)(sqlite3_file*
6de0: 29 3b 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e  );.  /* Addition
6df0: 61 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62  al methods may b
6e00: 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
6e10: 65 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b  e releases */.};
6e20: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
6e30: 3a 20 53 74 61 6e 64 61 72 64 20 46 69 6c 65 20  : Standard File 
6e40: 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73 20  Control Opcodes 
6e50: 7b 46 31 31 33 31 30 7d 0a 2a 2a 0a 2a 2a 20 54  {F11310}.**.** T
6e60: 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  hese integer con
6e70: 73 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64  stants are opcod
6e80: 65 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65  es for the xFile
6e90: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a  Control method.*
6ea0: 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * of the [sqlite
6eb0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
6ec0: 6a 65 63 74 20 61 6e 64 20 74 6f 20 74 68 65 20  ject and to the 
6ed0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
6ee0: 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65  ntrol()].** inte
6ef0: 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rface..**.** The
6f00: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c   [SQLITE_FCNTL_L
6f10: 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64 65  OCKSTATE] opcode
6f20: 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65 62   is used for deb
6f30: 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a  ugging.  This.**
6f40: 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20 74   opcode causes t
6f50: 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  he xFileControl 
6f60: 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65 20  method to write 
6f70: 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61 74  the current stat
6f80: 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b  e of.** the lock
6f90: 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45   (one of [SQLITE
6fa0: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51  _LOCK_NONE], [SQ
6fb0: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44  LITE_LOCK_SHARED
6fc0: 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f  ],.** [SQLITE_LO
6fd0: 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b 53  CK_RESERVED], [S
6fe0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49  QLITE_LOCK_PENDI
6ff0: 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  NG], or [SQLITE_
7000: 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29  LOCK_EXCLUSIVE])
7010: 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65  .** into an inte
7020: 67 65 72 20 74 68 61 74 20 74 68 65 20 70 41 72  ger that the pAr
7030: 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74  g argument point
7040: 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61 62  s to. This capab
7050: 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65 64  ility.** is used
7060: 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20   during testing 
7070: 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74  and only needs t
7080: 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 20 77  o be supported w
7090: 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 0a  hen SQLITE_TEST.
70a0: 2a 2a 20 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a  ** is defined..*
70b0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
70c0: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45  _FCNTL_LOCKSTATE
70d0: 20 20 20 20 20 20 20 20 31 0a 0a 2f 2a 0a 2a 2a          1../*.**
70e0: 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78   CAPI3REF: Mutex
70f0: 20 48 61 6e 64 6c 65 20 7b 46 31 37 31 31 30 7d   Handle {F17110}
7100: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78  .**.** The mutex
7110: 20 6d 6f 64 75 6c 65 20 77 69 74 68 69 6e 20 53   module within S
7120: 51 4c 69 74 65 20 64 65 66 69 6e 65 73 20 5b 73  QLite defines [s
7130: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f  qlite3_mutex] to
7140: 20 62 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61   be an.** abstra
7150: 63 74 20 74 79 70 65 20 66 6f 72 20 61 20 6d 75  ct type for a mu
7160: 74 65 78 20 6f 62 6a 65 63 74 2e 20 20 54 68 65  tex object.  The
7170: 20 53 51 4c 69 74 65 20 63 6f 72 65 20 6e 65 76   SQLite core nev
7180: 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74  er looks.** at t
7190: 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72  he internal repr
71a0: 65 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e  esentation of an
71b0: 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d   [sqlite3_mutex]
71c0: 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65  .  It only.** de
71d0: 61 6c 73 20 77 69 74 68 20 70 6f 69 6e 74 65 72  als with pointer
71e0: 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  s to the [sqlite
71f0: 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e  3_mutex] object.
7200: 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61  .**.** Mutexes a
7210: 72 65 20 63 72 65 61 74 65 64 20 75 73 69 6e 67  re created using
7220: 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
7230: 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70  alloc()]..*/.typ
7240: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
7250: 74 65 33 5f 6d 75 74 65 78 20 73 71 6c 69 74 65  te3_mutex sqlite
7260: 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20  3_mutex;../*.** 
7270: 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74  CAPI3REF: OS Int
7280: 65 72 66 61 63 65 20 4f 62 6a 65 63 74 20 7b 46  erface Object {F
7290: 31 31 31 34 30 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20  11140}.**.** An 
72a0: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
72b0: 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20   object defines 
72c0: 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65  the interface be
72d0: 74 77 65 65 6e 20 74 68 65 0a 2a 2a 20 53 51 4c  tween the.** SQL
72e0: 69 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65  ite core and the
72f0: 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72   underlying oper
7300: 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54  ating system.  T
7310: 68 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74  he "vfs".** in t
7320: 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f  he name of the o
7330: 62 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72  bject stands for
7340: 20 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73   "virtual file s
7350: 79 73 74 65 6d 22 2e 0a 2a 2a 0a 2a 2a 20 54 68  ystem"..**.** Th
7360: 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64  e iVersion field
7370: 20 69 73 20 69 6e 69 74 69 61 6c 6c 79 20 31 20   is initially 1 
7380: 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65  but may be large
7390: 72 20 66 6f 72 20 66 75 74 75 72 65 0a 2a 2a 20  r for future.** 
73a0: 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
73b0: 74 65 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 20  te.  Additional 
73c0: 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70  fields may be ap
73d0: 70 65 6e 64 65 64 20 74 6f 20 74 68 69 73 0a 2a  pended to this.*
73e0: 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e 20 74 68  * object when th
73f0: 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c 75 65  e iVersion value
7400: 20 69 73 20 69 6e 63 72 65 61 73 65 64 2e 0a 2a   is increased..*
7410: 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c  *.** The szOsFil
7420: 65 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 73  e field is the s
7430: 69 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c  ize of the subcl
7440: 61 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66  assed [sqlite3_f
7450: 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72  ile].** structur
7460: 65 20 75 73 65 64 20 62 79 20 74 68 69 73 20 56  e used by this V
7470: 46 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20  FS.  mxPathname 
7480: 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c  is the maximum l
7490: 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61  ength of.** a pa
74a0: 74 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56  thname in this V
74b0: 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74  FS..**.** Regist
74c0: 65 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73  ered sqlite3_vfs
74d0: 20 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70   objects are kep
74e0: 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69  t on a linked li
74f0: 73 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20  st formed by.** 
7500: 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65  the pNext pointe
7510: 72 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  r.  The [sqlite3
7520: 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d  _vfs_register()]
7530: 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
7540: 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28  _vfs_unregister(
7550: 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61  )] interfaces ma
7560: 6e 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a  nage this list.*
7570: 2a 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61  * in a thread-sa
7580: 66 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71  fe way.  The [sq
7590: 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29  lite3_vfs_find()
75a0: 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73  ] interface.** s
75b0: 65 61 72 63 68 65 73 20 74 68 65 20 6c 69 73 74  earches the list
75c0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78  ..**.** The pNex
75d0: 74 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f  t field is the o
75e0: 6e 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65  nly field in the
75f0: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 0a 2a 2a   sqlite3_vfs .**
7600: 20 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20   structure that 
7610: 53 51 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72  SQLite will ever
7620: 20 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65   modify.  SQLite
7630: 20 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73   will only acces
7640: 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74  s.** or modify t
7650: 68 69 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20  his field while 
7660: 68 6f 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63  holding a partic
7670: 75 6c 61 72 20 73 74 61 74 69 63 20 6d 75 74 65  ular static mute
7680: 78 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  x..** The applic
7690: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76  ation should nev
76a0: 65 72 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69  er modify anythi
76b0: 6e 67 20 77 69 74 68 69 6e 20 74 68 65 20 73 71  ng within the sq
76c0: 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a  lite3_vfs.** obj
76d0: 65 63 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a  ect once the obj
76e0: 65 63 74 20 68 61 73 20 62 65 65 6e 20 72 65 67  ect has been reg
76f0: 69 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  istered..**.** T
7700: 68 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68  he zName field h
7710: 6f 6c 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  olds the name of
7720: 20 74 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e   the VFS module.
7730: 20 20 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a    The name must.
7740: 2a 2a 20 62 65 20 75 6e 69 71 75 65 20 61 63 72  ** be unique acr
7750: 6f 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75  oss all VFS modu
7760: 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 31  les..**.** {F111
7770: 34 31 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  41} SQLite will 
7780: 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 74  guarantee that t
7790: 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 73 74 72  he zFilename str
77a0: 69 6e 67 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a  ing passed to.**
77b0: 20 78 4f 70 65 6e 28 29 20 69 73 20 61 20 66 75   xOpen() is a fu
77c0: 6c 6c 20 70 61 74 68 6e 61 6d 65 20 61 73 20 67  ll pathname as g
77d0: 65 6e 65 72 61 74 65 64 20 62 79 20 78 46 75 6c  enerated by xFul
77e0: 6c 50 61 74 68 6e 61 6d 65 28 29 20 61 6e 64 0a  lPathname() and.
77f0: 2a 2a 20 74 68 61 74 20 74 68 65 20 73 74 72 69  ** that the stri
7800: 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64  ng will be valid
7810: 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75   and unchanged u
7820: 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73  ntil xClose() is
7830: 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 20 7b 45 4e  .** called.  {EN
7840: 44 7d 20 53 6f 20 74 68 65 20 5b 73 71 6c 69 74  D} So the [sqlit
7850: 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 74 6f  e3_file] can sto
7860: 72 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  re a pointer to 
7870: 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20  the.** filename 
7880: 69 66 20 69 74 20 6e 65 65 64 73 20 74 6f 20 72  if it needs to r
7890: 65 6d 65 6d 62 65 72 20 74 68 65 20 66 69 6c 65  emember the file
78a0: 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72 65  name for some re
78b0: 61 73 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31  ason..**.** {F11
78c0: 31 34 32 7d 20 54 68 65 20 66 6c 61 67 73 20 61  142} The flags a
78d0: 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e  rgument to xOpen
78e0: 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20  () includes all 
78f0: 62 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74  bits set in.** t
7900: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
7910: 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  t to [sqlite3_op
7920: 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66  en_v2()].  Or if
7930: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
7940: 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ].** or [sqlite3
7950: 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73  _open16()] is us
7960: 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69  ed, then flags i
7970: 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74  ncludes at least
7980: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
7990: 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53  _READWRITE] | [S
79a0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
79b0: 45 5d 2e 20 7b 45 4e 44 7d 0a 2a 2a 20 49 66 20  E]. {END}.** If 
79c0: 78 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20  xOpen() opens a 
79d0: 66 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74  file read-only t
79e0: 68 65 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75  hen it sets *pOu
79f0: 74 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63  tFlags to.** inc
7a00: 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  lude [SQLITE_OPE
7a10: 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74  N_READONLY].  Ot
7a20: 68 65 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75  her bits in *pOu
7a30: 74 46 6c 61 67 73 20 6d 61 79 20 62 65 0a 2a 2a  tFlags may be.**
7a40: 20 73 65 74 2e 0a 2a 2a 20 0a 2a 2a 20 7b 46 31   set..** .** {F1
7a50: 31 31 34 33 7d 20 53 51 4c 69 74 65 20 77 69 6c  1143} SQLite wil
7a60: 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f  l also add one o
7a70: 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
7a80: 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70  flags to the xOp
7a90: 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65  en().** call, de
7aa0: 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f  pending on the o
7ab0: 62 6a 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e  bject being open
7ac0: 65 64 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75 6c 3e 0a  ed:.** .** <ul>.
7ad0: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
7ae0: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a  _OPEN_MAIN_DB].*
7af0: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
7b00: 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41  OPEN_MAIN_JOURNA
7b10: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
7b20: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42  ITE_OPEN_TEMP_DB
7b30: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
7b40: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55  TE_OPEN_TEMP_JOU
7b50: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
7b60: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e  SQLITE_OPEN_TRAN
7b70: 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69  SIENT_DB].** <li
7b80: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
7b90: 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  SUBJOURNAL].** <
7ba0: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
7bb0: 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c  N_MASTER_JOURNAL
7bc0: 5d 0a 2a 2a 20 3c 2f 75 6c 3e 20 7b 45 4e 44 7d  ].** </ul> {END}
7bd0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20  .**.** The file 
7be0: 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  I/O implementati
7bf0: 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 65 20 6f  on can use the o
7c00: 62 6a 65 63 74 20 74 79 70 65 20 66 6c 61 67 73  bject type flags
7c10: 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74   to.** changes t
7c20: 68 65 20 77 61 79 20 69 74 20 64 65 61 6c 73 20  he way it deals 
7c30: 77 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f 72  with files.  For
7c40: 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70   example, an app
7c50: 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74  lication.** that
7c60: 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 61   does not care a
7c70: 62 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f 76  bout crash recov
7c80: 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20  ery or rollback 
7c90: 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68  might make.** th
7ca0: 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72  e open of a jour
7cb0: 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70  nal file a no-op
7cc0: 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74 68 69  .  Writes to thi
7cd0: 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a  s journal would.
7ce0: 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70  ** also be no-op
7cf0: 73 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 65 6d  s, and any attem
7d00: 70 74 20 74 6f 20 72 65 61 64 20 74 68 65 20 6a  pt to read the j
7d10: 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74  ournal would ret
7d20: 75 72 6e 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 49  urn .** SQLITE_I
7d30: 4f 45 52 52 2e 20 20 4f 72 20 74 68 65 20 69 6d  OERR.  Or the im
7d40: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67  plementation mig
7d50: 68 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 61  ht recognize tha
7d60: 74 20 61 20 64 61 74 61 62 61 73 65 20 0a 2a 2a  t a database .**
7d70: 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f   file will be do
7d80: 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64  ing page-aligned
7d90: 20 73 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e   sector reads an
7da0: 64 20 77 72 69 74 65 73 20 69 6e 20 61 20 72 61  d writes in a ra
7db0: 6e 64 6f 6d 20 0a 2a 2a 20 6f 72 64 65 72 20 61  ndom .** order a
7dc0: 6e 64 20 73 65 74 20 75 70 20 69 74 73 20 49 2f  nd set up its I/
7dd0: 4f 20 73 75 62 73 79 73 74 65 6d 20 61 63 63 6f  O subsystem acco
7de0: 72 64 69 6e 67 6c 79 2e 0a 2a 2a 20 0a 2a 2a 20  rdingly..** .** 
7df0: 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73  SQLite might als
7e00: 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65  o add one of the
7e10: 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73   following flags
7e20: 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a 2a 2a   to the xOpen.**
7e30: 20 6d 65 74 68 6f 64 3a 0a 2a 2a 20 0a 2a 2a 20   method:.** .** 
7e40: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  <ul>.** <li> [SQ
7e50: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
7e60: 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e  ONCLOSE].** <li>
7e70: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58   [SQLITE_OPEN_EX
7e80: 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c  CLUSIVE].** </ul
7e90: 3e 0a 2a 2a 20 0a 2a 2a 20 7b 46 31 31 31 34 35  >.** .** {F11145
7ea0: 7d 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  } The [SQLITE_OP
7eb0: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
7ec0: 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65  ] flag means the
7ed0: 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a   file should be.
7ee0: 2a 2a 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20  ** deleted when 
7ef0: 69 74 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 7b  it is closed.  {
7f00: 46 31 31 31 34 36 7d 20 54 68 65 20 5b 53 51 4c  F11146} The [SQL
7f10: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
7f20: 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20  NCLOSE].** will 
7f30: 62 65 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20  be set for TEMP 
7f40: 20 64 61 74 61 62 61 73 65 73 2c 20 6a 6f 75 72   databases, jour
7f50: 6e 61 6c 73 20 61 6e 64 20 66 6f 72 20 73 75 62  nals and for sub
7f60: 6a 6f 75 72 6e 61 6c 73 2e 20 0a 2a 2a 20 7b 46  journals. .** {F
7f70: 31 31 31 34 37 7d 20 54 68 65 20 5b 53 51 4c 49  11147} The [SQLI
7f80: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56  TE_OPEN_EXCLUSIV
7f90: 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68  E] flag means th
7fa0: 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65  e file should be
7fb0: 20 6f 70 65 6e 65 64 0a 2a 2a 20 66 6f 72 20 65   opened.** for e
7fc0: 78 63 6c 75 73 69 76 65 20 61 63 63 65 73 73 2e  xclusive access.
7fd0: 20 20 54 68 69 73 20 66 6c 61 67 20 69 73 20 73    This flag is s
7fe0: 65 74 20 66 6f 72 20 61 6c 6c 20 66 69 6c 65 73  et for all files
7ff0: 20 65 78 63 65 70 74 0a 2a 2a 20 66 6f 72 20 74   except.** for t
8000: 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65  he main database
8010: 20 66 69 6c 65 2e 20 7b 45 4e 44 7d 0a 2a 2a 20   file. {END}.** 
8020: 0a 2a 2a 20 7b 46 31 31 31 34 38 7d 20 41 74 20  .** {F11148} At 
8030: 6c 65 61 73 74 20 73 7a 4f 73 46 69 6c 65 20 62  least szOsFile b
8040: 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61  ytes of memory a
8050: 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20  re allocated by 
8060: 53 51 4c 69 74 65 20 0a 2a 2a 20 74 6f 20 68 6f  SQLite .** to ho
8070: 6c 64 20 74 68 65 20 20 5b 73 71 6c 69 74 65 33  ld the  [sqlite3
8080: 5f 66 69 6c 65 5d 20 73 74 72 75 63 74 75 72 65  _file] structure
8090: 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 74   passed as the t
80a0: 68 69 72 64 20 0a 2a 2a 20 61 72 67 75 6d 65 6e  hird .** argumen
80b0: 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20 7b 45 4e  t to xOpen.  {EN
80c0: 44 7d 20 20 54 68 65 20 78 4f 70 65 6e 20 6d 65  D}  The xOpen me
80d0: 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68 61  thod does not ha
80e0: 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74  ve to.** allocat
80f0: 65 20 74 68 65 20 73 74 72 75 63 74 75 72 65 3b  e the structure;
8100: 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73 74 20   it should just 
8110: 66 69 6c 6c 20 69 74 20 69 6e 2e 0a 2a 2a 20 0a  fill it in..** .
8120: 2a 2a 20 7b 46 31 31 31 34 39 7d 20 54 68 65 20  ** {F11149} The 
8130: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
8140: 6f 20 78 41 63 63 65 73 73 28 29 20 6d 61 79 20  o xAccess() may 
8150: 62 65 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53  be [SQLITE_ACCES
8160: 53 5f 45 58 49 53 54 53 5d 20 0a 2a 2a 20 74 6f  S_EXISTS] .** to
8170: 20 74 65 73 74 20 66 6f 72 20 74 68 65 20 65 78   test for the ex
8180: 69 73 74 65 6e 63 65 20 6f 66 20 61 20 66 69 6c  istence of a fil
8190: 65 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45  e,.** or [SQLITE
81a0: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
81b0: 45 5d 20 74 6f 20 74 65 73 74 20 74 6f 20 73 65  E] to test to se
81c0: 65 0a 2a 2a 20 69 66 20 61 20 66 69 6c 65 20 69  e.** if a file i
81d0: 73 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77  s readable and w
81e0: 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c  ritable, or [SQL
81f0: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d  ITE_ACCESS_READ]
8200: 0a 2a 2a 20 74 6f 20 74 65 73 74 20 74 6f 20 73  .** to test to s
8210: 65 65 20 69 66 20 61 20 66 69 6c 65 20 69 73 20  ee if a file is 
8220: 61 74 20 6c 65 61 73 74 20 72 65 61 64 61 62 6c  at least readabl
8230: 65 2e 20 20 7b 45 4e 44 7d 20 54 68 65 20 66 69  e.  {END} The fi
8240: 6c 65 20 63 61 6e 20 62 65 20 61 20 0a 2a 2a 20  le can be a .** 
8250: 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 20 0a 2a  directory..** .*
8260: 2a 20 7b 46 31 31 31 35 30 7d 20 53 51 4c 69 74  * {F11150} SQLit
8270: 65 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c  e will always al
8280: 6c 6f 63 61 74 65 20 61 74 20 6c 65 61 73 74 20  locate at least 
8290: 6d 78 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74  mxPathname+1 byt
82a0: 65 73 20 66 6f 72 0a 2a 2a 20 74 68 65 20 6f 75  es for.** the ou
82b0: 74 70 75 74 20 62 75 66 66 65 72 20 78 46 75 6c  tput buffer xFul
82c0: 6c 50 61 74 68 6e 61 6d 65 2e 20 7b 46 31 31 31  lPathname. {F111
82d0: 35 31 7d 20 54 68 65 20 65 78 61 63 74 0a 2a 2a  51} The exact.**
82e0: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f 75 74   size of the out
82f0: 70 75 74 20 62 75 66 66 65 72 20 69 73 20 61 6c  put buffer is al
8300: 73 6f 20 70 61 73 73 65 64 20 61 73 20 61 20 70  so passed as a p
8310: 61 72 61 6d 65 74 65 72 20 74 6f 20 62 6f 74 68  arameter to both
8320: 20 0a 2a 2a 20 6d 65 74 68 6f 64 73 2e 20 7b 45   .** methods. {E
8330: 4e 44 7d 20 49 66 20 74 68 65 20 6f 75 74 70 75  ND} If the outpu
8340: 74 20 62 75 66 66 65 72 20 69 73 20 6e 6f 74 20  t buffer is not 
8350: 6c 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53  large enough, [S
8360: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 0a  QLITE_CANTOPEN].
8370: 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74  ** should be ret
8380: 75 72 6e 65 64 2e 20 41 73 20 74 68 69 73 20 69  urned. As this i
8390: 73 20 68 61 6e 64 6c 65 64 20 61 73 20 61 20 66  s handled as a f
83a0: 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20 53 51  atal error by SQ
83b0: 4c 69 74 65 2c 0a 2a 2a 20 76 66 73 20 69 6d 70  Lite,.** vfs imp
83c0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f  lementations sho
83d0: 75 6c 64 20 65 6e 64 65 61 76 6f 72 20 74 6f 20  uld endeavor to 
83e0: 70 72 65 76 65 6e 74 20 74 68 69 73 20 62 79 20  prevent this by 
83f0: 73 65 74 74 69 6e 67 20 0a 2a 2a 20 6d 78 50 61  setting .** mxPa
8400: 74 68 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66  thname to a suff
8410: 69 63 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76  iciently large v
8420: 61 6c 75 65 2e 0a 2a 2a 20 0a 2a 2a 20 54 68 65  alue..** .** The
8430: 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20   xRandomness(), 
8440: 78 53 6c 65 65 70 28 29 2c 20 61 6e 64 20 78 43  xSleep(), and xC
8450: 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69 6e 74  urrentTime() int
8460: 65 72 66 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e  erfaces.** are n
8470: 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20 70 61  ot strictly a pa
8480: 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65 73 79  rt of the filesy
8490: 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79 20 61  stem, but they a
84a0: 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69  re.** included i
84b0: 6e 20 74 68 65 20 56 46 53 20 73 74 72 75 63 74  n the VFS struct
84c0: 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65  ure for complete
84d0: 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61  ness..** The xRa
84e0: 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63 74  ndomness() funct
84f0: 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 6f 20  ion attempts to 
8500: 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20 62 79  return nBytes by
8510: 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71  tes.** of good-q
8520: 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73  uality randomnes
8530: 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68  s into zOut.  Th
8540: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 69  e return value i
8550: 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 6c 20  s.** the actual 
8560: 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
8570: 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62  of randomness ob
8580: 74 61 69 6e 65 64 2e 20 20 54 68 65 0a 2a 2a 20  tained.  The.** 
8590: 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20  xSleep() method 
85a0: 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 69  causes the calli
85b0: 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c 65  ng thread to sle
85c0: 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61  ep for at.** lea
85d0: 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  st the number of
85e0: 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 69   microseconds gi
85f0: 76 65 6e 2e 20 20 54 68 65 20 78 43 75 72 72 65  ven.  The xCurre
8600: 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 68  ntTime().** meth
8610: 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a 75 6c  od returns a Jul
8620: 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72 20 66  ian Day Number f
8630: 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 64  or the current d
8640: 61 74 65 20 61 6e 64 0a 2a 2a 20 74 69 6d 65 2e  ate and.** time.
8650: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
8660: 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 73  ct sqlite3_vfs s
8670: 71 6c 69 74 65 33 5f 76 66 73 3b 0a 73 74 72 75  qlite3_vfs;.stru
8680: 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 7b  ct sqlite3_vfs {
8690: 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b  .  int iVersion;
86a0: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53              /* S
86b0: 74 72 75 63 74 75 72 65 20 76 65 72 73 69 6f 6e  tructure version
86c0: 20 6e 75 6d 62 65 72 20 2a 2f 0a 20 20 69 6e 74   number */.  int
86d0: 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20 20   szOsFile;      
86e0: 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66        /* Size of
86f0: 20 73 75 62 63 6c 61 73 73 65 64 20 73 71 6c 69   subclassed sqli
8700: 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e  te3_file */.  in
8710: 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20 20  t mxPathname;   
8720: 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
8730: 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20  m file pathname 
8740: 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69  length */.  sqli
8750: 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20  te3_vfs *pNext; 
8760: 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 72 65 67       /* Next reg
8770: 69 73 74 65 72 65 64 20 56 46 53 20 2a 2f 0a 20  istered VFS */. 
8780: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
8790: 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d  me;       /* Nam
87a0: 65 20 6f 66 20 74 68 69 73 20 76 69 72 74 75 61  e of this virtua
87b0: 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f  l file system */
87c0: 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74  .  void *pAppDat
87d0: 61 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 50  a;          /* P
87e0: 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 6c 69 63  ointer to applic
87f0: 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63 20 64  ation-specific d
8800: 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ata */.  int (*x
8810: 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66  Open)(sqlite3_vf
8820: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
8830: 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66  zName, sqlite3_f
8840: 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20 20 20  ile*,.          
8850: 20 20 20 20 20 69 6e 74 20 66 6c 61 67 73 2c 20       int flags, 
8860: 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b  int *pOutFlags);
8870: 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c 65 74 65  .  int (*xDelete
8880: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
8890: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
88a0: 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 72 29 3b  e, int syncDir);
88b0: 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 65 73 73  .  int (*xAccess
88c0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
88d0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
88e0: 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e  e, int flags, in
88f0: 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69  t *pResOut);.  i
8900: 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61  nt (*xFullPathna
8910: 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  me)(sqlite3_vfs*
8920: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
8930: 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63  ame, int nOut, c
8940: 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f  har *zOut);.  vo
8950: 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73  id *(*xDlOpen)(s
8960: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
8970: 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61  st char *zFilena
8980: 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44  me);.  void (*xD
8990: 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f  lError)(sqlite3_
89a0: 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c  vfs*, int nByte,
89b0: 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b   char *zErrMsg);
89c0: 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c 53 79  .  void *(*xDlSy
89d0: 6d 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  m)(sqlite3_vfs*,
89e0: 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61  void*, const cha
89f0: 72 20 2a 7a 53 79 6d 62 6f 6c 29 3b 0a 20 20 76  r *zSymbol);.  v
8a00: 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29 28  oid (*xDlClose)(
8a10: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76 6f  sqlite3_vfs*, vo
8a20: 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52  id*);.  int (*xR
8a30: 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69 74  andomness)(sqlit
8a40: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79  e3_vfs*, int nBy
8a50: 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b  te, char *zOut);
8a60: 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65 70 29  .  int (*xSleep)
8a70: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
8a80: 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 29  nt microseconds)
8a90: 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65  ;.  int (*xCurre
8aa0: 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65 33 5f  ntTime)(sqlite3_
8ab0: 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a  vfs*, double*);.
8ac0: 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61 73 74    int (*xGetLast
8ad0: 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76  Error)(sqlite3_v
8ae0: 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72 20 2a  fs*, int, char *
8af0: 29 3b 0a 20 20 2f 2a 20 4e 65 77 20 66 69 65 6c  );.  /* New fiel
8b00: 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64  ds may be append
8b10: 65 64 20 69 6e 20 66 69 67 75 72 65 20 76 65 72  ed in figure ver
8b20: 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 56 65 72  sions.  The iVer
8b30: 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20  sion.  ** value 
8b40: 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77  will increment w
8b50: 68 65 6e 65 76 65 72 20 74 68 69 73 20 68 61 70  henever this hap
8b60: 70 65 6e 73 2e 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a  pens. */.};../*.
8b70: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61  ** CAPI3REF: Fla
8b80: 67 73 20 66 6f 72 20 74 68 65 20 78 41 63 63 65  gs for the xAcce
8b90: 73 73 20 56 46 53 20 6d 65 74 68 6f 64 20 7b 46  ss VFS method {F
8ba0: 31 31 31 39 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31  11190}.**.** {F1
8bb0: 31 31 39 31 7d 20 54 68 65 73 65 20 69 6e 74 65  1191} These inte
8bc0: 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61  ger constants ca
8bd0: 6e 20 62 65 20 75 73 65 64 20 61 73 20 74 68 65  n be used as the
8be0: 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
8bf0: 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65   to.** the xAcce
8c00: 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20  ss method of an 
8c10: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
8c20: 6a 65 63 74 2e 20 7b 45 4e 44 7d 20 20 54 68 65  ject. {END}  The
8c30: 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77  y determine.** w
8c40: 68 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d  hat kind of perm
8c50: 69 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63  issions the xAcc
8c60: 65 73 73 20 6d 65 74 68 6f 64 20 69 73 0a 2a 2a  ess method is.**
8c70: 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e 20 20 7b   looking for.  {
8c80: 46 31 31 31 39 32 7d 20 57 69 74 68 20 5b 53 51  F11192} With [SQ
8c90: 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53  LITE_ACCESS_EXIS
8ca0: 54 53 5d 2c 20 74 68 65 20 78 41 63 63 65 73 73  TS], the xAccess
8cb0: 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c   method.** simpl
8cc0: 79 20 63 68 65 63 6b 73 20 74 6f 20 73 65 65 20  y checks to see 
8cd0: 69 66 20 74 68 65 20 66 69 6c 65 20 65 78 69 73  if the file exis
8ce0: 74 73 2e 20 7b 46 31 31 31 39 33 7d 20 57 69 74  ts. {F11193} Wit
8cf0: 68 0a 2a 2a 20 53 51 4c 49 54 45 5f 41 43 43 45  h.** SQLITE_ACCE
8d00: 53 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68  SS_READWRITE, th
8d10: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
8d20: 20 63 68 65 63 6b 73 20 74 6f 20 73 65 65 0a 2a   checks to see.*
8d30: 2a 20 69 66 20 74 68 65 20 66 69 6c 65 20 69 73  * if the file is
8d40: 20 62 6f 74 68 20 72 65 61 64 61 62 6c 65 20 61   both readable a
8d50: 6e 64 20 77 72 69 74 61 62 6c 65 2e 20 20 7b 46  nd writable.  {F
8d60: 31 31 31 39 34 7d 20 57 69 74 68 0a 2a 2a 20 53  11194} With.** S
8d70: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
8d80: 44 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  D the xAccess me
8d90: 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 74  thod.** checks t
8da0: 6f 20 73 65 65 20 69 66 20 74 68 65 20 66 69 6c  o see if the fil
8db0: 65 20 69 73 20 72 65 61 64 61 62 6c 65 2e 0a 2a  e is readable..*
8dc0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
8dd0: 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 20 20  _ACCESS_EXISTS  
8de0: 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    0.#define SQLI
8df0: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52  TE_ACCESS_READWR
8e00: 49 54 45 20 31 0a 23 64 65 66 69 6e 65 20 53 51  ITE 1.#define SQ
8e10: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
8e20: 20 20 20 20 20 20 32 0a 0a 2f 2a 0a 2a 2a 20 43        2../*.** C
8e30: 41 50 49 33 52 45 46 3a 20 49 6e 69 74 69 61 6c  API3REF: Initial
8e40: 69 7a 65 20 54 68 65 20 53 51 4c 69 74 65 20 4c  ize The SQLite L
8e50: 69 62 72 61 72 79 20 7b 46 31 30 31 33 30 7d 0a  ibrary {F10130}.
8e60: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
8e70: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72  3_initialize() r
8e80: 6f 75 74 69 6e 65 20 69 6e 69 74 69 61 6c 69 7a  outine initializ
8e90: 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65  es the.** SQLite
8ea0: 20 6c 69 62 72 61 72 79 20 70 72 69 6f 72 20 74   library prior t
8eb0: 6f 20 75 73 65 2e 20 20 54 68 65 20 73 71 6c 69  o use.  The sqli
8ec0: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 72  te3_shutdown() r
8ed0: 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f  outine.** deallo
8ee0: 63 61 74 65 73 20 61 6e 79 20 72 65 73 6f 75 72  cates any resour
8ef0: 63 65 73 20 74 68 61 74 20 77 65 72 65 20 61 6c  ces that were al
8f00: 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74  located by sqlit
8f10: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e  e3_initialize().
8f20: 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f  .**.** A call to
8f30: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
8f40: 69 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66 66  ize() is an "eff
8f50: 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20  ective" call if 
8f60: 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72  it is.** the fir
8f70: 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f  st time sqlite3_
8f80: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
8f90: 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74  invoked during t
8fa0: 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a  he lifetime of.*
8fb0: 2a 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f  * the process, o
8fc0: 72 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66  r if it is the f
8fd0: 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65  irst time sqlite
8fe0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
8ff0: 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c  s invoked.** fol
9000: 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f  lowing a call to
9010: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
9020: 6e 28 29 2e 20 20 4f 6e 6c 79 20 61 6e 20 65 66  n().  Only an ef
9030: 66 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a 20  fective call.** 
9040: 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  of sqlite3_initi
9050: 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 61 6e 79  alize() does any
9060: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e   initialization.
9070: 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c 6c    All other call
9080: 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65 73  s.** are harmles
9090: 73 20 6e 6f 2d 6f 70 73 2e 20 20 49 6e 20 6f 74  s no-ops.  In ot
90a0: 68 65 72 20 77 6f 72 64 73 2c 0a 2a 2a 20 74 68  her words,.** th
90b0: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
90c0: 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 6d  lize() routine m
90d0: 61 79 20 62 65 20 63 61 6c 6c 65 64 20 6d 75 6c  ay be called mul
90e0: 74 69 70 6c 65 20 74 69 6d 65 73 0a 2a 2a 20 77  tiple times.** w
90f0: 69 74 68 6f 75 74 20 63 6f 6e 73 65 71 75 65 6e  ithout consequen
9100: 63 65 2e 20 20 53 65 63 6f 6e 64 20 61 6e 64 20  ce.  Second and 
9110: 73 75 62 73 65 71 75 65 6e 74 20 65 76 61 6c 75  subsequent evalu
9120: 61 74 69 6f 6e 73 20 6f 66 0a 2a 2a 20 73 71 6c  ations of.** sql
9130: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
9140: 29 20 61 72 65 20 6e 6f 2d 6f 70 73 2e 20 20 54  ) are no-ops.  T
9150: 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  he sqlite3_initi
9160: 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 0a  alize() routine.
9170: 2a 2a 20 6f 6e 6c 79 20 77 6f 72 6b 73 20 74 68  ** only works th
9180: 65 20 66 69 72 73 74 20 74 69 6d 65 20 69 74 20  e first time it 
9190: 69 73 20 63 61 6c 6c 65 64 20 66 6f 72 20 61 20  is called for a 
91a0: 70 72 6f 63 65 73 73 2c 20 6f 72 20 74 68 65 20  process, or the 
91b0: 66 69 72 73 74 0a 2a 2a 20 74 69 6d 65 20 69 74  first.** time it
91c0: 20 69 73 20 63 61 6c 6c 65 64 20 61 66 74 65 72   is called after
91d0: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
91e0: 6e 28 29 2e 20 20 49 6e 20 61 6c 6c 20 6f 74 68  n().  In all oth
91f0: 65 72 20 63 61 73 65 73 2c 0a 2a 2a 20 73 71 6c  er cases,.** sql
9200: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
9210: 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45  ) returns SQLITE
9220: 5f 4f 4b 20 77 69 74 68 6f 75 74 20 64 6f 69 6e  _OK without doin
9230: 67 20 61 6e 79 20 72 65 61 6c 20 77 6f 72 6b 2e  g any real work.
9240: 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68  .**.** Among oth
9250: 65 72 20 74 68 69 6e 67 73 2c 20 73 71 6c 69 74  er things, sqlit
9260: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
9270: 73 68 61 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20  shall invoke.** 
9280: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
9290: 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20 73  ).  Similarly, s
92a0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
92b0: 29 0a 2a 2a 20 73 68 61 6c 6c 20 69 6e 76 6f 6b  ).** shall invok
92c0: 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  e sqlite3_os_end
92d0: 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ()..**.** The sq
92e0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
92f0: 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
9300: 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 20 6f 6e 20  ns SQLITE_OK on 
9310: 73 75 63 63 65 73 73 2e 0a 2a 2a 20 49 66 20 66  success..** If f
9320: 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20  or some reason, 
9330: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
9340: 7a 65 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74  ze() is unable t
9350: 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20  o initialize.** 
9360: 74 68 65 20 6c 69 62 72 61 72 79 20 28 70 65 72  the library (per
9370: 68 61 70 73 20 69 74 20 69 73 20 75 6e 61 62 6c  haps it is unabl
9380: 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20  e to allocate a 
9390: 6e 65 65 64 65 64 20 72 65 73 6f 75 72 63 65 20  needed resource 
93a0: 73 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74  such.** as a mut
93b0: 65 78 29 20 69 74 20 72 65 74 75 72 6e 73 20 61  ex) it returns a
93c0: 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f  n [error code] o
93d0: 74 68 65 72 20 74 68 61 6e 20 53 51 4c 49 54 45  ther than SQLITE
93e0: 5f 4f 4b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  _OK..**.** The s
93f0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
9400: 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63  e() routine is c
9410: 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79  alled internally
9420: 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a   by many other.*
9430: 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  * SQLite interfa
9440: 63 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20 61  ces so that an a
9450: 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 6c  pplication usual
9460: 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  ly does not need
9470: 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71   to.** invoke sq
9480: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
9490: 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46 6f  () directly.  Fo
94a0: 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69  r example, [sqli
94b0: 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63  te3_open()].** c
94c0: 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69  alls sqlite3_ini
94d0: 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 65  tialize() so the
94e0: 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20   SQLite library 
94f0: 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69  will be automati
9500: 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c  cally.** initial
9510: 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74  ized when [sqlit
9520: 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 61  e3_open()] is ca
9530: 6c 6c 65 64 20 69 66 20 69 74 20 68 61 73 20 6e  lled if it has n
9540: 6f 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65  ot be initialize
9550: 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 48  d.** already.  H
9560: 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69 74  owever, if SQLit
9570: 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
9580: 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d  th the SQLITE_OM
9590: 49 54 5f 41 55 54 4f 49 4e 49 54 0a 2a 2a 20 63  IT_AUTOINIT.** c
95a0: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
95b0: 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 61 75 74  on, then the aut
95c0: 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20 74 6f 20  omatic calls to 
95d0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
95e0: 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d 69 74  ze().** are omit
95f0: 74 65 64 20 61 6e 64 20 74 68 65 20 61 70 70 6c  ted and the appl
9600: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 63 61 6c  ication must cal
9610: 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  l sqlite3_initia
9620: 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 0a  lize() directly.
9630: 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e  ** prior to usin
9640: 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69  g any other SQLi
9650: 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46  te interface.  F
9660: 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72 74 61  or maximum porta
9670: 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20 69 73  bility,.** it is
9680: 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61   recommended tha
9690: 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61  t applications a
96a0: 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20 73 71 6c  lways invoke sql
96b0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
96c0: 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20 70 72  ).** directly pr
96d0: 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79  ior to using any
96e0: 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
96f0: 74 65 72 66 61 63 65 2e 20 20 46 75 74 75 72 65  terface.  Future
9700: 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f 66 20   releases.** of 
9710: 53 51 4c 69 74 65 20 6d 61 79 20 72 65 71 75 69  SQLite may requi
9720: 72 65 20 74 68 69 73 2e 20 20 49 6e 20 6f 74 68  re this.  In oth
9730: 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 62 65  er words, the be
9740: 68 61 76 69 6f 72 20 65 78 68 69 62 69 74 65 64  havior exhibited
9750: 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20  .** when SQLite 
9760: 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
9770: 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54   SQLITE_OMIT_AUT
9780: 4f 49 4e 49 54 20 6d 69 67 68 74 20 62 65 63 6f  OINIT might beco
9790: 6d 65 20 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c  me the.** defaul
97a0: 74 20 62 65 68 61 76 69 6f 72 20 69 6e 20 73 6f  t behavior in so
97b0: 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  me future releas
97c0: 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a  e of SQLite..**.
97d0: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f  ** The sqlite3_o
97e0: 73 5f 69 6e 69 74 28 29 20 72 6f 75 74 69 6e 65  s_init() routine
97f0: 20 64 6f 65 73 20 6f 70 65 72 61 74 69 6e 67 2d   does operating-
9800: 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 0a  system specific.
9810: 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ** initializatio
9820: 6e 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20  n of the SQLite 
9830: 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 73 71  library.  The sq
9840: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a  lite3_os_end().*
9850: 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73  * routine undoes
9860: 20 74 68 65 20 65 66 66 65 63 74 20 6f 66 20 73   the effect of s
9870: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
9880: 2e 20 20 54 79 70 69 63 61 6c 20 74 61 73 6b 73  .  Typical tasks
9890: 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 62 79  .** performed by
98a0: 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
98b0: 69 6e 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69  include allocati
98c0: 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69  on or deallocati
98d0: 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63 20  on.** of static 
98e0: 72 65 73 6f 75 72 63 65 73 2c 20 69 6e 69 74 69  resources, initi
98f0: 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f  alization of glo
9900: 62 61 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a  bal variables,.*
9910: 2a 20 73 65 74 74 69 6e 67 20 75 70 20 61 20 64  * setting up a d
9920: 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f  efault [sqlite3_
9930: 76 66 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20  vfs] module, or 
9940: 73 65 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20  setting up.** a 
9950: 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72  default configur
9960: 61 74 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c  ation using [sql
9970: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 20  ite3_config()]. 
9980: 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c   .**.** The appl
9990: 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e  ication should n
99a0: 65 76 65 72 20 69 6e 76 6f 6b 65 20 65 69 74 68  ever invoke eith
99b0: 65 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  er sqlite3_os_in
99c0: 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  it().** or sqlit
99d0: 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69 72 65  e3_os_end() dire
99e0: 63 74 6c 79 2e 20 20 54 68 65 20 61 70 70 6c 69  ctly.  The appli
99f0: 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e  cation should on
9a00: 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c  ly invoke.** sql
9a10: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
9a20: 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 73 68  ) and sqlite3_sh
9a30: 75 74 64 6f 77 6e 28 29 2e 20 20 54 68 65 20 73  utdown().  The s
9a40: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
9a50: 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73  .** interface is
9a60: 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61 74 69   called automati
9a70: 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33  cally by sqlite3
9a80: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e  _initialize() an
9a90: 64 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73  d .** sqlite3_os
9aa0: 5f 65 6e 64 28 29 20 69 73 20 63 61 6c 6c 65 64  _end() is called
9ab0: 20 62 79 20 73 71 6c 69 74 65 33 5f 73 68 75 74   by sqlite3_shut
9ac0: 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f 70 72  down().  Appropr
9ad0: 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  iate.** implemen
9ae0: 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c 69  tations for sqli
9af0: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e  te3_os_init() an
9b00: 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  d sqlite3_os_end
9b10: 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74 20  ().** are built 
9b20: 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 68 65 6e  into SQLite when
9b30: 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 64 20   it is compiled 
9b40: 66 6f 72 20 75 6e 69 78 2c 20 77 69 6e 64 6f 77  for unix, window
9b50: 73 2c 20 6f 72 20 6f 73 2f 32 2e 0a 2a 2a 20 57  s, or os/2..** W
9b60: 68 65 6e 20 62 75 69 6c 74 20 66 6f 72 20 6f 74  hen built for ot
9b70: 68 65 72 20 70 6c 61 74 66 6f 72 6d 73 20 28 75  her platforms (u
9b80: 73 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f  sing the SQLITE_
9b90: 4f 53 5f 4f 54 48 45 52 3d 31 20 63 6f 6d 70 69  OS_OTHER=1 compi
9ba0: 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f  le-time.** optio
9bb0: 6e 29 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  n) the applicati
9bc0: 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 20 61  on must supply a
9bd0: 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d   suitable implem
9be0: 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20  entation for.** 
9bf0: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
9c00: 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73  ) and sqlite3_os
9c10: 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61 70 70 6c  _end().  An appl
9c20: 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64  ication-supplied
9c30: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
9c40: 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73  on of sqlite3_os
9c50: 5f 69 6e 69 74 28 29 20 6f 72 20 73 71 6c 69 74  _init() or sqlit
9c60: 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d  e3_os_end().** m
9c70: 75 73 74 20 72 65 74 75 72 6e 20 53 51 4c 49 54  ust return SQLIT
9c80: 45 5f 4f 4b 20 6f 6e 20 73 75 63 63 65 73 73 20  E_OK on success 
9c90: 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b  and some other [
9ca0: 65 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e  error code] upon
9cb0: 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a  .** failure..*/.
9cc0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  int sqlite3_init
9cd0: 69 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 69 6e  ialize(void);.in
9ce0: 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  t sqlite3_shutdo
9cf0: 77 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71  wn(void);.int sq
9d00: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f  lite3_os_init(vo
9d10: 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  id);.int sqlite3
9d20: 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a  _os_end(void);..
9d30: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
9d40: 43 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65 20  Configuring The 
9d50: 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 20 7b  SQLite Library {
9d60: 46 31 30 31 34 35 7d 0a 2a 2a 0a 2a 2a 20 54 68  F10145}.**.** Th
9d70: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  e sqlite3_config
9d80: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
9d90: 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f  used to make glo
9da0: 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  bal configuratio
9db0: 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20  n.** changes to 
9dc0: 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20  SQLite in order 
9dd0: 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 65 20 74  to tune SQLite t
9de0: 6f 20 74 68 65 20 73 70 65 63 69 66 69 63 20 6e  o the specific n
9df0: 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61  eeds of.** the a
9e00: 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 65  pplication.  The
9e10: 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75   default configu
9e20: 72 61 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d  ration is recomm
9e30: 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a  ended for most.*
9e40: 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61  * applications a
9e50: 6e 64 20 73 6f 20 74 68 69 73 20 72 6f 75 74 69  nd so this routi
9e60: 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f  ne is usually no
9e70: 74 20 6e 65 63 65 73 73 61 72 79 2e 20 20 49 74  t necessary.  It
9e80: 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20   is.** provided 
9e90: 74 6f 20 73 75 70 70 6f 72 74 20 72 61 72 65 20  to support rare 
9ea0: 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69 74  applications wit
9eb0: 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e  h unusual needs.
9ec0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
9ed0: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65  e3_config() inte
9ee0: 72 66 61 63 65 20 69 73 20 6e 6f 74 20 74 68 72  rface is not thr
9ef0: 65 61 64 73 61 66 65 2e 20 20 54 68 65 20 61 70  eadsafe.  The ap
9f00: 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73  plication.** mus
9f10: 74 20 69 6e 73 75 72 65 20 74 68 61 74 20 6e 6f  t insure that no
9f20: 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
9f30: 74 65 72 66 61 63 65 73 20 61 72 65 20 69 6e 76  terfaces are inv
9f40: 6f 6b 65 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a  oked by other.**
9f50: 20 74 68 72 65 61 64 73 20 77 68 69 6c 65 20 73   threads while s
9f60: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
9f70: 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20 46 75 72  is running.  Fur
9f80: 74 68 65 72 6d 6f 72 65 2c 20 73 71 6c 69 74 65  thermore, sqlite
9f90: 33 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d 61  3_config().** ma
9fa0: 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65  y only be invoke
9fb0: 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 72 61  d prior to libra
9fc0: 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ry initializatio
9fd0: 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  n using.** [sqli
9fe0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
9ff0: 5d 20 6f 72 20 61 66 74 65 72 20 73 68 75 74 64  ] or after shutd
a000: 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  own by [sqlite3_
a010: 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20  shutdown()]..** 
a020: 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20 74  Note, however, t
a030: 68 61 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  hat sqlite3_conf
a040: 69 67 28 29 20 63 61 6e 20 62 65 20 63 61 6c 6c  ig() can be call
a050: 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68  ed as part of th
a060: 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
a070: 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69 63  ion of an applic
a080: 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73  ation-defined [s
a090: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
a0a0: 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  ]..**.** The fir
a0b0: 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  st argument to s
a0c0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
a0d0: 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  is an integer.**
a0e0: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
a0f0: 53 49 4e 47 4c 45 54 48 52 45 41 44 20 7c 20 63  SINGLETHREAD | c
a100: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
a110: 69 6f 6e 5d 20 74 68 61 74 20 64 65 74 65 72 6d  ion] that determ
a120: 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f  ines.** what pro
a130: 70 65 72 74 79 20 6f 66 20 53 51 4c 69 74 65 20  perty of SQLite 
a140: 69 73 20 74 6f 20 62 65 20 63 6f 6e 66 69 67 75  is to be configu
a150: 72 65 64 2e 20 20 53 75 62 73 65 71 75 65 6e 74  red.  Subsequent
a160: 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61   arguments.** va
a170: 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  ry depending on 
a180: 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  the [SQLITE_CONF
a190: 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20  IG_SINGLETHREAD 
a1a0: 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  | configuration 
a1b0: 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68  option].** in th
a1c0: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
a1d0: 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 61 20 63  ..**.** When a c
a1e0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
a1f0: 69 6f 6e 20 69 73 20 73 65 74 2c 20 73 71 6c 69  ion is set, sqli
a200: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 72 65 74  te3_config() ret
a210: 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 2e 0a  urns SQLITE_OK..
a220: 2a 2a 20 49 66 20 74 68 65 20 6f 70 74 69 6f 6e  ** If the option
a230: 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53   is unknown or S
a240: 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20  QLite is unable 
a250: 74 6f 20 73 65 74 20 74 68 65 20 6f 70 74 69 6f  to set the optio
a260: 6e 20 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20  n .** then this 
a270: 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
a280: 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f  a non-zero [erro
a290: 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20  r code]..*/.int 
a2a0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69  sqlite3_config(i
a2b0: 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a  nt, ...);../*.**
a2c0: 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72   CAPI3REF: Memor
a2d0: 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75  y Allocation Rou
a2e0: 74 69 6e 65 73 20 7b 46 31 30 31 35 35 7d 0a 2a  tines {F10155}.*
a2f0: 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65  *.** An instance
a300: 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20   of this object 
a310: 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65  defines the inte
a320: 72 66 61 63 65 20 62 65 74 77 65 65 6e 20 53 51  rface between SQ
a330: 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d  Lite.** and low-
a340: 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c  level memory all
a350: 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
a360: 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f  .  .**.** This o
a370: 62 6a 65 63 74 20 69 73 20 75 73 65 64 20 69 6e  bject is used in
a380: 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20   only one place 
a390: 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e  in the SQLite in
a3a0: 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f  terface..** A po
a3b0: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74  inter to an inst
a3c0: 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
a3d0: 65 63 74 20 69 73 20 74 68 65 20 61 72 67 75 6d  ect is the argum
a3e0: 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  ent to.** [sqlit
a3f0: 65 33 5f 63 6f 6e 66 69 67 5d 20 77 68 65 6e 20  e3_config] when 
a400: 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  the configuratio
a410: 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b  n option is.** [
a420: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
a430: 4c 4c 4f 43 5d 2e 20 20 42 79 20 63 72 65 61 74  LLOC].  By creat
a440: 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63 65 20  ing an instance 
a450: 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a  of this object.*
a460: 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20 69 74  * and passing it
a470: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e   to [sqlite3_con
a480: 66 69 67 5d 20 64 75 72 69 6e 67 20 63 6f 6e 66  fig] during conf
a490: 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 0a 2a 2a  iguration, an.**
a4a0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e   application can
a4b0: 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65   specify an alte
a4c0: 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79 20 61  rnative memory a
a4d0: 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73  llocation subsys
a4e0: 74 65 6d 0a 2a 2a 20 66 6f 72 20 53 51 4c 69 74  tem.** for SQLit
a4f0: 65 20 74 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c  e to use for all
a500: 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20   of its dynamic 
a510: 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a  memory needs..**
a520: 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51  .** Note that SQ
a530: 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74 68 20  Lite comes with 
a540: 61 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72  a built-in memor
a550: 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74  y allocator that
a560: 20 69 73 0a 2a 2a 20 70 65 72 66 65 63 74 6c 79   is.** perfectly
a570: 20 61 64 65 71 75 61 74 65 20 66 6f 72 20 74 68   adequate for th
a580: 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d  e overwhelming m
a590: 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69  ajority of appli
a5a0: 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74  cations.** and t
a5b0: 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63 74 20  hat this object 
a5c0: 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74  is only useful t
a5d0: 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74  o a tiny minorit
a5e0: 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e  y of application
a5f0: 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63 69 61  s.** with specia
a600: 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c  lized memory all
a610: 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72 65 6d  ocation requirem
a620: 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62 6a 65  ents.  This obje
a630: 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73  ct is.** also us
a640: 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e  ed during testin
a650: 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e 20 6f  g of SQLite in o
a660: 72 64 65 72 20 74 6f 20 73 70 65 63 69 66 79 20  rder to specify 
a670: 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a  an alternative.*
a680: 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * memory allocat
a690: 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 65  or that simulate
a6a0: 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d  s memory out-of-
a6b0: 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e  memory condition
a6c0: 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f  s in.** order to
a6d0: 20 76 65 72 69 66 79 20 74 68 61 74 20 53 51 4c   verify that SQL
a6e0: 69 74 65 20 72 65 63 6f 76 65 72 73 20 67 72 61  ite recovers gra
a6f0: 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63  cefully from suc
a700: 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e  h.** conditions.
a710: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c  .**.** The xMall
a720: 6f 63 2c 20 78 46 72 65 65 2c 20 61 6e 64 20 78  oc, xFree, and x
a730: 52 65 61 6c 6c 6f 63 20 6d 65 74 68 6f 64 73 20  Realloc methods 
a740: 73 68 6f 75 6c 64 20 77 6f 72 6b 20 6c 69 6b 65  should work like
a750: 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29   the.** malloc()
a760: 2c 20 66 72 65 65 28 29 2c 20 61 6e 64 20 72 65  , free(), and re
a770: 61 6c 6c 6f 63 28 29 20 66 75 6e 63 74 69 6f 6e  alloc() function
a780: 73 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64  s from the stand
a790: 61 72 64 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a  ard library..**.
a7a0: 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20  ** xSize should 
a7b0: 72 65 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63  return the alloc
a7c0: 61 74 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d  ated size of a m
a7d0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
a7e0: 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f  .** previously o
a7f0: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61  btained from xMa
a800: 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63  lloc or xRealloc
a810: 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64  .  The allocated
a820: 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61   size.** is alwa
a830: 79 73 20 61 74 20 6c 65 61 73 74 20 61 73 20 62  ys at least as b
a840: 69 67 20 61 73 20 74 68 65 20 72 65 71 75 65 73  ig as the reques
a850: 74 65 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79  ted size but may
a860: 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a   be larger..**.*
a870: 2a 20 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d  * The xRoundup m
a880: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68  ethod returns wh
a890: 61 74 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20  at would be the 
a8a0: 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f  allocated size o
a8b0: 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c  f.** a memory al
a8c0: 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61  location given a
a8d0: 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 71 75   particular requ
a8e0: 65 73 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73  ested size.  Mos
a8f0: 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  t memory.** allo
a900: 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20  cators round up 
a910: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
a920: 6e 73 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74  ns at least to t
a930: 68 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65  he next multiple
a940: 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20  .** of 8.  Some 
a950: 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64  allocators round
a960: 20 75 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20   up to a larger 
a970: 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61  multiple or to a
a980: 20 70 6f 77 65 72 20 6f 66 20 32 2e 20 0a 2a 2a   power of 2. .**
a990: 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d 65  .** The xInit me
a9a0: 74 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65 73  thod initializes
a9b0: 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
a9c0: 63 61 74 6f 72 2e 20 20 28 46 6f 72 20 65 78 61  cator.  (For exa
a9d0: 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68  mple,.** it migh
a9e0: 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72  t allocate any r
a9f0: 65 71 75 69 72 65 20 6d 75 74 65 78 65 73 20 6f  equire mutexes o
aa00: 72 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74  r initialize int
aa10: 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74  ernal data.** st
aa20: 72 75 63 74 75 72 65 73 2e 20 20 54 68 65 20 78  ructures.  The x
aa30: 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20  Shutdown method 
aa40: 69 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69  is invoked (indi
aa50: 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73  rectly) by.** [s
aa60: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
aa70: 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 65  )] and should de
aa80: 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 73  allocate any res
aa90: 6f 75 72 63 65 73 20 61 63 71 75 69 72 65 64 0a  ources acquired.
aaa0: 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54 68  ** by xInit.  Th
aab0: 65 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e 74  e pAppData point
aac0: 65 72 20 69 73 20 75 73 65 64 20 61 73 20 74 68  er is used as th
aad0: 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72  e only parameter
aae0: 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64   to.** xInit and
aaf0: 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2f 0a 74   xShutdown..*/.t
ab00: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
ab10: 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
ab20: 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  s sqlite3_mem_me
ab30: 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71  thods;.struct sq
ab40: 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
ab50: 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d  s {.  void *(*xM
ab60: 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20  alloc)(int);    
ab70: 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61       /* Memory a
ab80: 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69  llocation functi
ab90: 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78  on */.  void (*x
aba0: 46 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20  Free)(void*);   
abb0: 20 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61         /* Free a
abc0: 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
abd0: 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78  n */.  void *(*x
abe0: 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69  Realloc)(void*,i
abf0: 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20  nt);  /* Resize 
ac00: 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f  an allocation */
ac10: 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28  .  int (*xSize)(
ac20: 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20  void*);         
ac30: 20 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20    /* Return the 
ac40: 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63  size of an alloc
ac50: 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28  ation */.  int (
ac60: 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b  *xRoundup)(int);
ac70: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75            /* Rou
ac80: 6e 64 20 75 70 20 72 65 71 75 65 73 74 20 73 69  nd up request si
ac90: 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e  ze to allocation
aca0: 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28   size */.  int (
acb0: 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20  *xInit)(void*); 
acc0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69            /* Ini
acd0: 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f  tialize the memo
ace0: 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a  ry allocator */.
acf0: 20 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f    void (*xShutdo
ad00: 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  wn)(void*);     
ad10: 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65   /* Deinitialize
ad20: 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
ad30: 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20  cator */.  void 
ad40: 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20  *pAppData;      
ad50: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67            /* Arg
ad60: 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29  ument to xInit()
ad70: 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29   and xShutdown()
ad80: 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
ad90: 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72  PI3REF: Configur
ada0: 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 20 7b 46  ation Options {F
adb0: 31 30 31 36 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  10160}.**.** The
adc0: 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  se constants are
add0: 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69   the available i
ade0: 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61  nteger configura
adf0: 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61  tion options tha
ae00: 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73  t.** can be pass
ae10: 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20  ed as the first 
ae20: 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
ae30: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
ae40: 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  )] interface..**
ae50: 20 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74   .** <dl>.** <dt
ae60: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  >SQLITE_CONFIG_S
ae70: 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e  INGLETHREAD</dt>
ae80: 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72  .** <dd>There ar
ae90: 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74  e no arguments t
aea0: 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20  o this option.  
aeb0: 54 68 69 73 20 6f 70 74 69 6f 6e 20 64 69 73 61  This option disa
aec0: 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65  bles.** all mute
aed0: 78 69 6e 67 20 61 6e 64 20 70 75 74 73 20 53 51  xing and puts SQ
aee0: 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65  Lite into a mode
aef0: 20 77 68 65 72 65 20 69 74 20 63 61 6e 20 6f 6e   where it can on
af00: 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a 20 62 79  ly be used.** by
af10: 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64   a single thread
af20: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
af30: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
af40: 55 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a  ULTITHREAD</dt>.
af50: 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65  ** <dd>There are
af60: 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f   no arguments to
af70: 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 54   this option.  T
af80: 68 69 73 20 6f 70 74 69 6f 6e 20 64 69 73 61 62  his option disab
af90: 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20  les.** mutexing 
afa0: 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  on [database con
afb0: 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72  nection] and [pr
afc0: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
afd0: 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68  ] objects..** Th
afe0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73  e application is
aff0: 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
b000: 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 63 63   serializing acc
b010: 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62  ess to.** [datab
b020: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d  ase connections]
b030: 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73   and [prepared s
b040: 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74  tatements].  But
b050: 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73 0a 2a   other mutexes.*
b060: 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 73 6f  * are enabled so
b070: 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c   that SQLite wil
b080: 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75 73 65  l be safe to use
b090: 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65   in a multi-thre
b0a0: 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d  aded.** environm
b0b0: 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ent.</dd>.**.** 
b0c0: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
b0d0: 47 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74  G_SERIALIZED</dt
b0e0: 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61  >.** <dd>There a
b0f0: 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20  re no arguments 
b100: 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20  to this option. 
b110: 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61   This option ena
b120: 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65  bles.** all mute
b130: 78 65 73 20 69 6e 63 6c 75 64 69 6e 67 20 74 68  xes including th
b140: 65 20 72 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d  e recursive.** m
b150: 75 74 65 78 65 73 20 6f 6e 20 5b 64 61 74 61 62  utexes on [datab
b160: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
b170: 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  and [prepared st
b180: 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73  atement] objects
b190: 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64  ..** In this mod
b1a0: 65 20 28 77 68 69 63 68 20 69 73 20 74 68 65 20  e (which is the 
b1b0: 64 65 66 61 75 6c 74 20 77 68 65 6e 20 53 51 4c  default when SQL
b1c0: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
b1d0: 77 69 74 68 0a 2a 2a 20 53 51 4c 49 54 45 5f 54  with.** SQLITE_T
b1e0: 48 52 45 41 44 53 41 46 45 3d 31 29 20 74 68 65  HREADSAFE=1) the
b1f0: 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20   SQLite library 
b200: 77 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69  will itself seri
b210: 61 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20  alize access.** 
b220: 74 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  to [database con
b230: 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70  nections] and [p
b240: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
b250: 74 73 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a  ts] so that the.
b260: 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69  ** application i
b270: 73 20 66 72 65 65 20 74 6f 20 75 73 65 20 74 68  s free to use th
b280: 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65  e same [database
b290: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20   connection] or 
b2a0: 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65  the.** same [pre
b2b0: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
b2c0: 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68   in different th
b2d0: 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d  reads at the sam
b2e0: 65 20 74 69 6d 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a  e time.</dd>.**.
b2f0: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
b300: 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e  NFIG_MALLOC</dt>
b310: 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74  .** <dd>This opt
b320: 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
b330: 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
b340: 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  h is a pointer t
b350: 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65  o an.** instance
b360: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
b370: 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74  _mem_methods] st
b380: 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 61 72  ructure.  The ar
b390: 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 63 73  gument specifics
b3a0: 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20  .** alternative 
b3b0: 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79  low-level memory
b3c0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
b3d0: 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 20  ines to be used 
b3e0: 69 6e 20 70 6c 61 63 65 0a 2a 2a 20 74 68 65 20  in place.** the 
b3f0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
b400: 6e 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74  n routines built
b410: 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 3c 2f 64   into SQLite.</d
b420: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
b430: 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
b440: 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LLOC</dt>.** <dd
b450: 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  >This option tak
b460: 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
b470: 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
b480: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a  pointer to an.**
b490: 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
b4a0: 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
b4b0: 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
b4c0: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
b4d0: 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  mem_methods].** 
b4e0: 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c  structure is fil
b4f0: 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72  led with the cur
b500: 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d  rently defined m
b510: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
b520: 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 54 68   routines..** Th
b530: 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65  is option can be
b540: 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61   used to overloa
b550: 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 65  d the default me
b560: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  mory allocation.
b570: 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68  ** routines with
b580: 20 61 20 77 72 61 70 70 65 72 20 74 68 61 74 20   a wrapper that 
b590: 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f  simulations memo
b5a0: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61  ry allocation fa
b5b0: 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63  ilure or.** trac
b5c0: 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c  ks memory usage,
b5d0: 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 3c 2f 64   for example.</d
b5e0: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
b5f0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
b600: 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ATUS</dt>.** <dd
b610: 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  >This option tak
b620: 65 73 20 73 69 6e 67 6c 65 20 62 6f 6f 6c 65 61  es single boolea
b630: 6e 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  n argument which
b640: 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61   enables or disa
b650: 62 6c 65 73 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c  bles.** the coll
b660: 65 63 74 69 6f 6e 20 6f 66 20 6d 65 6d 6f 72 79  ection of memory
b670: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74   allocation stat
b680: 69 73 74 69 63 73 2e 20 20 57 68 65 6e 20 64 69  istics.  When di
b690: 73 61 62 6c 65 64 2c 20 74 68 65 0a 2a 2a 20 66  sabled, the.** f
b6a0: 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65 20  ollowing SQLite 
b6b0: 69 6e 74 65 72 66 61 63 65 73 20 62 65 63 6f 6d  interfaces becom
b6c0: 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61  e non-operationa
b6d0: 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20  l:.**   <ul>.** 
b6e0: 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f    <li> [sqlite3_
b6f0: 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a  memory_used()].*
b700: 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65  *   <li> [sqlite
b710: 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
b720: 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20  er()].**   <li> 
b730: 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65  [sqlite3_soft_he
b740: 61 70 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 20  ap_limit()].**  
b750: 20 3c 6c 69 3e 20 73 71 6c 69 74 65 33 5f 6d 65   <li> sqlite3_me
b760: 6d 6f 72 79 5f 73 74 61 74 75 73 28 29 0a 2a 2a  mory_status().**
b770: 20 20 20 3c 2f 75 6c 3e 0a 2a 2a 20 3c 2f 64 64     </ul>.** </dd
b780: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
b790: 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
b7a0: 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
b7b0: 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66  is option specif
b7c0: 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d  ies a static mem
b7d0: 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74 20  ory buffer that 
b7e0: 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66  SQLite can use f
b7f0: 6f 72 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65  or.** scratch me
b800: 6d 6f 72 79 2e 20 20 54 68 65 72 65 20 61 72 65  mory.  There are
b810: 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73   three arguments
b820: 3a 20 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20  :  A pointer to 
b830: 74 68 65 20 6d 65 6d 6f 72 79 2c 20 74 68 65 0a  the memory, the.
b840: 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20  ** size of each 
b850: 73 63 72 61 74 63 68 20 62 75 66 66 65 72 20 28  scratch buffer (
b860: 73 7a 29 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d  sz), and the num
b870: 62 65 72 20 6f 66 20 62 75 66 66 65 72 73 20 28  ber of buffers (
b880: 4e 29 2e 20 20 54 68 65 20 73 7a 0a 2a 2a 20 61  N).  The sz.** a
b890: 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20  rgument must be 
b8a0: 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 31 36  a multiple of 16
b8b0: 2e 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 61  . The first.** a
b8c0: 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70  rgument should p
b8d0: 6f 69 6e 74 20 74 6f 20 61 6e 20 61 6c 6c 6f 63  oint to an alloc
b8e0: 61 74 69 6f 6e 20 6f 66 20 61 74 20 6c 65 61 73  ation of at leas
b8f0: 74 20 28 73 7a 2b 34 29 2a 4e 20 62 79 74 65 73  t (sz+4)*N bytes
b900: 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 53   of memory..** S
b910: 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 6e  QLite will use n
b920: 6f 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20  o more than one 
b930: 73 63 72 61 74 63 68 20 62 75 66 66 65 72 20 61  scratch buffer a
b940: 74 20 6f 6e 63 65 20 70 65 72 20 74 68 72 65 61  t once per threa
b950: 64 2c 20 73 6f 0a 2a 2a 20 4e 20 73 68 6f 75 6c  d, so.** N shoul
b960: 64 20 62 65 20 73 65 74 20 74 6f 20 74 68 65 20  d be set to the 
b970: 65 78 70 65 63 74 65 64 20 6d 61 78 69 6d 75 6d  expected maximum
b980: 20 6e 75 6d 62 65 72 20 6f 66 20 74 68 72 65 61   number of threa
b990: 64 73 2e 20 20 54 68 65 20 73 7a 20 0a 2a 2a 20  ds.  The sz .** 
b9a0: 70 61 72 61 6d 65 74 65 72 20 73 68 6f 75 6c 64  parameter should
b9b0: 20 62 65 20 36 20 74 69 6d 65 73 20 74 68 65 20   be 6 times the 
b9c0: 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67  size of the larg
b9d0: 65 73 74 20 64 61 74 61 62 61 73 65 20 70 61 67  est database pag
b9e0: 65 20 73 69 7a 65 2e 0a 2a 2a 20 53 63 72 61 74  e size..** Scrat
b9f0: 63 68 20 62 75 66 66 65 72 73 20 61 72 65 20 75  ch buffers are u
ba00: 73 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74  sed as part of t
ba10: 68 65 20 62 74 72 65 65 20 62 61 6c 61 6e 63 65  he btree balance
ba20: 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 49 66 0a   operation.  If.
ba30: 2a 2a 20 54 68 65 20 62 74 72 65 65 20 62 61 6c  ** The btree bal
ba40: 61 6e 63 65 72 20 6e 65 65 64 73 20 61 64 64 69  ancer needs addi
ba50: 74 69 6f 6e 61 6c 20 6d 65 6d 6f 72 79 20 62 65  tional memory be
ba60: 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f  yond what is pro
ba70: 76 69 64 65 64 20 62 79 0a 2a 2a 20 73 63 72 61  vided by.** scra
ba80: 74 63 68 20 62 75 66 66 65 72 73 20 6f 72 20 69  tch buffers or i
ba90: 66 20 6e 6f 20 73 63 72 61 74 63 68 20 62 75 66  f no scratch buf
baa0: 66 65 72 20 73 70 61 63 65 20 69 73 20 73 70 65  fer space is spe
bab0: 63 69 66 69 65 64 2c 20 74 68 65 6e 20 53 51 4c  cified, then SQL
bac0: 69 74 65 0a 2a 2a 20 67 6f 65 73 20 74 6f 20 5b  ite.** goes to [
bad0: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
bae0: 5d 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20  ] to obtain the 
baf0: 6d 65 6d 6f 72 79 20 69 74 20 6e 65 65 64 73 2e  memory it needs.
bb00: 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .** </dd>.**.** 
bb10: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
bb20: 47 5f 50 41 47 45 43 41 43 48 45 3c 2f 64 74 3e  G_PAGECACHE</dt>
bb30: 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74  .** <dd>This opt
bb40: 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20  ion specifies a 
bb50: 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75  static memory bu
bb60: 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65  ffer that SQLite
bb70: 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20   can use for.** 
bb80: 74 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67  the database pag
bb90: 65 20 63 61 63 68 65 2e 20 20 54 68 65 72 65 20  e cache.  There 
bba0: 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65  are three argume
bbb0: 6e 74 73 3a 0a 2a 2a 20 41 20 70 6f 69 6e 74 65  nts:.** A pointe
bbc0: 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c  r to the memory,
bbd0: 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20   the.** size of 
bbe0: 65 61 63 68 20 70 61 67 65 20 62 75 66 66 65 72  each page buffer
bbf0: 20 28 73 7a 29 2c 20 61 6e 64 20 74 68 65 20 6e   (sz), and the n
bc00: 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73 20 28  umber of pages (
bc10: 4e 29 2e 20 20 54 68 65 20 73 7a 0a 2a 2a 20 61  N).  The sz.** a
bc20: 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20  rgument must be 
bc30: 61 20 70 6f 77 65 72 20 6f 66 20 74 77 6f 20 62  a power of two b
bc40: 65 74 77 65 65 6e 20 35 31 32 20 61 6e 64 20 33  etween 512 and 3
bc50: 32 37 36 38 2e 20 20 54 68 65 20 66 69 72 73 74  2768.  The first
bc60: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f  .** argument sho
bc70: 75 6c 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20  uld point to an 
bc80: 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61 74  allocation of at
bc90: 20 6c 65 61 73 74 20 28 73 7a 2b 34 29 2a 4e 20   least (sz+4)*N 
bca0: 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e  bytes of memory.
bcb0: 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  .** SQLite will 
bcc0: 75 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70  use the memory p
bcd0: 72 6f 76 69 64 65 64 20 62 79 20 74 68 65 20 66  rovided by the f
bce0: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
bcf0: 20 73 61 74 69 73 66 79 0a 2a 2a 20 69 74 73 20   satisfy.** its 
bd00: 6d 65 6d 6f 72 79 20 6e 65 65 64 73 20 66 6f 72  memory needs for
bd10: 20 74 68 65 20 66 69 72 73 74 20 4e 20 70 61 67   the first N pag
bd20: 65 73 20 74 68 61 74 20 69 74 20 61 64 64 73 20  es that it adds 
bd30: 74 6f 20 63 61 63 68 65 2e 20 20 49 66 20 0a 2a  to cache.  If .*
bd40: 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 70 61 67  * additional pag
bd50: 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 69  e cache memory i
bd60: 73 20 6e 65 65 64 65 64 20 62 65 79 6f 6e 64 20  s needed beyond 
bd70: 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64  what is provided
bd80: 20 62 79 0a 2a 2a 20 74 68 69 73 20 6f 70 74 69   by.** this opti
bd90: 6f 6e 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  on, then SQLite 
bda0: 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  goes to [sqlite3
bdb0: 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f 72 20 74  _malloc()] for t
bdc0: 68 65 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  he additional.**
bdd0: 20 73 74 6f 72 61 67 65 20 73 70 61 63 65 2e 0a   storage space..
bde0: 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  ** </dd>.**.** <
bdf0: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
be00: 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  _HEAP</dt>.** <d
be10: 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70  d>This option sp
be20: 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63  ecifies a static
be30: 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74   memory buffer t
be40: 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  hat SQLite will 
be50: 75 73 65 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f  use.** for all o
be60: 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65  f its dynamic me
be70: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
be80: 6e 65 65 64 73 20 62 65 79 6f 6e 64 20 74 68 6f  needs beyond tho
be90: 73 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 66  se provided.** f
bea0: 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f  or by [SQLITE_CO
beb0: 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 20 61 6e  NFIG_SCRATCH] an
bec0: 64 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  d [SQLITE_CONFIG
bed0: 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20  _PAGECACHE]..** 
bee0: 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20  There are three 
bef0: 61 72 67 75 6d 65 6e 74 73 3a 20 41 20 70 6f 69  arguments: A poi
bf00: 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f  nter to the memo
bf10: 72 79 2c 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ry, the number o
bf20: 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68  f.** bytes in th
bf30: 65 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 2c  e memory buffer,
bf40: 20 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d   and the minimum
bf50: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65   allocation size
bf60: 2e 20 20 57 68 65 6e 0a 2a 2a 20 74 68 69 73 20  .  When.** this 
bf70: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
bf80: 74 69 6f 6e 20 69 73 20 75 73 65 64 2c 20 53 51  tion is used, SQ
bf90: 4c 69 74 65 20 6e 65 76 65 72 20 63 61 6c 6c 73  Lite never calls
bfa0: 20 74 68 65 20 73 79 73 74 65 6d 0a 2a 2a 20 6d   the system.** m
bfb0: 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e  alloc() implemen
bfc0: 74 61 74 69 6f 6e 20 62 75 74 20 69 6e 73 74 65  tation but inste
bfd0: 61 64 20 75 73 65 73 20 74 68 65 20 73 75 70 70  ad uses the supp
bfe0: 6c 69 65 64 20 6d 65 6d 6f 72 79 20 62 75 66 66  lied memory buff
bff0: 65 72 0a 2a 2a 20 74 6f 20 73 61 74 69 73 66 79  er.** to satisfy
c000: 20 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 6d 61   all [sqlite3_ma
c010: 6c 6c 6f 63 28 29 5d 20 72 65 71 75 65 73 74 73  lloc()] requests
c020: 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ..** </dd>.**.**
c030: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
c040: 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a  IG_MUTEX</dt>.**
c050: 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e   <dd>This option
c060: 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
c070: 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
c080: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
c090: 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66  n.** instance of
c0a0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
c0b0: 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  tex_methods] str
c0c0: 75 63 74 75 72 65 2e 20 20 54 68 65 20 61 72 67  ucture.  The arg
c0d0: 75 6d 65 6e 74 20 73 70 65 63 69 66 69 63 73 0a  ument specifics.
c0e0: 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c  ** alternative l
c0f0: 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20 72  ow-level mutex r
c100: 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73  outines to be us
c110: 65 64 20 69 6e 20 70 6c 61 63 65 0a 2a 2a 20 74  ed in place.** t
c120: 68 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65  he mutex routine
c130: 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c  s built into SQL
c140: 69 74 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ite.</dd>.**.** 
c150: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
c160: 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e  G_GETMALLOC</dt>
c170: 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74  .** <dd>This opt
c180: 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
c190: 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
c1a0: 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  h is a pointer t
c1b0: 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65  o an.** instance
c1c0: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
c1d0: 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20  _mutex_methods] 
c1e0: 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 0a  structure.  The.
c1f0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ** [sqlite3_mute
c200: 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74  x_methods].** st
c210: 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65  ructure is fille
c220: 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65  d with the curre
c230: 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75 74  ntly defined mut
c240: 65 78 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20  ex routines..** 
c250: 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20  This option can 
c260: 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c  be used to overl
c270: 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20  oad the default 
c280: 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e  mutex allocation
c290: 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74  .** routines wit
c2a0: 68 20 61 20 77 72 61 70 70 65 72 20 75 73 65 64  h a wrapper used
c2b0: 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 78 20   to track mutex 
c2c0: 75 73 61 67 65 20 66 6f 72 20 70 65 72 66 6f 72  usage for perfor
c2d0: 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69  mance.** profili
c2e0: 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c 20 66  ng or testing, f
c2f0: 6f 72 20 65 78 61 6d 70 6c 65 2e 3c 2f 64 64 3e  or example.</dd>
c300: 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 20  .**.** </dl>.*/ 
c310: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c320: 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
c330: 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a  EAD  1  /* nil *
c340: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
c350: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
c360: 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20  EAD   2  /* nil 
c370: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
c380: 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49  E_CONFIG_SERIALI
c390: 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c  ZED    3  /* nil
c3a0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
c3b0: 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
c3c0: 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71          4  /* sq
c3d0: 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
c3e0: 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s* */.#define SQ
c3f0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
c400: 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a 20  ALLOC     5  /* 
c410: 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
c420: 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ods* */.#define 
c430: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
c440: 52 41 54 43 48 20 20 20 20 20 20 20 36 20 20 2f  RATCH       6  /
c450: 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c  * void*, int sz,
c460: 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e   int N */.#defin
c470: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
c480: 50 41 47 45 43 41 43 48 45 20 20 20 20 20 37 20  PAGECACHE     7 
c490: 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73   /* void*, int s
c4a0: 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66  z, int N */.#def
c4b0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
c4c0: 47 5f 48 45 41 50 20 20 20 20 20 20 20 20 20 20  G_HEAP          
c4d0: 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74  8  /* void*, int
c4e0: 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20   nByte, int min 
c4f0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
c500: 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
c510: 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f  US     9  /* boo
c520: 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  lean */.#define 
c530: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
c540: 54 45 58 20 20 20 20 20 20 20 20 31 30 20 20 2f  TEX        10  /
c550: 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  * sqlite3_mutex_
c560: 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66  methods* */.#def
c570: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
c580: 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20 31  G_GETMUTEX     1
c590: 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75  1  /* sqlite3_mu
c5a0: 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  tex_methods* */.
c5b0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
c5c0: 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61  : Enable Or Disa
c5d0: 62 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65 73  ble Extended Res
c5e0: 75 6c 74 20 43 6f 64 65 73 20 7b 46 31 32 32 30  ult Codes {F1220
c5f0: 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  0}.**.** The sql
c600: 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65  ite3_extended_re
c610: 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f 75  sult_codes() rou
c620: 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20  tine enables or 
c630: 64 69 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20  disables the.** 
c640: 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45  [SQLITE_IOERR_RE
c650: 41 44 20 7c 20 65 78 74 65 6e 64 65 64 20 72 65  AD | extended re
c660: 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74  sult codes] feat
c670: 75 72 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ure of SQLite..*
c680: 2a 20 54 68 65 20 65 78 74 65 6e 64 65 64 20 72  * The extended r
c690: 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20  esult codes are 
c6a0: 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
c6b0: 75 6c 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63  ult for historic
c6c0: 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c  al.** compatibil
c6d0: 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ity..**.** INVAR
c6e0: 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31  IANTS:.**.** {F1
c6f0: 32 32 30 31 7d 20 45 61 63 68 20 6e 65 77 20 5b  2201} Each new [
c700: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
c710: 69 6f 6e 5d 20 73 68 61 6c 6c 20 68 61 76 65 20  ion] shall have 
c720: 74 68 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  the .**         
c730: 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
c740: 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65  t codes] feature
c750: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 69 73  .**          dis
c760: 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
c770: 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 30 32 7d  ..**.** {F12202}
c780: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 78   The [sqlite3_ex
c790: 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f  tended_result_co
c7a0: 64 65 73 28 44 2c 46 29 5d 20 69 6e 74 65 72 66  des(D,F)] interf
c7b0: 61 63 65 20 73 68 61 6c 6c 20 65 6e 61 62 6c 65  ace shall enable
c7c0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 65 78  .**          [ex
c7d0: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
c7e0: 64 65 73 5d 20 66 6f 72 20 74 68 65 20 0a 2a 2a  des] for the .**
c7f0: 20 20 20 20 20 20 20 20 20 20 5b 64 61 74 61 62            [datab
c800: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
c810: 44 20 69 66 20 74 68 65 20 46 20 70 61 72 61 6d  D if the F param
c820: 65 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  eter.**         
c830: 20 69 73 20 74 72 75 65 2c 20 6f 72 20 64 69 73   is true, or dis
c840: 61 62 6c 65 20 74 68 65 6d 20 69 66 20 46 20 69  able them if F i
c850: 73 20 66 61 6c 73 65 2e 0a 2a 2f 0a 69 6e 74 20  s false..*/.int 
c860: 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
c870: 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 73 71  _result_codes(sq
c880: 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66  lite3*, int onof
c890: 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  f);../*.** CAPI3
c8a0: 52 45 46 3a 20 4c 61 73 74 20 49 6e 73 65 72 74  REF: Last Insert
c8b0: 20 52 6f 77 69 64 20 7b 46 31 32 32 32 30 7d 0a   Rowid {F12220}.
c8c0: 2a 2a 0a 2a 2a 20 45 61 63 68 20 65 6e 74 72 79  **.** Each entry
c8d0: 20 69 6e 20 61 6e 20 53 51 4c 69 74 65 20 74 61   in an SQLite ta
c8e0: 62 6c 65 20 68 61 73 20 61 20 75 6e 69 71 75 65  ble has a unique
c8f0: 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a   64-bit signed.*
c900: 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20 63 61  * integer key ca
c910: 6c 6c 65 64 20 74 68 65 20 22 72 6f 77 69 64 22  lled the "rowid"
c920: 2e 20 54 68 65 20 72 6f 77 69 64 20 69 73 20 61  . The rowid is a
c930: 6c 77 61 79 73 20 61 76 61 69 6c 61 62 6c 65 0a  lways available.
c940: 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65 63 6c 61  ** as an undecla
c950: 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64  red column named
c960: 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20   ROWID, OID, or 
c970: 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20  _ROWID_ as long 
c980: 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65  as those.** name
c990: 73 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75  s are not also u
c9a0: 73 65 64 20 62 79 20 65 78 70 6c 69 63 69 74 6c  sed by explicitl
c9b0: 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d  y declared colum
c9c0: 6e 73 2e 20 49 66 0a 2a 2a 20 74 68 65 20 74 61  ns. If.** the ta
c9d0: 62 6c 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e  ble has a column
c9e0: 20 6f 66 20 74 79 70 65 20 49 4e 54 45 47 45 52   of type INTEGER
c9f0: 20 50 52 49 4d 41 52 59 20 4b 45 59 20 74 68 65   PRIMARY KEY the
ca00: 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a  n that column.**
ca10: 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61   is another alia
ca20: 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e  s for the rowid.
ca30: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
ca40: 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
ca50: 72 6f 77 69 64 20 6f 66 20 74 68 65 20 6d 6f 73  rowid of the mos
ca60: 74 20 72 65 63 65 6e 74 0a 2a 2a 20 73 75 63 63  t recent.** succ
ca70: 65 73 73 66 75 6c 20 49 4e 53 45 52 54 20 69 6e  essful INSERT in
ca80: 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20  to the database 
ca90: 66 72 6f 6d 20 74 68 65 20 64 61 74 61 62 61 73  from the databas
caa0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
cab0: 73 68 6f 77 6e 20 69 6e 20 74 68 65 20 66 69 72  shown in the fir
cac0: 73 74 20 61 72 67 75 6d 65 6e 74 2e 20 20 49 66  st argument.  If
cad0: 20 6e 6f 20 73 75 63 63 65 73 73 66 75 6c 20 69   no successful i
cae0: 6e 73 65 72 74 73 0a 2a 2a 20 68 61 76 65 20 65  nserts.** have e
caf0: 76 65 72 20 6f 63 63 75 72 72 65 64 20 6f 6e 20  ver occurred on 
cb00: 74 68 69 73 20 64 61 74 61 62 61 73 65 20 63 6f  this database co
cb10: 6e 6e 65 63 74 69 6f 6e 2c 20 7a 65 72 6f 20 69  nnection, zero i
cb20: 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
cb30: 2a 20 49 66 20 61 6e 20 49 4e 53 45 52 54 20 6f  * If an INSERT o
cb40: 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 20 74  ccurs within a t
cb50: 72 69 67 67 65 72 2c 20 74 68 65 6e 20 74 68 65  rigger, then the
cb60: 20 72 6f 77 69 64 20 6f 66 20 74 68 65 0a 2a 2a   rowid of the.**
cb70: 20 69 6e 73 65 72 74 65 64 20 72 6f 77 20 69 73   inserted row is
cb80: 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69   returned by thi
cb90: 73 20 72 6f 75 74 69 6e 65 20 61 73 20 6c 6f 6e  s routine as lon
cba0: 67 20 61 73 20 74 68 65 20 74 72 69 67 67 65 72  g as the trigger
cbb0: 0a 2a 2a 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20  .** is running. 
cbc0: 20 42 75 74 20 6f 6e 63 65 20 74 68 65 20 74 72   But once the tr
cbd0: 69 67 67 65 72 20 74 65 72 6d 69 6e 61 74 65 73  igger terminates
cbe0: 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  , the value retu
cbf0: 72 6e 65 64 0a 2a 2a 20 62 79 20 74 68 69 73 20  rned.** by this 
cc00: 72 6f 75 74 69 6e 65 20 72 65 76 65 72 74 73 20  routine reverts 
cc10: 74 6f 20 74 68 65 20 6c 61 73 74 20 76 61 6c 75  to the last valu
cc20: 65 20 69 6e 73 65 72 74 65 64 20 62 65 66 6f 72  e inserted befor
cc30: 65 20 74 68 65 0a 2a 2a 20 74 72 69 67 67 65 72  e the.** trigger
cc40: 20 66 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 6e   fired..**.** An
cc50: 20 49 4e 53 45 52 54 20 74 68 61 74 20 66 61 69   INSERT that fai
cc60: 6c 73 20 64 75 65 20 74 6f 20 61 20 63 6f 6e 73  ls due to a cons
cc70: 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e  traint violation
cc80: 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63   is not a.** suc
cc90: 63 65 73 73 66 75 6c 20 69 6e 73 65 72 74 20 61  cessful insert a
cca0: 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e  nd does not chan
ccb0: 67 65 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  ge the value ret
ccc0: 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a 2a 2a  urned by this.**
ccd0: 20 72 6f 75 74 69 6e 65 2e 20 20 54 68 75 73 20   routine.  Thus 
cce0: 49 4e 53 45 52 54 20 4f 52 20 46 41 49 4c 2c 20  INSERT OR FAIL, 
ccf0: 49 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f 52 45  INSERT OR IGNORE
cd00: 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c  , INSERT OR ROLL
cd10: 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53  BACK,.** and INS
cd20: 45 52 54 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b  ERT OR ABORT mak
cd30: 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f 20  e no changes to 
cd40: 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
cd50: 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74   of this.** rout
cd60: 69 6e 65 20 77 68 65 6e 20 74 68 65 69 72 20 69  ine when their i
cd70: 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20  nsertion fails. 
cd80: 20 57 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 20   When INSERT OR 
cd90: 52 45 50 4c 41 43 45 20 0a 2a 2a 20 65 6e 63 6f  REPLACE .** enco
cda0: 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 74 72 61  unters a constra
cdb0: 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69  int violation, i
cdc0: 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e  t does not fail.
cdd0: 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20    The.** INSERT 
cde0: 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d  continues to com
cdf0: 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 20 64 65  pletion after de
ce00: 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 68 61 74  leting rows that
ce10: 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 65 20 63   caused.** the c
ce20: 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f 62 6c 65  onstraint proble
ce30: 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f 52 20 52  m so INSERT OR R
ce40: 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77 61  EPLACE will alwa
ce50: 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65  ys change.** the
ce60: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
ce70: 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e   this interface.
ce80: 20 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 74 68 65 20   .**.** For the 
ce90: 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73  purposes of this
cea0: 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 69 6e 73   routine, an ins
ceb0: 65 72 74 20 69 73 20 63 6f 6e 73 69 64 65 72 65  ert is considere
cec0: 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65  d to.** be succe
ced0: 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69 74  ssful even if it
cee0: 20 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c 79   is subsequently
cef0: 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a   rolled back..**
cf00: 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
cf10: 2a 2a 0a 2a 2a 20 7b 46 31 32 32 32 31 7d 20 54  **.** {F12221} T
cf20: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74  he [sqlite3_last
cf30: 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d  _insert_rowid()]
cf40: 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
cf50: 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
cf60: 20 20 72 6f 77 69 64 20 6f 66 20 74 68 65 20 6d    rowid of the m
cf70: 6f 73 74 20 72 65 63 65 6e 74 20 73 75 63 63 65  ost recent succe
cf80: 73 73 66 75 6c 20 69 6e 73 65 72 74 20 64 6f 6e  ssful insert don
cf90: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 6e  e.**          on
cfa0: 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
cfb0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 61 6e  se connection an
cfc0: 64 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d  d within the sam
cfd0: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  e.**          or
cfe0: 20 68 69 67 68 65 72 20 6c 65 76 65 6c 20 74 72   higher level tr
cff0: 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2c 20 6f  igger context, o
d000: 72 20 7a 65 72 6f 20 69 66 20 74 68 65 72 65 20  r zero if there 
d010: 68 61 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  have.**         
d020: 20 62 65 65 6e 20 6e 6f 20 71 75 61 6c 69 66 79   been no qualify
d030: 69 6e 67 20 69 6e 73 65 72 74 73 2e 0a 2a 2a 0a  ing inserts..**.
d040: 2a 2a 20 7b 46 31 32 32 32 33 7d 20 54 68 65 20  ** {F12223} The 
d050: 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e  [sqlite3_last_in
d060: 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 66 75  sert_rowid()] fu
d070: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 0a 2a  nction returns.*
d080: 2a 20 20 20 20 20 20 20 20 20 20 73 61 6d 65 20  *          same 
d090: 76 61 6c 75 65 20 77 68 65 6e 20 63 61 6c 6c 65  value when calle
d0a0: 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
d0b0: 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 0a  trigger context.
d0c0: 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6d 6d 65  **          imme
d0d0: 64 69 61 74 65 6c 79 20 62 65 66 6f 72 65 20 61  diately before a
d0e0: 6e 64 20 61 66 74 65 72 20 61 20 52 4f 4c 4c 42  nd after a ROLLB
d0f0: 41 43 4b 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49 54  ACK..**.** LIMIT
d100: 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 55  ATIONS:.**.** {U
d110: 31 32 32 33 32 7d 20 49 66 20 61 20 73 65 70 61  12232} If a sepa
d120: 72 61 74 65 20 74 68 72 65 61 64 20 64 6f 65 73  rate thread does
d130: 20 61 20 6e 65 77 20 69 6e 73 65 72 74 20 6f 6e   a new insert on
d140: 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20   the same.**    
d150: 20 20 20 20 20 20 64 61 74 61 62 61 73 65 20 63        database c
d160: 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20  onnection while 
d170: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73  the [sqlite3_las
d180: 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29  t_insert_rowid()
d190: 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 75  ].**          fu
d1a0: 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
d1b0: 67 20 61 6e 64 20 74 68 75 73 20 63 68 61 6e 67  g and thus chang
d1c0: 65 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65  es the last inse
d1d0: 72 74 20 72 6f 77 69 64 2c 0a 2a 2a 20 20 20 20  rt rowid,.**    
d1e0: 20 20 20 20 20 20 74 68 65 6e 20 74 68 65 20 76        then the v
d1f0: 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
d200: 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69   [sqlite3_last_i
d210: 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 69  nsert_rowid()] i
d220: 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 75 6e  s.**          un
d230: 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20  predictable and 
d240: 6d 69 67 68 74 20 6e 6f 74 20 65 71 75 61 6c 20  might not equal 
d250: 65 69 74 68 65 72 20 74 68 65 20 6f 6c 64 20 6f  either the old o
d260: 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20 20 20 20  r the new.**    
d270: 20 20 20 20 20 20 6c 61 73 74 20 69 6e 73 65 72        last inser
d280: 74 20 72 6f 77 69 64 2e 0a 2a 2f 0a 73 71 6c 69  t rowid..*/.sqli
d290: 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
d2a0: 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
d2b0: 77 69 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  wid(sqlite3*);..
d2c0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
d2d0: 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62 65 72  Count The Number
d2e0: 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65   Of Rows Modifie
d2f0: 64 20 7b 46 31 32 32 34 30 7d 0a 2a 2a 0a 2a 2a  d {F12240}.**.**
d300: 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72   This function r
d310: 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
d320: 72 20 6f 66 20 64 61 74 61 62 61 73 65 20 72 6f  r of database ro
d330: 77 73 20 74 68 61 74 20 77 65 72 65 20 63 68 61  ws that were cha
d340: 6e 67 65 64 0a 2a 2a 20 6f 72 20 69 6e 73 65 72  nged.** or inser
d350: 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 20 62  ted or deleted b
d360: 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  y the most recen
d370: 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 53 51  tly completed SQ
d380: 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 6f  L statement.** o
d390: 6e 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  n the connection
d3a0: 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
d3b0: 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
d3c0: 72 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 63 68 61 6e  r.  Only.** chan
d3d0: 67 65 73 20 74 68 61 74 20 61 72 65 20 64 69 72  ges that are dir
d3e0: 65 63 74 6c 79 20 73 70 65 63 69 66 69 65 64 20  ectly specified 
d3f0: 62 79 20 74 68 65 20 49 4e 53 45 52 54 2c 20 55  by the INSERT, U
d400: 50 44 41 54 45 2c 20 6f 72 0a 2a 2a 20 44 45 4c  PDATE, or.** DEL
d410: 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 61 72  ETE statement ar
d420: 65 20 63 6f 75 6e 74 65 64 2e 20 20 41 75 78 69  e counted.  Auxi
d430: 6c 69 61 72 79 20 63 68 61 6e 67 65 73 20 63 61  liary changes ca
d440: 75 73 65 64 20 62 79 0a 2a 2a 20 74 72 69 67 67  used by.** trigg
d450: 65 72 73 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e  ers are not coun
d460: 74 65 64 2e 20 55 73 65 20 74 68 65 20 5b 73 71  ted. Use the [sq
d470: 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
d480: 67 65 73 28 29 5d 20 66 75 6e 63 74 69 6f 6e 0a  ges()] function.
d490: 2a 2a 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74  ** to find the t
d4a0: 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 63  otal number of c
d4b0: 68 61 6e 67 65 73 20 69 6e 63 6c 75 64 69 6e 67  hanges including
d4c0: 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20   changes caused 
d4d0: 62 79 20 74 72 69 67 67 65 72 73 2e 0a 2a 2a 0a  by triggers..**.
d4e0: 2a 2a 20 41 20 22 72 6f 77 20 63 68 61 6e 67 65  ** A "row change
d4f0: 22 20 69 73 20 61 20 63 68 61 6e 67 65 20 74 6f  " is a change to
d500: 20 61 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66   a single row of
d510: 20 61 20 73 69 6e 67 6c 65 20 74 61 62 6c 65 0a   a single table.
d520: 2a 2a 20 63 61 75 73 65 64 20 62 79 20 61 6e 20  ** caused by an 
d530: 49 4e 53 45 52 54 2c 20 44 45 4c 45 54 45 2c 20  INSERT, DELETE, 
d540: 6f 72 20 55 50 44 41 54 45 20 73 74 61 74 65 6d  or UPDATE statem
d550: 65 6e 74 2e 20 20 52 6f 77 73 20 74 68 61 74 0a  ent.  Rows that.
d560: 2a 2a 20 61 72 65 20 63 68 61 6e 67 65 64 20 61  ** are changed a
d570: 73 20 73 69 64 65 20 65 66 66 65 63 74 73 20 6f  s side effects o
d580: 66 20 52 45 50 4c 41 43 45 20 63 6f 6e 73 74 72  f REPLACE constr
d590: 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 2c  aint resolution,
d5a0: 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20 41 42  .** rollback, AB
d5b0: 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20  ORT processing, 
d5c0: 44 52 4f 50 20 54 41 42 4c 45 2c 20 6f 72 20 62  DROP TABLE, or b
d5d0: 79 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 6d  y any other.** m
d5e0: 65 63 68 61 6e 69 73 6d 73 20 64 6f 20 6e 6f 74  echanisms do not
d5f0: 20 63 6f 75 6e 74 20 61 73 20 64 69 72 65 63 74   count as direct
d600: 20 72 6f 77 20 63 68 61 6e 67 65 73 2e 0a 2a 2a   row changes..**
d610: 0a 2a 2a 20 41 20 22 74 72 69 67 67 65 72 20 63  .** A "trigger c
d620: 6f 6e 74 65 78 74 22 20 69 73 20 61 20 73 63 6f  ontext" is a sco
d630: 70 65 20 6f 66 20 65 78 65 63 75 74 69 6f 6e 20  pe of execution 
d640: 74 68 61 74 20 62 65 67 69 6e 73 20 61 6e 64 0a  that begins and.
d650: 2a 2a 20 65 6e 64 73 20 77 69 74 68 20 74 68 65  ** ends with the
d660: 20 73 63 72 69 70 74 20 6f 66 20 61 20 74 72 69   script of a tri
d670: 67 67 65 72 2e 20 20 4d 6f 73 74 20 53 51 4c 20  gger.  Most SQL 
d680: 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 0a 2a  statements are.*
d690: 2a 20 65 76 61 6c 75 61 74 65 64 20 6f 75 74 73  * evaluated outs
d6a0: 69 64 65 20 6f 66 20 61 6e 79 20 74 72 69 67 67  ide of any trigg
d6b0: 65 72 2e 20 20 54 68 69 73 20 69 73 20 74 68 65  er.  This is the
d6c0: 20 22 74 6f 70 20 6c 65 76 65 6c 22 0a 2a 2a 20   "top level".** 
d6d0: 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e  trigger context.
d6e0: 20 20 49 66 20 61 20 74 72 69 67 67 65 72 20 66    If a trigger f
d6f0: 69 72 65 73 20 66 72 6f 6d 20 74 68 65 20 74 6f  ires from the to
d700: 70 20 6c 65 76 65 6c 2c 20 61 0a 2a 2a 20 6e 65  p level, a.** ne
d710: 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78  w trigger contex
d720: 74 20 69 73 20 65 6e 74 65 72 65 64 20 66 6f 72  t is entered for
d730: 20 74 68 65 20 64 75 72 61 74 69 6f 6e 20 6f 66   the duration of
d740: 20 74 68 61 74 20 6f 6e 65 0a 2a 2a 20 74 72 69   that one.** tri
d750: 67 67 65 72 2e 20 20 53 75 62 74 72 69 67 67 65  gger.  Subtrigge
d760: 72 73 20 63 72 65 61 74 65 20 73 75 62 63 6f 6e  rs create subcon
d770: 74 65 78 74 73 20 66 6f 72 20 74 68 65 69 72 20  texts for their 
d780: 64 75 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  duration..**.** 
d790: 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  Calling [sqlite3
d7a0: 5f 65 78 65 63 28 29 5d 20 6f 72 20 5b 73 71 6c  _exec()] or [sql
d7b0: 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65 63  ite3_step()] rec
d7c0: 75 72 73 69 76 65 6c 79 20 64 6f 65 73 0a 2a 2a  ursively does.**
d7d0: 20 6e 6f 74 20 63 72 65 61 74 65 20 61 20 6e 65   not create a ne
d7e0: 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78  w trigger contex
d7f0: 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75  t..**.** This fu
d800: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
d810: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 69 72  he number of dir
d820: 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73 20  ect row changes 
d830: 69 6e 20 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 72  in the.** most r
d840: 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50  ecent INSERT, UP
d850: 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 20  DATE, or DELETE 
d860: 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e  statement within
d870: 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 74 72 69   the same.** tri
d880: 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a  gger context..**
d890: 0a 2a 2a 20 53 6f 20 77 68 65 6e 20 63 61 6c 6c  .** So when call
d8a0: 65 64 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20  ed from the top 
d8b0: 6c 65 76 65 6c 2c 20 74 68 69 73 20 66 75 6e 63  level, this func
d8c0: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
d8d0: 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  .** number of ch
d8e0: 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73  anges in the mos
d8f0: 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c  t recent INSERT,
d900: 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45   UPDATE, or DELE
d910: 54 45 0a 2a 2a 20 74 68 61 74 20 61 6c 73 6f 20  TE.** that also 
d920: 6f 63 63 75 72 72 65 64 20 61 74 20 74 68 65 20  occurred at the 
d930: 74 6f 70 20 6c 65 76 65 6c 2e 0a 2a 2a 20 57 69  top level..** Wi
d940: 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66  thin the body of
d950: 20 61 20 74 72 69 67 67 65 72 2c 20 74 68 65 20   a trigger, the 
d960: 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
d970: 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 63  ) interface.** c
d980: 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 74 6f 20  an be called to 
d990: 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20  find the number 
d9a0: 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e  of.** changes in
d9b0: 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
d9c0: 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53  ly completed INS
d9d0: 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20  ERT, UPDATE, or 
d9e0: 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d  DELETE.** statem
d9f0: 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 62  ent within the b
da00: 6f 64 79 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ody of the same 
da10: 74 72 69 67 67 65 72 2e 0a 2a 2a 20 48 6f 77 65  trigger..** Howe
da20: 76 65 72 2c 20 74 68 65 20 6e 75 6d 62 65 72 20  ver, the number 
da30: 72 65 74 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f  returned does no
da40: 74 20 69 6e 63 6c 75 64 65 20 69 6e 20 63 68 61  t include in cha
da50: 6e 67 65 73 0a 2a 2a 20 63 61 75 73 65 64 20 62  nges.** caused b
da60: 79 20 73 75 62 74 72 69 67 67 65 72 73 20 73 69  y subtriggers si
da70: 6e 63 65 20 74 68 65 79 20 68 61 76 65 20 74 68  nce they have th
da80: 65 69 72 20 6f 77 6e 20 63 6f 6e 74 65 78 74 2e  eir own context.
da90: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6d  .**.** SQLite im
daa0: 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 63 6f 6d  plements the com
dab0: 6d 61 6e 64 20 22 44 45 4c 45 54 45 20 46 52 4f  mand "DELETE FRO
dac0: 4d 20 74 61 62 6c 65 22 20 77 69 74 68 6f 75 74  M table" without
dad0: 0a 2a 2a 20 61 20 57 48 45 52 45 20 63 6c 61 75  .** a WHERE clau
dae0: 73 65 20 62 79 20 64 72 6f 70 70 69 6e 67 20 61  se by dropping a
daf0: 6e 64 20 72 65 63 72 65 61 74 69 6e 67 20 74 68  nd recreating th
db00: 65 20 74 61 62 6c 65 2e 20 20 28 54 68 69 73 20  e table.  (This 
db10: 69 73 20 6d 75 63 68 0a 2a 2a 20 66 61 73 74 65  is much.** faste
db20: 72 20 74 68 61 6e 20 67 6f 69 6e 67 20 74 68 72  r than going thr
db30: 6f 75 67 68 20 61 6e 64 20 64 65 6c 65 74 69 6e  ough and deletin
db40: 67 20 69 6e 64 69 76 69 64 75 61 6c 20 65 6c 65  g individual ele
db50: 6d 65 6e 74 73 20 66 72 6f 6d 20 74 68 65 0a 2a  ments from the.*
db60: 2a 20 74 61 62 6c 65 2e 29 20 20 42 65 63 61 75  * table.)  Becau
db70: 73 65 20 6f 66 20 74 68 69 73 20 6f 70 74 69 6d  se of this optim
db80: 69 7a 61 74 69 6f 6e 2c 20 74 68 65 20 64 65 6c  ization, the del
db90: 65 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 22 44 45  etions in.** "DE
dba0: 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 22  LETE FROM table"
dbb0: 20 61 72 65 20 6e 6f 74 20 72 6f 77 20 63 68 61   are not row cha
dbc0: 6e 67 65 73 20 61 6e 64 20 77 69 6c 6c 20 6e 6f  nges and will no
dbd0: 74 20 62 65 20 63 6f 75 6e 74 65 64 0a 2a 2a 20  t be counted.** 
dbe0: 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  by the sqlite3_c
dbf0: 68 61 6e 67 65 73 28 29 20 6f 72 20 5b 73 71 6c  hanges() or [sql
dc00: 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
dc10: 65 73 28 29 5d 20 66 75 6e 63 74 69 6f 6e 73 2e  es()] functions.
dc20: 0a 2a 2a 20 54 6f 20 67 65 74 20 61 6e 20 61 63  .** To get an ac
dc30: 63 75 72 61 74 65 20 63 6f 75 6e 74 20 6f 66 20  curate count of 
dc40: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  the number of ro
dc50: 77 73 20 64 65 6c 65 74 65 64 2c 20 75 73 65 0a  ws deleted, use.
dc60: 2a 2a 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20  ** "DELETE FROM 
dc70: 74 61 62 6c 65 20 57 48 45 52 45 20 31 22 20 69  table WHERE 1" i
dc80: 6e 73 74 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e  nstead..**.** IN
dc90: 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
dca0: 7b 46 31 32 32 34 31 7d 20 54 68 65 20 5b 73 71  {F12241} The [sq
dcb0: 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d  lite3_changes()]
dcc0: 20 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20   function shall 
dcd0: 72 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65  return the numbe
dce0: 72 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20  r of.**         
dcf0: 20 72 6f 77 20 63 68 61 6e 67 65 73 20 63 61 75   row changes cau
dd00: 73 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20  sed by the most 
dd10: 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55  recent INSERT, U
dd20: 50 44 41 54 45 2c 0a 2a 2a 20 20 20 20 20 20 20  PDATE,.**       
dd30: 20 20 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61     or DELETE sta
dd40: 74 65 6d 65 6e 74 20 6f 6e 20 74 68 65 20 73 61  tement on the sa
dd50: 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
dd60: 65 63 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 20 20  ection and.**   
dd70: 20 20 20 20 20 20 20 77 69 74 68 69 6e 20 74 68         within th
dd80: 65 20 73 61 6d 65 20 6f 72 20 68 69 67 68 65 72  e same or higher
dd90: 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74   trigger context
dda0: 2c 20 6f 72 20 7a 65 72 6f 20 69 66 20 74 68 65  , or zero if the
ddb0: 72 65 20 68 61 76 65 0a 2a 2a 20 20 20 20 20 20  re have.**      
ddc0: 20 20 20 20 6e 6f 74 20 62 65 65 6e 20 61 6e 79      not been any
ddd0: 20 71 75 61 6c 69 66 79 69 6e 67 20 72 6f 77 20   qualifying row 
dde0: 63 68 61 6e 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b  changes..**.** {
ddf0: 46 31 32 32 34 33 7d 20 53 74 61 74 65 6d 65 6e  F12243} Statemen
de00: 74 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22  ts of the form "
de10: 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c  DELETE FROM tabl
de20: 65 6e 61 6d 65 22 20 77 69 74 68 20 6e 6f 0a 2a  ename" with no.*
de30: 2a 20 20 20 20 20 20 20 20 20 20 57 48 45 52 45  *          WHERE
de40: 20 63 6c 61 75 73 65 20 73 68 61 6c 6c 20 63 61   clause shall ca
de50: 75 73 65 20 73 75 62 73 65 71 75 65 6e 74 20 63  use subsequent c
de60: 61 6c 6c 73 20 74 6f 20 0a 2a 2a 20 20 20 20 20  alls to .**     
de70: 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 68       [sqlite3_ch
de80: 61 6e 67 65 73 28 29 5d 20 74 6f 20 72 65 74 75  anges()] to retu
de90: 72 6e 20 7a 65 72 6f 2c 20 72 65 67 61 72 64 6c  rn zero, regardl
dea0: 65 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20  ess of the.**   
deb0: 20 20 20 20 20 20 20 6e 75 6d 62 65 72 20 6f 66         number of
dec0: 20 72 6f 77 73 20 6f 72 69 67 69 6e 61 6c 6c 79   rows originally
ded0: 20 69 6e 20 74 68 65 20 74 61 62 6c 65 2e 0a 2a   in the table..*
dee0: 2a 0a 2a 2a 20 4c 49 4d 49 54 41 54 49 4f 4e 53  *.** LIMITATIONS
def0: 3a 0a 2a 2a 0a 2a 2a 20 7b 55 31 32 32 35 32 7d  :.**.** {U12252}
df00: 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74   If a separate t
df10: 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e  hread makes chan
df20: 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  ges on the same 
df30: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
df40: 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ion.**          
df50: 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63  while [sqlite3_c
df60: 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e  hanges()] is run
df70: 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61  ning then the va
df80: 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  lue returned.** 
df90: 20 20 20 20 20 20 20 20 20 69 73 20 75 6e 70 72           is unpr
dfa0: 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f  edictable and no
dfb0: 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f  t meaningful..*/
dfc0: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61  .int sqlite3_cha
dfd0: 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a  nges(sqlite3*);.
dfe0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
dff0: 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66   Total Number Of
e000: 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 20 7b   Rows Modified {
e010: 46 31 32 32 36 30 7d 0a 2a 2a 2a 0a 2a 2a 20 54  F12260}.***.** T
e020: 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  his function ret
e030: 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
e040: 6f 66 20 72 6f 77 20 63 68 61 6e 67 65 73 20 63  of row changes c
e050: 61 75 73 65 64 0a 2a 2a 20 62 79 20 49 4e 53 45  aused.** by INSE
e060: 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45  RT, UPDATE or DE
e070: 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 73 20  LETE statements 
e080: 73 69 6e 63 65 20 74 68 65 20 64 61 74 61 62 61  since the databa
e090: 73 65 20 68 61 6e 64 6c 65 0a 2a 2a 20 77 61 73  se handle.** was
e0a0: 20 6f 70 65 6e 65 64 2e 20 20 54 68 65 20 63 6f   opened.  The co
e0b0: 75 6e 74 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c  unt includes all
e0c0: 20 63 68 61 6e 67 65 73 20 66 72 6f 6d 20 61 6c   changes from al
e0d0: 6c 20 74 72 69 67 67 65 72 0a 2a 2a 20 63 6f 6e  l trigger.** con
e0e0: 74 65 78 74 73 2e 20 20 42 75 74 20 74 68 65 20  texts.  But the 
e0f0: 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69  count does not i
e100: 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73 20 75  nclude changes u
e110: 73 65 64 20 74 6f 0a 2a 2a 20 69 6d 70 6c 65 6d  sed to.** implem
e120: 65 6e 74 20 52 45 50 4c 41 43 45 20 63 6f 6e 73  ent REPLACE cons
e130: 74 72 61 69 6e 74 73 2c 20 64 6f 20 72 6f 6c 6c  traints, do roll
e140: 62 61 63 6b 73 20 6f 72 20 41 42 4f 52 54 20 70  backs or ABORT p
e150: 72 6f 63 65 73 73 69 6e 67 2c 0a 2a 2a 20 6f 72  rocessing,.** or
e160: 20 44 52 4f 50 20 74 61 62 6c 65 20 70 72 6f 63   DROP table proc
e170: 65 73 73 69 6e 67 2e 0a 2a 2a 20 54 68 65 20 63  essing..** The c
e180: 68 61 6e 67 65 73 0a 2a 2a 20 61 72 65 20 63 6f  hanges.** are co
e190: 75 6e 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73  unted as soon as
e1a0: 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74   the statement t
e1b0: 68 61 74 20 6d 61 6b 65 73 20 74 68 65 6d 20 69  hat makes them i
e1c0: 73 20 63 6f 6d 70 6c 65 74 65 64 20 0a 2a 2a 20  s completed .** 
e1d0: 28 77 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d  (when the statem
e1e0: 65 6e 74 20 68 61 6e 64 6c 65 20 69 73 20 70 61  ent handle is pa
e1f0: 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33  ssed to [sqlite3
e200: 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 0a 2a 2a  _reset()] or .**
e210: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
e220: 7a 65 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 51  ze()])..**.** SQ
e230: 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20  Lite implements 
e240: 74 68 65 20 63 6f 6d 6d 61 6e 64 20 22 44 45 4c  the command "DEL
e250: 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 22 20  ETE FROM table" 
e260: 77 69 74 68 6f 75 74 0a 2a 2a 20 61 20 57 48 45  without.** a WHE
e270: 52 45 20 63 6c 61 75 73 65 20 62 79 20 64 72 6f  RE clause by dro
e280: 70 70 69 6e 67 20 61 6e 64 20 72 65 63 72 65 61  pping and recrea
e290: 74 69 6e 67 20 74 68 65 20 74 61 62 6c 65 2e 20  ting the table. 
e2a0: 20 28 54 68 69 73 20 69 73 20 6d 75 63 68 0a 2a   (This is much.*
e2b0: 2a 20 66 61 73 74 65 72 20 74 68 61 6e 20 67 6f  * faster than go
e2c0: 69 6e 67 0a 2a 2a 20 74 68 72 6f 75 67 68 20 61  ing.** through a
e2d0: 6e 64 20 64 65 6c 65 74 69 6e 67 20 69 6e 64 69  nd deleting indi
e2e0: 76 69 64 75 61 6c 20 65 6c 65 6d 65 6e 74 73 20  vidual elements 
e2f0: 66 72 6f 6d 20 74 68 65 20 74 61 62 6c 65 2e 29  from the table.)
e300: 20 20 42 65 63 61 75 73 65 20 6f 66 0a 2a 2a 20    Because of.** 
e310: 74 68 69 73 20 6f 70 74 69 6d 69 7a 61 74 69 6f  this optimizatio
e320: 6e 2c 20 74 68 65 20 63 68 61 6e 67 65 20 63 6f  n, the change co
e330: 75 6e 74 20 66 6f 72 20 22 44 45 4c 45 54 45 20  unt for "DELETE 
e340: 46 52 4f 4d 20 74 61 62 6c 65 22 20 77 69 6c 6c  FROM table" will
e350: 20 62 65 0a 2a 2a 20 7a 65 72 6f 20 72 65 67 61   be.** zero rega
e360: 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20 6e 75  rdless of the nu
e370: 6d 62 65 72 20 6f 66 20 65 6c 65 6d 65 6e 74 73  mber of elements
e380: 20 74 68 61 74 20 77 65 72 65 20 6f 72 69 67 69   that were origi
e390: 6e 61 6c 6c 79 20 69 6e 20 74 68 65 0a 2a 2a 20  nally in the.** 
e3a0: 74 61 62 6c 65 2e 20 54 6f 20 67 65 74 20 61 6e  table. To get an
e3b0: 20 61 63 63 75 72 61 74 65 20 63 6f 75 6e 74 20   accurate count 
e3c0: 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  of the number of
e3d0: 20 72 6f 77 73 20 64 65 6c 65 74 65 64 2c 20 75   rows deleted, u
e3e0: 73 65 0a 2a 2a 20 22 44 45 4c 45 54 45 20 46 52  se.** "DELETE FR
e3f0: 4f 4d 20 74 61 62 6c 65 20 57 48 45 52 45 20 31  OM table WHERE 1
e400: 22 20 69 6e 73 74 65 61 64 2e 0a 2a 2a 0a 2a 2a  " instead..**.**
e410: 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73   See also the [s
e420: 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
e430: 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  ] interface..**.
e440: 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
e450: 2a 20 0a 2a 2a 20 7b 46 31 32 32 36 31 7d 20 54  * .** {F12261} T
e460: 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61  he [sqlite3_tota
e470: 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 72 65 74  l_changes()] ret
e480: 75 72 6e 73 20 74 68 65 20 74 6f 74 61 6c 20 6e  urns the total n
e490: 75 6d 62 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  umber.**        
e4a0: 20 20 6f 66 20 72 6f 77 20 63 68 61 6e 67 65 73    of row changes
e4b0: 20 63 61 75 73 65 64 20 62 79 20 49 4e 53 45 52   caused by INSER
e4c0: 54 2c 20 55 50 44 41 54 45 2c 20 61 6e 64 2f 6f  T, UPDATE, and/o
e4d0: 72 20 44 45 4c 45 54 45 0a 2a 2a 20 20 20 20 20  r DELETE.**     
e4e0: 20 20 20 20 20 73 74 61 74 65 6d 65 6e 74 73 20       statements 
e4f0: 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74  on the same [dat
e500: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
e510: 5d 2c 20 69 6e 20 61 6e 79 0a 2a 2a 20 20 20 20  ], in any.**    
e520: 20 20 20 20 20 20 74 72 69 67 67 65 72 20 63 6f        trigger co
e530: 6e 74 65 78 74 2c 20 73 69 6e 63 65 20 74 68 65  ntext, since the
e540: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
e550: 74 69 6f 6e 20 77 61 73 0a 2a 2a 20 20 20 20 20  tion was.**     
e560: 20 20 20 20 20 63 72 65 61 74 65 64 2e 0a 2a 2a       created..**
e570: 0a 2a 2a 20 7b 46 31 32 32 36 33 7d 20 53 74 61  .** {F12263} Sta
e580: 74 65 6d 65 6e 74 73 20 6f 66 20 74 68 65 20 66  tements of the f
e590: 6f 72 6d 20 22 44 45 4c 45 54 45 20 46 52 4f 4d  orm "DELETE FROM
e5a0: 20 74 61 62 6c 65 6e 61 6d 65 22 20 77 69 74 68   tablename" with
e5b0: 20 6e 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   no.**          
e5c0: 57 48 45 52 45 20 63 6c 61 75 73 65 20 73 68 61  WHERE clause sha
e5d0: 6c 6c 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  ll not change th
e5e0: 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
e5f0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 79 20  .**          by 
e600: 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63  [sqlite3_total_c
e610: 68 61 6e 67 65 73 28 29 5d 0a 2a 2a 0a 2a 2a 20  hanges()].**.** 
e620: 4c 49 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a  LIMITATIONS:.**.
e630: 2a 2a 20 7b 55 31 32 32 36 34 7d 20 49 66 20 61  ** {U12264} If a
e640: 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64   separate thread
e650: 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f   makes changes o
e660: 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  n the same datab
e670: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
e680: 2a 20 20 20 20 20 20 20 20 20 20 77 68 69 6c 65  *          while
e690: 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f   [sqlite3_total_
e6a0: 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75  changes()] is ru
e6b0: 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76  nning then the v
e6c0: 61 6c 75 65 20 0a 2a 2a 20 20 20 20 20 20 20 20  alue .**        
e6d0: 20 20 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e    returned is un
e6e0: 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20  predictable and 
e6f0: 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a  not meaningful..
e700: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74  */.int sqlite3_t
e710: 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c  otal_changes(sql
e720: 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
e730: 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72 75  API3REF: Interru
e740: 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e  pt A Long-Runnin
e750: 67 20 51 75 65 72 79 20 7b 46 31 32 32 37 30 7d  g Query {F12270}
e760: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63  .**.** This func
e770: 74 69 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 20  tion causes any 
e780: 70 65 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65  pending database
e790: 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 62   operation to ab
e7a0: 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72  ort and.** retur
e7b0: 6e 20 61 74 20 69 74 73 20 65 61 72 6c 69 65 73  n at its earlies
e7c0: 74 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 54  t opportunity. T
e7d0: 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74  his routine is t
e7e0: 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c  ypically.** call
e7f0: 65 64 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74  ed in response t
e800: 6f 20 61 20 75 73 65 72 20 61 63 74 69 6f 6e 20  o a user action 
e810: 73 75 63 68 20 61 73 20 70 72 65 73 73 69 6e 67  such as pressing
e820: 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20   "Cancel".** or 
e830: 43 74 72 6c 2d 43 20 77 68 65 72 65 20 74 68 65  Ctrl-C where the
e840: 20 75 73 65 72 20 77 61 6e 74 73 20 61 20 6c 6f   user wants a lo
e850: 6e 67 20 71 75 65 72 79 20 6f 70 65 72 61 74 69  ng query operati
e860: 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d  on to halt.** im
e870: 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a  mediately..**.**
e880: 20 49 74 20 69 73 20 73 61 66 65 20 74 6f 20 63   It is safe to c
e890: 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65  all this routine
e8a0: 20 66 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64   from a thread d
e8b0: 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68  ifferent from th
e8c0: 65 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74  e.** thread that
e8d0: 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75   is currently ru
e8e0: 6e 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 61  nning the databa
e8f0: 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42  se operation.  B
e900: 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20  ut it.** is not 
e910: 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69  safe to call thi
e920: 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61  s routine with a
e930: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
e940: 74 69 6f 6e 20 74 68 61 74 0a 2a 2a 20 69 73 20  tion that.** is 
e950: 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20  closed or might 
e960: 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c  close before sql
e970: 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
e980: 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
e990: 49 66 20 61 6e 20 53 51 4c 20 69 73 20 76 65 72  If an SQL is ver
e9a0: 79 20 6e 65 61 72 6c 79 20 66 69 6e 69 73 68 65  y nearly finishe
e9b0: 64 20 61 74 20 74 68 65 20 74 69 6d 65 20 77 68  d at the time wh
e9c0: 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  en sqlite3_inter
e9d0: 72 75 70 74 28 29 0a 2a 2a 20 69 73 20 63 61 6c  rupt().** is cal
e9e0: 6c 65 64 2c 20 74 68 65 6e 20 69 74 20 6d 69 67  led, then it mig
e9f0: 68 74 20 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f  ht not have an o
ea00: 70 70 6f 72 74 75 6e 69 74 79 20 74 6f 20 62 65  pportunity to be
ea10: 20 69 6e 74 65 72 72 75 70 74 65 64 2e 0a 2a 2a   interrupted..**
ea20: 20 49 74 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e   It might contin
ea30: 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e  ue to completion
ea40: 2e 0a 2a 2a 20 41 6e 20 53 51 4c 20 6f 70 65 72  ..** An SQL oper
ea50: 61 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e  ation that is in
ea60: 74 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72  terrupted will r
ea70: 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45  eturn.** [SQLITE
ea80: 5f 49 4e 54 45 52 52 55 50 54 5d 2e 20 20 49 66  _INTERRUPT].  If
ea90: 20 74 68 65 20 69 6e 74 65 72 72 75 70 74 65 64   the interrupted
eaa0: 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69   SQL operation i
eab0: 73 20 61 6e 0a 2a 2a 20 49 4e 53 45 52 54 2c 20  s an.** INSERT, 
eac0: 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54  UPDATE, or DELET
ead0: 45 20 74 68 61 74 20 69 73 20 69 6e 73 69 64 65  E that is inside
eae0: 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61   an explicit tra
eaf0: 6e 73 61 63 74 69 6f 6e 2c 20 0a 2a 2a 20 74 68  nsaction, .** th
eb00: 65 6e 20 74 68 65 20 65 6e 74 69 72 65 20 74 72  en the entire tr
eb10: 61 6e 73 61 63 74 69 6f 6e 20 77 69 6c 6c 20 62  ansaction will b
eb20: 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75  e rolled back au
eb30: 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 20  tomatically..** 
eb40: 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  A call to sqlite
eb50: 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 68 61  3_interrupt() ha
eb60: 73 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 53  s no effect on S
eb70: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
eb80: 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65   that are starte
eb90: 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f  d after sqlite3_
eba0: 69 6e 74 65 72 72 75 70 74 28 29 20 72 65 74 75  interrupt() retu
ebb0: 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  rns..**.** INVAR
ebc0: 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31  IANTS:.**.** {F1
ebd0: 32 32 37 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  2271} The [sqlit
ebe0: 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 20  e3_interrupt()] 
ebf0: 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 66  interface will f
ec00: 6f 72 63 65 20 61 6c 6c 20 72 75 6e 6e 69 6e 67  orce all running
ec10: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53 51 4c  .**          SQL
ec20: 20 73 74 61 74 65 6d 65 6e 74 73 20 61 73 73 6f   statements asso
ec30: 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
ec40: 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
ec50: 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20  nnection.**     
ec60: 20 20 20 20 20 74 6f 20 68 61 6c 74 20 61 66 74       to halt aft
ec70: 65 72 20 70 72 6f 63 65 73 73 69 6e 67 20 61 74  er processing at
ec80: 20 6d 6f 73 74 20 6f 6e 65 20 61 64 64 69 74 69   most one additi
ec90: 6f 6e 61 6c 20 72 6f 77 20 6f 66 0a 2a 2a 20 20  onal row of.**  
eca0: 20 20 20 20 20 20 20 20 64 61 74 61 2e 0a 2a 2a          data..**
ecb0: 0a 2a 2a 20 7b 46 31 32 32 37 32 7d 20 41 6e 79  .** {F12272} Any
ecc0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
ecd0: 68 61 74 20 69 73 20 69 6e 74 65 72 72 75 70 74  hat is interrupt
ece0: 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 69  ed by [sqlite3_i
ecf0: 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 20  nterrupt()].**  
ed00: 20 20 20 20 20 20 20 20 77 69 6c 6c 20 72 65 74          will ret
ed10: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  urn [SQLITE_INTE
ed20: 52 52 55 50 54 5d 2e 0a 2a 2a 0a 2a 2a 20 4c 49  RRUPT]..**.** LI
ed30: 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a  MITATIONS:.**.**
ed40: 20 7b 55 31 32 32 37 39 7d 20 49 66 20 74 68 65   {U12279} If the
ed50: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
ed60: 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c  tion closes whil
ed70: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  e [sqlite3_inter
ed80: 72 75 70 74 28 29 5d 0a 2a 2a 20 20 20 20 20 20  rupt()].**      
ed90: 20 20 20 20 69 73 20 72 75 6e 6e 69 6e 67 20 74      is running t
eda0: 68 65 6e 20 62 61 64 20 74 68 69 6e 67 73 20 77  hen bad things w
edb0: 69 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70 65  ill likely happe
edc0: 6e 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  n..*/.void sqlit
edd0: 65 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c  e3_interrupt(sql
ede0: 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
edf0: 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69  API3REF: Determi
ee00: 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61  ne If An SQL Sta
ee10: 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65  tement Is Comple
ee20: 74 65 20 7b 46 31 30 35 31 30 7d 0a 2a 2a 0a 2a  te {F10510}.**.*
ee30: 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
ee40: 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20   are useful for 
ee50: 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70  command-line inp
ee60: 75 74 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20  ut to determine 
ee70: 69 66 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e  if the.** curren
ee80: 74 6c 79 20 65 6e 74 65 72 65 64 20 74 65 78 74  tly entered text
ee90: 20 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20 63   seems to form c
eea0: 6f 6d 70 6c 65 74 65 20 61 20 53 51 4c 20 73 74  omplete a SQL st
eeb0: 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66  atement or.** if
eec0: 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75   additional inpu
eed0: 74 20 69 73 20 6e 65 65 64 65 64 20 62 65 66 6f  t is needed befo
eee0: 72 65 20 73 65 6e 64 69 6e 67 20 74 68 65 20 74  re sending the t
eef0: 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69  ext into.** SQLi
ef00: 74 65 20 66 6f 72 20 70 61 72 73 69 6e 67 2e 20  te for parsing. 
ef10: 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
ef20: 72 65 74 75 72 6e 20 74 72 75 65 20 69 66 20 74  return true if t
ef30: 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 0a  he input string.
ef40: 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62 65  ** appears to be
ef50: 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20   a complete SQL 
ef60: 73 74 61 74 65 6d 65 6e 74 2e 20 20 41 20 73 74  statement.  A st
ef70: 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 64 67 65  atement is judge
ef80: 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c  d to be.** compl
ef90: 65 74 65 20 69 66 20 69 74 20 65 6e 64 73 20 77  ete if it ends w
efa0: 69 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20  ith a semicolon 
efb0: 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74  token and is not
efc0: 20 61 20 66 72 61 67 6d 65 6e 74 20 6f 66 20 61   a fragment of a
efd0: 0a 2a 2a 20 43 52 45 41 54 45 20 54 52 49 47 47  .** CREATE TRIGG
efe0: 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 53  ER statement.  S
eff0: 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61  emicolons that a
f000: 72 65 20 65 6d 62 65 64 64 65 64 20 77 69 74 68  re embedded with
f010: 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74  in.** string lit
f020: 65 72 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20  erals or quoted 
f030: 69 64 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73  identifier names
f040: 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65   or comments are
f050: 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64   not.** independ
f060: 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79  ent tokens (they
f070: 20 61 72 65 20 70 61 72 74 20 6f 66 20 74 68 65   are part of the
f080: 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20   token in which 
f090: 74 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65  they are.** embe
f0a0: 64 64 65 64 29 20 61 6e 64 20 74 68 75 73 20 64  dded) and thus d
f0b0: 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61  o not count as a
f0c0: 20 73 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69   statement termi
f0d0: 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  nator..**.** The
f0e0: 73 65 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e  se routines do n
f0f0: 6f 74 20 70 61 72 73 65 20 74 68 65 20 53 51 4c  ot parse the SQL
f100: 20 61 6e 64 0a 2a 2a 20 73 6f 20 77 69 6c 6c 20   and.** so will 
f110: 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e 74 61  not detect synta
f120: 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65  ctically incorre
f130: 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 49 4e  ct SQL..**.** IN
f140: 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
f150: 7b 46 31 30 35 31 31 7d 20 54 68 65 20 73 71 6c  {F10511} The sql
f160: 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 20  ite3_complete() 
f170: 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  and sqlite3_comp
f180: 6c 65 74 65 31 36 28 29 20 66 75 6e 63 74 69 6f  lete16() functio
f190: 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  ns.**          r
f1a0: 65 74 75 72 6e 20 74 72 75 65 20 28 6e 6f 6e 2d  eturn true (non-
f1b0: 7a 65 72 6f 29 20 69 66 20 61 6e 64 20 6f 6e 6c  zero) if and onl
f1c0: 79 20 69 66 20 74 68 65 20 6c 61 73 74 0a 2a 2a  y if the last.**
f1d0: 20 20 20 20 20 20 20 20 20 20 6e 6f 6e 2d 77 68            non-wh
f1e0: 69 74 65 73 70 61 63 65 20 74 6f 6b 65 6e 20 69  itespace token i
f1f0: 6e 20 74 68 65 69 72 20 69 6e 70 75 74 20 69 73  n their input is
f200: 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 68 61   a semicolon tha
f210: 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73  t.**          is
f220: 20 6e 6f 74 20 69 6e 20 62 65 74 77 65 65 6e 20   not in between 
f230: 74 68 65 20 42 45 47 49 4e 20 61 6e 64 20 45 4e  the BEGIN and EN
f240: 44 20 6f 66 20 61 20 43 52 45 41 54 45 20 54 52  D of a CREATE TR
f250: 49 47 47 45 52 0a 2a 2a 20 20 20 20 20 20 20 20  IGGER.**        
f260: 20 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a    statement..**.
f270: 2a 2a 20 4c 49 4d 49 54 41 54 49 4f 4e 53 3a 0a  ** LIMITATIONS:.
f280: 2a 2a 0a 2a 2a 20 7b 55 31 30 35 31 32 7d 20 54  **.** {U10512} T
f290: 68 65 20 69 6e 70 75 74 20 74 6f 20 73 71 6c 69  he input to sqli
f2a0: 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 20 6d  te3_complete() m
f2b0: 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65  ust be a zero-te
f2c0: 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 20 20 20 20  rminated.**     
f2d0: 20 20 20 20 20 55 54 46 2d 38 20 73 74 72 69 6e       UTF-8 strin
f2e0: 67 2e 0a 2a 2a 0a 2a 2a 20 7b 55 31 30 35 31 33  g..**.** {U10513
f2f0: 7d 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 73  } The input to s
f300: 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
f310: 36 28 29 20 6d 75 73 74 20 62 65 20 61 20 7a 65  6() must be a ze
f320: 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
f330: 20 20 20 20 20 20 20 20 20 20 55 54 46 2d 31 36            UTF-16
f340: 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76   string in nativ
f350: 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f  e byte order..*/
f360: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d  .int sqlite3_com
f370: 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72  plete(const char
f380: 20 2a 73 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69   *sql);.int sqli
f390: 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63  te3_complete16(c
f3a0: 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b  onst void *sql);
f3b0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
f3c0: 3a 20 52 65 67 69 73 74 65 72 20 41 20 43 61 6c  : Register A Cal
f3d0: 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20  lback To Handle 
f3e0: 53 51 4c 49 54 45 5f 42 55 53 59 20 45 72 72 6f  SQLITE_BUSY Erro
f3f0: 72 73 20 7b 46 31 32 33 31 30 7d 0a 2a 2a 0a 2a  rs {F12310}.**.*
f400: 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69  * This routine i
f410: 64 65 6e 74 69 66 69 65 73 20 61 20 63 61 6c 6c  dentifies a call
f420: 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 74 68  back function th
f430: 61 74 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 69  at might be.** i
f440: 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20  nvoked whenever 
f450: 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61  an attempt is ma
f460: 64 65 20 74 6f 20 6f 70 65 6e 20 61 20 64 61 74  de to open a dat
f470: 61 62 61 73 65 20 74 61 62 6c 65 20 0a 2a 2a 20  abase table .** 
f480: 74 68 61 74 20 61 6e 6f 74 68 65 72 20 74 68 72  that another thr
f490: 65 61 64 20 6f 72 20 70 72 6f 63 65 73 73 20 68  ead or process h
f4a0: 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 20 49 66  as locked..** If
f4b0: 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61   the busy callba
f4c0: 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  ck is NULL, then
f4d0: 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a   [SQLITE_BUSY].*
f4e0: 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45  * or [SQLITE_IOE
f4f0: 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69  RR_BLOCKED].** i
f500: 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64  s returned immed
f510: 69 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f  iately upon enco
f520: 75 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63  untering the loc
f530: 6b 2e 0a 2a 2a 20 49 66 20 74 68 65 20 62 75 73  k..** If the bus
f540: 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f  y callback is no
f550: 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65  t NULL, then the
f560: 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 77 69 6c  .** callback wil
f570: 6c 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74  l be invoked wit
f580: 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e  h two arguments.
f590: 20 20 54 68 65 0a 2a 2a 20 66 69 72 73 74 20 61    The.** first a
f5a0: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 68  rgument to the h
f5b0: 61 6e 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79  andler is a copy
f5c0: 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f   of the void* po
f5d0: 69 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69  inter which.** i
f5e0: 73 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75  s the third argu
f5f0: 6d 65 6e 74 20 74 6f 20 74 68 69 73 20 72 6f 75  ment to this rou
f600: 74 69 6e 65 2e 20 20 54 68 65 20 73 65 63 6f 6e  tine.  The secon
f610: 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  d argument to.**
f620: 20 74 68 65 20 68 61 6e 64 6c 65 72 20 69 73 20   the handler is 
f630: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69  the number of ti
f640: 6d 65 73 20 74 68 61 74 20 74 68 65 20 62 75 73  mes that the bus
f650: 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a  y handler has.**
f660: 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 66 6f   been invoked fo
f670: 72 20 74 68 69 73 20 6c 6f 63 6b 69 6e 67 20 65  r this locking e
f680: 76 65 6e 74 2e 20 20 20 49 66 20 74 68 65 0a 2a  vent.   If the.*
f690: 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  * busy callback 
f6a0: 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20  returns 0, then 
f6b0: 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74  no additional at
f6c0: 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20  tempts are made 
f6d0: 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65  to.** access the
f6e0: 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53   database and [S
f6f0: 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b  QLITE_BUSY] or [
f700: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
f710: 43 4b 45 44 5d 20 69 73 20 72 65 74 75 72 6e 65  CKED] is returne
f720: 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 63 61 6c  d..** If the cal
f730: 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f  lback returns no
f740: 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f  n-zero, then ano
f750: 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20  ther attempt.** 
f760: 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20  is made to open 
f770: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 6f 72  the database for
f780: 20 72 65 61 64 69 6e 67 20 61 6e 64 20 74 68 65   reading and the
f790: 20 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e 0a   cycle repeats..
f7a0: 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 6e  **.** The presen
f7b0: 63 65 20 6f 66 20 61 20 62 75 73 79 20 68 61 6e  ce of a busy han
f7c0: 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 75  dler does not gu
f7d0: 61 72 61 6e 74 65 65 20 74 68 61 74 0a 2a 2a 20  arantee that.** 
f7e0: 69 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b  it will be invok
f7f0: 65 64 20 77 68 65 6e 20 74 68 65 72 65 20 69 73  ed when there is
f800: 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e   lock contention
f810: 2e 0a 2a 2a 20 49 66 20 53 51 4c 69 74 65 20 64  ..** If SQLite d
f820: 65 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69  etermines that i
f830: 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79  nvoking the busy
f840: 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72   handler could r
f850: 65 73 75 6c 74 20 69 6e 0a 2a 2a 20 61 20 64 65  esult in.** a de
f860: 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20  adlock, it will 
f870: 67 6f 20 61 68 65 61 64 20 61 6e 64 20 72 65 74  go ahead and ret
f880: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  urn [SQLITE_BUSY
f890: 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ] or.** [SQLITE_
f8a0: 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69  IOERR_BLOCKED] i
f8b0: 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69  nstead of invoki
f8c0: 6e 67 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 68  ng the.** busy h
f8d0: 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69  andler..** Consi
f8e0: 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f 20 77  der a scenario w
f8f0: 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 73 73  here one process
f900: 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65   is holding a re
f910: 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20  ad lock that.** 
f920: 69 74 20 69 73 20 74 72 79 69 6e 67 20 74 6f 20  it is trying to 
f930: 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65 73  promote to a res
f940: 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a  erved lock and.*
f950: 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f 63 65  * a second proce
f960: 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20  ss is holding a 
f970: 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 74 68  reserved lock th
f980: 61 74 20 69 74 20 69 73 20 74 72 79 69 6e 67 0a  at it is trying.
f990: 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f  ** to promote to
f9a0: 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c 6f   an exclusive lo
f9b0: 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74 20 70  ck.  The first p
f9c0: 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 70 72  rocess cannot pr
f9d0: 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 73 65  oceed.** because
f9e0: 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62   it is blocked b
f9f0: 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64  y the second and
fa00: 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63   the second proc
fa10: 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72  ess cannot.** pr
fa20: 6f 63 65 65 64 20 62 65 63 61 75 73 65 20 69 74  oceed because it
fa30: 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74   is blocked by t
fa40: 68 65 20 66 69 72 73 74 2e 20 20 49 66 20 62 6f  he first.  If bo
fa50: 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20  th processes.** 
fa60: 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 79 20  invoke the busy 
fa70: 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68 65  handlers, neithe
fa80: 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20  r will make any 
fa90: 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65 72 65  progress.  There
faa0: 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20  fore,.** SQLite 
fab0: 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
fac0: 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20 66 69  BUSY] for the fi
fad0: 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68 6f 70  rst process, hop
fae0: 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a 2a 2a  ing that this.**
faf0: 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 68 65   will induce the
fb00: 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 74   first process t
fb10: 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20 72 65  o release its re
fb20: 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f  ad lock and allo
fb30: 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20  w.** the second 
fb40: 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f 63 65  process to proce
fb50: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65  ed..**.** The de
fb60: 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c 6c 62  fault busy callb
fb70: 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a  ack is NULL..**.
fb80: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 42  ** The [SQLITE_B
fb90: 55 53 59 5d 20 65 72 72 6f 72 20 69 73 20 63 6f  USY] error is co
fba0: 6e 76 65 72 74 65 64 20 74 6f 20 5b 53 51 4c 49  nverted to [SQLI
fbb0: 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
fbc0: 5d 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65  ].** when SQLite
fbd0: 20 69 73 20 69 6e 20 74 68 65 20 6d 69 64 64 6c   is in the middl
fbe0: 65 20 6f 66 20 61 20 6c 61 72 67 65 20 74 72 61  e of a large tra
fbf0: 6e 73 61 63 74 69 6f 6e 20 77 68 65 72 65 20 61  nsaction where a
fc00: 6c 6c 20 74 68 65 0a 2a 2a 20 63 68 61 6e 67 65  ll the.** change
fc10: 73 20 77 69 6c 6c 20 6e 6f 74 20 66 69 74 20 69  s will not fit i
fc20: 6e 74 6f 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72  nto the in-memor
fc30: 79 20 63 61 63 68 65 2e 20 20 53 51 4c 69 74 65  y cache.  SQLite
fc40: 20 77 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64 79   will.** already
fc50: 20 68 6f 6c 64 20 61 20 52 45 53 45 52 56 45 44   hold a RESERVED
fc60: 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 64 61 74   lock on the dat
fc70: 61 62 61 73 65 20 66 69 6c 65 2c 20 62 75 74 20  abase file, but 
fc80: 69 74 20 6e 65 65 64 73 0a 2a 2a 20 74 6f 20 70  it needs.** to p
fc90: 72 6f 6d 6f 74 65 20 74 68 69 73 20 6c 6f 63 6b  romote this lock
fca0: 20 74 6f 20 45 58 43 4c 55 53 49 56 45 20 73 6f   to EXCLUSIVE so
fcb0: 20 74 68 61 74 20 69 74 20 63 61 6e 20 73 70 69   that it can spi
fcc0: 6c 6c 20 63 61 63 68 65 0a 2a 2a 20 70 61 67 65  ll cache.** page
fcd0: 73 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62  s into the datab
fce0: 61 73 65 20 66 69 6c 65 20 77 69 74 68 6f 75 74  ase file without
fcf0: 20 68 61 72 6d 20 74 6f 20 63 6f 6e 63 75 72 72   harm to concurr
fd00: 65 6e 74 0a 2a 2a 20 72 65 61 64 65 72 73 2e 20  ent.** readers. 
fd10: 20 49 66 20 69 74 20 69 73 20 75 6e 61 62 6c 65   If it is unable
fd20: 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 65 20   to promote the 
fd30: 6c 6f 63 6b 2c 20 74 68 65 6e 20 74 68 65 20 69  lock, then the i
fd40: 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61 63 68  n-memory.** cach
fd50: 65 20 77 69 6c 6c 20 62 65 20 6c 65 66 74 20 69  e will be left i
fd60: 6e 20 61 6e 20 69 6e 63 6f 6e 73 69 73 74 65 6e  n an inconsisten
fd70: 74 20 73 74 61 74 65 20 61 6e 64 20 73 6f 20 74  t state and so t
fd80: 68 65 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65  he error.** code
fd90: 20 69 73 20 70 72 6f 6d 6f 74 65 64 20 66 72 6f   is promoted fro
fda0: 6d 20 74 68 65 20 72 65 6c 61 74 69 76 65 6c 79  m the relatively
fdb0: 20 62 65 6e 69 67 6e 20 5b 53 51 4c 49 54 45 5f   benign [SQLITE_
fdc0: 42 55 53 59 5d 20 74 6f 0a 2a 2a 20 74 68 65 20  BUSY] to.** the 
fdd0: 6d 6f 72 65 20 73 65 76 65 72 65 20 5b 53 51 4c  more severe [SQL
fde0: 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45  ITE_IOERR_BLOCKE
fdf0: 44 5d 2e 20 20 54 68 69 73 20 65 72 72 6f 72 20  D].  This error 
fe00: 63 6f 64 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a  code promotion.*
fe10: 2a 20 66 6f 72 63 65 73 20 61 6e 20 61 75 74 6f  * forces an auto
fe20: 6d 61 74 69 63 20 72 6f 6c 6c 62 61 63 6b 20 6f  matic rollback o
fe30: 66 20 74 68 65 20 63 68 61 6e 67 65 73 2e 20 20  f the changes.  
fe40: 53 65 65 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72  See the.** <a hr
fe50: 65 66 3d 22 68 74 74 70 3a 2f 2f 77 77 77 2e 73  ef="http://www.s
fe60: 71 6c 69 74 65 2e 6f 72 67 2f 63 76 73 74 72 61  qlite.org/cvstra
fe70: 63 2f 77 69 6b 69 3f 70 3d 43 6f 72 72 75 70 74  c/wiki?p=Corrupt
fe80: 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79  ionFollowingBusy
fe90: 45 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72 75  Error">.** Corru
fea0: 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75  ptionFollowingBu
feb0: 73 79 45 72 72 6f 72 3c 2f 61 3e 20 77 69 6b 69  syError</a> wiki
fec0: 20 70 61 67 65 20 66 6f 72 20 61 20 64 69 73 63   page for a disc
fed0: 75 73 73 69 6f 6e 20 6f 66 20 77 68 79 0a 2a 2a  ussion of why.**
fee0: 20 74 68 69 73 20 69 73 20 69 6d 70 6f 72 74 61   this is importa
fef0: 6e 74 2e 0a 2a 2a 09 0a 2a 2a 20 54 68 65 72 65  nt..**..** There
ff00: 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73   can only be a s
ff10: 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c  ingle busy handl
ff20: 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72 20 65  er defined for e
ff30: 61 63 68 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  ach database.** 
ff40: 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65 74  connection.  Set
ff50: 74 69 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20  ting a new busy 
ff60: 68 61 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61  handler clears a
ff70: 6e 79 20 70 72 65 76 69 6f 75 73 20 6f 6e 65 2e  ny previous one.
ff80: 20 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 63   .** Note that c
ff90: 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
ffa0: 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20  busy_timeout()] 
ffb0: 77 69 6c 6c 20 61 6c 73 6f 20 73 65 74 20 6f 72  will also set or
ffc0: 20 63 6c 65 61 72 0a 2a 2a 20 74 68 65 20 62 75   clear.** the bu
ffd0: 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a  sy handler..**.*
ffe0: 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
fff0: 0a 2a 2a 20 7b 46 31 32 33 31 31 7d 20 54 68 65  .** {F12311} The
10000 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68   [sqlite3_busy_h
10010 61 6e 64 6c 65 72 28 29 5d 20 66 75 6e 63 74 69  andler()] functi
10020 6f 6e 20 72 65 70 6c 61 63 65 73 20 74 68 65 20  on replaces the 
10030 62 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20  busy handler.** 
10040 20 20 20 20 20 20 20 20 20 63 61 6c 6c 62 61 63           callbac
10050 6b 20 69 6e 20 74 68 65 20 64 61 74 61 62 61 73  k in the databas
10060 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 64 65  e connection ide
10070 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20 31  ntified by the 1
10080 73 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70  st.**          p
10090 61 72 61 6d 65 74 65 72 20 77 69 74 68 20 61 20  arameter with a 
100a0 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72  new busy handler
100b0 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74   identified by t
100c0 68 65 20 32 6e 64 20 61 6e 64 20 33 72 64 0a 2a  he 2nd and 3rd.*
100d0 2a 20 20 20 20 20 20 20 20 20 20 70 61 72 61 6d  *          param
100e0 65 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  eters..**.** {F1
100f0 32 33 31 32 7d 20 54 68 65 20 64 65 66 61 75 6c  2312} The defaul
10100 74 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66  t busy handler f
10110 6f 72 20 6e 65 77 20 64 61 74 61 62 61 73 65 20  or new database 
10120 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 69 73 20 4e  connections is N
10130 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33  ULL..**.** {F123
10140 31 34 7d 20 57 68 65 6e 20 74 77 6f 20 6f 72 20  14} When two or 
10150 6d 6f 72 65 20 64 61 74 61 62 61 73 65 20 63 6f  more database co
10160 6e 6e 65 63 74 69 6f 6e 20 73 68 61 72 65 20 61  nnection share a
10170 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65   [sqlite3_enable
10180 5f 73 68 61 72 65 64 5f 63 61 63 68 65 20 7c 20  _shared_cache | 
10190 63 6f 6d 6d 6f 6e 20 63 61 63 68 65 5d 2c 0a 2a  common cache],.*
101a0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 62  *          the b
101b0 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20  usy handler for 
101c0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
101d0 6e 65 63 74 69 6f 6e 20 63 75 72 72 65 6e 74 6c  nection currentl
101e0 79 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20  y using.**      
101f0 20 20 20 20 74 68 65 20 63 61 63 68 65 20 69 73      the cache is
10200 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 68   invoked when th
10210 65 20 63 61 63 68 65 20 65 6e 63 6f 75 6e 74 65  e cache encounte
10220 72 73 20 61 20 6c 6f 63 6b 2e 0a 2a 2a 0a 2a 2a  rs a lock..**.**
10230 20 7b 46 31 32 33 31 36 7d 20 49 66 20 61 20 62   {F12316} If a b
10240 75 73 79 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c  usy handler call
10250 62 61 63 6b 20 72 65 74 75 72 6e 73 20 7a 65 72  back returns zer
10260 6f 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 69  o, then the SQLi
10270 74 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  te.**          i
10280 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 70 72  nterface that pr
10290 6f 76 6f 6b 65 64 20 74 68 65 20 6c 6f 63 6b 69  ovoked the locki
102a0 6e 67 20 65 76 65 6e 74 20 77 69 6c 6c 20 72 65  ng event will re
102b0 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  turn.**         
102c0 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a   [SQLITE_BUSY]..
102d0 2a 2a 0a 2a 2a 20 7b 46 31 32 33 31 38 7d 20 53  **.** {F12318} S
102e0 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b  QLite will invok
102f0 65 73 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  es the busy hand
10300 6c 65 72 20 77 69 74 68 20 74 77 6f 20 61 72 67  ler with two arg
10310 75 6d 65 6e 74 73 20 77 68 69 63 68 0a 2a 2a 20  uments which.** 
10320 20 20 20 20 20 20 20 20 20 61 72 65 20 61 20 63           are a c
10330 6f 70 79 20 6f 66 20 74 68 65 20 70 6f 69 6e 74  opy of the point
10340 65 72 20 73 75 70 70 6c 69 65 64 20 62 79 20 74  er supplied by t
10350 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
10360 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   to.**          
10370 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61  [sqlite3_busy_ha
10380 6e 64 6c 65 72 28 29 5d 20 61 6e 64 20 61 20 63  ndler()] and a c
10390 6f 75 6e 74 20 6f 66 20 74 68 65 20 6e 75 6d 62  ount of the numb
103a0 65 72 20 6f 66 20 70 72 69 6f 72 0a 2a 2a 20 20  er of prior.**  
103b0 20 20 20 20 20 20 20 20 69 6e 76 6f 63 61 74 69          invocati
103c0 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 73 79 20  ons of the busy 
103d0 68 61 6e 64 6c 65 72 20 66 6f 72 20 74 68 65 20  handler for the 
103e0 73 61 6d 65 20 6c 6f 63 6b 69 6e 67 20 65 76 65  same locking eve
103f0 6e 74 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49 54 41  nt..**.** LIMITA
10400 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 55 31  TIONS:.**.** {U1
10410 32 33 31 39 7d 20 41 20 62 75 73 79 20 68 61 6e  2319} A busy han
10420 64 6c 65 72 20 73 68 6f 75 6c 64 20 6e 6f 74 20  dler should not 
10430 63 61 6c 6c 20 63 6c 6f 73 65 20 74 68 65 20 64  call close the d
10440 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
10450 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  on.**          o
10460 72 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  r prepared state
10470 6d 65 6e 74 20 74 68 61 74 20 69 6e 76 6f 6b 65  ment that invoke
10480 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  d the busy handl
10490 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  er..*/.int sqlit
104a0 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
104b0 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29  sqlite3*, int(*)
104c0 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69  (void*,int), voi
104d0 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
104e0 33 52 45 46 3a 20 53 65 74 20 41 20 42 75 73 79  3REF: Set A Busy
104f0 20 54 69 6d 65 6f 75 74 20 7b 46 31 32 33 34 30   Timeout {F12340
10500 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  }.**.** This rou
10510 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71 6c  tine sets a [sql
10520 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
10530 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65 72  r | busy handler
10540 5d 0a 2a 2a 20 74 68 61 74 20 73 6c 65 65 70 73  ].** that sleeps
10550 20 66 6f 72 20 61 20 77 68 69 6c 65 20 77 68 65   for a while whe
10560 6e 20 61 0a 2a 2a 20 74 61 62 6c 65 20 69 73 20  n a.** table is 
10570 6c 6f 63 6b 65 64 2e 20 20 54 68 65 20 68 61 6e  locked.  The han
10580 64 6c 65 72 20 77 69 6c 6c 20 73 6c 65 65 70 20  dler will sleep 
10590 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75  multiple times u
105a0 6e 74 69 6c 20 0a 2a 2a 20 61 74 20 6c 65 61 73  ntil .** at leas
105b0 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f  t "ms" milliseco
105c0 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 20  nds of sleeping 
105d0 68 61 76 65 20 62 65 65 6e 20 64 6f 6e 65 2e 20  have been done. 
105e0 7b 46 31 32 33 34 33 7d 20 41 66 74 65 72 0a 2a  {F12343} After.*
105f0 2a 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f  * "ms" milliseco
10600 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c  nds of sleeping,
10610 20 74 68 65 20 68 61 6e 64 6c 65 72 20 72 65 74   the handler ret
10620 75 72 6e 73 20 30 20 77 68 69 63 68 0a 2a 2a 20  urns 0 which.** 
10630 63 61 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f  causes [sqlite3_
10640 73 74 65 70 28 29 5d 20 74 6f 20 72 65 74 75 72  step()] to retur
10650 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  n [SQLITE_BUSY] 
10660 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  or [SQLITE_IOERR
10670 5f 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a  _BLOCKED]..**.**
10680 20 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f   Calling this ro
10690 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72  utine with an ar
106a0 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e  gument less than
106b0 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72   or equal to zer
106c0 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61  o.** turns off a
106d0 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73  ll busy handlers
106e0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 63 61  ..**.** There ca
106f0 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67  n only be a sing
10700 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  le busy handler 
10710 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72  for a particular
10720 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
10730 6e 65 63 74 69 6f 6e 2e 20 20 49 66 20 61 6e 6f  nection.  If ano
10740 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65  ther busy handle
10750 72 20 77 61 73 20 64 65 66 69 6e 65 64 20 20 0a  r was defined  .
10760 2a 2a 20 28 75 73 69 6e 67 20 5b 73 71 6c 69 74  ** (using [sqlit
10770 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
10780 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61 6c  )]) prior to cal
10790 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75  ling.** this rou
107a0 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65 72  tine, that other
107b0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73   busy handler is
107c0 20 63 6c 65 61 72 65 64 2e 0a 2a 2a 0a 2a 2a 20   cleared..**.** 
107d0 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
107e0 2a 20 7b 46 31 32 33 34 31 7d 20 54 68 65 20 5b  * {F12341} The [
107f0 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d  sqlite3_busy_tim
10800 65 6f 75 74 28 29 5d 20 66 75 6e 63 74 69 6f 6e  eout()] function
10810 20 6f 76 65 72 72 69 64 65 73 20 61 6e 79 20 70   overrides any p
10820 72 69 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  rior.**         
10830 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74   [sqlite3_busy_t
10840 69 6d 65 6f 75 74 28 29 5d 20 6f 72 20 5b 73 71  imeout()] or [sq
10850 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
10860 65 72 28 29 5d 20 73 65 74 74 69 6e 67 0a 2a 2a  er()] setting.**
10870 20 20 20 20 20 20 20 20 20 20 6f 6e 20 74 68 65            on the
10880 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
10890 6f 6e 6e 65 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  onnection..**.**
108a0 20 7b 46 31 32 33 34 33 7d 20 49 66 20 74 68 65   {F12343} If the
108b0 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74   2nd parameter t
108c0 6f 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  o [sqlite3_busy_
108d0 74 69 6d 65 6f 75 74 28 29 5d 20 69 73 20 6c 65  timeout()] is le
108e0 73 73 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20  ss than.**      
108f0 20 20 20 20 6f 72 20 65 71 75 61 6c 20 74 6f 20      or equal to 
10900 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 62  zero, then the b
10910 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 63  usy handler is c
10920 6c 65 61 72 65 64 20 73 6f 20 74 68 61 74 0a 2a  leared so that.*
10930 2a 20 20 20 20 20 20 20 20 20 20 61 6c 6c 20 73  *          all s
10940 75 62 73 65 71 75 65 6e 74 20 6c 6f 63 6b 69 6e  ubsequent lockin
10950 67 20 65 76 65 6e 74 73 20 69 6d 6d 65 64 69 61  g events immedia
10960 74 65 6c 79 20 72 65 74 75 72 6e 20 5b 53 51 4c  tely return [SQL
10970 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a  ITE_BUSY]..**.**
10980 20 7b 46 31 32 33 34 34 7d 20 49 66 20 74 68 65   {F12344} If the
10990 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74   2nd parameter t
109a0 6f 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  o [sqlite3_busy_
109b0 74 69 6d 65 6f 75 74 28 29 5d 20 69 73 20 61 20  timeout()] is a 
109c0 70 6f 73 69 74 69 76 65 0a 2a 2a 20 20 20 20 20  positive.**     
109d0 20 20 20 20 20 6e 75 6d 62 65 72 20 4e 2c 20 74       number N, t
109e0 68 65 6e 20 61 20 62 75 73 79 20 68 61 6e 64 6c  hen a busy handl
109f0 65 72 20 69 73 20 73 65 74 20 74 68 61 74 20 72  er is set that r
10a00 65 70 65 61 74 65 64 6c 79 20 63 61 6c 6c 73 0a  epeatedly calls.
10a10 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
10a20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20  xSleep() method 
10a30 69 6e 20 74 68 65 20 56 46 53 20 69 6e 74 65 72  in the VFS inter
10a40 66 61 63 65 20 75 6e 74 69 6c 20 65 69 74 68 65  face until eithe
10a50 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  r the.**        
10a60 20 20 6c 6f 63 6b 20 63 6c 65 61 72 73 20 6f 72    lock clears or
10a70 20 75 6e 74 69 6c 20 74 68 65 20 63 75 6d 75 6c   until the cumul
10a80 61 74 69 76 65 20 73 6c 65 65 70 20 74 69 6d 65  ative sleep time
10a90 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 0a 2a   reported back.*
10aa0 2a 20 20 20 20 20 20 20 20 20 20 62 79 20 78 53  *          by xS
10ab0 6c 65 65 70 28 29 20 65 78 63 65 65 64 73 20 4e  leep() exceeds N
10ac0 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 2e 0a 2a   milliseconds..*
10ad0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75  /.int sqlite3_bu
10ae0 73 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74  sy_timeout(sqlit
10af0 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f  e3*, int ms);../
10b00 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
10b10 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69  onvenience Routi
10b20 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20  nes For Running 
10b30 51 75 65 72 69 65 73 20 7b 46 31 32 33 37 30 7d  Queries {F12370}
10b40 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f  .**.** Definitio
10b50 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74 20 74  n: A <b>result t
10b60 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f  able</b> is memo
10b70 72 79 20 64 61 74 61 20 73 74 72 75 63 74 75 72  ry data structur
10b80 65 20 63 72 65 61 74 65 64 20 62 79 20 74 68 65  e created by the
10b90 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74  .** [sqlite3_get
10ba0 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 65 72 66  _table()] interf
10bb0 61 63 65 2e 20 20 41 20 72 65 73 75 6c 74 20 74  ace.  A result t
10bc0 61 62 6c 65 20 72 65 63 6f 72 64 73 20 74 68 65  able records the
10bd0 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75 65  .** complete que
10be0 72 79 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20  ry results from 
10bf0 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75 65 72  one or more quer
10c00 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  ies..**.** The t
10c10 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c  able conceptuall
10c20 79 20 68 61 73 20 61 20 6e 75 6d 62 65 72 20 6f  y has a number o
10c30 66 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d  f rows and colum
10c40 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65 73  ns.  But.** thes
10c50 65 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6e 6f  e numbers are no
10c60 74 20 70 61 72 74 20 6f 66 20 74 68 65 20 72 65  t part of the re
10c70 73 75 6c 74 20 74 61 62 6c 65 20 69 74 73 65 6c  sult table itsel
10c80 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d  f.  These.** num
10c90 62 65 72 73 20 61 72 65 20 6f 62 74 61 69 6e 65  bers are obtaine
10ca0 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20 20 4c  d separately.  L
10cb0 65 74 20 4e 20 62 65 20 74 68 65 20 6e 75 6d 62  et N be the numb
10cc0 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e  er of rows.** an
10cd0 64 20 4d 20 62 65 20 74 68 65 20 6e 75 6d 62 65  d M be the numbe
10ce0 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a  r of columns..**
10cf0 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62  .** A result tab
10d00 6c 65 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f  le is an array o
10d10 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65  f pointers to ze
10d20 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
10d30 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 20   UTF-8 strings. 
10d40 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31 29   There are (N+1)
10d50 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74  *M elements in t
10d60 68 65 20 61 72 72 61 79 2e 20 20 0a 2a 2a 20 54  he array.  .** T
10d70 68 65 20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74  he first M point
10d80 65 72 73 20 70 6f 69 6e 74 20 74 6f 20 7a 65 72  ers point to zer
10d90 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72  o-terminated str
10da0 69 6e 67 73 20 74 68 61 74 20 0a 2a 2a 20 63 6f  ings that .** co
10db0 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20  ntain the names 
10dc0 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a  of the columns..
10dd0 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67  ** The remaining
10de0 20 65 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f 69   entries all poi
10df0 6e 74 20 74 6f 20 71 75 65 72 79 20 72 65 73 75  nt to query resu
10e00 6c 74 73 2e 20 20 4e 55 4c 4c 0a 2a 2a 20 76 61  lts.  NULL.** va
10e10 6c 75 65 73 20 61 72 65 20 67 69 76 65 20 61 20  lues are give a 
10e20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 41  NULL pointer.  A
10e30 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20  ll other values 
10e40 61 72 65 20 69 6e 0a 2a 2a 20 74 68 65 69 72 20  are in.** their 
10e50 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69  UTF-8 zero-termi
10e60 6e 61 74 65 64 20 73 74 72 69 6e 67 20 72 65 70  nated string rep
10e70 72 65 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 72  resentation as r
10e80 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73  eturned by.** [s
10e90 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
10ea0 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72  xt()]..**.** A r
10eb0 65 73 75 6c 74 20 74 61 62 6c 65 20 6d 69 67 68  esult table migh
10ec0 74 20 63 6f 6e 73 69 73 74 73 20 6f 66 20 6f 6e  t consists of on
10ed0 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79  e or more memory
10ee0 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a   allocations..**
10ef0 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20   It is not safe 
10f00 74 6f 20 70 61 73 73 20 61 20 72 65 73 75 6c 74  to pass a result
10f10 20 74 61 62 6c 65 20 64 69 72 65 63 74 6c 79 20   table directly 
10f20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  to [sqlite3_free
10f30 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74  ()]..** A result
10f40 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 20 62 65   table should be
10f50 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 75 73 69   deallocated usi
10f60 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ng [sqlite3_free
10f70 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  _table()]..**.**
10f80 20 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f   As an example o
10f90 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  f the result tab
10fa0 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f  le format, suppo
10fb0 73 65 20 61 20 71 75 65 72 79 20 72 65 73 75 6c  se a query resul
10fc0 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f  t.** is as follo
10fd0 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
10fe0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
10ff0 20 20 20 20 20 20 4e 61 6d 65 20 20 20 20 20 20        Name      
11000 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 20    | Age.**      
11010 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d    --------------
11020 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20  ---------.**    
11030 20 20 20 20 41 6c 69 63 65 20 20 20 20 20 20 20      Alice       
11040 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 42  | 43.**        B
11050 6f 62 20 20 20 20 20 20 20 20 20 7c 20 32 38 0a  ob         | 28.
11060 2a 2a 20 20 20 20 20 20 20 20 43 69 6e 64 79 20  **        Cindy 
11070 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f        | 21.** </
11080 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
11090 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72  >.**.** There ar
110a0 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d  e two column (M=
110b0 3d 32 29 20 61 6e 64 20 74 68 72 65 65 20 72 6f  =2) and three ro
110c0 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73  ws (N==3).  Thus
110d0 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74   the.** result t
110e0 61 62 6c 65 20 68 61 73 20 38 20 65 6e 74 72 69  able has 8 entri
110f0 65 73 2e 20 20 53 75 70 70 6f 73 65 20 74 68 65  es.  Suppose the
11100 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73   result table is
11110 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e   stored.** in an
11120 20 61 72 72 61 79 20 6e 61 6d 65 73 20 61 7a 52   array names azR
11130 65 73 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52  esult.  Then azR
11140 65 73 75 6c 74 20 68 6f 6c 64 73 20 74 68 69 73  esult holds this
11150 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20   content:.**.** 
11160 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
11170 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  >.**        azRe
11180 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e  sult&#91;0] = "N
11190 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  ame";.**        
111a0 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 31 5d 20  azResult&#91;1] 
111b0 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20  = "Age";.**     
111c0 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
111d0 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a  2] = "Alice";.**
111e0 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
111f0 26 23 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a  &#91;3] = "43";.
11200 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
11210 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62  lt&#91;4] = "Bob
11220 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
11230 65 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22  esult&#91;5] = "
11240 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  28";.**        a
11250 7a 52 65 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d  zResult&#91;6] =
11260 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20   "Cindy";.**    
11270 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
11280 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c  ;7] = "21";.** <
11290 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
112a0 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  e>.**.** The sql
112b0 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
112c0 20 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61   function evalua
112d0 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a  tes one or more.
112e0 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70  ** semicolon-sep
112f0 61 72 61 74 65 64 20 53 51 4c 20 73 74 61 74 65  arated SQL state
11300 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72  ments in the zer
11310 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
11320 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20  -8.** string of 
11330 69 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65  its 2nd paramete
11340 72 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20 61  r.  It returns a
11350 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f   result table to
11360 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20   the.** pointer 
11370 67 69 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64  given in its 3rd
11380 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
11390 2a 20 41 66 74 65 72 20 74 68 65 20 63 61 6c 6c  * After the call
113a0 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 68 61 73  ing function has
113b0 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20   finished using 
113c0 74 68 65 20 72 65 73 75 6c 74 2c 20 69 74 20 73  the result, it s
113d0 68 6f 75 6c 64 20 0a 2a 2a 20 70 61 73 73 20 74  hould .** pass t
113e0 68 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68  he pointer to th
113f0 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74  e result table t
11400 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74  o sqlite3_free_t
11410 61 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20  able() in order 
11420 74 6f 20 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74  to .** release t
11430 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77  he memory that w
11440 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65  as malloced.  Be
11450 63 61 75 73 65 20 6f 66 20 74 68 65 20 77 61 79  cause of the way
11460 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65   the .** [sqlite
11470 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70  3_malloc()] happ
11480 65 6e 73 20 77 69 74 68 69 6e 20 73 71 6c 69 74  ens within sqlit
11490 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 20  e3_get_table(), 
114a0 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66  the calling.** f
114b0 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  unction must not
114c0 20 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71   try to call [sq
114d0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 64 69  lite3_free()] di
114e0 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 20 0a 2a  rectly.  Only .*
114f0 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  * [sqlite3_free_
11500 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62 6c 65  table()] is able
11510 20 74 6f 20 72 65 6c 65 61 73 65 20 74 68 65 20   to release the 
11520 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79 20  memory properly 
11530 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a  and safely..**.*
11540 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65  * The sqlite3_ge
11550 74 5f 74 61 62 6c 65 28 29 20 69 6e 74 65 72 66  t_table() interf
11560 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74  ace is implement
11570 65 64 20 61 73 20 61 20 77 72 61 70 70 65 72 20  ed as a wrapper 
11580 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  around.** [sqlit
11590 65 33 5f 65 78 65 63 28 29 5d 2e 20 20 54 68 65  e3_exec()].  The
115a0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
115b0 6c 65 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65  le() routine doe
115c0 73 20 6e 6f 74 20 68 61 76 65 20 61 63 63 65 73  s not have acces
115d0 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65  s.** to any inte
115e0 72 6e 61 6c 20 64 61 74 61 20 73 74 72 75 63 74  rnal data struct
115f0 75 72 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20  ures of SQLite. 
11600 20 49 74 20 75 73 65 73 20 6f 6e 6c 79 20 74 68   It uses only th
11610 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65  e public.** inte
11620 72 66 61 63 65 20 64 65 66 69 6e 65 64 20 68 65  rface defined he
11630 72 65 2e 20 20 41 73 20 61 20 63 6f 6e 73 65 71  re.  As a conseq
11640 75 65 6e 63 65 2c 20 65 72 72 6f 72 73 20 74 68  uence, errors th
11650 61 74 20 6f 63 63 75 72 20 69 6e 20 74 68 65 0a  at occur in the.
11660 2a 2a 20 77 72 61 70 70 65 72 20 6c 61 79 65 72  ** wrapper layer
11670 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20   outside of the 
11680 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65  internal [sqlite
11690 33 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c 20 61  3_exec()] call a
116a0 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63  re not.** reflec
116b0 74 65 64 20 69 6e 20 73 75 62 73 65 71 75 65 6e  ted in subsequen
116c0 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  t calls to [sqli
116d0 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f  te3_errcode()] o
116e0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72  r.** [sqlite3_er
116f0 72 6d 73 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49  rmsg()]..**.** I
11700 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
11710 20 7b 46 31 32 33 37 31 7d 20 49 66 20 61 20 5b   {F12371} If a [
11720 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
11730 65 28 29 5d 20 66 61 69 6c 73 20 61 20 6d 65 6d  e()] fails a mem
11740 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20  ory allocation, 
11750 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  then.**         
11760 20 69 74 20 66 72 65 65 73 20 74 68 65 20 72 65   it frees the re
11770 73 75 6c 74 20 74 61 62 6c 65 20 75 6e 64 65 72  sult table under
11780 20 63 6f 6e 73 74 72 75 63 74 69 6f 6e 2c 20 61   construction, a
11790 62 6f 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20  borts the.**    
117a0 20 20 20 20 20 20 71 75 65 72 79 20 69 6e 20 70        query in p
117b0 72 6f 63 65 73 73 2c 20 73 6b 69 70 73 20 61 6e  rocess, skips an
117c0 79 20 73 75 62 73 65 71 75 65 6e 74 20 71 75 65  y subsequent que
117d0 72 69 65 73 2c 20 73 65 74 73 20 74 68 65 0a 2a  ries, sets the.*
117e0 2a 20 20 20 20 20 20 20 20 20 20 2a 72 65 73 75  *          *resu
117f0 6c 74 70 20 6f 75 74 70 75 74 20 70 6f 69 6e 74  ltp output point
11800 65 72 20 74 6f 20 4e 55 4c 4c 20 61 6e 64 20 72  er to NULL and r
11810 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4e  eturns [SQLITE_N
11820 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  OMEM]..**.** {F1
11830 32 33 37 33 7d 20 49 66 20 74 68 65 20 6e 63 6f  2373} If the nco
11840 6c 75 6d 6e 20 70 61 72 61 6d 65 74 65 72 20 74  lumn parameter t
11850 6f 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  o [sqlite3_get_t
11860 61 62 6c 65 28 29 5d 20 69 73 20 6e 6f 74 20 4e  able()] is not N
11870 55 4c 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ULL.**          
11880 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 67 65  then [sqlite3_ge
11890 74 5f 74 61 62 6c 65 28 29 5d 20 77 72 69 74 65  t_table()] write
118a0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
118b0 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a  olumns in the.**
118c0 20 20 20 20 20 20 20 20 20 20 72 65 73 75 6c 74            result
118d0 20 73 65 74 20 6f 66 20 74 68 65 20 71 75 65 72   set of the quer
118e0 79 20 69 6e 74 6f 20 2a 6e 63 6f 6c 75 6d 6e 20  y into *ncolumn 
118f0 69 66 20 74 68 65 20 71 75 65 72 79 20 69 73 0a  if the query is.
11900 2a 2a 20 20 20 20 20 20 20 20 20 20 73 75 63 63  **          succ
11910 65 73 73 66 75 6c 20 28 69 66 20 74 68 65 20 66  essful (if the f
11920 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
11930 53 51 4c 49 54 45 5f 4f 4b 29 2e 0a 2a 2a 0a 2a  SQLITE_OK)..**.*
11940 2a 20 7b 46 31 32 33 37 34 7d 20 49 66 20 74 68  * {F12374} If th
11950 65 20 6e 72 6f 77 20 70 61 72 61 6d 65 74 65 72  e nrow parameter
11960 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 67 65 74   to [sqlite3_get
11970 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 6e 6f 74  _table()] is not
11980 20 4e 55 4c 4c 0a 2a 2a 20 20 20 20 20 20 20 20   NULL.**        
11990 20 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f    then [sqlite3_
119a0 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 77 72 69  get_table()] wri
119b0 74 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  te the number of
119c0 20 72 6f 77 73 20 69 6e 20 74 68 65 0a 2a 2a 20   rows in the.** 
119d0 20 20 20 20 20 20 20 20 20 72 65 73 75 6c 74 20           result 
119e0 73 65 74 20 6f 66 20 74 68 65 20 71 75 65 72 79  set of the query
119f0 20 69 6e 74 6f 20 2a 6e 72 6f 77 20 69 66 20 74   into *nrow if t
11a00 68 65 20 71 75 65 72 79 20 69 73 0a 2a 2a 20 20  he query is.**  
11a10 20 20 20 20 20 20 20 20 73 75 63 63 65 73 73 66          successf
11a20 75 6c 20 28 69 66 20 74 68 65 20 66 75 6e 63 74  ul (if the funct
11a30 69 6f 6e 20 72 65 74 75 72 6e 73 20 53 51 4c 49  ion returns SQLI
11a40 54 45 5f 4f 4b 29 2e 0a 2a 2a 0a 2a 2a 20 7b 46  TE_OK)..**.** {F
11a50 31 32 33 37 36 7d 20 54 68 65 20 5b 73 71 6c 69  12376} The [sqli
11a60 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d  te3_get_table()]
11a70 20 66 75 6e 63 74 69 6f 6e 20 73 65 74 73 20 69   function sets i
11a80 74 73 20 2a 6e 63 6f 6c 75 6d 6e 20 76 61 6c 75  ts *ncolumn valu
11a90 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f  e.**          to
11aa0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
11ab0 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65  olumns in the re
11ac0 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68 65 20  sult set of the 
11ad0 71 75 65 72 79 20 69 6e 20 74 68 65 0a 2a 2a 20  query in the.** 
11ae0 20 20 20 20 20 20 20 20 20 73 71 6c 20 70 61 72           sql par
11af0 61 6d 65 74 65 72 2c 20 6f 72 20 74 6f 20 7a 65  ameter, or to ze
11b00 72 6f 20 69 66 20 74 68 65 20 71 75 65 72 79 20  ro if the query 
11b10 69 6e 20 73 71 6c 20 68 61 73 20 61 6e 20 65 6d  in sql has an em
11b20 70 74 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  pty.**          
11b30 72 65 73 75 6c 74 20 73 65 74 2e 0a 2a 2f 0a 69  result set..*/.i
11b40 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  nt sqlite3_get_t
11b50 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 2a  able(.  sqlite3*
11b60 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  ,             /*
11b70 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   An open databas
11b80 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
11b90 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 2f 2a 20  r *sql,      /* 
11ba0 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61  SQL to be evalua
11bb0 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a  ted */.  char **
11bc0 2a 70 52 65 73 75 6c 74 2c 20 20 20 20 20 20 2f  *pResult,      /
11bd0 2a 20 52 65 73 75 6c 74 73 20 6f 66 20 74 68 65  * Results of the
11be0 20 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20   query */.  int 
11bf0 2a 6e 72 6f 77 2c 20 20 20 20 20 20 20 20 20 20  *nrow,          
11c00 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72    /* Number of r
11c10 65 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74 74  esult rows writt
11c20 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74  en here */.  int
11c30 20 2a 6e 63 6f 6c 75 6d 6e 2c 20 20 20 20 20 20   *ncolumn,      
11c40 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20     /* Number of 
11c50 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77  result columns w
11c60 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20  ritten here */. 
11c70 20 63 68 61 72 20 2a 2a 65 72 72 6d 73 67 20 20   char **errmsg  
11c80 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20         /* Error 
11c90 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65  msg written here
11ca0 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71 6c 69   */.);.void sqli
11cb0 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 63  te3_free_table(c
11cc0 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a  har **result);..
11cd0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
11ce0 46 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e 67  Formatted String
11cf0 20 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 69   Printing Functi
11d00 6f 6e 73 20 7b 46 31 37 34 30 30 7d 0a 2a 2a 0a  ons {F17400}.**.
11d10 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
11d20 73 20 61 72 65 20 77 6f 72 6b 61 6c 69 6b 65 73  s are workalikes
11d30 20 6f 66 20 74 68 65 20 22 70 72 69 6e 74 66 28   of the "printf(
11d40 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e  )" family of fun
11d50 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74  ctions.** from t
11d60 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
11d70 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  brary..**.** The
11d80 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
11d90 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76  () and sqlite3_v
11da0 6d 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e  mprintf() routin
11db0 65 73 20 77 72 69 74 65 20 74 68 65 69 72 0a 2a  es write their.*
11dc0 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d  * results into m
11dd0 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
11de0 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
11df0 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73  loc()]..** The s
11e00 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20  trings returned 
11e10 62 79 20 74 68 65 73 65 20 74 77 6f 20 72 6f 75  by these two rou
11e20 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 0a  tines should be.
11e30 2a 2a 20 72 65 6c 65 61 73 65 64 20 62 79 20 5b  ** released by [
11e40 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e  sqlite3_free()].
11e50 20 20 20 42 6f 74 68 20 72 6f 75 74 69 6e 65 73     Both routines
11e60 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c   return a.** NUL
11e70 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 5b 73 71  L pointer if [sq
11e80 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
11e90 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c  is unable to all
11ea0 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20  ocate enough.** 
11eb0 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  memory to hold t
11ec0 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72  he resulting str
11ed0 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 73 71  ing..**.** In sq
11ee0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
11ef0 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69   routine is simi
11f00 6c 61 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 66  lar to "snprintf
11f10 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20  ()" from.** the 
11f20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
11f30 72 79 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20  ry.  The result 
11f40 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  is written into 
11f50 74 68 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 75  the.** buffer su
11f60 70 70 6c 69 65 64 20 61 73 20 74 68 65 20 73 65  pplied as the se
11f70 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 77  cond parameter w
11f80 68 6f 73 65 20 73 69 7a 65 20 69 73 20 67 69 76  hose size is giv
11f90 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72  en by.** the fir
11fa0 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f  st parameter. No
11fb0 74 65 20 74 68 61 74 20 74 68 65 20 6f 72 64 65  te that the orde
11fc0 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73  r of the.** firs
11fd0 74 20 74 77 6f 20 70 61 72 61 6d 65 74 65 72 73  t two parameters
11fe0 20 69 73 20 72 65 76 65 72 73 65 64 20 66 72 6f   is reversed fro
11ff0 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e 20 20 54  m snprintf().  T
12000 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73  his is an.** his
12010 74 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74  torical accident
12020 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20   that cannot be 
12030 66 69 78 65 64 20 77 69 74 68 6f 75 74 20 62 72  fixed without br
12040 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61  eaking.** backwa
12050 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
12060 79 2e 20 20 4e 6f 74 65 20 61 6c 73 6f 20 74 68  y.  Note also th
12070 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  at sqlite3_snpri
12080 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73  ntf().** returns
12090 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74   a pointer to it
120a0 73 20 62 75 66 66 65 72 20 69 6e 73 74 65 61 64  s buffer instead
120b0 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   of the number o
120c0 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20  f.** characters 
120d0 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e  actually written
120e0 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72   into the buffer
120f0 2e 20 20 57 65 20 61 64 6d 69 74 20 74 68 61 74  .  We admit that
12100 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
12110 66 20 63 68 61 72 61 63 74 65 72 73 20 77 72 69  f characters wri
12120 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 20  tten would be a 
12130 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74 75  more useful retu
12140 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 20  rn.** value but 
12150 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65  we cannot change
12160 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
12170 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73  ion of sqlite3_s
12180 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77  nprintf().** now
12190 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e   without breakin
121a0 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  g compatibility.
121b0 0a 2a 2a 0a 2a 2a 20 41 73 20 6c 6f 6e 67 20 61  .**.** As long a
121c0 73 20 74 68 65 20 62 75 66 66 65 72 20 73 69 7a  s the buffer siz
121d0 65 20 69 73 20 67 72 65 61 74 65 72 20 74 68 61  e is greater tha
121e0 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f  n zero, sqlite3_
121f0 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75  snprintf().** gu
12200 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68  arantees that th
12210 65 20 62 75 66 66 65 72 20 69 73 20 61 6c 77 61  e buffer is alwa
12220 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  ys zero-terminat
12230 65 64 2e 20 20 54 68 65 20 66 69 72 73 74 0a 2a  ed.  The first.*
12240 2a 20 70 61 72 61 6d 65 74 65 72 20 22 6e 22 20  * parameter "n" 
12250 69 73 20 74 68 65 20 74 6f 74 61 6c 20 73 69 7a  is the total siz
12260 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 2c  e of the buffer,
12270 20 69 6e 63 6c 75 64 69 6e 67 20 73 70 61 63 65   including space
12280 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f   for.** the zero
12290 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f   terminator.  So
122a0 20 74 68 65 20 6c 6f 6e 67 65 73 74 20 73 74 72   the longest str
122b0 69 6e 67 20 74 68 61 74 20 63 61 6e 20 62 65 20  ing that can be 
122c0 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72  completely.** wr
122d0 69 74 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d  itten will be n-
122e0 31 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a  1 characters..**
122f0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
12300 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74  es all implement
12310 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c   some additional
12320 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f   formatting.** o
12330 70 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20  ptions that are 
12340 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74  useful for const
12350 72 75 63 74 69 6e 67 20 53 51 4c 20 73 74 61 74  ructing SQL stat
12360 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f  ements..** All o
12370 66 20 74 68 65 20 75 73 75 61 6c 20 70 72 69 6e  f the usual prin
12380 74 66 28 29 20 66 6f 72 6d 61 74 74 69 6e 67 20  tf() formatting 
12390 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20  options apply.  
123a0 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74 68 65  In addition, the
123b0 72 65 0a 2a 2a 20 69 73 20 61 72 65 20 22 25 71  re.** is are "%q
123c0 22 2c 20 22 25 51 22 2c 20 61 6e 64 20 22 25 7a  ", "%Q", and "%z
123d0 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  " options..**.**
123e0 20 54 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 77   The %q option w
123f0 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e 20  orks like %s in 
12400 74 68 61 74 20 69 74 20 73 75 62 73 74 69 74 75  that it substitu
12410 74 65 73 20 61 20 6e 75 6c 6c 2d 74 65 72 6d 69  tes a null-termi
12420 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20  nated.** string 
12430 66 72 6f 6d 20 74 68 65 20 61 72 67 75 6d 65 6e  from the argumen
12440 74 20 6c 69 73 74 2e 20 20 42 75 74 20 25 71 20  t list.  But %q 
12450 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65 76 65  also doubles eve
12460 72 79 20 27 5c 27 27 20 63 68 61 72 61 63 74 65  ry '\'' characte
12470 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65 73 69  r..** %q is desi
12480 67 6e 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73  gned for use ins
12490 69 64 65 20 61 20 73 74 72 69 6e 67 20 6c 69 74  ide a string lit
124a0 65 72 61 6c 2e 20 20 42 79 20 64 6f 75 62 6c 69  eral.  By doubli
124b0 6e 67 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20  ng each '\''.** 
124c0 63 68 61 72 61 63 74 65 72 20 69 74 20 65 73 63  character it esc
124d0 61 70 65 73 20 74 68 61 74 20 63 68 61 72 61 63  apes that charac
124e0 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69  ter and allows i
124f0 74 20 74 6f 20 62 65 20 69 6e 73 65 72 74 65 64  t to be inserted
12500 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72   into.** the str
12510 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65  ing..**.** For e
12520 78 61 6d 70 6c 65 2c 20 73 6f 20 73 6f 6d 65 20  xample, so some 
12530 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c 65 20  string variable 
12540 63 6f 6e 74 61 69 6e 73 20 74 65 78 74 20 61 73  contains text as
12550 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
12560 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
12570 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65 78  >.**  char *zTex
12580 74 20 3d 20 22 49 74 27 73 20 61 20 68 61 70 70  t = "It's a happ
12590 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72  y day!";.** </pr
125a0 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
125b0 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73  **.** One can us
125c0 65 20 74 68 69 73 20 74 65 78 74 20 69 6e 20 61  e this text in a
125d0 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  n SQL statement 
125e0 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
125f0 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
12600 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53  re>.**  char *zS
12610 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72  QL = sqlite3_mpr
12620 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54  intf("INSERT INT
12630 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 27  O table VALUES('
12640 25 71 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a  %q')", zText);.*
12650 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  *  sqlite3_exec(
12660 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20  db, zSQL, 0, 0, 
12670 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  0);.**  sqlite3_
12680 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c  free(zSQL);.** <
12690 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
126a0 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65  e>.**.** Because
126b0 20 74 68 65 20 25 71 20 66 6f 72 6d 61 74 20 73   the %q format s
126c0 74 72 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74  tring is used, t
126d0 68 65 20 27 5c 27 27 20 63 68 61 72 61 63 74 65  he '\'' characte
126e0 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73  r in zText.** is
126f0 20 65 73 63 61 70 65 64 20 61 6e 64 20 74 68 65   escaped and the
12700 20 53 51 4c 20 67 65 6e 65 72 61 74 65 64 20 69   SQL generated i
12710 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  s as follows:.**
12720 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
12730 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54  <pre>.**  INSERT
12740 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c   INTO table1 VAL
12750 55 45 53 28 27 49 74 27 27 73 20 61 20 68 61 70  UES('It''s a hap
12760 70 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70  py day!').** </p
12770 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
12780 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 63  .**.** This is c
12790 6f 72 72 65 63 74 2e 20 20 48 61 64 20 77 65 20  orrect.  Had we 
127a0 75 73 65 64 20 25 73 20 69 6e 73 74 65 61 64 20  used %s instead 
127b0 6f 66 20 25 71 2c 20 74 68 65 20 67 65 6e 65 72  of %q, the gener
127c0 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c  ated SQL.** woul
127d0 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69  d have looked li
127e0 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ke this:.**.** <
127f0 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
12800 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f  .**  INSERT INTO
12810 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27   table1 VALUES('
12820 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79  It's a happy day
12830 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  !');.** </pre></
12840 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
12850 2a 20 54 68 69 73 20 73 65 63 6f 6e 64 20 65 78  * This second ex
12860 61 6d 70 6c 65 20 69 73 20 61 6e 20 53 51 4c 20  ample is an SQL 
12870 73 79 6e 74 61 78 20 65 72 72 6f 72 2e 20 20 41  syntax error.  A
12880 73 20 61 20 67 65 6e 65 72 61 6c 20 72 75 6c 65  s a general rule
12890 20 79 6f 75 0a 2a 2a 20 73 68 6f 75 6c 64 20 61   you.** should a
128a0 6c 77 61 79 73 20 75 73 65 20 25 71 20 69 6e 73  lways use %q ins
128b0 74 65 61 64 20 6f 66 20 25 73 20 77 68 65 6e 20  tead of %s when 
128c0 69 6e 73 65 72 74 69 6e 67 20 74 65 78 74 20 69  inserting text i
128d0 6e 74 6f 20 61 20 73 74 72 69 6e 67 20 0a 2a 2a  nto a string .**
128e0 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20   literal..**.** 
128f0 54 68 65 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f  The %Q option wo
12900 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 78 63 65  rks like %q exce
12910 70 74 20 69 74 20 61 6c 73 6f 20 61 64 64 73 20  pt it also adds 
12920 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20 61 72  single quotes ar
12930 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73  ound.** the outs
12940 69 64 65 20 6f 66 20 74 68 65 20 74 6f 74 61 6c  ide of the total
12950 20 73 74 72 69 6e 67 2e 20 20 4f 72 20 69 66 20   string.  Or if 
12960 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 6e  the parameter in
12970 20 74 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a   the argument.**
12980 20 6c 69 73 74 20 69 73 20 61 20 4e 55 4c 4c 20   list is a NULL 
12990 70 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 62 73  pointer, %Q subs
129a0 74 69 74 75 74 65 73 20 74 68 65 20 74 65 78 74  titutes the text
129b0 20 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75 74   "NULL" (without
129c0 20 73 69 6e 67 6c 65 0a 2a 2a 20 71 75 6f 74 65   single.** quote
129d0 73 29 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74  s) in place of t
129e0 68 65 20 25 51 20 6f 70 74 69 6f 6e 2e 20 7b 45  he %Q option. {E
129f0 4e 44 7d 20 20 53 6f 2c 20 66 6f 72 20 65 78 61  ND}  So, for exa
12a00 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20  mple, one could 
12a10 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  say:.**.** <bloc
12a20 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
12a30 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71   char *zSQL = sq
12a40 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49  lite3_mprintf("I
12a50 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
12a60 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54   VALUES(%Q)", zT
12a70 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65  ext);.**  sqlite
12a80 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c  3_exec(db, zSQL,
12a90 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73   0, 0, 0);.**  s
12aa0 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c  qlite3_free(zSQL
12ab0 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
12ac0 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
12ad0 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77  The code above w
12ae0 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72  ill render a cor
12af0 72 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65  rect SQL stateme
12b00 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a  nt in the zSQL.*
12b10 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20  * variable even 
12b20 69 66 20 74 68 65 20 7a 54 65 78 74 20 76 61 72  if the zText var
12b30 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20  iable is a NULL 
12b40 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54  pointer..**.** T
12b50 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69  he "%z" formatti
12b60 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20  ng option works 
12b70 65 78 61 63 74 6c 79 20 6c 69 6b 65 20 22 25 73  exactly like "%s
12b80 22 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 61 64  " with the.** ad
12b90 64 69 74 69 6f 6e 20 74 68 61 74 20 61 66 74 65  dition that afte
12ba0 72 20 74 68 65 20 73 74 72 69 6e 67 20 68 61 73  r the string has
12bb0 20 62 65 65 6e 20 72 65 61 64 20 61 6e 64 20 63   been read and c
12bc0 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68  opied into.** th
12bd0 65 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74  e result, [sqlit
12be0 65 33 5f 66 72 65 65 28 29 5d 20 69 73 20 63 61  e3_free()] is ca
12bf0 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e 70 75  lled on the inpu
12c00 74 20 73 74 72 69 6e 67 2e 20 7b 45 4e 44 7d 0a  t string. {END}.
12c10 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
12c20 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 34 30 33 7d  :.**.** {F17403}
12c30 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d    The [sqlite3_m
12c40 70 72 69 6e 74 66 28 29 5d 20 61 6e 64 20 5b 73  printf()] and [s
12c50 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28  qlite3_vmprintf(
12c60 29 5d 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  )] interfaces.**
12c70 20 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72             retur
12c80 6e 20 65 69 74 68 65 72 20 70 6f 69 6e 74 65 72  n either pointer
12c90 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  s to zero-termin
12ca0 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e  ated UTF-8 strin
12cb0 67 73 20 68 65 6c 64 20 69 6e 0a 2a 2a 20 20 20  gs held in.**   
12cc0 20 20 20 20 20 20 20 20 6d 65 6d 6f 72 79 20 6f          memory o
12cd0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
12ce0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
12cf0 6f 72 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73  or NULL pointers
12d00 20 69 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   if.**          
12d10 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69   a call to [sqli
12d20 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66 61  te3_malloc()] fa
12d30 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 34  ils..**.** {F174
12d40 30 36 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65  06}  The [sqlite
12d50 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 6e  3_snprintf()] in
12d60 74 65 72 66 61 63 65 20 77 72 69 74 65 73 20 61  terface writes a
12d70 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
12d80 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 55 54  .**           UT
12d90 46 2d 38 20 73 74 72 69 6e 67 20 69 6e 74 6f 20  F-8 string into 
12da0 74 68 65 20 62 75 66 66 65 72 20 70 6f 69 6e 74  the buffer point
12db0 65 64 20 74 6f 20 62 79 20 74 68 65 20 73 65 63  ed to by the sec
12dc0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  ond parameter.**
12dd0 20 20 20 20 20 20 20 20 20 20 20 70 72 6f 76 69             provi
12de0 64 65 64 20 74 68 61 74 20 74 68 65 20 66 69 72  ded that the fir
12df0 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  st parameter is 
12e00 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72  greater than zer
12e10 6f 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 34 30 37  o..**.** {F17407
12e20 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  }  The [sqlite3_
12e30 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 6e 74 65  snprintf()] inte
12e40 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 20 77  rface does not w
12e50 72 69 74 65 73 20 73 6c 6f 74 73 20 6f 66 0a 2a  rites slots of.*
12e60 2a 20 20 20 20 20 20 20 20 20 20 20 69 74 73 20  *           its 
12e70 6f 75 74 70 75 74 20 62 75 66 66 65 72 20 28 74  output buffer (t
12e80 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
12e90 74 65 72 29 20 6f 75 74 73 69 64 65 20 74 68 65  ter) outside the
12ea0 20 72 61 6e 67 65 0a 2a 2a 20 20 20 20 20 20 20   range.**       
12eb0 20 20 20 20 6f 66 20 30 20 74 68 72 6f 75 67 68      of 0 through
12ec0 20 4e 2d 31 20 28 77 68 65 72 65 20 4e 20 69 73   N-1 (where N is
12ed0 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
12ee0 65 74 65 72 29 0a 2a 2a 20 20 20 20 20 20 20 20  eter).**        
12ef0 20 20 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66     regardless of
12f00 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74   the length of t
12f10 68 65 20 73 74 72 69 6e 67 0a 2a 2a 20 20 20 20  he string.**    
12f20 20 20 20 20 20 20 20 72 65 71 75 65 73 74 65 64         requested
12f30 20 62 79 20 74 68 65 20 66 6f 72 6d 61 74 20 73   by the format s
12f40 70 65 63 69 66 69 63 61 74 69 6f 6e 2e 0a 2a 2a  pecification..**
12f50 20 20 20 0a 2a 2f 0a 63 68 61 72 20 2a 73 71 6c     .*/.char *sql
12f60 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e  ite3_mprintf(con
12f70 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63  st char*,...);.c
12f80 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70  har *sqlite3_vmp
12f90 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72  rintf(const char
12fa0 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 63 68 61  *, va_list);.cha
12fb0 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  r *sqlite3_snpri
12fc0 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f  ntf(int,char*,co
12fd0 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b  nst char*, ...);
12fe0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
12ff0 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74  : Memory Allocat
13000 69 6f 6e 20 53 75 62 73 79 73 74 65 6d 20 7b 46  ion Subsystem {F
13010 31 37 33 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  17300}.**.** The
13020 20 53 51 4c 69 74 65 20 63 6f 72 65 20 20 75 73   SQLite core  us
13030 65 73 20 74 68 65 73 65 20 74 68 72 65 65 20 72  es these three r
13040 6f 75 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20  outines for all 
13050 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e  of its own.** in
13060 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c  ternal memory al
13070 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20  location needs. 
13080 22 43 6f 72 65 22 20 69 6e 20 74 68 65 20 70 72  "Core" in the pr
13090 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a  evious sentence.
130a0 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c  ** does not incl
130b0 75 64 65 20 6f 70 65 72 61 74 69 6e 67 2d 73 79  ude operating-sy
130c0 73 74 65 6d 20 73 70 65 63 69 66 69 63 20 56 46  stem specific VF
130d0 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
130e0 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77  .  The.** Window
130f0 73 20 56 46 53 20 75 73 65 73 20 6e 61 74 69 76  s VFS uses nativ
13100 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66  e malloc() and f
13110 72 65 65 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f  ree() for some o
13120 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  perations..**.**
13130 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c   The sqlite3_mal
13140 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 72 65  loc() routine re
13150 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
13160 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66  to a block.** of
13170 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61 73 74   memory at least
13180 20 4e 20 62 79 74 65 73 20 69 6e 20 6c 65 6e 67   N bytes in leng
13190 74 68 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74  th, where N is t
131a0 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  he parameter..**
131b0 20 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c   If sqlite3_mall
131c0 6f 63 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74  oc() is unable t
131d0 6f 20 6f 62 74 61 69 6e 20 73 75 66 66 69 63 69  o obtain suffici
131e0 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f  ent free.** memo
131f0 72 79 2c 20 69 74 20 72 65 74 75 72 6e 73 20 61  ry, it returns a
13200 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
13210 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  If the parameter
13220 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33   N to.** sqlite3
13230 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72  _malloc() is zer
13240 6f 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 68  o or negative th
13250 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  en sqlite3_mallo
13260 63 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61  c() returns.** a
13270 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
13280 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20 73 71 6c  *.** Calling sql
13290 69 74 65 33 5f 66 72 65 65 28 29 20 77 69 74 68  ite3_free() with
132a0 20 61 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69   a pointer previ
132b0 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a  ously returned.*
132c0 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c  * by sqlite3_mal
132d0 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33  loc() or sqlite3
132e0 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61  _realloc() relea
132f0 73 65 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20  ses that memory 
13300 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69  so.** that it mi
13310 67 68 74 20 62 65 20 72 65 75 73 65 64 2e 20 20  ght be reused.  
13320 54 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65 65  The sqlite3_free
13330 28 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a  () routine is.**
13340 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63   a no-op if is c
13350 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c  alled with a NUL
13360 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73 73  L pointer.  Pass
13370 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ing a NULL point
13380 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33  er.** to sqlite3
13390 5f 66 72 65 65 28 29 20 69 73 20 68 61 72 6d 6c  _free() is harml
133a0 65 73 73 2e 20 20 41 66 74 65 72 20 62 65 69 6e  ess.  After bein
133b0 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a  g freed, memory.
133c0 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68 65  ** should neithe
133d0 72 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77 72  r be read nor wr
133e0 69 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65 61  itten.  Even rea
133f0 64 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79 20  ding previously 
13400 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20  freed.** memory 
13410 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e 20  might result in 
13420 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66  a segmentation f
13430 61 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73 65  ault or other se
13440 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d  vere error..** M
13450 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f 6e  emory corruption
13460 2c 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e  , a segmentation
13470 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72   fault, or other
13480 20 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a   severe error.**
13490 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 66   might result if
134a0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
134b0 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61  is called with a
134c0 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65   non-NULL pointe
134d0 72 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f  r that.** was no
134e0 74 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  t obtained from 
134f0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
13500 20 6f 72 20 73 71 6c 69 74 65 33 5f 66 72 65 65   or sqlite3_free
13510 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ()..**.** The sq
13520 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
13530 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70  interface attemp
13540 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a  ts to resize a.*
13550 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61  * prior memory a
13560 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20  llocation to be 
13570 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73  at least N bytes
13580 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  , where N is the
13590 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  .** second param
135a0 65 74 65 72 2e 20 20 54 68 65 20 6d 65 6d 6f 72  eter.  The memor
135b0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20  y allocation to 
135c0 62 65 20 72 65 73 69 7a 65 64 20 69 73 20 74 68  be resized is th
135d0 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d  e first.** param
135e0 65 74 65 72 2e 20 20 49 66 20 74 68 65 20 66 69  eter.  If the fi
135f0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
13600 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
13610 28 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20  ().** is a NULL 
13620 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73  pointer then its
13630 20 62 65 68 61 76 69 6f 72 20 69 73 20 69 64 65   behavior is ide
13640 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e  ntical to callin
13650 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c  g.** sqlite3_mal
13660 6c 6f 63 28 4e 29 20 77 68 65 72 65 20 4e 20 69  loc(N) where N i
13670 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  s the second par
13680 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
13690 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20  3_realloc()..** 
136a0 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  If the second pa
136b0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
136c0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 73 20  e3_realloc() is 
136d0 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74  zero or.** negat
136e0 69 76 65 20 74 68 65 6e 20 74 68 65 20 62 65 68  ive then the beh
136f0 61 76 69 6f 72 20 69 73 20 65 78 61 63 74 6c 79  avior is exactly
13700 20 74 68 65 20 73 61 6d 65 20 61 73 20 63 61 6c   the same as cal
13710 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ling.** sqlite3_
13720 66 72 65 65 28 50 29 20 77 68 65 72 65 20 50 20  free(P) where P 
13730 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72  is the first par
13740 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
13750 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20  3_realloc()..** 
13760 53 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  Sqlite3_realloc(
13770 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  ) returns a poin
13780 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20  ter to a memory 
13790 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66  allocation.** of
137a0 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65   at least N byte
137b0 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c  s in size or NUL
137c0 4c 20 69 66 20 73 75 66 66 69 63 69 65 6e 74 20  L if sufficient 
137d0 6d 65 6d 6f 72 79 20 69 73 20 75 6e 61 76 61 69  memory is unavai
137e0 6c 61 62 6c 65 2e 0a 2a 2a 20 49 66 20 4d 20 69  lable..** If M i
137f0 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  s the size of th
13800 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  e prior allocati
13810 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d  on, then min(N,M
13820 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74 68  ) bytes.** of th
13830 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  e prior allocati
13840 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 20 69 6e  on are copied in
13850 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67  to the beginning
13860 20 6f 66 20 62 75 66 66 65 72 20 72 65 74 75 72   of buffer retur
13870 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65  ned.** by sqlite
13880 33 5f 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20  3_realloc() and 
13890 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  the prior alloca
138a0 74 69 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a  tion is freed..*
138b0 2a 20 49 66 20 73 71 6c 69 74 65 33 5f 72 65 61  * If sqlite3_rea
138c0 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20 4e  lloc() returns N
138d0 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 70 72  ULL, then the pr
138e0 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  ior allocation.*
138f0 2a 20 69 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a  * is not freed..
13900 2a 2a 0a 2a 2a 20 54 68 65 20 6d 65 6d 6f 72 79  **.** The memory
13910 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
13920 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 61 6e  ite3_malloc() an
13930 64 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  d sqlite3_reallo
13940 63 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73  c().** is always
13950 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 74 20 6c   aligned to at l
13960 65 61 73 74 20 61 6e 20 38 20 62 79 74 65 20 62  east an 8 byte b
13970 6f 75 6e 64 61 72 79 2e 20 7b 45 4e 44 7d 0a 2a  oundary. {END}.*
13980 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74  *.** The default
13990 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a   implementation.
139a0 2a 2a 20 6f 66 20 74 68 65 20 6d 65 6d 6f 72 79  ** of the memory
139b0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73   allocation subs
139c0 79 73 74 65 6d 20 75 73 65 73 20 74 68 65 20 6d  ystem uses the m
139d0 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63  alloc(), realloc
139e0 28 29 0a 2a 2a 20 61 6e 64 20 66 72 65 65 28 29  ().** and free()
139f0 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 65   provided by the
13a00 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
13a10 61 72 79 2e 20 7b 46 31 37 33 38 32 7d 20 48 6f  ary. {F17382} Ho
13a20 77 65 76 65 72 2c 20 69 66 20 0a 2a 2a 20 53 51  wever, if .** SQ
13a30 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
13a40 20 77 69 74 68 20 74 68 65 20 66 6f 6c 6c 6f 77   with the follow
13a50 69 6e 67 20 43 20 70 72 65 70 72 6f 63 65 73 73  ing C preprocess
13a60 6f 72 20 6d 61 63 72 6f 0a 2a 2a 0a 2a 2a 20 3c  or macro.**.** <
13a70 62 6c 6f 63 6b 71 75 6f 74 65 3e 20 53 51 4c 49  blockquote> SQLI
13a80 54 45 5f 4d 45 4d 4f 52 59 5f 53 49 5a 45 3d 3c  TE_MEMORY_SIZE=<
13a90 69 3e 4e 4e 4e 3c 2f 69 3e 20 3c 2f 62 6c 6f 63  i>NNN</i> </bloc
13aa0 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 77 68  kquote>.**.** wh
13ab0 65 72 65 20 3c 69 3e 4e 4e 4e 3c 2f 69 3e 20 69  ere <i>NNN</i> i
13ac0 73 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68  s an integer, th
13ad0 65 6e 20 53 51 4c 69 74 65 20 63 72 65 61 74 65  en SQLite create
13ae0 20 61 20 73 74 61 74 69 63 0a 2a 2a 20 61 72 72   a static.** arr
13af0 61 79 20 6f 66 20 61 74 20 6c 65 61 73 74 20 3c  ay of at least <
13b00 69 3e 4e 4e 4e 3c 2f 69 3e 20 62 79 74 65 73 20  i>NNN</i> bytes 
13b10 69 6e 20 73 69 7a 65 20 61 6e 64 20 75 73 65 20  in size and use 
13b20 74 68 61 74 20 61 72 72 61 79 0a 2a 2a 20 66 6f  that array.** fo
13b30 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e  r all of its dyn
13b40 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  amic memory allo
13b50 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 7b 45  cation needs. {E
13b60 4e 44 7d 20 20 41 64 64 69 74 69 6f 6e 61 6c 0a  ND}  Additional.
13b70 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ** memory alloca
13b80 74 6f 72 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20  tor options may 
13b90 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
13ba0 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a  re releases..**.
13bb0 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 65 72  ** In SQLite ver
13bc0 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33  sion 3.5.0 and 3
13bd0 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 73  .5.1, it was pos
13be0 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a  sible to define.
13bf0 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d  ** the SQLITE_OM
13c00 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41  IT_MEMORY_ALLOCA
13c10 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c 64  TION which would
13c20 20 63 61 75 73 65 20 74 68 65 20 62 75 69 6c 74   cause the built
13c30 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  -in.** implement
13c40 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 72  ation of these r
13c50 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d  outines to be om
13c60 69 74 74 65 64 2e 20 20 54 68 61 74 20 63 61 70  itted.  That cap
13c70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f  ability.** is no
13c80 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 64   longer provided
13c90 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e  .  Only built-in
13ca0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
13cb0 72 73 20 63 61 6e 20 62 65 0a 2a 2a 20 75 73 65  rs can be.** use
13cc0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 57 69 6e  d..**.** The Win
13cd0 64 6f 77 73 20 4f 53 20 69 6e 74 65 72 66 61 63  dows OS interfac
13ce0 65 20 6c 61 79 65 72 20 63 61 6c 6c 73 0a 2a 2a  e layer calls.**
13cf0 20 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c   the system mall
13d00 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20  oc() and free() 
13d10 64 69 72 65 63 74 6c 79 20 77 68 65 6e 20 63 6f  directly when co
13d20 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65  nverting.** file
13d30 6e 61 6d 65 73 20 62 65 74 77 65 65 6e 20 74 68  names between th
13d40 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67  e UTF-8 encoding
13d50 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 0a   used by SQLite.
13d60 2a 2a 20 61 6e 64 20 77 68 61 74 65 76 65 72 20  ** and whatever 
13d70 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e  filename encodin
13d80 67 20 69 73 20 75 73 65 64 20 62 79 20 74 68 65  g is used by the
13d90 20 70 61 72 74 69 63 75 6c 61 72 20 57 69 6e 64   particular Wind
13da0 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74  ows.** installat
13db0 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c  ion.  Memory all
13dc0 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 61  ocation errors a
13dd0 72 65 20 64 65 74 65 63 74 65 64 2c 20 62 75 74  re detected, but
13de0 0a 2a 2a 20 74 68 65 79 20 61 72 65 20 72 65 70  .** they are rep
13df0 6f 72 74 65 64 20 62 61 63 6b 20 61 73 20 5b 53  orted back as [S
13e00 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20  QLITE_CANTOPEN] 
13e10 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f  or.** [SQLITE_IO
13e20 45 52 52 5d 20 72 61 74 68 65 72 20 74 68 61 6e  ERR] rather than
13e30 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e   [SQLITE_NOMEM].
13e40 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
13e50 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 30 33  S:.**.** {F17303
13e60 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  }  The [sqlite3_
13e70 6d 61 6c 6c 6f 63 28 4e 29 5d 20 69 6e 74 65 72  malloc(N)] inter
13e80 66 61 63 65 20 72 65 74 75 72 6e 73 20 65 69 74  face returns eit
13e90 68 65 72 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  her a pointer to
13ea0 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6e   .**           n
13eb0 65 77 6c 79 20 63 68 65 63 6b 65 64 2d 6f 75 74  ewly checked-out
13ec0 20 62 6c 6f 63 6b 20 6f 66 20 61 74 20 6c 65 61   block of at lea
13ed0 73 74 20 4e 20 62 79 74 65 73 20 6f 66 20 6d 65  st N bytes of me
13ee0 6d 6f 72 79 0a 2a 2a 20 20 20 20 20 20 20 20 20  mory.**         
13ef0 20 20 74 68 61 74 20 69 73 20 38 2d 62 79 74 65    that is 8-byte
13f00 20 61 6c 69 67 6e 65 64 2c 20 0a 2a 2a 20 20 20   aligned, .**   
13f10 20 20 20 20 20 20 20 20 6f 72 20 69 74 20 72 65          or it re
13f20 74 75 72 6e 73 20 4e 55 4c 4c 20 69 66 20 69 74  turns NULL if it
13f30 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 66 75   is unable to fu
13f40 6c 66 69 6c 6c 20 74 68 65 20 72 65 71 75 65 73  lfill the reques
13f50 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 30 34  t..**.** {F17304
13f60 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  }  The [sqlite3_
13f70 6d 61 6c 6c 6f 63 28 4e 29 5d 20 69 6e 74 65 72  malloc(N)] inter
13f80 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 4e  face returns a N
13f90 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 0a 2a  ULL pointer if.*
13fa0 2a 20 20 20 20 20 20 20 20 20 20 20 4e 20 69 73  *           N is
13fb0 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71   less than or eq
13fc0 75 61 6c 20 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a  ual to zero..**.
13fd0 2a 2a 20 7b 46 31 37 33 30 35 7d 20 20 54 68 65  ** {F17305}  The
13fe0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 50   [sqlite3_free(P
13ff0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 6c  )] interface rel
14000 65 61 73 65 73 20 6d 65 6d 6f 72 79 20 70 72 65  eases memory pre
14010 76 69 6f 75 73 6c 79 0a 2a 2a 20 20 20 20 20 20  viously.**      
14020 20 20 20 20 20 72 65 74 75 72 6e 65 64 20 66 72       returned fr
14030 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
14040 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  oc()] or [sqlite
14050 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a  3_realloc()],.**
14060 20 20 20 20 20 20 20 20 20 20 20 6d 61 6b 69 6e             makin
14070 67 20 69 74 20 61 76 61 69 6c 61 62 6c 65 20 66  g it available f
14080 6f 72 20 72 65 75 73 65 2e 0a 2a 2a 0a 2a 2a 20  or reuse..**.** 
14090 7b 46 31 37 33 30 36 7d 20 20 41 20 63 61 6c 6c  {F17306}  A call
140a0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65   to [sqlite3_fre
140b0 65 28 4e 55 4c 4c 29 5d 20 69 73 20 61 20 68 61  e(NULL)] is a ha
140c0 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a  rmless no-op..**
140d0 0a 2a 2a 20 7b 46 31 37 33 31 30 7d 20 20 41 20  .** {F17310}  A 
140e0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
140f0 5f 72 65 61 6c 6c 6f 63 28 30 2c 4e 29 5d 20 69  _realloc(0,N)] i
14100 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20  s equivalent to 
14110 61 20 63 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20  a call.**       
14120 20 20 20 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f      to [sqlite3_
14130 6d 61 6c 6c 6f 63 28 4e 29 5d 2e 0a 2a 2a 0a 2a  malloc(N)]..**.*
14140 2a 20 7b 46 31 37 33 31 32 7d 20 20 41 20 63 61  * {F17312}  A ca
14150 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  ll to [sqlite3_r
14160 65 61 6c 6c 6f 63 28 50 2c 30 29 5d 20 69 73 20  ealloc(P,0)] is 
14170 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 61 20  equivalent to a 
14180 63 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20  call.**         
14190 20 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72    to [sqlite3_fr
141a0 65 65 28 50 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46  ee(P)]..**.** {F
141b0 31 37 33 31 35 7d 20 20 54 68 65 20 53 51 4c 69  17315}  The SQLi
141c0 74 65 20 63 6f 72 65 20 75 73 65 73 20 5b 73 71  te core uses [sq
141d0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c  lite3_malloc()],
141e0 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
141f0 63 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  c()],.**        
14200 20 20 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f     and [sqlite3_
14210 66 72 65 65 28 29 5d 20 66 6f 72 20 61 6c 6c 20  free()] for all 
14220 6f 66 20 69 74 73 20 6d 65 6d 6f 72 79 20 61 6c  of its memory al
14230 6c 6f 63 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20  location and.** 
14240 20 20 20 20 20 20 20 20 20 20 64 65 61 6c 6c 6f            deallo
14250 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a  cation needs..**
14260 0a 2a 2a 20 7b 46 31 37 33 31 38 7d 20 20 54 68  .** {F17318}  Th
14270 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  e [sqlite3_reall
14280 6f 63 28 50 2c 4e 29 5d 20 69 6e 74 65 72 66 61  oc(P,N)] interfa
14290 63 65 20 72 65 74 75 72 6e 73 20 65 69 74 68 65  ce returns eithe
142a0 72 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 20  r a pointer.**  
142b0 20 20 20 20 20 20 20 20 20 74 6f 20 61 20 62 6c           to a bl
142c0 6f 63 6b 20 6f 66 20 63 68 65 63 6b 65 64 2d 6f  ock of checked-o
142d0 75 74 20 6d 65 6d 6f 72 79 20 6f 66 20 61 74 20  ut memory of at 
142e0 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e  least N bytes in
142f0 20 73 69 7a 65 0a 2a 2a 20 20 20 20 20 20 20 20   size.**        
14300 20 20 20 74 68 61 74 20 69 73 20 38 2d 62 79 74     that is 8-byt
14310 65 20 61 6c 69 67 6e 65 64 2c 20 6f 72 20 61 20  e aligned, or a 
14320 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
14330 0a 2a 2a 20 7b 46 31 37 33 32 31 7d 20 20 57 68  .** {F17321}  Wh
14340 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  en [sqlite3_real
14350 6c 6f 63 28 50 2c 4e 29 5d 20 72 65 74 75 72 6e  loc(P,N)] return
14360 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69  s a non-NULL poi
14370 6e 74 65 72 2c 20 69 74 20 66 69 72 73 74 0a 2a  nter, it first.*
14380 2a 20 20 20 20 20 20 20 20 20 20 20 63 6f 70 69  *           copi
14390 65 73 20 74 68 65 20 66 69 72 73 74 20 4b 20 62  es the first K b
143a0 79 74 65 73 20 6f 66 20 63 6f 6e 74 65 6e 74 20  ytes of content 
143b0 66 72 6f 6d 20 50 20 69 6e 74 6f 20 74 68 65 20  from P into the 
143c0 6e 65 77 6c 79 20 61 6c 6c 6f 63 61 74 65 64 0a  newly allocated.
143d0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 77 68 65  **           whe
143e0 72 65 20 4b 20 69 73 20 74 68 65 20 6c 65 73 73  re K is the less
143f0 65 72 20 6f 66 20 4e 20 61 6e 64 20 74 68 65 20  er of N and the 
14400 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66  size of the buff
14410 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37  er P..**.** {F17
14420 33 32 32 7d 20 20 57 68 65 6e 20 5b 73 71 6c 69  322}  When [sqli
14430 74 65 33 5f 72 65 61 6c 6c 6f 63 28 50 2c 4e 29  te3_realloc(P,N)
14440 5d 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d  ] returns a non-
14450 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 74  NULL pointer, it
14460 20 66 69 72 73 74 0a 2a 2a 20 20 20 20 20 20 20   first.**       
14470 20 20 20 20 72 65 6c 65 61 73 65 73 20 74 68 65      releases the
14480 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a   buffer P..**.**
14490 20 7b 46 31 37 33 32 33 7d 20 20 57 68 65 6e 20   {F17323}  When 
144a0 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
144b0 28 50 2c 4e 29 5d 20 72 65 74 75 72 6e 73 20 4e  (P,N)] returns N
144c0 55 4c 4c 2c 20 74 68 65 20 62 75 66 66 65 72 20  ULL, the buffer 
144d0 50 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  P is.**         
144e0 20 20 6e 6f 74 20 6d 6f 64 69 66 69 65 64 20 6f    not modified o
144f0 72 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a  r released..**.*
14500 2a 20 4c 49 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a  * LIMITATIONS:.*
14510 2a 0a 2a 2a 20 7b 55 31 37 33 35 30 7d 20 20 54  *.** {U17350}  T
14520 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d  he pointer argum
14530 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  ents to [sqlite3
14540 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71  _free()] and [sq
14550 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
14560 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6d 75  .**           mu
14570 73 74 20 62 65 20 65 69 74 68 65 72 20 4e 55 4c  st be either NUL
14580 4c 20 6f 72 20 65 6c 73 65 20 61 20 70 6f 69 6e  L or else a poin
14590 74 65 72 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ter obtained fro
145a0 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20 20 20 20  m a prior.**    
145b0 20 20 20 20 20 20 20 69 6e 76 6f 63 61 74 69 6f         invocatio
145c0 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61  n of [sqlite3_ma
145d0 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69  lloc()] or [sqli
145e0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 74  te3_realloc()] t
145f0 68 61 74 20 68 61 73 0a 2a 2a 20 20 20 20 20 20  hat has.**      
14600 20 20 20 20 20 6e 6f 74 20 62 65 65 6e 20 72 65       not been re
14610 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 55  leased..**.** {U
14620 31 37 33 35 31 7d 20 20 54 68 65 20 61 70 70 6c  17351}  The appl
14630 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
14640 20 72 65 61 64 20 6f 72 20 77 72 69 74 65 20 61   read or write a
14650 6e 79 20 70 61 72 74 20 6f 66 20 0a 2a 2a 20 20  ny part of .**  
14660 20 20 20 20 20 20 20 20 20 61 20 62 6c 6f 63 6b           a block
14670 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 72   of memory after
14680 20 69 74 20 68 61 73 20 62 65 65 6e 20 72 65 6c   it has been rel
14690 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20  eased using.**  
146a0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
146b0 33 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 71  3_free()] or [sq
146c0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
146d0 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  ..**.*/.void *sq
146e0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74  lite3_malloc(int
146f0 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  );.void *sqlite3
14700 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20  _realloc(void*, 
14710 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  int);.void sqlit
14720 65 33 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a  e3_free(void*);.
14730 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
14740 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f   Memory Allocato
14750 72 20 53 74 61 74 69 73 74 69 63 73 20 7b 46 31  r Statistics {F1
14760 37 33 37 30 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  7370}.**.** SQLi
14770 74 65 20 70 72 6f 76 69 64 65 73 20 74 68 65 73  te provides thes
14780 65 20 74 77 6f 20 69 6e 74 65 72 66 61 63 65 73  e two interfaces
14790 20 66 6f 72 20 72 65 70 6f 72 74 69 6e 67 20 6f   for reporting o
147a0 6e 20 74 68 65 20 73 74 61 74 75 73 0a 2a 2a 20  n the status.** 
147b0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
147c0 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69  malloc()], [sqli
147d0 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64  te3_free()], and
147e0 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
147f0 63 28 29 5d 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f  c()].** the memo
14800 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75  ry allocation su
14810 62 73 79 73 74 65 6d 20 69 6e 63 6c 75 64 65 64  bsystem included
14820 20 77 69 74 68 69 6e 20 74 68 65 20 53 51 4c 69   within the SQLi
14830 74 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  te..**.** INVARI
14840 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 37  ANTS:.**.** {F17
14850 33 37 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  371} The [sqlite
14860 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
14870 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
14880 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
14890 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
148a0 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72 72 65   of memory curre
148b0 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e 67  ntly outstanding
148c0 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 28 6d   .**          (m
148d0 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f 74 20  alloced but not 
148e0 66 72 65 65 64 29 2e 0a 2a 2a 0a 2a 2a 20 7b 46  freed)..**.** {F
148f0 31 37 33 37 33 7d 20 54 68 65 20 5b 73 71 6c 69  17373} The [sqli
14900 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
14910 61 74 65 72 28 29 5d 20 72 6f 75 74 69 6e 65 20  ater()] routine 
14920 72 65 74 75 72 6e 73 20 74 68 65 20 6d 61 78 69  returns the maxi
14930 6d 75 6d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  mum.**          
14940 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65  value of [sqlite
14950 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
14960 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 69   .**          si
14970 6e 63 65 20 74 68 65 20 68 69 67 68 2d 77 61 74  nce the high-wat
14980 65 72 20 6d 61 72 6b 20 77 61 73 20 6c 61 73 74  er mark was last
14990 20 72 65 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46   reset..**.** {F
149a0 31 37 33 37 34 7d 20 54 68 65 20 76 61 6c 75 65  17374} The value
149b0 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  s returned by [s
149c0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
149d0 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 20 20 20  ed()] and.**    
149e0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6d        [sqlite3_m
149f0 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
14a00 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f  )] include any o
14a10 76 65 72 68 65 61 64 0a 2a 2a 20 20 20 20 20 20  verhead.**      
14a20 20 20 20 20 61 64 64 65 64 20 62 79 20 53 51 4c      added by SQL
14a30 69 74 65 20 69 6e 20 69 74 73 20 69 6d 70 6c 65  ite in its imple
14a40 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71  mentation of [sq
14a50 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c  lite3_malloc()],
14a60 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 75 74  .**          but
14a70 20 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 61 64   not overhead ad
14a80 64 65 64 20 62 79 20 74 68 65 20 61 6e 79 20 75  ded by the any u
14a90 6e 64 65 72 6c 79 69 6e 67 20 73 79 73 74 65 6d  nderlying system
14aa0 20 6c 69 62 72 61 72 79 0a 2a 2a 20 20 20 20 20   library.**     
14ab0 20 20 20 20 20 72 6f 75 74 69 6e 65 73 20 74 68       routines th
14ac0 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  at [sqlite3_mall
14ad0 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a  oc()] may call..
14ae0 2a 2a 20 0a 2a 2a 20 7b 46 31 37 33 37 35 7d 20  ** .** {F17375} 
14af0 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d  The memory high-
14b00 77 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72 65  water mark is re
14b10 73 65 74 20 74 6f 20 74 68 65 20 63 75 72 72 65  set to the curre
14b20 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 20  nt value of.**  
14b30 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
14b40 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
14b50 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74  if and only if t
14b60 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  he parameter to.
14b70 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
14b80 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
14b90 77 61 74 65 72 28 29 5d 20 69 73 20 74 72 75 65  water()] is true
14ba0 2e 20 20 54 68 65 20 76 61 6c 75 65 20 72 65 74  .  The value ret
14bb0 75 72 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  urned.**        
14bc0 20 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65    by [sqlite3_me
14bd0 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 31  mory_highwater(1
14be0 29 5d 20 69 73 20 74 68 65 20 68 69 67 68 2d 77  )] is the high-w
14bf0 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 20 20 20  ater mark.**    
14c00 20 20 20 20 20 20 70 72 69 6f 72 20 74 6f 20 74        prior to t
14c10 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c  he reset..*/.sql
14c20 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
14c30 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76  e3_memory_used(v
14c40 6f 69 64 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e  oid);.sqlite3_in
14c50 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  t64 sqlite3_memo
14c60 72 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74  ry_highwater(int
14c70 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a   resetFlag);../*
14c80 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73  .** CAPI3REF: Ps
14c90 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62  eudo-Random Numb
14ca0 65 72 20 47 65 6e 65 72 61 74 6f 72 20 7b 46 31  er Generator {F1
14cb0 37 33 39 30 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  7390}.**.** SQLi
14cc0 74 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69  te contains a hi
14cd0 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64  gh-quality pseud
14ce0 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20  o-random number 
14cf0 67 65 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29  generator (PRNG)
14d00 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65   used to.** sele
14d10 63 74 20 72 61 6e 64 6f 6d 20 52 4f 57 49 44 73  ct random ROWIDs
14d20 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20   when inserting 
14d30 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f  new records into
14d40 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a   a table that.**
14d50 20 61 6c 72 65 61 64 79 20 75 73 65 73 20 74 68   already uses th
14d60 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62  e largest possib
14d70 6c 65 20 52 4f 57 49 44 2e 20 20 54 68 65 20 50  le ROWID.  The P
14d80 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 73 65 64  RNG is also used
14d90 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c   for.** the buil
14da0 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e  d-in random() an
14db0 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53  d randomblob() S
14dc0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54  QL functions.  T
14dd0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c  his interface al
14de0 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74  lows.** applicat
14df0 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 73 20 74  ions to access t
14e00 68 65 20 73 61 6d 65 20 50 52 4e 47 20 66 6f 72  he same PRNG for
14e10 20 6f 74 68 65 72 20 70 75 72 70 6f 73 65 73 2e   other purposes.
14e20 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f  .**.** A call to
14e30 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74   this routine st
14e40 6f 72 65 73 20 4e 20 62 79 74 65 73 20 6f 66 20  ores N bytes of 
14e50 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20  randomness into 
14e60 62 75 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20  buffer P..**.** 
14e70 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 74  The first time t
14e80 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 69  his routine is i
14e90 6e 76 6f 6b 65 64 20 28 65 69 74 68 65 72 20 69  nvoked (either i
14ea0 6e 74 65 72 6e 61 6c 6c 79 20 6f 72 20 62 79 0a  nternally or by.
14eb0 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
14ec0 6f 6e 29 20 74 68 65 20 50 52 4e 47 20 69 73 20  on) the PRNG is 
14ed0 73 65 65 64 65 64 20 75 73 69 6e 67 20 72 61 6e  seeded using ran
14ee0 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64  domness obtained
14ef0 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 78 52 61  .** from the xRa
14f00 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20  ndomness method 
14f10 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b  of the default [
14f20 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
14f30 65 63 74 2e 0a 2a 2a 20 4f 6e 20 61 6c 6c 20 73  ect..** On all s
14f40 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61  ubsequent invoca
14f50 74 69 6f 6e 73 2c 20 74 68 65 20 70 73 65 75 64  tions, the pseud
14f60 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20  o-randomness is 
14f70 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74  generated.** int
14f80 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68  ernally and with
14f90 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20  out recourse to 
14fa0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
14fb0 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a  ] xRandomness.**
14fc0 20 6d 65 74 68 6f 64 2e 0a 2a 2a 0a 2a 2a 20 49   method..**.** I
14fd0 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
14fe0 20 7b 46 31 37 33 39 32 7d 20 54 68 65 20 5b 73   {F17392} The [s
14ff0 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73  qlite3_randomnes
15000 73 28 4e 2c 50 29 5d 20 69 6e 74 65 72 66 61 63  s(N,P)] interfac
15010 65 20 77 72 69 74 65 73 20 4e 20 62 79 74 65 73  e writes N bytes
15020 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   of.**          
15030 68 69 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65  high-quality pse
15040 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69  udo-randomness i
15050 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2f  nto buffer P..*/
15060 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 61  .void sqlite3_ra
15070 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20  ndomness(int N, 
15080 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a  void *P);../*.**
15090 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69   CAPI3REF: Compi
150a0 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f 72 69 7a  le-Time Authoriz
150b0 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 20  ation Callbacks 
150c0 7b 46 31 32 35 30 30 7d 0a 2a 2a 0a 2a 2a 20 54  {F12500}.**.** T
150d0 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 67 69  his routine regi
150e0 73 74 65 72 73 20 61 20 61 75 74 68 6f 72 69 7a  sters a authoriz
150f0 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68  er callback with
15100 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a   a particular.**
15110 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
15120 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64  ction], supplied
15130 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
15140 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 61  gument..** The a
15150 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
15160 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73  ck is invoked as
15170 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
15180 61 72 65 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c  are being compil
15190 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65  ed.** by [sqlite
151a0 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20  3_prepare()] or 
151b0 69 74 73 20 76 61 72 69 61 6e 74 73 20 5b 73 71  its variants [sq
151c0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
151d0 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
151e0 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 61 6e  _prepare16()] an
151f0 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
15200 72 65 31 36 5f 76 32 28 29 5d 2e 20 20 41 74 20  re16_v2()].  At 
15210 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74  various.** point
15220 73 20 64 75 72 69 6e 67 20 74 68 65 20 63 6f 6d  s during the com
15230 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73 73  pilation process
15240 2c 20 61 73 20 6c 6f 67 69 63 20 69 73 20 62 65  , as logic is be
15250 69 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a 20 74  ing created.** t
15260 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75  o perform variou
15270 73 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 20 61  s actions, the a
15280 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
15290 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f  ck is invoked to
152a0 0a 2a 2a 20 73 65 65 20 69 66 20 74 68 6f 73 65  .** see if those
152b0 20 61 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c   actions are all
152c0 6f 77 65 64 2e 20 20 54 68 65 20 61 75 74 68 6f  owed.  The autho
152d0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 73  rizer callback s
152e0 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20  hould.** return 
152f0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61  [SQLITE_OK] to a
15300 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 6f 6e 2c  llow the action,
15310 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
15320 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68 65   to disallow the
15330 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 61 63 74  .** specific act
15340 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74 68  ion but allow th
15350 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
15360 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62  to continue to b
15370 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f  e.** compiled, o
15380 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20  r [SQLITE_DENY] 
15390 74 6f 20 63 61 75 73 65 20 74 68 65 20 65 6e 74  to cause the ent
153a0 69 72 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ire SQL statemen
153b0 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63  t to be.** rejec
153c0 74 65 64 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ted with an erro
153d0 72 2e 20 20 20 49 66 20 74 68 65 20 61 75 74 68  r.   If the auth
153e0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
153f0 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76  returns.** any v
15400 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20  alue other than 
15410 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c  [SQLITE_IGNORE],
15420 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72   [SQLITE_OK], or
15430 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a   [SQLITE_DENY].*
15440 2a 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f  * then [sqlite3_
15450 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
15460 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c   equivalent call
15470 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64 0a   that triggered.
15480 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  ** the authorize
15490 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68  r will fail with
154a0 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   an error messag
154b0 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  e..**.** When th
154c0 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
154d0 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20  ns [SQLITE_OK], 
154e0 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f  that means the o
154f0 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75  peration.** requ
15500 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 57 68  ested is ok.  Wh
15510 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  en the callback 
15520 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
15530 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73  DENY], the.** [s
15540 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
15550 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65  2()] or equivale
15560 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69  nt call that tri
15570 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61 75  ggered the.** au
15580 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61  thorizer will fa
15590 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  il with an error
155a0 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69 6e   message explain
155b0 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 65  ing that.** acce
155c0 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20 20 49  ss is denied.  I
155d0 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  f the authorizer
155e0 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45   code is [SQLITE
155f0 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68  _READ].** and th
15600 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
15610 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  ns [SQLITE_IGNOR
15620 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b  E] then the.** [
15630 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
15640 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73  nt] statement is
15650 20 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20   constructed to 
15660 73 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 20  substitute.** a 
15670 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c  NULL value in pl
15680 61 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65  ace of the table
15690 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75   column that wou
156a0 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20  ld have.** been 
156b0 72 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f  read if [SQLITE_
156c0 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74  OK] had been ret
156d0 75 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 4c  urned.  The [SQL
156e0 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72  ITE_IGNORE].** r
156f0 65 74 75 72 6e 20 63 61 6e 20 62 65 20 75 73 65  eturn can be use
15700 64 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74  d to deny an unt
15710 72 75 73 74 65 64 20 75 73 65 72 20 61 63 63 65  rusted user acce
15720 73 73 20 74 6f 20 69 6e 64 69 76 69 64 75 61 6c  ss to individual
15730 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61  .** columns of a
15740 20 74 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68   table..**.** Th
15750 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
15760 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69  r to the authori
15770 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
15780 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65  a copy of.** the
15790 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
157a0 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
157b0 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29  set_authorizer()
157c0 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 54   interface..** T
157d0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
157e0 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  ter to the callb
157f0 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ack is an intege
15800 72 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f  r .** [SQLITE_CO
15810 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65  PY | action code
15820 5d 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73  ] that specifies
15830 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20   the particular 
15840 61 63 74 69 6f 6e 0a 2a 2a 20 74 6f 20 62 65 20  action.** to be 
15850 61 75 74 68 6f 72 69 7a 65 64 2e 20 54 68 65 20  authorized. The 
15860 74 68 69 72 64 20 74 68 72 6f 75 67 68 20 73 69  third through si
15870 78 74 68 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  xth.** parameter
15880 73 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  s to the callbac
15890 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69  k are zero-termi
158a0 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68  nated strings th
158b0 61 74 20 63 6f 6e 74 61 69 6e 20 0a 2a 2a 20 61  at contain .** a
158c0 64 64 69 74 69 6f 6e 61 6c 20 64 65 74 61 69 6c  dditional detail
158d0 73 20 61 62 6f 75 74 20 74 68 65 20 61 63 74 69  s about the acti
158e0 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69  on to be authori
158f0 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75  zed..**.** An au
15900 74 68 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64  thorizer is used
15910 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70   when [sqlite3_p
15920 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 69  repare | prepari
15930 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  ng].** SQL state
15940 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e  ments from an un
15950 74 72 75 73 74 65 64 0a 2a 2a 20 73 6f 75 72 63  trusted.** sourc
15960 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61  e, to ensure tha
15970 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  t the SQL statem
15980 65 6e 74 73 20 64 6f 20 6e 6f 74 20 74 72 79 20  ents do not try 
15990 74 6f 20 61 63 63 65 73 73 20 64 61 74 61 0a 2a  to access data.*
159a0 2a 20 74 68 61 74 20 74 68 65 79 20 61 72 65 20  * that they are 
159b0 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73  not allowed to s
159c0 65 65 2c 20 6f 72 20 74 68 61 74 20 74 68 65 79  ee, or that they
159d0 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 0a 2a   do not try to.*
159e0 2a 20 65 78 65 63 75 74 65 20 6d 61 6c 69 63 69  * execute malici
159f0 6f 75 73 20 73 74 61 74 65 6d 65 6e 74 73 20 74  ous statements t
15a00 68 61 74 20 64 61 6d 61 67 65 20 74 68 65 20 64  hat damage the d
15a10 61 74 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a  atabase.  For.**
15a20 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70   example, an app
15a30 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c  lication may all
15a40 6f 77 20 61 20 75 73 65 72 20 74 6f 20 65 6e 74  ow a user to ent
15a50 65 72 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20  er arbitrary.** 
15a60 53 51 4c 20 71 75 65 72 69 65 73 20 66 6f 72 20  SQL queries for 
15a70 65 76 61 6c 75 61 74 69 6f 6e 20 62 79 20 61 20  evaluation by a 
15a80 64 61 74 61 62 61 73 65 2e 20 20 42 75 74 20 74  database.  But t
15a90 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
15aa0 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20  oes.** not want 
15ab0 74 68 65 20 75 73 65 72 20 74 6f 20 62 65 20 61  the user to be a
15ac0 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72 62 69  ble to make arbi
15ad0 74 72 61 72 79 20 63 68 61 6e 67 65 73 20 74 6f  trary changes to
15ae0 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
15af0 2e 20 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72  .  An authorizer
15b00 20 63 6f 75 6c 64 20 74 68 65 6e 20 62 65 20 70   could then be p
15b10 75 74 20 69 6e 20 70 6c 61 63 65 20 77 68 69 6c  ut in place whil
15b20 65 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e  e the.** user-en
15b30 74 65 72 65 64 20 53 51 4c 20 69 73 20 62 65 69  tered SQL is bei
15b40 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ng [sqlite3_prep
15b50 61 72 65 20 7c 20 70 72 65 70 61 72 65 64 5d 20  are | prepared] 
15b60 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77  that.** disallow
15b70 73 20 65 76 65 72 79 74 68 69 6e 67 20 65 78 63  s everything exc
15b80 65 70 74 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  ept [SELECT] sta
15b90 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41  tements..**.** A
15ba0 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
15bb0 20 6e 65 65 64 20 74 6f 20 70 72 6f 63 65 73 73   need to process
15bc0 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73   SQL from untrus
15bd0 74 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d  ted sources.** m
15be0 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64  ight also consid
15bf0 65 72 20 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f  er lowering reso
15c00 75 72 63 65 20 6c 69 6d 69 74 73 20 75 73 69 6e  urce limits usin
15c10 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  g [sqlite3_limit
15c20 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74  ()].** and limit
15c30 69 6e 67 20 64 61 74 61 62 61 73 65 20 73 69 7a  ing database siz
15c40 65 20 75 73 69 6e 67 20 74 68 65 20 5b 6d 61 78  e using the [max
15c50 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52  _page_count] [PR
15c60 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69  AGMA].** in addi
15c70 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e  tion to using an
15c80 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a   authorizer..**.
15c90 2a 2a 20 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65  ** Only a single
15ca0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6e 20   authorizer can 
15cb0 62 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61  be in place on a
15cc0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
15cd0 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d  tion.** at a tim
15ce0 65 2e 20 20 45 61 63 68 20 63 61 6c 6c 20 74 6f  e.  Each call to
15cf0 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74   sqlite3_set_aut
15d00 68 6f 72 69 7a 65 72 20 6f 76 65 72 72 69 64 65  horizer override
15d10 73 20 74 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75  s the.** previou
15d20 73 20 63 61 6c 6c 2e 20 20 44 69 73 61 62 6c 65  s call.  Disable
15d30 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
15d40 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20  by installing a 
15d50 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a  NULL callback..*
15d60 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * The authorizer
15d70 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20   is disabled by 
15d80 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 4e  default..**.** N
15d90 6f 74 65 20 74 68 61 74 20 74 68 65 20 61 75 74  ote that the aut
15da0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
15db0 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79   is invoked only
15dc0 20 64 75 72 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c   during .** [sql
15dd0 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
15de0 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e  or its variants.
15df0 20 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20    Authorization 
15e00 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72  is not.** perfor
15e10 6d 65 64 20 64 75 72 69 6e 67 20 73 74 61 74 65  med during state
15e20 6d 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20  ment evaluation 
15e30 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  in [sqlite3_step
15e40 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ()]..**.** INVAR
15e50 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31  IANTS:.**.** {F1
15e60 32 35 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  2501} The [sqlit
15e70 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
15e80 72 28 44 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66  r(D,...)] interf
15e90 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61 0a  ace registers a.
15ea0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 75 74 68  **          auth
15eb0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
15ec0 77 69 74 68 20 64 61 74 61 62 61 73 65 20 63 6f  with database co
15ed0 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a 2a 0a 2a  nnection D..**.*
15ee0 2a 20 7b 46 31 32 35 30 32 7d 20 54 68 65 20 61  * {F12502} The a
15ef0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
15f00 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73  ck is invoked as
15f10 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
15f20 61 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  are.**          
15f30 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a  being compiled.*
15f40 2a 0a 2a 2a 20 7b 46 31 32 35 30 33 7d 20 49 66  *.** {F12503} If
15f50 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
15f60 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
15f70 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72   any value other
15f80 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20   than.**        
15f90 20 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45    [SQLITE_IGNORE
15fa0 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20  ], [SQLITE_OK], 
15fb0 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d  or [SQLITE_DENY]
15fc0 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20   then.**        
15fd0 20 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70    the [sqlite3_p
15fe0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
15ff0 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20  equivalent call 
16000 74 68 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 20  that caused.**  
16010 20 20 20 20 20 20 20 20 74 68 65 20 61 75 74 68          the auth
16020 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
16030 74 6f 20 72 75 6e 20 73 68 61 6c 6c 20 66 61 69  to run shall fai
16040 6c 20 77 69 74 68 20 61 6e 0a 2a 2a 20 20 20 20  l with an.**    
16050 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 45 52        [SQLITE_ER
16060 52 4f 52 5d 20 65 72 72 6f 72 20 63 6f 64 65 20  ROR] error code 
16070 61 6e 64 20 61 6e 20 61 70 70 72 6f 70 72 69 61  and an appropria
16080 74 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  te error message
16090 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 30 34 7d  ..**.** {F12504}
160a0 20 57 68 65 6e 20 74 68 65 20 61 75 74 68 6f 72   When the author
160b0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65  izer callback re
160c0 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
160d0 5d 2c 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  ], the operation
160e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65 73  .**          des
160f0 63 72 69 62 65 64 20 69 73 20 63 6f 64 65 64 20  cribed is coded 
16100 6e 6f 72 6d 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20  normally..**.** 
16110 7b 46 31 32 35 30 35 7d 20 57 68 65 6e 20 74 68  {F12505} When th
16120 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
16130 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53  lback returns [S
16140 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65  QLITE_DENY], the
16150 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
16160 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
16170 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e  ()] or equivalen
16180 74 20 63 61 6c 6c 20 74 68 61 74 20 63 61 75 73  t call that caus
16190 65 64 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ed the.**       
161a0 20 20 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61     authorizer ca
161b0 6c 6c 62 61 63 6b 20 74 6f 20 72 75 6e 20 73 68  llback to run sh
161c0 61 6c 6c 20 66 61 69 6c 0a 2a 2a 20 20 20 20 20  all fail.**     
161d0 20 20 20 20 20 77 69 74 68 20 61 6e 20 5b 53 51       with an [SQ
161e0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 65 72 72 6f  LITE_ERROR] erro
161f0 72 20 63 6f 64 65 20 61 6e 64 20 61 6e 20 65 72  r code and an er
16200 72 6f 72 20 6d 65 73 73 61 67 65 0a 2a 2a 20 20  ror message.**  
16210 20 20 20 20 20 20 20 20 65 78 70 6c 61 69 6e 69          explaini
16220 6e 67 20 74 68 61 74 20 61 63 63 65 73 73 20 69  ng that access i
16230 73 20 64 65 6e 69 65 64 2e 0a 2a 2a 0a 2a 2a 20  s denied..**.** 
16240 7b 46 31 32 35 30 36 7d 20 49 66 20 74 68 65 20  {F12506} If the 
16250 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 64 65 20  authorizer code 
16260 28 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74  (the 2nd paramet
16270 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72  er to the author
16280 69 7a 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  izer.**         
16290 20 63 61 6c 6c 62 61 63 6b 29 20 69 73 20 5b 53   callback) is [S
162a0 51 4c 49 54 45 5f 52 45 41 44 5d 20 61 6e 64 20  QLITE_READ] and 
162b0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
162c0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a  allback returns.
162d0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c  **          [SQL
162e0 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e  ITE_IGNORE] then
162f0 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
16300 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74  atement is const
16310 72 75 63 74 65 64 20 74 6f 0a 2a 2a 20 20 20 20  ructed to.**    
16320 20 20 20 20 20 20 69 6e 73 65 72 74 20 61 20 4e        insert a N
16330 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61  ULL value in pla
16340 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20  ce of the table 
16350 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c  column that woul
16360 64 20 68 61 76 65 0a 2a 2a 20 20 20 20 20 20 20  d have.**       
16370 20 20 20 62 65 65 6e 20 72 65 61 64 20 69 66 20     been read if 
16380 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20  [SQLITE_OK] had 
16390 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 0a 2a  been returned..*
163a0 2a 0a 2a 2a 20 7b 46 31 32 35 30 37 7d 20 49 66  *.** {F12507} If
163b0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
163c0 63 6f 64 65 20 28 74 68 65 20 32 6e 64 20 70 61  code (the 2nd pa
163d0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61  rameter to the a
163e0 75 74 68 6f 72 69 7a 65 72 0a 2a 2a 20 20 20 20  uthorizer.**    
163f0 20 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 29 20        callback) 
16400 69 73 20 61 6e 79 74 68 69 6e 67 20 6f 74 68 65  is anything othe
16410 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52  r than [SQLITE_R
16420 45 41 44 5d 2c 20 74 68 65 6e 0a 2a 2a 20 20 20  EAD], then.**   
16430 20 20 20 20 20 20 20 61 20 72 65 74 75 72 6e 20         a return 
16440 6f 66 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  of [SQLITE_IGNOR
16450 45 5d 20 68 61 73 20 74 68 65 20 73 61 6d 65 20  E] has the same 
16460 65 66 66 65 63 74 20 61 73 20 5b 53 51 4c 49 54  effect as [SQLIT
16470 45 5f 44 45 4e 59 5d 2e 20 0a 2a 2a 0a 2a 2a 20  E_DENY]. .**.** 
16480 7b 46 31 32 35 31 30 7d 20 54 68 65 20 66 69 72  {F12510} The fir
16490 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
164a0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
164b0 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70  allback is a cop
164c0 79 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20  y of.**         
164d0 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
164e0 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c  eter to the [sql
164f0 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
16500 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65  zer()] interface
16510 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 31 31 7d  ..**.** {F12511}
16520 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
16530 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c  meter to the cal
16540 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65  lback is an inte
16550 67 65 72 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  ger .**         
16560 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20   [SQLITE_COPY | 
16570 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61  action code] tha
16580 74 20 73 70 65 63 69 66 69 65 73 20 74 68 65 20  t specifies the 
16590 70 61 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f  particular actio
165a0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f  n.**          to
165b0 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a   be authorized..
165c0 2a 2a 0a 2a 2a 20 7b 46 31 32 35 31 32 7d 20 54  **.** {F12512} T
165d0 68 65 20 74 68 69 72 64 20 74 68 72 6f 75 67 68  he third through
165e0 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72   sixth parameter
165f0 73 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  s to the callbac
16600 6b 20 61 72 65 0a 2a 2a 20 20 20 20 20 20 20 20  k are.**        
16610 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65    zero-terminate
16620 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 63  d strings that c
16630 6f 6e 74 61 69 6e 20 0a 2a 2a 20 20 20 20 20 20  ontain .**      
16640 20 20 20 20 61 64 64 69 74 69 6f 6e 61 6c 20 64      additional d
16650 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65  etails about the
16660 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75   action to be au
16670 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20  thorized..**.** 
16680 7b 46 31 32 35 32 30 7d 20 45 61 63 68 20 63 61  {F12520} Each ca
16690 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
166a0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d  et_authorizer()]
166b0 20 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a   overrides the.*
166c0 2a 20 20 20 20 20 20 20 20 20 20 61 6e 79 20 70  *          any p
166d0 72 65 76 69 6f 75 73 6c 79 20 69 6e 73 74 61 6c  reviously instal
166e0 6c 65 64 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a  led authorizer..
166f0 2a 2a 0a 2a 2a 20 7b 46 31 32 35 32 31 7d 20 41  **.** {F12521} A
16700 20 4e 55 4c 4c 20 61 75 74 68 6f 72 69 7a 65 72   NULL authorizer
16710 20 6d 65 61 6e 73 20 74 68 61 74 20 6e 6f 20 61   means that no a
16720 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20  uthorization.** 
16730 20 20 20 20 20 20 20 20 20 63 61 6c 6c 62 61 63           callbac
16740 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a  k is invoked..**
16750 0a 2a 2a 20 7b 46 31 32 35 32 32 7d 20 54 68 65  .** {F12522} The
16760 20 64 65 66 61 75 6c 74 20 61 75 74 68 6f 72 69   default authori
16770 7a 65 72 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2f 0a  zer is NULL..*/.
16780 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  int sqlite3_set_
16790 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 71  authorizer(.  sq
167a0 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a  lite3*,.  int (*
167b0 78 41 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74  xAuth)(void*,int
167c0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e  ,const char*,con
167d0 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  st char*,const c
167e0 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
167f0 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 72  ),.  void *pUser
16800 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  Data.);../*.** C
16810 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69  API3REF: Authori
16820 7a 65 72 20 52 65 74 75 72 6e 20 43 6f 64 65 73  zer Return Codes
16830 20 7b 46 31 32 35 39 30 7d 0a 2a 2a 0a 2a 2a 20   {F12590}.**.** 
16840 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  The [sqlite3_set
16850 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75  _authorizer | au
16860 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
16870 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74  k function] must
16880 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68 65  .** return eithe
16890 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72  r [SQLITE_OK] or
168a0 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74 77   one of these tw
168b0 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f  o constants in o
168c0 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61  rder.** to signa
168d0 6c 20 53 51 4c 69 74 65 20 77 68 65 74 68 65 72  l SQLite whether
168e0 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74 69   or not the acti
168f0 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 2e  on is permitted.
16900 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71    See the.** [sq
16910 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
16920 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65  izer | authorize
16930 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d  r documentation]
16940 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a   for additional.
16950 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  ** information..
16960 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
16970 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20  E_DENY   1   /* 
16980 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74  Abort the SQL st
16990 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20  atement with an 
169a0 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65  error */.#define
169b0 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32   SQLITE_IGNORE 2
169c0 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f     /* Don't allo
169d0 77 20 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f  w access, but do
169e0 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20  n't generate an 
169f0 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  error */../*.** 
16a00 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72  CAPI3REF: Author
16a10 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65  izer Action Code
16a20 73 20 7b 46 31 32 35 35 30 7d 0a 2a 2a 0a 2a 2a  s {F12550}.**.**
16a30 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65   The [sqlite3_se
16a40 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20  t_authorizer()] 
16a50 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74  interface regist
16a60 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66  ers a callback f
16a70 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20  unction.** that 
16a80 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75  is invoked to au
16a90 74 68 6f 72 69 7a 65 72 20 63 65 72 74 61 69 6e  thorizer certain
16aa0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61   SQL statement a
16ab0 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20  ctions.  The.** 
16ac0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
16ad0 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
16ae0 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63   is an integer c
16af0 6f 64 65 20 74 68 61 74 20 73 70 65 63 69 66 69  ode that specifi
16b00 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f  es.** what actio
16b10 6e 20 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f  n is being autho
16b20 72 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72  rized.  These ar
16b30 65 20 74 68 65 20 69 6e 74 65 67 65 72 20 61 63  e the integer ac
16b40 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a  tion codes that.
16b50 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  ** the authorize
16b60 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62  r callback may b
16b70 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  e passed..**.** 
16b80 54 68 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64  These action cod
16b90 65 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79  e values signify
16ba0 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70   what kind of op
16bb0 65 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65  eration is to be
16bc0 20 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e   .** authorized.
16bd0 20 20 54 68 65 20 33 72 64 20 61 6e 64 20 34 74    The 3rd and 4t
16be0 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  h parameters to 
16bf0 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f  the authorizatio
16c00 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75  n.** callback fu
16c10 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70  nction will be p
16c20 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c  arameters or NUL
16c30 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77  L depending on w
16c40 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a  hich of these.**
16c50 20 63 6f 64 65 73 20 69 73 20 75 73 65 64 20 61   codes is used a
16c60 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  s the second par
16c70 61 6d 65 74 65 72 2e 20 20 54 68 65 20 35 74 68  ameter.  The 5th
16c80 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
16c90 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20  e.** authorizer 
16ca0 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20  callback is the 
16cb0 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61  name of the data
16cc0 62 61 73 65 20 28 22 6d 61 69 6e 22 2c 20 22 74  base ("main", "t
16cd0 65 6d 70 22 2c 20 0a 2a 2a 20 65 74 63 2e 29 20  emp", .** etc.) 
16ce0 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 20 20  if applicable.  
16cf0 54 68 65 20 36 74 68 20 70 61 72 61 6d 65 74 65  The 6th paramete
16d00 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69  r to the authori
16d10 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  zer callback.** 
16d20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
16d30 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72  he inner-most tr
16d40 69 67 67 65 72 20 6f 72 20 76 69 65 77 20 74 68  igger or view th
16d50 61 74 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  at is responsibl
16d60 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63  e for.** the acc
16d70 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72 20 4e  ess attempt or N
16d80 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63 63 65  ULL if this acce
16d90 73 73 20 61 74 74 65 6d 70 74 20 69 73 20 64 69  ss attempt is di
16da0 72 65 63 74 6c 79 20 66 72 6f 6d 20 0a 2a 2a 20  rectly from .** 
16db0 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f  top-level SQL co
16dc0 64 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  de..**.** INVARI
16dd0 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  ANTS:.**.** {F12
16de0 35 35 31 7d 20 54 68 65 20 73 65 63 6f 6e 64 20  551} The second 
16df0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 61 6e 20  parameter to an 
16e00 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
16e10 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
16e20 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65  izer | authorize
16e30 72 20 63 61 6c 6c 62 61 63 6b 5d 20 69 73 20 61  r callback] is a
16e40 6c 77 61 79 73 20 61 6e 20 69 6e 74 65 67 65 72  lways an integer
16e50 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51  .**          [SQ
16e60 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 75 74 68  LITE_COPY | auth
16e70 6f 72 69 7a 65 72 20 63 6f 64 65 5d 20 74 68 61  orizer code] tha
16e80 74 20 73 70 65 63 69 66 69 65 73 20 77 68 61 74  t specifies what
16e90 20 61 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20   action.**      
16ea0 20 20 20 20 69 73 20 62 65 69 6e 67 20 61 75 74      is being aut
16eb0 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b  horized..**.** {
16ec0 46 31 32 35 35 32 7d 20 54 68 65 20 33 72 64 20  F12552} The 3rd 
16ed0 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74 65  and 4th paramete
16ee0 72 73 20 74 6f 20 74 68 65 20 0a 2a 2a 20 20 20  rs to the .**   
16ef0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
16f00 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c  set_authorizer |
16f10 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 63   authorization c
16f20 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
16f30 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69  ].**          wi
16f40 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72 73  ll be parameters
16f50 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69   or NULL dependi
16f60 6e 67 20 6f 6e 20 77 68 69 63 68 20 0a 2a 2a 20  ng on which .** 
16f70 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45           [SQLITE
16f80 5f 43 4f 50 59 20 7c 20 61 75 74 68 6f 72 69 7a  _COPY | authoriz
16f90 65 72 20 63 6f 64 65 5d 20 69 73 20 75 73 65 64  er code] is used
16fa0 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70   as the second p
16fb0 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
16fc0 7b 46 31 32 35 35 33 7d 20 54 68 65 20 35 74 68  {F12553} The 5th
16fd0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
16fe0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  e.**          [s
16ff0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
17000 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a  rizer | authoriz
17010 65 72 20 63 61 6c 6c 62 61 63 6b 5d 20 69 73 20  er callback] is 
17020 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 20 20 20 20  the name.**     
17030 20 20 20 20 20 6f 66 20 74 68 65 20 64 61 74 61       of the data
17040 62 61 73 65 20 28 65 78 61 6d 70 6c 65 3a 20 22  base (example: "
17050 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 20 65  main", "temp", e
17060 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62  tc.) if applicab
17070 6c 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 35  le..**.** {F1255
17080 34 7d 20 54 68 65 20 36 74 68 20 70 61 72 61 6d  4} The 6th param
17090 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 20  eter to the.**  
170a0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
170b0 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20  _set_authorizer 
170c0 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  | authorizer cal
170d0 6c 62 61 63 6b 5d 20 69 73 20 74 68 65 20 6e 61  lback] is the na
170e0 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  me.**          o
170f0 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74  f the inner-most
17100 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 65 77   trigger or view
17110 20 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73   that is respons
17120 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20  ible for.**     
17130 20 20 20 20 20 74 68 65 20 61 63 63 65 73 73 20       the access 
17140 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20  attempt or NULL 
17150 69 66 20 74 68 69 73 20 61 63 63 65 73 73 20 61  if this access a
17160 74 74 65 6d 70 74 20 69 73 20 64 69 72 65 63 74  ttempt is direct
17170 6c 79 20 66 72 6f 6d 20 0a 2a 2a 20 20 20 20 20  ly from .**     
17180 20 20 20 20 20 74 6f 70 2d 6c 65 76 65 6c 20 53       top-level S
17190 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a  QL code..*/./***
171a0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
171b0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
171c0 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a  ******** 3rd ***
171d0 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a  ********* 4th **
171e0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69  *********/.#defi
171f0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
17200 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20  _INDEX          
17210 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  1   /* Index Nam
17220 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
17230 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
17240 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
17250 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32  TABLE          2
17260 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
17270 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
17280 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
17290 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
172a0 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20  EMP_INDEX     3 
172b0 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
172c0 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
172d0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
172e0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
172f0 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20  MP_TABLE     4  
17300 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
17310 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
17320 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
17330 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
17340 50 5f 54 52 49 47 47 45 52 20 20 20 35 20 20 20  P_TRIGGER   5   
17350 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
17360 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
17370 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
17380 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
17390 5f 56 49 45 57 20 20 20 20 20 20 36 20 20 20 2f  _VIEW      6   /
173a0 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
173b0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
173c0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
173d0 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47  ITE_CREATE_TRIGG
173e0 45 52 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a  ER        7   /*
173f0 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
17400 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
17410 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
17420 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20  TE_CREATE_VIEW  
17430 20 20 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20           8   /* 
17440 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
17450 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
17460 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
17470 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20  E_DELETE        
17480 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54          9   /* T
17490 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
174a0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
174b0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
174c0 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20  _DROP_INDEX     
174d0 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e        10   /* In
174e0 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
174f0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
17500 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
17510 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20  DROP_TABLE      
17520 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62       11   /* Tab
17530 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
17540 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
17550 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
17560 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20  ROP_TEMP_INDEX  
17570 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65      12   /* Inde
17580 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
17590 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
175a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
175b0 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20  OP_TEMP_TABLE   
175c0 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65     13   /* Table
175d0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
175e0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
175f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
17600 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20  P_TEMP_TRIGGER  
17610 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65    14   /* Trigge
17620 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
17630 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
17640 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
17650 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20  _TEMP_VIEW      
17660 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61   15   /* View Na
17670 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
17680 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
17690 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
176a0 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20 20  TRIGGER         
176b0 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20  16   /* Trigger 
176c0 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
176d0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
176e0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56  ne SQLITE_DROP_V
176f0 49 45 57 20 20 20 20 20 20 20 20 20 20 20 20 31  IEW            1
17700 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  7   /* View Name
17710 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
17720 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
17730 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20  e SQLITE_INSERT 
17740 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 38                18
17750 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
17760 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
17770 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
17780 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20   SQLITE_PRAGMA  
17790 20 20 20 20 20 20 20 20 20 20 20 20 20 31 39 20               19 
177a0 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65    /* Pragma Name
177b0 20 20 20 20 20 31 73 74 20 61 72 67 20 6f 72 20       1st arg or 
177c0 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20  NULL */.#define 
177d0 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20  SQLITE_READ     
177e0 20 20 20 20 20 20 20 20 20 20 20 20 32 30 20 20              20  
177f0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
17800 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20      Column Name 
17810 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
17820 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20  QLITE_SELECT    
17830 20 20 20 20 20 20 20 20 20 20 20 32 31 20 20 20             21   
17840 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20  /* NULL         
17850 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
17860 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
17870 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e  LITE_TRANSACTION
17880 20 20 20 20 20 20 20 20 20 20 32 32 20 20 20 2f            22   /
17890 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20  * NULL          
178a0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
178b0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
178c0 49 54 45 5f 55 50 44 41 54 45 20 20 20 20 20 20  ITE_UPDATE      
178d0 20 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a           23   /*
178e0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
178f0 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20   Column Name    
17900 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
17910 54 45 5f 41 54 54 41 43 48 20 20 20 20 20 20 20  TE_ATTACH       
17920 20 20 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20          24   /* 
17930 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20  Filename        
17940 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
17950 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
17960 45 5f 44 45 54 41 43 48 20 20 20 20 20 20 20 20  E_DETACH        
17970 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44         25   /* D
17980 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e  atabase Name   N
17990 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
179a0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
179b0 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20  _ALTER_TABLE    
179c0 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61        26   /* Da
179d0 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61  tabase Name   Ta
179e0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
179f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
17a00 52 45 49 4e 44 45 58 20 20 20 20 20 20 20 20 20  REINDEX         
17a10 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64       27   /* Ind
17a20 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  ex Name      NUL
17a30 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
17a40 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
17a50 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20  NALYZE          
17a60 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c      28   /* Tabl
17a70 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
17a80 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
17a90 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
17aa0 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20  EATE_VTABLE     
17ab0 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65     29   /* Table
17ac0 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c   Name      Modul
17ad0 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  e Name     */.#d
17ae0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
17af0 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20  P_VTABLE        
17b00 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20    30   /* Table 
17b10 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65  Name      Module
17b20 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
17b30 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43  fine SQLITE_FUNC
17b40 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20  TION            
17b50 20 33 31 20 20 20 2f 2a 20 46 75 6e 63 74 69 6f   31   /* Functio
17b60 6e 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20  n Name   NULL   
17b70 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
17b80 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 20  ine SQLITE_COPY 
17b90 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
17ba0 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65   0   /* No longe
17bb0 72 20 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  r used */../*.**
17bc0 20 43 41 50 49 33 52 45 46 3a 20 54 72 61 63 69   CAPI3REF: Traci
17bd0 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67  ng And Profiling
17be0 20 46 75 6e 63 74 69 6f 6e 73 20 7b 46 31 32 32   Functions {F122
17bf0 38 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  80}.**.** These 
17c00 72 6f 75 74 69 6e 65 73 20 72 65 67 69 73 74 65  routines registe
17c10 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  r callback funct
17c20 69 6f 6e 73 20 74 68 61 74 20 63 61 6e 20 62 65  ions that can be
17c30 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61   used for.** tra
17c40 63 69 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c 69  cing and profili
17c50 6e 67 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e  ng the execution
17c60 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   of SQL statemen
17c70 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61  ts..**.** The ca
17c80 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
17c90 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71  registered by sq
17ca0 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 69 73  lite3_trace() is
17cb0 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76   invoked at.** v
17cc0 61 72 69 6f 75 73 20 74 69 6d 65 73 20 77 68 65  arious times whe
17cd0 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  n an SQL stateme
17ce0 6e 74 20 69 73 20 62 65 69 6e 67 20 72 75 6e 20  nt is being run 
17cf0 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  by [sqlite3_step
17d00 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c  ()]..** The call
17d10 62 61 63 6b 20 72 65 74 75 72 6e 73 20 61 20 55  back returns a U
17d20 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f  TF-8 rendering o
17d30 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  f the SQL statem
17d40 65 6e 74 20 74 65 78 74 0a 2a 2a 20 61 73 20 74  ent text.** as t
17d50 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72  he statement fir
17d60 73 74 20 62 65 67 69 6e 73 20 65 78 65 63 75 74  st begins execut
17d70 69 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c  ing.  Additional
17d80 20 63 61 6c 6c 62 61 63 6b 73 20 6f 63 63 75 72   callbacks occur
17d90 0a 2a 2a 20 61 73 20 65 61 63 68 20 74 72 69 67  .** as each trig
17da0 67 65 72 65 64 20 73 75 62 70 72 6f 67 72 61 6d  gered subprogram
17db0 20 69 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68   is entered.  Th
17dc0 65 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20  e callbacks for 
17dd0 74 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74  triggers.** cont
17de0 61 69 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20  ain a UTF-8 SQL 
17df0 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65  comment that ide
17e00 6e 74 69 66 69 65 73 20 74 68 65 20 74 72 69 67  ntifies the trig
17e10 67 65 72 2e 0a 2a 2a 20 0a 2a 2a 20 54 68 65 20  ger..** .** The 
17e20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
17e30 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20  n registered by 
17e40 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28  sqlite3_profile(
17e50 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20  ) is invoked.** 
17e60 61 73 20 65 61 63 68 20 53 51 4c 20 73 74 61 74  as each SQL stat
17e70 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 20  ement finishes. 
17e80 20 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c   The profile cal
17e90 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a  lback contains.*
17ea0 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73  * the original s
17eb0 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 6e  tatement text an
17ec0 64 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66  d an estimate of
17ed0 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65   wall-clock time
17ee0 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20  .** of how long 
17ef0 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 74  that statement t
17f00 6f 6f 6b 20 74 6f 20 72 75 6e 2e 0a 2a 2a 0a 2a  ook to run..**.*
17f10 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72  * The sqlite3_pr
17f20 6f 66 69 6c 65 28 29 20 41 50 49 20 69 73 20 63  ofile() API is c
17f30 75 72 72 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65  urrently conside
17f40 72 65 64 20 65 78 70 65 72 69 6d 65 6e 74 61 6c  red experimental
17f50 20 61 6e 64 0a 2a 2a 20 69 73 20 73 75 62 6a 65   and.** is subje
17f60 63 74 20 74 6f 20 63 68 61 6e 67 65 20 6f 72 20  ct to change or 
17f70 72 65 6d 6f 76 61 6c 20 69 6e 20 61 20 66 75 74  removal in a fut
17f80 75 72 65 20 72 65 6c 65 61 73 65 2e 0a 2a 2a 0a  ure release..**.
17f90 2a 2a 20 54 68 65 20 74 72 69 67 67 65 72 20 72  ** The trigger r
17fa0 65 70 6f 72 74 69 6e 67 20 66 65 61 74 75 72 65  eporting feature
17fb0 20 6f 66 20 74 68 65 20 74 72 61 63 65 20 63 61   of the trace ca
17fc0 6c 6c 62 61 63 6b 20 69 73 20 63 6f 6e 73 69 64  llback is consid
17fd0 65 72 65 64 0a 2a 2a 20 65 78 70 65 72 69 6d 65  ered.** experime
17fe0 6e 74 61 6c 20 61 6e 64 20 69 73 20 73 75 62 6a  ntal and is subj
17ff0 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 6f 72  ect to change or
18000 20 72 65 6d 6f 76 61 6c 20 69 6e 20 66 75 74 75   removal in futu
18010 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 20  re releases..** 
18020 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  Future versions 
18030 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20  of SQLite might 
18040 61 6c 73 6f 20 61 64 64 20 6e 65 77 20 74 72 61  also add new tra
18050 63 65 20 63 61 6c 6c 62 61 63 6b 20 0a 2a 2a 20  ce callback .** 
18060 69 6e 76 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 0a  invocations..**.
18070 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
18080 2a 0a 2a 2a 20 7b 46 31 32 32 38 31 7d 20 54 68  *.** {F12281} Th
18090 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
180a0 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62  ion registered b
180b0 79 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65  y [sqlite3_trace
180c0 28 29 5d 20 69 73 0a 2a 2a 20 20 20 20 20 20 20  ()] is.**       
180d0 20 20 20 77 68 65 6e 65 76 65 72 20 61 6e 20 53     whenever an S
180e0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72  QL statement fir
180f0 73 74 20 62 65 67 69 6e 73 20 74 6f 20 65 78 65  st begins to exe
18100 63 75 74 65 20 61 6e 64 0a 2a 2a 20 20 20 20 20  cute and.**     
18110 20 20 20 20 20 77 68 65 6e 65 76 65 72 20 61 20       whenever a 
18120 74 72 69 67 67 65 72 20 73 75 62 70 72 6f 67 72  trigger subprogr
18130 61 6d 20 66 69 72 73 74 20 62 65 67 69 6e 73 20  am first begins 
18140 74 6f 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46  to run..**.** {F
18150 31 32 32 38 32 7d 20 45 61 63 68 20 63 61 6c 6c  12282} Each call
18160 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74 72 61   to [sqlite3_tra
18170 63 65 28 29 5d 20 6f 76 65 72 72 69 64 65 73 20  ce()] overrides 
18180 74 68 65 20 70 72 65 76 69 6f 75 73 6c 79 0a 2a  the previously.*
18190 2a 20 20 20 20 20 20 20 20 20 20 72 65 67 69 73  *          regis
181a0 74 65 72 65 64 20 74 72 61 63 65 20 63 61 6c 6c  tered trace call
181b0 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  back..**.** {F12
181c0 32 38 33 7d 20 41 20 4e 55 4c 4c 20 74 72 61 63  283} A NULL trac
181d0 65 20 63 61 6c 6c 62 61 63 6b 20 64 69 73 61 62  e callback disab
181e0 6c 65 73 20 74 72 61 63 69 6e 67 2e 0a 2a 2a 0a  les tracing..**.
181f0 2a 2a 20 7b 46 31 32 32 38 34 7d 20 54 68 65 20  ** {F12284} The 
18200 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
18210 6f 20 74 68 65 20 74 72 61 63 65 20 63 61 6c 6c  o the trace call
18220 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f  back is a copy o
18230 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  f.**          th
18240 65 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 20  e pointer which 
18250 77 61 73 20 74 68 65 20 33 72 64 20 61 72 67 75  was the 3rd argu
18260 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  ment to [sqlite3
18270 5f 74 72 61 63 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  _trace()]..**.**
18280 20 7b 46 31 32 32 38 35 7d 20 54 68 65 20 73 65   {F12285} The se
18290 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
182a0 20 74 68 65 20 74 72 61 63 65 20 63 61 6c 6c 62   the trace callb
182b0 61 63 6b 20 69 73 20 61 0a 2a 2a 20 20 20 20 20  ack is a.**     
182c0 20 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e       zero-termin
182d0 61 74 65 64 20 55 54 46 38 20 73 74 72 69 6e 67  ated UTF8 string
182e0 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
182f0 6f 72 69 67 69 6e 61 6c 20 74 65 78 74 0a 2a 2a  original text.**
18300 20 20 20 20 20 20 20 20 20 20 6f 66 20 74 68 65            of the
18310 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61   SQL statement a
18320 73 20 69 74 20 77 61 73 20 70 61 73 73 65 64 20  s it was passed 
18330 69 6e 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72  into [sqlite3_pr
18340 65 70 61 72 65 5f 76 32 28 29 5d 0a 2a 2a 20 20  epare_v2()].**  
18350 20 20 20 20 20 20 20 20 6f 72 20 74 68 65 20 65          or the e
18360 71 75 69 76 61 6c 65 6e 74 2c 20 6f 72 20 61 6e  quivalent, or an
18370 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 69 6e 64   SQL comment ind
18380 69 63 61 74 69 6e 67 20 74 68 65 20 62 65 67 69  icating the begi
18390 6e 6e 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20  nning.**        
183a0 20 20 6f 66 20 61 20 74 72 69 67 67 65 72 20 73    of a trigger s
183b0 75 62 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a  ubprogram..**.**
183c0 20 7b 46 31 32 32 38 37 7d 20 54 68 65 20 63 61   {F12287} The ca
183d0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
183e0 72 65 67 69 73 74 65 72 65 64 20 62 79 20 5b 73  registered by [s
183f0 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29  qlite3_profile()
18400 5d 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20  ] is invoked.** 
18410 20 20 20 20 20 20 20 20 20 61 73 20 65 61 63 68           as each
18420 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66   SQL statement f
18430 69 6e 69 73 68 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b  inishes..**.** {
18440 46 31 32 32 38 38 7d 20 54 68 65 20 66 69 72 73  F12288} The firs
18450 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  t parameter to t
18460 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62  he profile callb
18470 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ack is a copy of
18480 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
18490 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
184a0 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 66 69  o [sqlite3_profi
184b0 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  le()]..**.** {F1
184c0 32 32 38 39 7d 20 54 68 65 20 73 65 63 6f 6e 64  2289} The second
184d0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
184e0 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61  e profile callba
184f0 63 6b 20 69 73 20 61 0a 2a 2a 20 20 20 20 20 20  ck is a.**      
18500 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61      zero-termina
18510 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67  ted UTF-8 string
18520 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 73 20 74   that contains t
18530 68 65 20 63 6f 6d 70 6c 65 74 65 20 74 65 78 74  he complete text
18540 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   of.**          
18550 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
18560 74 20 61 73 20 69 74 20 77 61 73 20 70 72 6f 63  t as it was proc
18570 65 73 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65  essed by [sqlite
18580 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 0a  3_prepare_v2()].
18590 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 74  **          or t
185a0 68 65 20 65 71 75 69 76 61 6c 65 6e 74 2e 0a 2a  he equivalent..*
185b0 2a 0a 2a 2a 20 7b 46 31 32 32 39 30 7d 20 54 68  *.** {F12290} Th
185c0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
185d0 72 20 74 6f 20 74 68 65 20 70 72 6f 66 69 6c 65  r to the profile
185e0 20 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e    callback is an
185f0 20 65 73 74 69 6d 61 74 65 0a 2a 2a 20 20 20 20   estimate.**    
18600 20 20 20 20 20 20 6f 66 20 74 68 65 20 6e 75 6d        of the num
18610 62 65 72 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e  ber of nanosecon
18620 64 73 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b  ds of wall-clock
18630 20 74 69 6d 65 20 72 65 71 75 69 72 65 64 20 74   time required t
18640 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 75  o.**          ru
18650 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  n the SQL statem
18660 65 6e 74 20 66 72 6f 6d 20 73 74 61 72 74 20 74  ent from start t
18670 6f 20 66 69 6e 69 73 68 2e 0a 2a 2f 0a 76 6f 69  o finish..*/.voi
18680 64 20 2a 73 71 6c 69 74 65 33 5f 74 72 61 63 65  d *sqlite3_trace
18690 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28  (sqlite3*, void(
186a0 2a 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63  *xTrace)(void*,c
186b0 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69  onst char*), voi
186c0 64 2a 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74  d*);.void *sqlit
186d0 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 74  e3_profile(sqlit
186e0 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50  e3*,.   void(*xP
186f0 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f  rofile)(void*,co
18700 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65  nst char*,sqlite
18710 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a  3_uint64), void*
18720 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
18730 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72 65  EF: Query Progre
18740 73 73 20 43 61 6c 6c 62 61 63 6b 73 20 7b 46 31  ss Callbacks {F1
18750 32 39 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73  2910}.**.** This
18760 20 72 6f 75 74 69 6e 65 20 63 6f 6e 66 69 67 75   routine configu
18770 72 65 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66  res a callback f
18780 75 6e 63 74 69 6f 6e 20 2d 20 74 68 65 0a 2a 2a  unction - the.**
18790 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61   progress callba
187a0 63 6b 20 2d 20 74 68 61 74 20 69 73 20 69 6e 76  ck - that is inv
187b0 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c  oked periodicall
187c0 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 0a 2a 2a  y during long.**
187d0 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74   running calls t
187e0 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  o [sqlite3_exec(
187f0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  )], [sqlite3_ste
18800 70 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  p()] and.** [sql
18810 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
18820 5d 2e 20 20 20 41 6e 20 65 78 61 6d 70 6c 65 20  ].   An example 
18830 75 73 65 20 66 6f 72 20 74 68 69 73 20 0a 2a 2a  use for this .**
18840 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 6f   interface is to
18850 20 6b 65 65 70 20 61 20 47 55 49 20 75 70 64 61   keep a GUI upda
18860 74 65 64 20 64 75 72 69 6e 67 20 61 20 6c 61 72  ted during a lar
18870 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20  ge query..**.** 
18880 49 66 20 74 68 65 20 70 72 6f 67 72 65 73 73 20  If the progress 
18890 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
188a0 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f   non-zero, the o
188b0 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69  peration is.** i
188c0 6e 74 65 72 72 75 70 74 65 64 2e 20 20 54 68 69  nterrupted.  Thi
188d0 73 20 66 65 61 74 75 72 65 20 63 61 6e 20 62 65  s feature can be
188e0 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65   used to impleme
188f0 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22  nt a.** "Cancel"
18900 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49   button on a GUI
18910 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a   dialog box..**.
18920 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
18930 2a 0a 2a 2a 20 7b 46 31 32 39 31 31 7d 20 54 68  *.** {F12911} Th
18940 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
18950 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62  ion registered b
18960 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 67 72  y [sqlite3_progr
18970 65 73 73 5f 68 61 6e 64 6c 65 72 28 29 5d 0a 2a  ess_handler()].*
18980 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 69 6e  *          is in
18990 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c  voked periodical
189a0 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72  ly during long r
189b0 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 0a  unning calls to.
189c0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
189d0 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a  ite3_step()]..**
189e0 0a 2a 2a 20 7b 46 31 32 39 31 32 7d 20 54 68 65  .** {F12912} The
189f0 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61   progress callba
18a00 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e  ck is invoked on
18a10 63 65 20 66 6f 72 20 65 76 65 72 79 20 4e 20 76  ce for every N v
18a20 69 72 74 75 61 6c 0a 2a 2a 20 20 20 20 20 20 20  irtual.**       
18a30 20 20 20 6d 61 63 68 69 6e 65 20 6f 70 63 6f 64     machine opcod
18a40 65 73 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74  es, where N is t
18a50 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
18a60 6e 74 20 74 6f 20 0a 2a 2a 20 20 20 20 20 20 20  nt to .**       
18a70 20 20 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f     the [sqlite3_
18a80 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72  progress_handler
18a90 28 29 5d 20 63 61 6c 6c 20 74 68 61 74 20 72 65  ()] call that re
18aa0 67 69 73 74 65 72 65 64 0a 2a 2a 20 20 20 20 20  gistered.**     
18ab0 20 20 20 20 20 74 68 65 20 63 61 6c 6c 62 61 63       the callbac
18ac0 6b 2e 20 20 3c 74 6f 64 6f 3e 57 68 61 74 20 69  k.  <todo>What i
18ad0 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e  f N is less than
18ae0 20 31 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a   1?</todo>.**.**
18af0 20 7b 46 31 32 39 31 33 7d 20 54 68 65 20 70 72   {F12913} The pr
18b00 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20  ogress callback 
18b10 69 74 73 65 6c 66 20 69 73 20 69 64 65 6e 74 69  itself is identi
18b20 66 69 65 64 20 62 79 20 74 68 65 20 74 68 69 72  fied by the thir
18b30 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 72  d.**          ar
18b40 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74  gument to [sqlit
18b50 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64  e3_progress_hand
18b60 6c 65 72 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46  ler()]..**.** {F
18b70 31 32 39 31 34 7d 20 54 68 65 20 66 6f 75 72 74  12914} The fourt
18b80 68 20 61 72 67 75 6d 65 6e 74 20 5b 73 71 6c 69  h argument [sqli
18b90 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e  te3_progress_han
18ba0 64 6c 65 72 28 29 5d 20 69 73 20 61 0a 2a 2a 2a  dler()] is a.***
18bb0 20 20 20 20 20 20 20 20 20 76 6f 69 64 20 70 6f           void po
18bc0 69 6e 74 65 72 20 70 61 73 73 65 64 20 74 6f 20  inter passed to 
18bd0 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c  the progress cal
18be0 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20  lback.**        
18bf0 20 20 66 75 6e 63 74 69 6f 6e 20 65 61 63 68 20    function each 
18c00 74 69 6d 65 20 69 74 20 69 73 20 69 6e 76 6f 6b  time it is invok
18c10 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 31  ed..**.** {F1291
18c20 35 7d 20 49 66 20 61 20 63 61 6c 6c 20 74 6f 20  5} If a call to 
18c30 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
18c40 20 72 65 73 75 6c 74 73 20 69 6e 20 66 65 77 65   results in fewe
18c50 72 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20 20  r than.**       
18c60 20 20 20 4e 20 6f 70 63 6f 64 65 73 20 62 65 69     N opcodes bei
18c70 6e 67 20 65 78 65 63 75 74 65 64 2c 0a 2a 2a 20  ng executed,.** 
18c80 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 74 68           then th
18c90 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62  e progress callb
18ca0 61 63 6b 20 69 73 20 6e 65 76 65 72 20 69 6e 76  ack is never inv
18cb0 6f 6b 65 64 2e 20 7b 45 4e 44 7d 0a 2a 2a 20 0a  oked. {END}.** .
18cc0 2a 2a 20 7b 46 31 32 39 31 36 7d 20 45 76 65 72  ** {F12916} Ever
18cd0 79 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  y call to [sqlit
18ce0 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64  e3_progress_hand
18cf0 6c 65 72 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ler()].**       
18d00 20 20 20 6f 76 65 72 77 72 69 74 65 73 20 61 6e     overwrites an
18d10 79 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 67  y previously reg
18d20 69 73 74 65 72 65 64 20 70 72 6f 67 72 65 73 73  istered progress
18d30 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20   handler..**.** 
18d40 7b 46 31 32 39 31 37 7d 20 49 66 20 74 68 65 20  {F12917} If the 
18d50 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
18d60 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c   callback is NUL
18d70 4c 20 74 68 65 6e 20 6e 6f 20 70 72 6f 67 72 65  L then no progre
18d80 73 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 68  ss.**          h
18d90 61 6e 64 6c 65 72 20 69 73 20 69 6e 76 6f 6b 65  andler is invoke
18da0 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 31 38  d..**.** {F12918
18db0 7d 20 49 66 20 74 68 65 20 70 72 6f 67 72 65 73  } If the progres
18dc0 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  s callback retur
18dd0 6e 73 20 61 20 72 65 73 75 6c 74 20 6f 74 68 65  ns a result othe
18de0 72 20 74 68 61 6e 20 30 2c 20 74 68 65 6e 0a 2a  r than 0, then.*
18df0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 62  *          the b
18e00 65 68 61 76 69 6f 72 20 69 73 20 61 20 69 66 20  ehavior is a if 
18e10 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75  [sqlite3_interru
18e20 70 74 28 29 5d 20 68 61 64 20 62 65 65 6e 20 63  pt()] had been c
18e30 61 6c 6c 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73  alled..*/.void s
18e40 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f  qlite3_progress_
18e50 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a  handler(sqlite3*
18e60 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f  , int, int(*)(vo
18e70 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  id*), void*);../
18e80 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
18e90 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74  pening A New Dat
18ea0 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
18eb0 20 7b 46 31 32 37 30 30 7d 0a 2a 2a 0a 2a 2a 20   {F12700}.**.** 
18ec0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f  These routines o
18ed0 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61  pen an SQLite da
18ee0 74 61 62 61 73 65 20 66 69 6c 65 20 77 68 6f 73  tabase file whos
18ef0 65 20 6e 61 6d 65 0a 2a 2a 20 69 73 20 67 69 76  e name.** is giv
18f00 65 6e 20 62 79 20 74 68 65 20 66 69 6c 65 6e 61  en by the filena
18f10 6d 65 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20  me argument..** 
18f20 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  The filename arg
18f30 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70 72  ument is interpr
18f40 65 74 65 64 20 61 73 20 55 54 46 2d 38 0a 2a 2a  eted as UTF-8.**
18f50 20 66 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70   for [sqlite3_op
18f60 65 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  en()] and [sqlit
18f70 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 61 6e  e3_open_v2()] an
18f80 64 20 61 73 20 55 54 46 2d 31 36 0a 2a 2a 20 69  d as UTF-16.** i
18f90 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74  n the native byt
18fa0 65 20 6f 72 64 65 72 20 66 6f 72 20 5b 73 71 6c  e order for [sql
18fb0 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a  ite3_open16()]..
18fc0 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 2a 5d  ** An [sqlite3*]
18fd0 20 68 61 6e 64 6c 65 20 69 73 20 75 73 75 61 6c   handle is usual
18fe0 6c 79 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a  ly returned in *
18ff0 70 70 44 62 2c 20 65 76 65 6e 0a 2a 2a 20 69 66  ppDb, even.** if
19000 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
19010 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65 78 63 65  .  The only exce
19020 70 74 69 6f 6e 20 69 73 20 69 66 20 53 51 4c 69  ption is if SQLi
19030 74 65 20 69 73 20 75 6e 61 62 6c 65 0a 2a 2a 20  te is unable.** 
19040 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f  to allocate memo
19050 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b  ry to hold the [
19060 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c  sqlite3] object,
19070 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 0a 2a 2a 20   a NULL will.** 
19080 62 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  be written into 
19090 2a 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66  *ppDb instead of
190a0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
190b0 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  e [sqlite3] obje
190c0 63 74 2e 0a 2a 2a 20 49 66 20 74 68 65 20 64 61  ct..** If the da
190d0 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
190e0 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 64   (and/or created
190f0 29 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c  ).** successfull
19100 79 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f  y, then [SQLITE_
19110 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  OK] is returned.
19120 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e 0a 2a    Otherwise an.*
19130 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20  * error code is 
19140 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 0a 2a  returned.  The.*
19150 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  * [sqlite3_errms
19160 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  g()] or [sqlite3
19170 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 20 72 6f  _errmsg16()]  ro
19180 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75 73  utines can be us
19190 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20  ed to obtain.** 
191a0 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75  an English langu
191b0 61 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e 20  age description 
191c0 6f 66 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a  of the error..**
191d0 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20  .** The default 
191e0 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 74 68 65  encoding for the
191f0 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62   database will b
19200 65 20 55 54 46 2d 38 20 69 66 0a 2a 2a 20 5b 73  e UTF-8 if.** [s
19210 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 6f  qlite3_open()] o
19220 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  r [sqlite3_open_
19230 76 32 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20  v2()] is called 
19240 61 6e 64 0a 2a 2a 20 55 54 46 2d 31 36 20 69 6e  and.** UTF-16 in
19250 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
19260 20 6f 72 64 65 72 20 69 66 20 5b 73 71 6c 69 74   order if [sqlit
19270 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 20  e3_open16()] is 
19280 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74  used..**.** Whet
19290 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72  her or not an er
192a0 72 6f 72 20 6f 63 63 75 72 73 20 77 68 65 6e 20  ror occurs when 
192b0 69 74 20 69 73 20 6f 70 65 6e 65 64 2c 20 72 65  it is opened, re
192c0 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63  sources.** assoc
192d0 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b  iated with the [
192e0 73 71 6c 69 74 65 33 2a 5d 20 68 61 6e 64 6c 65  sqlite3*] handle
192f0 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61   should be relea
19300 73 65 64 20 62 79 20 70 61 73 73 69 6e 67 20 69  sed by passing i
19310 74 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33  t.** to [sqlite3
19320 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69  _close()] when i
19330 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72  t is no longer r
19340 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  equired..**.** T
19350 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
19360 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65  _v2()] interface
19370 20 77 6f 72 6b 73 20 6c 69 6b 65 20 5b 73 71 6c   works like [sql
19380 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 0a 2a 2a  ite3_open()] .**
19390 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20   except that it 
193a0 61 63 63 65 70 74 73 20 74 77 6f 20 61 64 64 69  accepts two addi
193b0 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72  tional parameter
193c0 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  s for additional
193d0 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72   control.** over
193e0 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73   the new databas
193f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54  e connection.  T
19400 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74  he flags paramet
19410 65 72 20 63 61 6e 20 62 65 0a 2a 2a 20 6f 6e 65  er can be.** one
19420 20 6f 66 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a   of:.**.** <ol>.
19430 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
19440 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 0a  _OPEN_READONLY].
19450 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
19460 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d  _OPEN_READWRITE]
19470 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
19480 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
19490 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ] | [SQLITE_OPEN
194a0 5f 43 52 45 41 54 45 5d 0a 2a 2a 20 3c 2f 6f 6c  _CREATE].** </ol
194b0 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  >.**.** The firs
194c0 74 20 76 61 6c 75 65 20 6f 70 65 6e 73 20 74 68  t value opens th
194d0 65 20 64 61 74 61 62 61 73 65 20 72 65 61 64 2d  e database read-
194e0 6f 6e 6c 79 2e 20 0a 2a 2a 20 49 66 20 74 68 65  only. .** If the
194f0 20 64 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e   database does n
19500 6f 74 20 70 72 65 76 69 6f 75 73 6c 79 20 65 78  ot previously ex
19510 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73  ist, an error is
19520 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 54 68   returned..** Th
19530 65 20 73 65 63 6f 6e 64 20 6f 70 74 69 6f 6e 20  e second option 
19540 6f 70 65 6e 73 0a 2a 2a 20 74 68 65 20 64 61 74  opens.** the dat
19550 61 62 61 73 65 20 66 6f 72 20 72 65 61 64 69 6e  abase for readin
19560 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66  g and writing if
19570 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 65   possible, or re
19580 61 64 69 6e 67 20 6f 6e 6c 79 20 69 66 0a 2a 2a  ading only if.**
19590 20 69 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   if the file is 
195a0 77 72 69 74 65 20 70 72 6f 74 65 63 74 65 64 2e  write protected.
195b0 20 20 49 6e 20 65 69 74 68 65 72 20 63 61 73 65    In either case
195c0 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
195d0 20 6d 75 73 74 20 61 6c 72 65 61 64 79 20 65 78   must already ex
195e0 69 73 74 20 6f 72 20 61 6e 20 65 72 72 6f 72 20  ist or an error 
195f0 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68  is returned.  Th
19600 65 20 74 68 69 72 64 20 6f 70 74 69 6f 6e 0a 2a  e third option.*
19610 2a 20 6f 70 65 6e 73 20 74 68 65 20 64 61 74 61  * opens the data
19620 62 61 73 65 20 66 6f 72 20 72 65 61 64 69 6e 67  base for reading
19630 20 61 6e 64 20 77 72 69 74 69 6e 67 20 61 6e 64   and writing and
19640 20 63 72 65 61 74 65 73 20 69 74 20 69 66 20 69   creates it if i
19650 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 61 6c  t does.** not al
19660 72 65 61 64 79 20 65 78 69 73 74 2e 0a 2a 2a 20  ready exist..** 
19670 54 68 65 20 74 68 69 72 64 20 6f 70 74 69 6f 6e  The third option
19680 73 20 69 73 20 62 65 68 61 76 69 6f 72 20 74 68  s is behavior th
19690 61 74 20 69 73 20 61 6c 77 61 79 73 20 75 73 65  at is always use
196a0 64 20 66 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f  d for [sqlite3_o
196b0 70 65 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73  pen()].** and [s
196c0 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
196d0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33  ..**.** If the 3
196e0 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
196f0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
19700 28 29 5d 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f  ()] is not one o
19710 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61  f the.** combina
19720 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76  tions shown abov
19730 65 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  e then the behav
19740 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ior is undefined
19750 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66  ..**.** If the f
19760 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d  ilename is ":mem
19770 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 6e 20 70  ory:", then an p
19780 72 69 76 61 74 65 0a 2a 2a 20 69 6e 2d 6d 65 6d  rivate.** in-mem
19790 6f 72 79 20 64 61 74 61 62 61 73 65 20 69 73 20  ory database is 
197a0 63 72 65 61 74 65 64 20 66 6f 72 20 74 68 65 20  created for the 
197b0 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 69  connection.  Thi
197c0 73 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 64  s in-memory.** d
197d0 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61 6e  atabase will van
197e0 69 73 68 20 77 68 65 6e 20 74 68 65 20 64 61 74  ish when the dat
197f0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
19800 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 46 75 74   is closed.  Fut
19810 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f  ure.** version o
19820 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 6d  f SQLite might m
19830 61 6b 65 20 75 73 65 20 6f 66 20 61 64 64 69 74  ake use of addit
19840 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20 66 69  ional special fi
19850 6c 65 6e 61 6d 65 73 0a 2a 2a 20 74 68 61 74 20  lenames.** that 
19860 62 65 67 69 6e 20 77 69 74 68 20 74 68 65 20 22  begin with the "
19870 3a 22 20 63 68 61 72 61 63 74 65 72 2e 20 20 49  :" character.  I
19880 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  t is recommended
19890 20 74 68 61 74 20 0a 2a 2a 20 77 68 65 6e 20 61   that .** when a
198a0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   database filena
198b0 6d 65 20 72 65 61 6c 6c 79 20 64 6f 65 73 20 62  me really does b
198c0 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 22 3a 22  egin with.** ":"
198d0 20 74 68 61 74 20 79 6f 75 20 70 72 65 66 69 78   that you prefix
198e0 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69   the filename wi
198f0 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20 6c 69  th a pathname li
19900 6b 65 20 22 2e 2f 22 20 74 6f 0a 2a 2a 20 61 76  ke "./" to.** av
19910 6f 69 64 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a  oid ambiguity..*
19920 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 6c 65  *.** If the file
19930 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d 70 74 79  name is an empty
19940 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 20   string, then a 
19950 70 72 69 76 61 74 65 20 74 65 6d 70 6f 72 61 72  private temporar
19960 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74  y.** on-disk dat
19970 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72  abase will be cr
19980 65 61 74 65 64 2e 20 20 54 68 69 73 20 70 72 69  eated.  This pri
19990 76 61 74 65 20 64 61 74 61 62 61 73 65 20 77 69  vate database wi
199a0 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74  ll be.** automat
199b0 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 61  ically deleted a
199c0 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 64 61  s soon as the da
199d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
199e0 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a  n is closed..**.
199f0 2a 2a 20 54 68 65 20 66 6f 75 72 74 68 20 70 61  ** The fourth pa
19a00 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
19a10 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20  e3_open_v2() is 
19a20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a  the name of the.
19a30 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  ** [sqlite3_vfs]
19a40 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66   object that def
19a50 69 6e 65 73 20 74 68 65 20 6f 70 65 72 61 74 69  ines the operati
19a60 6e 67 20 73 79 73 74 65 6d 20 0a 2a 2a 20 69 6e  ng system .** in
19a70 74 65 72 66 61 63 65 20 74 68 61 74 20 74 68 65  terface that the
19a80 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f   new database co
19a90 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20  nnection should 
19aa0 75 73 65 2e 20 20 49 66 20 74 68 65 0a 2a 2a 20  use.  If the.** 
19ab0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
19ac0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
19ad0 65 72 20 74 68 65 6e 20 74 68 65 20 64 65 66 61  er then the defa
19ae0 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  ult [sqlite3_vfs
19af0 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 69 73 20 75  ].** object is u
19b00 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f  sed..**.** <b>No
19b10 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 75 73  te to Windows us
19b20 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e  ers:</b>  The en
19b30 63 6f 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20  coding used for 
19b40 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  the filename arg
19b50 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 5b 73 71 6c  ument.** of [sql
19b60 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 61 6e 64  ite3_open()] and
19b70 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
19b80 32 28 29 5d 20 6d 75 73 74 20 62 65 20 55 54 46  2()] must be UTF
19b90 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72  -8, not whatever
19ba0 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20  .** codepage is 
19bb0 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65  currently define
19bc0 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f  d.  Filenames co
19bd0 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61  ntaining interna
19be0 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63  tional.** charac
19bf0 74 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e  ters must be con
19c00 76 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20  verted to UTF-8 
19c10 70 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67  prior to passing
19c20 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 5b 73   them into.** [s
19c30 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 6f  qlite3_open()] o
19c40 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  r [sqlite3_open_
19c50 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  v2()]..**.** INV
19c60 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
19c70 46 31 32 37 30 31 7d 20 54 68 65 20 5b 73 71 6c  F12701} The [sql
19c80 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
19c90 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
19ca0 2c 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20  , and.**        
19cb0 20 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f    [sqlite3_open_
19cc0 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73  v2()] interfaces
19cd0 20 63 72 65 61 74 65 20 61 20 6e 65 77 0a 2a 2a   create a new.**
19ce0 20 20 20 20 20 20 20 20 20 20 5b 64 61 74 61 62            [datab
19cf0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
19d00 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 0a  associated with.
19d10 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
19d20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 67 69  database file gi
19d30 76 65 6e 20 69 6e 20 74 68 65 69 72 20 66 69 72  ven in their fir
19d40 73 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  st parameter..**
19d50 0a 2a 2a 20 7b 46 31 32 37 30 32 7d 20 54 68 65  .** {F12702} The
19d60 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65   filename argume
19d70 6e 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65  nt is interprete
19d80 64 20 61 73 20 55 54 46 2d 38 0a 2a 2a 20 20 20  d as UTF-8.**   
19d90 20 20 20 20 20 20 20 66 6f 72 20 5b 73 71 6c 69         for [sqli
19da0 74 65 33 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20  te3_open()] and 
19db0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
19dc0 28 29 5d 20 61 6e 64 20 61 73 20 55 54 46 2d 31  ()] and as UTF-1
19dd0 36 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  6.**          in
19de0 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
19df0 20 6f 72 64 65 72 20 66 6f 72 20 5b 73 71 6c 69   order for [sqli
19e00 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a  te3_open16()]..*
19e10 2a 0a 2a 2a 20 7b 46 31 32 37 30 33 7d 20 41 20  *.** {F12703} A 
19e20 73 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63  successful invoc
19e30 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65  ation of [sqlite
19e40 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
19e50 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 0a  te3_open16()], .
19e60 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 5b  **          or [
19e70 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
19e80 29 5d 20 77 72 69 74 65 73 20 61 20 70 6f 69 6e  )] writes a poin
19e90 74 65 72 20 74 6f 20 61 20 6e 65 77 0a 2a 2a 20  ter to a new.** 
19ea0 20 20 20 20 20 20 20 20 20 5b 64 61 74 61 62 61           [databa
19eb0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69  se connection] i
19ec0 6e 74 6f 20 2a 70 70 44 62 2e 0a 2a 2a 0a 2a 2a  nto *ppDb..**.**
19ed0 20 7b 46 31 32 37 30 34 7d 20 54 68 65 20 5b 73   {F12704} The [s
19ee0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
19ef0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
19f00 29 5d 2c 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20  )], and.**      
19f10 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65      [sqlite3_ope
19f20 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63  n_v2()] interfac
19f30 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  es return [SQLIT
19f40 45 5f 4f 4b 5d 20 75 70 6f 6e 20 73 75 63 63 65  E_OK] upon succe
19f50 73 73 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ss,.**          
19f60 6f 72 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74  or an appropriat
19f70 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f  e [error code] o
19f80 6e 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a  n failure..**.**
19f90 20 7b 46 31 32 37 30 36 7d 20 54 68 65 20 64 65   {F12706} The de
19fa0 66 61 75 6c 74 20 74 65 78 74 20 65 6e 63 6f 64  fault text encod
19fb0 69 6e 67 20 66 6f 72 20 61 20 6e 65 77 20 64 61  ing for a new da
19fc0 74 61 62 61 73 65 20 63 72 65 61 74 65 64 20 75  tabase created u
19fd0 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20  sing.**         
19fe0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
19ff0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ] or [sqlite3_op
1a000 65 6e 5f 76 32 28 29 5d 20 77 69 6c 6c 20 62 65  en_v2()] will be
1a010 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b 46   UTF-8..**.** {F
1a020 31 32 37 30 37 7d 20 54 68 65 20 64 65 66 61 75  12707} The defau
1a030 6c 74 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  lt text encoding
1a040 20 66 6f 72 20 61 20 6e 65 77 20 64 61 74 61 62   for a new datab
1a050 61 73 65 20 63 72 65 61 74 65 64 20 75 73 69 6e  ase created usin
1a060 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  g.**          [s
1a070 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
1a080 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 31 36 2e   will be UTF-16.
1a090 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 30 39 7d 20  .**.** {F12709} 
1a0a0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  The [sqlite3_ope
1a0b0 6e 28 46 2c 44 29 5d 20 69 6e 74 65 72 66 61 63  n(F,D)] interfac
1a0c0 65 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20  e is equivalent 
1a0d0 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  to.**          [
1a0e0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1a0f0 46 2c 44 2c 47 2c 30 29 5d 20 77 68 65 72 65 20  F,D,G,0)] where 
1a100 74 68 65 20 47 20 70 61 72 61 6d 65 74 65 72 20  the G parameter 
1a110 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  is.**          [
1a120 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
1a130 57 52 49 54 45 5d 7c 5b 53 51 4c 49 54 45 5f 4f  WRITE]|[SQLITE_O
1a140 50 45 4e 5f 43 52 45 41 54 45 5d 2e 0a 2a 2a 0a  PEN_CREATE]..**.
1a150 2a 2a 20 7b 46 31 32 37 31 31 7d 20 49 66 20 74  ** {F12711} If t
1a160 68 65 20 47 20 70 61 72 61 6d 65 74 65 72 20 74  he G parameter t
1a170 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  o [sqlite3_open_
1a180 76 32 28 46 2c 44 2c 47 2c 56 29 5d 20 63 6f 6e  v2(F,D,G,V)] con
1a190 74 61 69 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20  tains the.**    
1a1a0 20 20 20 20 20 20 62 69 74 20 76 61 6c 75 65 20        bit value 
1a1b0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
1a1c0 44 4f 4e 4c 59 5d 20 74 68 65 6e 20 74 68 65 20  DONLY] then the 
1a1d0 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
1a1e0 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  ed.**          f
1a1f0 6f 72 20 72 65 61 64 69 6e 67 20 6f 6e 6c 79 2e  or reading only.
1a200 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 31 32 7d 20  .**.** {F12712} 
1a210 49 66 20 74 68 65 20 47 20 70 61 72 61 6d 65 74  If the G paramet
1a220 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f  er to [sqlite3_o
1a230 70 65 6e 5f 76 32 28 46 2c 44 2c 47 2c 56 29 5d  pen_v2(F,D,G,V)]
1a240 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 0a 2a 2a   contains the.**
1a250 20 20 20 20 20 20 20 20 20 20 62 69 74 20 76 61            bit va
1a260 6c 75 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  lue [SQLITE_OPEN
1a270 5f 52 45 41 44 57 52 49 54 45 5d 20 74 68 65 6e  _READWRITE] then
1a280 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
1a290 20 6f 70 65 6e 65 64 0a 2a 2a 20 20 20 20 20 20   opened.**      
1a2a0 20 20 20 20 72 65 61 64 69 6e 67 20 61 6e 64 20      reading and 
1a2b0 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69  writing if possi
1a2c0 62 6c 65 2c 20 6f 72 20 66 6f 72 20 72 65 61 64  ble, or for read
1a2d0 69 6e 67 20 6f 6e 6c 79 20 69 66 20 74 68 65 0a  ing only if the.
1a2e0 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65  **          file
1a2f0 20 69 73 20 77 72 69 74 65 20 70 72 6f 74 65 63   is write protec
1a300 74 65 64 20 62 79 20 74 68 65 20 6f 70 65 72 61  ted by the opera
1a310 74 69 6e 67 20 73 79 73 74 65 6d 2e 0a 2a 2a 0a  ting system..**.
1a320 2a 2a 20 7b 46 31 32 37 31 33 7d 20 49 66 20 74  ** {F12713} If t
1a330 68 65 20 47 20 70 61 72 61 6d 65 74 65 72 20 74  he G parameter t
1a340 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  o [sqlite3_open(
1a350 76 32 28 46 2c 44 2c 47 2c 56 29 5d 20 6f 6d 69  v2(F,D,G,V)] omi
1a360 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ts the.**       
1a370 20 20 20 62 69 74 20 76 61 6c 75 65 20 5b 53 51     bit value [SQ
1a380 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
1a390 5d 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61  ] and the databa
1a3a0 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 20  se does not.**  
1a3b0 20 20 20 20 20 20 20 20 70 72 65 76 69 6f 75 73          previous
1a3c0 6c 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72  ly exist, an err
1a3d0 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  or is returned..
1a3e0 2a 2a 0a 2a 2a 20 7b 46 31 32 37 31 34 7d 20 49  **.** {F12714} I
1a3f0 66 20 74 68 65 20 47 20 70 61 72 61 6d 65 74 65  f the G paramete
1a400 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  r to [sqlite3_op
1a410 65 6e 28 76 32 28 46 2c 44 2c 47 2c 56 29 5d 20  en(v2(F,D,G,V)] 
1a420 63 6f 6e 74 61 69 6e 73 20 74 68 65 0a 2a 2a 20  contains the.** 
1a430 20 20 20 20 20 20 20 20 20 62 69 74 20 76 61 6c           bit val
1a440 75 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ue [SQLITE_OPEN_
1a450 43 52 45 41 54 45 5d 20 61 6e 64 20 74 68 65 20  CREATE] and the 
1a460 64 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f  database does no
1a470 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 72  t.**          pr
1a480 65 76 69 6f 75 73 6c 79 20 65 78 69 73 74 2c 20  eviously exist, 
1a490 74 68 65 6e 20 61 6e 20 61 74 74 65 6d 70 74 20  then an attempt 
1a4a0 69 73 20 6d 61 64 65 20 74 6f 20 63 72 65 61 74  is made to creat
1a4b0 65 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20  e and.**        
1a4c0 20 20 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65    initialize the
1a4d0 20 64 61 74 61 62 61 73 65 2e 0a 2a 2a 0a 2a 2a   database..**.**
1a4e0 20 7b 46 31 32 37 31 37 7d 20 49 66 20 74 68 65   {F12717} If the
1a4f0 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65   filename argume
1a500 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f  nt to [sqlite3_o
1a510 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  pen()], [sqlite3
1a520 5f 6f 70 65 6e 31 36 28 29 5d 2c 0a 2a 2a 20 20  _open16()],.**  
1a530 20 20 20 20 20 20 20 20 6f 72 20 5b 73 71 6c 69          or [sqli
1a540 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69  te3_open_v2()] i
1a550 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68  s ":memory:", th
1a560 65 6e 20 61 6e 20 70 72 69 76 61 74 65 2c 0a 2a  en an private,.*
1a570 2a 20 20 20 20 20 20 20 20 20 20 65 70 68 65 6d  *          ephem
1a580 65 72 61 6c 2c 20 69 6e 2d 6d 65 6d 6f 72 79 20  eral, in-memory 
1a590 64 61 74 61 62 61 73 65 20 69 73 20 63 72 65 61  database is crea
1a5a0 74 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e  ted for the conn
1a5b0 65 63 74 69 6f 6e 2e 0a 2a 2a 20 20 20 20 20 20  ection..**      
1a5c0 20 20 20 20 3c 74 6f 64 6f 3e 49 73 20 53 51 4c      <todo>Is SQL
1a5d0 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 7c  ITE_OPEN_CREATE|
1a5e0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
1a5f0 57 52 49 54 45 20 72 65 71 75 69 72 65 64 0a 2a  WRITE required.*
1a600 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 73 71  *          in sq
1a610 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 3f  lite3_open_v2()?
1a620 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 7b 46  </todo>.**.** {F
1a630 31 32 37 31 39 7d 20 49 66 20 74 68 65 20 66 69  12719} If the fi
1a640 6c 65 6e 61 6d 65 20 69 73 20 4e 55 4c 4c 20 6f  lename is NULL o
1a650 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  r an empty strin
1a660 67 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74  g, then a privat
1a670 65 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65  e,.**          e
1a680 70 68 65 6d 65 72 61 6c 20 6f 6e 2d 64 69 73 6b  phemeral on-disk
1a690 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62   database will b
1a6a0 65 20 63 72 65 61 74 65 64 2e 0a 2a 2a 20 20 20  e created..**   
1a6b0 20 20 20 20 20 20 20 3c 74 6f 64 6f 3e 49 73 20         <todo>Is 
1a6c0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
1a6d0 54 45 7c 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  TE|SQLITE_OPEN_R
1a6e0 45 41 44 57 52 49 54 45 20 72 65 71 75 69 72 65  EADWRITE require
1a6f0 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  d.**          in
1a700 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1a710 28 29 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a  ()?</todo>.**.**
1a720 20 7b 46 31 32 37 32 31 7d 20 54 68 65 20 5b 64   {F12721} The [d
1a730 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1a740 6f 6e 5d 20 63 72 65 61 74 65 64 20 62 79 20 0a  on] created by .
1a750 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
1a760 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 46 2c 44  ite3_open_v2(F,D
1a770 2c 47 2c 56 29 5d 20 77 69 6c 6c 20 75 73 65 20  ,G,V)] will use 
1a780 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
1a790 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
1a7a0 6a 65 63 74 20 69 64 65 6e 74 69 66 69 65 64 20  ject identified 
1a7b0 62 79 20 74 68 65 20 56 20 70 61 72 61 6d 65 74  by the V paramet
1a7c0 65 72 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20  er, or.**       
1a7d0 20 20 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b     the default [
1a7e0 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
1a7f0 65 63 74 20 69 73 20 56 20 69 73 20 61 20 4e 55  ect is V is a NU
1a800 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
1a810 2a 20 7b 46 31 32 37 32 33 7d 20 54 77 6f 20 5b  * {F12723} Two [
1a820 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1a830 69 6f 6e 20 7c 20 64 61 74 61 62 61 73 65 20 63  ion | database c
1a840 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 77 69 6c 6c  onnections] will
1a850 20 73 68 61 72 65 20 61 20 63 6f 6d 6d 6f 6e 20   share a common 
1a860 63 61 63 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  cache.**        
1a870 20 20 69 66 20 62 6f 74 68 20 77 65 72 65 20 6f    if both were o
1a880 70 65 6e 65 64 20 77 69 74 68 20 74 68 65 20 73  pened with the s
1a890 61 6d 65 20 56 46 53 0a 2a 2a 20 20 20 20 20 20  ame VFS.**      
1a8a0 20 20 20 20 77 68 69 6c 65 20 5b 73 71 6c 69 74      while [sqlit
1a8b0 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64  e3_enable_shared
1a8c0 5f 63 61 63 68 65 20 7c 20 73 68 61 72 65 64 20  _cache | shared 
1a8d0 63 61 63 68 65 20 6d 6f 64 65 20 77 61 73 20 65  cache mode was e
1a8e0 6e 61 62 6c 65 64 5d 20 61 6e 64 0a 2a 2a 20 20  nabled] and.**  
1a8f0 20 20 20 20 20 20 20 20 69 66 20 62 6f 74 68 20          if both 
1a900 66 69 6c 65 6e 61 6d 65 73 20 63 6f 6d 70 61 72  filenames compar
1a910 65 20 65 71 75 61 6c 20 75 73 69 6e 67 20 6d 65  e equal using me
1a920 6d 63 6d 70 28 29 0a 2a 2a 20 20 20 20 20 20 20  mcmp().**       
1a930 20 20 20 61 66 74 65 72 20 68 61 76 69 6e 67 20     after having 
1a940 62 65 65 6e 20 70 72 6f 63 65 73 73 65 64 20 62  been processed b
1a950 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  y the [sqlite3_v
1a960 66 73 20 7c 20 78 46 75 6c 6c 50 61 74 68 6e 61  fs | xFullPathna
1a970 6d 65 5d 20 6d 65 74 68 6f 64 20 6f 66 0a 2a 2a  me] method of.**
1a980 20 20 20 20 20 20 20 20 20 20 74 68 65 20 56 46            the VF
1a990 53 2e 0a 2a 2a 0a 2a 2f 0a 69 6e 74 20 73 71 6c  S..**.*/.int sql
1a9a0 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e  ite3_open(.  con
1a9b0 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d  st char *filenam
1a9c0 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  e,   /* Database
1a9d0 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38   filename (UTF-8
1a9e0 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a  ) */.  sqlite3 *
1a9f0 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f  *ppDb          /
1aa00 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62  * OUT: SQLite db
1aa10 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e   handle */.);.in
1aa20 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  t sqlite3_open16
1aa30 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  (.  const void *
1aa40 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
1aa50 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
1aa60 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73   (UTF-16) */.  s
1aa70 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20  qlite3 **ppDb   
1aa80 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53         /* OUT: S
1aa90 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20  QLite db handle 
1aaa0 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
1aab0 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e  3_open_v2(.  con
1aac0 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d  st char *filenam
1aad0 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  e,   /* Database
1aae0 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38   filename (UTF-8
1aaf0 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a  ) */.  sqlite3 *
1ab00 2a 70 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f  *ppDb,         /
1ab10 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62  * OUT: SQLite db
1ab20 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74   handle */.  int
1ab30 20 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20   flags,         
1ab40 20 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f       /* Flags */
1ab50 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
1ab60 56 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61  Vfs        /* Na
1ab70 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65  me of VFS module
1ab80 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f   to use */.);../
1ab90 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45  *.** CAPI3REF: E
1aba0 72 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d  rror Codes And M
1abb0 65 73 73 61 67 65 73 20 7b 46 31 32 38 30 30 7d  essages {F12800}
1abc0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
1abd0 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 6e 74  e3_errcode() int
1abe0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
1abf0 68 65 20 6e 75 6d 65 72 69 63 0a 2a 2a 20 5b 53  he numeric.** [S
1ac00 51 4c 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c  QLITE_OK | resul
1ac10 74 20 63 6f 64 65 5d 20 6f 72 20 5b 53 51 4c 49  t code] or [SQLI
1ac20 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20  TE_IOERR_READ | 
1ac30 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
1ac40 63 6f 64 65 5d 0a 2a 2a 20 66 6f 72 20 74 68 65  code].** for the
1ac50 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 66 61 69   most recent fai
1ac60 6c 65 64 20 73 71 6c 69 74 65 33 5f 2a 20 41 50  led sqlite3_* AP
1ac70 49 20 63 61 6c 6c 20 61 73 73 6f 63 69 61 74 65  I call associate
1ac80 64 0a 2a 2a 20 77 69 74 68 20 5b 73 71 6c 69 74  d.** with [sqlit
1ac90 65 33 5d 20 68 61 6e 64 6c 65 20 27 64 62 27 2e  e3] handle 'db'.
1aca0 20 49 66 20 61 20 70 72 69 6f 72 20 41 50 49 20   If a prior API 
1acb0 63 61 6c 6c 20 66 61 69 6c 65 64 20 62 75 74 20  call failed but 
1acc0 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65  the.** most rece
1acd0 6e 74 20 41 50 49 20 63 61 6c 6c 20 73 75 63 63  nt API call succ
1ace0 65 65 64 65 64 2c 20 74 68 65 20 72 65 74 75 72  eeded, the retur
1acf0 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c  n value from sql
1ad00 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 0a 2a  ite3_errcode().*
1ad10 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  * is undefined..
1ad20 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
1ad30 33 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 20 73  3_errmsg() and s
1ad40 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
1ad50 29 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68  ) return English
1ad60 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78  -language.** tex
1ad70 74 20 74 68 61 74 20 64 65 73 63 72 69 62 65 73  t that describes
1ad80 20 74 68 65 20 65 72 72 6f 72 2c 20 61 73 20 65   the error, as e
1ad90 69 74 68 65 72 20 55 54 46 38 20 6f 72 20 55 54  ither UTF8 or UT
1ada0 46 31 36 20 72 65 73 70 65 63 74 69 76 65 6c 79  F16 respectively
1adb0 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 74 6f 20 68  ..** Memory to h
1adc0 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65  old the error me
1add0 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20  ssage string is 
1ade0 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c  managed internal
1adf0 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  ly..** The appli
1ae00 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20  cation does not 
1ae10 6e 65 65 64 20 74 6f 20 77 6f 72 72 79 20 77 69  need to worry wi
1ae20 74 68 20 66 72 65 65 69 6e 67 20 74 68 65 20 72  th freeing the r
1ae30 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65  esult..** Howeve
1ae40 72 2c 20 74 68 65 20 65 72 72 6f 72 20 73 74 72  r, the error str
1ae50 69 6e 67 20 6d 69 67 68 74 20 62 65 20 6f 76 65  ing might be ove
1ae60 72 77 72 69 74 74 65 6e 20 6f 72 20 64 65 61 6c  rwritten or deal
1ae70 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20 73 75  located by.** su
1ae80 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74  bsequent calls t
1ae90 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  o other SQLite i
1aea0 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74 69 6f  nterface functio
1aeb0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  ns..**.** INVARI
1aec0 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  ANTS:.**.** {F12
1aed0 38 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  801} The [sqlite
1aee0 33 5f 65 72 72 63 6f 64 65 28 44 29 5d 20 69 6e  3_errcode(D)] in
1aef0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
1af00 74 68 65 20 6e 75 6d 65 72 69 63 0a 2a 2a 20 20  the numeric.**  
1af10 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f          [SQLITE_
1af20 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65  OK | result code
1af30 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  ] or.**         
1af40 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52   [SQLITE_IOERR_R
1af50 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64 20 72  EAD | extended r
1af60 65 73 75 6c 74 20 63 6f 64 65 5d 0a 2a 2a 20 20  esult code].**  
1af70 20 20 20 20 20 20 20 20 66 6f 72 20 74 68 65 20          for the 
1af80 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 66 61  most recently fa
1af90 69 6c 65 64 20 69 6e 74 65 72 66 61 63 65 20 63  iled interface c
1afa0 61 6c 6c 20 61 73 73 6f 63 69 61 74 65 64 0a 2a  all associated.*
1afb0 2a 20 20 20 20 20 20 20 20 20 20 77 69 74 68 20  *          with 
1afc0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1afd0 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b  tion] D..**.** {
1afe0 46 31 32 38 30 33 7d 20 54 68 65 20 5b 73 71 6c  F12803} The [sql
1aff0 69 74 65 33 5f 65 72 72 6d 73 67 28 44 29 5d 20  ite3_errmsg(D)] 
1b000 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  and [sqlite3_err
1b010 6d 73 67 31 36 28 44 29 5d 0a 2a 2a 20 20 20 20  msg16(D)].**    
1b020 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73        interfaces
1b030 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d   return English-
1b040 6c 61 6e 67 75 61 67 65 20 74 65 78 74 20 74 68  language text th
1b050 61 74 20 64 65 73 63 72 69 62 65 73 0a 2a 2a 20  at describes.** 
1b060 20 20 20 20 20 20 20 20 20 74 68 65 20 65 72 72           the err
1b070 6f 72 20 69 6e 20 74 68 65 20 6d 6f 73 74 6c 79  or in the mostly
1b080 20 72 65 63 65 6e 74 6c 79 20 66 61 69 6c 65 64   recently failed
1b090 20 69 6e 74 65 72 66 61 63 65 20 63 61 6c 6c 2c   interface call,
1b0a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 6e 63  .**          enc
1b0b0 6f 64 65 64 20 61 73 20 65 69 74 68 65 72 20 55  oded as either U
1b0c0 54 46 38 20 6f 72 20 55 54 46 31 36 20 72 65 73  TF8 or UTF16 res
1b0d0 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a  pectively..**.**
1b0e0 20 7b 46 31 32 38 30 37 7d 20 54 68 65 20 73 74   {F12807} The st
1b0f0 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62  rings returned b
1b100 79 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  y [sqlite3_errms
1b110 67 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  g()] and [sqlite
1b120 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 0a 2a 2a  3_errmsg16()].**
1b130 20 20 20 20 20 20 20 20 20 20 61 72 65 20 76 61            are va
1b140 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20 6e 65  lid until the ne
1b150 78 74 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  xt SQLite interf
1b160 61 63 65 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20  ace call..**.** 
1b170 7b 46 31 32 38 30 38 7d 20 43 61 6c 6c 73 20 74  {F12808} Calls t
1b180 6f 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 74  o API routines t
1b190 68 61 74 20 64 6f 20 6e 6f 74 20 72 65 74 75 72  hat do not retur
1b1a0 6e 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 0a  n an error code.
1b1b0 2a 2a 20 20 20 20 20 20 20 20 20 20 28 65 78 61  **          (exa
1b1c0 6d 70 6c 65 3a 20 5b 73 71 6c 69 74 65 33 5f 64  mple: [sqlite3_d
1b1d0 61 74 61 5f 63 6f 75 6e 74 28 29 5d 29 20 64 6f  ata_count()]) do
1b1e0 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 20 20 20 20   not.**         
1b1f0 20 63 68 61 6e 67 65 20 74 68 65 20 65 72 72 6f   change the erro
1b200 72 20 63 6f 64 65 20 6f 72 20 6d 65 73 73 61 67  r code or messag
1b210 65 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  e returned by.**
1b220 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
1b230 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 2c 20 5b  e3_errcode()], [
1b240 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
1b250 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65  ], or [sqlite3_e
1b260 72 72 6d 73 67 31 36 28 29 5d 2e 0a 2a 2a 0a 2a  rrmsg16()]..**.*
1b270 2a 20 7b 46 31 32 38 30 39 7d 20 49 6e 74 65 72  * {F12809} Inter
1b280 66 61 63 65 73 20 74 68 61 74 20 61 72 65 20 6e  faces that are n
1b290 6f 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ot associated wi
1b2a0 74 68 20 61 20 73 70 65 63 69 66 69 63 0a 2a 2a  th a specific.**
1b2b0 20 20 20 20 20 20 20 20 20 20 5b 64 61 74 61 62            [datab
1b2c0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
1b2d0 28 65 78 61 6d 70 6c 65 73 3a 0a 2a 2a 20 20 20  (examples:.**   
1b2e0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
1b2f0 6d 70 72 69 6e 74 66 28 29 5d 20 6f 72 20 5b 73  mprintf()] or [s
1b300 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68  qlite3_enable_sh
1b310 61 72 65 64 5f 63 61 63 68 65 28 29 5d 0a 2a 2a  ared_cache()].**
1b320 20 20 20 20 20 20 20 20 20 20 64 6f 20 6e 6f 74            do not
1b330 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75   change the valu
1b340 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  es returned by.*
1b350 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
1b360 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 2c 20  te3_errcode()], 
1b370 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
1b380 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  )], or [sqlite3_
1b390 65 72 72 6d 73 67 31 36 28 29 5d 2e 0a 2a 2f 0a  errmsg16()]..*/.
1b3a0 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72 72 63  int sqlite3_errc
1b3b0 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29  ode(sqlite3 *db)
1b3c0 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
1b3d0 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c  lite3_errmsg(sql
1b3e0 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f  ite3*);.const vo
1b3f0 69 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d  id *sqlite3_errm
1b400 73 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a  sg16(sqlite3*);.
1b410 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1b420 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f   SQL Statement O
1b430 62 6a 65 63 74 20 7b 46 31 33 30 30 30 7d 0a 2a  bject {F13000}.*
1b440 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 65  * KEYWORDS: {pre
1b450 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 7d  pared statement}
1b460 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   {prepared state
1b470 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20  ments}.**.** An 
1b480 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
1b490 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e   object represen
1b4a0 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20  ts a single SQL 
1b4b0 73 74 61 74 65 6d 65 6e 74 2e 20 20 54 68 69 73  statement.  This
1b4c0 0a 2a 2a 20 6f 62 6a 65 63 74 20 69 73 20 76 61  .** object is va
1b4d0 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20 61 73  riously known as
1b4e0 20 61 20 22 70 72 65 70 61 72 65 64 20 73 74 61   a "prepared sta
1b4f0 74 65 6d 65 6e 74 22 20 6f 72 20 61 20 0a 2a 2a  tement" or a .**
1b500 20 22 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73   "compiled SQL s
1b510 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 73 69 6d  tatement" or sim
1b520 70 6c 79 20 61 73 20 61 20 22 73 74 61 74 65 6d  ply as a "statem
1b530 65 6e 74 22 2e 0a 2a 2a 20 0a 2a 2a 20 54 68 65  ent"..** .** The
1b540 20 6c 69 66 65 20 6f 66 20 61 20 73 74 61 74 65   life of a state
1b550 6d 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f 65 73  ment object goes
1b560 20 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20   something like 
1b570 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e  this:.**.** <ol>
1b580 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20  .** <li> Create 
1b590 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67  the object using
1b5a0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1b5b0 65 5f 76 32 28 29 5d 20 6f 72 20 61 20 72 65 6c  e_v2()] or a rel
1b5c0 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e  ated.**      fun
1b5d0 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42  ction..** <li> B
1b5e0 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f  ind values to ho
1b5f0 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 75 73  st parameters us
1b600 69 6e 67 0a 2a 2a 20 20 20 20 20 20 5b 73 71 6c  ing.**      [sql
1b610 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c  ite3_bind_blob |
1b620 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20   sqlite3_bind_* 
1b630 69 6e 74 65 72 66 61 63 65 73 5d 2e 0a 2a 2a 20  interfaces]..** 
1b640 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c  <li> Run the SQL
1b650 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c   by calling [sql
1b660 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65  ite3_step()] one
1b670 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a   or more times..
1b680 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68  ** <li> Reset th
1b690 65 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e  e statement usin
1b6a0 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
1b6b0 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 6b  ()] then go back
1b6c0 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65 70  .**      to step
1b6d0 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 72   2.  Do this zer
1b6e0 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e  o or more times.
1b6f0 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79  .** <li> Destroy
1b700 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e   the object usin
1b710 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  g [sqlite3_final
1b720 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e  ize()]..** </ol>
1b730 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20  .**.** Refer to 
1b740 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e  documentation on
1b750 20 69 6e 64 69 76 69 64 75 61 6c 20 6d 65 74 68   individual meth
1b760 6f 64 73 20 61 62 6f 76 65 20 66 6f 72 20 61 64  ods above for ad
1b770 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f  ditional.** info
1b780 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65  rmation..*/.type
1b790 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
1b7a0 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f  e3_stmt sqlite3_
1b7b0 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  stmt;../*.** CAP
1b7c0 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20  I3REF: Run-time 
1b7d0 4c 69 6d 69 74 73 20 7b 46 31 32 37 36 30 7d 0a  Limits {F12760}.
1b7e0 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72  **.** This inter
1b7f0 66 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20  face allows the 
1b800 73 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20  size of various 
1b810 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65  constructs to be
1b820 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61   limited.** on a
1b830 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63   connection by c
1b840 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e  onnection basis.
1b850 20 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61    The first para
1b860 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20  meter is the.** 
1b870 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1b880 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69  tion] whose limi
1b890 74 20 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f  t is to be set o
1b8a0 72 20 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a  r queried.  The.
1b8b0 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  ** second parame
1b8c0 74 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68  ter is one of th
1b8d0 65 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  e [limit categor
1b8e0 69 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65  ies] that define
1b8f0 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63   a.** class of c
1b900 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20  onstructs to be 
1b910 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54  size limited.  T
1b920 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
1b930 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77  er is the.** new
1b940 20 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20   limit for that 
1b950 63 6f 6e 73 74 72 75 63 74 2e 20 20 54 68 65 20  construct.  The 
1b960 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
1b970 20 74 68 65 20 6f 6c 64 20 6c 69 6d 69 74 2e 0a   the old limit..
1b980 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6e 65 77  **.** If the new
1b990 20 6c 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61   limit is a nega
1b9a0 74 69 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65  tive number, the
1b9b0 20 6c 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e   limit is unchan
1b9c0 67 65 64 2e 0a 2a 2a 20 46 6f 72 20 74 68 65 20  ged..** For the 
1b9d0 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20 6f  limit category o
1b9e0 66 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 58  f SQLITE_LIMIT_X
1b9f0 59 5a 20 74 68 65 72 65 20 69 73 20 61 20 68 61  YZ there is a ha
1ba00 72 64 20 75 70 70 65 72 0a 2a 2a 20 62 6f 75 6e  rd upper.** boun
1ba10 64 20 73 65 74 20 62 79 20 61 20 63 6f 6d 70 69  d set by a compi
1ba20 6c 65 2d 74 69 6d 65 20 43 2d 70 72 65 70 72 6f  le-time C-prepro
1ba30 63 65 73 73 20 6d 61 63 72 6f 20 6e 61 6d 65 64  cess macro named
1ba40 20 53 51 4c 49 54 45 5f 4d 41 58 5f 58 59 5a 2e   SQLITE_MAX_XYZ.
1ba50 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54  .** (The "_LIMIT
1ba60 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69  _" in the name i
1ba70 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d  s changed to "_M
1ba80 41 58 5f 22 2e 29 0a 2a 2a 20 41 74 74 65 6d 70  AX_".).** Attemp
1ba90 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20 61  ts to increase a
1baa0 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74 73   limit above its
1bab0 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e   hard upper boun
1bac0 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c  d are.** silentl
1bad0 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20 74  y truncated to t
1bae0 68 65 20 68 61 72 64 20 75 70 70 65 72 20 6c 69  he hard upper li
1baf0 6d 69 74 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 20 74  mit..**.** Run t
1bb00 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69  ime limits are i
1bb10 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20  ntended for use 
1bb20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  in applications 
1bb30 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62  that manage.** b
1bb40 6f 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e  oth their own in
1bb50 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20  ternal database 
1bb60 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73  and also databas
1bb70 65 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74  es that are cont
1bb80 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74  rolled.** by unt
1bb90 72 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20  rusted external 
1bba0 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61  sources.  An exa
1bbb0 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e  mple application
1bbc0 20 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77   might be a.** w
1bbd0 65 62 62 72 6f 77 73 65 72 20 74 68 61 74 20 68  ebbrowser that h
1bbe0 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62  as its own datab
1bbf0 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67  ases for storing
1bc00 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20   history and.** 
1bc10 73 65 70 61 72 61 74 65 20 64 61 74 61 62 61 73  separate databas
1bc20 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79  es controlled by
1bc30 20 4a 61 76 61 53 63 72 69 70 74 20 61 70 70 6c   JavaScript appl
1bc40 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61  ications downloa
1bc50 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49  ded.** off the I
1bc60 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e  nternet.  The in
1bc70 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73  ternal databases
1bc80 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68   can be given th
1bc90 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61  e.** large, defa
1bca0 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74  ult limits.  Dat
1bcb0 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62  abases managed b
1bcc0 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63  y external sourc
1bcd0 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76  es can.** be giv
1bce0 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20  en much smaller 
1bcf0 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20  limits designed 
1bd00 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e  to prevent a den
1bd10 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a  ial of service.*
1bd20 2a 20 61 74 74 61 63 68 2e 20 20 44 65 76 65 6c  * attach.  Devel
1bd30 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f  opers might also
1bd40 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65   want to use the
1bd50 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
1bd60 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69  thorizer()].** i
1bd70 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75 72 74  nterface to furt
1bd80 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72  her control untr
1bd90 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20  usted SQL.  The 
1bda0 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61  size of the data
1bdb0 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20  base.** created 
1bdc0 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20  by an untrusted 
1bdd0 73 63 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f  script can be co
1bde0 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68  ntained using th
1bdf0 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63  e.** [max_page_c
1be00 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a  ount] [PRAGMA]..
1be10 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72  **.** This inter
1be20 66 61 63 65 20 69 73 20 63 75 72 72 65 6e 74 6c  face is currentl
1be30 79 20 63 6f 6e 73 69 64 65 72 65 64 20 65 78 70  y considered exp
1be40 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73  erimental and is
1be50 20 73 75 62 6a 65 63 74 0a 2a 2a 20 74 6f 20 63   subject.** to c
1be60 68 61 6e 67 65 20 6f 72 20 72 65 6d 6f 76 61 6c  hange or removal
1be70 20 77 69 74 68 6f 75 74 20 70 72 69 6f 72 20 6e   without prior n
1be80 6f 74 69 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  otice..**.** INV
1be90 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
1bea0 46 31 32 37 36 32 7d 20 41 20 73 75 63 63 65 73  F12762} A succes
1beb0 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71  sful call to [sq
1bec0 6c 69 74 65 33 5f 6c 69 6d 69 74 28 44 2c 43 2c  lite3_limit(D,C,
1bed0 56 29 5d 20 77 68 65 72 65 20 56 20 69 73 0a 2a  V)] where V is.*
1bee0 2a 20 20 20 20 20 20 20 20 20 20 70 6f 73 69 74  *          posit
1bef0 69 76 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a  ive changes the.
1bf00 2a 2a 20 20 20 20 20 20 20 20 20 20 6c 69 6d 69  **          limi
1bf10 74 20 6f 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  t on the size of
1bf20 20 63 6f 6e 73 74 72 75 63 74 20 43 20 69 6e 20   construct C in 
1bf30 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1bf40 74 69 6f 6e 5d 20 44 0a 2a 2a 20 20 20 20 20 20  tion] D.**      
1bf50 20 20 20 20 74 6f 20 74 68 65 20 6c 65 73 73 65      to the lesse
1bf60 72 20 6f 66 20 56 20 61 6e 64 20 74 68 65 20 68  r of V and the h
1bf70 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 20  ard upper bound 
1bf80 6f 6e 20 74 68 65 20 73 69 7a 65 0a 2a 2a 20 20  on the size.**  
1bf90 20 20 20 20 20 20 20 20 6f 66 20 43 20 74 68 61          of C tha
1bfa0 74 20 69 73 20 73 65 74 20 61 74 20 63 6f 6d 70  t is set at comp
1bfb0 69 6c 65 2d 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20  ile-time..**.** 
1bfc0 7b 46 31 32 37 36 36 7d 20 41 20 73 75 63 63 65  {F12766} A succe
1bfd0 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73  ssful call to [s
1bfe0 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 44 2c 43  qlite3_limit(D,C
1bff0 2c 56 29 5d 20 77 68 65 72 65 20 56 20 69 73 20  ,V)] where V is 
1c000 6e 65 67 61 74 69 76 65 0a 2a 2a 20 20 20 20 20  negative.**     
1c010 20 20 20 20 20 6c 65 61 76 65 73 20 74 68 65 20       leaves the 
1c020 73 74 61 74 65 20 6f 66 20 5b 64 61 74 61 62 61  state of [databa
1c030 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
1c040 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a   unchanged..**.*
1c050 2a 20 7b 46 31 32 37 36 39 7d 20 41 20 73 75 63  * {F12769} A suc
1c060 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
1c070 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 44  [sqlite3_limit(D
1c080 2c 43 2c 56 29 5d 20 72 65 74 75 72 6e 73 20 74  ,C,V)] returns t
1c090 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76  he.**          v
1c0a0 61 6c 75 65 20 6f 66 20 74 68 65 20 6c 69 6d 69  alue of the limi
1c0b0 74 20 6f 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  t on the size of
1c0c0 20 63 6f 6e 73 74 72 75 63 74 20 43 20 69 6e 0a   construct C in.
1c0d0 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 5b  **          in [
1c0e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1c0f0 69 6f 6e 5d 20 44 20 61 73 20 69 74 20 77 61 73  ion] D as it was
1c100 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 63 61   prior to the ca
1c110 6c 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ll..*/.int sqlit
1c120 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 33  e3_limit(sqlite3
1c130 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e  *, int id, int n
1c140 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ewVal);../*.** C
1c150 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
1c160 65 20 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 69  e Limit Categori
1c170 65 73 20 7b 46 31 32 37 39 30 7d 0a 2a 2a 20 4b  es {F12790}.** K
1c180 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20  EYWORDS: {limit 
1c190 63 61 74 65 67 6f 72 79 7d 20 7b 6c 69 6d 69 74  category} {limit
1c1a0 20 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 20   categories}.** 
1c1b0 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
1c1c0 6e 74 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f  nts define vario
1c1d0 75 73 20 61 73 70 65 63 74 73 20 6f 66 20 61 20  us aspects of a 
1c1e0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1c1f0 74 69 6f 6e 5d 0a 2a 2a 20 74 68 61 74 20 63 61  tion].** that ca
1c200 6e 20 62 65 20 6c 69 6d 69 74 65 64 20 69 6e 20  n be limited in 
1c210 73 69 7a 65 20 62 79 20 63 61 6c 6c 73 20 74 6f  size by calls to
1c220 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
1c230 29 5d 2e 0a 2a 2a 20 54 68 65 20 6d 65 61 6e 69  )]..** The meani
1c240 6e 67 73 20 6f 66 20 74 68 65 20 76 61 72 69 6f  ngs of the vario
1c250 75 73 20 6c 69 6d 69 74 73 20 61 72 65 20 61 73  us limits are as
1c260 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
1c270 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  <dl>.** <dt>SQLI
1c280 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c  TE_LIMIT_LENGTH<
1c290 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
1c2a0 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20  maximum size of 
1c2b0 61 6e 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72  any.** string or
1c2c0 20 62 6c 6f 62 20 6f 72 20 74 61 62 6c 65 20 72   blob or table r
1c2d0 6f 77 2e 3c 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  ow.<dd>.**.** <d
1c2e0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53  t>SQLITE_LIMIT_S
1c2f0 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a  QL_LENGTH</dt>.*
1c300 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
1c310 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20 53  m length of an S
1c320 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64  QL statement.</d
1c330 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
1c340 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e  ITE_LIMIT_COLUMN
1c350 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
1c360 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
1c370 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20  of columns in a 
1c380 74 61 62 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e  table definition
1c390 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65   or in the.** re
1c3a0 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 53 45  sult set of a SE
1c3b0 4c 45 43 54 20 6f 72 20 74 68 65 20 6d 61 78 69  LECT or the maxi
1c3c0 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  mum number of co
1c3d0 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65  lumns in an inde
1c3e0 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52  x.** or in an OR
1c3f0 44 45 52 20 42 59 20 6f 72 20 47 52 4f 55 50 20  DER BY or GROUP 
1c400 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 0a  BY clause.</dd>.
1c410 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
1c420 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54  _LIMIT_EXPR_DEPT
1c430 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
1c440 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20  e maximum depth 
1c450 6f 66 20 74 68 65 20 70 61 72 73 65 20 74 72 65  of the parse tre
1c460 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 65 73 73  e on any express
1c470 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ion.</dd>.**.** 
1c480 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
1c490 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54  _COMPOUND_SELECT
1c4a0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
1c4b0 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
1c4c0 6f 66 20 74 65 72 6d 73 20 69 6e 20 61 20 63 6f  of terms in a co
1c4d0 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54 20 73 74  mpound SELECT st
1c4e0 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a  atement.</dd>.**
1c4f0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  .** <dt>SQLITE_L
1c500 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74  IMIT_VDBE_OP</dt
1c510 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
1c520 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69  imum number of i
1c530 6e 73 74 72 75 63 74 69 6f 6e 73 20 69 6e 20 61  nstructions in a
1c540 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65   virtual machine
1c550 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64   program.** used
1c560 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e   to implement an
1c570 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 3c   SQL statement.<
1c580 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
1c590 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43  QLITE_LIMIT_FUNC
1c5a0 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a  TION_ARG</dt>.**
1c5b0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
1c5c0 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d   number of argum
1c5d0 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 74 69  ents on a functi
1c5e0 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  on.</dd>.**.** <
1c5f0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
1c600 41 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a  ATTACHED</dt>.**
1c610 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
1c620 20 6e 75 6d 62 65 72 20 6f 66 20 61 74 74 61 63   number of attac
1c630 68 65 64 20 64 61 74 61 62 61 73 65 73 2e 3c 2f  hed databases.</
1c640 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
1c650 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f  LITE_LIMIT_LIKE_
1c660 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f  PATTERN_LENGTH</
1c670 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
1c680 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
1c690 20 74 68 65 20 70 61 74 74 65 72 6e 20 61 72 67   the pattern arg
1c6a0 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 4c 49 4b  ument to the LIK
1c6b0 45 20 6f 72 0a 2a 2a 20 47 4c 4f 42 20 6f 70 65  E or.** GLOB ope
1c6c0 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a  rators.</dd>.**.
1c6d0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49  ** <dt>SQLITE_LI
1c6e0 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MIT_VARIABLE_NUM
1c6f0 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  BER</dt>.** <dd>
1c700 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
1c710 65 72 20 6f 66 20 76 61 72 69 61 62 6c 65 73 20  er of variables 
1c720 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  in an SQL statem
1c730 65 6e 74 20 74 68 61 74 20 63 61 6e 0a 2a 2a 20  ent that can.** 
1c740 62 65 20 62 6f 75 6e 64 2e 3c 2f 64 64 3e 0a 2a  be bound.</dd>.*
1c750 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69  * </dl>.*/.#defi
1c760 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
1c770 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20  LENGTH          
1c780 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66            0.#def
1c790 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
1c7a0 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20  _SQL_LENGTH     
1c7b0 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65             1.#de
1c7c0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
1c7d0 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20  T_COLUMN        
1c7e0 20 20 20 20 20 20 20 20 20 20 20 20 32 0a 23 64              2.#d
1c7f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
1c800 49 54 5f 45 58 50 52 5f 44 45 50 54 48 20 20 20  IT_EXPR_DEPTH   
1c810 20 20 20 20 20 20 20 20 20 20 20 20 20 33 0a 23               3.#
1c820 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
1c830 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c  MIT_COMPOUND_SEL
1c840 45 43 54 20 20 20 20 20 20 20 20 20 20 20 34 0a  ECT           4.
1c850 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
1c860 49 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20 20 20  IMIT_VDBE_OP    
1c870 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 35                 5
1c880 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1c890 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41  LIMIT_FUNCTION_A
1c8a0 52 47 20 20 20 20 20 20 20 20 20 20 20 20 20 20  RG              
1c8b0 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  6.#define SQLITE
1c8c0 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 20  _LIMIT_ATTACHED 
1c8d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1c8e0 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   7.#define SQLIT
1c8f0 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54  E_LIMIT_LIKE_PAT
1c900 54 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20  TERN_LENGTH     
1c910 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    8.#define SQLI
1c920 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c  TE_LIMIT_VARIABL
1c930 45 5f 4e 55 4d 42 45 52 20 20 20 20 20 20 20 20  E_NUMBER        
1c940 20 20 20 39 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49     9../*.** CAPI
1c950 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20  3REF: Compiling 
1c960 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
1c970 20 7b 46 31 33 30 31 30 7d 0a 2a 2a 0a 2a 2a 20   {F13010}.**.** 
1c980 54 6f 20 65 78 65 63 75 74 65 20 61 6e 20 53 51  To execute an SQ
1c990 4c 20 71 75 65 72 79 2c 20 69 74 20 6d 75 73 74  L query, it must
1c9a0 20 66 69 72 73 74 20 62 65 20 63 6f 6d 70 69 6c   first be compil
1c9b0 65 64 20 69 6e 74 6f 20 61 20 62 79 74 65 2d 63  ed into a byte-c
1c9c0 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75  ode.** program u
1c9d0 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 73  sing one of thes
1c9e0 65 20 72 6f 75 74 69 6e 65 73 2e 20 0a 2a 2a 0a  e routines. .**.
1c9f0 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
1ca00 75 6d 65 6e 74 20 22 64 62 22 20 69 73 20 61 6e  ument "db" is an
1ca10 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1ca20 63 74 69 6f 6e 5d 20 0a 2a 2a 20 6f 62 74 61 69  ction] .** obtai
1ca30 6e 65 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72  ned from a prior
1ca40 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
1ca50 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
1ca60 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 0a 2a  te3_open_v2()].*
1ca70 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70  * or [sqlite3_op
1ca80 65 6e 31 36 28 29 5d 2e 20 0a 2a 2a 20 54 68 65  en16()]. .** The
1ca90 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
1caa0 20 22 7a 53 71 6c 22 20 69 73 20 74 68 65 20 73   "zSql" is the s
1cab0 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63  tatement to be c
1cac0 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64  ompiled, encoded
1cad0 0a 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55 54  .** as either UT
1cae0 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20  F-8 or UTF-16.  
1caf0 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70  The sqlite3_prep
1cb00 61 72 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  are() and sqlite
1cb10 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 0a 2a  3_prepare_v2().*
1cb20 2a 20 69 6e 74 65 72 66 61 63 65 73 20 75 73 65  * interfaces use
1cb30 73 20 55 54 46 2d 38 20 61 6e 64 20 73 71 6c 69  s UTF-8 and sqli
1cb40 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 20  te3_prepare16() 
1cb50 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
1cb60 61 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73  are16_v2().** us
1cb70 65 20 55 54 46 2d 31 36 2e 20 7b 45 4e 44 7d 0a  e UTF-16. {END}.
1cb80 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6e 42 79  **.** If the nBy
1cb90 74 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6c  te argument is l
1cba0 65 73 73 0a 2a 2a 20 74 68 61 6e 20 7a 65 72 6f  ess.** than zero
1cbb0 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 72  , then zSql is r
1cbc0 65 61 64 20 75 70 20 74 6f 20 74 68 65 20 66 69  ead up to the fi
1cbd0 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  rst zero termina
1cbe0 74 6f 72 2e 0a 2a 2a 20 49 66 20 6e 42 79 74 65  tor..** If nByte
1cbf0 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
1cc00 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74 68 65  , then it is the
1cc10 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
1cc20 6f 66 20 0a 2a 2a 20 62 79 74 65 73 20 72 65 61  of .** bytes rea
1cc30 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 57 68  d from zSql.  Wh
1cc40 65 6e 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d  en nByte is non-
1cc50 6e 65 67 61 74 69 76 65 2c 20 74 68 65 0a 2a 2a  negative, the.**
1cc60 20 7a 53 71 6c 20 73 74 72 69 6e 67 20 65 6e 64   zSql string end
1cc70 73 20 61 74 20 65 69 74 68 65 72 20 74 68 65 20  s at either the 
1cc80 66 69 72 73 74 20 27 5c 30 30 30 27 20 6f 72 20  first '\000' or 
1cc90 27 5c 75 30 30 30 30 27 20 63 68 61 72 61 63 74  '\u0000' charact
1cca0 65 72 20 6f 72 20 0a 2a 2a 20 74 68 65 20 6e 42  er or .** the nB
1ccb0 79 74 65 2d 74 68 20 62 79 74 65 2c 20 77 68 69  yte-th byte, whi
1ccc0 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72  chever comes fir
1ccd0 73 74 2e 20 49 66 20 74 68 65 20 63 61 6c 6c 65  st. If the calle
1cce0 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61 74 20  r knows.** that 
1ccf0 74 68 65 20 73 75 70 70 6c 69 65 64 20 73 74 72  the supplied str
1cd00 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69  ing is nul-termi
1cd10 6e 61 74 65 64 2c 20 74 68 65 6e 20 74 68 65 72  nated, then ther
1cd20 65 20 69 73 20 61 20 73 6d 61 6c 6c 0a 2a 2a 20  e is a small.** 
1cd30 70 65 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 61  performance adva
1cd40 6e 74 61 67 65 20 74 6f 20 62 65 20 68 61 64 20  ntage to be had 
1cd50 62 79 20 70 61 73 73 69 6e 67 20 61 6e 20 6e 42  by passing an nB
1cd60 79 74 65 20 70 61 72 61 6d 65 74 65 72 20 74 68  yte parameter th
1cd70 61 74 20 0a 2a 2a 20 69 73 20 65 71 75 61 6c 20  at .** is equal 
1cd80 74 6f 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  to the number of
1cd90 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 69 6e   bytes in the in
1cda0 70 75 74 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e  put string <i>in
1cdb0 63 6c 75 64 69 6e 67 3c 2f 69 3e 20 0a 2a 2a 20  cluding</i> .** 
1cdc0 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74  the nul-terminat
1cdd0 6f 72 20 62 79 74 65 73 2e 7b 45 4e 44 7d 0a 2a  or bytes.{END}.*
1cde0 2a 0a 2a 2a 20 2a 70 7a 54 61 69 6c 20 69 73 20  *.** *pzTail is 
1cdf0 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f  made to point to
1ce00 20 74 68 65 20 66 69 72 73 74 20 62 79 74 65 20   the first byte 
1ce10 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20  past the end of 
1ce20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 53 51 4c  the.** first SQL
1ce30 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53   statement in zS
1ce40 71 6c 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69  ql.  These routi
1ce50 6e 65 73 20 6f 6e 6c 79 20 63 6f 6d 70 69 6c 65  nes only compile
1ce60 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 73 74   the first.** st
1ce70 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c  atement in zSql,
1ce80 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c   so *pzTail is l
1ce90 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20  eft pointing to 
1cea0 77 68 61 74 20 72 65 6d 61 69 6e 73 0a 2a 2a 20  what remains.** 
1ceb0 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a  uncompiled..**.*
1cec0 2a 20 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66  * *ppStmt is lef
1ced0 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20  t pointing to a 
1cee0 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70 61 72  compiled [prepar
1cef0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
1cf00 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65  at can be.** exe
1cf10 63 75 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  cuted using [sql
1cf20 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 4f  ite3_step()].  O
1cf30 72 20 69 66 20 74 68 65 72 65 20 69 73 20 61 6e  r if there is an
1cf40 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20   error, *ppStmt 
1cf50 69 73 0a 2a 2a 20 73 65 74 20 74 6f 20 4e 55 4c  is.** set to NUL
1cf60 4c 2e 20 20 49 66 20 74 68 65 20 69 6e 70 75 74  L.  If the input
1cf70 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e   text contains n
1cf80 6f 20 53 51 4c 20 28 69 66 20 74 68 65 20 69 6e  o SQL (if the in
1cf90 70 75 74 0a 2a 2a 20 69 73 20 61 6e 64 20 65 6d  put.** is and em
1cfa0 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20 61 20  pty string or a 
1cfb0 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70  comment) then *p
1cfc0 70 53 74 6d 74 20 69 73 20 73 65 74 20 74 6f 20  pStmt is set to 
1cfd0 4e 55 4c 4c 2e 0a 2a 2a 20 7b 55 31 33 30 31 38  NULL..** {U13018
1cfe0 7d 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70 72  } The calling pr
1cff0 6f 63 65 64 75 72 65 20 69 73 20 72 65 73 70 6f  ocedure is respo
1d000 6e 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65 74  nsible for delet
1d010 69 6e 67 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69  ing the.** compi
1d020 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  led SQL statemen
1d030 74 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69  t.** using [sqli
1d040 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
1d050 61 66 74 65 72 20 69 74 20 68 61 73 20 66 69 6e  after it has fin
1d060 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 0a 2a  ished with it..*
1d070 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73 2c  *.** On success,
1d080 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20   [SQLITE_OK] is 
1d090 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72  returned.  Other
1d0a0 77 69 73 65 20 61 6e 20 0a 2a 2a 20 5b 65 72 72  wise an .** [err
1d0b0 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75  or code] is retu
1d0c0 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  rned..**.** The 
1d0d0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1d0e0 76 32 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  v2() and sqlite3
1d0f0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 20  _prepare16_v2() 
1d100 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 0a 2a  interfaces are.*
1d110 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f  * recommended fo
1d120 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61  r all new progra
1d130 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64 65  ms. The two olde
1d140 72 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  r interfaces are
1d150 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72   retained.** for
1d160 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
1d170 74 69 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68  tibility, but th
1d180 65 69 72 20 75 73 65 20 69 73 20 64 69 73 63 6f  eir use is disco
1d190 75 72 61 67 65 64 2e 0a 2a 2a 20 49 6e 20 74 68  uraged..** In th
1d1a0 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
1d1b0 73 2c 20 74 68 65 20 70 72 65 70 61 72 65 64 20  s, the prepared 
1d1c0 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61  statement.** tha
1d1d0 74 20 69 73 20 72 65 74 75 72 6e 65 64 20 28 74  t is returned (t
1d1e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  he [sqlite3_stmt
1d1f0 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61 69  ] object) contai
1d200 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  ns a copy of the
1d210 20 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51   .** original SQ
1d220 4c 20 74 65 78 74 2e 20 7b 45 4e 44 7d 20 54 68  L text. {END} Th
1d230 69 73 20 63 61 75 73 65 73 20 74 68 65 20 5b 73  is causes the [s
1d240 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69  qlite3_step()] i
1d250 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62  nterface to.** b
1d260 65 68 61 76 65 20 61 20 64 69 66 66 65 72 65 6e  ehave a differen
1d270 74 6c 79 20 69 6e 20 74 77 6f 20 77 61 79 73 3a  tly in two ways:
1d280 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c  .**.** <ol>.** <
1d290 6c 69 3e 0a 2a 2a 20 49 66 20 74 68 65 20 64 61  li>.** If the da
1d2a0 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68  tabase schema ch
1d2b0 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f  anges, instead o
1d2c0 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c  f returning [SQL
1d2d0 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69  ITE_SCHEMA] as i
1d2e0 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64  t.** always used
1d2f0 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33   to do, [sqlite3
1d300 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75  _step()] will au
1d310 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f  tomatically reco
1d320 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a  mpile the SQL.**
1d330 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74   statement and t
1d340 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61  ry to run it aga
1d350 69 6e 2e 20 20 49 66 20 74 68 65 20 73 63 68 65  in.  If the sche
1d360 6d 61 20 68 61 73 20 63 68 61 6e 67 65 64 20 69  ma has changed i
1d370 6e 0a 2a 2a 20 61 20 77 61 79 20 74 68 61 74 20  n.** a way that 
1d380 6d 61 6b 65 73 20 74 68 65 20 73 74 61 74 65 6d  makes the statem
1d390 65 6e 74 20 6e 6f 20 6c 6f 6e 67 65 72 20 76 61  ent no longer va
1d3a0 6c 69 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74  lid, [sqlite3_st
1d3b0 65 70 28 29 5d 20 77 69 6c 6c 20 73 74 69 6c 6c  ep()] will still
1d3c0 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  .** return [SQLI
1d3d0 54 45 5f 53 43 48 45 4d 41 5d 2e 20 20 42 75 74  TE_SCHEMA].  But
1d3e0 20 75 6e 6c 69 6b 65 20 74 68 65 20 6c 65 67 61   unlike the lega
1d3f0 63 79 20 62 65 68 61 76 69 6f 72 2c 20 0a 2a 2a  cy behavior, .**
1d400 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d   [SQLITE_SCHEMA]
1d410 20 69 73 20 6e 6f 77 20 61 20 66 61 74 61 6c 20   is now a fatal 
1d420 65 72 72 6f 72 2e 20 20 43 61 6c 6c 69 6e 67 0a  error.  Calling.
1d430 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
1d440 61 72 65 5f 76 32 28 29 5d 20 61 67 61 69 6e 20  are_v2()] again 
1d450 77 69 6c 6c 20 6e 6f 74 20 6d 61 6b 65 20 74 68  will not make th
1d460 65 0a 2a 2a 20 65 72 72 6f 72 20 67 6f 20 61 77  e.** error go aw
1d470 61 79 2e 20 20 4e 6f 74 65 3a 20 75 73 65 20 5b  ay.  Note: use [
1d480 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
1d490 5d 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74 65  ] to find the te
1d4a0 78 74 0a 2a 2a 20 6f 66 20 74 68 65 20 70 61 72  xt.** of the par
1d4b0 73 69 6e 67 20 65 72 72 6f 72 20 74 68 61 74 20  sing error that 
1d4c0 72 65 73 75 6c 74 73 20 69 6e 20 61 6e 20 5b 53  results in an [S
1d4d0 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 72 65  QLITE_SCHEMA] re
1d4e0 74 75 72 6e 2e 20 7b 45 4e 44 7d 0a 2a 2a 20 3c  turn. {END}.** <
1d4f0 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a  /li>.**.** <li>.
1d500 2a 2a 20 57 68 65 6e 20 61 6e 20 65 72 72 6f 72  ** When an error
1d510 20 6f 63 63 75 72 73 2c 20 0a 2a 2a 20 5b 73 71   occurs, .** [sq
1d520 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69  lite3_step()] wi
1d530 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66  ll return one of
1d540 20 74 68 65 20 64 65 74 61 69 6c 65 64 20 0a 2a   the detailed .*
1d550 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20  * [error codes] 
1d560 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72  or [extended err
1d570 6f 72 20 63 6f 64 65 73 5d 2e 20 0a 2a 2a 20 54  or codes]. .** T
1d580 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69  he legacy behavi
1d590 6f 72 20 77 61 73 20 74 68 61 74 20 5b 73 71 6c  or was that [sql
1d5a0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 6f 75  ite3_step()] wou
1d5b0 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61  ld only return a
1d5c0 20 67 65 6e 65 72 69 63 0a 2a 2a 20 5b 53 51 4c   generic.** [SQL
1d5d0 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c  ITE_ERROR] resul
1d5e0 74 20 63 6f 64 65 20 61 6e 64 20 79 6f 75 20 77  t code and you w
1d5f0 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b  ould have to mak
1d600 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20  e a second call 
1d610 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  to.** [sqlite3_r
1d620 65 73 65 74 28 29 5d 20 69 6e 20 6f 72 64 65 72  eset()] in order
1d630 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64   to find the und
1d640 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66  erlying cause of
1d650 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 0a 2a 2a   the problem..**
1d660 20 57 69 74 68 20 74 68 65 20 22 76 32 22 20 70   With the "v2" p
1d670 72 65 70 61 72 65 20 69 6e 74 65 72 66 61 63 65  repare interface
1d680 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  s, the underlyin
1d690 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65  g reason for the
1d6a0 20 65 72 72 6f 72 20 69 73 0a 2a 2a 20 72 65 74   error is.** ret
1d6b0 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c  urned immediatel
1d6c0 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c  y..** </li>.** <
1d6d0 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  /ol>.**.** INVAR
1d6e0 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31  IANTS:.**.** {F1
1d6f0 33 30 31 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  3011} The [sqlit
1d700 65 33 5f 70 72 65 70 61 72 65 28 64 62 2c 7a 53  e3_prepare(db,zS
1d710 71 6c 2c 2e 2e 2e 29 5d 20 61 6e 64 0a 2a 2a 20  ql,...)] and.** 
1d720 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
1d730 33 5f 70 72 65 70 61 72 65 5f 76 32 28 64 62 2c  3_prepare_v2(db,
1d740 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72  zSql,...)] inter
1d750 66 61 63 65 73 20 69 6e 74 65 72 70 72 65 74 20  faces interpret 
1d760 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
1d770 74 65 78 74 20 69 6e 20 74 68 65 69 72 20 7a 53  text in their zS
1d780 71 6c 20 70 61 72 61 6d 65 74 65 72 20 61 73 20  ql parameter as 
1d790 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  UTF-8..**.** {F1
1d7a0 33 30 31 32 7d 20 54 68 65 20 5b 73 71 6c 69 74  3012} The [sqlit
1d7b0 65 33 5f 70 72 65 70 61 72 65 31 36 28 64 62 2c  e3_prepare16(db,
1d7c0 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 61 6e 64 0a 2a  zSql,...)] and.*
1d7d0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
1d7e0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
1d7f0 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 69  (db,zSql,...)] i
1d800 6e 74 65 72 66 61 63 65 73 20 69 6e 74 65 72 70  nterfaces interp
1d810 72 65 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  ret the.**      
1d820 20 20 20 20 74 65 78 74 20 69 6e 20 74 68 65 69      text in thei
1d830 72 20 7a 53 71 6c 20 70 61 72 61 6d 65 74 65 72  r zSql parameter
1d840 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74 68   as UTF-16 in th
1d850 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
1d860 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 30  der..**.** {F130
1d870 31 33 7d 20 49 66 20 74 68 65 20 6e 42 79 74 65  13} If the nByte
1d880 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71   argument to [sq
1d890 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1d8a0 28 64 62 2c 7a 53 71 6c 2c 6e 42 79 74 65 2c 2e  (db,zSql,nByte,.
1d8b0 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ..)].**         
1d8c0 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74   and its variant
1d8d0 73 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 7a  s is less than z
1d8e0 65 72 6f 2c 20 74 68 65 6e 20 53 51 4c 20 74 65  ero, then SQL te
1d8f0 78 74 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20  xt is.**        
1d900 20 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c    read from zSql
1d910 20 69 73 20 72 65 61 64 20 75 70 20 74 6f 20 74   is read up to t
1d920 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65  he first zero te
1d930 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20  rminator..**.** 
1d940 7b 46 31 33 30 31 34 7d 20 49 66 20 74 68 65 20  {F13014} If the 
1d950 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 74  nByte argument t
1d960 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  o [sqlite3_prepa
1d970 72 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 6e 42  re_v2(db,zSql,nB
1d980 79 74 65 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20  yte,...)].**    
1d990 20 20 20 20 20 20 61 6e 64 20 69 74 73 20 76 61        and its va
1d9a0 72 69 61 6e 74 73 20 69 73 20 6e 6f 6e 2d 6e 65  riants is non-ne
1d9b0 67 61 74 69 76 65 2c 20 74 68 65 6e 20 61 74 20  gative, then at 
1d9c0 6d 6f 73 74 20 6e 42 79 74 65 73 20 62 79 74 65  most nBytes byte
1d9d0 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53 51  s.**          SQ
1d9e0 4c 20 74 65 78 74 20 69 73 20 72 65 61 64 20 66  L text is read f
1d9f0 72 6f 6d 20 7a 53 71 6c 2e 0a 2a 2a 0a 2a 2a 20  rom zSql..**.** 
1da00 7b 46 31 33 30 31 35 7d 20 49 6e 20 5b 73 71 6c  {F13015} In [sql
1da10 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1da20 64 62 2c 7a 53 71 6c 2c 4e 2c 50 2c 70 7a 54 61  db,zSql,N,P,pzTa
1da30 69 6c 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72  il)] and its var
1da40 69 61 6e 74 73 0a 2a 2a 20 20 20 20 20 20 20 20  iants.**        
1da50 20 20 69 66 20 74 68 65 20 7a 53 71 6c 20 69 6e    if the zSql in
1da60 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e  put text contain
1da70 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20  s more than one 
1da80 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  SQL statement.**
1da90 20 20 20 20 20 20 20 20 20 20 61 6e 64 20 70 7a            and pz
1daa0 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  Tail is not NULL
1dab0 2c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69  , then *pzTail i
1dac0 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20  s made to point 
1dad0 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  to the.**       
1dae0 20 20 20 66 69 72 73 74 20 62 79 74 65 20 70 61     first byte pa
1daf0 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68  st the end of th
1db00 65 20 66 69 72 73 74 20 53 51 4c 20 73 74 61 74  e first SQL stat
1db10 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 0a 2a  ement in zSql..*
1db20 2a 20 20 20 20 20 20 20 20 20 20 3c 74 6f 64 6f  *          <todo
1db30 3e 57 68 61 74 20 64 6f 65 73 20 2a 70 7a 54 61  >What does *pzTa
1db40 69 6c 20 70 6f 69 6e 74 20 74 6f 20 69 66 20 74  il point to if t
1db50 68 65 72 65 20 69 73 20 6f 6e 65 20 73 74 61 74  here is one stat
1db60 65 6d 65 6e 74 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a  ement?</todo>.**
1db70 0a 2a 2a 20 7b 46 31 33 30 31 36 7d 20 41 20 73  .** {F13016} A s
1db80 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74  uccessful call t
1db90 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  o [sqlite3_prepa
1dba0 72 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 4e 2c  re_v2(db,zSql,N,
1dbb0 70 70 53 74 6d 74 2c 2e 2e 2e 29 5d 0a 2a 2a 20  ppStmt,...)].** 
1dbc0 20 20 20 20 20 20 20 20 20 6f 72 20 6f 6e 65 20           or one 
1dbd0 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74 73 20  of its variants 
1dbe0 77 72 69 74 65 73 20 69 6e 74 6f 20 2a 70 70 53  writes into *ppS
1dbf0 74 6d 74 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  tmt a pointer to
1dc00 20 61 20 6e 65 77 0a 2a 2a 20 20 20 20 20 20 20   a new.**       
1dc10 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61     [prepared sta
1dc20 74 65 6d 65 6e 74 5d 20 6f 72 20 61 20 70 6f 69  tement] or a poi
1dc30 6e 74 65 72 20 74 6f 20 4e 55 4c 4c 0a 2a 2a 20  nter to NULL.** 
1dc40 20 20 20 20 20 20 20 20 20 69 66 20 7a 53 71 6c           if zSql
1dc50 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 74 68 69 6e   contains nothin
1dc60 67 20 6f 74 68 65 72 20 74 68 61 6e 20 77 68 69  g other than whi
1dc70 74 65 73 70 61 63 65 20 6f 72 20 63 6f 6d 6d 65  tespace or comme
1dc80 6e 74 73 2e 20 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  nts. .**.** {F13
1dc90 30 31 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  019} The [sqlite
1dca0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
1dcb0 69 6e 74 65 72 66 61 63 65 20 61 6e 64 20 69 74  interface and it
1dcc0 73 20 76 61 72 69 61 6e 74 73 20 72 65 74 75 72  s variants retur
1dcd0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53  n.**          [S
1dce0 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 61 6e 20  QLITE_OK] or an 
1dcf0 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72  appropriate [err
1dd00 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 20 66 61  or code] upon fa
1dd10 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  ilure..**.** {F1
1dd20 33 30 32 31 7d 20 42 65 66 6f 72 65 20 5b 73 71  3021} Before [sq
1dd30 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 64 62  lite3_prepare(db
1dd40 2c 7a 53 71 6c 2c 6e 42 79 74 65 2c 70 70 53 74  ,zSql,nByte,ppSt
1dd50 6d 74 2c 70 7a 54 61 69 6c 29 5d 20 6f 72 20 69  mt,pzTail)] or i
1dd60 74 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76  ts.**          v
1dd70 61 72 69 61 6e 74 73 20 72 65 74 75 72 6e 73 20  ariants returns 
1dd80 61 6e 20 65 72 72 6f 72 20 28 61 6e 79 20 76 61  an error (any va
1dd90 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  lue other than [
1dda0 53 51 4c 49 54 45 5f 4f 4b 5d 29 0a 2a 2a 20 20  SQLITE_OK]).**  
1ddb0 20 20 20 20 20 20 20 20 69 74 20 66 69 72 73 74          it first
1ddc0 20 73 65 74 73 20 2a 70 70 53 74 6d 74 20 74 6f   sets *ppStmt to
1ddd0 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71   NULL..*/.int sq
1dde0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 0a 20  lite3_prepare(. 
1ddf0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
1de00 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
1de10 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
1de20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71   const char *zSq
1de30 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
1de40 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38  statement, UTF-8
1de50 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
1de60 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
1de70 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
1de80 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
1de90 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
1dea0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
1deb0 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
1dec0 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
1ded0 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
1dee0 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
1def0 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
1df00 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
1df10 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74  f zSql */.);.int
1df20 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
1df30 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v2(.  sqlite3 *
1df40 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
1df50 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
1df60 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
1df70 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  r *zSql,       /
1df80 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
1df90 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a   UTF-8 encoded *
1dfa0 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
1dfb0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
1dfc0 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
1dfd0 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
1dfe0 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
1dff0 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
1e000 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
1e010 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
1e020 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20   char **pzTail  
1e030 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
1e040 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
1e050 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
1e060 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  );.int sqlite3_p
1e070 72 65 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69  repare16(.  sqli
1e080 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
1e090 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
1e0a0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
1e0b0 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20  t void *zSql,   
1e0c0 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
1e0d0 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63  ment, UTF-16 enc
1e0e0 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
1e0f0 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
1e100 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
1e110 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
1e120 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
1e130 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
1e140 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
1e150 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
1e160 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a   const void **pz
1e170 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
1e180 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
1e190 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
1e1a0 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  ql */.);.int sql
1e1b0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
1e1c0 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  2(.  sqlite3 *db
1e1d0 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
1e1e0 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
1e1f0 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
1e200 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
1e210 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
1e220 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f  TF-16 encoded */
1e230 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
1e240 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
1e250 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
1e260 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
1e270 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
1e280 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
1e290 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
1e2a0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
1e2b0 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20  void **pzTail   
1e2c0 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
1e2d0 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
1e2e0 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
1e2f0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 52 45 46  ;../*.** CAPIREF
1e300 3a 20 52 65 74 72 69 65 76 69 6e 67 20 53 74 61  : Retrieving Sta
1e310 74 65 6d 65 6e 74 20 53 51 4c 20 7b 46 31 33 31  tement SQL {F131
1e320 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  00}.**.** This i
1e330 6e 74 65 72 66 61 63 65 20 20 63 61 6e 20 62 65  nterface  can be
1e340 20 75 73 65 64 20 74 6f 20 72 65 74 72 69 65 76   used to retriev
1e350 65 20 61 20 73 61 76 65 64 20 63 6f 70 79 20 6f  e a saved copy o
1e360 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a  f the original.*
1e370 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65 64 20  * SQL text used 
1e380 74 6f 20 63 72 65 61 74 65 20 61 20 5b 70 72 65  to create a [pre
1e390 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
1e3a0 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
1e3b0 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 31 30  TS:.**.** {F1310
1e3c0 31 7d 20 49 66 20 74 68 65 20 5b 70 72 65 70 61  1} If the [prepa
1e3d0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 70  red statement] p
1e3e0 61 73 73 65 64 20 61 73 20 0a 2a 2a 20 20 20 20  assed as .**    
1e3f0 20 20 20 20 20 20 74 68 65 20 61 6e 20 61 72 67        the an arg
1e400 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65  ument to [sqlite
1e410 33 5f 73 71 6c 28 29 5d 20 77 61 73 20 63 6f 6d  3_sql()] was com
1e420 70 69 6c 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  piled.**        
1e430 20 20 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67    compiled using
1e440 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33   either [sqlite3
1e450 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
1e460 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  r.**          [s
1e470 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
1e480 5f 76 32 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20  _v2()],.**      
1e490 20 20 20 20 74 68 65 6e 20 5b 73 71 6c 69 74 65      then [sqlite
1e4a0 33 5f 73 71 6c 28 29 5d 20 66 75 6e 63 74 69 6f  3_sql()] functio
1e4b0 6e 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  n returns a poin
1e4c0 74 65 72 20 74 6f 20 61 0a 2a 2a 20 20 20 20 20  ter to a.**     
1e4d0 20 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e       zero-termin
1e4e0 61 74 65 64 20 73 74 72 69 6e 67 20 63 6f 6e 74  ated string cont
1e4f0 61 69 6e 69 6e 67 20 61 20 55 54 46 2d 38 20 72  aining a UTF-8 r
1e500 65 6e 64 65 72 69 6e 67 0a 2a 2a 20 20 20 20 20  endering.**     
1e510 20 20 20 20 20 6f 66 20 74 68 65 20 6f 72 69 67       of the orig
1e520 69 6e 61 6c 20 53 51 4c 20 73 74 61 74 65 6d 65  inal SQL stateme
1e530 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 31 30  nt..**.** {F1310
1e540 32 7d 20 49 66 20 74 68 65 20 5b 70 72 65 70 61  2} If the [prepa
1e550 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 70  red statement] p
1e560 61 73 73 65 64 20 61 73 20 0a 2a 2a 20 20 20 20  assed as .**    
1e570 20 20 20 20 20 20 74 68 65 20 61 6e 20 61 72 67        the an arg
1e580 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65  ument to [sqlite
1e590 33 5f 73 71 6c 28 29 5d 20 77 61 73 20 63 6f 6d  3_sql()] was com
1e5a0 70 69 6c 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  piled.**        
1e5b0 20 20 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67    compiled using
1e5c0 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33   either [sqlite3
1e5d0 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 0a 2a  _prepare()] or.*
1e5e0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
1e5f0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
1e600 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  ,.**          th
1e610 65 6e 20 5b 73 71 6c 69 74 65 33 5f 73 71 6c 28  en [sqlite3_sql(
1e620 29 5d 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  )] function retu
1e630 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
1e640 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 31 30  er..**.** {F1310
1e650 33 7d 20 54 68 65 20 73 74 72 69 6e 67 20 72 65  3} The string re
1e660 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
1e670 65 33 5f 73 71 6c 28 53 29 5d 20 69 73 20 76 61  e3_sql(S)] is va
1e680 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 0a 2a 2a  lid until the.**
1e690 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61            [prepa
1e6a0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
1e6b0 20 69 73 20 64 65 6c 65 74 65 64 20 75 73 69 6e   is deleted usin
1e6c0 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  g [sqlite3_final
1e6d0 69 7a 65 28 53 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73  ize(S)]..*/.cons
1e6e0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
1e6f0 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  sql(sqlite3_stmt
1e700 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
1e710 20 43 41 50 49 33 52 45 46 3a 20 20 44 79 6e 61   CAPI3REF:  Dyna
1e720 6d 69 63 61 6c 6c 79 20 54 79 70 65 64 20 56 61  mically Typed Va
1e730 6c 75 65 20 4f 62 6a 65 63 74 20 20 7b 46 31 35  lue Object  {F15
1e740 30 30 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  000}.** KEYWORDS
1e750 3a 20 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  : {protected sql
1e760 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70  ite3_value} {unp
1e770 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
1e780 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51  _value}.**.** SQ
1e790 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73 71  Lite uses the sq
1e7a0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
1e7b0 63 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20  ct to represent 
1e7c0 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68  all values.** th
1e7d0 61 74 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64  at can be stored
1e7e0 20 69 6e 20 61 20 64 61 74 61 62 61 73 65 20 74   in a database t
1e7f0 61 62 6c 65 2e 0a 2a 2a 20 53 51 4c 69 74 65 20  able..** SQLite 
1e800 75 73 65 73 20 64 79 6e 61 6d 69 63 20 74 79 70  uses dynamic typ
1e810 69 6e 67 20 66 6f 72 20 74 68 65 20 76 61 6c 75  ing for the valu
1e820 65 73 20 69 74 20 73 74 6f 72 65 73 2e 20 20 0a  es it stores.  .
1e830 2a 2a 20 56 61 6c 75 65 73 20 73 74 6f 72 65 64  ** Values stored
1e840 20 69 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75   in sqlite3_valu
1e850 65 20 6f 62 6a 65 63 74 73 20 63 61 6e 20 62 65  e objects can be
1e860 0a 2a 2a 20 62 65 20 69 6e 74 65 67 65 72 73 2c  .** be integers,
1e870 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
1e880 76 61 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 2c  values, strings,
1e890 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e   BLOBs, or NULL.
1e8a0 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65  .**.** An sqlite
1e8b0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d  3_value object m
1e8c0 61 79 20 62 65 20 65 69 74 68 65 72 20 22 70 72  ay be either "pr
1e8d0 6f 74 65 63 74 65 64 22 20 6f 72 20 22 75 6e 70  otected" or "unp
1e8e0 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f  rotected"..** So
1e8f0 6d 65 20 69 6e 74 65 72 66 61 63 65 73 20 72 65  me interfaces re
1e900 71 75 69 72 65 20 61 20 70 72 6f 74 65 63 74 65  quire a protecte
1e910 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e  d sqlite3_value.
1e920 20 20 4f 74 68 65 72 20 69 6e 74 65 72 66 61 63    Other interfac
1e930 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70  es.** will accep
1e940 74 20 65 69 74 68 65 72 20 61 20 70 72 6f 74 65  t either a prote
1e950 63 74 65 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f  cted or an unpro
1e960 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
1e970 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69  alue..** Every i
1e980 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61 63  nterface that ac
1e990 63 65 70 74 73 20 73 71 6c 69 74 65 33 5f 76 61  cepts sqlite3_va
1e9a0 6c 75 65 20 61 72 67 75 6d 65 6e 74 73 20 73 70  lue arguments sp
1e9b0 65 63 69 66 69 65 73 20 0a 2a 2a 20 77 68 65 74  ecifies .** whet
1e9c0 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 20 72 65  her or not it re
1e9d0 71 75 69 72 65 73 20 61 20 70 72 6f 74 65 63 74  quires a protect
1e9e0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
1e9f0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d  ..**.** The term
1ea00 73 20 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e  s "protected" an
1ea10 64 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20  d "unprotected" 
1ea20 72 65 66 65 72 20 74 6f 20 77 68 65 74 68 65 72  refer to whether
1ea30 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74   or not.** a mut
1ea40 65 78 20 69 73 20 68 65 6c 64 2e 20 20 41 20 69  ex is held.  A i
1ea50 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 73  nternal mutex is
1ea60 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f 74   held for a prot
1ea70 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
1ea80 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 75  _value object bu
1ea90 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 65  t no mutex is he
1eaa0 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74  ld for an unprot
1eab0 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
1eac0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20  _value object.  
1ead0 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
1eae0 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e 67  piled to be sing
1eaf0 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 28  le-threaded.** (
1eb00 77 69 74 68 20 53 51 4c 49 54 45 5f 54 48 52 45  with SQLITE_THRE
1eb10 41 44 53 41 46 45 3d 30 20 61 6e 64 20 77 69 74  ADSAFE=0 and wit
1eb20 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61  h [sqlite3_threa
1eb30 64 73 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69  dsafe()] returni
1eb40 6e 67 20 30 29 0a 2a 2a 20 74 68 65 6e 20 74 68  ng 0).** then th
1eb50 65 72 65 20 69 73 20 6e 6f 20 64 69 73 74 69 6e  ere is no distin
1eb60 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a  ction between.**
1eb70 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75   protected and u
1eb80 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
1eb90 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
1eba0 20 61 6e 64 20 74 68 65 79 20 63 61 6e 20 62 65   and they can be
1ebb0 0a 2a 2a 20 75 73 65 64 20 69 6e 74 65 72 63 68  .** used interch
1ebc0 61 6e 67 65 61 62 6c 65 2e 20 20 48 6f 77 65 76  angeable.  Howev
1ebd0 65 72 2c 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20  er, for maximum 
1ebe0 63 6f 64 65 20 70 6f 72 74 61 62 69 6c 69 74 79  code portability
1ebf0 20 69 74 0a 2a 2a 20 69 73 20 72 65 63 6f 6d 6d   it.** is recomm
1ec00 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69  ended that appli
1ec10 63 61 74 69 6f 6e 73 20 6d 61 6b 65 20 74 68 65  cations make the
1ec20 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74   distinction bet
1ec30 77 65 65 6e 0a 2a 2a 20 62 65 74 77 65 65 6e 20  ween.** between 
1ec40 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e  protected and un
1ec50 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
1ec60 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20  3_value objects 
1ec70 65 76 65 6e 20 69 66 0a 2a 2a 20 74 68 65 79 20  even if.** they 
1ec80 61 72 65 20 73 69 6e 67 6c 65 20 74 68 72 65 61  are single threa
1ec90 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ded..**.** The s
1eca0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
1ecb0 65 63 74 73 20 74 68 61 74 20 61 72 65 20 70 61  ects that are pa
1ecc0 73 73 65 64 20 61 73 20 70 61 72 61 6d 65 74 65  ssed as paramete
1ecd0 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69  rs into the.** i
1ece0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
1ecf0 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72   .** [sqlite3_cr
1ed00 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 20 7c 20  eate_function | 
1ed10 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
1ed20 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
1ed30 73 5d 0a 2a 2a 20 61 72 65 20 70 72 6f 74 65 63  s].** are protec
1ed40 74 65 64 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ted..** The sqli
1ed50 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
1ed60 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
1ed70 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
1ed80 76 61 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72  value()] is unpr
1ed90 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72  otected..** Unpr
1eda0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
1edb0 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61  value objects ma
1edc0 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77  y only be used w
1edd0 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ith.** [sqlite3_
1ede0 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20  result_value()] 
1edf0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  and [sqlite3_bin
1ee00 64 5f 76 61 6c 75 65 28 29 5d 2e 20 20 0a 2a 2a  d_value()].  .**
1ee10 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   The [sqlite3_va
1ee20 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74  lue_blob | sqlit
1ee30 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 29 5d  e3_value_type()]
1ee40 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e   family of.** in
1ee50 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65  terfaces require
1ee60 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74   protected sqlit
1ee70 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
1ee80 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
1ee90 75 63 74 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f  uct Mem sqlite3_
1eea0 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  value;../*.** CA
1eeb0 50 49 33 52 45 46 3a 20 20 53 51 4c 20 46 75 6e  PI3REF:  SQL Fun
1eec0 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62  ction Context Ob
1eed0 6a 65 63 74 20 7b 46 31 36 30 30 31 7d 0a 2a 2a  ject {F16001}.**
1eee0 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78 74 20  .** The context 
1eef0 69 6e 20 77 68 69 63 68 20 61 6e 20 53 51 4c 20  in which an SQL 
1ef00 66 75 6e 63 74 69 6f 6e 20 65 78 65 63 75 74 65  function execute
1ef10 73 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61  s is stored in a
1ef20 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e  n.** sqlite3_con
1ef30 74 65 78 74 20 6f 62 6a 65 63 74 2e 20 20 41 20  text object.  A 
1ef40 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 73 71  pointer to an sq
1ef50 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a  lite3_context.**
1ef60 20 6f 62 6a 65 63 74 20 69 73 20 61 6c 77 61 79   object is alway
1ef70 73 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  s first paramete
1ef80 72 20 74 6f 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  r to .** [sqlite
1ef90 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
1efa0 6e 20 7c 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  n | application-
1efb0 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
1efc0 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61  tions]..** The a
1efd0 70 70 6c 69 63 61 74 69 6f 6e 65 64 2d 64 65 66  pplicationed-def
1efe0 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
1eff0 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
1f000 20 77 69 6c 6c 20 70 61 73 73 20 74 68 69 73 0a   will pass this.
1f010 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68 72 6f 75  ** pointer throu
1f020 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f  gh into calls to
1f030 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
1f040 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65  ult_int | sqlite
1f050 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20  3_result()],.** 
1f060 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61  [sqlite3_aggrega
1f070 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 0a 2a  te_context()],.*
1f080 2a 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f  * [sqlite3_user_
1f090 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  data()],.** [sql
1f0a0 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f  ite3_context_db_
1f0b0 68 61 6e 64 6c 65 28 29 5d 2c 0a 2a 2a 20 5b 73  handle()],.** [s
1f0c0 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
1f0d0 74 61 28 29 5d 2c 20 61 6e 64 2f 6f 72 20 5b 73  ta()], and/or [s
1f0e0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
1f0f0 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65  ta()]..*/.typede
1f100 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
1f110 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33  _context sqlite3
1f120 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a  _context;../*.**
1f130 20 43 41 50 49 33 52 45 46 3a 20 20 42 69 6e 64   CAPI3REF:  Bind
1f140 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72  ing Values To Pr
1f150 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
1f160 73 20 7b 46 31 33 35 30 30 7d 0a 2a 2a 0a 2a 2a  s {F13500}.**.**
1f170 20 49 6e 20 74 68 65 20 53 51 4c 20 73 74 72 69   In the SQL stri
1f180 6e 67 73 20 69 6e 70 75 74 20 74 6f 20 5b 73 71  ngs input to [sq
1f190 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1f1a0 28 29 5d 20 61 6e 64 20 69 74 73 0a 2a 2a 20 76  ()] and its.** v
1f1b0 61 72 69 61 6e 74 73 2c 20 6c 69 74 65 72 61 6c  ariants, literal
1f1c0 73 20 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65  s may be replace
1f1d0 20 62 79 20 61 20 70 61 72 61 6d 65 74 65 72 20   by a parameter 
1f1e0 69 6e 20 6f 6e 65 0a 2a 2a 20 6f 66 20 74 68 65  in one.** of the
1f1f0 73 65 20 66 6f 72 6d 73 3a 0a 2a 2a 0a 2a 2a 20  se forms:.**.** 
1f200 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a  <ul>.** <li>  ?.
1f210 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a  ** <li>  ?NNN.**
1f220 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c   <li>  :VVV.** <
1f230 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69  li>  @VVV.** <li
1f240 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e  >  $VVV.** </ul>
1f250 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 70 61  .**.** In the pa
1f260 72 61 6d 65 74 65 72 20 66 6f 72 6d 73 20 73 68  rameter forms sh
1f270 6f 77 6e 20 61 62 6f 76 65 20 4e 4e 4e 20 69 73  own above NNN is
1f280 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65   an integer lite
1f290 72 61 6c 2c 0a 2a 2a 20 56 56 56 20 61 6c 70 68  ral,.** VVV alph
1f2a0 61 2d 6e 75 6d 65 72 69 63 20 70 61 72 61 6d 65  a-numeric parame
1f2b0 74 65 72 20 6e 61 6d 65 2e 0a 2a 2a 20 54 68 65  ter name..** The
1f2c0 20 76 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65   values of these
1f2d0 20 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73   parameters (als
1f2e0 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70  o called "host p
1f2f0 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 0a  arameter names".
1f300 2a 2a 20 6f 72 20 22 53 51 4c 20 70 61 72 61 6d  ** or "SQL param
1f310 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62  eters").** can b
1f320 65 20 73 65 74 20 75 73 69 6e 67 20 74 68 65 20  e set using the 
1f330 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
1f340 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65   routines define
1f350 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  d here..**.** Th
1f360 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
1f370 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
1f380 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
1f390 73 20 61 6c 77 61 79 73 0a 2a 2a 20 69 73 20 61  s always.** is a
1f3a0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
1f3b0 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f  [sqlite3_stmt] o
1f3c0 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 66  bject returned f
1f3d0 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  rom.** [sqlite3_
1f3e0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
1f3f0 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20 54   its variants. T
1f400 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67  he second.** arg
1f410 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64  ument is the ind
1f420 65 78 20 6f 66 20 74 68 65 20 70 61 72 61 6d 65  ex of the parame
1f430 74 65 72 20 74 6f 20 62 65 20 73 65 74 2e 20 54  ter to be set. T
1f440 68 65 0a 2a 2a 20 66 69 72 73 74 20 70 61 72 61  he.** first para
1f450 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64  meter has an ind
1f460 65 78 20 6f 66 20 31 2e 20 20 57 68 65 6e 20 74  ex of 1.  When t
1f470 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a  he same named.**
1f480 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 75 73   parameter is us
1f490 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63  ed more than onc
1f4a0 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75  e, second and su
1f4b0 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75  bsequent.** occu
1f4c0 72 72 65 6e 63 65 73 20 68 61 76 65 20 74 68 65  rrences have the
1f4d0 20 73 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74   same index as t
1f4e0 68 65 20 66 69 72 73 74 20 6f 63 63 75 72 72 65  he first occurre
1f4f0 6e 63 65 2e 20 0a 2a 2a 20 54 68 65 20 69 6e 64  nce. .** The ind
1f500 65 78 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72  ex for named par
1f510 61 6d 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c  ameters can be l
1f520 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74  ooked up using t
1f530 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  he.** [sqlite3_b
1f540 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
1f550 6d 65 28 29 5d 20 41 50 49 20 69 66 20 64 65 73  me()] API if des
1f560 69 72 65 64 2e 20 20 54 68 65 20 69 6e 64 65 78  ired.  The index
1f570 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70  .** for "?NNN" p
1f580 61 72 61 6d 65 74 65 72 73 20 69 73 20 74 68 65  arameters is the
1f590 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a   value of NNN..*
1f5a0 2a 20 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20  * The NNN value 
1f5b0 6d 75 73 74 20 62 65 20 62 65 74 77 65 65 6e 20  must be between 
1f5c0 31 20 61 6e 64 20 74 68 65 20 63 6f 6d 70 69 6c  1 and the compil
1f5d0 65 2d 74 69 6d 65 0a 2a 2a 20 70 61 72 61 6d 65  e-time.** parame
1f5e0 74 65 72 20 53 51 4c 49 54 45 5f 4d 41 58 5f 56  ter SQLITE_MAX_V
1f5f0 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20 28  ARIABLE_NUMBER (
1f600 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39  default value: 9
1f610 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  99)..**.** The t
1f620 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
1f630 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69   the value to bi
1f640 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65  nd to the parame
1f650 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68  ter..**.** In th
1f660 6f 73 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  ose.** routines 
1f670 74 68 61 74 20 68 61 76 65 20 61 20 66 6f 75 72  that have a four
1f680 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73  th argument, its
1f690 20 76 61 6c 75 65 20 69 73 20 74 68 65 20 6e 75   value is the nu
1f6a0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a  mber of bytes.**
1f6b0 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65   in the paramete
1f6c0 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a  r.  To be clear:
1f6d0 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 74 68   the value is th
1f6e0 65 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62  e number of <u>b
1f6f0 79 74 65 73 3c 2f 75 3e 0a 2a 2a 20 69 6e 20 74  ytes</u>.** in t
1f700 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68  he value, not th
1f710 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72  e number of char
1f720 61 63 74 65 72 73 2e 20 0a 2a 2a 20 49 66 20 74  acters. .** If t
1f730 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
1f740 74 65 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c  ter is negative,
1f750 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74   the length of t
1f760 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20  he string is.** 
1f770 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
1f780 74 65 73 20 75 70 20 74 6f 20 74 68 65 20 66 69  tes up to the fi
1f790 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  rst zero termina
1f7a0 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  tor..**.** The f
1f7b0 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f  ifth argument to
1f7c0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c   sqlite3_bind_bl
1f7d0 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 62 69  ob(), sqlite3_bi
1f7e0 6e 64 5f 74 65 78 74 28 29 2c 20 61 6e 64 0a 2a  nd_text(), and.*
1f7f0 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  * sqlite3_bind_t
1f800 65 78 74 31 36 28 29 20 69 73 20 61 20 64 65 73  ext16() is a des
1f810 74 72 75 63 74 6f 72 20 75 73 65 64 20 74 6f 20  tructor used to 
1f820 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42  dispose of the B
1f830 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67  LOB or.** string
1f840 20 61 66 74 65 72 20 53 51 4c 69 74 65 20 68 61   after SQLite ha
1f850 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20  s finished with 
1f860 69 74 2e 20 49 66 20 74 68 65 20 66 69 66 74 68  it. If the fifth
1f870 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20   argument is.** 
1f880 74 68 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75  the special valu
1f890 65 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43  e [SQLITE_STATIC
1f8a0 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 61  ], then SQLite a
1f8b0 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a  ssumes that the.
1f8c0 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  ** information i
1f8d0 73 20 69 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d  s in static, unm
1f8e0 61 6e 61 67 65 64 20 73 70 61 63 65 20 61 6e 64  anaged space and
1f8f0 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
1f900 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20 49  o be freed..** I
1f910 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75  f the fifth argu
1f920 6d 65 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c  ment has the val
1f930 75 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53  ue [SQLITE_TRANS
1f940 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53  IENT], then.** S
1f950 51 4c 69 74 65 20 6d 61 6b 65 73 20 69 74 73 20  QLite makes its 
1f960 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79  own private copy
1f970 20 6f 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d   of the data imm
1f980 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65  ediately, before
1f990 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f  .** the sqlite3_
1f9a0 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
1f9b0 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
1f9c0 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  The sqlite3_bind
1f9d0 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74  _zeroblob() rout
1f9e0 69 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f 42  ine binds a BLOB
1f9f0 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 68 61   of length N tha
1fa00 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 77  t.** is filled w
1fa10 69 74 68 20 7a 65 72 6f 73 2e 20 20 41 20 7a 65  ith zeros.  A ze
1fa20 72 6f 62 6c 6f 62 20 75 73 65 73 20 61 20 66 69  roblob uses a fi
1fa30 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65  xed amount of me
1fa40 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e  mory.** (just an
1fa50 20 69 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c 64   integer to hold
1fa60 20 69 74 20 73 69 7a 65 29 20 77 68 69 6c 65 20   it size) while 
1fa70 69 74 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63  it is being proc
1fa80 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c  essed..** Zerobl
1fa90 6f 62 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64  obs are intended
1faa0 20 74 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61   to serve as pla
1fab0 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c  ceholders for BL
1fac0 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e  OBs whose.** con
1fad0 74 65 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72  tent is later wr
1fae0 69 74 74 65 6e 20 75 73 69 6e 67 20 0a 2a 2a 20  itten using .** 
1faf0 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70  [sqlite3_blob_op
1fb00 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 20 42  en | increment B
1fb10 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65  LOB I/O] routine
1fb20 73 2e 20 41 20 6e 65 67 61 74 69 76 65 0a 2a 2a  s. A negative.**
1fb30 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 7a   value for the z
1fb40 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 20  eroblob results 
1fb50 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68  in a zero-length
1fb60 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   BLOB..**.** The
1fb70 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
1fb80 29 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20  ) routines must 
1fb90 62 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72 0a  be called after.
1fba0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
1fbb0 61 72 65 5f 76 32 28 29 5d 20 28 61 6e 64 20 69  are_v2()] (and i
1fbc0 74 73 20 76 61 72 69 61 6e 74 73 29 20 6f 72 20  ts variants) or 
1fbd0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
1fbe0 5d 20 61 6e 64 0a 2a 2a 20 62 65 66 6f 72 65 20  ] and.** before 
1fbf0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1fc00 2e 0a 2a 2a 20 42 69 6e 64 69 6e 67 73 20 61 72  ..** Bindings ar
1fc10 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79  e not cleared by
1fc20 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   the [sqlite3_re
1fc30 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a  set()] routine..
1fc40 2a 2a 20 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d  ** Unbound param
1fc50 65 74 65 72 73 20 61 72 65 20 69 6e 74 65 72 70  eters are interp
1fc60 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a  reted as NULL..*
1fc70 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
1fc80 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  nes return [SQLI
1fc90 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73  TE_OK] on succes
1fca0 73 20 6f 72 20 61 6e 20 65 72 72 6f 72 20 63 6f  s or an error co
1fcb0 64 65 20 69 66 0a 2a 2a 20 61 6e 79 74 68 69 6e  de if.** anythin
1fcc0 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 20 20 5b  g goes wrong.  [
1fcd0 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69 73  SQLITE_RANGE] is
1fce0 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 65   returned if the
1fcf0 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e   parameter.** in
1fd00 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61  dex is out of ra
1fd10 6e 67 65 2e 20 20 5b 53 51 4c 49 54 45 5f 4e 4f  nge.  [SQLITE_NO
1fd20 4d 45 4d 5d 20 69 73 20 72 65 74 75 72 6e 65 64  MEM] is returned
1fd30 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69   if malloc() fai
1fd40 6c 73 2e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d  ls..** [SQLITE_M
1fd50 49 53 55 53 45 5d 20 6d 69 67 68 74 20 62 65 20  ISUSE] might be 
1fd60 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 73  returned if thes
1fd70 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63  e routines are c
1fd80 61 6c 6c 65 64 20 6f 6e 20 61 0a 2a 2a 20 76 69  alled on a.** vi
1fd90 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 74 68  rtual machine th
1fda0 61 74 20 69 73 20 74 68 65 20 77 72 6f 6e 67 20  at is the wrong 
1fdb0 73 74 61 74 65 20 6f 72 20 77 68 69 63 68 20 68  state or which h
1fdc0 61 73 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20  as already been 
1fdd0 66 69 6e 61 6c 69 7a 65 64 2e 0a 2a 2a 20 44 65  finalized..** De
1fde0 74 65 63 74 69 6f 6e 20 6f 66 20 6d 69 73 75 73  tection of misus
1fdf0 65 20 69 73 20 75 6e 72 65 6c 69 61 62 6c 65 2e  e is unreliable.
1fe00 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73    Applications s
1fe10 68 6f 75 6c 64 20 6e 6f 74 20 64 65 70 65 6e 64  hould not depend
1fe20 0a 2a 2a 20 6f 6e 20 53 51 4c 49 54 45 5f 4d 49  .** on SQLITE_MI
1fe30 53 55 53 45 20 72 65 74 75 72 6e 73 2e 20 20 53  SUSE returns.  S
1fe40 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 69 73 20  QLITE_MISUSE is 
1fe50 69 6e 74 65 6e 64 65 64 20 74 6f 20 69 6e 64 69  intended to indi
1fe60 63 61 74 65 20 61 0a 2a 2a 20 61 20 6c 6f 67 69  cate a.** a logi
1fe70 63 20 65 72 72 6f 72 20 69 6e 20 74 68 65 20 61  c error in the a
1fe80 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 46 75 74  pplication.  Fut
1fe90 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
1fea0 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20  SQLite might.** 
1feb0 70 61 6e 69 63 20 72 61 74 68 65 72 20 74 68 61  panic rather tha
1fec0 6e 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f  n return SQLITE_
1fed0 4d 49 53 55 53 45 2e 0a 2a 2a 0a 2a 2a 20 53 65  MISUSE..**.** Se
1fee0 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
1fef0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
1ff00 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71  count()],.** [sq
1ff10 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
1ff20 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e  eter_name()], an
1ff30 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  d.** [sqlite3_bi
1ff40 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
1ff50 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  ex()]..**.** INV
1ff60 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
1ff70 46 31 33 35 30 36 7d 20 54 68 65 20 5b 73 71 6c  F13506} The [sql
1ff80 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 53  ite3_prepare | S
1ff90 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d  QL statement com
1ffa0 70 69 6c 65 72 5d 20 72 65 63 6f 67 6e 69 7a 65  piler] recognize
1ffb0 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f  s.**          to
1ffc0 6b 65 6e 73 20 6f 66 20 74 68 65 20 66 6f 72 6d  kens of the form
1ffd0 73 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22  s "?", "?NNN", "
1ffe0 24 56 56 56 22 2c 20 22 3a 56 56 56 22 2c 20 61  $VVV", ":VVV", a
1fff0 6e 64 20 22 40 56 56 56 22 0a 2a 2a 20 20 20 20  nd "@VVV".**    
20000 20 20 20 20 20 20 61 73 20 53 51 4c 20 70 61 72        as SQL par
20010 61 6d 65 74 65 72 73 2c 20 77 68 65 72 65 20 4e  ameters, where N
20020 4e 4e 20 69 73 20 61 6e 79 20 73 65 71 75 65 6e  NN is any sequen
20030 63 65 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72  ce of one or mor
20040 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 69  e.**          di
20050 67 69 74 73 20 61 6e 64 20 77 68 65 72 65 20 56  gits and where V
20060 56 56 20 69 73 20 61 6e 79 20 73 65 71 75 65 6e  VV is any sequen
20070 63 65 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72  ce of one or mor
20080 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  e .**          a
20090 6c 70 68 61 6e 75 6d 65 72 69 63 20 63 68 61 72  lphanumeric char
200a0 61 63 74 65 72 73 20 6f 72 20 22 3a 3a 22 20 6f  acters or "::" o
200b0 70 74 69 6f 6e 61 6c 6c 79 20 66 6f 6c 6c 6f 77  ptionally follow
200c0 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20  ed by.**        
200d0 20 20 61 20 73 74 72 69 6e 67 20 63 6f 6e 74 61    a string conta
200e0 69 6e 69 6e 67 20 6e 6f 20 73 70 61 63 65 73 20  ining no spaces 
200f0 61 6e 64 20 63 6f 6e 74 61 69 6e 65 64 20 77 69  and contained wi
20100 74 68 69 6e 20 70 61 72 65 6e 74 68 65 73 65 73  thin parentheses
20110 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 30 39 7d  ..**.** {F13509}
20120 20 54 68 65 20 69 6e 69 74 69 61 6c 20 76 61 6c   The initial val
20130 75 65 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72  ue of an SQL par
20140 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 2e 0a  ameter is NULL..
20150 2a 2a 0a 2a 2a 20 7b 46 31 33 35 31 32 7d 20 54  **.** {F13512} T
20160 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 22  he index of an "
20170 3f 22 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  ?" SQL parameter
20180 20 69 73 20 6f 6e 65 20 6c 61 72 67 65 72 20 74   is one larger t
20190 68 61 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  han the.**      
201a0 20 20 20 20 6c 61 72 67 65 73 74 20 69 6e 64 65      largest inde
201b0 78 20 6f 66 20 53 51 4c 20 70 61 72 61 6d 65 74  x of SQL paramet
201c0 65 72 20 74 6f 20 74 68 65 20 6c 65 66 74 2c 20  er to the left, 
201d0 6f 72 20 31 20 69 66 0a 2a 2a 20 20 20 20 20 20  or 1 if.**      
201e0 20 20 20 20 74 68 65 20 22 3f 22 20 69 73 20 74      the "?" is t
201f0 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20  he leftmost SQL 
20200 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
20210 20 7b 46 31 33 35 31 35 7d 20 54 68 65 20 69 6e   {F13515} The in
20220 64 65 78 20 6f 66 20 61 6e 20 22 3f 4e 4e 4e 22  dex of an "?NNN"
20230 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69   SQL parameter i
20240 73 20 74 68 65 20 69 6e 74 65 67 65 72 20 4e 4e  s the integer NN
20250 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 31 38  N..**.** {F13518
20260 7d 20 54 68 65 20 69 6e 64 65 78 20 6f 66 20 61  } The index of a
20270 6e 20 22 3a 56 56 56 22 2c 20 22 24 56 56 56 22  n ":VVV", "$VVV"
20280 2c 20 6f 72 20 22 40 56 56 56 22 20 53 51 4c 20  , or "@VVV" SQL 
20290 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20  parameter is.** 
202a0 20 20 20 20 20 20 20 20 20 74 68 65 20 73 61 6d           the sam
202b0 65 20 61 73 20 74 68 65 20 69 6e 64 65 78 20 6f  e as the index o
202c0 66 20 6c 65 66 74 6d 6f 73 74 20 6f 63 63 75 72  f leftmost occur
202d0 72 65 6e 63 65 73 20 6f 66 20 74 68 65 20 73 61  rences of the sa
202e0 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70  me.**          p
202f0 61 72 61 6d 65 74 65 72 2c 20 6f 72 20 6f 6e 65  arameter, or one
20300 20 6d 6f 72 65 20 74 68 61 6e 20 74 68 65 20 6c   more than the l
20310 61 72 67 65 73 74 20 69 6e 64 65 78 20 6f 76 65  argest index ove
20320 72 20 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20  r all.**        
20330 20 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20    parameters to 
20340 74 68 65 20 6c 65 66 74 20 69 66 20 74 68 69 73  the left if this
20350 20 69 73 20 74 68 65 20 66 69 72 73 74 20 6f 63   is the first oc
20360 63 75 72 72 65 6e 63 65 0a 2a 2a 20 20 20 20 20  currence.**     
20370 20 20 20 20 20 6f 66 20 74 68 69 73 20 70 61 72       of this par
20380 61 6d 65 74 65 72 2c 20 6f 72 20 31 20 69 66 20  ameter, or 1 if 
20390 74 68 69 73 20 69 73 20 74 68 65 20 6c 65 66 74  this is the left
203a0 6d 6f 73 74 20 70 61 72 61 6d 65 74 65 72 2e 0a  most parameter..
203b0 2a 2a 0a 2a 2a 20 7b 46 31 33 35 32 31 7d 20 54  **.** {F13521} T
203c0 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  he [sqlite3_prep
203d0 61 72 65 20 7c 20 53 51 4c 20 73 74 61 74 65 6d  are | SQL statem
203e0 65 6e 74 20 63 6f 6d 70 69 6c 65 72 5d 20 66 61  ent compiler] fa
203f0 69 6c 20 77 69 74 68 0a 2a 2a 20 20 20 20 20 20  il with.**      
20400 20 20 20 20 61 6e 20 5b 53 51 4c 49 54 45 5f 52      an [SQLITE_R
20410 41 4e 47 45 5d 20 65 72 72 6f 72 20 69 66 20 74  ANGE] error if t
20420 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53  he index of an S
20430 51 4c 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  QL parameter.** 
20440 20 20 20 20 20 20 20 20 20 69 73 20 6c 65 73 73           is less
20450 20 74 68 61 6e 20 31 20 6f 72 20 67 72 65 61 74   than 1 or great
20460 65 72 20 74 68 61 6e 20 53 51 4c 49 54 45 5f 4d  er than SQLITE_M
20470 41 58 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42  AX_VARIABLE_NUMB
20480 45 52 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 32  ER..**.** {F1352
20490 34 7d 20 43 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  4} Calls to [sql
204a0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c  ite3_bind_text |
204b0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 53 2c   sqlite3_bind(S,
204c0 4e 2c 56 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20  N,V,...)].**    
204d0 20 20 20 20 20 20 61 73 73 6f 63 69 61 74 65 20        associate 
204e0 74 68 65 20 76 61 6c 75 65 20 56 20 77 69 74 68  the value V with
204f0 20 61 6c 6c 20 53 51 4c 20 70 61 72 61 6d 65 74   all SQL paramet
20500 65 72 73 20 68 61 76 69 6e 67 20 61 6e 0a 2a 2a  ers having an.**
20510 20 20 20 20 20 20 20 20 20 20 69 6e 64 65 78 20            index 
20520 6f 66 20 4e 20 69 6e 20 74 68 65 20 5b 70 72 65  of N in the [pre
20530 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
20540 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 32   S..**.** {F1352
20550 37 7d 20 43 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  7} Calls to [sql
20560 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c  ite3_bind_text |
20570 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 53 2c   sqlite3_bind(S,
20580 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20  N,...)].**      
20590 20 20 20 20 6f 76 65 72 72 69 64 65 20 70 72 69      override pri
205a0 6f 72 20 63 61 6c 6c 73 20 77 69 74 68 20 74 68  or calls with th
205b0 65 20 73 61 6d 65 20 76 61 6c 75 65 73 20 6f 66  e same values of
205c0 20 53 20 61 6e 64 20 4e 2e 0a 2a 2a 0a 2a 2a 20   S and N..**.** 
205d0 7b 46 31 33 35 33 30 7d 20 42 69 6e 64 69 6e 67  {F13530} Binding
205e0 73 20 65 73 74 61 62 6c 69 73 68 65 64 20 62 79  s established by
205f0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74   [sqlite3_bind_t
20600 65 78 74 20 7c 20 73 71 6c 69 74 65 33 5f 62 69  ext | sqlite3_bi
20610 6e 64 28 53 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20  nd(S,...)].**   
20620 20 20 20 20 20 20 20 70 65 72 73 69 73 74 20 61         persist a
20630 63 72 6f 73 73 20 63 61 6c 6c 73 20 74 6f 20 5b  cross calls to [
20640 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
20650 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 33 33  ]..**.** {F13533
20660 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73  } In calls to [s
20670 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
20680 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a  (S,N,V,L,D)],.**
20690 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
206a0 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 53 2c 4e  e3_bind_text(S,N
206b0 2c 56 2c 4c 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20  ,V,L,D)], or.** 
206c0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
206d0 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 53 2c  3_bind_text16(S,
206e0 4e 2c 56 2c 4c 2c 44 29 5d 20 53 51 4c 69 74 65  N,V,L,D)] SQLite
206f0 20 62 69 6e 64 73 20 74 68 65 20 66 69 72 73 74   binds the first
20700 20 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62   L.**          b
20710 79 74 65 73 20 6f 66 20 74 68 65 20 62 6c 6f 62  ytes of the blob
20720 20 6f 72 20 73 74 72 69 6e 67 20 70 6f 69 6e 74   or string point
20730 65 64 20 74 6f 20 62 79 20 56 2c 20 77 68 65 6e  ed to by V, when
20740 20 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69   L.**          i
20750 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2e 0a  s non-negative..
20760 2a 2a 0a 2a 2a 20 7b 46 31 33 35 33 36 7d 20 49  **.** {F13536} I
20770 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  n calls to [sqli
20780 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 53 2c  te3_bind_text(S,
20790 4e 2c 56 2c 4c 2c 44 29 5d 20 6f 72 0a 2a 2a 20  N,V,L,D)] or.** 
207a0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
207b0 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 53 2c  3_bind_text16(S,
207c0 4e 2c 56 2c 4c 2c 44 29 5d 20 53 51 4c 69 74 65  N,V,L,D)] SQLite
207d0 20 62 69 6e 64 73 20 63 68 61 72 61 63 74 65 72   binds character
207e0 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 72  s.**          fr
207f0 6f 6d 20 56 20 74 68 72 6f 75 67 68 20 74 68 65  om V through the
20800 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72   first zero char
20810 61 63 74 65 72 20 77 68 65 6e 20 4c 20 69 73 20  acter when L is 
20820 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20  negative..**.** 
20830 7b 46 31 33 35 33 39 7d 20 49 6e 20 63 61 6c 6c  {F13539} In call
20840 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69  s to [sqlite3_bi
20850 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 2c  nd_blob(S,N,V,L,
20860 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  D)],.**         
20870 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74   [sqlite3_bind_t
20880 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c  ext(S,N,V,L,D)],
20890 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   or.**          
208a0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65  [sqlite3_bind_te
208b0 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d  xt16(S,N,V,L,D)]
208c0 20 77 68 65 6e 20 44 20 69 73 20 74 68 65 20 73   when D is the s
208d0 70 65 63 69 61 6c 0a 2a 2a 20 20 20 20 20 20 20  pecial.**       
208e0 20 20 20 63 6f 6e 73 74 61 6e 74 20 5b 53 51 4c     constant [SQL
208f0 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 53 51 4c  ITE_STATIC], SQL
20900 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 74  ite assumes that
20910 20 74 68 65 20 76 61 6c 75 65 20 56 0a 2a 2a 20   the value V.** 
20920 20 20 20 20 20 20 20 20 20 69 73 20 68 65 6c 64           is held
20930 20 69 6e 20 73 74 61 74 69 63 20 75 6e 6d 61 6e   in static unman
20940 61 67 65 64 20 73 70 61 63 65 20 74 68 61 74 20  aged space that 
20950 77 69 6c 6c 20 6e 6f 74 20 63 68 61 6e 67 65 0a  will not change.
20960 2a 2a 20 20 20 20 20 20 20 20 20 20 64 75 72 69  **          duri
20970 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20  ng the lifetime 
20980 6f 66 20 74 68 65 20 62 69 6e 64 69 6e 67 2e 0a  of the binding..
20990 2a 2a 0a 2a 2a 20 7b 46 31 33 35 34 32 7d 20 49  **.** {F13542} I
209a0 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  n calls to [sqli
209b0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 53 2c  te3_bind_blob(S,
209c0 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20  N,V,L,D)],.**   
209d0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
209e0 62 69 6e 64 5f 74 65 78 74 28 53 2c 4e 2c 56 2c  bind_text(S,N,V,
209f0 4c 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20  L,D)], or.**    
20a00 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62        [sqlite3_b
20a10 69 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e 2c 56  ind_text16(S,N,V
20a20 2c 4c 2c 44 29 5d 20 77 68 65 6e 20 44 20 69 73  ,L,D)] when D is
20a30 20 74 68 65 20 73 70 65 63 69 61 6c 0a 2a 2a 20   the special.** 
20a40 20 20 20 20 20 20 20 20 20 63 6f 6e 73 74 61 6e           constan
20a50 74 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  t [SQLITE_TRANSI
20a60 45 4e 54 5d 2c 20 74 68 65 20 72 6f 75 74 69 6e  ENT], the routin
20a70 65 20 6d 61 6b 65 73 20 61 20 0a 2a 2a 20 20 20  e makes a .**   
20a80 20 20 20 20 20 20 20 70 72 69 76 61 74 65 20 63         private c
20a90 6f 70 79 20 6f 66 20 56 20 76 61 6c 75 65 20 62  opy of V value b
20aa0 65 66 6f 72 65 20 69 74 20 72 65 74 75 72 6e 73  efore it returns
20ab0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 34 35 7d  ..**.** {F13545}
20ac0 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71   In calls to [sq
20ad0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
20ae0 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20  S,N,V,L,D)],.** 
20af0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
20b00 33 5f 62 69 6e 64 5f 74 65 78 74 28 53 2c 4e 2c  3_bind_text(S,N,
20b10 56 2c 4c 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20  V,L,D)], or.**  
20b20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
20b30 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e  _bind_text16(S,N
20b40 2c 56 2c 4c 2c 44 29 5d 20 77 68 65 6e 20 44 20  ,V,L,D)] when D 
20b50 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a  is a pointer to.
20b60 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 66 75  **          a fu
20b70 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 69  nction, SQLite i
20b80 6e 76 6f 6b 65 73 20 74 68 61 74 20 66 75 6e 63  nvokes that func
20b90 74 69 6f 6e 20 74 6f 20 64 65 73 74 72 6f 79 20  tion to destroy 
20ba0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
20bb0 56 20 76 61 6c 75 65 20 61 66 74 65 72 20 69 74  V value after it
20bc0 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 75 73   has finished us
20bd0 69 6e 67 20 74 68 65 20 56 20 76 61 6c 75 65 2e  ing the V value.
20be0 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 34 38 7d 20  .**.** {F13548} 
20bf0 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  In calls to [sql
20c00 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c  ite3_bind_zerobl
20c10 6f 62 28 53 2c 4e 2c 56 2c 4c 29 5d 20 74 68 65  ob(S,N,V,L)] the
20c20 20 76 61 6c 75 65 20 62 6f 75 6e 64 0a 2a 2a 20   value bound.** 
20c30 20 20 20 20 20 20 20 20 20 69 73 20 61 20 62 6c           is a bl
20c40 6f 62 20 6f 66 20 4c 20 62 79 74 65 73 2c 20 6f  ob of L bytes, o
20c50 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20  r a zero-length 
20c60 62 6c 6f 62 20 69 66 20 4c 20 69 73 20 6e 65 67  blob if L is neg
20c70 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  ative..**.** {F1
20c80 33 35 35 31 7d 20 49 6e 20 63 61 6c 6c 73 20 74  3551} In calls t
20c90 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  o [sqlite3_bind_
20ca0 76 61 6c 75 65 28 53 2c 4e 2c 56 29 5d 20 74 68  value(S,N,V)] th
20cb0 65 20 56 20 61 72 67 75 6d 65 6e 74 20 6d 61 79  e V argument may
20cc0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 65 20  .**          be 
20cd0 65 69 74 68 65 72 20 61 20 5b 70 72 6f 74 65 63  either a [protec
20ce0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
20cf0 65 5d 20 6f 62 6a 65 63 74 20 6f 72 20 61 6e 0a  e] object or an.
20d00 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 75 6e 70  **          [unp
20d10 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
20d20 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 0a  _value] object..
20d30 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
20d40 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  ind_blob(sqlite3
20d50 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
20d60 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c  st void*, int n,
20d70 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
20d80 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
20d90 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65  nd_double(sqlite
20da0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f  3_stmt*, int, do
20db0 75 62 6c 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74  uble);.int sqlit
20dc0 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69  e3_bind_int(sqli
20dd0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
20de0 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  int);.int sqlite
20df0 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c  3_bind_int64(sql
20e00 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
20e10 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b   sqlite3_int64);
20e20 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
20e30 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73  d_null(sqlite3_s
20e40 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20  tmt*, int);.int 
20e50 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
20e60 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  t(sqlite3_stmt*,
20e70 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 72   int, const char
20e80 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a  *, int n, void(*
20e90 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73  )(void*));.int s
20ea0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
20eb0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
20ec0 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69  , int, const voi
20ed0 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  d*, int, void(*)
20ee0 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71  (void*));.int sq
20ef0 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65  lite3_bind_value
20f00 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
20f10 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74  int, const sqlit
20f20 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
20f30 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72  sqlite3_bind_zer
20f40 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74  oblob(sqlite3_st
20f50 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29  mt*, int, int n)
20f60 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
20f70 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c  F: Number Of SQL
20f80 20 50 61 72 61 6d 65 74 65 72 73 20 7b 46 31 33   Parameters {F13
20f90 36 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  600}.**.** This 
20fa0 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 75  routine can be u
20fb0 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20  sed to find the 
20fc0 6e 75 6d 62 65 72 20 6f 66 20 53 51 4c 20 70 61  number of SQL pa
20fd0 72 61 6d 65 74 65 72 73 0a 2a 2a 20 69 6e 20 61  rameters.** in a
20fe0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
20ff0 65 6e 74 2e 20 20 53 51 4c 20 70 61 72 61 6d 65  ent.  SQL parame
21000 74 65 72 73 20 61 72 65 20 74 6f 6b 65 6e 73 20  ters are tokens 
21010 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22  of the.** form "
21020 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41  ?", "?NNN", ":AA
21030 41 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 20 22  A", "$AAA", or "
21040 40 41 41 41 22 20 74 68 61 74 20 73 65 72 76 65  @AAA" that serve
21050 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64   as.** placehold
21060 65 72 73 20 66 6f 72 20 76 61 6c 75 65 73 20 74  ers for values t
21070 68 61 74 20 61 72 65 20 5b 73 71 6c 69 74 65 33  hat are [sqlite3
21080 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75  _bind_blob | bou
21090 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61  nd].** to the pa
210a0 72 61 6d 65 74 65 72 73 20 61 74 20 61 20 6c 61  rameters at a la
210b0 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20  ter time..**.** 
210c0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 61 63 74  This routine act
210d0 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 68  ually returns th
210e0 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 6c  e index of the l
210f0 61 72 67 65 73 74 20 70 61 72 61 6d 65 74 65 72  argest parameter
21100 2e 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 66 6f 72  ..** For all for
21110 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20  ms except ?NNN, 
21120 74 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 73  this will corres
21130 70 6f 6e 64 20 74 6f 20 74 68 65 20 6e 75 6d 62  pond to the numb
21140 65 72 20 6f 66 0a 2a 2a 20 75 6e 69 71 75 65 20  er of.** unique 
21150 70 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66 20  parameters.  If 
21160 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68  parameters of th
21170 65 20 3f 4e 4e 4e 20 61 72 65 20 75 73 65 64 2c  e ?NNN are used,
21180 20 74 68 65 72 65 20 6d 61 79 0a 2a 2a 20 62 65   there may.** be
21190 20 67 61 70 73 20 69 6e 20 74 68 65 20 6c 69 73   gaps in the lis
211a0 74 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  t..**.** See als
211b0 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  o: [sqlite3_bind
211c0 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
211d0 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  nd()],.** [sqlit
211e0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
211f0 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a  r_name()], and.*
21200 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
21210 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
21220 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  )]..**.** INVARI
21230 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  ANTS:.**.** {F13
21240 36 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  601} The [sqlite
21250 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
21260 5f 63 6f 75 6e 74 28 53 29 5d 20 69 6e 74 65 72  _count(S)] inter
21270 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20  face returns.** 
21280 20 20 20 20 20 20 20 20 20 74 68 65 20 6c 61 72           the lar
21290 67 65 73 74 20 69 6e 64 65 78 20 6f 66 20 61 6c  gest index of al
212a0 6c 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73  l SQL parameters
212b0 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   in the.**      
212c0 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74      [prepared st
212d0 61 74 65 6d 65 6e 74 5d 20 53 2c 20 6f 72 20 30  atement] S, or 0
212e0 20 69 66 20 53 0a 2a 2a 20 20 20 20 20 20 20 20   if S.**        
212f0 20 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51    contains no SQ
21300 4c 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f  L parameters..*/
21310 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
21320 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
21330 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  t(sqlite3_stmt*)
21340 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
21350 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73  F: Name Of A Hos
21360 74 20 50 61 72 61 6d 65 74 65 72 20 7b 46 31 33  t Parameter {F13
21370 36 32 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  620}.**.** This 
21380 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
21390 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
213a0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6e 2d 74   name of the n-t
213b0 68 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74  h.** SQL paramet
213c0 65 72 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65  er in a [prepare
213d0 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  d statement]..**
213e0 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20   SQL parameters 
213f0 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e  of the form "?NN
21400 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20  N" or ":AAA" or 
21410 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22  "@AAA" or "$AAA"
21420 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65 20  .** have a name 
21430 77 68 69 63 68 20 69 73 20 74 68 65 20 73 74 72  which is the str
21440 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a  ing "?NNN" or ":
21450 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f  AAA" or "@AAA" o
21460 72 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73 70  r "$AAA".** resp
21470 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20  ectively..** In 
21480 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65  other words, the
21490 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 20   initial ":" or 
214a0 22 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22 3f  "$" or "@" or "?
214b0 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 64  ".** is included
214c0 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 20   as part of the 
214d0 6e 61 6d 65 2e 0a 2a 2a 20 50 61 72 61 6d 65 74  name..** Paramet
214e0 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20  ers of the form 
214f0 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66 6f  "?" without a fo
21500 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 20  llowing integer 
21510 68 61 76 65 20 6e 6f 20 6e 61 6d 65 2e 0a 2a 2a  have no name..**
21520 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 68 6f  .** The first ho
21530 73 74 20 70 61 72 61 6d 65 74 65 72 20 68 61 73  st parameter has
21540 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20   an index of 1, 
21550 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  not 0..**.** If 
21560 74 68 65 20 76 61 6c 75 65 20 6e 20 69 73 20 6f  the value n is o
21570 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 69  ut of range or i
21580 66 20 74 68 65 20 6e 2d 74 68 20 70 61 72 61 6d  f the n-th param
21590 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c  eter is.** namel
215a0 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69  ess, then NULL i
215b0 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65  s returned.  The
215c0 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
215d0 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e   is.** always in
215e0 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64   the UTF-8 encod
215f0 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20  ing even if the 
21600 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20  named parameter 
21610 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c  was.** originall
21620 79 20 73 70 65 63 69 66 69 65 64 20 61 73 20 55  y specified as U
21630 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65  TF-16 in [sqlite
21640 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 6f  3_prepare16()] o
21650 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  r.** [sqlite3_pr
21660 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a  epare16_v2()]..*
21670 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
21680 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
21690 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
216a0 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
216b0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
216c0 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  unt()], and.** [
216d0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
216e0 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e  ameter_index()].
216f0 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
21700 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 36 32 31  S:.**.** {F13621
21710 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  } The [sqlite3_b
21720 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
21730 6d 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61  me(S,N)] interfa
21740 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20  ce returns.**   
21750 20 20 20 20 20 20 20 61 20 55 54 46 2d 38 20 72         a UTF-8 r
21760 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20  endering of the 
21770 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20  name of the SQL 
21780 70 61 72 61 6d 65 74 65 72 20 69 6e 0a 2a 2a 20  parameter in.** 
21790 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72           [prepar
217a0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
217b0 68 61 76 69 6e 67 20 69 6e 64 65 78 20 4e 2c 20  having index N, 
217c0 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e  or.**          N
217d0 55 4c 4c 20 69 66 20 74 68 65 72 65 20 69 73 20  ULL if there is 
217e0 6e 6f 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  no SQL parameter
217f0 20 77 69 74 68 20 69 6e 64 65 78 20 4e 20 6f 72   with index N or
21800 20 69 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   if the.**      
21810 20 20 20 20 70 61 72 61 6d 65 74 65 72 20 77 69      parameter wi
21820 74 68 20 69 6e 64 65 78 20 4e 20 69 73 20 61 6e  th index N is an
21830 20 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d   anonymous param
21840 65 74 65 72 20 22 3f 22 2e 0a 2a 2f 0a 63 6f 6e  eter "?"..*/.con
21850 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
21860 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
21870 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
21880 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  t*, int);../*.**
21890 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78   CAPI3REF: Index
218a0 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72 20   Of A Parameter 
218b0 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d  With A Given Nam
218c0 65 20 7b 46 31 33 36 34 30 7d 0a 2a 2a 0a 2a 2a  e {F13640}.**.**
218d0 20 52 65 74 75 72 6e 20 74 68 65 20 69 6e 64 65   Return the inde
218e0 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61  x of an SQL para
218f0 6d 65 74 65 72 20 67 69 76 65 6e 20 69 74 73 20  meter given its 
21900 6e 61 6d 65 2e 20 20 54 68 65 0a 2a 2a 20 69 6e  name.  The.** in
21910 64 65 78 20 76 61 6c 75 65 20 72 65 74 75 72 6e  dex value return
21920 65 64 20 69 73 20 73 75 69 74 61 62 6c 65 20 66  ed is suitable f
21930 6f 72 20 75 73 65 20 61 73 20 74 68 65 20 73 65  or use as the se
21940 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65  cond.** paramete
21950 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69  r to [sqlite3_bi
21960 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f  nd_blob|sqlite3_
21970 62 69 6e 64 28 29 5d 2e 20 20 41 20 7a 65 72 6f  bind()].  A zero
21980 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20  .** is returned 
21990 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70  if no matching p
219a0 61 72 61 6d 65 74 65 72 20 69 73 20 66 6f 75 6e  arameter is foun
219b0 64 2e 20 20 54 68 65 20 70 61 72 61 6d 65 74 65  d.  The paramete
219c0 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62  r.** name must b
219d0 65 20 67 69 76 65 6e 20 69 6e 20 55 54 46 2d 38  e given in UTF-8
219e0 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 72 69   even if the ori
219f0 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a  ginal statement.
21a00 2a 2a 20 77 61 73 20 70 72 65 70 61 72 65 64 20  ** was prepared 
21a10 66 72 6f 6d 20 55 54 46 2d 31 36 20 74 65 78 74  from UTF-16 text
21a20 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
21a30 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
21a40 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
21a50 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
21a60 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
21a70 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
21a80 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
21a90 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a  count()], and.**
21aa0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
21ab0 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
21ac0 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  ]..**.** INVARIA
21ad0 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 36  NTS:.**.** {F136
21ae0 34 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  41} The [sqlite3
21af0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
21b00 69 6e 64 65 78 28 53 2c 4e 29 5d 20 69 6e 74 65  index(S,N)] inte
21b10 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a  rface returns.**
21b20 20 20 20 20 20 20 20 20 20 20 74 68 65 20 69 6e            the in
21b30 64 65 78 20 6f 66 20 53 51 4c 20 70 61 72 61 6d  dex of SQL param
21b40 65 74 65 72 20 69 6e 20 5b 70 72 65 70 61 72 65  eter in [prepare
21b50 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
21b60 20 20 20 20 20 20 20 20 20 53 20 77 68 6f 73 65           S whose
21b70 20 6e 61 6d 65 20 6d 61 74 63 68 65 73 20 74 68   name matches th
21b80 65 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 4e  e UTF-8 string N
21b90 2c 20 6f 72 20 30 20 69 66 20 74 68 65 72 65 20  , or 0 if there 
21ba0 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e  is.**          n
21bb0 6f 20 6d 61 74 63 68 2e 0a 2a 2f 0a 69 6e 74 20  o match..*/.int 
21bc0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
21bd0 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 73 71 6c  ameter_index(sql
21be0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73  ite3_stmt*, cons
21bf0 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a  t char *zName);.
21c00 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
21c10 20 52 65 73 65 74 20 41 6c 6c 20 42 69 6e 64 69   Reset All Bindi
21c20 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 61 72 65  ngs On A Prepare
21c30 64 20 53 74 61 74 65 6d 65 6e 74 20 7b 46 31 33  d Statement {F13
21c40 36 36 30 7d 0a 2a 2a 0a 2a 2a 20 43 6f 6e 74 72  660}.**.** Contr
21c50 61 72 79 20 74 6f 20 74 68 65 20 69 6e 74 75 69  ary to the intui
21c60 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73  tion of many, [s
21c70 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
21c80 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 72 65 73 65  does not.** rese
21c90 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  t the [sqlite3_b
21ca0 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69  ind_blob | bindi
21cb0 6e 67 73 5d 20 6f 6e 20 61 20 0a 2a 2a 20 5b 70  ngs] on a .** [p
21cc0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
21cd0 74 5d 2e 20 20 55 73 65 20 74 68 69 73 20 72 6f  t].  Use this ro
21ce0 75 74 69 6e 65 20 74 6f 0a 2a 2a 20 72 65 73 65  utine to.** rese
21cf0 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d  t all host param
21d00 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a  eters to NULL..*
21d10 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
21d20 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 36 36 31 7d 20  .**.** {F13661} 
21d30 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65  The [sqlite3_cle
21d40 61 72 5f 62 69 6e 64 69 6e 67 73 28 53 29 5d 20  ar_bindings(S)] 
21d50 69 6e 74 65 72 66 61 63 65 20 72 65 73 65 74 73  interface resets
21d60 20 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20   all.**         
21d70 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 62   SQL parameter b
21d80 69 6e 64 69 6e 67 73 20 69 6e 20 5b 70 72 65 70  indings in [prep
21d90 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
21da0 53 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 61  S.**          ba
21db0 63 6b 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69  ck to NULL..*/.i
21dc0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 72  nt sqlite3_clear
21dd0 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65  _bindings(sqlite
21de0 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  3_stmt*);../*.**
21df0 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65   CAPI3REF: Numbe
21e00 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20  r Of Columns In 
21e10 41 20 52 65 73 75 6c 74 20 53 65 74 20 7b 46 31  A Result Set {F1
21e20 33 37 31 30 7d 0a 2a 2a 0a 2a 2a 20 52 65 74 75  3710}.**.** Retu
21e30 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  rn the number of
21e40 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20   columns in the 
21e50 72 65 73 75 6c 74 20 73 65 74 20 72 65 74 75 72  result set retur
21e60 6e 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 5b  ned by the .** [
21e70 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
21e80 6e 74 5d 2e 20 54 68 69 73 20 72 6f 75 74 69 6e  nt]. This routin
21e90 65 20 72 65 74 75 72 6e 73 20 30 0a 2a 2a 20 69  e returns 0.** i
21ea0 66 20 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51  f pStmt is an SQ
21eb0 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74  L statement that
21ec0 20 64 6f 65 73 20 6e 6f 74 20 72 65 74 75 72 6e   does not return
21ed0 20 64 61 74 61 20 28 66 6f 72 20 0a 2a 2a 20 65   data (for .** e
21ee0 78 61 6d 70 6c 65 20 61 6e 20 55 50 44 41 54 45  xample an UPDATE
21ef0 29 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  )..**.** INVARIA
21f00 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37  NTS:.**.** {F137
21f10 31 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  11} The [sqlite3
21f20 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 53 29  _column_count(S)
21f30 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
21f40 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
21f50 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f  f.**          co
21f60 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73  lumns in the res
21f70 75 6c 74 20 73 65 74 20 67 65 6e 65 72 61 74 65  ult set generate
21f80 64 20 62 79 20 74 68 65 0a 2a 2a 20 20 20 20 20  d by the.**     
21f90 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73       [prepared s
21fa0 74 61 74 65 6d 65 6e 74 5d 20 53 2c 20 6f 72 20  tatement] S, or 
21fb0 30 20 69 66 20 53 20 64 6f 65 73 20 6e 6f 74 20  0 if S does not 
21fc0 67 65 6e 65 72 61 74 65 0a 2a 2a 20 20 20 20 20  generate.**     
21fd0 20 20 20 20 20 61 20 72 65 73 75 6c 74 20 73 65       a result se
21fe0 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  t..*/.int sqlite
21ff0 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73  3_column_count(s
22000 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
22010 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
22020 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d  3REF: Column Nam
22030 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53  es In A Result S
22040 65 74 20 7b 46 31 33 37 32 30 7d 0a 2a 2a 0a 2a  et {F13720}.**.*
22050 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
22060 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65   return the name
22070 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70   assigned to a p
22080 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e  articular column
22090 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c  .** in the resul
220a0 74 20 73 65 74 20 6f 66 20 61 20 53 45 4c 45 43  t set of a SELEC
220b0 54 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 54 68  T statement.  Th
220c0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
220d0 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72  _name().** inter
220e0 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70  face returns a p
220f0 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f  ointer to a zero
22100 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 38  -terminated UTF8
22110 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73   string.** and s
22120 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
22130 6d 65 31 36 28 29 20 72 65 74 75 72 6e 73 20 61  me16() returns a
22140 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65   pointer to a ze
22150 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
22160 20 55 54 46 31 36 20 73 74 72 69 6e 67 2e 20 20   UTF16 string.  
22170 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
22180 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 70  ter is the.** [p
22190 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
221a0 74 5d 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  t] that implemen
221b0 74 73 20 74 68 65 20 53 45 4c 45 43 54 20 73 74  ts the SELECT st
221c0 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20  atement..** The 
221d0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
221e0 20 69 73 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e   is the column n
221f0 75 6d 62 65 72 2e 20 20 54 68 65 20 6c 65 66 74  umber.  The left
22200 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 0a  -most column is.
22210 2a 2a 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a  ** number 0..**.
22220 2a 2a 20 54 68 65 20 72 65 74 75 72 6e 65 64 20  ** The returned 
22230 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 69  string pointer i
22240 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 65 69  s valid until ei
22250 74 68 65 72 20 74 68 65 20 0a 2a 2a 20 5b 70 72  ther the .** [pr
22260 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
22270 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64 20 62  ] is destroyed b
22280 79 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  y [sqlite3_final
22290 69 7a 65 28 29 5d 0a 2a 2a 20 6f 72 20 75 6e 74  ize()].** or unt
222a0 69 6c 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c  il the next call
222b0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
222c0 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65  name() or sqlite
222d0 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
222e0 29 0a 2a 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65  ).** on the same
222f0 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 49   column..**.** I
22300 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  f sqlite3_malloc
22310 28 29 20 66 61 69 6c 73 20 64 75 72 69 6e 67 20  () fails during 
22320 74 68 65 20 70 72 6f 63 65 73 73 69 6e 67 20 6f  the processing o
22330 66 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65  f either routine
22340 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  .** (for example
22350 20 64 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 72   during a conver
22360 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20  sion from UTF-8 
22370 74 6f 20 55 54 46 2d 31 36 29 20 74 68 65 6e 20  to UTF-16) then 
22380 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  a.** NULL pointe
22390 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  r is returned..*
223a0 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66  *.** The name of
223b0 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e   a result column
223c0 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66   is the value of
223d0 20 74 68 65 20 22 41 53 22 20 63 6c 61 75 73 65   the "AS" clause
223e0 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c   for.** that col
223f0 75 6d 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73  umn, if there is
22400 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20   an AS clause.  
22410 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41  If there is no A
22420 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e  S clause.** then
22430 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
22440 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65   column is unspe
22450 63 69 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63  cified and may c
22460 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e  hange from.** on
22470 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c  e release of SQL
22480 69 74 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e  ite to the next.
22490 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
224a0 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 32 31  S:.**.** {F13721
224b0 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 69  } A successful i
224c0 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 65  nvocation of the
224d0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
224e0 5f 6e 61 6d 65 28 53 2c 4e 29 5d 0a 2a 2a 20 20  _name(S,N)].**  
224f0 20 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 63          interfac
22500 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 61  e returns the na
22510 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  me.**          o
22520 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  f the Nth column
22530 20 28 77 68 65 72 65 20 30 20 69 73 20 74 68 65   (where 0 is the
22540 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d   left-most colum
22550 6e 29 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20  n) for the.**   
22560 20 20 20 20 20 20 20 72 65 73 75 6c 74 20 73 65         result se
22570 74 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73  t of [prepared s
22580 74 61 74 65 6d 65 6e 74 5d 20 53 20 61 73 20 61  tatement] S as a
22590 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72  .**          zer
225a0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
225b0 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  -8 string..**.**
225c0 20 7b 46 31 33 37 32 33 7d 20 41 20 73 75 63 63   {F13723} A succ
225d0 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f  essful invocatio
225e0 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  n of the [sqlite
225f0 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
22600 53 2c 4e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  S,N)].**        
22610 20 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75    interface retu
22620 72 6e 73 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20  rns the name.** 
22630 20 20 20 20 20 20 20 20 20 6f 66 20 74 68 65 20           of the 
22640 4e 74 68 20 63 6f 6c 75 6d 6e 20 28 77 68 65 72  Nth column (wher
22650 65 20 30 20 69 73 20 74 68 65 20 6c 65 66 74 2d  e 0 is the left-
22660 6d 6f 73 74 20 63 6f 6c 75 6d 6e 29 20 66 6f 72  most column) for
22670 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
22680 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 5b   result set of [
22690 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
226a0 6e 74 5d 20 53 20 61 73 20 61 0a 2a 2a 20 20 20  nt] S as a.**   
226b0 20 20 20 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d         zero-term
226c0 69 6e 61 74 65 64 20 55 54 46 2d 31 36 20 73 74  inated UTF-16 st
226d0 72 69 6e 67 20 69 6e 20 74 68 65 20 6e 61 74 69  ring in the nati
226e0 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a  ve byte order..*
226f0 2a 0a 2a 2a 20 7b 46 31 33 37 32 34 7d 20 54 68  *.** {F13724} Th
22700 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
22710 6e 5f 6e 61 6d 65 28 29 5d 20 61 6e 64 20 5b 73  n_name()] and [s
22720 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
22730 6d 65 31 36 28 29 5d 0a 2a 2a 20 20 20 20 20 20  me16()].**      
22740 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 20 72      interfaces r
22750 65 74 75 72 6e 20 61 20 4e 55 4c 4c 20 70 6f 69  eturn a NULL poi
22760 6e 74 65 72 20 69 66 20 74 68 65 79 20 61 72 65  nter if they are
22770 20 75 6e 61 62 6c 65 20 74 6f 0a 2a 2a 20 20 20   unable to.**   
22780 20 20 20 20 20 20 20 61 6c 6c 6f 63 61 74 65 20         allocate 
22790 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  memory to hold t
227a0 68 65 69 72 20 6e 6f 72 6d 61 6c 20 72 65 74 75  heir normal retu
227b0 72 6e 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 0a 2a  rn strings..**.*
227c0 2a 20 7b 46 31 33 37 32 35 7d 20 49 66 20 74 68  * {F13725} If th
227d0 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 74 6f  e N parameter to
227e0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
227f0 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 6f 72 0a 2a  _name(S,N)] or.*
22800 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
22810 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
22820 36 28 53 2c 4e 29 5d 20 69 73 20 6f 75 74 20 6f  6(S,N)] is out o
22830 66 20 72 61 6e 67 65 2c 20 74 68 65 6e 20 74 68  f range, then th
22840 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  e.**          in
22850 74 65 72 66 61 63 65 73 20 72 65 74 75 72 6e 20  terfaces return 
22860 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
22870 2a 2a 20 0a 2a 2a 20 7b 46 31 33 37 32 36 7d 20  ** .** {F13726} 
22880 54 68 65 20 73 74 72 69 6e 67 73 20 72 65 74 75  The strings retu
22890 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
228a0 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 53 2c 4e  _column_name(S,N
228b0 29 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20  )] and.**       
228c0 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75     [sqlite3_colu
228d0 6d 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20  mn_name16(S,N)] 
228e0 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20  are valid until 
228f0 74 68 65 20 6e 65 78 74 0a 2a 2a 20 20 20 20 20  the next.**     
22900 20 20 20 20 20 63 61 6c 6c 20 74 6f 20 65 69 74       call to eit
22910 68 65 72 20 72 6f 75 74 69 6e 65 20 77 69 74 68  her routine with
22920 20 74 68 65 20 73 61 6d 65 20 53 20 61 6e 64 20   the same S and 
22930 4e 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20  N parameters.** 
22940 20 20 20 20 20 20 20 20 20 6f 72 20 75 6e 74 69           or unti
22950 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  l [sqlite3_final
22960 69 7a 65 28 53 29 5d 20 69 73 20 63 61 6c 6c 65  ize(S)] is calle
22970 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 32 37  d..**.** {F13727
22980 7d 20 57 68 65 6e 20 61 20 72 65 73 75 6c 74 20  } When a result 
22990 63 6f 6c 75 6d 6e 20 6f 66 20 61 20 5b 53 45 4c  column of a [SEL
229a0 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 63  ECT] statement c
229b0 6f 6e 74 61 69 6e 73 0a 2a 2a 20 20 20 20 20 20  ontains.**      
229c0 20 20 20 20 61 6e 20 41 53 20 63 6c 61 75 73 65      an AS clause
229d0 2c 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  , the name of th
229e0 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65  at column is the
229f0 20 69 64 65 6e 74 69 66 69 65 72 0a 2a 2a 20 20   identifier.**  
22a00 20 20 20 20 20 20 20 20 74 6f 20 74 68 65 20 72          to the r
22a10 69 67 68 74 20 6f 66 20 74 68 65 20 41 53 20 6b  ight of the AS k
22a20 65 79 77 6f 72 64 2e 0a 2a 2f 0a 63 6f 6e 73 74  eyword..*/.const
22a30 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
22a40 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74  olumn_name(sqlit
22a50 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29  e3_stmt*, int N)
22a60 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
22a70 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
22a80 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
22a90 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a  *, int N);../*.*
22aa0 2a 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75 72  * CAPI3REF: Sour
22ab0 63 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41 20  ce Of Data In A 
22ac0 51 75 65 72 79 20 52 65 73 75 6c 74 20 7b 46 31  Query Result {F1
22ad0 33 37 34 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  3740}.**.** Thes
22ae0 65 20 72 6f 75 74 69 6e 65 73 20 70 72 6f 76 69  e routines provi
22af0 64 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 64 65  de a means to de
22b00 74 65 72 6d 69 6e 65 20 77 68 61 74 20 63 6f 6c  termine what col
22b10 75 6d 6e 20 6f 66 20 77 68 61 74 0a 2a 2a 20 74  umn of what.** t
22b20 61 62 6c 65 20 69 6e 20 77 68 69 63 68 20 64 61  able in which da
22b30 74 61 62 61 73 65 20 61 20 72 65 73 75 6c 74 20  tabase a result 
22b40 6f 66 20 61 20 53 45 4c 45 43 54 20 73 74 61 74  of a SELECT stat
22b50 65 6d 65 6e 74 20 63 6f 6d 65 73 20 66 72 6f 6d  ement comes from
22b60 2e 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66  ..** The name of
22b70 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 72   the database or
22b80 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e   table or column
22b90 20 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64   can be returned
22ba0 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20   as.** either a 
22bb0 55 54 46 38 20 6f 72 20 55 54 46 31 36 20 73 74  UTF8 or UTF16 st
22bc0 72 69 6e 67 2e 20 20 54 68 65 20 5f 64 61 74 61  ring.  The _data
22bd0 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 72  base_ routines r
22be0 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74  eturn.** the dat
22bf0 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 20  abase name, the 
22c00 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73  _table_ routines
22c10 20 72 65 74 75 72 6e 20 74 68 65 20 74 61 62 6c   return the tabl
22c20 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74  e name, and.** t
22c30 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69  he origin_ routi
22c40 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 63  nes return the c
22c50 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 54  olumn name..** T
22c60 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
22c70 6e 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69  ng is valid unti
22c80 6c 0a 2a 2a 20 74 68 65 20 5b 70 72 65 70 61 72  l.** the [prepar
22c90 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73  ed statement] is
22ca0 20 64 65 73 74 72 6f 79 65 64 20 75 73 69 6e 67   destroyed using
22cb0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  .** [sqlite3_fin
22cc0 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69  alize()] or unti
22cd0 6c 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72  l the same infor
22ce0 6d 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73  mation is reques
22cf0 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20  ted.** again in 
22d00 61 20 64 69 66 66 65 72 65 6e 74 20 65 6e 63 6f  a different enco
22d10 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ding..**.** The 
22d20 6e 61 6d 65 73 20 72 65 74 75 72 6e 65 64 20 61  names returned a
22d30 72 65 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  re the original 
22d40 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 73  un-aliased names
22d50 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 62   of the.** datab
22d60 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20  ase, table, and 
22d70 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  column..**.** Th
22d80 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
22d90 20 74 6f 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   to the followin
22da0 67 20 63 61 6c 6c 73 20 69 73 20 61 20 5b 70 72  g calls is a [pr
22db0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
22dc0 5d 2e 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63  ]..** These func
22dd0 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e 66  tions return inf
22de0 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74  ormation about t
22df0 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65  he Nth column re
22e00 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 74 68  turned by .** th
22e10 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 65  e statement, whe
22e20 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f  re N is the seco
22e30 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75  nd function argu
22e40 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  ment..**.** If t
22e50 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65  he Nth column re
22e60 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 73 74  turned by the st
22e70 61 74 65 6d 65 6e 74 20 69 73 20 61 6e 20 65 78  atement is an ex
22e80 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 6f 72 20 73  pression.** or s
22e90 75 62 71 75 65 72 79 20 61 6e 64 20 69 73 20 6e  ubquery and is n
22ea0 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75  ot a column valu
22eb0 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74  e, then all of t
22ec0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 0a 2a  hese functions.*
22ed0 2a 20 72 65 74 75 72 6e 20 4e 55 4c 4c 2e 20 20  * return NULL.  
22ee0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 20 6d 69  These routine mi
22ef0 67 68 74 20 61 6c 73 6f 20 72 65 74 75 72 6e 20  ght also return 
22f00 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79  NULL if a memory
22f10 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65  .** allocation e
22f20 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 4f 74  rror occurs.  Ot
22f30 68 65 72 77 69 73 65 2c 20 74 68 65 79 20 72 65  herwise, they re
22f40 74 75 72 6e 20 74 68 65 20 0a 2a 2a 20 6e 61 6d  turn the .** nam
22f50 65 20 6f 66 20 74 68 65 20 61 74 74 61 63 68 65  e of the attache
22f60 64 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c  d database, tabl
22f70 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 74 68 61  e and column tha
22f80 74 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a  t query result.*
22f90 2a 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74  * column was ext
22fa0 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a  racted from..**.
22fb0 2a 2a 20 41 73 20 77 69 74 68 20 61 6c 6c 20 6f  ** As with all o
22fc0 74 68 65 72 20 53 51 4c 69 74 65 20 41 50 49 73  ther SQLite APIs
22fd0 2c 20 74 68 6f 73 65 20 70 6f 73 74 66 69 78 65  , those postfixe
22fe0 64 20 77 69 74 68 20 22 31 36 22 20 72 65 74 75  d with "16" retu
22ff0 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63  rn.** UTF-16 enc
23000 6f 64 65 64 20 73 74 72 69 6e 67 73 2c 20 74 68  oded strings, th
23010 65 20 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e  e other function
23020 73 20 72 65 74 75 72 6e 20 55 54 46 2d 38 2e 20  s return UTF-8. 
23030 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  {END}.**.** Thes
23040 65 20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20  e APIs are only 
23050 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65  available if the
23060 20 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d   library was com
23070 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 20 0a  piled with the .
23080 2a 2a 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  ** SQLITE_ENABLE
23090 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41  _COLUMN_METADATA
230a0 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79   preprocessor sy
230b0 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a 2a 2a  mbol defined..**
230c0 0a 2a 2a 20 7b 55 31 33 37 35 31 7d 0a 2a 2a 20  .** {U13751}.** 
230d0 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74  If two or more t
230e0 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20  hreads call one 
230f0 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 73 65  or more of these
23100 20 72 6f 75 74 69 6e 65 73 20 61 67 61 69 6e 73   routines agains
23110 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72  t the same.** pr
23120 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
23130 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74   and column at t
23140 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65  he same time the
23150 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  n the results ar
23160 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a  e.** undefined..
23170 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
23180 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 34 31 7d  :.**.** {F13741}
23190 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
231a0 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61  lumn_database_na
231b0 6d 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61  me(S,N)] interfa
231c0 63 65 20 72 65 74 75 72 6e 73 20 65 69 74 68 65  ce returns eithe
231d0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  r.**          th
231e0 65 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72  e UTF-8 zero-ter
231f0 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66 20  minated name of 
23200 74 68 65 20 64 61 74 61 62 61 73 65 20 66 72 6f  the database fro
23210 6d 20 77 68 69 63 68 20 74 68 65 20 0a 2a 2a 20  m which the .** 
23220 20 20 20 20 20 20 20 20 20 4e 74 68 20 72 65 73           Nth res
23230 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 5b 70  ult column of [p
23240 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
23250 74 5d 20 53 20 0a 2a 2a 20 20 20 20 20 20 20 20  t] S .**        
23260 20 20 69 73 20 65 78 74 72 61 63 74 65 64 2c 20    is extracted, 
23270 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 4e  or NULL if the N
23280 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69  th column of S i
23290 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  s a.**          
232a0 67 65 6e 65 72 61 6c 20 65 78 70 72 65 73 73 69  general expressi
232b0 6f 6e 20 6f 72 20 69 66 20 75 6e 61 62 6c 65 20  on or if unable 
232c0 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f  to allocate memo
232d0 72 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  ry.**          t
232e0 6f 20 73 74 6f 72 65 20 74 68 65 20 6e 61 6d 65  o store the name
232f0 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 0a 2a  ..**          .*
23300 2a 20 7b 46 31 33 37 34 32 7d 20 54 68 65 20 5b  * {F13742} The [
23310 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
23320 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 53  atabase_name16(S
23330 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  ,N)] interface r
23340 65 74 75 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a  eturns either.**
23350 20 20 20 20 20 20 20 20 20 20 74 68 65 20 55 54            the UT
23360 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65  F-16 native byte
23370 20 6f 72 64 65 72 0a 2a 2a 20 20 20 20 20 20 20   order.**       
23380 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74     zero-terminat
23390 65 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  ed name of the d
233a0 61 74 61 62 61 73 65 20 66 72 6f 6d 20 77 68 69  atabase from whi
233b0 63 68 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 20  ch the .**      
233c0 20 20 20 20 4e 74 68 20 72 65 73 75 6c 74 20 63      Nth result c
233d0 6f 6c 75 6d 6e 20 6f 66 20 5b 70 72 65 70 61 72  olumn of [prepar
233e0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
233f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20  .**          is 
23400 65 78 74 72 61 63 74 65 64 2c 20 6f 72 20 4e 55  extracted, or NU
23410 4c 4c 20 69 66 20 74 68 65 20 4e 74 68 20 63 6f  LL if the Nth co
23420 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20 61 0a 2a  lumn of S is a.*
23430 2a 20 20 20 20 20 20 20 20 20 20 67 65 6e 65 72  *          gener
23440 61 6c 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72  al expression or
23450 20 69 66 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c   if unable to al
23460 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 0a 2a 2a  locate memory.**
23470 20 20 20 20 20 20 20 20 20 20 74 6f 20 73 74 6f            to sto
23480 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 20  re the name..** 
23490 20 20 20 20 20 20 20 20 20 0a 2a 2a 20 7b 46 31           .** {F1
234a0 33 37 34 33 7d 20 54 68 65 20 5b 73 71 6c 69 74  3743} The [sqlit
234b0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f  e3_column_table_
234c0 6e 61 6d 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72  name(S,N)] inter
234d0 66 61 63 65 20 72 65 74 75 72 6e 73 20 65 69 74  face returns eit
234e0 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  her.**          
234f0 74 68 65 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74  the UTF-8 zero-t
23500 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f  erminated name o
23510 66 20 74 68 65 20 74 61 62 6c 65 20 66 72 6f 6d  f the table from
23520 20 77 68 69 63 68 20 74 68 65 20 0a 2a 2a 20 20   which the .**  
23530 20 20 20 20 20 20 20 20 4e 74 68 20 72 65 73 75          Nth resu
23540 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 5b 70 72  lt column of [pr
23550 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
23560 5d 20 53 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  ] S .**         
23570 20 69 73 20 65 78 74 72 61 63 74 65 64 2c 20 6f   is extracted, o
23580 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 4e 74  r NULL if the Nt
23590 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73  h column of S is
235a0 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 67   a.**          g
235b0 65 6e 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f  eneral expressio
235c0 6e 20 6f 72 20 69 66 20 75 6e 61 62 6c 65 20 74  n or if unable t
235d0 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72  o allocate memor
235e0 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f  y.**          to
235f0 20 73 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e   store the name.
23600 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 0a 2a 2a  .**          .**
23610 20 7b 46 31 33 37 34 34 7d 20 54 68 65 20 5b 73   {F13744} The [s
23620 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61  qlite3_column_ta
23630 62 6c 65 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d  ble_name16(S,N)]
23640 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
23650 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20  ns either.**    
23660 20 20 20 20 20 20 74 68 65 20 55 54 46 2d 31 36        the UTF-16
23670 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
23680 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a  er.**          z
23690 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e  ero-terminated n
236a0 61 6d 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65  ame of the table
236b0 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20   from which the 
236c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68  .**          Nth
236d0 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f   result column o
236e0 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  f [prepared stat
236f0 65 6d 65 6e 74 5d 20 53 20 0a 2a 2a 20 20 20 20  ement] S .**    
23700 20 20 20 20 20 20 69 73 20 65 78 74 72 61 63 74        is extract
23710 65 64 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74  ed, or NULL if t
23720 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66  he Nth column of
23730 20 53 20 69 73 20 61 0a 2a 2a 20 20 20 20 20 20   S is a.**      
23740 20 20 20 20 67 65 6e 65 72 61 6c 20 65 78 70 72      general expr
23750 65 73 73 69 6f 6e 20 6f 72 20 69 66 20 75 6e 61  ession or if una
23760 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ble to allocate 
23770 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20 20 20 20 20  memory.**       
23780 20 20 20 74 6f 20 73 74 6f 72 65 20 74 68 65 20     to store the 
23790 6e 61 6d 65 2e 0a 2a 2a 20 20 20 20 20 20 20 20  name..**        
237a0 20 20 0a 2a 2a 20 7b 46 31 33 37 34 35 7d 20 54    .** {F13745} T
237b0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
237c0 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 53  mn_origin_name(S
237d0 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  ,N)] interface r
237e0 65 74 75 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a  eturns either.**
237f0 20 20 20 20 20 20 20 20 20 20 74 68 65 20 55 54            the UT
23800 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  F-8 zero-termina
23810 74 65 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  ted name of the 
23820 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 66 72 6f  table column fro
23830 6d 20 77 68 69 63 68 20 74 68 65 20 0a 2a 2a 20  m which the .** 
23840 20 20 20 20 20 20 20 20 20 4e 74 68 20 72 65 73           Nth res
23850 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 5b 70  ult column of [p
23860 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
23870 74 5d 20 53 20 0a 2a 2a 20 20 20 20 20 20 20 20  t] S .**        
23880 20 20 69 73 20 65 78 74 72 61 63 74 65 64 2c 20    is extracted, 
23890 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 4e  or NULL if the N
238a0 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69  th column of S i
238b0 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  s a.**          
238c0 67 65 6e 65 72 61 6c 20 65 78 70 72 65 73 73 69  general expressi
238d0 6f 6e 20 6f 72 20 69 66 20 75 6e 61 62 6c 65 20  on or if unable 
238e0 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f  to allocate memo
238f0 72 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  ry.**          t
23900 6f 20 73 74 6f 72 65 20 74 68 65 20 6e 61 6d 65  o store the name
23910 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 0a 2a  ..**          .*
23920 2a 20 7b 46 31 33 37 34 36 7d 20 54 68 65 20 5b  * {F13746} The [
23930 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f  sqlite3_column_o
23940 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e  rigin_name16(S,N
23950 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
23960 75 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 20  urns either.**  
23970 20 20 20 20 20 20 20 20 74 68 65 20 55 54 46 2d          the UTF-
23980 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  16 native byte o
23990 72 64 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  rder.**         
239a0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
239b0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 74 61 62   name of the tab
239c0 6c 65 20 63 6f 6c 75 6d 6e 20 66 72 6f 6d 20 77  le column from w
239d0 68 69 63 68 20 74 68 65 20 0a 2a 2a 20 20 20 20  hich the .**    
239e0 20 20 20 20 20 20 4e 74 68 20 72 65 73 75 6c 74        Nth result
239f0 20 63 6f 6c 75 6d 6e 20 6f 66 20 5b 70 72 65 70   column of [prep
23a00 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
23a10 53 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  S .**          i
23a20 73 20 65 78 74 72 61 63 74 65 64 2c 20 6f 72 20  s extracted, or 
23a30 4e 55 4c 4c 20 69 66 20 74 68 65 20 4e 74 68 20  NULL if the Nth 
23a40 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20 61  column of S is a
23a50 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 67 65 6e  .**          gen
23a60 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e 20  eral expression 
23a70 6f 72 20 69 66 20 75 6e 61 62 6c 65 20 74 6f 20  or if unable to 
23a80 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 0a  allocate memory.
23a90 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 73  **          to s
23aa0 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a  tore the name..*
23ab0 2a 20 20 20 20 20 20 20 20 20 20 0a 2a 2a 20 7b  *          .** {
23ac0 46 31 33 37 34 38 7d 20 54 68 65 20 72 65 74 75  F13748} The retu
23ad0 72 6e 20 76 61 6c 75 65 73 20 66 72 6f 6d 0a 2a  rn values from.*
23ae0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
23af0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62  te3_column_datab
23b00 61 73 65 5f 6e 61 6d 65 7c 63 6f 6c 75 6d 6e 20  ase_name|column 
23b10 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72 66 61  metadata interfa
23b20 63 65 73 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ces].**         
23b30 20 61 72 65 20 76 61 6c 69 64 0a 2a 2a 20 20 20   are valid.**   
23b40 20 20 20 20 20 20 20 66 6f 72 20 74 68 65 20 6c         for the l
23b50 69 66 65 74 69 6d 65 20 6f 66 20 74 68 65 20 5b  ifetime of the [
23b60 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
23b70 6e 74 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  nt].**          
23b80 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 65 6e 63  or until the enc
23b90 6f 64 69 6e 67 20 69 73 20 63 68 61 6e 67 65 64  oding is changed
23ba0 20 62 79 20 61 6e 6f 74 68 65 72 20 6d 65 74 61   by another meta
23bb0 64 61 74 61 0a 2a 2a 20 20 20 20 20 20 20 20 20  data.**         
23bc0 20 69 6e 74 65 72 66 61 63 65 20 63 61 6c 6c 20   interface call 
23bd0 66 6f 72 20 74 68 65 20 73 61 6d 65 20 70 72 65  for the same pre
23be0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
23bf0 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a  and column..**.*
23c00 2a 20 4c 49 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a  * LIMITATIONS:.*
23c10 2a 0a 2a 2a 20 7b 55 31 33 37 35 31 7d 20 49 66  *.** {U13751} If
23c20 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72   two or more thr
23c30 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72  eads call one or
23c40 20 6d 6f 72 65 0a 2a 2a 20 20 20 20 20 20 20 20   more.**        
23c50 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d    [sqlite3_colum
23c60 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 7c  n_database_name|
23c70 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20  column metadata 
23c80 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 20  interfaces].**  
23c90 20 20 20 20 20 20 20 20 74 68 65 20 73 61 6d 65          the same
23ca0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
23cb0 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c 74  ment] and result
23cc0 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 20 20 20 20 20   column.**      
23cd0 20 20 20 20 61 74 20 74 68 65 20 73 61 6d 65 20      at the same 
23ce0 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65  time then the re
23cf0 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
23d00 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  ned..*/.const ch
23d10 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
23d20 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
23d30 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
23d40 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  nt);.const void 
23d50 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
23d60 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28  database_name16(
23d70 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
23d80 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  t);.const char *
23d90 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
23da0 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65  able_name(sqlite
23db0 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
23dc0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
23dd0 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e  3_column_table_n
23de0 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
23df0 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
23e00 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
23e10 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65  lumn_origin_name
23e20 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
23e30 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  nt);.const void 
23e40 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
23e50 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71  origin_name16(sq
23e60 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
23e70 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
23e80 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61 74 61  F: Declared Data
23e90 74 79 70 65 20 4f 66 20 41 20 51 75 65 72 79 20  type Of A Query 
23ea0 52 65 73 75 6c 74 20 7b 46 31 33 37 36 30 7d 0a  Result {F13760}.
23eb0 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
23ec0 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 5b  parameter is a [
23ed0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
23ee0 6e 74 5d 2e 20 0a 2a 2a 20 49 66 20 74 68 69 73  nt]. .** If this
23ef0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20   statement is a 
23f00 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74  SELECT statement
23f10 20 61 6e 64 20 74 68 65 20 4e 74 68 20 63 6f 6c   and the Nth col
23f20 75 6d 6e 20 6f 66 20 74 68 65 20 0a 2a 2a 20 72  umn of the .** r
23f30 65 74 75 72 6e 65 64 20 72 65 73 75 6c 74 20 73  eturned result s
23f40 65 74 20 6f 66 20 74 68 61 74 20 53 45 4c 45 43  et of that SELEC
23f50 54 20 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c  T is a table col
23f60 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65  umn (not an.** e
23f70 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62  xpression or sub
23f80 71 75 65 72 79 29 20 74 68 65 6e 20 74 68 65 20  query) then the 
23f90 64 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66  declared type of
23fa0 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f   the table.** co
23fb0 6c 75 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64  lumn is returned
23fc0 2e 20 20 49 66 20 74 68 65 20 4e 74 68 20 63 6f  .  If the Nth co
23fd0 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75  lumn of the resu
23fe0 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20  lt set is an.** 
23ff0 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75  expression or su
24000 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e  bquery, then a N
24010 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72  ULL pointer is r
24020 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 54 68 65 20  eturned..** The 
24030 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
24040 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20  is always UTF-8 
24050 65 6e 63 6f 64 65 64 2e 20 20 7b 45 4e 44 7d 20  encoded.  {END} 
24060 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  .** For example,
24070 20 69 6e 20 74 68 65 20 64 61 74 61 62 61 73 65   in the database
24080 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43   schema:.**.** C
24090 52 45 41 54 45 20 54 41 42 4c 45 20 74 31 28 63  REATE TABLE t1(c
240a0 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a  1 VARIANT);.**.*
240b0 2a 20 41 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77  * And the follow
240c0 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63 6f  ing statement co
240d0 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45  mpiled:.**.** SE
240e0 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 63 31 20  LECT c1 + 1, c1 
240f0 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 54  FROM t1;.**.** T
24100 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65  hen this routine
24110 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68   would return th
24120 65 20 73 74 72 69 6e 67 20 22 56 41 52 49 41 4e  e string "VARIAN
24130 54 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e  T" for the secon
24140 64 0a 2a 2a 20 72 65 73 75 6c 74 20 63 6f 6c 75  d.** result colu
24150 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61  mn (i==1), and a
24160 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f   NULL pointer fo
24170 72 20 74 68 65 20 66 69 72 73 74 20 72 65 73 75  r the first resu
24180 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 28 69 3d  lt column.** (i=
24190 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  =0)..**.** SQLit
241a0 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 72  e uses dynamic r
241b0 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e 20  un-time typing. 
241c0 20 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73 65   So just because
241d0 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20   a column.** is 
241e0 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74  declared to cont
241f0 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72  ain a particular
24200 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d   type does not m
24210 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  ean that the.** 
24220 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20 74  data stored in t
24230 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66  hat column is of
24240 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79   the declared ty
24250 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a 2a  pe.  SQLite is.*
24260 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65 64  * strongly typed
24270 2c 20 62 75 74 20 74 68 65 20 74 79 70 69 6e 67  , but the typing
24280 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20   is dynamic not 
24290 73 74 61 74 69 63 2e 20 20 54 79 70 65 0a 2a 2a  static.  Type.**
242a0 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20 77   is associated w
242b0 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c 20 76  ith individual v
242c0 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 68 20  alues, not with 
242d0 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a  the containers.*
242e0 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 74  * used to hold t
242f0 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2a 0a  hose values..**.
24300 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
24310 2a 0a 2a 2a 20 7b 46 31 33 37 36 31 7d 20 20 41  *.** {F13761}  A
24320 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c   successful call
24330 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   to [sqlite3_col
24340 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 53 2c 4e  umn_decltype(S,N
24350 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  )].**           
24360 72 65 74 75 72 6e 73 20 61 20 7a 65 72 6f 2d 74  returns a zero-t
24370 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20  erminated UTF-8 
24380 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e  string containin
24390 67 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  g the.**        
243a0 20 20 20 74 68 65 20 64 65 63 6c 61 72 65 64 20     the declared 
243b0 64 61 74 61 74 79 70 65 20 6f 66 20 74 68 65 20  datatype of the 
243c0 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61  table column tha
243d0 74 20 61 70 70 65 61 72 73 0a 2a 2a 20 20 20 20  t appears.**    
243e0 20 20 20 20 20 20 20 61 73 20 74 68 65 20 4e 74         as the Nt
243f0 68 20 63 6f 6c 75 6d 6e 20 28 6e 75 6d 62 65 72  h column (number
24400 65 64 20 66 72 6f 6d 20 30 29 20 6f 66 20 74 68  ed from 0) of th
24410 65 20 72 65 73 75 6c 74 20 73 65 74 20 74 6f 20  e result set to 
24420 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
24430 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
24440 6d 65 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b  ment] S..**.** {
24450 46 31 33 37 36 32 7d 20 20 41 20 73 75 63 63 65  F13762}  A succe
24460 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73  ssful call to [s
24470 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65  qlite3_column_de
24480 63 6c 74 79 70 65 31 36 28 53 2c 4e 29 5d 0a 2a  cltype16(S,N)].*
24490 2a 20 20 20 20 20 20 20 20 20 20 20 72 65 74 75  *           retu
244a0 72 6e 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69  rns a zero-termi
244b0 6e 61 74 65 64 20 55 54 46 2d 31 36 20 6e 61 74  nated UTF-16 nat
244c0 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 73  ive byte order s
244d0 74 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20  tring.**        
244e0 20 20 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68     containing th
244f0 65 20 64 65 63 6c 61 72 65 64 20 64 61 74 61 74  e declared datat
24500 79 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65  ype of the table
24510 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 61 70 70   column that app
24520 65 61 72 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  ears.**         
24530 20 20 61 73 20 74 68 65 20 4e 74 68 20 63 6f 6c    as the Nth col
24540 75 6d 6e 20 28 6e 75 6d 62 65 72 65 64 20 66 72  umn (numbered fr
24550 6f 6d 20 30 29 20 6f 66 20 74 68 65 20 72 65 73  om 0) of the res
24560 75 6c 74 20 73 65 74 20 74 6f 20 74 68 65 0a 2a  ult set to the.*
24570 2a 20 20 20 20 20 20 20 20 20 20 20 5b 70 72 65  *           [pre
24580 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
24590 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 36   S..**.** {F1376
245a0 33 7d 20 20 49 66 20 4e 20 69 73 20 6c 65 73 73  3}  If N is less
245b0 20 74 68 61 6e 20 30 20 6f 72 20 4e 20 69 73 20   than 0 or N is 
245c0 67 72 65 61 74 65 72 20 74 68 61 6e 20 6f 72 20  greater than or 
245d0 65 71 75 61 6c 20 74 6f 0a 2a 2a 20 20 20 20 20  equal to.**     
245e0 20 20 20 20 20 20 74 68 65 20 6e 75 6d 62 65 72        the number
245f0 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 5b   of columns in [
24600 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
24610 6e 74 5d 20 53 0a 2a 2a 20 20 20 20 20 20 20 20  nt] S.**        
24620 20 20 20 6f 72 20 69 66 20 74 68 65 20 4e 74 68     or if the Nth
24630 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20   column of S is 
24640 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72  an expression or
24650 20 73 75 62 71 75 65 72 79 20 72 61 74 68 65 72   subquery rather
24660 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 68  .**           th
24670 61 6e 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d  an a table colum
24680 6e 20 6f 72 20 69 66 20 61 20 6d 65 6d 6f 72 79  n or if a memory
24690 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c   allocation fail
246a0 75 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ure.**          
246b0 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 65   occurs during e
246c0 6e 63 6f 64 69 6e 67 20 63 6f 6e 76 65 72 73 69  ncoding conversi
246d0 6f 6e 73 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20  ons, then.**    
246e0 20 20 20 20 20 20 20 63 61 6c 6c 73 20 74 6f 20         calls to 
246f0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
24700 64 65 63 6c 74 79 70 65 28 53 2c 4e 29 5d 20 6f  decltype(S,N)] o
24710 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b  r.**           [
24720 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
24730 65 63 6c 74 79 70 65 31 36 28 53 2c 4e 29 5d 20  ecltype16(S,N)] 
24740 72 65 74 75 72 6e 20 4e 55 4c 4c 2e 0a 2a 2f 0a  return NULL..*/.
24750 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
24760 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74  te3_column_declt
24770 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ype(sqlite3_stmt
24780 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f  *,int);.const vo
24790 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
247a0 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 73 71  mn_decltype16(sq
247b0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
247c0 3b 0a 0a 2f 2a 20 0a 2a 2a 20 43 41 50 49 33 52  ;../* .** CAPI3R
247d0 45 46 3a 20 20 45 76 61 6c 75 61 74 65 20 41 6e  EF:  Evaluate An
247e0 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 7b   SQL Statement {
247f0 46 31 33 32 30 30 7d 0a 2a 2a 0a 2a 2a 20 41 66  F13200}.**.** Af
24800 74 65 72 20 61 6e 20 5b 70 72 65 70 61 72 65 64  ter an [prepared
24810 20 73 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 20   statement] has 
24820 62 65 65 6e 20 70 72 65 70 61 72 65 64 20 77 69  been prepared wi
24830 74 68 20 61 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20  th a call.** to 
24840 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f  either [sqlite3_
24850 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
24860 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
24870 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 6f 20  e16_v2()] or to 
24880 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 65  one of.** the le
24890 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 73 20  gacy interfaces 
248a0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
248b0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
248c0 70 72 65 70 61 72 65 31 36 28 29 5d 2c 0a 2a 2a  prepare16()],.**
248d0 20 74 68 65 6e 20 74 68 69 73 20 66 75 6e 63 74   then this funct
248e0 69 6f 6e 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  ion must be call
248f0 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74  ed one or more t
24900 69 6d 65 73 20 74 6f 20 65 76 61 6c 75 61 74 65  imes to evaluate
24910 20 74 68 65 20 0a 2a 2a 20 73 74 61 74 65 6d 65   the .** stateme
24920 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65  nt..**.** The de
24930 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65 68  tails of the beh
24940 61 76 69 6f 72 20 6f 66 20 74 68 69 73 20 73 71  avior of this sq
24950 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 74  lite3_step() int
24960 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a  erface depend.**
24970 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65 20   on whether the 
24980 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70 72  statement was pr
24990 65 70 61 72 65 64 20 75 73 69 6e 67 20 74 68 65  epared using the
249a0 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e 74 65   newer "v2" inte
249b0 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  rface.** [sqlite
249c0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
249d0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  and [sqlite3_pre
249e0 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20  pare16_v2()] or 
249f0 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 63 79  the older legacy
24a00 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 5b 73  .** interface [s
24a10 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
24a20 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
24a30 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20 54 68  repare16()].  Th
24a40 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20  e use of the.** 
24a50 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72 66 61  new "v2" interfa
24a60 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  ce is recommende
24a70 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c 69 63  d for new applic
24a80 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65 20 6c  ations but the l
24a90 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61  egacy.** interfa
24aa0 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65  ce will continue
24ab0 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64   to be supported
24ac0 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 6c  ..**.** In the l
24ad0 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c  egacy interface,
24ae0 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
24af0 65 20 77 69 6c 6c 20 62 65 20 65 69 74 68 65 72  e will be either
24b00 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 20   [SQLITE_BUSY], 
24b10 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45  .** [SQLITE_DONE
24b20 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c  ], [SQLITE_ROW],
24b30 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c   [SQLITE_ERROR],
24b40 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55   or [SQLITE_MISU
24b50 53 45 5d 2e 0a 2a 2a 20 57 69 74 68 20 74 68 65  SE]..** With the
24b60 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c   "v2" interface,
24b70 20 61 6e 79 20 6f 66 20 74 68 65 20 6f 74 68 65   any of the othe
24b80 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 72  r [SQLITE_OK | r
24b90 65 73 75 6c 74 20 63 6f 64 65 5d 0a 2a 2a 20 6f  esult code].** o
24ba0 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  r [SQLITE_IOERR_
24bb0 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64 20  READ | extended 
24bc0 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6d 69 67  result code] mig
24bd0 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 61  ht be returned a
24be0 73 0a 2a 2a 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a  s.** well..**.**
24bf0 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d   [SQLITE_BUSY] m
24c00 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 64 61  eans that the da
24c10 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20 77 61  tabase engine wa
24c20 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 63 71 75  s unable to acqu
24c30 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  ire the.** datab
24c40 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65  ase locks it nee
24c50 64 73 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62  ds to do its job
24c60 2e 20 20 49 66 20 74 68 65 20 73 74 61 74 65 6d  .  If the statem
24c70 65 6e 74 20 69 73 20 61 20 43 4f 4d 4d 49 54 0a  ent is a COMMIT.
24c80 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f 75 74  ** or occurs out
24c90 73 69 64 65 20 6f 66 20 61 6e 20 65 78 70 6c 69  side of an expli
24ca0 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c  cit transaction,
24cb0 20 74 68 65 6e 20 79 6f 75 20 63 61 6e 20 72 65   then you can re
24cc0 74 72 79 20 74 68 65 0a 2a 2a 20 73 74 61 74 65  try the.** state
24cd0 6d 65 6e 74 2e 20 20 49 66 20 74 68 65 20 73 74  ment.  If the st
24ce0 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61  atement is not a
24cf0 20 43 4f 4d 4d 49 54 20 61 6e 64 20 6f 63 63 75   COMMIT and occu
24d00 72 73 20 77 69 74 68 69 6e 20 61 0a 2a 2a 20 65  rs within a.** e
24d10 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74  xplicit transact
24d20 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73 68 6f  ion then you sho
24d30 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65  uld rollback the
24d40 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 66   transaction bef
24d50 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e  ore.** continuin
24d60 67 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45  g..**.** [SQLITE
24d70 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61  _DONE] means tha
24d80 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  t the statement 
24d90 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65  has finished exe
24da0 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73  cuting.** succes
24db0 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33  sfully.  sqlite3
24dc0 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e  _step() should n
24dd0 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61  ot be called aga
24de0 69 6e 20 6f 6e 20 74 68 69 73 20 76 69 72 74 75  in on this virtu
24df0 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69  al.** machine wi
24e00 74 68 6f 75 74 20 66 69 72 73 74 20 63 61 6c 6c  thout first call
24e10 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ing [sqlite3_res
24e20 65 74 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74  et()] to reset t
24e30 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61  he virtual.** ma
24e40 63 68 69 6e 65 20 62 61 63 6b 20 74 6f 20 69 74  chine back to it
24e50 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2e  s initial state.
24e60 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51  .**.** If the SQ
24e70 4c 20 73 74 61 74 65 6d 65 6e 74 20 62 65 69 6e  L statement bein
24e80 67 20 65 78 65 63 75 74 65 64 20 72 65 74 75 72  g executed retur
24e90 6e 73 20 61 6e 79 20 64 61 74 61 2c 20 74 68 65  ns any data, the
24ea0 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 52 4f  n .** [SQLITE_RO
24eb0 57 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 65  W] is returned e
24ec0 61 63 68 20 74 69 6d 65 20 61 20 6e 65 77 20 72  ach time a new r
24ed0 6f 77 20 6f 66 20 64 61 74 61 20 69 73 20 72 65  ow of data is re
24ee0 61 64 79 0a 2a 2a 20 66 6f 72 20 70 72 6f 63 65  ady.** for proce
24ef0 73 73 69 6e 67 20 62 79 20 74 68 65 20 63 61 6c  ssing by the cal
24f00 6c 65 72 2e 20 54 68 65 20 76 61 6c 75 65 73 20  ler. The values 
24f10 6d 61 79 20 62 65 20 61 63 63 65 73 73 65 64 20  may be accessed 
24f20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71  using.** the [sq
24f30 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74  lite3_column_int
24f40 20 7c 20 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73   | column access
24f50 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20   functions]..** 
24f60 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69  sqlite3_step() i
24f70 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 74  s called again t
24f80 6f 20 72 65 74 72 69 65 76 65 20 74 68 65 20 6e  o retrieve the n
24f90 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61 2e  ext row of data.
24fa0 0a 2a 2a 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  .** .** [SQLITE_
24fb0 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61  ERROR] means tha
24fc0 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72  t a run-time err
24fd0 6f 72 20 28 73 75 63 68 20 61 73 20 61 20 63 6f  or (such as a co
24fe0 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c  nstraint.** viol
24ff0 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 72  ation) has occur
25000 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 74  red.  sqlite3_st
25010 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20  ep() should not 
25020 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20  be called again 
25030 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f  on.** the VM. Mo
25040 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d  re information m
25050 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20 63  ay be found by c
25060 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
25070 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 57 69  errmsg()]..** Wi
25080 74 68 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e  th the legacy in
25090 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 20  terface, a more 
250a0 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63  specific error c
250b0 6f 64 65 20 28 65 78 61 6d 70 6c 65 3a 0a 2a 2a  ode (example:.**
250c0 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55   [SQLITE_INTERRU
250d0 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48  PT], [SQLITE_SCH
250e0 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f  EMA], [SQLITE_CO
250f0 52 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66  RRUPT], and so f
25100 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20  orth).** can be 
25110 6f 62 74 61 69 6e 65 64 20 62 79 20 63 61 6c 6c  obtained by call
25120 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ing [sqlite3_res
25130 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20  et()] on the.** 
25140 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
25150 65 6e 74 5d 2e 20 20 49 6e 20 74 68 65 20 22 76  ent].  In the "v
25160 32 22 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a  2" interface,.**
25170 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66   the more specif
25180 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73  ic error code is
25190 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74   returned direct
251a0 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74  ly by sqlite3_st
251b0 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c  ep()..**.** [SQL
251c0 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e  ITE_MISUSE] mean
251d0 73 20 74 68 61 74 20 74 68 65 20 74 68 69 73 20  s that the this 
251e0 72 6f 75 74 69 6e 65 20 77 61 73 20 63 61 6c 6c  routine was call
251f0 65 64 20 69 6e 61 70 70 72 6f 70 72 69 61 74 65  ed inappropriate
25200 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20 69  ly..** Perhaps i
25210 74 20 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20  t was called on 
25220 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
25230 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 0a  ement] that has.
25240 2a 2a 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20  ** already been 
25250 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
25260 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f  e | finalized] o
25270 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68 61  r on one that ha
25280 64 20 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79  d .** previously
25290 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54   returned [SQLIT
252a0 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c  E_ERROR] or [SQL
252b0 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69  ITE_DONE].  Or i
252c0 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68  t could.** be th
252d0 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65 20  e case that the 
252e0 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
252f0 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62 65 69 6e  nnection is bein
25300 67 20 75 73 65 64 20 62 79 20 74 77 6f 20 6f 72  g used by two or
25310 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61 64 73  .** more threads
25320 20 61 74 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d   at the same mom
25330 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a  ent in time..**.
25340 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65  ** <b>Goofy Inte
25350 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e  rface Alert:</b>
25360 0a 2a 2a 20 49 6e 20 74 68 65 20 6c 65 67 61 63  .** In the legac
25370 79 20 69 6e 74 65 72 66 61 63 65 2c 20 0a 2a 2a  y interface, .**
25380 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65   the sqlite3_ste
25390 70 28 29 20 41 50 49 20 61 6c 77 61 79 73 20 72  p() API always r
253a0 65 74 75 72 6e 73 20 61 20 67 65 6e 65 72 69 63  eturns a generic
253b0 20 65 72 72 6f 72 20 63 6f 64 65 2c 0a 2a 2a 20   error code,.** 
253c0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20  [SQLITE_ERROR], 
253d0 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 65 72  following any er
253e0 72 6f 72 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  ror other than [
253f0 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20  SQLITE_BUSY].** 
25400 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  and [SQLITE_MISU
25410 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20 63  SE].  You must c
25420 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  all [sqlite3_res
25430 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  et()] or.** [sql
25440 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
25450 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e   in order to fin
25460 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 73 70 65  d one of the spe
25470 63 69 66 69 63 0a 2a 2a 20 5b 65 72 72 6f 72 20  cific.** [error 
25480 63 6f 64 65 73 5d 20 74 68 61 74 20 62 65 74 74  codes] that bett
25490 65 72 20 64 65 73 63 72 69 62 65 73 20 74 68 65  er describes the
254a0 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64   error..** We ad
254b0 6d 69 74 20 74 68 61 74 20 74 68 69 73 20 69 73  mit that this is
254c0 20 61 20 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e   a goofy design.
254d0 20 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 68 61    The problem ha
254e0 73 20 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20  s been fixed.** 
254f0 77 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e  with the "v2" in
25500 74 65 72 66 61 63 65 2e 20 20 49 66 20 79 6f 75  terface.  If you
25510 20 70 72 65 70 61 72 65 20 61 6c 6c 20 6f 66 20   prepare all of 
25520 79 6f 75 72 20 53 51 4c 20 73 74 61 74 65 6d 65  your SQL stateme
25530 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74  nts.** using eit
25540 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  her [sqlite3_pre
25550 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73  pare_v2()] or [s
25560 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
25570 5f 76 32 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a  _v2()] instead.*
25580 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 20  * of the legacy 
25590 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
255a0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
255b0 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74  _prepare16()], t
255c0 68 65 6e 20 74 68 65 20 0a 2a 2a 20 6d 6f 72 65  hen the .** more
255d0 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72   specific [error
255e0 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75   codes] are retu
255f0 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a  rned directly.**
25600 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70   by sqlite3_step
25610 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20  ().  The use of 
25620 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
25630 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  ce is recommende
25640 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  d..**.** INVARIA
25650 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 32  NTS:.**.** {F132
25660 30 32 7d 20 20 49 66 20 5b 70 72 65 70 61 72 65  02}  If [prepare
25670 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69  d statement] S i
25680 73 20 72 65 61 64 79 20 74 6f 20 62 65 0a 2a 2a  s ready to be.**
25690 20 20 20 20 20 20 20 20 20 20 20 72 75 6e 2c 20             run, 
256a0 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74  then [sqlite3_st
256b0 65 70 28 53 29 5d 20 61 64 76 61 6e 63 65 73 20  ep(S)] advances 
256c0 74 68 61 74 20 70 72 65 70 61 72 65 64 20 73 74  that prepared st
256d0 61 74 65 6d 65 6e 74 0a 2a 2a 20 20 20 20 20 20  atement.**      
256e0 20 20 20 20 20 75 6e 74 69 6c 20 74 6f 20 63 6f       until to co
256f0 6d 70 6c 65 74 69 6f 6e 20 6f 72 20 75 6e 74 69  mpletion or unti
25700 6c 20 69 74 20 69 73 20 72 65 61 64 79 20 74 6f  l it is ready to
25710 20 72 65 74 75 72 6e 20 61 6e 6f 74 68 65 72 0a   return another.
25720 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72 6f 77  **           row
25730 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
25740 65 74 20 6f 72 20 61 6e 20 69 6e 74 65 72 72 75  et or an interru
25750 70 74 20 6f 72 20 72 75 6e 2d 74 69 6d 65 20 65  pt or run-time e
25760 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a  rror occurs..**.
25770 2a 2a 20 7b 46 31 35 33 30 34 7d 20 20 57 68 65  ** {F15304}  Whe
25780 6e 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  n a call to [sql
25790 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 63 61  ite3_step(S)] ca
257a0 75 73 65 73 20 74 68 65 20 0a 2a 2a 20 20 20 20  uses the .**    
257b0 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64         [prepared
257c0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 74 6f   statement] S to
257d0 20 72 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 69   run to completi
257e0 6f 6e 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  on,.**          
257f0 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 72 65   the function re
25800 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 4f  turns [SQLITE_DO
25810 4e 45 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 33  NE]..**.** {F153
25820 30 36 7d 20 20 57 68 65 6e 20 61 20 63 61 6c 6c  06}  When a call
25830 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
25840 70 28 53 29 5d 20 73 74 6f 70 73 20 62 65 63 61  p(S)] stops beca
25850 75 73 65 20 69 74 20 69 73 20 72 65 61 64 79 0a  use it is ready.
25860 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 6f 20  **           to 
25870 72 65 74 75 72 6e 20 61 6e 6f 74 68 65 72 20 72  return another r
25880 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ow of the result
25890 20 73 65 74 2c 20 69 74 20 72 65 74 75 72 6e 73   set, it returns
258a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 53  .**           [S
258b0 51 4c 49 54 45 5f 52 4f 57 5d 2e 0a 2a 2a 0a 2a  QLITE_ROW]..**.*
258c0 2a 20 7b 46 31 35 33 30 38 7d 20 20 49 66 20 61  * {F15308}  If a
258d0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
258e0 33 5f 73 74 65 70 28 53 29 5d 20 65 6e 63 6f 75  3_step(S)] encou
258f0 6e 74 65 72 73 20 61 6e 0a 2a 2a 20 20 20 20 20  nters an.**     
25900 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 69        [sqlite3_i
25910 6e 74 65 72 72 75 70 74 7c 69 6e 74 65 72 72 75  nterrupt|interru
25920 70 74 5d 20 6f 72 20 61 20 72 75 6e 2d 74 69 6d  pt] or a run-tim
25930 65 20 65 72 72 6f 72 2c 0a 2a 2a 20 20 20 20 20  e error,.**     
25940 20 20 20 20 20 20 69 74 20 72 65 74 75 72 6e 73        it returns
25950 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20   an appropriate 
25960 65 72 72 6f 72 20 63 6f 64 65 20 74 68 61 74 20  error code that 
25970 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 0a 2a 2a  is not one of.**
25980 20 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49             [SQLI
25990 54 45 5f 4f 4b 5d 2c 20 5b 53 51 4c 49 54 45 5f  TE_OK], [SQLITE_
259a0 52 4f 57 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  ROW], or [SQLITE
259b0 5f 44 4f 4e 45 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46  _DONE]..**.** {F
259c0 31 35 33 31 30 7d 20 20 49 66 20 61 6e 20 5b 73  15310}  If an [s
259d0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
259e0 7c 69 6e 74 65 72 72 75 70 74 5d 20 6f 72 20 72  |interrupt] or r
259f0 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 0a 2a 2a  un-time error.**
25a00 20 20 20 20 20 20 20 20 20 20 20 6f 63 63 75 72             occur
25a10 73 20 64 75 72 69 6e 67 20 61 20 63 61 6c 6c 20  s during a call 
25a20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
25a30 28 53 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  (S)].**         
25a40 20 20 66 6f 72 20 61 20 5b 70 72 65 70 61 72 65    for a [prepare
25a50 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 63  d statement] S c
25a60 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20  reated using.** 
25a70 20 20 20 20 20 20 20 20 20 20 6c 65 67 61 63 79            legacy
25a80 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c   interfaces [sql
25a90 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
25aa0 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  or.**           
25ab0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
25ac0 31 36 28 29 5d 20 74 68 65 6e 20 74 68 65 20 66  16()] then the f
25ad0 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
25ae0 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20  either.**       
25af0 20 20 20 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f      [SQLITE_ERRO
25b00 52 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  R], [SQLITE_BUSY
25b10 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49  ], or [SQLITE_MI
25b20 53 55 53 45 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  SUSE]..*/.int sq
25b30 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69 74  lite3_step(sqlit
25b40 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
25b50 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62  * CAPI3REF: Numb
25b60 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
25b70 20 61 20 72 65 73 75 6c 74 20 73 65 74 20 7b 46   a result set {F
25b80 31 33 37 37 30 7d 0a 2a 2a 0a 2a 2a 20 52 65 74  13770}.**.** Ret
25b90 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  urn the number o
25ba0 66 20 76 61 6c 75 65 73 20 69 6e 20 74 68 65 20  f values in the 
25bb0 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74  current row of t
25bc0 68 65 20 72 65 73 75 6c 74 20 73 65 74 2e 0a 2a  he result set..*
25bd0 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
25be0 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 37 31 7d 20  .**.** {F13771} 
25bf0 20 41 66 74 65 72 20 61 20 63 61 6c 6c 20 74 6f   After a call to
25c00 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
25c10 29 5d 20 74 68 61 74 20 72 65 74 75 72 6e 73 0a  )] that returns.
25c20 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 53 51  **           [SQ
25c30 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 5b  LITE_ROW], the [
25c40 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
25c50 6e 74 28 53 29 5d 20 72 6f 75 74 69 6e 65 0a 2a  nt(S)] routine.*
25c60 2a 20 20 20 20 20 20 20 20 20 20 20 77 69 6c 6c  *           will
25c70 20 72 65 74 75 72 6e 20 74 68 65 20 73 61 6d 65   return the same
25c80 20 76 61 6c 75 65 20 61 73 20 74 68 65 0a 2a 2a   value as the.**
25c90 20 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69             [sqli
25ca0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74  te3_column_count
25cb0 28 53 29 5d 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  (S)] function..*
25cc0 2a 0a 2a 2a 20 7b 46 31 33 37 37 32 7d 20 20 41  *.** {F13772}  A
25cd0 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74  fter [sqlite3_st
25ce0 65 70 28 53 29 5d 20 68 61 73 20 72 65 74 75 72  ep(S)] has retur
25cf0 6e 65 64 20 61 6e 79 20 76 61 6c 75 65 20 6f 74  ned any value ot
25d00 68 65 72 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20  her than.**     
25d10 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 52 4f        [SQLITE_RO
25d20 57 5d 20 6f 72 20 62 65 66 6f 72 65 20 5b 73 71  W] or before [sq
25d30 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68  lite3_step(S)] h
25d40 61 73 20 62 65 65 6e 20 0a 2a 2a 20 20 20 20 20  as been .**     
25d50 20 20 20 20 20 20 63 61 6c 6c 65 64 20 6f 6e 20        called on 
25d60 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
25d70 61 74 65 6d 65 6e 74 5d 20 66 6f 72 0a 2a 2a 20  atement] for.** 
25d80 20 20 20 20 20 20 20 20 20 20 74 68 65 20 66 69            the fi
25d90 72 73 74 20 74 69 6d 65 20 73 69 6e 63 65 20 69  rst time since i
25da0 74 20 77 61 73 20 5b 73 71 6c 69 74 65 33 5f 70  t was [sqlite3_p
25db0 72 65 70 61 72 65 7c 70 72 65 70 61 72 65 64 5d  repare|prepared]
25dc0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6f 72  .**           or
25dd0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 7c   [sqlite3_reset|
25de0 72 65 73 65 74 5d 2c 20 74 68 65 20 5b 73 71 6c  reset], the [sql
25df0 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
25e00 53 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  S)].**          
25e10 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
25e20 20 7a 65 72 6f 2e 0a 2a 2f 0a 69 6e 74 20 73 71   zero..*/.int sq
25e30 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
25e40 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
25e50 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
25e60 50 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e  PI3REF: Fundamen
25e70 74 61 6c 20 44 61 74 61 74 79 70 65 73 20 7b 46  tal Datatypes {F
25e80 31 30 32 36 35 7d 0a 2a 2a 20 4b 45 59 57 4f 52  10265}.** KEYWOR
25e90 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 54 0a  DS: SQLITE_TEXT.
25ea0 2a 2a 0a 2a 2a 20 7b 46 31 30 32 36 36 7d 45 76  **.** {F10266}Ev
25eb0 65 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51 4c  ery value in SQL
25ec0 69 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 66  ite has one of f
25ed0 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20  ive fundamental 
25ee0 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a  datatypes:.**.**
25ef0 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34   <ul>.** <li> 64
25f00 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
25f10 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62  ger.** <li> 64-b
25f20 69 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e 67  it IEEE floating
25f30 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a   point number.**
25f40 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20   <li> string.** 
25f50 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69  <li> BLOB.** <li
25f60 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 20  > NULL.** </ul> 
25f70 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  {END}.**.** Thes
25f80 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  e constants are 
25f90 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68 20 6f  codes for each o
25fa0 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a  f those types..*
25fb0 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74  *.** Note that t
25fc0 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 63  he SQLITE_TEXT c
25fd0 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c 73 6f  onstant was also
25fe0 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74 65 20   used in SQLite 
25ff0 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72  version 2.** for
26000 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69   a completely di
26010 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e  fferent meaning.
26020 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20    Software that 
26030 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 6f  links against bo
26040 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72  th.** SQLite ver
26050 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 74  sion 2 and SQLit
26060 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68 6f 75  e version 3 shou
26070 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33 5f 54  ld use SQLITE3_T
26080 45 58 54 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54  EXT not.** SQLIT
26090 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69  E_TEXT..*/.#defi
260a0 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  ne SQLITE_INTEGE
260b0 52 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c  R  1.#define SQL
260c0 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23  ITE_FLOAT    2.#
260d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c  define SQLITE_BL
260e0 4f 42 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65  OB     4.#define
260f0 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20   SQLITE_NULL    
26100 20 35 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45   5.#ifdef SQLITE
26110 5f 54 45 58 54 0a 23 20 75 6e 64 65 66 20 53 51  _TEXT.# undef SQ
26120 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a  LITE_TEXT.#else.
26130 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
26140 54 45 58 54 20 20 20 20 20 33 0a 23 65 6e 64 69  TEXT     3.#endi
26150 66 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  f.#define SQLITE
26160 33 5f 54 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a  3_TEXT     3../*
26170 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
26180 73 75 6c 74 73 20 56 61 6c 75 65 73 20 46 72 6f  sults Values Fro
26190 6d 20 41 20 51 75 65 72 79 20 7b 46 31 33 38 30  m A Query {F1380
261a0 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  0}.**.** These r
261b0 6f 75 74 69 6e 65 73 20 66 6f 72 6d 20 74 68 65  outines form the
261c0 20 22 72 65 73 75 6c 74 20 73 65 74 20 71 75 65   "result set que
261d0 72 79 22 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ry" interface..*
261e0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
261f0 6e 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72  nes return infor
26200 6d 61 74 69 6f 6e 20 61 62 6f 75 74 0a 2a 2a 20  mation about.** 
26210 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20  a single column 
26220 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 72  of the current r
26230 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 71  esult row of a q
26240 75 65 72 79 2e 20 20 49 6e 20 65 76 65 72 79 0a  uery.  In every.
26250 2a 2a 20 63 61 73 65 20 74 68 65 20 66 69 72 73  ** case the firs
26260 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  t argument is a 
26270 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 0a  pointer to the .
26280 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
26290 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 20  tement] that is 
262a0 62 65 69 6e 67 0a 2a 2a 20 65 76 61 6c 75 61 74  being.** evaluat
262b0 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33  ed (the [sqlite3
262c0 5f 73 74 6d 74 2a 5d 20 74 68 61 74 20 77 61 73  _stmt*] that was
262d0 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 0a   returned from .
262e0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
262f0 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65  are_v2()] or one
26300 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74 73   of its variants
26310 29 20 61 6e 64 0a 2a 2a 20 74 68 65 20 73 65 63  ) and.** the sec
26320 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
26330 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65  the index of the
26340 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63   column for whic
26350 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 0a 2a  h information .*
26360 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75  * should be retu
26370 72 6e 65 64 2e 20 20 54 68 65 20 6c 65 66 74 2d  rned.  The left-
26380 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  most column of t
26390 68 65 20 72 65 73 75 6c 74 20 73 65 74 0a 2a 2a  he result set.**
263a0 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66   has an index of
263b0 20 30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65   0..**.** If the
263c0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69   SQL statement i
263d0 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20  s not currently 
263e0 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69 64  point to a valid
263f0 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65 0a   row, or if the.
26400 2a 2a 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 6e  ** the column in
26410 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61  dex is out of ra
26420 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20  nge, the result 
26430 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 0a 2a  is undefined. .*
26440 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
26450 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c   may only be cal
26460 6c 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f 73  led when the mos
26470 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f  t recent call to
26480 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  .** [sqlite3_ste
26490 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65  p()] has returne
264a0 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61  d [SQLITE_ROW] a
264b0 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73  nd neither.** [s
264c0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
264d0 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  nor [sqlite3_fin
264e0 61 6c 69 7a 65 28 29 5d 20 68 61 73 20 62 65 65  alize()] has bee
264f0 6e 20 63 61 6c 6c 20 73 75 62 73 65 71 75 65 6e  n call subsequen
26500 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f  tly..** If any o
26510 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
26520 20 61 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65   are called afte
26530 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  r [sqlite3_reset
26540 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
26550 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f  e3_finalize()] o
26560 72 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33  r after [sqlite3
26570 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74  _step()] has ret
26580 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69  urned.** somethi
26590 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  ng other than [S
265a0 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20  QLITE_ROW], the 
265b0 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
265c0 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71  fined..** If [sq
265d0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72  lite3_step()] or
265e0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
265f0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  )] or [sqlite3_f
26600 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72  inalize()].** ar
26610 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20  e called from a 
26620 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64  different thread
26630 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68   while any of th
26640 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20  ese routines.** 
26650 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65  are pending, the
26660 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  n the results ar
26670 65 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 0a 2a  e undefined.  .*
26680 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
26690 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72  _column_type() r
266a0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 0a  outine returns .
266b0 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47  ** [SQLITE_INTEG
266c0 45 52 20 7c 20 64 61 74 61 74 79 70 65 20 63 6f  ER | datatype co
266d0 64 65 5d 20 66 6f 72 20 74 68 65 20 69 6e 69 74  de] for the init
266e0 69 61 6c 20 64 61 74 61 20 74 79 70 65 0a 2a 2a  ial data type.**
266f0 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 63   of the result c
26700 6f 6c 75 6d 6e 2e 20 20 54 68 65 20 72 65 74 75  olumn.  The retu
26710 72 6e 65 64 20 76 61 6c 75 65 20 69 73 20 6f 6e  rned value is on
26720 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54  e of [SQLITE_INT
26730 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  EGER],.** [SQLIT
26740 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54  E_FLOAT], [SQLIT
26750 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45  E_TEXT], [SQLITE
26760 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49  _BLOB], or [SQLI
26770 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76  TE_NULL].  The v
26780 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64  alue.** returned
26790 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
267a0 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 6f 6e 6c  mn_type() is onl
267b0 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 20  y meaningful if 
267c0 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65  no type.** conve
267d0 72 73 69 6f 6e 73 20 68 61 76 65 20 6f 63 63 75  rsions have occu
267e0 72 72 65 64 20 61 73 20 64 65 73 63 72 69 62 65  rred as describe
267f0 64 20 62 65 6c 6f 77 2e 20 20 41 66 74 65 72 20  d below.  After 
26800 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  a type conversio
26810 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20  n,.** the value 
26820 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
26830 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
26840 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20  ) is undefined. 
26850 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69   Future.** versi
26860 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61  ons of SQLite ma
26870 79 20 63 68 61 6e 67 65 20 74 68 65 20 62 65 68  y change the beh
26880 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33  avior of sqlite3
26890 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a  _column_type().*
268a0 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79  * following a ty
268b0 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a  pe conversion..*
268c0 2a 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 73 75  *.** If the resu
268d0 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20  lt is a BLOB or 
268e0 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65  UTF-8 string the
268f0 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  n the sqlite3_co
26900 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 0a 2a 2a  lumn_bytes() .**
26910 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
26920 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
26930 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f  ytes in that BLO
26940 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20  B or string..** 
26950 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
26960 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67   a UTF-16 string
26970 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  , then sqlite3_c
26980 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f  olumn_bytes() co
26990 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74  nverts.** the st
269a0 72 69 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e  ring to UTF-8 an
269b0 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74  d then returns t
269c0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
269d0 65 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 72 65  es..** If the re
269e0 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69  sult is a numeri
269f0 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c  c value then sql
26a00 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
26a10 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c  s() uses.** [sql
26a20 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
26a30 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74   to convert that
26a40 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d   value to a UTF-
26a50 38 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74  8 string and ret
26a60 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  urns.** the numb
26a70 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
26a80 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 54  hat string..** T
26a90 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
26aa0 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75  d does not inclu
26ab0 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d  de the zero term
26ac0 69 6e 61 74 6f 72 20 61 74 20 74 68 65 20 65 6e  inator at the en
26ad0 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69  d.** of the stri
26ae0 6e 67 2e 20 20 46 6f 72 20 63 6c 61 72 69 74 79  ng.  For clarity
26af0 3a 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  : the value retu
26b00 72 6e 65 64 20 69 73 20 74 68 65 20 6e 75 6d 62  rned is the numb
26b10 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69  er of.** bytes i
26b20 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f  n the string, no
26b30 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
26b40 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a  characters..**.*
26b50 2a 20 53 74 72 69 6e 67 73 20 72 65 74 75 72 6e  * Strings return
26b60 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
26b70 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 20  lumn_text() and 
26b80 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
26b90 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e  ext16(),.** even
26ba0 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c 20   empty strings, 
26bb0 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f 20  are always zero 
26bc0 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 54 68 65  terminated.  The
26bd0 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65   return.** value
26be0 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f   from sqlite3_co
26bf0 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20  lumn_blob() for 
26c00 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 62 6c  a zero-length bl
26c10 6f 62 20 69 73 20 61 6e 20 61 72 62 69 74 72 61  ob is an arbitra
26c20 72 79 0a 2a 2a 20 70 6f 69 6e 74 65 72 2c 20 70  ry.** pointer, p
26c30 6f 73 73 69 62 6c 79 20 65 76 65 6e 20 61 20 4e  ossibly even a N
26c40 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
26c50 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63  ** The sqlite3_c
26c60 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
26c70 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c  routine is simil
26c80 61 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ar to sqlite3_co
26c90 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20  lumn_bytes().** 
26ca0 62 75 74 20 6c 65 61 76 65 73 20 74 68 65 20 72  but leaves the r
26cb0 65 73 75 6c 74 20 69 6e 20 55 54 46 2d 31 36 20  esult in UTF-16 
26cc0 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  in native byte o
26cd0 72 64 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20  rder instead of 
26ce0 55 54 46 2d 38 2e 20 20 0a 2a 2a 20 54 68 65 20  UTF-8.  .** The 
26cf0 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20  zero terminator 
26d00 69 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 64 20  is not included 
26d10 69 6e 20 74 68 69 73 20 63 6f 75 6e 74 2e 0a 2a  in this count..*
26d20 2a 0a 2a 2a 20 54 68 65 20 6f 62 6a 65 63 74 20  *.** The object 
26d30 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
26d40 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
26d50 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75  e()] is an.** [u
26d60 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
26d70 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
26d80 2e 20 20 41 6e 20 75 6e 70 72 6f 74 65 63 74 65  .  An unprotecte
26d90 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  d sqlite3_value 
26da0 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e  object.** may on
26db0 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68 20  ly be used with 
26dc0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61  [sqlite3_bind_va
26dd0 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  lue()] and [sqli
26de0 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
26df0 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b  ()]..** If the [
26e00 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
26e10 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
26e20 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  t returned by.**
26e30 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
26e40 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65  _value()] is use
26e50 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77  d in any other w
26e60 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61  ay, including ca
26e70 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e  lls.** to routin
26e80 65 73 20 6c 69 6b 65 20 0a 2a 2a 20 5b 73 71 6c  es like .** [sql
26e90 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29  ite3_value_int()
26ea0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
26eb0 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72 20 5b 73  e_text()], or [s
26ec0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
26ed0 65 73 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74  es()],.** then t
26ee0 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75  he behavior is u
26ef0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
26f00 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
26f10 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72  ttempt to conver
26f20 74 20 74 68 65 20 76 61 6c 75 65 20 77 68 65 72  t the value wher
26f30 65 20 61 70 70 72 6f 70 72 69 61 74 65 2e 20 20  e appropriate.  
26f40 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20  For.** example, 
26f50 69 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20  if the internal 
26f60 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69  representation i
26f70 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 65  s FLOAT and a te
26f80 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20  xt result.** is 
26f90 72 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c 69  requested, [sqli
26fa0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20  te3_snprintf()] 
26fb0 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c  is used internal
26fc0 6c 79 20 74 6f 20 64 6f 20 74 68 65 20 63 6f 6e  ly to do the con
26fd0 76 65 72 73 69 6f 6e 0a 2a 2a 20 61 75 74 6f 6d  version.** autom
26fe0 61 74 69 63 61 6c 6c 79 2e 20 20 54 68 65 20 66  atically.  The f
26ff0 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 64  ollowing table d
27000 65 74 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 65  etails the conve
27010 72 73 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 61  rsions that.** a
27020 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a  re applied:.**.*
27030 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  * <blockquote>.*
27040 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d  * <table border=
27050 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e  "1">.** <tr><th>
27060 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70   Internal<br>Typ
27070 65 20 3c 74 68 3e 20 52 65 71 75 65 73 74 65 64  e <th> Requested
27080 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 43  <br>Type <th>  C
27090 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20  onversion.**.** 
270a0 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
270b0 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
270c0 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
270d0 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  0.** <tr><td>  N
270e0 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f  ULL    <td>  FLO
270f0 41 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  AT    <td> Resul
27100 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e  t is 0.0.** <tr>
27110 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74  <td>  NULL    <t
27120 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64  d>   TEXT    <td
27130 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c  > Result is NULL
27140 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e   pointer.** <tr>
27150 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74  <td>  NULL    <t
27160 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
27170 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c  > Result is NULL
27180 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e   pointer.** <tr>
27190 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74  <td> INTEGER  <t
271a0 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
271b0 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69  > Convert from i
271c0 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a  nteger to float.
271d0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45  ** <tr><td> INTE
271e0 47 45 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54  GER  <td>   TEXT
271f0 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72      <td> ASCII r
27200 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20  endering of the 
27210 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c  integer.** <tr><
27220 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64  td> INTEGER  <td
27230 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  >   BLOB    <td>
27240 20 53 61 6d 65 20 61 73 20 66 6f 72 20 49 4e 54   Same as for INT
27250 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74  EGER->TEXT.** <t
27260 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20  r><td>  FLOAT   
27270 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
27280 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d  td> Convert from
27290 20 66 6c 6f 61 74 20 74 6f 20 69 6e 74 65 67 65   float to intege
272a0 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46  r.** <tr><td>  F
272b0 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45  LOAT   <td>   TE
272c0 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49  XT    <td> ASCII
272d0 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68   rendering of th
272e0 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c  e float.** <tr><
272f0 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64  td>  FLOAT   <td
27300 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  >   BLOB    <td>
27310 20 53 61 6d 65 20 61 73 20 46 4c 4f 41 54 2d 3e   Same as FLOAT->
27320 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  TEXT.** <tr><td>
27330 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 49    TEXT    <td> I
27340 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 55 73  NTEGER   <td> Us
27350 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e  e atoi().** <tr>
27360 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74  <td>  TEXT    <t
27370 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
27380 3e 20 55 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20  > Use atof().** 
27390 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20  <tr><td>  TEXT  
273a0 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
273b0 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a   <td> No change.
273c0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f  ** <tr><td>  BLO
273d0 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45  B    <td> INTEGE
273e0 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74  R   <td> Convert
273f0 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73   to TEXT then us
27400 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e  e atoi().** <tr>
27410 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74  <td>  BLOB    <t
27420 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
27430 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58  > Convert to TEX
27440 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f 66 28  T then use atof(
27450 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42  ).** <tr><td>  B
27460 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 54 45  LOB    <td>   TE
27470 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64 20 61  XT    <td> Add a
27480 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
27490 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f   if needed.** </
274a0 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63  table>.** </bloc
274b0 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
274c0 65 20 74 61 62 6c 65 20 61 62 6f 76 65 20 6d 61  e table above ma
274d0 6b 65 73 20 72 65 66 65 72 65 6e 63 65 20 74 6f  kes reference to
274e0 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
274f0 61 72 79 20 66 75 6e 63 74 69 6f 6e 73 20 61 74  ary functions at
27500 6f 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74 6f 66  oi().** and atof
27510 28 29 2e 20 20 53 51 4c 69 74 65 20 64 6f 65 73  ().  SQLite does
27520 20 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73 65 20   not really use 
27530 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e  these functions.
27540 20 20 49 74 20 68 61 73 20 69 74 73 0a 2a 2a 20    It has its.** 
27550 6f 77 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 69  own equivalent i
27560 6e 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e 65 73  nternal routines
27570 2e 20 20 54 68 65 20 61 74 6f 69 28 29 20 61 6e  .  The atoi() an
27580 64 20 61 74 6f 66 28 29 20 6e 61 6d 65 73 20 61  d atof() names a
27590 72 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20 74 68  re.** used in th
275a0 65 20 74 61 62 6c 65 20 66 6f 72 20 62 72 65 76  e table for brev
275b0 69 74 79 20 61 6e 64 20 62 65 63 61 75 73 65 20  ity and because 
275c0 74 68 65 79 20 61 72 65 20 66 61 6d 69 6c 69 61  they are familia
275d0 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20 70  r to most.** C p
275e0 72 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a  rogrammers..**.*
275f0 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e  * Note that when
27600 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
27610 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72  s occur, pointer
27620 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 70 72  s returned by pr
27630 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20  ior.** calls to 
27640 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
27650 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63  lob(), sqlite3_c
27660 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e  olumn_text(), an
27670 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  d/or.** sqlite3_
27680 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
27690 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74  may be invalidat
276a0 65 64 2e 20 0a 2a 2a 20 54 79 70 65 20 63 6f 6e  ed. .** Type con
276b0 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69  versions and poi
276c0 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f  nter invalidatio
276d0 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a  ns might occur.*
276e0 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69  * in the followi
276f0 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20  ng cases:.**.** 
27700 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 3c 70 3e 20  <ul>.** <li><p> 
27710 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e   The initial con
27720 74 65 6e 74 20 69 73 20 61 20 42 4c 4f 42 20 61  tent is a BLOB a
27730 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
27740 6e 5f 74 65 78 74 28 29 20 0a 2a 2a 20 20 20 20  n_text() .**    
27750 20 20 20 20 20 20 6f 72 20 73 71 6c 69 74 65 33        or sqlite3
27760 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
27770 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a   is called.  A z
27780 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d  ero-terminator m
27790 69 67 68 74 0a 2a 2a 20 20 20 20 20 20 20 20 20  ight.**         
277a0 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64 65   need to be adde
277b0 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67 2e  d to the string.
277c0 3c 2f 70 3e 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20  </p></li>.**.** 
277d0 3c 6c 69 3e 3c 70 3e 20 20 54 68 65 20 69 6e 69  <li><p>  The ini
277e0 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20  tial content is 
277f0 55 54 46 2d 38 20 74 65 78 74 20 61 6e 64 20 73  UTF-8 text and s
27800 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
27810 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20  tes16() or.**   
27820 20 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63         sqlite3_c
27830 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69  olumn_text16() i
27840 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63  s called.  The c
27850 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63  ontent must be c
27860 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20  onverted.**     
27870 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c       to UTF-16.<
27880 2f 70 3e 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c  /p></li>.**.** <
27890 6c 69 3e 3c 70 3e 20 20 54 68 65 20 69 6e 69 74  li><p>  The init
278a0 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55  ial content is U
278b0 54 46 2d 31 36 20 74 65 78 74 20 61 6e 64 20 73  TF-16 text and s
278c0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
278d0 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20  tes() or.**     
278e0 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c       sqlite3_col
278f0 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61  umn_text() is ca
27900 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65  lled.  The conte
27910 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65  nt must be conve
27920 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  rted.**         
27930 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 70 3e 3c 2f   to UTF-8.</p></
27940 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  li>.** </ul>.**.
27950 2a 2a 20 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62  ** Conversions b
27960 65 74 77 65 65 6e 20 55 54 46 2d 31 36 62 65 20  etween UTF-16be 
27970 61 6e 64 20 55 54 46 2d 31 36 6c 65 20 61 72 65  and UTF-16le are
27980 20 61 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e 20   always done in 
27990 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20  place and do.** 
279a0 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74 65 20 61  not invalidate a
279b0 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20   prior pointer, 
279c0 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 65  though of course
279d0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
279e0 74 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 74 68  the buffer.** th
279f0 61 74 20 74 68 65 20 70 72 69 6f 72 20 70 6f 69  at the prior poi
27a00 6e 74 65 72 20 70 6f 69 6e 74 73 20 74 6f 20 77  nter points to w
27a10 69 6c 6c 20 68 61 76 65 20 62 65 65 6e 20 6d 6f  ill have been mo
27a20 64 69 66 69 65 64 2e 20 20 4f 74 68 65 72 20 6b  dified.  Other k
27a30 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65  inds.** of conve
27a40 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69  rsion are done i
27a50 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 69 74 20  n place when it 
27a60 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 62 75 74  is possible, but
27a70 20 73 6f 6d 65 74 69 6d 65 20 69 74 20 69 73 0a   sometime it is.
27a80 2a 2a 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  ** not possible 
27a90 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73  and in those cas
27aa0 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72  es prior pointer
27ab0 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65  s are invalidate
27ac0 64 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  d.  .**.** The s
27ad0 61 66 65 73 74 20 61 6e 64 20 65 61 73 69 65 73  afest and easies
27ae0 74 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 70 6f  t to remember po
27af0 6c 69 63 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b  licy is to invok
27b00 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  e these routines
27b10 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68  .** in one of th
27b20 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73  e following ways
27b30 3a 0a 2a 2a 0a 2a 2a 20 20 3c 75 6c 3e 0a 2a 2a  :.**.**  <ul>.**
27b40 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f    <li>sqlite3_co
27b50 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c  lumn_text() foll
27b60 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  owed by sqlite3_
27b70 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f  column_bytes()</
27b80 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69  li>.**  <li>sqli
27b90 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
27ba0 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71  ) followed by sq
27bb0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
27bc0 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c  es()</li>.**  <l
27bd0 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  i>sqlite3_column
27be0 5f 74 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77  _text16() follow
27bf0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
27c00 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f  lumn_bytes16()</
27c10 6c 69 3e 0a 2a 2a 20 20 3c 2f 75 6c 3e 0a 2a 2a  li>.**  </ul>.**
27c20 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  .** In other wor
27c30 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20 63  ds, you should c
27c40 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  all sqlite3_colu
27c50 6d 6e 5f 74 65 78 74 28 29 2c 20 73 71 6c 69 74  mn_text(), sqlit
27c60 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
27c70 2c 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  ,.** or sqlite3_
27c80 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
27c90 66 69 72 73 74 20 74 6f 20 66 6f 72 63 65 20 74  first to force t
27ca0 68 65 20 72 65 73 75 6c 74 20 69 6e 74 6f 20 74  he result into t
27cb0 68 65 20 64 65 73 69 72 65 64 0a 2a 2a 20 66 6f  he desired.** fo
27cc0 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b  rmat, then invok
27cd0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
27ce0 5f 62 79 74 65 73 28 29 20 6f 72 20 73 71 6c 69  _bytes() or sqli
27cf0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
27d00 31 36 28 29 20 74 6f 0a 2a 2a 20 66 69 6e 64 20  16() to.** find 
27d10 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
27d20 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20  result.  Do not 
27d30 6d 69 78 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  mix call to sqli
27d40 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
27d50 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ) or.** sqlite3_
27d60 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69  column_blob() wi
27d70 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  th calls to sqli
27d80 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
27d90 31 36 28 29 2e 20 20 41 6e 64 20 64 6f 20 6e 6f  16().  And do no
27da0 74 0a 2a 2a 20 6d 69 78 20 63 61 6c 6c 73 20 74  t.** mix calls t
27db0 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
27dc0 5f 74 65 78 74 31 36 28 29 20 77 69 74 68 20 63  _text16() with c
27dd0 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
27de0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a  column_bytes()..
27df0 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65  **.** The pointe
27e00 72 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20  rs returned are 
27e10 76 61 6c 69 64 20 75 6e 74 69 6c 20 61 20 74 79  valid until a ty
27e20 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63  pe conversion oc
27e30 63 75 72 73 20 61 73 0a 2a 2a 20 64 65 73 63 72  curs as.** descr
27e40 69 62 65 64 20 61 62 6f 76 65 2c 20 6f 72 20 75  ibed above, or u
27e50 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74  ntil [sqlite3_st
27e60 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ep()] or [sqlite
27e70 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a  3_reset()] or.**
27e80 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
27e90 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e  ze()] is called.
27ea0 20 20 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 61    The memory spa
27eb0 63 65 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20  ce used to hold 
27ec0 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 62  strings.** and b
27ed0 6c 6f 62 73 20 69 73 20 66 72 65 65 64 20 61 75  lobs is freed au
27ee0 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f  tomatically.  Do
27ef0 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 73   <b>not</b> pass
27f00 20 74 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65   the pointers re
27f10 74 75 72 6e 65 64 0a 2a 2a 20 5b 73 71 6c 69 74  turned.** [sqlit
27f20 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
27f30 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ], [sqlite3_colu
27f40 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 2e  mn_text()], etc.
27f50 20 69 6e 74 6f 20 0a 2a 2a 20 5b 73 71 6c 69 74   into .** [sqlit
27f60 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a  e3_free()]..**.*
27f70 2a 20 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c  * If a memory al
27f80 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f  location error o
27f90 63 63 75 72 73 20 64 75 72 69 6e 67 20 74 68 65  ccurs during the
27fa0 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61   evaluation of a
27fb0 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 72  ny.** of these r
27fc0 6f 75 74 69 6e 65 73 2c 20 61 20 64 65 66 61 75  outines, a defau
27fd0 6c 74 20 76 61 6c 75 65 20 69 73 20 72 65 74 75  lt value is retu
27fe0 72 6e 65 64 2e 20 20 54 68 65 20 64 65 66 61 75  rned.  The defau
27ff0 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65  lt value.** is e
28000 69 74 68 65 72 20 74 68 65 20 69 6e 74 65 67 65  ither the intege
28010 72 20 30 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e  r 0, the floatin
28020 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30  g point number 0
28030 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a  .0, or a NULL.**
28040 20 70 6f 69 6e 74 65 72 2e 20 20 53 75 62 73 65   pointer.  Subse
28050 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b  quent calls to [
28060 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
28070 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a  )] will return.*
28080 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d  * [SQLITE_NOMEM]
28090 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
280a0 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 30  TS:.**.** {F1380
280b0 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  3} The [sqlite3_
280c0 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 53 2c 4e 29  column_blob(S,N)
280d0 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76  ] interface conv
280e0 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  erts the.**     
280f0 20 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20       Nth column 
28100 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72  in the current r
28110 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ow of the result
28120 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20   set for.**     
28130 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73       [prepared s
28140 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f  tatement] S into
28150 20 61 20 62 6c 6f 62 20 61 6e 64 20 74 68 65 6e   a blob and then
28160 20 72 65 74 75 72 6e 73 20 61 0a 2a 2a 20 20 20   returns a.**   
28170 20 20 20 20 20 20 20 70 6f 69 6e 74 65 72 20 74         pointer t
28180 6f 20 74 68 65 20 63 6f 6e 76 65 72 74 65 64 20  o the converted 
28190 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  value..**.** {F1
281a0 33 38 30 36 7d 20 54 68 65 20 5b 73 71 6c 69 74  3806} The [sqlit
281b0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
281c0 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  S,N)] interface 
281d0 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20  returns the.**  
281e0 20 20 20 20 20 20 20 20 6e 75 6d 62 65 72 20 6f          number o
281f0 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 62  f bytes in the b
28200 6c 6f 62 20 6f 72 20 73 74 72 69 6e 67 20 28 65  lob or string (e
28210 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65 0a  xclusive of the.
28220 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f  **          zero
28230 20 74 65 72 6d 69 6e 61 74 6f 72 20 6f 6e 20 74   terminator on t
28240 68 65 20 73 74 72 69 6e 67 29 20 74 68 61 74 20  he string) that 
28250 77 61 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  was returned by 
28260 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
28270 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c  most recent call
28280 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   to [sqlite3_col
28290 75 6d 6e 5f 62 6c 6f 62 28 53 2c 4e 29 5d 20 6f  umn_blob(S,N)] o
282a0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  r.**          [s
282b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
282c0 78 74 28 53 2c 4e 29 5d 2e 0a 2a 2a 0a 2a 2a 20  xt(S,N)]..**.** 
282d0 7b 46 31 33 38 30 39 7d 20 54 68 65 20 5b 73 71  {F13809} The [sq
282e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
282f0 65 73 31 36 28 53 2c 4e 29 5d 20 69 6e 74 65 72  es16(S,N)] inter
28300 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
28310 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 75 6d  .**          num
28320 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
28330 74 68 65 20 73 74 72 69 6e 67 20 28 65 78 63 6c  the string (excl
28340 75 73 69 76 65 20 6f 66 20 74 68 65 0a 2a 2a 20  usive of the.** 
28350 20 20 20 20 20 20 20 20 20 7a 65 72 6f 20 74 65           zero te
28360 72 6d 69 6e 61 74 6f 72 20 6f 6e 20 74 68 65 20  rminator on the 
28370 73 74 72 69 6e 67 29 20 74 68 61 74 20 77 61 73  string) that was
28380 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
28390 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 6f 73  .**          mos
283a0 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f  t recent call to
283b0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
283c0 5f 74 65 78 74 31 36 28 53 2c 4e 29 5d 2e 0a 2a  _text16(S,N)]..*
283d0 2a 0a 2a 2a 20 7b 46 31 33 38 31 32 7d 20 54 68  *.** {F13812} Th
283e0 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
283f0 6e 5f 64 6f 75 62 6c 65 28 53 2c 4e 29 5d 20 69  n_double(S,N)] i
28400 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74  nterface convert
28410 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
28420 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20    Nth column in 
28430 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20  the current row 
28440 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
28450 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  t for.**        
28460 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74    [prepared stat
28470 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20  ement] S into a 
28480 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76  floating point v
28490 61 6c 75 65 20 61 6e 64 0a 2a 2a 20 20 20 20 20  alue and.**     
284a0 20 20 20 20 20 72 65 74 75 72 6e 73 20 61 20 63       returns a c
284b0 6f 70 79 20 6f 66 20 74 68 61 74 20 76 61 6c 75  opy of that valu
284c0 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 31 35  e..**.** {F13815
284d0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
284e0 6f 6c 75 6d 6e 5f 69 6e 74 28 53 2c 4e 29 5d 20  olumn_int(S,N)] 
284f0 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72  interface conver
28500 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ts the.**       
28510 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e     Nth column in
28520 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77   the current row
28530 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
28540 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20  et for.**       
28550 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61     [prepared sta
28560 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61  tement] S into a
28570 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69   64-bit signed i
28580 6e 74 65 67 65 72 20 61 6e 64 0a 2a 2a 20 20 20  nteger and.**   
28590 20 20 20 20 20 20 20 72 65 74 75 72 6e 73 20 74         returns t
285a0 68 65 20 6c 6f 77 65 72 20 33 32 20 62 69 74 73  he lower 32 bits
285b0 20 6f 66 20 74 68 61 74 20 69 6e 74 65 67 65 72   of that integer
285c0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 31 38 7d  ..**.** {F13818}
285d0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
285e0 6c 75 6d 6e 5f 69 6e 74 36 34 28 53 2c 4e 29 5d  lumn_int64(S,N)]
285f0 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65   interface conve
28600 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  rts the.**      
28610 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69      Nth column i
28620 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f  n the current ro
28630 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  w of the result 
28640 73 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20  set for.**      
28650 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74      [prepared st
28660 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20  atement] S into 
28670 61 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  a 64-bit signed 
28680 69 6e 74 65 67 65 72 20 61 6e 64 0a 2a 2a 20 20  integer and.**  
28690 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 73 20          returns 
286a0 61 20 63 6f 70 79 20 6f 66 20 74 68 61 74 20 69  a copy of that i
286b0 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46  nteger..**.** {F
286c0 31 33 38 32 31 7d 20 54 68 65 20 5b 73 71 6c 69  13821} The [sqli
286d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
286e0 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  S,N)] interface 
286f0 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20  converts the.** 
28700 20 20 20 20 20 20 20 20 20 4e 74 68 20 63 6f 6c           Nth col
28710 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65  umn in the curre
28720 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65  nt row of the re
28730 73 75 6c 74 20 73 65 74 20 66 6f 72 0a 2a 2a 20  sult set for.** 
28740 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72           [prepar
28750 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
28760 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d  into a zero-term
28770 69 6e 61 74 65 64 20 55 54 46 2d 38 20 0a 2a 2a  inated UTF-8 .**
28780 20 20 20 20 20 20 20 20 20 20 73 74 72 69 6e 67            string
28790 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70   and returns a p
287a0 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20 73  ointer to that s
287b0 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  tring..**.** {F1
287c0 33 38 32 34 7d 20 54 68 65 20 5b 73 71 6c 69 74  3824} The [sqlit
287d0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
287e0 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  (S,N)] interface
287f0 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a   converts the.**
28800 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 63 6f            Nth co
28810 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72  lumn in the curr
28820 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72  ent row of the r
28830 65 73 75 6c 74 20 73 65 74 20 66 6f 72 0a 2a 2a  esult set for.**
28840 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61            [prepa
28850 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
28860 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72   into a zero-ter
28870 6d 69 6e 61 74 65 64 20 32 2d 62 79 74 65 0a 2a  minated 2-byte.*
28880 2a 20 20 20 20 20 20 20 20 20 20 61 6c 69 67 6e  *          align
28890 65 64 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65  ed UTF-16 native
288a0 20 62 79 74 65 20 6f 72 64 65 72 0a 2a 2a 20 20   byte order.**  
288b0 20 20 20 20 20 20 20 20 73 74 72 69 6e 67 20 61          string a
288c0 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  nd returns a poi
288d0 6e 74 65 72 20 74 6f 20 74 68 61 74 20 73 74 72  nter to that str
288e0 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38  ing..**.** {F138
288f0 32 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  27} The [sqlite3
28900 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 53 2c 4e  _column_type(S,N
28910 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
28920 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  urns.**         
28930 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f   one of [SQLITE_
28940 4e 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49  NULL], [SQLITE_I
28950 4e 54 45 47 45 52 5d 2c 20 5b 53 51 4c 49 54 45  NTEGER], [SQLITE
28960 5f 46 4c 4f 41 54 5d 2c 0a 2a 2a 20 20 20 20 20  _FLOAT],.**     
28970 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 54 45 58       [SQLITE_TEX
28980 54 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 42  T], or [SQLITE_B
28990 4c 4f 42 5d 20 61 73 20 61 70 70 72 6f 70 72 69  LOB] as appropri
289a0 61 74 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20  ate for.**      
289b0 20 20 20 20 74 68 65 20 4e 74 68 20 63 6f 6c 75      the Nth colu
289c0 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e  mn in the curren
289d0 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73  t row of the res
289e0 75 6c 74 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20  ult set for.**  
289f0 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65          [prepare
28a00 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a  d statement] S..
28a10 2a 2a 0a 2a 2a 20 7b 46 31 33 38 33 30 7d 20 54  **.** {F13830} T
28a20 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
28a30 6d 6e 5f 76 61 6c 75 65 28 53 2c 4e 29 5d 20 69  mn_value(S,N)] i
28a40 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
28a50 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70   a.**          p
28a60 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b 75 6e  ointer to an [un
28a70 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
28a80 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
28a90 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  for the.**      
28aa0 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69      Nth column i
28ab0 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f  n the current ro
28ac0 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  w of the result 
28ad0 73 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20  set for.**      
28ae0 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74      [prepared st
28af0 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 63  atement] S..*/.c
28b00 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
28b10 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73  e3_column_blob(s
28b20 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
28b30 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c  t iCol);.int sql
28b40 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
28b50 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  s(sqlite3_stmt*,
28b60 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20   int iCol);.int 
28b70 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
28b80 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 73  ytes16(sqlite3_s
28b90 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
28ba0 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f  .double sqlite3_
28bb0 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71  column_double(sq
28bc0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
28bd0 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69   iCol);.int sqli
28be0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73  te3_column_int(s
28bf0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
28c00 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33  t iCol);.sqlite3
28c10 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 63  _int64 sqlite3_c
28c20 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69  olumn_int64(sqli
28c30 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
28c40 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69  Col);.const unsi
28c50 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74  gned char *sqlit
28c60 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73  e3_column_text(s
28c70 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
28c80 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76  t iCol);.const v
28c90 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
28ca0 75 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c 69 74  umn_text16(sqlit
28cb0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
28cc0 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ol);.int sqlite3
28cd0 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c  _column_type(sql
28ce0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
28cf0 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 76  iCol);.sqlite3_v
28d00 61 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f  alue *sqlite3_co
28d10 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74  lumn_value(sqlit
28d20 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
28d30 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ol);../*.** CAPI
28d40 33 52 45 46 3a 20 44 65 73 74 72 6f 79 20 41 20  3REF: Destroy A 
28d50 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
28d60 6e 74 20 4f 62 6a 65 63 74 20 7b 46 31 33 33 30  nt Object {F1330
28d70 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  0}.**.** The sql
28d80 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20  ite3_finalize() 
28d90 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c  function is call
28da0 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20 0a  ed to delete a .
28db0 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
28dc0 74 65 6d 65 6e 74 5d 2e 20 49 66 20 74 68 65 20  tement]. If the 
28dd0 73 74 61 74 65 6d 65 6e 74 20 77 61 73 0a 2a 2a  statement was.**
28de0 20 65 78 65 63 75 74 65 64 20 73 75 63 63 65 73   executed succes
28df0 73 66 75 6c 6c 79 2c 20 6f 72 20 6e 6f 74 20 65  sfully, or not e
28e00 78 65 63 75 74 65 64 20 61 74 20 61 6c 6c 2c 20  xecuted at all, 
28e10 74 68 65 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69  then SQLITE_OK i
28e20 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 49  s returned..** I
28e30 66 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74  f execution of t
28e40 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 61 69  he statement fai
28e50 6c 65 64 20 74 68 65 6e 20 61 6e 20 0a 2a 2a 20  led then an .** 
28e60 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 20  [error code] or 
28e70 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  [extended error 
28e80 63 6f 64 65 5d 0a 2a 2a 20 69 73 20 72 65 74 75  code].** is retu
28e90 72 6e 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 54 68 69  rned. .**.** Thi
28ea0 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65  s routine can be
28eb0 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 70   called at any p
28ec0 6f 69 6e 74 20 64 75 72 69 6e 67 20 74 68 65 20  oint during the 
28ed0 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65  execution of the
28ee0 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
28ef0 61 74 65 6d 65 6e 74 5d 2e 20 20 49 66 20 74 68  atement].  If th
28f00 65 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e  e virtual machin
28f10 65 20 68 61 73 20 6e 6f 74 20 0a 2a 2a 20 63 6f  e has not .** co
28f20 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74 69 6f  mpleted executio
28f30 6e 20 77 68 65 6e 20 74 68 69 73 20 72 6f 75 74  n when this rout
28f40 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 2c 20 74  ine is called, t
28f50 68 61 74 20 69 73 20 6c 69 6b 65 0a 2a 2a 20 65  hat is like.** e
28f60 6e 63 6f 75 6e 74 65 72 69 6e 67 20 61 6e 20 65  ncountering an e
28f70 72 72 6f 72 20 6f 72 20 61 6e 20 69 6e 74 65 72  rror or an inter
28f80 72 75 70 74 2e 20 20 28 53 65 65 20 5b 73 71 6c  rupt.  (See [sql
28f90 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
28fa0 5d 2e 29 20 0a 2a 2a 20 49 6e 63 6f 6d 70 6c 65  ].) .** Incomple
28fb0 74 65 20 75 70 64 61 74 65 73 20 6d 61 79 20 62  te updates may b
28fc0 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 6e  e rolled back an
28fd0 64 20 74 72 61 6e 73 61 63 74 69 6f 6e 73 20 63  d transactions c
28fe0 61 6e 63 65 6c 65 64 2c 20 20 0a 2a 2a 20 64 65  anceled,  .** de
28ff0 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63  pending on the c
29000 69 72 63 75 6d 73 74 61 6e 63 65 73 2c 20 61 6e  ircumstances, an
29010 64 20 74 68 65 20 0a 2a 2a 20 5b 65 72 72 6f 72  d the .** [error
29020 20 63 6f 64 65 5d 20 72 65 74 75 72 6e 65 64 20   code] returned 
29030 77 69 6c 6c 20 62 65 20 5b 53 51 4c 49 54 45 5f  will be [SQLITE_
29040 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e  ABORT]..**.** IN
29050 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
29060 7b 46 31 31 33 30 32 7d 20 54 68 65 20 5b 73 71  {F11302} The [sq
29070 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53  lite3_finalize(S
29080 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64 65 73  )] interface des
29090 74 72 6f 79 73 20 74 68 65 0a 2a 2a 20 20 20 20  troys the.**    
290a0 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20        [prepared 
290b0 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 61 6e 64  statement] S and
290c0 20 72 65 6c 65 61 73 65 73 20 61 6c 6c 0a 2a 2a   releases all.**
290d0 20 20 20 20 20 20 20 20 20 20 6d 65 6d 6f 72 79            memory
290e0 20 61 6e 64 20 66 69 6c 65 20 72 65 73 6f 75 72   and file resour
290f0 63 65 73 20 68 65 6c 64 20 62 79 20 74 68 61 74  ces held by that
29100 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 7b   object..**.** {
29110 46 31 31 33 30 34 7d 20 49 66 20 74 68 65 20 6d  F11304} If the m
29120 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
29130 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
29140 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20  (S)] for the.** 
29150 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72           [prepar
29160 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
29170 72 65 74 75 72 6e 65 64 20 61 6e 20 65 72 72 6f  returned an erro
29180 72 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  r,.**          t
29190 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  hen [sqlite3_fin
291a0 61 6c 69 7a 65 28 53 29 5d 20 72 65 74 75 72 6e  alize(S)] return
291b0 73 20 74 68 61 74 20 73 61 6d 65 20 65 72 72 6f  s that same erro
291c0 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  r..*/.int sqlite
291d0 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74  3_finalize(sqlit
291e0 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
291f0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
29200 3a 20 52 65 73 65 74 20 41 20 50 72 65 70 61 72  : Reset A Prepar
29210 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a  ed Statement Obj
29220 65 63 74 20 7b 46 31 33 33 33 30 7d 0a 2a 2a 0a  ect {F13330}.**.
29230 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
29240 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20  eset() function 
29250 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73  is called to res
29260 65 74 20 61 20 0a 2a 2a 20 5b 70 72 65 70 61 72  et a .** [prepar
29270 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62  ed statement] ob
29280 6a 65 63 74 2e 0a 2a 2a 20 62 61 63 6b 20 74 6f  ject..** back to
29290 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61   its initial sta
292a0 74 65 2c 20 72 65 61 64 79 20 74 6f 20 62 65 20  te, ready to be 
292b0 72 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20  re-executed..** 
292c0 41 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  Any SQL statemen
292d0 74 20 76 61 72 69 61 62 6c 65 73 20 74 68 61 74  t variables that
292e0 20 68 61 64 20 76 61 6c 75 65 73 20 62 6f 75 6e   had values boun
292f0 64 20 74 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a  d to them using.
29300 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
29310 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69  bind_blob | sqli
29320 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49  te3_bind_*() API
29330 5d 20 72 65 74 61 69 6e 20 74 68 65 69 72 20 76  ] retain their v
29340 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73  alues..** Use [s
29350 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e  qlite3_clear_bin
29360 64 69 6e 67 73 28 29 5d 20 74 6f 20 72 65 73 65  dings()] to rese
29370 74 20 74 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a  t the bindings..
29380 2a 2a 0a 2a 2a 20 7b 46 31 31 33 33 32 7d 20 54  **.** {F11332} T
29390 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  he [sqlite3_rese
293a0 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20  t(S)] interface 
293b0 72 65 73 65 74 73 20 74 68 65 20 5b 70 72 65 70  resets the [prep
293c0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
293d0 53 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 61  S.**          ba
293e0 63 6b 20 74 6f 20 74 68 65 20 62 65 67 69 6e 6e  ck to the beginn
293f0 69 6e 67 20 6f 66 20 69 74 73 20 70 72 6f 67 72  ing of its progr
29400 61 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 33 33  am..**.** {F1133
29410 34 7d 20 49 66 20 74 68 65 20 6d 6f 73 74 20 72  4} If the most r
29420 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73  ecent call to [s
29430 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
29440 66 6f 72 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  for .**         
29450 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
29460 6d 65 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64  ment] S returned
29470 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72   [SQLITE_ROW] or
29480 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a   [SQLITE_DONE],.
29490 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 69  **          or i
294a0 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  f [sqlite3_step(
294b0 53 29 5d 20 68 61 73 20 6e 65 76 65 72 20 62 65  S)] has never be
294c0 66 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 64  fore been called
294d0 20 6f 6e 20 53 2c 0a 2a 2a 20 20 20 20 20 20 20   on S,.**       
294e0 20 20 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33     then [sqlite3
294f0 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72  _reset(S)] retur
29500 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a  ns [SQLITE_OK]..
29510 2a 2a 0a 2a 2a 20 7b 46 31 31 33 33 36 7d 20 49  **.** {F11336} I
29520 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
29530 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
29540 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 0a  e3_step(S)] for.
29550 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65  **          [pre
29560 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
29570 20 53 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20   S indicated an 
29580 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 20  error, then.**  
29590 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
295a0 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72  _reset(S)] retur
295b0 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74  ns an appropriat
295c0 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a  e [error code]..
295d0 2a 2a 0a 2a 2a 20 7b 46 31 31 33 33 38 7d 20 54  **.** {F11338} T
295e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  he [sqlite3_rese
295f0 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20  t(S)] interface 
29600 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20  does not change 
29610 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 20 20  the values.**   
29620 20 20 20 20 20 20 20 6f 66 20 61 6e 79 20 5b 73         of any [s
29630 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
29640 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 5b 70  |bindings] on [p
29650 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
29660 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  t] S..*/.int sql
29670 69 74 65 33 5f 72 65 73 65 74 28 73 71 6c 69 74  ite3_reset(sqlit
29680 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
29690 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
296a0 3a 20 43 72 65 61 74 65 20 4f 72 20 52 65 64 65  : Create Or Rede
296b0 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 74 69 6f  fine SQL Functio
296c0 6e 73 20 7b 46 31 36 31 30 30 7d 0a 2a 2a 20 4b  ns {F16100}.** K
296d0 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69  EYWORDS: {functi
296e0 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74  on creation rout
296f0 69 6e 65 73 7d 20 0a 2a 2a 0a 2a 2a 20 54 68 65  ines} .**.** The
29700 73 65 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73  se two functions
29710 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b   (collectively k
29720 6e 6f 77 6e 20 61 73 0a 2a 2a 20 22 66 75 6e 63  nown as.** "func
29730 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f  tion creation ro
29740 75 74 69 6e 65 73 22 29 20 61 72 65 20 75 73 65  utines") are use
29750 64 20 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e  d to add SQL fun
29760 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67  ctions or aggreg
29770 61 74 65 73 0a 2a 2a 20 6f 72 20 74 6f 20 72 65  ates.** or to re
29780 64 65 66 69 6e 65 20 74 68 65 20 62 65 68 61 76  define the behav
29790 69 6f 72 20 6f 66 20 65 78 69 73 74 69 6e 67 20  ior of existing 
297a0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72  SQL functions or
297b0 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 54 68   aggregates.  Th
297c0 65 0a 2a 2a 20 64 69 66 66 65 72 65 6e 63 65 20  e.** difference 
297d0 6f 6e 6c 79 20 62 65 74 77 65 65 6e 20 74 68 65  only between the
297e0 20 74 77 6f 20 69 73 20 74 68 61 74 20 74 68 65   two is that the
297f0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
29800 72 2c 20 74 68 65 0a 2a 2a 20 6e 61 6d 65 20 6f  r, the.** name o
29810 66 20 74 68 65 20 28 73 63 61 6c 61 72 29 20 66  f the (scalar) f
29820 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65  unction or aggre
29830 67 61 74 65 2c 20 69 73 20 65 6e 63 6f 64 65 64  gate, is encoded
29840 20 69 6e 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a   in UTF-8 for.**
29850 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
29860 66 75 6e 63 74 69 6f 6e 28 29 20 61 6e 64 20 55  function() and U
29870 54 46 2d 31 36 20 66 6f 72 20 73 71 6c 69 74 65  TF-16 for sqlite
29880 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
29890 6e 31 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  n16()..**.** The
298a0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
298b0 20 69 73 20 74 68 65 20 5b 64 61 74 61 62 61 73   is the [databas
298c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f  e connection] to
298d0 20 77 68 69 63 68 20 74 68 65 20 53 51 4c 0a 2a   which the SQL.*
298e0 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f  * function is to
298f0 20 62 65 20 61 64 64 65 64 2e 20 20 49 66 20 61   be added.  If a
29900 20 73 69 6e 67 6c 65 0a 2a 2a 20 70 72 6f 67 72   single.** progr
29910 61 6d 20 75 73 65 73 20 6d 6f 72 65 20 74 68 61  am uses more tha
29920 6e 20 6f 6e 65 20 5b 64 61 74 61 62 61 73 65 20  n one [database 
29930 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 6e 74 65  connection] inte
29940 72 6e 61 6c 6c 79 2c 20 74 68 65 6e 20 53 51 4c  rnally, then SQL
29950 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75  .** functions mu
29960 73 74 20 62 65 20 61 64 64 65 64 20 69 6e 64 69  st be added indi
29970 76 69 64 75 61 6c 6c 79 20 74 6f 20 65 61 63 68  vidually to each
29980 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
29990 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  ction]..**.** Th
299a0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
299b0 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  er is the name o
299c0 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  f the SQL functi
299d0 6f 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65 64  on to be created
299e0 0a 2a 2a 20 6f 72 20 72 65 64 65 66 69 6e 65 64  .** or redefined
299f0 2e 0a 2a 2a 20 54 68 65 20 6c 65 6e 67 74 68 20  ..** The length 
29a00 6f 66 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c  of the name is l
29a10 69 6d 69 74 65 64 20 74 6f 20 32 35 35 20 62 79  imited to 255 by
29a20 74 65 73 2c 20 65 78 63 6c 75 73 69 76 65 20 6f  tes, exclusive o
29a30 66 20 74 68 65 20 0a 2a 2a 20 7a 65 72 6f 2d 74  f the .** zero-t
29a40 65 72 6d 69 6e 61 74 6f 72 2e 20 20 4e 6f 74 65  erminator.  Note
29a50 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65 20 6c   that the name l
29a60 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20 69  ength limit is i
29a70 6e 20 62 79 74 65 73 2c 20 6e 6f 74 0a 2a 2a 20  n bytes, not.** 
29a80 63 68 61 72 61 63 74 65 72 73 2e 20 20 41 6e 79  characters.  Any
29a90 20 61 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61   attempt to crea
29aa0 74 65 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69  te a function wi
29ab0 74 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65  th a longer name
29ac0 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 20  .** will result 
29ad0 69 6e 20 61 6e 20 53 51 4c 49 54 45 5f 45 52 52  in an SQLITE_ERR
29ae0 4f 52 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20  OR error..**.** 
29af0 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  The third parame
29b00 74 65 72 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ter is the numbe
29b10 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74  r of arguments t
29b20 68 61 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63  hat the SQL func
29b30 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65  tion or.** aggre
29b40 67 61 74 65 20 74 61 6b 65 73 2e 20 49 66 20 74  gate takes. If t
29b50 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 69 73  his parameter is
29b60 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20   negative, then 
29b70 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
29b80 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65   or.** aggregate
29b90 20 6d 61 79 20 74 61 6b 65 20 61 6e 79 20 6e 75   may take any nu
29ba0 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
29bb0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 75  s..**.** The fou
29bc0 72 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65  rth parameter, e
29bd0 54 65 78 74 52 65 70 2c 20 73 70 65 63 69 66 69  TextRep, specifi
29be0 65 73 20 77 68 61 74 20 0a 2a 2a 20 5b 53 51 4c  es what .** [SQL
29bf0 49 54 45 5f 55 54 46 38 20 7c 20 74 65 78 74 20  ITE_UTF8 | text 
29c00 65 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73 20 53  encoding] this S
29c10 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72 65 66  QL function pref
29c20 65 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70  ers for.** its p
29c30 61 72 61 6d 65 74 65 72 73 2e 20 20 41 6e 79 20  arameters.  Any 
29c40 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70  SQL function imp
29c50 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75  lementation shou
29c60 6c 64 20 62 65 20 61 62 6c 65 20 74 6f 20 77 6f  ld be able to wo
29c70 72 6b 0a 2a 2a 20 77 6f 72 6b 20 77 69 74 68 20  rk.** work with 
29c80 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 6c 65 2c  UTF-8, UTF-16le,
29c90 20 6f 72 20 55 54 46 2d 31 36 62 65 2e 20 20 42   or UTF-16be.  B
29ca0 75 74 20 73 6f 6d 65 20 69 6d 70 6c 65 6d 65 6e  ut some implemen
29cb0 74 61 74 69 6f 6e 73 20 6d 61 79 20 62 65 0a 2a  tations may be.*
29cc0 2a 20 6d 6f 72 65 20 65 66 66 69 63 69 65 6e 74  * more efficient
29cd0 20 77 69 74 68 20 6f 6e 65 20 65 6e 63 6f 64 69   with one encodi
29ce0 6e 67 20 74 68 61 6e 20 61 6e 6f 74 68 65 72 2e  ng than another.
29cf0 20 20 49 74 20 69 73 20 61 6c 6c 6f 77 65 64 20    It is allowed 
29d00 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c  to.** invoke sql
29d10 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
29d20 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c 69 74 65  tion() or sqlite
29d30 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
29d40 6e 31 36 28 29 20 6d 75 6c 74 69 70 6c 65 0a 2a  n16() multiple.*
29d50 2a 20 74 69 6d 65 73 20 77 69 74 68 20 74 68 65  * times with the
29d60 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 62   same function b
29d70 75 74 20 77 69 74 68 20 64 69 66 66 65 72 65 6e  ut with differen
29d80 74 20 76 61 6c 75 65 73 20 6f 66 20 65 54 65 78  t values of eTex
29d90 74 52 65 70 2e 0a 2a 2a 20 57 68 65 6e 20 6d 75  tRep..** When mu
29da0 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  ltiple implement
29db0 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
29dc0 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20  me function are 
29dd0 61 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74  available, SQLit
29de0 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74  e.** will pick t
29df0 68 65 20 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f  he one that invo
29e00 6c 76 65 73 20 74 68 65 20 6c 65 61 73 74 20 61  lves the least a
29e10 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 63 6f  mount of data co
29e20 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 49 66 20  nversion..** If 
29e30 74 68 65 72 65 20 69 73 20 6f 6e 6c 79 20 61 20  there is only a 
29e40 73 69 6e 67 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  single implement
29e50 61 74 69 6f 6e 20 77 68 69 63 68 20 64 6f 65 73  ation which does
29e60 20 6e 6f 74 20 63 61 72 65 20 77 68 61 74 0a 2a   not care what.*
29e70 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20  * text encoding 
29e80 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20 74 68  is used, then th
29e90 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  e fourth argumen
29ea0 74 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 5b  t should be.** [
29eb0 53 51 4c 49 54 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a  SQLITE_ANY]..**.
29ec0 2a 2a 20 54 68 65 20 66 69 66 74 68 20 70 61 72  ** The fifth par
29ed0 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72 62  ameter is an arb
29ee0 69 74 72 61 72 79 20 70 6f 69 6e 74 65 72 2e 20  itrary pointer. 
29ef0 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   The implementat
29f00 69 6f 6e 0a 2a 2a 20 6f 66 20 74 68 65 20 66 75  ion.** of the fu
29f10 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20  nction can gain 
29f20 61 63 63 65 73 73 20 74 6f 20 74 68 69 73 20 70  access to this p
29f30 6f 69 6e 74 65 72 20 75 73 69 6e 67 0a 2a 2a 20  ointer using.** 
29f40 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61  [sqlite3_user_da
29f50 74 61 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ta()]..**.** The
29f60 20 73 65 76 65 6e 74 68 2c 20 65 69 67 68 74 68   seventh, eighth
29f70 20 61 6e 64 20 6e 69 6e 74 68 20 70 61 72 61 6d   and ninth param
29f80 65 74 65 72 73 2c 20 78 46 75 6e 63 2c 20 78 53  eters, xFunc, xS
29f90 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20  tep and xFinal, 
29fa0 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20  are.** pointers 
29fb0 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20 66 75  to C-language fu
29fc0 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 69 6d 70  nctions that imp
29fd0 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 0a 2a  lement the SQL.*
29fe0 2a 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67  * function or ag
29ff0 67 72 65 67 61 74 65 2e 20 41 20 73 63 61 6c 61  gregate. A scala
2a000 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72  r SQL function r
2a010 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65  equires an imple
2a020 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20  mentation of.** 
2a030 74 68 65 20 78 46 75 6e 63 20 63 61 6c 6c 62 61  the xFunc callba
2a040 63 6b 20 6f 6e 6c 79 2c 20 4e 55 4c 4c 20 70 6f  ck only, NULL po
2a050 69 6e 74 65 72 73 20 73 68 6f 75 6c 64 20 62 65  inters should be
2a060 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 78   passed as the x
2a070 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e  Step.** and xFin
2a080 61 6c 20 70 61 72 61 6d 65 74 65 72 73 2e 20 41  al parameters. A
2a090 6e 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20  n aggregate SQL 
2a0a0 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65  function require
2a0b0 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  s an implementat
2a0c0 69 6f 6e 0a 2a 2a 20 6f 66 20 78 53 74 65 70 20  ion.** of xStep 
2a0d0 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e  and xFinal and N
2a0e0 55 4c 4c 20 73 68 6f 75 6c 64 20 62 65 20 70 61  ULL should be pa
2a0f0 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20  ssed for xFunc. 
2a100 54 6f 20 64 65 6c 65 74 65 20 61 6e 0a 2a 2a 20  To delete an.** 
2a110 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e  existing SQL fun
2a120 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61  ction or aggrega
2a130 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 66 6f  te, pass NULL fo
2a140 72 20 61 6c 6c 20 74 68 72 65 65 20 66 75 6e 63  r all three func
2a150 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  tion.** callback
2a160 73 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 70  s..**.** It is p
2a170 65 72 6d 69 74 74 65 64 20 74 6f 20 72 65 67 69  ermitted to regi
2a180 73 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d  ster multiple im
2a190 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66  plementations of
2a1a0 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e   the same.** fun
2a1b0 63 74 69 6f 6e 73 20 77 69 74 68 20 74 68 65 20  ctions with the 
2a1c0 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 69  same name but wi
2a1d0 74 68 20 65 69 74 68 65 72 20 64 69 66 66 65 72  th either differ
2a1e0 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a  ing numbers of.*
2a1f0 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 64  * arguments or d
2a200 69 66 66 65 72 69 6e 67 20 70 72 65 66 65 72 72  iffering preferr
2a210 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  ed text encoding
2a220 73 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  s.  SQLite will 
2a230 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65  use.** the imple
2a240 6d 65 6e 74 61 74 69 6f 6e 20 6d 6f 73 74 20 63  mentation most c
2a250 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74  losely matches t
2a260 68 65 20 77 61 79 20 69 6e 20 77 68 69 63 68 20  he way in which 
2a270 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74  the.** SQL funct
2a280 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a  ion is used..**.
2a290 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
2a2a0 2a 0a 2a 2a 20 7b 46 31 36 31 30 33 7d 20 54 68  *.** {F16103} Th
2a2b0 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
2a2c0 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20  e_function16()] 
2a2d0 69 6e 74 65 72 66 61 63 65 20 62 65 68 61 76 65  interface behave
2a2e0 73 20 65 78 61 63 74 6c 79 0a 2a 2a 20 20 20 20  s exactly.**    
2a2f0 20 20 20 20 20 20 6c 69 6b 65 20 5b 73 71 6c 69        like [sqli
2a300 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2a310 69 6f 6e 28 29 5d 20 69 6e 20 65 76 65 72 79 20  ion()] in every 
2a320 77 61 79 20 65 78 63 65 70 74 20 74 68 61 74 20  way except that 
2a330 69 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  it.**          i
2a340 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 7a 46  nterprets the zF
2a350 75 6e 63 74 69 6f 6e 4e 61 6d 65 20 61 72 67 75  unctionName argu
2a360 6d 65 6e 74 20 61 73 0a 2a 2a 20 20 20 20 20 20  ment as.**      
2a370 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61      zero-termina
2a380 74 65 64 20 55 54 46 2d 31 36 20 6e 61 74 69 76  ted UTF-16 nativ
2a390 65 20 62 79 74 65 20 6f 72 64 65 72 20 69 6e 73  e byte order ins
2a3a0 74 65 61 64 20 6f 66 20 61 73 20 61 0a 2a 2a 20  tead of as a.** 
2a3b0 20 20 20 20 20 20 20 20 20 7a 65 72 6f 2d 74 65           zero-te
2a3c0 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 2e 0a  rminated UTF-8..
2a3d0 2a 2a 0a 2a 2a 20 7b 46 31 36 31 30 36 7d 20 41  **.** {F16106} A
2a3e0 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f   successful invo
2a3f0 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 20 20 20  cation of.**    
2a400 20 20 20 20 20 20 74 68 65 20 5b 73 71 6c 69 74        the [sqlit
2a410 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2a420 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 2e 2e 2e 29 5d  on(D,X,N,E,...)]
2a430 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73   interface regis
2a440 74 65 72 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  ters.**         
2a450 20 6f 72 20 72 65 70 6c 61 63 65 73 20 63 61 6c   or replaces cal
2a460 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20  lback functions 
2a470 69 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  in [database con
2a480 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 20 20  nection] D.**   
2a490 20 20 20 20 20 20 20 75 73 65 64 20 74 6f 20 69         used to i
2a4a0 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c  mplement the SQL
2a4b0 20 66 75 6e 63 74 69 6f 6e 20 6e 61 6d 65 64 20   function named 
2a4c0 58 20 77 69 74 68 20 4e 20 70 61 72 61 6d 65 74  X with N paramet
2a4d0 65 72 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ers.**          
2a4e0 61 6e 64 20 68 61 76 69 6e 67 20 61 20 70 72 65  and having a pre
2a4f0 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f  ferred text enco
2a500 64 69 6e 67 20 6f 66 20 45 2e 0a 2a 2a 0a 2a 2a  ding of E..**.**
2a510 20 7b 46 31 36 31 30 39 7d 20 41 20 73 75 63 63   {F16109} A succ
2a520 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b  essful call to [
2a530 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2a540 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c  unction(D,X,N,E,
2a550 50 2c 46 2c 53 2c 4c 29 5d 0a 2a 2a 20 20 20 20  P,F,S,L)].**    
2a560 20 20 20 20 20 20 72 65 70 6c 61 63 65 73 20 74        replaces t
2a570 68 65 20 50 2c 20 46 2c 20 53 2c 20 61 6e 64 20  he P, F, S, and 
2a580 4c 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 61 6e  L values from an
2a590 79 20 70 72 69 6f 72 20 63 61 6c 6c 73 20 77 69  y prior calls wi
2a5a0 74 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  th.**          t
2a5b0 68 65 20 73 61 6d 65 20 44 2c 20 58 2c 20 4e 2c  he same D, X, N,
2a5c0 20 61 6e 64 20 45 20 76 61 6c 75 65 73 2e 0a 2a   and E values..*
2a5d0 2a 0a 2a 2a 20 7b 46 31 36 31 31 32 7d 20 54 68  *.** {F16112} Th
2a5e0 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
2a5f0 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 2e  e_function(D,X,.
2a600 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 66  ..)] interface f
2a610 61 69 6c 73 20 77 69 74 68 0a 2a 2a 20 20 20 20  ails with.**    
2a620 20 20 20 20 20 20 61 20 72 65 74 75 72 6e 20 63        a return c
2a630 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 45  ode of [SQLITE_E
2a640 52 52 4f 52 5d 20 69 66 20 74 68 65 20 53 51 4c  RROR] if the SQL
2a650 20 66 75 6e 63 74 69 6f 6e 20 6e 61 6d 65 20 58   function name X
2a660 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   is.**          
2a670 6c 6f 6e 67 65 72 20 74 68 61 6e 20 32 35 35 20  longer than 255 
2a680 62 79 74 65 73 20 65 78 63 6c 75 73 69 76 65 20  bytes exclusive 
2a690 6f 66 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d  of the zero term
2a6a0 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46  inator..**.** {F
2a6b0 31 36 31 31 38 7d 20 45 69 74 68 65 72 20 46 20  16118} Either F 
2a6c0 6d 75 73 74 20 62 65 20 4e 55 4c 4c 20 61 6e 64  must be NULL and
2a6d0 20 53 20 61 6e 64 20 4c 20 61 72 65 20 6e 6f 6e   S and L are non
2a6e0 2d 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 46 0a  -NULL or else F.
2a6f0 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 6e  **          is n
2a700 6f 6e 2d 4e 55 4c 4c 20 61 6e 64 20 53 20 61 6e  on-NULL and S an
2a710 64 20 4c 20 61 72 65 20 4e 55 4c 4c 2c 20 6f 74  d L are NULL, ot
2a720 68 65 72 77 69 73 65 0a 2a 2a 20 20 20 20 20 20  herwise.**      
2a730 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 72 65      [sqlite3_cre
2a740 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58  ate_function(D,X
2a750 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 20 72  ,N,E,P,F,S,L)] r
2a760 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 45  eturns [SQLITE_E
2a770 52 52 4f 52 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  RROR]..**.** {F1
2a780 36 31 32 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  6121} The [sqlit
2a790 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2a7a0 6f 6e 28 44 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72  on(D,...)] inter
2a7b0 66 61 63 65 20 66 61 69 6c 73 20 77 69 74 68 20  face fails with 
2a7c0 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65  an.**          e
2a7d0 72 72 6f 72 20 63 6f 64 65 20 6f 66 20 5b 53 51  rror code of [SQ
2a7e0 4c 49 54 45 5f 42 55 53 59 5d 20 69 66 20 74 68  LITE_BUSY] if th
2a7f0 65 72 65 20 65 78 69 73 74 20 5b 70 72 65 70 61  ere exist [prepa
2a800 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 0a  red statements].
2a810 2a 2a 20 20 20 20 20 20 20 20 20 20 61 73 73 6f  **          asso
2a820 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
2a830 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2a840 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b  tion] D..**.** {
2a850 46 31 36 31 32 34 7d 20 54 68 65 20 5b 73 71 6c  F16124} The [sql
2a860 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2a870 74 69 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d  tion(D,X,N,...)]
2a880 20 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73   interface fails
2a890 20 77 69 74 68 20 61 6e 0a 2a 2a 20 20 20 20 20   with an.**     
2a8a0 20 20 20 20 20 65 72 72 6f 72 20 63 6f 64 65 20       error code 
2a8b0 6f 66 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  of [SQLITE_ERROR
2a8c0 5d 20 69 66 20 70 61 72 61 6d 65 74 65 72 20 4e  ] if parameter N
2a8d0 20 28 73 70 65 63 69 66 79 69 6e 67 20 74 68 65   (specifying the
2a8e0 20 6e 75 6d 62 65 72 0a 2a 2a 20 20 20 20 20 20   number.**      
2a8f0 20 20 20 20 6f 66 20 61 72 67 75 6d 65 6e 74 73      of arguments
2a900 20 74 6f 20 74 68 65 20 53 51 4c 20 66 75 6e 63   to the SQL func
2a910 74 69 6f 6e 20 62 65 69 6e 67 20 72 65 67 69 73  tion being regis
2a920 74 65 72 65 64 29 20 69 73 20 6c 65 73 73 0a 2a  tered) is less.*
2a930 2a 20 20 20 20 20 20 20 20 20 20 74 68 61 6e 20  *          than 
2a940 2d 31 20 6f 72 20 67 72 65 61 74 65 72 20 74 68  -1 or greater th
2a950 61 6e 20 31 32 37 2e 0a 2a 2a 0a 2a 2a 20 7b 46  an 127..**.** {F
2a960 31 36 31 32 37 7d 20 57 68 65 6e 20 4e 20 69 73  16127} When N is
2a970 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74   non-negative, t
2a980 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  he [sqlite3_crea
2a990 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c  te_function(D,X,
2a9a0 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20  N,...)].**      
2a9b0 20 20 20 20 69 6e 74 65 72 66 61 63 65 20 63 61      interface ca
2a9c0 75 73 65 73 20 63 61 6c 6c 62 61 63 6b 73 20 74  uses callbacks t
2a9d0 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 66 6f 72  o be invoked for
2a9e0 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
2a9f0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 61  n.**          na
2aa00 6d 65 64 20 58 20 77 68 65 6e 20 74 68 65 20 6e  med X when the n
2aa10 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e  umber of argumen
2aa20 74 73 20 74 6f 20 74 68 65 20 53 51 4c 20 66 75  ts to the SQL fu
2aa30 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20  nction is.**    
2aa40 20 20 20 20 20 20 65 78 61 63 74 6c 79 20 4e 2e        exactly N.
2aa50 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 33 30 7d 20  .**.** {F16130} 
2aa60 57 68 65 6e 20 4e 20 69 73 20 2d 31 2c 20 74 68  When N is -1, th
2aa70 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
2aa80 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e  e_function(D,X,N
2aa90 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ,...)].**       
2aaa0 20 20 20 69 6e 74 65 72 66 61 63 65 20 63 61 75     interface cau
2aab0 73 65 73 20 63 61 6c 6c 62 61 63 6b 73 20 74 6f  ses callbacks to
2aac0 20 62 65 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20   be invoked for 
2aad0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
2aae0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 61 6d  .**          nam
2aaf0 65 64 20 58 20 77 69 74 68 20 61 6e 79 20 6e 75  ed X with any nu
2ab00 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
2ab10 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 33 33  s..**.** {F16133
2ab20 7d 20 57 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20  } When calls to 
2ab30 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2ab40 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 2e  function(D,X,N,.
2ab50 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ..)].**         
2ab60 20 73 70 65 63 69 66 79 20 6d 75 6c 74 69 70 6c   specify multipl
2ab70 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
2ab80 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75  s of the same fu
2ab90 6e 63 74 69 6f 6e 20 58 0a 2a 2a 20 20 20 20 20  nction X.**     
2aba0 20 20 20 20 20 61 6e 64 20 77 68 65 6e 20 6f 6e       and when on
2abb0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
2abc0 20 68 61 73 20 4e 3e 3d 30 20 61 6e 64 20 74 68   has N>=0 and th
2abd0 65 20 6f 74 68 65 72 20 68 61 73 20 4e 3d 28 2d  e other has N=(-
2abe0 31 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  1).**          t
2abf0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
2ac00 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a 65 72  n with a non-zer
2ac10 6f 20 4e 20 69 73 20 70 72 65 66 65 72 72 65 64  o N is preferred
2ac20 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 33 36 7d  ..**.** {F16136}
2ac30 20 57 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20 5b   When calls to [
2ac40 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2ac50 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c  unction(D,X,N,E,
2ac60 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  ...)].**        
2ac70 20 20 73 70 65 63 69 66 79 20 6d 75 6c 74 69 70    specify multip
2ac80 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
2ac90 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66  ns of the same f
2aca0 75 6e 63 74 69 6f 6e 20 58 20 77 69 74 68 0a 2a  unction X with.*
2acb0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 73  *          the s
2acc0 61 6d 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72  ame number of ar
2acd0 67 75 6d 65 6e 74 73 20 4e 20 62 75 74 20 77 69  guments N but wi
2ace0 74 68 20 64 69 66 66 65 72 65 6e 74 0a 2a 2a 20  th different.** 
2acf0 20 20 20 20 20 20 20 20 20 65 6e 63 6f 64 69 6e           encodin
2ad00 67 73 20 45 2c 20 74 68 65 6e 20 74 68 65 20 69  gs E, then the i
2ad10 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68  mplementation wh
2ad20 65 72 65 20 45 20 6d 61 74 63 68 65 73 20 74 68  ere E matches th
2ad30 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 61  e.**          da
2ad40 74 61 62 61 73 65 20 65 6e 63 6f 64 69 6e 67 20  tabase encoding 
2ad50 69 73 20 70 72 65 66 65 72 72 65 64 2e 0a 2a 2a  is preferred..**
2ad60 0a 2a 2a 20 7b 46 31 36 31 33 39 7d 20 46 6f 72  .** {F16139} For
2ad70 20 61 6e 20 61 67 67 72 65 67 61 74 65 20 53 51   an aggregate SQ
2ad80 4c 20 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74  L function creat
2ad90 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20  ed using.**     
2ada0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 72       [sqlite3_cr
2adb0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c  eate_function(D,
2adc0 58 2c 4e 2c 45 2c 50 2c 30 2c 53 2c 4c 29 5d 20  X,N,E,P,0,S,L)] 
2add0 74 68 65 20 66 69 6e 69 61 6c 69 7a 65 72 0a 2a  the finializer.*
2ade0 2a 20 20 20 20 20 20 20 20 20 20 66 75 6e 63 74  *          funct
2adf0 69 6f 6e 20 4c 20 77 69 6c 6c 20 61 6c 77 61 79  ion L will alway
2ae00 73 20 62 65 20 69 6e 76 6f 6b 65 64 20 65 78 61  s be invoked exa
2ae10 63 74 6c 79 20 6f 6e 63 65 20 69 66 20 74 68 65  ctly once if the
2ae20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 65  .**          ste
2ae30 70 20 66 75 6e 63 74 69 6f 6e 20 53 20 69 73 20  p function S is 
2ae40 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f  called one or mo
2ae50 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 0a 2a 2a 20  re times..**.** 
2ae60 7b 46 31 36 31 34 32 7d 20 57 68 65 6e 20 53 51  {F16142} When SQ
2ae70 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 65 69 74  Lite invokes eit
2ae80 68 65 72 20 74 68 65 20 78 46 75 6e 63 20 6f 72  her the xFunc or
2ae90 20 78 53 74 65 70 20 66 75 6e 63 74 69 6f 6e 20   xStep function 
2aea0 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  of.**          a
2aeb0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
2aec0 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
2aed0 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 20  on or aggregate 
2aee0 63 72 65 61 74 65 64 0a 2a 2a 20 20 20 20 20 20  created.**      
2aef0 20 20 20 20 62 79 20 5b 73 71 6c 69 74 65 33 5f      by [sqlite3_
2af00 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
2af10 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63  )] or [sqlite3_c
2af20 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
2af30 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ()],.**         
2af40 20 74 68 65 6e 20 74 68 65 20 61 72 72 61 79 20   then the array 
2af50 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  of [sqlite3_valu
2af60 65 5d 20 6f 62 6a 65 63 74 73 20 70 61 73 73 65  e] objects passe
2af70 64 20 61 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  d as the.**     
2af80 20 20 20 20 20 74 68 69 72 64 20 70 61 72 61 6d       third param
2af90 65 74 65 72 20 61 72 65 20 61 6c 77 61 79 73 20  eter are always 
2afa0 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
2afb0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
2afc0 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  s..*/.int sqlite
2afd0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2afe0 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  n(.  sqlite3 *db
2aff0 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  ,.  const char *
2b000 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20  zFunctionName,. 
2b010 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74   int nArg,.  int
2b020 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69   eTextRep,.  voi
2b030 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20  d *pApp,.  void 
2b040 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33  (*xFunc)(sqlite3
2b050 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
2b060 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
2b070 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28    void (*xStep)(
2b080 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2b090 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
2b0a0 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
2b0b0 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f  xFinal)(sqlite3_
2b0c0 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74  context*).);.int
2b0d0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2b0e0 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73 71  function16(.  sq
2b0f0 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e  lite3 *db,.  con
2b100 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69  st void *zFuncti
2b110 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41  onName,.  int nA
2b120 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52  rg,.  int eTextR
2b130 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70  ep,.  void *pApp
2b140 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63  ,.  void (*xFunc
2b150 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
2b160 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
2b170 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
2b180 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33  (*xStep)(sqlite3
2b190 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
2b1a0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
2b1b0 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29    void (*xFinal)
2b1c0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2b1d0 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  *).);../*.** CAP
2b1e0 49 33 52 45 46 3a 20 54 65 78 74 20 45 6e 63 6f  I3REF: Text Enco
2b1f0 64 69 6e 67 73 20 7b 46 31 30 32 36 37 7d 0a 2a  dings {F10267}.*
2b200 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
2b210 61 6e 74 20 64 65 66 69 6e 65 20 69 6e 74 65 67  ant define integ
2b220 65 72 20 63 6f 64 65 73 20 74 68 61 74 20 72 65  er codes that re
2b230 70 72 65 73 65 6e 74 20 74 68 65 20 76 61 72 69  present the vari
2b240 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f  ous.** text enco
2b250 64 69 6e 67 73 20 73 75 70 70 6f 72 74 65 64 20  dings supported 
2b260 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64  by SQLite..*/.#d
2b270 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46  efine SQLITE_UTF
2b280 38 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64  8           1.#d
2b290 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46  efine SQLITE_UTF
2b2a0 31 36 4c 45 20 20 20 20 20 20 20 20 32 0a 23 64  16LE        2.#d
2b2b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46  efine SQLITE_UTF
2b2c0 31 36 42 45 20 20 20 20 20 20 20 20 33 0a 23 64  16BE        3.#d
2b2d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46  efine SQLITE_UTF
2b2e0 31 36 20 20 20 20 20 20 20 20 20 20 34 20 20 20  16          4   
2b2f0 20 2f 2a 20 55 73 65 20 6e 61 74 69 76 65 20 62   /* Use native b
2b300 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65  yte order */.#de
2b310 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59 20  fine SQLITE_ANY 
2b320 20 20 20 20 20 20 20 20 20 20 20 35 20 20 20 20             5    
2b330 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  /* sqlite3_creat
2b340 65 5f 66 75 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20  e_function only 
2b350 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
2b360 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 20  E_UTF16_ALIGNED 
2b370 20 38 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33   8    /* sqlite3
2b380 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
2b390 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  n only */../*.**
2b3a0 20 43 41 50 49 33 52 45 46 3a 20 4f 62 73 6f 6c   CAPI3REF: Obsol
2b3b0 65 74 65 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  ete Functions.**
2b3c0 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69  .** These functi
2b3d0 6f 6e 73 20 61 72 65 20 61 6c 6c 20 6e 6f 77 20  ons are all now 
2b3e0 6f 62 73 6f 6c 65 74 65 2e 20 20 49 6e 20 6f 72  obsolete.  In or
2b3f0 64 65 72 20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a  der to maintain.
2b400 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  ** backwards com
2b410 70 61 74 69 62 69 6c 69 74 79 20 77 69 74 68 20  patibility with 
2b420 6f 6c 64 65 72 20 63 6f 64 65 2c 20 77 65 20 63  older code, we c
2b430 6f 6e 74 69 6e 75 65 20 74 6f 20 73 75 70 70 6f  ontinue to suppo
2b440 72 74 0a 2a 2a 20 74 68 65 73 65 20 66 75 6e 63  rt.** these func
2b450 74 69 6f 6e 73 2e 20 20 48 6f 77 65 76 65 72 2c  tions.  However,
2b460 20 6e 65 77 20 64 65 76 65 6c 6f 70 6d 65 6e 74   new development
2b470 20 70 72 6f 6a 65 63 74 73 20 73 68 6f 75 6c 64   projects should
2b480 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73   avoid.** the us
2b490 65 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74  e of these funct
2b4a0 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70 20 65  ions.  To help e
2b4b0 6e 63 6f 75 72 61 67 65 20 70 65 6f 70 6c 65 20  ncourage people 
2b4c0 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73 69 6e  to avoid.** usin
2b4d0 67 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  g these function
2b4e0 73 2c 20 77 65 20 61 72 65 20 6e 6f 74 20 67 6f  s, we are not go
2b4f0 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f 75 20  ing to tell you 
2b500 77 61 6e 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f  want they do..*/
2b510 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 67 67  .int sqlite3_agg
2b520 72 65 67 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c  regate_count(sql
2b530 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
2b540 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 70 69  int sqlite3_expi
2b550 72 65 64 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  red(sqlite3_stmt
2b560 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
2b570 74 72 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67  transfer_binding
2b580 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  s(sqlite3_stmt*,
2b590 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b   sqlite3_stmt*);
2b5a0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f  .int sqlite3_glo
2b5b0 62 61 6c 5f 72 65 63 6f 76 65 72 28 76 6f 69 64  bal_recover(void
2b5c0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
2b5d0 74 68 72 65 61 64 5f 63 6c 65 61 6e 75 70 28 76  thread_cleanup(v
2b5e0 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  oid);.int sqlite
2b5f0 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76  3_memory_alarm(v
2b600 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c  oid(*)(void*,sql
2b610 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c  ite3_int64,int),
2b620 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e  void*,sqlite3_in
2b630 74 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  t64);../*.** CAP
2b640 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67  I3REF: Obtaining
2b650 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 50 61   SQL Function Pa
2b660 72 61 6d 65 74 65 72 20 56 61 6c 75 65 73 20 7b  rameter Values {
2b670 46 31 35 31 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68  F15100}.**.** Th
2b680 65 20 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70  e C-language imp
2b690 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53  lementation of S
2b6a0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64  QL functions and
2b6b0 20 61 67 67 72 65 67 61 74 65 73 20 75 73 65 73   aggregates uses
2b6c0 0a 2a 2a 20 74 68 69 73 20 73 65 74 20 6f 66 20  .** this set of 
2b6d0 69 6e 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e  interface routin
2b6e0 65 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65  es to access the
2b6f0 20 70 61 72 61 6d 65 74 65 72 20 76 61 6c 75 65   parameter value
2b700 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63  s on.** the func
2b710 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74  tion or aggregat
2b720 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75  e..**.** The xFu
2b730 6e 63 20 28 66 6f 72 20 73 63 61 6c 61 72 20 66  nc (for scalar f
2b740 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78 53 74  unctions) or xSt
2b750 65 70 20 28 66 6f 72 20 61 67 67 72 65 67 61 74  ep (for aggregat
2b760 65 73 29 20 70 61 72 61 6d 65 74 65 72 73 0a 2a  es) parameters.*
2b770 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72  * to [sqlite3_cr
2b780 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
2b790 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72   and [sqlite3_cr
2b7a0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
2b7b0 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c  )].** define cal
2b7c0 6c 62 61 63 6b 73 20 74 68 61 74 20 69 6d 70 6c  lbacks that impl
2b7d0 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75  ement the SQL fu
2b7e0 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72  nctions and aggr
2b7f0 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20 34  egates..** The 4
2b800 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
2b810 74 68 65 73 65 20 63 61 6c 6c 62 61 63 6b 73 20  these callbacks 
2b820 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
2b830 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70  ointers to.** [p
2b840 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2b850 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e  _value] objects.
2b860 20 20 54 68 65 72 65 20 69 73 20 6f 6e 65 20 5b    There is one [
2b870 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2b880 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63  bject for.** eac
2b890 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
2b8a0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e  he SQL function.
2b8b0 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73    These routines
2b8c0 20 61 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20   are used to.** 
2b8d0 65 78 74 72 61 63 74 20 76 61 6c 75 65 73 20 66  extract values f
2b8e0 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33  rom the [sqlite3
2b8f0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e  _value] objects.
2b900 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
2b910 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20  tines work only 
2b920 77 69 74 68 20 5b 70 72 6f 74 65 63 74 65 64 20  with [protected 
2b930 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2b940 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61  bjects..** Any a
2b950 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68  ttempt to use th
2b960 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20  ese routines on 
2b970 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  an [unprotected 
2b980 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a  sqlite3_value].*
2b990 2a 20 6f 62 6a 65 63 74 20 72 65 73 75 6c 74 73  * object results
2b9a0 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65   in undefined be
2b9b0 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  havior..**.** Th
2b9c0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72  ese routines wor
2b9d0 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 20  k just like the 
2b9e0 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 0a 2a  corresponding .*
2b9f0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
2ba00 6e 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33  n_blob | sqlite3
2ba10 5f 63 6f 6c 75 6d 6e 5f 2a 20 72 6f 75 74 69 6e  _column_* routin
2ba20 65 73 5d 20 65 78 63 65 70 74 20 74 68 61 74 20  es] except that 
2ba30 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75 74 69 6e  .** these routin
2ba40 65 73 20 74 61 6b 65 20 61 20 73 69 6e 67 6c 65  es take a single
2ba50 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
2ba60 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
2ba70 74 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 69 6e 73  t pointer.** ins
2ba80 74 65 61 64 20 6f 66 20 61 20 5b 73 71 6c 69 74  tead of a [sqlit
2ba90 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65  e3_stmt*] pointe
2baa0 72 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 65 72  r and an integer
2bab0 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a   column number..
2bac0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
2bad0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29  3_value_text16()
2bae0 20 69 6e 74 65 72 66 61 63 65 20 65 78 74 72 61   interface extra
2baf0 63 74 73 20 61 20 55 54 46 31 36 20 73 74 72 69  cts a UTF16 stri
2bb00 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74  ng.** in the nat
2bb10 69 76 65 20 62 79 74 65 2d 6f 72 64 65 72 20 6f  ive byte-order o
2bb20 66 20 74 68 65 20 68 6f 73 74 20 6d 61 63 68 69  f the host machi
2bb30 6e 65 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69  ne.  The.** sqli
2bb40 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
2bb50 62 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  be() and sqlite3
2bb60 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28  _value_text16le(
2bb70 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ) interfaces.** 
2bb80 65 78 74 72 61 63 74 20 55 54 46 31 36 20 73 74  extract UTF16 st
2bb90 72 69 6e 67 73 20 61 73 20 62 69 67 2d 65 6e 64  rings as big-end
2bba0 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65  ian and little-e
2bbb0 6e 64 69 61 6e 20 72 65 73 70 65 63 74 69 76 65  ndian respective
2bbc0 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ly..**.** The sq
2bbd0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65  lite3_value_nume
2bbe0 72 69 63 5f 74 79 70 65 28 29 20 69 6e 74 65 72  ric_type() inter
2bbf0 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f  face attempts to
2bc00 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69   apply.** numeri
2bc10 63 20 61 66 66 69 6e 69 74 79 20 74 6f 20 74 68  c affinity to th
2bc20 65 20 76 61 6c 75 65 2e 20 20 54 68 69 73 20 6d  e value.  This m
2bc30 65 61 6e 73 20 74 68 61 74 20 61 6e 20 61 74 74  eans that an att
2bc40 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65 20  empt is.** made 
2bc50 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76  to convert the v
2bc60 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74 65 67  alue to an integ
2bc70 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20 70  er or floating p
2bc80 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75 63  oint.  If.** suc
2bc90 68 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69  h a conversion i
2bca0 73 20 70 6f 73 73 69 62 6c 65 20 77 69 74 68 6f  s possible witho
2bcb0 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f 72  ut loss of infor
2bcc0 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65 72  mation (in other
2bcd0 0a 2a 2a 20 77 6f 72 64 73 20 69 66 20 74 68 65  .** words if the
2bce0 20 76 61 6c 75 65 20 69 73 20 61 20 73 74 72 69   value is a stri
2bcf0 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69  ng that looks li
2bd00 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20  ke a number).** 
2bd10 74 68 65 6e 20 74 68 65 20 63 6f 6e 76 65 72 73  then the convers
2bd20 69 6f 6e 20 69 73 20 64 6f 6e 65 2e 20 20 4f 74  ion is done.  Ot
2bd30 68 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65  herwise no conve
2bd40 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e 20 20 54  rsion occurs.  T
2bd50 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  he .** [SQLITE_I
2bd60 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70  NTEGER | datatyp
2bd70 65 5d 20 61 66 74 65 72 20 63 6f 6e 76 65 72 73  e] after convers
2bd80 69 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ion is returned.
2bd90 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61  .**.** Please pa
2bda0 79 20 70 61 72 74 69 63 75 6c 61 72 20 61 74 74  y particular att
2bdb0 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20 66 61  ention to the fa
2bdc0 63 74 20 74 68 61 74 20 74 68 65 20 70 6f 69 6e  ct that the poin
2bdd0 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 72  ter that.** is r
2bde0 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71  eturned from [sq
2bdf0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62  lite3_value_blob
2be00 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61  ()], [sqlite3_va
2be10 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a  lue_text()], or.
2be20 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ** [sqlite3_valu
2be30 65 5f 74 65 78 74 31 36 28 29 5d 20 63 61 6e 20  e_text16()] can 
2be40 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 20 62  be invalidated b
2be50 79 20 61 20 73 75 62 73 65 71 75 65 6e 74 20 63  y a subsequent c
2be60 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
2be70 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29  e3_value_bytes()
2be80 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
2be90 65 5f 62 79 74 65 73 31 36 28 29 5d 2c 20 5b 73  e_bytes16()], [s
2bea0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2beb0 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c  t()],.** or [sql
2bec0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
2bed0 36 28 29 5d 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68  6()].  .**.** Th
2bee0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73  ese routines mus
2bef0 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
2bf00 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
2bf10 20 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66   as.** the SQL f
2bf20 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 73 75 70  unction that sup
2bf30 70 6c 69 65 64 20 74 68 65 20 5b 73 71 6c 69 74  plied the [sqlit
2bf40 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d  e3_value*] param
2bf50 65 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 0a 2a 2a 20  eters..**.**.** 
2bf60 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
2bf70 2a 20 7b 46 31 35 31 30 33 7d 20 54 68 65 20 5b  * {F15103} The [
2bf80 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c  sqlite3_value_bl
2bf90 6f 62 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65  ob(V)] interface
2bfa0 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a   converts the.**
2bfb0 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65            [prote
2bfc0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2bfd0 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74  ue] object V int
2bfe0 6f 20 61 20 62 6c 6f 62 20 61 6e 64 20 74 68 65  o a blob and the
2bff0 6e 20 72 65 74 75 72 6e 73 20 61 0a 2a 2a 20 20  n returns a.**  
2c000 20 20 20 20 20 20 20 20 70 6f 69 6e 74 65 72 20          pointer 
2c010 74 6f 20 74 68 65 20 63 6f 6e 76 65 72 74 65 64  to the converted
2c020 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46   value..**.** {F
2c030 31 35 31 30 36 7d 20 54 68 65 20 5b 73 71 6c 69  15106} The [sqli
2c040 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28  te3_value_bytes(
2c050 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  V)] interface re
2c060 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20  turns the.**    
2c070 20 20 20 20 20 20 6e 75 6d 62 65 72 20 6f 66 20        number of 
2c080 62 79 74 65 73 20 69 6e 20 74 68 65 20 62 6c 6f  bytes in the blo
2c090 62 20 6f 72 20 73 74 72 69 6e 67 20 28 65 78 63  b or string (exc
2c0a0 6c 75 73 69 76 65 20 6f 66 20 74 68 65 0a 2a 2a  lusive of the.**
2c0b0 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 20 74            zero t
2c0c0 65 72 6d 69 6e 61 74 6f 72 20 6f 6e 20 74 68 65  erminator on the
2c0d0 20 73 74 72 69 6e 67 29 20 74 68 61 74 20 77 61   string) that wa
2c0e0 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  s returned by th
2c0f0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 6f  e.**          mo
2c100 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74  st recent call t
2c110 6f 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  o [sqlite3_value
2c120 5f 62 6c 6f 62 28 56 29 5d 20 6f 72 0a 2a 2a 20  _blob(V)] or.** 
2c130 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
2c140 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 56 29 5d  3_value_text(V)]
2c150 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31 30 39 7d  ..**.** {F15109}
2c160 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   The [sqlite3_va
2c170 6c 75 65 5f 62 79 74 65 73 31 36 28 56 29 5d 20  lue_bytes16(V)] 
2c180 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2c190 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
2c1a0 20 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65    number of byte
2c1b0 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 20  s in the string 
2c1c0 28 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68  (exclusive of th
2c1d0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65  e.**          ze
2c1e0 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 6f 6e  ro terminator on
2c1f0 20 74 68 65 20 73 74 72 69 6e 67 29 20 74 68 61   the string) tha
2c200 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 62  t was returned b
2c210 79 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  y the.**        
2c220 20 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61    most recent ca
2c230 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 76  ll to [sqlite3_v
2c240 61 6c 75 65 5f 74 65 78 74 31 36 28 56 29 5d 2c  alue_text16(V)],
2c250 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
2c260 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
2c270 31 36 62 65 28 56 29 5d 2c 20 6f 72 20 5b 73 71  16be(V)], or [sq
2c280 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
2c290 31 36 6c 65 28 56 29 5d 2e 0a 2a 2a 0a 2a 2a 20  16le(V)]..**.** 
2c2a0 7b 46 31 35 31 31 32 7d 20 54 68 65 20 5b 73 71  {F15112} The [sq
2c2b0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62  lite3_value_doub
2c2c0 6c 65 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65  le(V)] interface
2c2d0 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a   converts the.**
2c2e0 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65            [prote
2c2f0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2c300 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74  ue] object V int
2c310 6f 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  o a floating poi
2c320 6e 74 20 76 61 6c 75 65 20 61 6e 64 0a 2a 2a 20  nt value and.** 
2c330 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 73           returns
2c340 20 61 20 63 6f 70 79 20 6f 66 20 74 68 61 74 20   a copy of that 
2c350 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  value..**.** {F1
2c360 35 31 31 35 7d 20 54 68 65 20 5b 73 71 6c 69 74  5115} The [sqlit
2c370 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 56 29 5d  e3_value_int(V)]
2c380 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65   interface conve
2c390 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  rts the.**      
2c3a0 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73      [protected s
2c3b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
2c3c0 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20 36 34  ject V into a 64
2c3d0 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
2c3e0 67 65 72 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20  ger and.**      
2c3f0 20 20 20 20 72 65 74 75 72 6e 73 20 74 68 65 20      returns the 
2c400 6c 6f 77 65 72 20 33 32 20 62 69 74 73 20 6f 66  lower 32 bits of
2c410 20 74 68 61 74 20 69 6e 74 65 67 65 72 2e 0a 2a   that integer..*
2c420 2a 0a 2a 2a 20 7b 46 31 35 31 31 38 7d 20 54 68  *.** {F15118} Th
2c430 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
2c440 5f 69 6e 74 36 34 28 56 29 5d 20 69 6e 74 65 72  _int64(V)] inter
2c450 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68  face converts th
2c460 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  e.**          [p
2c470 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2c480 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56  _value] object V
2c490 20 69 6e 74 6f 20 61 20 36 34 2d 62 69 74 20 73   into a 64-bit s
2c4a0 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e  igned integer an
2c4b0 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  d.**          re
2c4c0 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 20  turns a copy of 
2c4d0 74 68 61 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a  that integer..**
2c4e0 0a 2a 2a 20 7b 46 31 35 31 32 31 7d 20 54 68 65  .** {F15121} The
2c4f0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2c500 74 65 78 74 28 56 29 5d 20 69 6e 74 65 72 66 61  text(V)] interfa
2c510 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a  ce converts the.
2c520 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f  **          [pro
2c530 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2c540 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69  alue] object V i
2c550 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69  nto a zero-termi
2c560 6e 61 74 65 64 20 55 54 46 2d 38 20 0a 2a 2a 20  nated UTF-8 .** 
2c570 20 20 20 20 20 20 20 20 20 73 74 72 69 6e 67 20           string 
2c580 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f  and returns a po
2c590 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20 73 74  inter to that st
2c5a0 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35  ring..**.** {F15
2c5b0 31 32 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  124} The [sqlite
2c5c0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 56  3_value_text16(V
2c5d0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e  )] interface con
2c5e0 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20  verts the.**    
2c5f0 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64        [protected
2c600 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
2c610 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20  object V into a 
2c620 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
2c630 32 2d 62 79 74 65 0a 2a 2a 20 20 20 20 20 20 20  2-byte.**       
2c640 20 20 20 61 6c 69 67 6e 65 64 20 55 54 46 2d 31     aligned UTF-1
2c650 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  6 native byte or
2c660 64 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  der.**          
2c670 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72  string and retur
2c680 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
2c690 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  that string..**.
2c6a0 2a 2a 20 7b 46 31 35 31 32 37 7d 20 54 68 65 20  ** {F15127} The 
2c6b0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
2c6c0 65 78 74 31 36 62 65 28 56 29 5d 20 69 6e 74 65  ext16be(V)] inte
2c6d0 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74  rface converts t
2c6e0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
2c6f0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2c700 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
2c710 56 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65  V into a zero-te
2c720 72 6d 69 6e 61 74 65 64 20 32 2d 62 79 74 65 0a  rminated 2-byte.
2c730 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c 69 67  **          alig
2c740 6e 65 64 20 55 54 46 2d 31 36 20 62 69 67 2d 65  ned UTF-16 big-e
2c750 6e 64 69 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20  ndian.**        
2c760 20 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74    string and ret
2c770 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
2c780 6f 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a  o that string..*
2c790 2a 0a 2a 2a 20 7b 46 31 35 31 33 30 7d 20 54 68  *.** {F15130} Th
2c7a0 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
2c7b0 5f 74 65 78 74 31 36 6c 65 28 56 29 5d 20 69 6e  _text16le(V)] in
2c7c0 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73  terface converts
2c7d0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
2c7e0 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
2c7f0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
2c800 74 20 56 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d  t V into a zero-
2c810 74 65 72 6d 69 6e 61 74 65 64 20 32 2d 62 79 74  terminated 2-byt
2c820 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c  e.**          al
2c830 69 67 6e 65 64 20 55 54 46 2d 31 36 20 6c 69 74  igned UTF-16 lit
2c840 74 6c 65 2d 65 6e 64 69 61 6e 0a 2a 2a 20 20 20  tle-endian.**   
2c850 20 20 20 20 20 20 20 73 74 72 69 6e 67 20 61 6e         string an
2c860 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  d returns a poin
2c870 74 65 72 20 74 6f 20 74 68 61 74 20 73 74 72 69  ter to that stri
2c880 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31 33  ng..**.** {F1513
2c890 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  3} The [sqlite3_
2c8a0 76 61 6c 75 65 5f 74 79 70 65 28 56 29 5d 20 69  value_type(V)] i
2c8b0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2c8c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 6e 65  .**          one
2c8d0 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c   of [SQLITE_NULL
2c8e0 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47  ], [SQLITE_INTEG
2c8f0 45 52 5d 2c 20 5b 53 51 4c 49 54 45 5f 46 4c 4f  ER], [SQLITE_FLO
2c900 41 54 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  AT],.**         
2c910 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20   [SQLITE_TEXT], 
2c920 6f 72 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d  or [SQLITE_BLOB]
2c930 20 61 73 20 61 70 70 72 6f 70 72 69 61 74 65 20   as appropriate 
2c940 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  for.**          
2c950 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  the [sqlite3_val
2c960 75 65 5d 20 6f 62 6a 65 63 74 20 56 2e 0a 2a 2a  ue] object V..**
2c970 0a 2a 2a 20 7b 46 31 35 31 33 36 7d 20 54 68 65  .** {F15136} The
2c980 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2c990 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 56 29 5d  numeric_type(V)]
2c9a0 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65   interface conve
2c9b0 72 74 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  rts.**          
2c9c0 74 68 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73  the [protected s
2c9d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
2c9e0 6a 65 63 74 20 56 20 69 6e 74 6f 20 65 69 74 68  ject V into eith
2c9f0 65 72 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72  er an integer or
2ca00 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 66  .**          a f
2ca10 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61  loating point va
2ca20 6c 75 65 20 69 66 20 69 74 20 63 61 6e 20 64 6f  lue if it can do
2ca30 20 73 6f 20 77 69 74 68 6f 75 74 20 6c 6f 73 73   so without loss
2ca40 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   of.**          
2ca50 69 6e 66 6f 72 6d 61 74 69 6f 6e 2c 20 61 6e 64  information, and
2ca60 20 72 65 74 75 72 6e 73 20 6f 6e 65 20 6f 66 20   returns one of 
2ca70 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2c 0a 2a  [SQLITE_NULL],.*
2ca80 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49  *          [SQLI
2ca90 54 45 5f 49 4e 54 45 47 45 52 5d 2c 20 5b 53 51  TE_INTEGER], [SQ
2caa0 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51  LITE_FLOAT], [SQ
2cab0 4c 49 54 45 5f 54 45 58 54 5d 2c 20 6f 72 0a 2a  LITE_TEXT], or.*
2cac0 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49  *          [SQLI
2cad0 54 45 5f 42 4c 4f 42 5d 20 61 73 20 61 70 70 72  TE_BLOB] as appr
2cae0 6f 70 72 69 61 74 65 20 66 6f 72 0a 2a 2a 20 20  opriate for.**  
2caf0 20 20 20 20 20 20 20 20 74 68 65 20 5b 70 72 6f          the [pro
2cb00 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2cb10 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 61  alue] object V a
2cb20 66 74 65 72 20 74 68 65 20 63 6f 6e 76 65 72 73  fter the convers
2cb30 69 6f 6e 20 61 74 74 65 6d 70 74 2e 0a 2a 2f 0a  ion attempt..*/.
2cb40 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
2cb50 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73  te3_value_blob(s
2cb60 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
2cb70 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
2cb80 65 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f  e_bytes(sqlite3_
2cb90 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
2cba0 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
2cbb0 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  16(sqlite3_value
2cbc0 2a 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74  *);.double sqlit
2cbd0 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28  e3_value_double(
2cbe0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
2cbf0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  .int sqlite3_val
2cc00 75 65 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 76  ue_int(sqlite3_v
2cc10 61 6c 75 65 2a 29 3b 0a 73 71 6c 69 74 65 33 5f  alue*);.sqlite3_
2cc20 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 76 61  int64 sqlite3_va
2cc30 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  lue_int64(sqlite
2cc40 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74  3_value*);.const
2cc50 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a   unsigned char *
2cc60 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
2cc70 78 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  xt(sqlite3_value
2cc80 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  *);.const void *
2cc90 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
2cca0 78 74 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c  xt16(sqlite3_val
2ccb0 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  ue*);.const void
2ccc0 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
2ccd0 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33  text16le(sqlite3
2cce0 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20  _value*);.const 
2ccf0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61  void *sqlite3_va
2cd00 6c 75 65 5f 74 65 78 74 31 36 62 65 28 73 71 6c  lue_text16be(sql
2cd10 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
2cd20 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
2cd30 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  type(sqlite3_val
2cd40 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ue*);.int sqlite
2cd50 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f  3_value_numeric_
2cd60 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  type(sqlite3_val
2cd70 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ue*);../*.** CAP
2cd80 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 67  I3REF: Obtain Ag
2cd90 67 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f 6e  gregate Function
2cda0 20 43 6f 6e 74 65 78 74 20 7b 46 31 36 32 31 30   Context {F16210
2cdb0 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6d 70 6c  }.**.** The impl
2cdc0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 67  ementation of ag
2cdd0 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63  gregate SQL func
2cde0 74 69 6f 6e 73 20 75 73 65 20 74 68 69 73 20 72  tions use this r
2cdf0 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61  outine to alloca
2ce00 74 65 0a 2a 2a 20 61 20 73 74 72 75 63 74 75 72  te.** a structur
2ce10 65 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68  e for storing th
2ce20 65 69 72 20 73 74 61 74 65 2e 20 20 0a 2a 2a 20  eir state.  .** 
2ce30 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 74  The first time t
2ce40 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  he sqlite3_aggre
2ce50 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 72  gate_context() r
2ce60 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20 69 73 20  outine is.** is 
2ce70 63 61 6c 6c 65 64 20 66 6f 72 20 61 20 70 61 72  called for a par
2ce80 74 69 63 75 6c 61 72 20 61 67 67 72 65 67 61 74  ticular aggregat
2ce90 65 2c 20 53 51 4c 69 74 65 20 61 6c 6c 6f 63 61  e, SQLite alloca
2cea0 74 65 73 20 6e 42 79 74 65 73 20 6f 66 20 6d 65  tes nBytes of me
2ceb0 6d 6f 72 79 0a 2a 2a 20 7a 65 72 6f 73 20 74 68  mory.** zeros th
2cec0 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72  at memory, and r
2ced0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
2cee0 20 74 6f 20 69 74 2e 0a 2a 2a 20 4f 6e 20 73 65   to it..** On se
2cef0 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75  cond and subsequ
2cf00 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  ent calls to sql
2cf10 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
2cf20 6f 6e 74 65 78 74 28 29 0a 2a 2a 20 66 6f 72 20  ontext().** for 
2cf30 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67 61  the same aggrega
2cf40 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 64 65  te function inde
2cf50 78 2c 20 74 68 65 20 73 61 6d 65 20 62 75 66 66  x, the same buff
2cf60 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  er is returned..
2cf70 2a 2a 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74  ** The implement
2cf80 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 74 68 65 20  ation.** of the 
2cf90 61 67 67 72 65 67 61 74 65 20 63 61 6e 20 75 73  aggregate can us
2cfa0 65 20 74 68 65 20 72 65 74 75 72 6e 65 64 20 62  e the returned b
2cfb0 75 66 66 65 72 20 74 6f 20 61 63 63 75 6d 75 6c  uffer to accumul
2cfc0 61 74 65 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20  ate data..**.** 
2cfd0 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63  SQLite automatic
2cfe0 61 6c 6c 79 20 66 72 65 65 73 20 74 68 65 20 61  ally frees the a
2cff0 6c 6c 6f 63 61 74 65 64 20 62 75 66 66 65 72 20  llocated buffer 
2d000 77 68 65 6e 20 74 68 65 20 61 67 67 72 65 67 61  when the aggrega
2d010 74 65 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6e 63  te.** query conc
2d020 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ludes..**.** The
2d030 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
2d040 20 73 68 6f 75 6c 64 20 62 65 20 61 20 63 6f 70   should be a cop
2d050 79 20 6f 66 20 74 68 65 20 0a 2a 2a 20 5b 73 71  y of the .** [sq
2d060 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20  lite3_context | 
2d070 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e  SQL function con
2d080 74 65 78 74 5d 20 74 68 61 74 20 69 73 20 74 68  text] that is th
2d090 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d  e first.** param
2d0a0 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c  eter to the call
2d0b0 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74 68 61  back routine tha
2d0c0 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65  t implements the
2d0d0 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 66 75   aggregate.** fu
2d0e0 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  nction..**.** Th
2d0f0 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20  is routine must 
2d100 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  be called from t
2d110 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69  he same thread i
2d120 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61  n which.** the a
2d130 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e  ggregate SQL fun
2d140 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
2d150 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
2d160 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32 31  TS:.**.** {F1621
2d170 31 7d 20 54 68 65 20 66 69 72 73 74 20 69 6e 76  1} The first inv
2d180 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69  ocation of [sqli
2d190 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
2d1a0 6e 74 65 78 74 28 43 2c 4e 29 5d 20 66 6f 72 0a  ntext(C,N)] for.
2d1b0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 70 61  **          a pa
2d1c0 72 74 69 63 75 6c 61 72 20 69 6e 73 74 61 6e 63  rticular instanc
2d1d0 65 20 6f 66 20 61 6e 20 61 67 67 72 65 67 61 74  e of an aggregat
2d1e0 65 20 66 75 6e 63 74 69 6f 6e 20 28 66 6f 72 20  e function (for 
2d1f0 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20  a particular.** 
2d200 20 20 20 20 20 20 20 20 20 63 6f 6e 74 65 78 74           context
2d210 20 43 29 20 63 61 75 73 65 73 20 53 51 4c 69 74   C) causes SQLit
2d220 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  e to allocation 
2d230 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72  N bytes of memor
2d240 79 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a  y,.**          z
2d250 65 72 6f 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c  ero that memory,
2d260 20 61 6e 64 20 72 65 74 75 72 6e 20 61 20 70 6f   and return a po
2d270 69 6e 74 65 72 20 74 6f 20 74 68 65 20 61 6c 6c  inter to the all
2d280 6f 63 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20  ocated.**       
2d290 20 20 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 0a 2a 2a     memory..**.**
2d2a0 20 7b 46 31 36 32 31 33 7d 20 49 66 20 61 20 6d   {F16213} If a m
2d2b0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
2d2c0 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75   error occurs du
2d2d0 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20  ring.**         
2d2e0 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67   [sqlite3_aggreg
2d2f0 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29  ate_context(C,N)
2d300 5d 20 74 68 65 6e 20 74 68 65 20 66 75 6e 63 74  ] then the funct
2d310 69 6f 6e 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a  ion returns 0..*
2d320 2a 0a 2a 2a 20 7b 46 31 36 32 31 35 7d 20 53 65  *.** {F16215} Se
2d330 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75  cond and subsequ
2d340 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20  ent invocations 
2d350 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  of.**          [
2d360 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
2d370 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 5d 20  e_context(C,N)] 
2d380 66 6f 72 20 74 68 65 20 73 61 6d 65 20 63 6f 6e  for the same con
2d390 74 65 78 74 20 70 6f 69 6e 74 65 72 20 43 0a 2a  text pointer C.*
2d3a0 2a 20 20 20 20 20 20 20 20 20 20 69 67 6e 6f 72  *          ignor
2d3b0 65 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65  e the N paramete
2d3c0 72 20 61 6e 64 20 72 65 74 75 72 6e 20 61 20 70  r and return a p
2d3d0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 73 61  ointer to the sa
2d3e0 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62  me.**          b
2d3f0 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 72  lock of memory r
2d400 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 66  eturned by the f
2d410 69 72 73 74 20 69 6e 76 6f 63 61 74 69 6f 6e 2e  irst invocation.
2d420 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32 31 37 7d 20  .**.** {F16217} 
2d430 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  The memory alloc
2d440 61 74 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  ated by [sqlite3
2d450 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
2d460 78 74 28 43 2c 4e 29 5d 20 69 73 0a 2a 2a 20 20  xt(C,N)] is.**  
2d470 20 20 20 20 20 20 20 20 61 75 74 6f 6d 61 74 69          automati
2d480 63 61 6c 6c 79 20 66 72 65 65 64 20 6f 6e 20 74  cally freed on t
2d490 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 20  he next call to 
2d4a0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2d4b0 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  ].**          or
2d4c0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2d4d0 7a 65 28 29 5d 20 66 6f 72 20 74 68 65 20 5b 70  ze()] for the [p
2d4e0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2d4f0 74 5d 20 63 6f 6e 74 61 69 6e 69 6e 67 0a 2a 2a  t] containing.**
2d500 20 20 20 20 20 20 20 20 20 20 74 68 65 20 61 67            the ag
2d510 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e  gregate function
2d520 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
2d530 20 63 6f 6e 74 65 78 74 20 43 2e 0a 2a 2f 0a 76   context C..*/.v
2d540 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 61 67 67  oid *sqlite3_agg
2d550 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 73  regate_context(s
2d560 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2d570 20 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f   int nBytes);../
2d580 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 55  *.** CAPI3REF: U
2d590 73 65 72 20 44 61 74 61 20 46 6f 72 20 46 75 6e  ser Data For Fun
2d5a0 63 74 69 6f 6e 73 20 7b 46 31 36 32 34 30 7d 0a  ctions {F16240}.
2d5b0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
2d5c0 33 5f 75 73 65 72 5f 64 61 74 61 28 29 20 69 6e  3_user_data() in
2d5d0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2d5e0 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65  a copy of.** the
2d5f0 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 77 61   pointer that wa
2d600 73 20 74 68 65 20 70 55 73 65 72 44 61 74 61 20  s the pUserData 
2d610 70 61 72 61 6d 65 74 65 72 20 28 74 68 65 20 35  parameter (the 5
2d620 74 68 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a  th parameter).**
2d630 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
2d640 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2d650 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69  ()].** and [sqli
2d660 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2d670 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65  ion16()] routine
2d680 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c  s that originall
2d690 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20  y.** registered 
2d6a0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
2d6b0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
2d6c0 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68  . {END}.**.** Th
2d6d0 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20  is routine must 
2d6e0 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  be called from t
2d6f0 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69  he same thread i
2d700 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61  n which.** the a
2d710 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2d720 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  ed function is r
2d730 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 4e  unning..**.** IN
2d740 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
2d750 7b 46 31 36 32 34 33 7d 20 54 68 65 20 5b 73 71  {F16243} The [sq
2d760 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
2d770 43 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  C)] interface re
2d780 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 20  turns a copy of 
2d790 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
2d7a0 50 20 70 6f 69 6e 74 65 72 20 66 72 6f 6d 20 74  P pointer from t
2d7b0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  he [sqlite3_crea
2d7c0 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c  te_function(D,X,
2d7d0 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 0a 2a 2a  N,E,P,F,S,L)].**
2d7e0 20 20 20 20 20 20 20 20 20 20 6f 72 20 5b 73 71            or [sq
2d7f0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2d800 63 74 69 6f 6e 31 36 28 44 2c 58 2c 4e 2c 45 2c  ction16(D,X,N,E,
2d810 50 2c 46 2c 53 2c 4c 29 5d 20 63 61 6c 6c 20 74  P,F,S,L)] call t
2d820 68 61 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  hat.**          
2d830 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20 53  registered the S
2d840 51 4c 20 66 75 6e 63 74 69 6f 6e 20 61 73 73 6f  QL function asso
2d850 63 69 61 74 65 64 20 77 69 74 68 20 0a 2a 2a 20  ciated with .** 
2d860 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
2d870 33 5f 63 6f 6e 74 65 78 74 5d 20 43 2e 0a 2a 2f  3_context] C..*/
2d880 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75  .void *sqlite3_u
2d890 73 65 72 5f 64 61 74 61 28 73 71 6c 69 74 65 33  ser_data(sqlite3
2d8a0 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a  _context*);../*.
2d8b0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74  ** CAPI3REF: Dat
2d8c0 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
2d8d0 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 20 7b   For Functions {
2d8e0 46 31 36 32 35 30 7d 0a 2a 2a 0a 2a 2a 20 54 68  F16250}.**.** Th
2d8f0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e sqlite3_contex
2d900 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20 69 6e  t_db_handle() in
2d910 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2d920 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65  a copy of.** the
2d930 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
2d940 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2d950 74 69 6f 6e 5d 20 28 74 68 65 20 31 73 74 20 70  tion] (the 1st p
2d960 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20  arameter).** of 
2d970 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  the [sqlite3_cre
2d980 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a  ate_function()].
2d990 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
2d9a0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
2d9b0 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68  6()] routines th
2d9c0 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a  at originally.**
2d9d0 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20   registered the 
2d9e0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69  application defi
2d9f0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  ned function..**
2da00 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
2da10 2a 2a 0a 2a 2a 20 7b 46 31 36 32 35 33 7d 20 54  **.** {F16253} T
2da20 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74  he [sqlite3_cont
2da30 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 43 29  ext_db_handle(C)
2da40 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
2da50 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  rns a copy of th
2da60 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 44 20  e.**          D 
2da70 70 6f 69 6e 74 65 72 20 66 72 6f 6d 20 74 68 65  pointer from the
2da80 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2da90 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c  _function(D,X,N,
2daa0 45 2c 50 2c 46 2c 53 2c 4c 29 5d 0a 2a 2a 20 20  E,P,F,S,L)].**  
2dab0 20 20 20 20 20 20 20 20 6f 72 20 5b 73 71 6c 69          or [sqli
2dac0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2dad0 69 6f 6e 31 36 28 44 2c 58 2c 4e 2c 45 2c 50 2c  ion16(D,X,N,E,P,
2dae0 46 2c 53 2c 4c 29 5d 20 63 61 6c 6c 20 74 68 61  F,S,L)] call tha
2daf0 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  t.**          re
2db00 67 69 73 74 65 72 65 64 20 74 68 65 20 53 51 4c  gistered the SQL
2db10 20 66 75 6e 63 74 69 6f 6e 20 61 73 73 6f 63 69   function associ
2db20 61 74 65 64 20 77 69 74 68 20 0a 2a 2a 20 20 20  ated with .**   
2db30 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
2db40 63 6f 6e 74 65 78 74 5d 20 43 2e 0a 2a 2f 0a 73  context] C..*/.s
2db50 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f  qlite3 *sqlite3_
2db60 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c  context_db_handl
2db70 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
2db80 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
2db90 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41  3REF: Function A
2dba0 75 78 69 6c 69 61 72 79 20 44 61 74 61 20 7b 46  uxiliary Data {F
2dbb0 31 36 32 37 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  16270}.**.** The
2dbc0 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 77 6f 20 66   following two f
2dbd0 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20  unctions may be 
2dbe0 75 73 65 64 20 62 79 20 73 63 61 6c 61 72 20 53  used by scalar S
2dbf0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 0a  QL functions to.
2dc00 2a 2a 20 61 73 73 6f 63 69 61 74 65 20 6d 65 74  ** associate met
2dc10 61 2d 64 61 74 61 20 77 69 74 68 20 61 72 67 75  a-data with argu
2dc20 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20 49 66 20  ment values. If 
2dc30 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65 20 69  the same value i
2dc40 73 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 6d  s passed to.** m
2dc50 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61 74 69  ultiple invocati
2dc60 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ons of the same 
2dc70 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64 75 72  SQL function dur
2dc80 69 6e 67 20 71 75 65 72 79 20 65 78 65 63 75 74  ing query execut
2dc90 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20 73 6f  ion, under.** so
2dca0 6d 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73  me circumstances
2dcb0 20 74 68 65 20 61 73 73 6f 63 69 61 74 65 64 20   the associated 
2dcc0 6d 65 74 61 2d 64 61 74 61 20 6d 61 79 20 62 65  meta-data may be
2dcd0 20 70 72 65 73 65 72 76 65 64 2e 20 54 68 69 73   preserved. This
2dce0 20 6d 61 79 0a 2a 2a 20 62 65 20 75 73 65 64 2c   may.** be used,
2dcf0 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74 6f   for example, to
2dd00 20 61 64 64 20 61 20 72 65 67 75 6c 61 72 2d 65   add a regular-e
2dd10 78 70 72 65 73 73 69 6f 6e 20 6d 61 74 63 68 69  xpression matchi
2dd20 6e 67 20 73 63 61 6c 61 72 0a 2a 2a 20 66 75 6e  ng scalar.** fun
2dd30 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70 69  ction. The compi
2dd40 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f 66 20 74  led version of t
2dd50 68 65 20 72 65 67 75 6c 61 72 20 65 78 70 72 65  he regular expre
2dd60 73 73 69 6f 6e 20 69 73 20 73 74 6f 72 65 64 20  ssion is stored 
2dd70 61 73 0a 2a 2a 20 6d 65 74 61 2d 64 61 74 61 20  as.** meta-data 
2dd80 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
2dd90 74 68 65 20 53 51 4c 20 76 61 6c 75 65 20 70 61  the SQL value pa
2dda0 73 73 65 64 20 61 73 20 74 68 65 20 72 65 67 75  ssed as the regu
2ddb0 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a  lar expression.*
2ddc0 2a 20 70 61 74 74 65 72 6e 2e 20 20 54 68 65 20  * pattern.  The 
2ddd0 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c 61 72  compiled regular
2dde0 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20   expression can 
2ddf0 62 65 20 72 65 75 73 65 64 20 6f 6e 20 6d 75 6c  be reused on mul
2de00 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 74  tiple.** invocat
2de10 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
2de20 20 66 75 6e 63 74 69 6f 6e 20 73 6f 20 74 68 61   function so tha
2de30 74 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 70  t the original p
2de40 61 74 74 65 72 6e 20 73 74 72 69 6e 67 0a 2a 2a  attern string.**
2de50 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
2de60 6f 20 62 65 20 72 65 63 6f 6d 70 69 6c 65 64 20  o be recompiled 
2de70 6f 6e 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69  on each invocati
2de80 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  on..**.** The sq
2de90 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
2dea0 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  a() interface re
2deb0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
2dec0 74 6f 20 74 68 65 20 6d 65 74 61 2d 64 61 74 61  to the meta-data
2ded0 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 62  .** associated b
2dee0 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65  y the sqlite3_se
2def0 74 5f 61 75 78 64 61 74 61 28 29 20 66 75 6e 63  t_auxdata() func
2df00 74 69 6f 6e 20 77 69 74 68 20 74 68 65 20 4e 74  tion with the Nt
2df10 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 61  h argument.** va
2df20 6c 75 65 20 74 6f 20 74 68 65 20 61 70 70 6c 69  lue to the appli
2df30 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
2df40 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 49 66 20 6e  unction..** If n
2df50 6f 20 6d 65 74 61 2d 64 61 74 61 20 68 61 73 20  o meta-data has 
2df60 62 65 65 6e 20 65 76 65 72 20 62 65 65 6e 20 73  been ever been s
2df70 65 74 20 66 6f 72 20 74 68 65 20 4e 74 68 0a 2a  et for the Nth.*
2df80 2a 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68  * argument of th
2df90 65 20 66 75 6e 63 74 69 6f 6e 2c 20 6f 72 20 69  e function, or i
2dfa0 66 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  f the correspond
2dfb0 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70 61 72  ing function par
2dfc0 61 6d 65 74 65 72 0a 2a 2a 20 68 61 73 20 63 68  ameter.** has ch
2dfd0 61 6e 67 65 64 20 73 69 6e 63 65 20 74 68 65 20  anged since the 
2dfe0 6d 65 74 61 2d 64 61 74 61 20 77 61 73 20 73 65  meta-data was se
2dff0 74 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  t, then sqlite3_
2e000 67 65 74 5f 61 75 78 64 61 74 61 28 29 0a 2a 2a  get_auxdata().**
2e010 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
2e020 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54  pointer..**.** T
2e030 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  he sqlite3_set_a
2e040 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61  uxdata() interfa
2e050 63 65 20 73 61 76 65 73 20 74 68 65 20 6d 65 74  ce saves the met
2e060 61 2d 64 61 74 61 0a 2a 2a 20 70 6f 69 6e 74 65  a-data.** pointe
2e070 64 20 74 6f 20 62 79 20 69 74 73 20 33 72 64 20  d to by its 3rd 
2e080 70 61 72 61 6d 65 74 65 72 20 61 73 20 74 68 65  parameter as the
2e090 20 6d 65 74 61 2d 64 61 74 61 20 66 6f 72 20 74   meta-data for t
2e0a0 68 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d  he N-th.** argum
2e0b0 65 6e 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69  ent of the appli
2e0c0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
2e0d0 75 6e 63 74 69 6f 6e 2e 20 20 53 75 62 73 65 71  unction.  Subseq
2e0e0 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f  uent.** calls to
2e0f0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78   sqlite3_get_aux
2e100 64 61 74 61 28 29 20 6d 69 67 68 74 20 72 65 74  data() might ret
2e110 75 72 6e 20 74 68 69 73 20 64 61 74 61 2c 20 69  urn this data, i
2e120 66 20 69 74 20 68 61 73 0a 2a 2a 20 6e 6f 74 20  f it has.** not 
2e130 62 65 65 6e 20 64 65 73 74 72 6f 79 65 64 2e 20  been destroyed. 
2e140 0a 2a 2a 20 49 66 20 69 74 20 69 73 20 6e 6f 74  .** If it is not
2e150 20 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69   NULL, SQLite wi
2e160 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65  ll invoke the de
2e170 73 74 72 75 63 74 6f 72 20 0a 2a 2a 20 66 75 6e  structor .** fun
2e180 63 74 69 6f 6e 20 67 69 76 65 6e 20 62 79 20 74  ction given by t
2e190 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
2e1a0 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f   to sqlite3_set_
2e1b0 61 75 78 64 61 74 61 28 29 20 6f 6e 0a 2a 2a 20  auxdata() on.** 
2e1c0 74 68 65 20 6d 65 74 61 2d 64 61 74 61 20 77 68  the meta-data wh
2e1d0 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  en the correspon
2e1e0 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70 61  ding function pa
2e1f0 72 61 6d 65 74 65 72 20 63 68 61 6e 67 65 73 0a  rameter changes.
2e200 2a 2a 20 6f 72 20 77 68 65 6e 20 74 68 65 20 53  ** or when the S
2e210 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d  QL statement com
2e220 70 6c 65 74 65 73 2c 20 77 68 69 63 68 65 76 65  pletes, whicheve
2e230 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 0a 2a  r comes first..*
2e240 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73 20 66  *.** SQLite is f
2e250 72 65 65 20 74 6f 20 63 61 6c 6c 20 74 68 65 20  ree to call the 
2e260 64 65 73 74 72 75 63 74 6f 72 20 61 6e 64 20 64  destructor and d
2e270 72 6f 70 20 6d 65 74 61 2d 64 61 74 61 20 6f 6e  rop meta-data on
2e280 0a 2a 2a 20 61 6e 79 20 70 61 72 61 6d 65 74 65  .** any paramete
2e290 72 20 6f 66 20 61 6e 79 20 66 75 6e 63 74 69 6f  r of any functio
2e2a0 6e 20 61 74 20 61 6e 79 20 74 69 6d 65 2e 20 20  n at any time.  
2e2b0 54 68 65 20 6f 6e 6c 79 20 67 75 61 72 61 6e 74  The only guarant
2e2c0 65 65 0a 2a 2a 20 69 73 20 74 68 61 74 20 74 68  ee.** is that th
2e2d0 65 20 64 65 73 74 72 75 63 74 6f 72 20 77 69 6c  e destructor wil
2e2e0 6c 20 62 65 20 63 61 6c 6c 65 64 20 62 65 66 6f  l be called befo
2e2f0 72 65 20 74 68 65 20 6d 65 74 61 64 61 74 61 20  re the metadata 
2e300 69 73 0a 2a 2a 20 64 72 6f 70 70 65 64 2e 0a 2a  is.** dropped..*
2e310 2a 0a 2a 2a 20 49 6e 20 70 72 61 63 74 69 63 65  *.** In practice
2e320 2c 20 6d 65 74 61 2d 64 61 74 61 20 69 73 20 70  , meta-data is p
2e330 72 65 73 65 72 76 65 64 20 62 65 74 77 65 65 6e  reserved between
2e340 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20   function calls 
2e350 66 6f 72 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f  for.** expressio
2e360 6e 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 73  ns that are cons
2e370 74 61 6e 74 20 61 74 20 63 6f 6d 70 69 6c 65 20  tant at compile 
2e380 74 69 6d 65 2e 20 54 68 69 73 20 69 6e 63 6c 75  time. This inclu
2e390 64 65 73 20 6c 69 74 65 72 61 6c 0a 2a 2a 20 76  des literal.** v
2e3a0 61 6c 75 65 73 20 61 6e 64 20 53 51 4c 20 76 61  alues and SQL va
2e3b0 72 69 61 62 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  riables..**.** T
2e3c0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75  hese routines mu
2e3d0 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f  st be called fro
2e3e0 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  m the same threa
2e3f0 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68  d in which.** th
2e400 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  e SQL function i
2e410 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a  s running..**.**
2e420 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
2e430 2a 2a 20 7b 46 31 36 32 37 32 7d 20 54 68 65 20  ** {F16272} The 
2e440 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78  [sqlite3_get_aux
2e450 64 61 74 61 28 43 2c 4e 29 5d 20 69 6e 74 65 72  data(C,N)] inter
2e460 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70  face returns a p
2e470 6f 69 6e 74 65 72 0a 2a 2a 20 20 20 20 20 20 20  ointer.**       
2e480 20 20 20 74 6f 20 6d 65 74 61 64 61 74 61 20 61     to metadata a
2e490 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
2e4a0 68 65 20 4e 74 68 20 70 61 72 61 6d 65 74 65 72  he Nth parameter
2e4b0 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63   of the SQL func
2e4c0 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  tion.**         
2e4d0 20 77 68 6f 73 65 20 63 6f 6e 74 65 78 74 20 69   whose context i
2e4e0 73 20 43 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20  s C, or NULL if 
2e4f0 74 68 65 72 65 20 69 73 20 6e 6f 20 6d 65 74 61  there is no meta
2e500 64 61 74 61 20 61 73 73 6f 63 69 61 74 65 64 0a  data associated.
2e510 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69 74 68  **          with
2e520 20 74 68 61 74 20 70 61 72 61 6d 65 74 65 72 2e   that parameter.
2e530 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32 37 34 7d 20  .**.** {F16274} 
2e540 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  The [sqlite3_set
2e550 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 44  _auxdata(C,N,P,D
2e560 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61 73 73  )] interface ass
2e570 69 67 6e 73 20 61 20 6d 65 74 61 64 61 74 61 0a  igns a metadata.
2e580 2a 2a 20 20 20 20 20 20 20 20 20 20 70 6f 69 6e  **          poin
2e590 74 65 72 20 50 20 74 6f 20 74 68 65 20 4e 74 68  ter P to the Nth
2e5a0 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68   parameter of th
2e5b0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 77  e SQL function w
2e5c0 69 74 68 20 63 6f 6e 74 65 78 74 0a 2a 2a 20 20  ith context.**  
2e5d0 20 20 20 20 20 20 20 20 43 2e 0a 2a 2a 0a 2a 2a          C..**.**
2e5e0 20 7b 46 31 36 32 37 36 7d 20 53 51 4c 69 74 65   {F16276} SQLite
2e5f0 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65   will invoke the
2e600 20 64 65 73 74 72 75 63 74 6f 72 20 44 20 77 69   destructor D wi
2e610 74 68 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  th a single argu
2e620 6d 65 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20 20  ment.**         
2e630 20 77 68 69 63 68 20 69 73 20 74 68 65 20 6d 65   which is the me
2e640 74 61 64 61 74 61 20 70 6f 69 6e 74 65 72 20 50  tadata pointer P
2e650 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c   following a cal
2e660 6c 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20  l to.**         
2e670 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
2e680 78 64 61 74 61 28 43 2c 4e 2c 50 2c 44 29 5d 20  xdata(C,N,P,D)] 
2e690 77 68 65 6e 20 53 51 4c 69 74 65 20 63 65 61 73  when SQLite ceas
2e6a0 65 73 20 74 6f 20 68 6f 6c 64 0a 2a 2a 20 20 20  es to hold.**   
2e6b0 20 20 20 20 20 20 20 74 68 65 20 6d 65 74 61 64         the metad
2e6c0 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32  ata..**.** {F162
2e6d0 37 37 7d 20 53 51 4c 69 74 65 20 63 65 61 73 65  77} SQLite cease
2e6e0 73 20 74 6f 20 68 6f 6c 64 20 6d 65 74 61 64 61  s to hold metada
2e6f0 74 61 20 66 6f 72 20 61 6e 20 53 51 4c 20 66 75  ta for an SQL fu
2e700 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72  nction parameter
2e710 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68 65  .**          whe
2e720 6e 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  n the value of t
2e730 68 61 74 20 70 61 72 61 6d 65 74 65 72 20 63 68  hat parameter ch
2e740 61 6e 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  anges..**.** {F1
2e750 36 32 37 38 7d 20 57 68 65 6e 20 5b 73 71 6c 69  6278} When [sqli
2e760 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
2e770 43 2c 4e 2c 50 2c 44 29 5d 20 69 73 20 69 6e 76  C,N,P,D)] is inv
2e780 6f 6b 65 64 2c 20 74 68 65 20 64 65 73 74 72 75  oked, the destru
2e790 63 74 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  ctor.**         
2e7a0 20 69 73 20 63 61 6c 6c 65 64 20 66 6f 72 20 61   is called for a
2e7b0 6e 79 20 70 72 69 6f 72 20 6d 65 74 61 64 61 74  ny prior metadat
2e7c0 61 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  a associated wit
2e7d0 68 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74  h the same funct
2e7e0 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ion.**          
2e7f0 63 6f 6e 74 65 78 74 20 43 20 61 6e 64 20 70 61  context C and pa
2e800 72 61 6d 65 74 65 72 20 4e 2e 0a 2a 2a 0a 2a 2a  rameter N..**.**
2e810 20 7b 46 31 36 32 37 39 7d 20 53 51 4c 69 74 65   {F16279} SQLite
2e820 20 77 69 6c 6c 20 63 61 6c 6c 20 64 65 73 74 72   will call destr
2e830 75 63 74 6f 72 73 20 66 6f 72 20 61 6e 79 20 6d  uctors for any m
2e840 65 74 61 64 61 74 61 20 69 74 20 69 73 20 68 6f  etadata it is ho
2e850 6c 64 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20  lding.**        
2e860 20 20 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61    in a particula
2e870 72 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  r [prepared stat
2e880 65 6d 65 6e 74 5d 20 53 20 77 68 65 6e 20 65 69  ement] S when ei
2e890 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  ther.**         
2e8a0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2e8b0 53 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  S)] or [sqlite3_
2e8c0 66 69 6e 61 6c 69 7a 65 28 53 29 5d 20 69 73 20  finalize(S)] is 
2e8d0 63 61 6c 6c 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20  called..*/.void 
2e8e0 2a 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78  *sqlite3_get_aux
2e8f0 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e  data(sqlite3_con
2e900 74 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 76  text*, int N);.v
2e910 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  oid sqlite3_set_
2e920 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f  auxdata(sqlite3_
2e930 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 2c  context*, int N,
2e940 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29   void*, void (*)
2e950 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a  (void*));.../*.*
2e960 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 73  * CAPI3REF: Cons
2e970 74 61 6e 74 73 20 44 65 66 69 6e 69 6e 67 20 53  tants Defining S
2e980 70 65 63 69 61 6c 20 44 65 73 74 72 75 63 74 6f  pecial Destructo
2e990 72 20 42 65 68 61 76 69 6f 72 20 7b 46 31 30 32  r Behavior {F102
2e9a0 38 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  80}.**.** These 
2e9b0 61 72 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75  are special valu
2e9c0 65 20 66 6f 72 20 74 68 65 20 64 65 73 74 72 75  e for the destru
2e9d0 63 74 6f 72 20 74 68 61 74 20 69 73 20 70 61 73  ctor that is pas
2e9e0 73 65 64 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a  sed in as the.**
2e9f0 20 66 69 6e 61 6c 20 61 72 67 75 6d 65 6e 74 20   final argument 
2ea00 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65  to routines like
2ea10 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
2ea20 5f 62 6c 6f 62 28 29 5d 2e 20 20 49 66 20 74 68  _blob()].  If th
2ea30 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20  e destructor.** 
2ea40 61 72 67 75 6d 65 6e 74 20 69 73 20 53 51 4c 49  argument is SQLI
2ea50 54 45 5f 53 54 41 54 49 43 2c 20 69 74 20 6d 65  TE_STATIC, it me
2ea60 61 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e  ans that the con
2ea70 74 65 6e 74 20 70 6f 69 6e 74 65 72 20 69 73 20  tent pointer is 
2ea80 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20  constant.** and 
2ea90 77 69 6c 6c 20 6e 65 76 65 72 20 63 68 61 6e 67  will never chang
2eaa0 65 2e 20 20 49 74 20 64 6f 65 73 20 6e 6f 74 20  e.  It does not 
2eab0 6e 65 65 64 20 74 6f 20 62 65 20 64 65 73 74 72  need to be destr
2eac0 6f 79 65 64 2e 20 20 54 68 65 20 0a 2a 2a 20 53  oyed.  The .** S
2ead0 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20  QLITE_TRANSIENT 
2eae0 76 61 6c 75 65 20 6d 65 61 6e 73 20 74 68 61 74  value means that
2eaf0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c   the content wil
2eb00 6c 20 6c 69 6b 65 6c 79 20 63 68 61 6e 67 65 20  l likely change 
2eb10 69 6e 0a 2a 2a 20 74 68 65 20 6e 65 61 72 20 66  in.** the near f
2eb20 75 74 75 72 65 20 61 6e 64 20 74 68 61 74 20 53  uture and that S
2eb30 51 4c 69 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b  QLite should mak
2eb40 65 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74  e its own privat
2eb50 65 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65  e copy of.** the
2eb60 20 63 6f 6e 74 65 6e 74 20 62 65 66 6f 72 65 20   content before 
2eb70 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a  returning..**.**
2eb80 20 54 68 65 20 74 79 70 65 64 65 66 20 69 73 20   The typedef is 
2eb90 6e 65 63 65 73 73 61 72 79 20 74 6f 20 77 6f 72  necessary to wor
2eba0 6b 20 61 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d  k around problem
2ebb0 73 20 69 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20  s in certain.** 
2ebc0 43 2b 2b 20 63 6f 6d 70 69 6c 65 72 73 2e 20 20  C++ compilers.  
2ebd0 53 65 65 20 74 69 63 6b 65 74 20 23 32 31 39 31  See ticket #2191
2ebe0 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 76 6f 69  ..*/.typedef voi
2ebf0 64 20 28 2a 73 71 6c 69 74 65 33 5f 64 65 73 74  d (*sqlite3_dest
2ec00 72 75 63 74 6f 72 5f 74 79 70 65 29 28 76 6f 69  ructor_type)(voi
2ec10 64 2a 29 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c  d*);.#define SQL
2ec20 49 54 45 5f 53 54 41 54 49 43 20 20 20 20 20 20  ITE_STATIC      
2ec30 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75  ((sqlite3_destru
2ec40 63 74 6f 72 5f 74 79 70 65 29 30 29 0a 23 64 65  ctor_type)0).#de
2ec50 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e  fine SQLITE_TRAN
2ec60 53 49 45 4e 54 20 20 20 28 28 73 71 6c 69 74 65  SIENT   ((sqlite
2ec70 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70  3_destructor_typ
2ec80 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e)-1)../*.** CAP
2ec90 49 33 52 45 46 3a 20 53 65 74 74 69 6e 67 20 54  I3REF: Setting T
2eca0 68 65 20 52 65 73 75 6c 74 20 4f 66 20 41 6e 20  he Result Of An 
2ecb0 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 7b 46 31  SQL Function {F1
2ecc0 36 34 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  6400}.**.** Thes
2ecd0 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75  e routines are u
2ece0 73 65 64 20 62 79 20 74 68 65 20 78 46 75 6e 63  sed by the xFunc
2ecf0 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62   or xFinal callb
2ed00 61 63 6b 73 20 74 68 61 74 0a 2a 2a 20 69 6d 70  acks that.** imp
2ed10 6c 65 6d 65 6e 74 20 53 51 4c 20 66 75 6e 63 74  lement SQL funct
2ed20 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61  ions and aggrega
2ed30 74 65 73 2e 20 20 53 65 65 0a 2a 2a 20 5b 73 71  tes.  See.** [sq
2ed40 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2ed50 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  ction()] and [sq
2ed60 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2ed70 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f  ction16()].** fo
2ed80 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66  r additional inf
2ed90 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
2eda0 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
2edb0 77 6f 72 6b 20 76 65 72 79 20 6d 75 63 68 20 6c  work very much l
2edc0 69 6b 65 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c  ike the .** [sql
2edd0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c  ite3_bind_blob |
2ede0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 5d   sqlite3_bind_*]
2edf0 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74   family of funct
2ee00 69 6f 6e 73 20 75 73 65 64 0a 2a 2a 20 74 6f 20  ions used.** to 
2ee10 62 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 68  bind values to h
2ee20 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 69  ost parameters i
2ee30 6e 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  n prepared state
2ee40 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20  ments..** Refer 
2ee50 74 6f 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  to the.** [sqlit
2ee60 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73  e3_bind_blob | s
2ee70 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 64 6f  qlite3_bind_* do
2ee80 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72  cumentation] for
2ee90 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 69  .** additional i
2eea0 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
2eeb0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
2eec0 73 75 6c 74 5f 62 6c 6f 62 28 29 20 69 6e 74 65  sult_blob() inte
2eed0 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
2eee0 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e  esult from.** an
2eef0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66   application def
2ef00 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
2ef10 20 62 65 20 74 68 65 20 42 4c 4f 42 20 77 68 6f   be the BLOB who
2ef20 73 65 20 63 6f 6e 74 65 6e 74 20 69 73 20 70 6f  se content is po
2ef30 69 6e 74 65 64 0a 2a 2a 20 74 6f 20 62 79 20 74  inted.** to by t
2ef40 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
2ef50 74 65 72 20 61 6e 64 20 77 68 69 63 68 20 69 73  ter and which is
2ef60 20 4e 20 62 79 74 65 73 20 6c 6f 6e 67 20 77 68   N bytes long wh
2ef70 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20  ere N is the.** 
2ef80 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e  third parameter.
2ef90 20 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33   .** The sqlite3
2efa0 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62  _result_zeroblob
2efb0 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 73 65  () interfaces se
2efc0 74 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a  t the result of.
2efd0 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
2efe0 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on defined funct
2eff0 69 6f 6e 20 74 6f 20 62 65 20 61 20 42 4c 4f 42  ion to be a BLOB
2f000 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61 6c 6c 20   containing all 
2f010 7a 65 72 6f 0a 2a 2a 20 62 79 74 65 73 20 61 6e  zero.** bytes an
2f020 64 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  d N bytes in siz
2f030 65 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  e, where N is th
2f040 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 32  e value of the 2
2f050 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  nd parameter..**
2f060 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
2f070 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 29 20  result_double() 
2f080 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
2f090 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a  he result from.*
2f0a0 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  * an application
2f0b0 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f   defined functio
2f0c0 6e 20 74 6f 20 62 65 20 61 20 66 6c 6f 61 74 69  n to be a floati
2f0d0 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 73  ng point value s
2f0e0 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 69  pecified.** by i
2f0f0 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e  ts 2nd argument.
2f100 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
2f110 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
2f120 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65  ) and sqlite3_re
2f130 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 66  sult_error16() f
2f140 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63 61 75 73  unctions.** caus
2f150 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 65  e the implemente
2f160 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74  d SQL function t
2f170 6f 20 74 68 72 6f 77 20 61 6e 20 65 78 63 65 70  o throw an excep
2f180 74 69 6f 6e 2e 0a 2a 2a 20 53 51 4c 69 74 65 20  tion..** SQLite 
2f190 75 73 65 73 20 74 68 65 20 73 74 72 69 6e 67 20  uses the string 
2f1a0 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68  pointed to by th
2f1b0 65 0a 2a 2a 20 32 6e 64 20 70 61 72 61 6d 65 74  e.** 2nd paramet
2f1c0 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 72 65  er of sqlite3_re
2f1d0 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 20  sult_error() or 
2f1e0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
2f1f0 72 72 6f 72 31 36 28 29 0a 2a 2a 20 61 73 20 74  rror16().** as t
2f200 68 65 20 74 65 78 74 20 6f 66 20 61 6e 20 65 72  he text of an er
2f210 72 6f 72 20 6d 65 73 73 61 67 65 2e 20 20 53 51  ror message.  SQ
2f220 4c 69 74 65 20 69 6e 74 65 72 70 72 65 74 73 20  Lite interprets 
2f230 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73  the error.** mes
2f240 73 61 67 65 20 73 74 72 69 6e 67 20 66 72 6f 6d  sage string from
2f250 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2f260 65 72 72 6f 72 28 29 20 61 73 20 55 54 46 38 2e  error() as UTF8.
2f270 20 53 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72   SQLite.** inter
2f280 70 72 65 74 73 20 74 68 65 20 73 74 72 69 6e 67  prets the string
2f290 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65   from sqlite3_re
2f2a0 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 61  sult_error16() a
2f2b0 73 20 55 54 46 31 36 20 69 6e 20 6e 61 74 69 76  s UTF16 in nativ
2f2c0 65 0a 2a 2a 20 62 79 74 65 20 6f 72 64 65 72 2e  e.** byte order.
2f2d0 20 20 49 66 20 74 68 65 20 74 68 69 72 64 20 70    If the third p
2f2e0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
2f2f0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
2f300 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  ().** or sqlite3
2f310 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
2f320 29 20 69 73 20 6e 65 67 61 74 69 76 65 20 74 68  ) is negative th
2f330 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20  en SQLite takes 
2f340 61 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20  as the error.** 
2f350 6d 65 73 73 61 67 65 20 61 6c 6c 20 74 65 78 74  message all text
2f360 20 75 70 20 74 68 72 6f 75 67 68 20 74 68 65 20   up through the 
2f370 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61  first zero chara
2f380 63 74 65 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20  cter..** If the 
2f390 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
2f3a0 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  to sqlite3_resul
2f3b0 74 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20  t_error() or.** 
2f3c0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
2f3d0 72 72 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d  rror16() is non-
2f3e0 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 51  negative then SQ
2f3f0 4c 69 74 65 20 74 61 6b 65 73 20 74 68 61 74 20  Lite takes that 
2f400 6d 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e  many.** bytes (n
2f410 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20 66  ot characters) f
2f420 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61  rom the 2nd para
2f430 6d 65 74 65 72 20 61 73 20 74 68 65 20 65 72 72  meter as the err
2f440 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 54  or message..** T
2f450 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
2f460 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71  t_error() and sq
2f470 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
2f480 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  or16().** routin
2f490 65 73 20 6d 61 6b 65 20 61 20 63 6f 70 79 20 70  es make a copy p
2f4a0 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74  rivate copy of t
2f4b0 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
2f4c0 20 74 65 78 74 20 62 65 66 6f 72 65 0a 2a 2a 20   text before.** 
2f4d0 74 68 65 79 20 72 65 74 75 72 6e 2e 20 20 48 65  they return.  He
2f4e0 6e 63 65 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67  nce, the calling
2f4f0 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 64 65   function can de
2f500 61 6c 6c 6f 63 61 74 65 20 6f 72 0a 2a 2a 20 6d  allocate or.** m
2f510 6f 64 69 66 79 20 74 68 65 20 74 65 78 74 20 61  odify the text a
2f520 66 74 65 72 20 74 68 65 79 20 72 65 74 75 72 6e  fter they return
2f530 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a   without harm..*
2f540 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
2f550 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28  sult_error_code(
2f560 29 20 66 75 6e 63 74 69 6f 6e 20 63 68 61 6e 67  ) function chang
2f570 65 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64  es the error cod
2f580 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79  e.** returned by
2f590 20 53 51 4c 69 74 65 20 61 73 20 61 20 72 65 73   SQLite as a res
2f5a0 75 6c 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20  ult of an error 
2f5b0 69 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 20 20  in a function.  
2f5c0 42 79 20 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74  By default,.** t
2f5d0 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73  he error code is
2f5e0 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20   SQLITE_ERROR.  
2f5f0 41 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  A subsequent cal
2f600 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73  l to sqlite3_res
2f610 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f  ult_error().** o
2f620 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
2f630 5f 65 72 72 6f 72 31 36 28 29 20 72 65 73 65 74  _error16() reset
2f640 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65  s the error code
2f650 20 74 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f 52   to SQLITE_ERROR
2f660 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
2f670 74 65 33 5f 72 65 73 75 6c 74 5f 74 6f 6f 62 69  te3_result_toobi
2f680 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61  g() interface ca
2f690 75 73 65 73 20 53 51 4c 69 74 65 0a 2a 2a 20 74  uses SQLite.** t
2f6a0 6f 20 74 68 72 6f 77 20 61 6e 20 65 72 72 6f 72  o throw an error
2f6b0 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74   indicating that
2f6c0 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f   a string or BLO
2f6d0 42 20 69 73 20 74 6f 20 6c 6f 6e 67 0a 2a 2a 20  B is to long.** 
2f6e0 74 6f 20 72 65 70 72 65 73 65 6e 74 2e 20 20 54  to represent.  T
2f6f0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
2f700 74 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65 72 66  t_nomem() interf
2f710 61 63 65 0a 2a 2a 20 63 61 75 73 65 73 20 53 51  ace.** causes SQ
2f720 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e  Lite to throw an
2f730 20 65 78 63 65 70 74 69 6f 6e 20 69 6e 64 69 63   exception indic
2f740 61 74 69 6e 67 20 74 68 61 74 20 74 68 65 20 61  ating that the a
2f750 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
2f760 61 74 69 6f 6e 20 66 61 69 6c 65 64 2e 0a 2a 2a  ation failed..**
2f770 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
2f780 72 65 73 75 6c 74 5f 69 6e 74 28 29 20 69 6e 74  result_int() int
2f790 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
2f7a0 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20  return value.** 
2f7b0 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
2f7c0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
2f7d0 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 33 32  ion to be the 32
2f7e0 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
2f7f0 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76  ger.** value giv
2f800 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72  en in the 2nd ar
2f810 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 73  gument..** The s
2f820 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
2f830 74 36 34 28 29 20 69 6e 74 65 72 66 61 63 65 20  t64() interface 
2f840 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20  sets the return 
2f850 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20  value.** of the 
2f860 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2f870 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
2f880 62 65 20 74 68 65 20 36 34 2d 62 69 74 20 73 69  be the 64-bit si
2f890 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20  gned integer.** 
2f8a0 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74  value given in t
2f8b0 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e  he 2nd argument.
2f8c0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
2f8d0 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 29  e3_result_null()
2f8e0 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
2f8f0 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
2f900 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69  .** of the appli
2f910 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
2f920 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 4e 55  unction to be NU
2f930 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  LL..**.** The sq
2f940 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
2f950 74 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 73  t(), sqlite3_res
2f960 75 6c 74 5f 74 65 78 74 31 36 28 29 2c 20 0a 2a  ult_text16(), .*
2f970 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  * sqlite3_result
2f980 5f 74 65 78 74 31 36 6c 65 28 29 2c 20 61 6e 64  _text16le(), and
2f990 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2f9a0 74 65 78 74 31 36 62 65 28 29 20 69 6e 74 65 72  text16be() inter
2f9b0 66 61 63 65 73 0a 2a 2a 20 73 65 74 20 74 68 65  faces.** set the
2f9c0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
2f9d0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
2f9e0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
2f9f0 6e 20 74 6f 20 62 65 0a 2a 2a 20 61 20 74 65 78  n to be.** a tex
2fa00 74 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69  t string which i
2fa10 73 20 72 65 70 72 65 73 65 6e 74 65 64 20 61 73  s represented as
2fa20 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 20 6e   UTF-8, UTF-16 n
2fa30 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
2fa40 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 74  ,.** UTF-16 litt
2fa50 6c 65 20 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54  le endian, or UT
2fa60 46 2d 31 36 20 62 69 67 20 65 6e 64 69 61 6e 2c  F-16 big endian,
2fa70 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a   respectively..*
2fa80 2a 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74  * SQLite takes t
2fa90 68 65 20 74 65 78 74 20 72 65 73 75 6c 74 20 66  he text result f
2faa0 72 6f 6d 20 74 68 65 20 61 70 70 6c 69 63 61 74  rom the applicat
2fab0 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20  ion from.** the 
2fac0 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66  2nd parameter of
2fad0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
2fae0 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
2faf0 61 63 65 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20  aces..** If the 
2fb00 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
2fb10 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
2fb20 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
2fb30 61 63 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74  aces.** is negat
2fb40 69 76 65 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ive, then SQLite
2fb50 20 74 61 6b 65 73 20 72 65 73 75 6c 74 20 74 65   takes result te
2fb60 78 74 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20  xt from the 2nd 
2fb70 70 61 72 61 6d 65 74 65 72 20 0a 2a 2a 20 74 68  parameter .** th
2fb80 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20  rough the first 
2fb90 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a  zero character..
2fba0 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 70 61  ** If the 3rd pa
2fbb0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
2fbc0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
2fbd0 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  xt* interfaces.*
2fbe0 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  * is non-negativ
2fbf0 65 2c 20 74 68 65 6e 20 61 73 20 6d 61 6e 79 20  e, then as many 
2fc00 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61  bytes (not chara
2fc10 63 74 65 72 73 29 20 6f 66 20 74 68 65 20 74 65  cters) of the te
2fc20 78 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f  xt.** pointed to
2fc30 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61   by the 2nd para
2fc40 6d 65 74 65 72 20 61 72 65 20 74 61 6b 65 6e 20  meter are taken 
2fc50 61 73 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  as the applicati
2fc60 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75  on-defined.** fu
2fc70 6e 63 74 69 6f 6e 20 72 65 73 75 6c 74 2e 0a 2a  nction result..*
2fc80 2a 20 49 66 20 74 68 65 20 34 74 68 20 70 61 72  * If the 4th par
2fc90 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
2fca0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
2fcb0 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  t* interfaces.**
2fcc0 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
2fcd0 6c 74 5f 62 6c 6f 62 20 69 73 20 61 20 6e 6f 6e  lt_blob is a non
2fce0 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74  -NULL pointer, t
2fcf0 68 65 6e 20 53 51 4c 69 74 65 20 63 61 6c 6c 73  hen SQLite calls
2fd00 20 74 68 61 74 0a 2a 2a 20 66 75 6e 63 74 69 6f   that.** functio
2fd10 6e 20 61 73 20 74 68 65 20 64 65 73 74 72 75 63  n as the destruc
2fd20 74 6f 72 20 6f 6e 20 74 68 65 20 74 65 78 74 20  tor on the text 
2fd30 6f 72 20 62 6c 6f 62 20 72 65 73 75 6c 74 20 77  or blob result w
2fd40 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20 66 69  hen it has.** fi
2fd50 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 61  nished using tha
2fd60 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 49 66 20  t result..** If 
2fd70 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
2fd80 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
2fd90 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
2fda0 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73  terfaces.** or s
2fdb0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
2fdc0 6f 62 20 69 73 20 74 68 65 20 73 70 65 63 69 61  ob is the specia
2fdd0 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54  l constant SQLIT
2fde0 45 5f 53 54 41 54 49 43 2c 20 74 68 65 6e 0a 2a  E_STATIC, then.*
2fdf0 2a 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73  * SQLite assumes
2fe00 20 74 68 61 74 20 74 68 65 20 74 65 78 74 20 6f   that the text o
2fe10 72 20 62 6c 6f 62 20 72 65 73 75 6c 74 20 69 73  r blob result is
2fe20 20 63 6f 6e 73 74 61 6e 74 20 73 70 61 63 65 20   constant space 
2fe30 61 6e 64 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20  and.** does not 
2fe40 63 6f 70 79 20 74 68 65 20 73 70 61 63 65 20 6f  copy the space o
2fe50 72 20 63 61 6c 6c 20 61 20 64 65 73 74 72 75 63  r call a destruc
2fe60 74 6f 72 20 77 68 65 6e 20 69 74 20 68 61 73 0a  tor when it has.
2fe70 2a 2a 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e  ** finished usin
2fe80 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a  g that result..*
2fe90 2a 20 49 66 20 74 68 65 20 34 74 68 20 70 61 72  * If the 4th par
2fea0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
2feb0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
2fec0 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  t* interfaces.**
2fed0 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
2fee0 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73  lt_blob is the s
2fef0 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20  pecial constant 
2ff00 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54  SQLITE_TRANSIENT
2ff10 0a 2a 2a 20 74 68 65 6e 20 53 51 4c 69 74 65 20  .** then SQLite 
2ff20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20  makes a copy of 
2ff30 74 68 65 20 72 65 73 75 6c 74 20 69 6e 74 6f 20  the result into 
2ff40 73 70 61 63 65 20 6f 62 74 61 69 6e 65 64 20 66  space obtained f
2ff50 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  rom.** from [sql
2ff60 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62  ite3_malloc()] b
2ff70 65 66 6f 72 65 20 69 74 20 72 65 74 75 72 6e 73  efore it returns
2ff80 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
2ff90 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
2ffa0 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
2ffb0 73 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a  s the result of.
2ffc0 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
2ffd0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
2ffe0 69 6f 6e 20 74 6f 20 62 65 20 61 20 63 6f 70 79  ion to be a copy
2fff0 20 74 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65   the.** [unprote
30000 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
30010 75 65 5d 20 6f 62 6a 65 63 74 20 73 70 65 63 69  ue] object speci
30020 66 69 65 64 20 62 79 20 74 68 65 20 32 6e 64 20  fied by the 2nd 
30030 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65 0a  parameter.  The.
30040 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  ** sqlite3_resul
30050 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66  t_value() interf
30060 61 63 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79  ace makes a copy
30070 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
30080 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74 68  _value].** so th
30090 61 74 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  at [sqlite3_valu
300a0 65 5d 20 73 70 65 63 69 66 69 65 64 20 69 6e 20  e] specified in 
300b0 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61  the parameter ma
300c0 79 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 62  y change or.** b
300d0 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 61 66  e deallocated af
300e0 74 65 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75  ter sqlite3_resu
300f0 6c 74 5f 76 61 6c 75 65 28 29 20 72 65 74 75 72  lt_value() retur
30100 6e 73 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e  ns without harm.
30110 0a 2a 2a 20 41 20 5b 70 72 6f 74 65 63 74 65 64  .** A [protected
30120 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
30130 6f 62 6a 65 63 74 20 6d 61 79 20 61 6c 77 61 79  object may alway
30140 73 20 62 65 20 75 73 65 64 20 77 68 65 72 65 20  s be used where 
30150 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74  an.** [unprotect
30160 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
30170 5d 20 6f 62 6a 65 63 74 20 69 73 20 72 65 71 75  ] object is requ
30180 69 72 65 64 2c 20 73 6f 20 65 69 74 68 65 72 0a  ired, so either.
30190 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b 73 71 6c 69  ** kind of [sqli
301a0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
301b0 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 77 69  t can be used wi
301c0 74 68 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  th this interfac
301d0 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 73  e..**.** If thes
301e0 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63  e routines are c
301f0 61 6c 6c 65 64 20 66 72 6f 6d 20 77 69 74 68 69  alled from withi
30200 6e 20 74 68 65 20 64 69 66 66 65 72 65 6e 74 20  n the different 
30210 74 68 72 65 61 64 20 0a 2a 2a 20 74 68 61 6e 20  thread .** than 
30220 74 68 65 20 6f 6e 65 20 63 6f 6e 74 61 69 6e 69  the one containi
30230 6e 67 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ng the applicati
30240 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
30250 69 6f 6e 20 74 68 61 74 20 72 65 63 65 69 76 65  ion that receive
30260 64 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  d.** the [sqlite
30270 33 5f 63 6f 6e 74 65 78 74 5d 20 70 6f 69 6e 74  3_context] point
30280 65 72 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20  er, the results 
30290 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
302a0 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
302b0 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 30 33 7d 20  .**.** {F16403} 
302c0 54 68 65 20 64 65 66 61 75 6c 74 20 72 65 74 75  The default retu
302d0 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 61 6e  rn value from an
302e0 79 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  y SQL function i
302f0 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 46  s NULL..**.** {F
30300 31 36 34 30 36 7d 20 54 68 65 20 5b 73 71 6c 69  16406} The [sqli
30310 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28  te3_result_blob(
30320 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74 65 72 66  C,V,N,D)] interf
30330 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a  ace changes the.
30340 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75  **          retu
30350 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63  rn value of func
30360 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 20 62  tion C to be a b
30370 6c 6f 62 20 74 68 61 74 20 69 73 20 4e 20 62 79  lob that is N by
30380 74 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  tes.**          
30390 69 6e 20 6c 65 6e 67 74 68 20 61 6e 64 20 77 69  in length and wi
303a0 74 68 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74  th content point
303b0 65 64 20 74 6f 20 62 79 20 56 2e 0a 2a 2a 0a 2a  ed to by V..**.*
303c0 2a 20 7b 46 31 36 34 30 39 7d 20 54 68 65 20 5b  * {F16409} The [
303d0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64  sqlite3_result_d
303e0 6f 75 62 6c 65 28 43 2c 56 29 5d 20 69 6e 74 65  ouble(C,V)] inte
303f0 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68  rface changes th
30400 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  e.**          re
30410 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75  turn value of fu
30420 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74  nction C to be t
30430 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  he floating poin
30440 74 20 76 61 6c 75 65 20 56 2e 0a 2a 2a 0a 2a 2a  t value V..**.**
30450 20 7b 46 31 36 34 31 32 7d 20 54 68 65 20 5b 73   {F16412} The [s
30460 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
30470 72 6f 72 28 43 2c 56 2c 4e 29 5d 20 69 6e 74 65  ror(C,V,N)] inte
30480 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68  rface changes th
30490 65 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20  e return.**     
304a0 20 20 20 20 20 76 61 6c 75 65 20 6f 66 20 66 75       value of fu
304b0 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 61  nction C to be a
304c0 6e 20 65 78 63 65 70 74 69 6f 6e 20 77 69 74 68  n exception with
304d0 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 20   error code.**  
304e0 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f          [SQLITE_
304f0 45 52 52 4f 52 5d 20 61 6e 64 20 61 20 55 54 46  ERROR] and a UTF
30500 38 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  8 error message 
30510 63 6f 70 69 65 64 20 66 72 6f 6d 20 56 20 75 70  copied from V up
30520 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   to the.**      
30530 20 20 20 20 66 69 72 73 74 20 7a 65 72 6f 20 62      first zero b
30540 79 74 65 20 6f 72 20 75 6e 74 69 6c 20 4e 20 62  yte or until N b
30550 79 74 65 73 20 61 72 65 20 72 65 61 64 20 69 66  ytes are read if
30560 20 4e 20 69 73 20 70 6f 73 69 74 69 76 65 2e 0a   N is positive..
30570 2a 2a 0a 2a 2a 20 7b 46 31 36 34 31 35 7d 20 54  **.** {F16415} T
30580 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  he [sqlite3_resu
30590 6c 74 5f 65 72 72 6f 72 31 36 28 43 2c 56 2c 4e  lt_error16(C,V,N
305a0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61  )] interface cha
305b0 6e 67 65 73 20 74 68 65 20 72 65 74 75 72 6e 0a  nges the return.
305c0 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c 75  **          valu
305d0 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20  e of function C 
305e0 74 6f 20 62 65 20 61 6e 20 65 78 63 65 70 74 69  to be an excepti
305f0 6f 6e 20 77 69 74 68 20 65 72 72 6f 72 20 63 6f  on with error co
30600 64 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  de.**          [
30610 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 61 6e  SQLITE_ERROR] an
30620 64 20 61 20 55 54 46 31 36 20 6e 61 74 69 76 65  d a UTF16 native
30630 20 62 79 74 65 20 6f 72 64 65 72 20 65 72 72 6f   byte order erro
30640 72 20 6d 65 73 73 61 67 65 0a 2a 2a 20 20 20 20  r message.**    
30650 20 20 20 20 20 20 63 6f 70 69 65 64 20 66 72 6f        copied fro
30660 6d 20 56 20 75 70 20 74 6f 20 74 68 65 20 66 69  m V up to the fi
30670 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  rst zero termina
30680 74 6f 72 20 6f 72 20 75 6e 74 69 6c 20 4e 20 62  tor or until N b
30690 79 74 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  ytes.**         
306a0 20 61 72 65 20 72 65 61 64 20 69 66 20 4e 20 69   are read if N i
306b0 73 20 70 6f 73 69 74 69 76 65 2e 0a 2a 2a 0a 2a  s positive..**.*
306c0 2a 20 7b 46 31 36 34 31 38 7d 20 54 68 65 20 5b  * {F16418} The [
306d0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
306e0 72 72 6f 72 5f 74 6f 6f 62 69 67 28 43 29 5d 20  rror_toobig(C)] 
306f0 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65  interface change
30700 73 20 74 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20  s the return.** 
30710 20 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 6f           value o
30720 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 43  f the function C
30730 20 74 6f 20 62 65 20 61 6e 20 65 78 63 65 70 74   to be an except
30740 69 6f 6e 20 77 69 74 68 20 65 72 72 6f 72 20 63  ion with error c
30750 6f 64 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ode.**          
30760 5b 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 5d 20  [SQLITE_TOOBIG] 
30770 61 6e 64 20 61 6e 20 61 70 70 72 6f 70 72 69 61  and an appropria
30780 74 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  te error message
30790 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 32 31 7d  ..**.** {F16421}
307a0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   The [sqlite3_re
307b0 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d  sult_error_nomem
307c0 28 43 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  (C)] interface c
307d0 68 61 6e 67 65 73 20 74 68 65 20 72 65 74 75 72  hanges the retur
307e0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61  n.**          va
307f0 6c 75 65 20 6f 66 20 74 68 65 20 66 75 6e 63 74  lue of the funct
30800 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e 20 65  ion C to be an e
30810 78 63 65 70 74 69 6f 6e 20 77 69 74 68 20 65 72  xception with er
30820 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 20 20 20 20  ror code.**     
30830 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d       [SQLITE_NOM
30840 45 4d 5d 20 61 6e 64 20 61 6e 20 61 70 70 72 6f  EM] and an appro
30850 70 72 69 61 74 65 20 65 72 72 6f 72 20 6d 65 73  priate error mes
30860 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  sage..**.** {F16
30870 34 32 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  424} The [sqlite
30880 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63  3_result_error_c
30890 6f 64 65 28 43 2c 45 29 5d 20 69 6e 74 65 72 66  ode(C,E)] interf
308a0 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 20  ace changes the 
308b0 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20  return.**       
308c0 20 20 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20     value of the 
308d0 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65  function C to be
308e0 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 77 69   an exception wi
308f0 74 68 20 65 72 72 6f 72 20 63 6f 64 65 20 45 2e  th error code E.
30900 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 54 68 65  .**          The
30910 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74   error message t
30920 65 78 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64  ext is unchanged
30930 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 32 37 7d  ..**.** {F16427}
30940 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   The [sqlite3_re
30950 73 75 6c 74 5f 69 6e 74 28 43 2c 56 29 5d 20 69  sult_int(C,V)] i
30960 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73  nterface changes
30970 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
30980 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
30990 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62   function C to b
309a0 65 20 74 68 65 20 33 32 2d 62 69 74 20 69 6e 74  e the 32-bit int
309b0 65 67 65 72 20 76 61 6c 75 65 20 56 2e 0a 2a 2a  eger value V..**
309c0 0a 2a 2a 20 7b 46 31 36 34 33 30 7d 20 54 68 65  .** {F16430} The
309d0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
309e0 5f 69 6e 74 36 34 28 43 2c 56 29 5d 20 69 6e 74  _int64(C,V)] int
309f0 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74  erface changes t
30a00 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  he.**          r
30a10 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66  eturn value of f
30a20 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20  unction C to be 
30a30 74 68 65 20 36 34 2d 62 69 74 20 69 6e 74 65 67  the 64-bit integ
30a40 65 72 20 76 61 6c 75 65 20 56 2e 0a 2a 2a 0a 2a  er value V..**.*
30a50 2a 20 7b 46 31 36 34 33 33 7d 20 54 68 65 20 5b  * {F16433} The [
30a60 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e  sqlite3_result_n
30a70 75 6c 6c 28 43 29 5d 20 69 6e 74 65 72 66 61 63  ull(C)] interfac
30a80 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a  e changes the.**
30a90 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e            return
30aa0 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69   value of functi
30ab0 6f 6e 20 43 20 74 6f 20 62 65 20 4e 55 4c 4c 2e  on C to be NULL.
30ac0 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 33 36 7d 20  .**.** {F16436} 
30ad0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
30ae0 75 6c 74 5f 74 65 78 74 28 43 2c 56 2c 4e 2c 44  ult_text(C,V,N,D
30af0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61  )] interface cha
30b00 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  nges the.**     
30b10 20 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75       return valu
30b20 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20  e of function C 
30b30 74 6f 20 62 65 20 74 68 65 20 55 54 46 38 20 73  to be the UTF8 s
30b40 74 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20  tring.**        
30b50 20 20 56 20 75 70 20 74 6f 20 74 68 65 20 66 69    V up to the fi
30b60 72 73 74 20 7a 65 72 6f 20 69 66 20 4e 20 69 73  rst zero if N is
30b70 20 6e 65 67 61 74 69 76 65 0a 2a 2a 20 20 20 20   negative.**    
30b80 20 20 20 20 20 20 6f 72 20 74 68 65 20 66 69 72        or the fir
30b90 73 74 20 4e 20 62 79 74 65 73 20 6f 66 20 56 20  st N bytes of V 
30ba0 69 66 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  if N is non-nega
30bb0 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  tive..**.** {F16
30bc0 34 33 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  439} The [sqlite
30bd0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28  3_result_text16(
30be0 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74 65 72 66  C,V,N,D)] interf
30bf0 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a  ace changes the.
30c00 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75  **          retu
30c10 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63  rn value of func
30c20 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65  tion C to be the
30c30 20 55 54 46 31 36 20 6e 61 74 69 76 65 20 62 79   UTF16 native by
30c40 74 65 20 6f 72 64 65 72 0a 2a 2a 20 20 20 20 20  te order.**     
30c50 20 20 20 20 20 73 74 72 69 6e 67 20 56 20 75 70       string V up
30c60 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65   to the first ze
30c70 72 6f 20 69 66 20 4e 20 69 73 0a 2a 2a 20 20 20  ro if N is.**   
30c80 20 20 20 20 20 20 20 6e 65 67 61 74 69 76 65 20         negative 
30c90 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e 20 62  or the first N b
30ca0 79 74 65 73 20 6f 66 20 56 20 69 66 20 4e 20 69  ytes of V if N i
30cb0 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2e 0a  s non-negative..
30cc0 2a 2a 0a 2a 2a 20 7b 46 31 36 34 34 32 7d 20 54  **.** {F16442} T
30cd0 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  he [sqlite3_resu
30ce0 6c 74 5f 74 65 78 74 31 36 62 65 28 43 2c 56 2c  lt_text16be(C,V,
30cf0 4e 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20  N,D)] interface 
30d00 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20  changes the.**  
30d10 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 76          return v
30d20 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e  alue of function
30d30 20 43 20 74 6f 20 62 65 20 74 68 65 20 55 54 46   C to be the UTF
30d40 31 36 20 62 69 67 2d 65 6e 64 69 61 6e 0a 2a 2a  16 big-endian.**
30d50 20 20 20 20 20 20 20 20 20 20 73 74 72 69 6e 67            string
30d60 20 56 20 75 70 20 74 6f 20 74 68 65 20 66 69 72   V up to the fir
30d70 73 74 20 7a 65 72 6f 20 69 66 20 4e 20 69 73 0a  st zero if N is.
30d80 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 6e  **          is n
30d90 65 67 61 74 69 76 65 20 6f 72 20 74 68 65 20 66  egative or the f
30da0 69 72 73 74 20 4e 20 62 79 74 65 73 20 6f 72 20  irst N bytes or 
30db0 56 20 69 66 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65  V if N is non-ne
30dc0 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46  gative..**.** {F
30dd0 31 36 34 34 35 7d 20 54 68 65 20 5b 73 71 6c 69  16445} The [sqli
30de0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
30df0 36 6c 65 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e  6le(C,V,N,D)] in
30e00 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20  terface changes 
30e10 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
30e20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
30e30 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65  function C to be
30e40 20 74 68 65 20 55 54 46 31 36 20 6c 69 74 74 6c   the UTF16 littl
30e50 65 2d 65 6e 64 69 61 6e 0a 2a 2a 20 20 20 20 20  e-endian.**     
30e60 20 20 20 20 20 73 74 72 69 6e 67 20 56 20 75 70       string V up
30e70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65   to the first ze
30e80 72 6f 20 69 66 20 4e 20 69 73 0a 2a 2a 20 20 20  ro if N is.**   
30e90 20 20 20 20 20 20 20 6e 65 67 61 74 69 76 65 20         negative 
30ea0 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e 20 62  or the first N b
30eb0 79 74 65 73 20 6f 66 20 56 20 69 66 20 4e 20 69  ytes of V if N i
30ec0 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2e 0a  s non-negative..
30ed0 2a 2a 0a 2a 2a 20 7b 46 31 36 34 34 38 7d 20 54  **.** {F16448} T
30ee0 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  he [sqlite3_resu
30ef0 6c 74 5f 76 61 6c 75 65 28 43 2c 56 29 5d 20 69  lt_value(C,V)] i
30f00 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73  nterface changes
30f10 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
30f20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
30f30 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62   function C to b
30f40 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  e [unprotected s
30f50 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a  qlite3_value].**
30f60 20 20 20 20 20 20 20 20 20 20 6f 62 6a 65 63 74            object
30f70 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 35   V..**.** {F1645
30f80 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
30f90 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28  result_zeroblob(
30fa0 43 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  C,N)] interface 
30fb0 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20  changes the.**  
30fc0 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 76          return v
30fd0 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e  alue of function
30fe0 20 43 20 74 6f 20 62 65 20 61 6e 20 4e 2d 62 79   C to be an N-by
30ff0 74 65 20 62 6c 6f 62 20 6f 66 20 61 6c 6c 20 7a  te blob of all z
31000 65 72 6f 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  eros..**.** {F16
31010 34 35 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  454} The [sqlite
31020 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
31030 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72  ] and [sqlite3_r
31040 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 5d  esult_error16()]
31050 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74  .**          int
31060 65 72 66 61 63 65 73 20 6d 61 6b 65 20 61 20 63  erfaces make a c
31070 6f 70 79 20 6f 66 20 74 68 65 69 72 20 65 72 72  opy of their err
31080 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e  or message strin
31090 67 73 20 62 65 66 6f 72 65 0a 2a 2a 20 20 20 20  gs before.**    
310a0 20 20 20 20 20 20 72 65 74 75 72 6e 69 6e 67 2e        returning.
310b0 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 35 37 7d 20  .**.** {F16457} 
310c0 49 66 20 74 68 65 20 44 20 64 65 73 74 72 75 63  If the D destruc
310d0 74 6f 72 20 70 61 72 61 6d 65 74 65 72 20 74 6f  tor parameter to
310e0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
310f0 5f 62 6c 6f 62 28 43 2c 56 2c 4e 2c 44 29 5d 2c  _blob(C,V,N,D)],
31100 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
31110 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
31120 74 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 5b 73 71  t(C,V,N,D)], [sq
31130 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
31140 74 31 36 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a  t16(C,V,N,D)],.*
31150 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
31160 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
31170 36 62 65 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 6f  6be(C,V,N,D)], o
31180 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  r.**          [s
31190 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
311a0 78 74 31 36 6c 65 28 43 2c 56 2c 4e 2c 44 29 5d  xt16le(C,V,N,D)]
311b0 20 69 73 20 74 68 65 20 63 6f 6e 73 74 61 6e 74   is the constant
311c0 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d   [SQLITE_STATIC]
311d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
311e0 6e 20 6e 6f 20 64 65 73 74 72 75 63 74 6f 72 20  n no destructor 
311f0 69 73 20 65 76 65 72 20 63 61 6c 6c 65 64 20 6f  is ever called o
31200 6e 20 74 68 65 20 70 6f 69 6e 74 65 72 20 56 20  n the pointer V 
31210 61 6e 64 20 53 51 4c 69 74 65 0a 2a 2a 20 20 20  and SQLite.**   
31220 20 20 20 20 20 20 20 61 73 73 75 6d 65 73 20 74         assumes t
31230 68 61 74 20 56 20 69 73 20 69 6d 6d 75 74 61 62  hat V is immutab
31240 6c 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 36  le..**.** {F1646
31250 30 7d 20 49 66 20 74 68 65 20 44 20 64 65 73 74  0} If the D dest
31260 72 75 63 74 6f 72 20 70 61 72 61 6d 65 74 65 72  ructor parameter
31270 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
31280 75 6c 74 5f 62 6c 6f 62 28 43 2c 56 2c 4e 2c 44  ult_blob(C,V,N,D
31290 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  )],.**          
312a0 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
312b0 74 65 78 74 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20  text(C,V,N,D)], 
312c0 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
312d0 74 65 78 74 31 36 28 43 2c 56 2c 4e 2c 44 29 5d  text16(C,V,N,D)]
312e0 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  ,.**          [s
312f0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
31300 78 74 31 36 62 65 28 43 2c 56 2c 4e 2c 44 29 5d  xt16be(C,V,N,D)]
31310 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  , or.**         
31320 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
31330 5f 74 65 78 74 31 36 6c 65 28 43 2c 56 2c 4e 2c  _text16le(C,V,N,
31340 44 29 5d 20 69 73 20 74 68 65 20 63 6f 6e 73 74  D)] is the const
31350 61 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ant.**          
31360 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e  [SQLITE_TRANSIEN
31370 54 5d 20 74 68 65 6e 20 74 68 65 20 69 6e 74 65  T] then the inte
31380 72 66 61 63 65 73 20 6d 61 6b 65 73 20 61 20 63  rfaces makes a c
31390 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20  opy of the.**   
313a0 20 20 20 20 20 20 20 63 6f 6e 74 65 6e 74 20 6f         content o
313b0 66 20 56 20 61 6e 64 20 72 65 74 61 69 6e 73 20  f V and retains 
313c0 74 68 65 20 63 6f 70 79 2e 0a 2a 2a 0a 2a 2a 20  the copy..**.** 
313d0 7b 46 31 36 34 36 33 7d 20 49 66 20 74 68 65 20  {F16463} If the 
313e0 44 20 64 65 73 74 72 75 63 74 6f 72 20 70 61 72  D destructor par
313f0 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
31400 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 43  e3_result_blob(C
31410 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20  ,V,N,D)],.**    
31420 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72        [sqlite3_r
31430 65 73 75 6c 74 5f 74 65 78 74 28 43 2c 56 2c 4e  esult_text(C,V,N
31440 2c 44 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 72  ,D)], [sqlite3_r
31450 65 73 75 6c 74 5f 74 65 78 74 31 36 28 43 2c 56  esult_text16(C,V
31460 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20  ,N,D)],.**      
31470 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73      [sqlite3_res
31480 75 6c 74 5f 74 65 78 74 31 36 62 65 28 43 2c 56  ult_text16be(C,V
31490 2c 4e 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20  ,N,D)], or.**   
314a0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
314b0 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28  result_text16le(
314c0 43 2c 56 2c 4e 2c 44 29 5d 20 69 73 20 73 6f 6d  C,V,N,D)] is som
314d0 65 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68  e value other th
314e0 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  an.**          t
314f0 68 65 20 63 6f 6e 73 74 61 6e 74 73 20 5b 53 51  he constants [SQ
31500 4c 49 54 45 5f 53 54 41 54 49 43 5d 20 61 6e 64  LITE_STATIC] and
31510 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45   [SQLITE_TRANSIE
31520 4e 54 5d 20 74 68 65 6e 20 0a 2a 2a 20 20 20 20  NT] then .**    
31530 20 20 20 20 20 20 53 51 4c 69 74 65 20 77 69 6c        SQLite wil
31540 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73  l invoke the des
31550 74 72 75 63 74 6f 72 20 44 20 77 69 74 68 20 56  tructor D with V
31560 20 61 73 20 69 74 73 20 6f 6e 6c 79 20 61 72 67   as its only arg
31570 75 6d 65 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20  ument.**        
31580 20 20 77 68 65 6e 20 69 74 20 68 61 73 20 66 69    when it has fi
31590 6e 69 73 68 65 64 20 77 69 74 68 20 74 68 65 20  nished with the 
315a0 56 20 76 61 6c 75 65 2e 0a 2a 2f 0a 76 6f 69 64  V value..*/.void
315b0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
315c0 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e  blob(sqlite3_con
315d0 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
315e0 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  d*, int, void(*)
315f0 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
31600 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f  qlite3_result_do
31610 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  uble(sqlite3_con
31620 74 65 78 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a  text*, double);.
31630 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
31640 75 6c 74 5f 65 72 72 6f 72 28 73 71 6c 69 74 65  ult_error(sqlite
31650 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
31660 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 3b 0a 76  t char*, int);.v
31670 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
31680 6c 74 5f 65 72 72 6f 72 31 36 28 73 71 6c 69 74  lt_error16(sqlit
31690 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
316a0 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a  st void*, int);.
316b0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
316c0 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67  ult_error_toobig
316d0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
316e0 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  *);.void sqlite3
316f0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f  _result_error_no
31700 6d 65 6d 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  mem(sqlite3_cont
31710 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69  ext*);.void sqli
31720 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
31730 5f 63 6f 64 65 28 73 71 6c 69 74 65 33 5f 63 6f  _code(sqlite3_co
31740 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f  ntext*, int);.vo
31750 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
31760 74 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f  t_int(sqlite3_co
31770 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f  ntext*, int);.vo
31780 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
31790 74 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  t_int64(sqlite3_
317a0 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65  context*, sqlite
317b0 33 5f 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73  3_int64);.void s
317c0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75  qlite3_result_nu
317d0 6c 6c 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ll(sqlite3_conte
317e0 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  xt*);.void sqlit
317f0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 73  e3_result_text(s
31800 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
31810 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e   const char*, in
31820 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  t, void(*)(void*
31830 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  ));.void sqlite3
31840 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 73  _result_text16(s
31850 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
31860 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
31870 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  t, void(*)(void*
31880 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  ));.void sqlite3
31890 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65  _result_text16le
318a0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
318b0 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
318c0 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64  int,void(*)(void
318d0 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  *));.void sqlite
318e0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62  3_result_text16b
318f0 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
31900 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  t*, const void*,
31910 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69   int,void(*)(voi
31920 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  d*));.void sqlit
31930 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
31940 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
31950 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  , sqlite3_value*
31960 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
31970 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28  result_zeroblob(
31980 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
31990 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a  , int n);../*.**
319a0 20 43 41 50 49 33 52 45 46 3a 20 44 65 66 69 6e   CAPI3REF: Defin
319b0 65 20 4e 65 77 20 43 6f 6c 6c 61 74 69 6e 67 20  e New Collating 
319c0 53 65 71 75 65 6e 63 65 73 20 7b 46 31 36 36 30  Sequences {F1660
319d0 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66  0}.**.** These f
319e0 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 75 73 65  unctions are use
319f0 64 20 74 6f 20 61 64 64 20 6e 65 77 20 63 6f 6c  d to add new col
31a00 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73  lation sequences
31a10 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   to the.** [sqli
31a20 74 65 33 2a 5d 20 68 61 6e 64 6c 65 20 73 70 65  te3*] handle spe
31a30 63 69 66 69 65 64 20 61 73 20 74 68 65 20 66 69  cified as the fi
31a40 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 20 0a 2a  rst argument. .*
31a50 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66  *.** The name of
31a60 20 74 68 65 20 6e 65 77 20 63 6f 6c 6c 61 74 69   the new collati
31a70 6f 6e 20 73 65 71 75 65 6e 63 65 20 69 73 20 73  on sequence is s
31a80 70 65 63 69 66 69 65 64 20 61 73 20 61 20 55 54  pecified as a UT
31a90 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 66 6f  F-8 string.** fo
31aa0 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  r sqlite3_create
31ab0 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 61 6e 64  _collation() and
31ac0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
31ad0 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 0a 2a  collation_v2().*
31ae0 2a 20 61 6e 64 20 61 20 55 54 46 2d 31 36 20 73  * and a UTF-16 s
31af0 74 72 69 6e 67 20 66 6f 72 20 73 71 6c 69 74 65  tring for sqlite
31b00 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
31b10 6f 6e 31 36 28 29 2e 20 49 6e 20 61 6c 6c 20 63  on16(). In all c
31b20 61 73 65 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65  ases.** the name
31b30 20 69 73 20 70 61 73 73 65 64 20 61 73 20 74 68   is passed as th
31b40 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f  e second functio
31b50 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  n argument..**.*
31b60 2a 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75  * The third argu
31b70 6d 65 6e 74 20 6d 61 79 20 62 65 20 6f 6e 65 20  ment may be one 
31b80 6f 66 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 73  of the constants
31b90 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 0a   [SQLITE_UTF8],.
31ba0 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  ** [SQLITE_UTF16
31bb0 4c 45 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55  LE] or [SQLITE_U
31bc0 54 46 31 36 42 45 5d 2c 20 69 6e 64 69 63 61 74  TF16BE], indicat
31bd0 69 6e 67 20 74 68 61 74 20 74 68 65 20 75 73 65  ing that the use
31be0 72 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 72 6f  r-supplied.** ro
31bf0 75 74 69 6e 65 20 65 78 70 65 63 74 73 20 74 6f  utine expects to
31c00 20 62 65 20 70 61 73 73 65 64 20 70 6f 69 6e 74   be passed point
31c10 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 65  ers to strings e
31c20 6e 63 6f 64 65 64 20 75 73 69 6e 67 20 55 54 46  ncoded using UTF
31c30 2d 38 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69  -8,.** UTF-16 li
31c40 74 74 6c 65 2d 65 6e 64 69 61 6e 20 6f 72 20 55  ttle-endian or U
31c50 54 46 2d 31 36 20 62 69 67 2d 65 6e 64 69 61 6e  TF-16 big-endian
31c60 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 54   respectively. T
31c70 68 65 0a 2a 2a 20 74 68 69 72 64 20 61 72 67 75  he.** third argu
31c80 6d 65 6e 74 20 6d 69 67 68 74 20 61 6c 73 6f 20  ment might also 
31c90 62 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  be [SQLITE_UTF16
31ca0 5f 41 4c 49 47 4e 45 44 5d 20 74 6f 20 69 6e 64  _ALIGNED] to ind
31cb0 69 63 61 74 65 20 74 68 61 74 0a 2a 2a 20 74 68  icate that.** th
31cc0 65 20 72 6f 75 74 69 6e 65 20 65 78 70 65 63 74  e routine expect
31cd0 73 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 31 36  s pointers to 16
31ce0 2d 62 69 74 20 77 6f 72 64 20 61 6c 69 67 6e 65  -bit word aligne
31cf0 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 6f 66 20  d strings.** of 
31d00 55 54 46 31 36 20 69 6e 20 74 68 65 20 6e 61 74  UTF16 in the nat
31d10 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 6f  ive byte order o
31d20 66 20 74 68 65 20 68 6f 73 74 20 63 6f 6d 70 75  f the host compu
31d30 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 20 70 6f 69  ter..**.** A poi
31d40 6e 74 65 72 20 74 6f 20 74 68 65 20 75 73 65 72  nter to the user
31d50 20 73 75 70 70 6c 69 65 64 20 72 6f 75 74 69 6e   supplied routin
31d60 65 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64  e must be passed
31d70 20 61 73 20 74 68 65 20 66 69 66 74 68 0a 2a 2a   as the fifth.**
31d80 20 61 72 67 75 6d 65 6e 74 2e 20 20 49 66 20 69   argument.  If i
31d90 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 69 73 20  t is NULL, this 
31da0 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 64  is the same as d
31db0 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6c 6c  eleting the coll
31dc0 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63  ation.** sequenc
31dd0 65 20 28 73 6f 20 74 68 61 74 20 53 51 4c 69 74  e (so that SQLit
31de0 65 20 63 61 6e 6e 6f 74 20 63 61 6c 6c 20 69 74  e cannot call it
31df0 20 61 6e 79 6d 6f 72 65 29 2e 0a 2a 2a 20 45 61   anymore)..** Ea
31e00 63 68 20 74 69 6d 65 20 74 68 65 20 61 70 70 6c  ch time the appl
31e10 69 63 61 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c  ication.** suppl
31e20 69 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ied function is 
31e30 69 6e 76 6f 6b 65 64 2c 20 69 74 20 69 73 20 70  invoked, it is p
31e40 61 73 73 65 64 20 61 20 63 6f 70 79 20 6f 66 20  assed a copy of 
31e50 74 68 65 20 76 6f 69 64 2a 20 70 61 73 73 65 64  the void* passed
31e60 20 61 73 0a 2a 2a 20 74 68 65 20 66 6f 75 72 74   as.** the fourt
31e70 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  h argument to sq
31e80 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
31e90 6c 61 74 69 6f 6e 28 29 20 6f 72 0a 2a 2a 20 73  lation() or.** s
31ea0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
31eb0 6c 6c 61 74 69 6f 6e 31 36 28 29 20 61 73 20 69  llation16() as i
31ec0 74 73 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  ts first paramet
31ed0 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 72 65  er..**.** The re
31ee0 6d 61 69 6e 69 6e 67 20 61 72 67 75 6d 65 6e 74  maining argument
31ef0 73 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61  s to the applica
31f00 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 20 72 6f  tion-supplied ro
31f10 75 74 69 6e 65 20 61 72 65 20 74 77 6f 20 73 74  utine are two st
31f20 72 69 6e 67 73 2c 0a 2a 2a 20 65 61 63 68 20 72  rings,.** each r
31f30 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 61 20  epresented by a 
31f40 28 6c 65 6e 67 74 68 2c 20 64 61 74 61 29 20 70  (length, data) p
31f50 61 69 72 20 61 6e 64 20 65 6e 63 6f 64 65 64 20  air and encoded 
31f60 69 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 0a  in the encoding.
31f70 2a 2a 20 74 68 61 74 20 77 61 73 20 70 61 73 73  ** that was pass
31f80 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64 20  ed as the third 
31f90 61 72 67 75 6d 65 6e 74 20 77 68 65 6e 20 74 68  argument when th
31fa0 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  e collation sequ
31fb0 65 6e 63 65 20 77 61 73 0a 2a 2a 20 72 65 67 69  ence was.** regi
31fc0 73 74 65 72 65 64 2e 20 7b 45 4e 44 7d 20 54 68  stered. {END} Th
31fd0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65  e application de
31fe0 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20  fined collation 
31ff0 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 0a 2a  routine should.*
32000 2a 20 72 65 74 75 72 6e 20 6e 65 67 61 74 69 76  * return negativ
32010 65 2c 20 7a 65 72 6f 20 6f 72 20 70 6f 73 69 74  e, zero or posit
32020 69 76 65 20 69 66 0a 2a 2a 20 74 68 65 20 66 69  ive if.** the fi
32030 72 73 74 20 73 74 72 69 6e 67 20 69 73 20 6c 65  rst string is le
32040 73 73 20 74 68 61 6e 2c 20 65 71 75 61 6c 20 74  ss than, equal t
32050 6f 2c 20 6f 72 20 67 72 65 61 74 65 72 20 74 68  o, or greater th
32060 61 6e 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a  an the second.**
32070 20 73 74 72 69 6e 67 2e 20 69 2e 65 2e 20 28 53   string. i.e. (S
32080 54 52 49 4e 47 31 20 2d 20 53 54 52 49 4e 47 32  TRING1 - STRING2
32090 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  )..**.** The sql
320a0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
320b0 61 74 69 6f 6e 5f 76 32 28 29 20 77 6f 72 6b 73  ation_v2() works
320c0 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 63 72   like sqlite3_cr
320d0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29  eate_collation()
320e0 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20  .** except that 
320f0 69 74 20 74 61 6b 65 73 20 61 6e 20 65 78 74 72  it takes an extr
32100 61 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  a argument which
32110 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f 72   is a destructor
32120 20 66 6f 72 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c   for.** the coll
32130 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 73 74  ation.  The dest
32140 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 64  ructor is called
32150 20 77 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74   when the collat
32160 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 73 74 72 6f  ion is.** destro
32170 79 65 64 20 61 6e 64 20 69 73 20 70 61 73 73 65  yed and is passe
32180 64 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  d a copy of the 
32190 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
321a0 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 0a 2a   void* pointer.*
321b0 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  * of the sqlite3
321c0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
321d0 6e 5f 76 32 28 29 2e 0a 2a 2a 20 43 6f 6c 6c 61  n_v2()..** Colla
321e0 74 69 6f 6e 73 20 61 72 65 20 64 65 73 74 72 6f  tions are destro
321f0 79 65 64 20 77 68 65 6e 0a 2a 2a 20 74 68 65 79  yed when.** they
32200 20 61 72 65 20 6f 76 65 72 72 69 64 64 65 6e 20   are overridden 
32210 62 79 20 6c 61 74 65 72 20 63 61 6c 6c 73 20 74  by later calls t
32220 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20  o the collation 
32230 63 72 65 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f  creation functio
32240 6e 73 0a 2a 2a 20 6f 72 20 77 68 65 6e 20 74 68  ns.** or when th
32250 65 20 5b 73 71 6c 69 74 65 33 2a 5d 20 64 61 74  e [sqlite3*] dat
32260 61 62 61 73 65 20 68 61 6e 64 6c 65 20 69 73 20  abase handle is 
32270 63 6c 6f 73 65 64 20 75 73 69 6e 67 20 5b 73 71  closed using [sq
32280 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a  lite3_close()]..
32290 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
322a0 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36 30 33 7d  :.**.** {F16603}
322b0 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61   A successful ca
322c0 6c 6c 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20  ll to the.**    
322d0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63        [sqlite3_c
322e0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
322f0 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d  v2(B,X,E,P,F,D)]
32300 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 20 20   interface.**   
32310 20 20 20 20 20 20 20 72 65 67 69 73 74 65 72 73         registers
32320 20 66 75 6e 63 74 69 6f 6e 20 46 20 61 73 20 74   function F as t
32330 68 65 20 63 6f 6d 70 61 72 69 73 6f 6e 20 66 75  he comparison fu
32340 6e 63 74 69 6f 6e 20 75 73 65 64 20 74 6f 0a 2a  nction used to.*
32350 2a 20 20 20 20 20 20 20 20 20 20 69 6d 70 6c 65  *          imple
32360 6d 65 6e 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 58  ment collation X
32370 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f   on [database co
32380 6e 6e 65 63 74 69 6f 6e 5d 20 42 20 66 6f 72 0a  nnection] B for.
32390 2a 2a 20 20 20 20 20 20 20 20 20 20 64 61 74 61  **          data
323a0 62 61 73 65 73 20 68 61 76 69 6e 67 20 65 6e 63  bases having enc
323b0 6f 64 69 6e 67 20 45 2e 0a 2a 2a 0a 2a 2a 20 7b  oding E..**.** {
323c0 46 31 36 36 30 34 7d 20 53 51 4c 69 74 65 20 75  F16604} SQLite u
323d0 6e 64 65 72 73 74 61 6e 64 73 20 74 68 65 20 58  nderstands the X
323e0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
323f0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
32400 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
32410 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46  ion_v2(B,X,E,P,F
32420 2c 44 29 5d 20 61 73 20 61 20 7a 65 72 6f 2d 74  ,D)] as a zero-t
32430 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 20 20 20  erminated.**    
32440 20 20 20 20 20 20 55 54 46 2d 38 20 73 74 72 69        UTF-8 stri
32450 6e 67 20 69 6e 20 77 68 69 63 68 20 63 61 73 65  ng in which case
32460 20 69 73 20 69 67 6e 6f 72 65 64 20 66 6f 72 20   is ignored for 
32470 41 53 43 49 49 20 63 68 61 72 61 63 74 65 72 73  ASCII characters
32480 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20   and.**         
32490 20 69 73 20 73 69 67 6e 69 66 69 63 61 6e 74 20   is significant 
324a0 66 6f 72 20 6e 6f 6e 2d 41 53 43 49 49 20 63 68  for non-ASCII ch
324b0 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  aracters..**.** 
324c0 7b 46 31 36 36 30 36 7d 20 53 75 63 63 65 73 73  {F16606} Success
324d0 69 76 65 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  ive calls to [sq
324e0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
324f0 6c 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c  lation_v2(B,X,E,
32500 50 2c 46 2c 44 29 5d 0a 2a 2a 20 20 20 20 20 20  P,F,D)].**      
32510 20 20 20 20 77 69 74 68 20 74 68 65 20 73 61 6d      with the sam
32520 65 20 76 61 6c 75 65 73 20 66 6f 72 20 42 2c 20  e values for B, 
32530 58 2c 20 61 6e 64 20 45 2c 20 6f 76 65 72 72 69  X, and E, overri
32540 64 65 20 70 72 69 6f 72 20 76 61 6c 75 65 73 0a  de prior values.
32550 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 50  **          of P
32560 2c 20 46 2c 20 61 6e 64 20 44 2e 0a 2a 2a 0a 2a  , F, and D..**.*
32570 2a 20 7b 46 31 36 36 30 39 7d 20 54 68 65 20 64  * {F16609} The d
32580 65 73 74 72 75 63 74 6f 72 20 44 20 69 6e 20 5b  estructor D in [
32590 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
325a0 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c  ollation_v2(B,X,
325b0 45 2c 50 2c 46 2c 44 29 5d 0a 2a 2a 20 20 20 20  E,P,F,D)].**    
325c0 20 20 20 20 20 20 69 73 20 6e 6f 74 20 4e 55 4c        is not NUL
325d0 4c 20 74 68 65 6e 20 69 74 20 69 73 20 63 61 6c  L then it is cal
325e0 6c 65 64 20 77 69 74 68 20 61 72 67 75 6d 65 6e  led with argumen
325f0 74 20 50 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20  t P when the.** 
32600 20 20 20 20 20 20 20 20 20 63 6f 6c 6c 61 74 69           collati
32610 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64  ng function is d
32620 72 6f 70 70 65 64 20 62 79 20 53 51 4c 69 74 65  ropped by SQLite
32630 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36 31 32 7d  ..**.** {F16612}
32640 20 41 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e   A collating fun
32650 63 74 69 6f 6e 20 69 73 20 64 72 6f 70 70 65 64  ction is dropped
32660 20 77 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72   when it is over
32670 6c 6f 61 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46  loaded..**.** {F
32680 31 36 36 31 35 7d 20 41 20 63 6f 6c 6c 61 74 69  16615} A collati
32690 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64  ng function is d
326a0 72 6f 70 70 65 64 20 77 68 65 6e 20 74 68 65 20  ropped when the 
326b0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
326c0 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ion.**          
326d0 69 73 20 63 6c 6f 73 65 64 20 75 73 69 6e 67 20  is closed using 
326e0 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29  [sqlite3_close()
326f0 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36 31 38  ]..**.** {F16618
32700 7d 20 54 68 65 20 70 6f 69 6e 74 65 72 20 50 20  } The pointer P 
32710 69 6e 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  in [sqlite3_crea
32720 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
32730 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 0a 2a 2a  B,X,E,P,F,D)].**
32740 20 20 20 20 20 20 20 20 20 20 69 73 20 70 61 73            is pas
32750 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74  sed through as t
32760 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
32770 65 72 20 74 6f 20 74 68 65 20 63 6f 6d 70 61 72  er to the compar
32780 69 73 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  ison.**         
32790 20 66 75 6e 63 74 69 6f 6e 20 46 20 66 6f 72 20   function F for 
327a0 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20 69  all subsequent i
327b0 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 46 2e  nvocations of F.
327c0 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36 32 31 7d 20  .**.** {F16621} 
327d0 41 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  A call to [sqlit
327e0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
327f0 69 6f 6e 28 42 2c 58 2c 45 2c 50 2c 46 29 5d 20  ion(B,X,E,P,F)] 
32800 69 73 20 65 78 61 63 74 6c 79 0a 2a 2a 20 20 20  is exactly.**   
32810 20 20 20 20 20 20 20 74 68 65 20 73 61 6d 65 20         the same 
32820 61 73 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71  as a call to [sq
32830 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
32840 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 20 77 69 74  lation_v2()] wit
32850 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  h.**          th
32860 65 20 73 61 6d 65 20 70 61 72 61 6d 65 74 65 72  e same parameter
32870 73 20 61 6e 64 20 61 20 4e 55 4c 4c 20 64 65 73  s and a NULL des
32880 74 72 75 63 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b  tructor..**.** {
32890 46 31 36 36 32 34 7d 20 46 6f 6c 6c 6f 77 69 6e  F16624} Followin
328a0 67 20 61 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  g a [sqlite3_cre
328b0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
328c0 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 2c 0a  (B,X,E,P,F,D)],.
328d0 2a 2a 20 20 20 20 20 20 20 20 20 20 53 51 4c 69  **          SQLi
328e0 74 65 20 75 73 65 73 20 74 68 65 20 63 6f 6d 70  te uses the comp
328f0 61 72 69 73 6f 6e 20 66 75 6e 63 74 69 6f 6e 20  arison function 
32900 46 20 66 6f 72 20 61 6c 6c 20 74 65 78 74 20 63  F for all text c
32910 6f 6d 70 61 72 69 73 6f 6e 0a 2a 2a 20 20 20 20  omparison.**    
32920 20 20 20 20 20 20 6f 70 65 72 61 74 69 6f 6e 73        operations
32930 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f   on [database co
32940 6e 6e 65 63 74 69 6f 6e 5d 20 42 20 6f 6e 20 74  nnection] B on t
32950 65 78 74 20 76 61 6c 75 65 73 20 74 68 61 74 0a  ext values that.
32960 2a 2a 20 20 20 20 20 20 20 20 20 20 75 73 65 20  **          use 
32970 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 73 65  the collating se
32980 71 75 65 6e 63 65 20 6e 61 6d 65 20 58 2e 0a 2a  quence name X..*
32990 2a 0a 2a 2a 20 7b 46 31 36 36 32 37 7d 20 54 68  *.** {F16627} Th
329a0 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
329b0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 42 2c  e_collation16(B,
329c0 58 2c 45 2c 50 2c 46 29 5d 20 77 6f 72 6b 73 20  X,E,P,F)] works 
329d0 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20  the same.**     
329e0 20 20 20 20 20 61 73 20 5b 73 71 6c 69 74 65 33       as [sqlite3
329f0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
32a00 6e 28 42 2c 58 2c 45 2c 50 2c 46 29 5d 20 65 78  n(B,X,E,P,F)] ex
32a10 63 65 70 74 20 74 68 61 74 20 74 68 65 0a 2a 2a  cept that the.**
32a20 20 20 20 20 20 20 20 20 20 20 63 6f 6c 6c 61 74            collat
32a30 69 6f 6e 20 6e 61 6d 65 20 58 20 69 73 20 75 6e  ion name X is un
32a40 64 65 72 73 74 6f 6f 64 20 61 73 20 55 54 46 2d  derstood as UTF-
32a50 31 36 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74  16 in native byt
32a60 65 20 6f 72 64 65 72 0a 2a 2a 20 20 20 20 20 20  e order.**      
32a70 20 20 20 20 69 6e 73 74 65 61 64 20 6f 66 20 55      instead of U
32a80 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  TF-8..**.** {F16
32a90 36 33 30 7d 20 57 68 65 6e 20 6d 75 6c 74 69 70  630} When multip
32aa0 6c 65 20 63 6f 6d 70 61 72 69 73 6f 6e 20 66 75  le comparison fu
32ab0 6e 63 74 69 6f 6e 73 20 61 72 65 20 61 76 61 69  nctions are avai
32ac0 6c 61 62 6c 65 20 66 6f 72 20 74 68 65 20 73 61  lable for the sa
32ad0 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63  me.**          c
32ae0 6f 6c 6c 61 74 69 6e 67 20 73 65 71 75 65 6e 63  ollating sequenc
32af0 65 2c 20 53 51 4c 69 74 65 20 63 68 6f 6f 73 65  e, SQLite choose
32b00 73 20 74 68 65 20 6f 6e 65 20 77 68 6f 73 65 20  s the one whose 
32b10 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a  text encoding.**
32b20 20 20 20 20 20 20 20 20 20 20 72 65 71 75 69 72            requir
32b30 65 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f  es the least amo
32b40 75 6e 74 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f  unt of conversio
32b50 6e 20 66 72 6f 6d 20 74 68 65 20 64 65 66 61 75  n from the defau
32b60 6c 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  lt.**          t
32b70 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20  ext encoding of 
32b80 74 68 65 20 64 61 74 61 62 61 73 65 2e 0a 2a 2f  the database..*/
32b90 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65  .int sqlite3_cre
32ba0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20  ate_collation(. 
32bb0 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f   sqlite3*, .  co
32bc0 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
32bd0 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70   .  int eTextRep
32be0 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e  , .  void*,.  in
32bf0 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69  t(*xCompare)(voi
32c00 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
32c10 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
32c20 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  d*).);.int sqlit
32c30 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
32c40 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  ion_v2(.  sqlite
32c50 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61  3*, .  const cha
32c60 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74  r *zName, .  int
32c70 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f   eTextRep, .  vo
32c80 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d  id*,.  int(*xCom
32c90 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  pare)(void*,int,
32ca0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c  const void*,int,
32cb0 63 6f 6e 73 74 20 76 6f 69 64 2a 29 2c 0a 20 20  const void*),.  
32cc0 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28  void(*xDestroy)(
32cd0 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71  void*).);.int sq
32ce0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
32cf0 6c 61 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69  lation16(.  sqli
32d00 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63  te3*, .  const c
32d10 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69  har *zName, .  i
32d20 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20  nt eTextRep, .  
32d30 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43  void*,.  int(*xC
32d40 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e  ompare)(void*,in
32d50 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e  t,const void*,in
32d60 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29  t,const void*).)
32d70 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
32d80 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65  F: Collation Nee
32d90 64 65 64 20 43 61 6c 6c 62 61 63 6b 73 20 7b 46  ded Callbacks {F
32da0 31 36 37 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20  16700}.**.** To 
32db0 61 76 6f 69 64 20 68 61 76 69 6e 67 20 74 6f 20  avoid having to 
32dc0 72 65 67 69 73 74 65 72 20 61 6c 6c 20 63 6f 6c  register all col
32dd0 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73  lation sequences
32de0 20 62 65 66 6f 72 65 20 61 20 64 61 74 61 62 61   before a databa
32df0 73 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65  se.** can be use
32e00 64 2c 20 61 20 73 69 6e 67 6c 65 20 63 61 6c 6c  d, a single call
32e10 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6d 61  back function ma
32e20 79 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20  y be registered 
32e30 77 69 74 68 20 74 68 65 0a 2a 2a 20 64 61 74 61  with the.** data
32e40 62 61 73 65 20 68 61 6e 64 6c 65 20 74 6f 20 62  base handle to b
32e50 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 65 76 65  e called wheneve
32e60 72 20 61 6e 20 75 6e 64 65 66 69 6e 65 64 20 63  r an undefined c
32e70 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
32e80 65 20 69 73 0a 2a 2a 20 72 65 71 75 69 72 65 64  e is.** required
32e90 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66  ..**.** If the f
32ea0 75 6e 63 74 69 6f 6e 20 69 73 20 72 65 67 69 73  unction is regis
32eb0 74 65 72 65 64 20 75 73 69 6e 67 20 74 68 65 20  tered using the 
32ec0 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
32ed0 6e 5f 6e 65 65 64 65 64 28 29 20 41 50 49 2c 0a  n_needed() API,.
32ee0 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 70 61  ** then it is pa
32ef0 73 73 65 64 20 74 68 65 20 6e 61 6d 65 73 20 6f  ssed the names o
32f00 66 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c  f undefined coll
32f10 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20  ation sequences 
32f20 61 73 20 73 74 72 69 6e 67 73 0a 2a 2a 20 65 6e  as strings.** en
32f30 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 2e 20  coded in UTF-8. 
32f40 7b 46 31 36 37 30 33 7d 20 49 66 20 73 71 6c 69  {F16703} If sqli
32f50 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
32f60 65 64 65 64 31 36 28 29 20 69 73 20 75 73 65 64  eded16() is used
32f70 2c 20 74 68 65 20 6e 61 6d 65 73 0a 2a 2a 20 61  , the names.** a
32f80 72 65 20 70 61 73 73 65 64 20 61 73 20 55 54 46  re passed as UTF
32f90 2d 31 36 20 69 6e 20 6d 61 63 68 69 6e 65 20 6e  -16 in machine n
32fa0 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
32fb0 2e 20 41 20 63 61 6c 6c 20 74 6f 20 65 69 74 68  . A call to eith
32fc0 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72  er.** function r
32fd0 65 70 6c 61 63 65 73 20 61 6e 79 20 65 78 69 73  eplaces any exis
32fe0 74 69 6e 67 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a  ting callback..*
32ff0 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61  *.** When the ca
33000 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
33010 64 2c 20 74 68 65 20 66 69 72 73 74 20 61 72 67  d, the first arg
33020 75 6d 65 6e 74 20 70 61 73 73 65 64 20 69 73 20  ument passed is 
33030 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65  a copy.** of the
33040 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
33050 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c   to sqlite3_coll
33060 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 6f  ation_needed() o
33070 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r.** sqlite3_col
33080 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28  lation_needed16(
33090 29 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61  ).  The second a
330a0 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 64  rgument is the d
330b0 61 74 61 62 61 73 65 0a 2a 2a 20 68 61 6e 64 6c  atabase.** handl
330c0 65 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72  e.  The third ar
330d0 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66  gument is one of
330e0 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 0a   [SQLITE_UTF8],.
330f0 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  ** [SQLITE_UTF16
33100 42 45 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  BE], or [SQLITE_
33110 55 54 46 31 36 4c 45 5d 2c 20 69 6e 64 69 63 61  UTF16LE], indica
33120 74 69 6e 67 20 74 68 65 20 6d 6f 73 74 0a 2a 2a  ting the most.**
33130 20 64 65 73 69 72 61 62 6c 65 20 66 6f 72 6d 20   desirable form 
33140 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e  of the collation
33150 20 73 65 71 75 65 6e 63 65 20 66 75 6e 63 74 69   sequence functi
33160 6f 6e 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 20  on required..** 
33170 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  The fourth param
33180 65 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65  eter is the name
33190 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 71 75 69   of the.** requi
331a0 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  red collation se
331b0 71 75 65 6e 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  quence..**.** Th
331c0 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
331d0 69 6f 6e 20 73 68 6f 75 6c 64 20 72 65 67 69 73  ion should regis
331e0 74 65 72 20 74 68 65 20 64 65 73 69 72 65 64 20  ter the desired 
331f0 63 6f 6c 6c 61 74 69 6f 6e 20 75 73 69 6e 67 0a  collation using.
33200 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ** [sqlite3_crea
33210 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c  te_collation()],
33220 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
33230 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 5d 2c  _collation16()],
33240 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
33250 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
33260 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e  _v2()]..**.** IN
33270 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
33280 7b 46 31 36 37 30 32 7d 20 41 20 73 75 63 63 65  {F16702} A succe
33290 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73  ssful call to [s
332a0 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
332b0 5f 6e 65 65 64 65 64 28 44 2c 50 2c 46 29 5d 0a  _needed(D,P,F)].
332c0 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 5b  **          or [
332d0 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
332e0 6e 5f 6e 65 65 64 65 64 31 36 28 44 2c 50 2c 46  n_needed16(D,P,F
332f0 29 5d 20 63 61 75 73 65 73 0a 2a 2a 20 20 20 20  )] causes.**    
33300 20 20 20 20 20 20 74 68 65 20 5b 64 61 74 61 62        the [datab
33310 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
33320 44 20 74 6f 20 69 6e 76 6f 6b 65 20 63 61 6c 6c  D to invoke call
33330 62 61 63 6b 20 46 20 77 69 74 68 20 66 69 72 73  back F with firs
33340 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 61  t.**          pa
33350 72 61 6d 65 74 65 72 20 50 20 77 68 65 6e 65 76  rameter P whenev
33360 65 72 20 69 74 20 6e 65 65 64 73 20 61 20 63 6f  er it needs a co
33370 6d 70 61 72 69 73 6f 6e 20 66 75 6e 63 74 69 6f  mparison functio
33380 6e 20 66 6f 72 20 61 0a 2a 2a 20 20 20 20 20 20  n for a.**      
33390 20 20 20 20 63 6f 6c 6c 61 74 69 6e 67 20 73 65      collating se
333a0 71 75 65 6e 63 65 20 74 68 61 74 20 69 74 20 64  quence that it d
333b0 6f 65 73 20 6e 6f 74 20 6b 6e 6f 77 20 61 62 6f  oes not know abo
333c0 75 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 37 30  ut..**.** {F1670
333d0 34 7d 20 45 61 63 68 20 73 75 63 63 65 73 73 66  4} Each successf
333e0 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ul call to [sqli
333f0 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
33400 65 64 65 64 28 29 5d 20 6f 72 0a 2a 2a 20 20 20  eded()] or.**   
33410 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
33420 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
33430 31 36 28 29 5d 20 6f 76 65 72 72 69 64 65 73 20  16()] overrides 
33440 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 67  the callback reg
33450 69 73 74 65 72 65 64 0a 2a 2a 20 20 20 20 20 20  istered.**      
33460 20 20 20 20 6f 6e 20 74 68 65 20 73 61 6d 65 20      on the same 
33470 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
33480 74 69 6f 6e 5d 20 62 79 20 70 72 69 6f 72 20 63  tion] by prior c
33490 61 6c 6c 73 20 74 6f 20 65 69 74 68 65 72 0a 2a  alls to either.*
334a0 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 72  *          inter
334b0 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  face..**.** {F16
334c0 37 30 36 7d 20 54 68 65 20 6e 61 6d 65 20 6f 66  706} The name of
334d0 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20 63   the requested c
334e0 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
334f0 6e 20 70 61 73 73 65 64 20 69 6e 20 74 68 65 0a  n passed in the.
33500 2a 2a 20 20 20 20 20 20 20 20 20 20 34 74 68 20  **          4th 
33510 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
33520 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 20   callback is in 
33530 55 54 46 2d 38 20 69 66 20 74 68 65 20 63 61 6c  UTF-8 if the cal
33540 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20  lback.**        
33550 20 20 77 61 73 20 72 65 67 69 73 74 65 72 65 64    was registered
33560 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
33570 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
33580 28 29 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20  ()] and.**      
33590 20 20 20 20 69 73 20 69 6e 20 55 54 46 2d 31 36      is in UTF-16
335a0 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
335b0 65 72 20 69 66 20 74 68 65 20 63 61 6c 6c 62 61  er if the callba
335c0 63 6b 20 77 61 73 0a 2a 2a 20 20 20 20 20 20 20  ck was.**       
335d0 20 20 20 72 65 67 69 73 74 65 72 65 64 20 75 73     registered us
335e0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  ing [sqlite3_col
335f0 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28  lation_needed16(
33600 29 5d 2e 0a 2a 2a 0a 2a 2a 20 0a 2a 2f 0a 69 6e  )]..**.** .*/.in
33610 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  t sqlite3_collat
33620 69 6f 6e 5f 6e 65 65 64 65 64 28 0a 20 20 73 71  ion_needed(.  sq
33630 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a  lite3*, .  void*
33640 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69  , .  void(*)(voi
33650 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20  d*,sqlite3*,int 
33660 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 63  eTextRep,const c
33670 68 61 72 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c  har*).);.int sql
33680 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
33690 65 65 64 65 64 31 36 28 0a 20 20 73 71 6c 69 74  eeded16(.  sqlit
336a0 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20  e3*, .  void*,. 
336b0 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73   void(*)(void*,s
336c0 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78  qlite3*,int eTex
336d0 74 52 65 70 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  tRep,const void*
336e0 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63  ).);../*.** Spec
336f0 69 66 79 20 74 68 65 20 6b 65 79 20 66 6f 72 20  ify the key for 
33700 61 6e 20 65 6e 63 72 79 70 74 65 64 20 64 61 74  an encrypted dat
33710 61 62 61 73 65 2e 20 20 54 68 69 73 20 72 6f 75  abase.  This rou
33720 74 69 6e 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a  tine should be.*
33730 2a 20 63 61 6c 6c 65 64 20 72 69 67 68 74 20 61  * called right a
33740 66 74 65 72 20 73 71 6c 69 74 65 33 5f 6f 70 65  fter sqlite3_ope
33750 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  n()..**.** The c
33760 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  ode to implement
33770 20 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74   this API is not
33780 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68   available in th
33790 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65  e public release
337a0 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  .** of SQLite..*
337b0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65  /.int sqlite3_ke
337c0 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  y(.  sqlite3 *db
337d0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
337e0 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
337f0 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f  to be rekeyed */
33800 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70  .  const void *p
33810 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20  Key, int nKey   
33820 20 20 2f 2a 20 54 68 65 20 6b 65 79 20 2a 2f 0a    /* The key */.
33830 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65  );../*.** Change
33840 20 74 68 65 20 6b 65 79 20 6f 6e 20 61 6e 20 6f   the key on an o
33850 70 65 6e 20 64 61 74 61 62 61 73 65 2e 20 20 49  pen database.  I
33860 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 61  f the current da
33870 74 61 62 61 73 65 20 69 73 20 6e 6f 74 0a 2a 2a  tabase is not.**
33880 20 65 6e 63 72 79 70 74 65 64 2c 20 74 68 69 73   encrypted, this
33890 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 65 6e   routine will en
338a0 63 72 79 70 74 20 69 74 2e 20 20 49 66 20 70 4e  crypt it.  If pN
338b0 65 77 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d 3d 30  ew==0 or nNew==0
338c0 2c 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  , the.** databas
338d0 65 20 69 73 20 64 65 63 72 79 70 74 65 64 2e 0a  e is decrypted..
338e0 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74  **.** The code t
338f0 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73  o implement this
33900 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69   API is not avai
33910 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62  lable in the pub
33920 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f  lic release.** o
33930 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74  f SQLite..*/.int
33940 20 73 71 6c 69 74 65 33 5f 72 65 6b 65 79 28 0a   sqlite3_rekey(.
33950 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
33960 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
33970 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20   /* Database to 
33980 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20  be rekeyed */.  
33990 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79  const void *pKey
339a0 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f  , int nKey     /
339b0 2a 20 54 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f  * The new key */
339c0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
339d0 52 45 46 3a 20 20 53 75 73 70 65 6e 64 20 45 78  REF:  Suspend Ex
339e0 65 63 75 74 69 6f 6e 20 46 6f 72 20 41 20 53 68  ecution For A Sh
339f0 6f 72 74 20 54 69 6d 65 20 7b 46 31 30 35 33 30  ort Time {F10530
33a00 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  }.**.** The sqli
33a10 74 65 33 5f 73 6c 65 65 70 28 29 20 66 75 6e 63  te3_sleep() func
33a20 74 69 6f 6e 0a 2a 2a 20 63 61 75 73 65 73 20 74  tion.** causes t
33a30 68 65 20 63 75 72 72 65 6e 74 20 74 68 72 65 61  he current threa
33a40 64 20 74 6f 20 73 75 73 70 65 6e 64 20 65 78 65  d to suspend exe
33a50 63 75 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74  cution.** for at
33a60 20 6c 65 61 73 74 20 61 20 6e 75 6d 62 65 72 20   least a number 
33a70 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  of milliseconds 
33a80 73 70 65 63 69 66 69 65 64 20 69 6e 20 69 74 73  specified in its
33a90 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
33aa0 2a 20 49 66 20 74 68 65 20 6f 70 65 72 61 74 69  * If the operati
33ab0 6e 67 20 73 79 73 74 65 6d 20 64 6f 65 73 20 6e  ng system does n
33ac0 6f 74 20 73 75 70 70 6f 72 74 20 73 6c 65 65 70  ot support sleep
33ad0 20 72 65 71 75 65 73 74 73 20 77 69 74 68 20 0a   requests with .
33ae0 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 74  ** millisecond t
33af0 69 6d 65 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 20  ime resolution, 
33b00 74 68 65 6e 20 74 68 65 20 74 69 6d 65 20 77 69  then the time wi
33b10 6c 6c 20 62 65 20 72 6f 75 6e 64 65 64 20 75 70  ll be rounded up
33b20 20 74 6f 20 0a 2a 2a 20 74 68 65 20 6e 65 61 72   to .** the near
33b30 65 73 74 20 73 65 63 6f 6e 64 2e 20 54 68 65 20  est second. The 
33b40 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73  number of millis
33b50 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 20  econds of sleep 
33b60 61 63 74 75 61 6c 6c 79 20 0a 2a 2a 20 72 65 71  actually .** req
33b70 75 65 73 74 65 64 20 66 72 6f 6d 20 74 68 65 20  uested from the 
33b80 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
33b90 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
33ba0 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6d 70 6c 65  .** SQLite imple
33bb0 6d 65 6e 74 73 20 74 68 69 73 20 69 6e 74 65 72  ments this inter
33bc0 66 61 63 65 20 62 79 20 63 61 6c 6c 69 6e 67 20  face by calling 
33bd0 74 68 65 20 78 53 6c 65 65 70 28 29 0a 2a 2a 20  the xSleep().** 
33be0 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65  method of the de
33bf0 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76  fault [sqlite3_v
33c00 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a  fs] object..**.*
33c10 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
33c20 0a 2a 2a 20 7b 46 31 30 35 33 33 7d 20 54 68 65  .** {F10533} The
33c30 20 5b 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28   [sqlite3_sleep(
33c40 4d 29 5d 20 69 6e 74 65 72 66 61 63 65 20 69 6e  M)] interface in
33c50 76 6f 6b 65 73 20 74 68 65 20 78 53 6c 65 65 70  vokes the xSleep
33c60 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 65 74  .**          met
33c70 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61 75  hod of the defau
33c80 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 7c  lt [sqlite3_vfs|
33c90 56 46 53 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f  VFS] in order to
33ca0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 75 73  .**          sus
33cb0 70 65 6e 64 20 65 78 65 63 75 74 69 6f 6e 20 6f  pend execution o
33cc0 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 74 68  f the current th
33cd0 72 65 61 64 20 66 6f 72 20 61 74 20 6c 65 61 73  read for at leas
33ce0 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4d 20  t.**          M 
33cf0 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 2e 0a 2a 2a  milliseconds..**
33d00 0a 2a 2a 20 7b 46 31 30 35 33 36 7d 20 54 68 65  .** {F10536} The
33d10 20 5b 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28   [sqlite3_sleep(
33d20 4d 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  M)] interface re
33d30 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
33d40 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   of.**          
33d50 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20  milliseconds of 
33d60 73 6c 65 65 70 20 61 63 74 75 61 6c 6c 79 20 72  sleep actually r
33d70 65 71 75 65 73 74 65 64 20 6f 66 20 74 68 65 20  equested of the 
33d80 6f 70 65 72 61 74 69 6e 67 0a 2a 2a 20 20 20 20  operating.**    
33d90 20 20 20 20 20 20 73 79 73 74 65 6d 2c 20 77 68        system, wh
33da0 69 63 68 20 6d 69 67 68 74 20 62 65 20 6c 61 72  ich might be lar
33db0 67 65 72 20 74 68 61 6e 20 74 68 65 20 70 61 72  ger than the par
33dc0 61 6d 65 74 65 72 20 4d 2e 0a 2a 2f 0a 69 6e 74  ameter M..*/.int
33dd0 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 69   sqlite3_sleep(i
33de0 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
33df0 33 52 45 46 3a 20 20 4e 61 6d 65 20 4f 66 20 54  3REF:  Name Of T
33e00 68 65 20 46 6f 6c 64 65 72 20 48 6f 6c 64 69 6e  he Folder Holdin
33e10 67 20 54 65 6d 70 6f 72 61 72 79 20 46 69 6c 65  g Temporary File
33e20 73 20 7b 46 31 30 33 31 30 7d 0a 2a 2a 0a 2a 2a  s {F10310}.**.**
33e30 20 49 66 20 74 68 69 73 20 67 6c 6f 62 61 6c 20   If this global 
33e40 76 61 72 69 61 62 6c 65 20 69 73 20 6d 61 64 65  variable is made
33e50 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61 20 73   to point to a s
33e60 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 0a 2a  tring which is.*
33e70 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 20  * the name of a 
33e80 66 6f 6c 64 65 72 20 28 61 2e 6b 2e 61 2e 20 64  folder (a.k.a. d
33e90 69 72 65 63 74 6f 72 79 29 2c 20 74 68 65 6e 20  irectory), then 
33ea0 61 6c 6c 20 74 65 6d 70 6f 72 61 72 79 20 66 69  all temporary fi
33eb0 6c 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 62  les.** created b
33ec0 79 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65  y SQLite will be
33ed0 20 70 6c 61 63 65 64 20 69 6e 20 74 68 61 74 20   placed in that 
33ee0 64 69 72 65 63 74 6f 72 79 2e 20 20 49 66 20 74  directory.  If t
33ef0 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20  his variable.** 
33f00 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c  is NULL pointer,
33f10 20 74 68 65 6e 20 53 51 4c 69 74 65 20 64 6f 65   then SQLite doe
33f20 73 20 61 20 73 65 61 72 63 68 20 66 6f 72 20 61  s a search for a
33f30 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 74 65  n appropriate te
33f40 6d 70 6f 72 61 72 79 0a 2a 2a 20 66 69 6c 65 20  mporary.** file 
33f50 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a  directory..**.**
33f60 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20   It is not safe 
33f70 74 6f 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76  to modify this v
33f80 61 72 69 61 62 6c 65 20 6f 6e 63 65 20 61 20 64  ariable once a d
33f90 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
33fa0 6f 6e 0a 2a 2a 20 68 61 73 20 62 65 65 6e 20 6f  on.** has been o
33fb0 70 65 6e 65 64 2e 20 20 49 74 20 69 73 20 69 6e  pened.  It is in
33fc0 74 65 6e 64 65 64 20 74 68 61 74 20 74 68 69 73  tended that this
33fd0 20 76 61 72 69 61 62 6c 65 20 62 65 20 73 65 74   variable be set
33fe0 20 6f 6e 63 65 0a 2a 2a 20 61 73 20 70 61 72 74   once.** as part
33ff0 20 6f 66 20 70 72 6f 63 65 73 73 20 69 6e 69 74   of process init
34000 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 20 62  ialization and b
34010 65 66 6f 72 65 20 61 6e 79 20 53 51 4c 69 74 65  efore any SQLite
34020 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 6f   interface.** ro
34030 75 74 69 6e 65 73 20 68 61 76 65 20 62 65 65 6e  utines have been
34040 20 63 61 6c 6c 20 61 6e 64 20 72 65 6d 61 69 6e   call and remain
34050 20 75 6e 63 68 61 6e 67 65 64 20 74 68 65 72 65   unchanged there
34060 61 66 74 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45  after..*/.SQLITE
34070 5f 45 58 54 45 52 4e 20 63 68 61 72 20 2a 73 71  _EXTERN char *sq
34080 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63  lite3_temp_direc
34090 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tory;../*.** CAP
340a0 49 33 52 45 46 3a 20 20 54 65 73 74 20 54 6f 20  I3REF:  Test To 
340b0 53 65 65 20 49 66 20 54 68 65 20 44 61 74 61 62  See If The Datab
340c0 61 73 65 20 49 73 20 49 6e 20 41 75 74 6f 2d 43  ase Is In Auto-C
340d0 6f 6d 6d 69 74 20 4d 6f 64 65 20 7b 46 31 32 39  ommit Mode {F129
340e0 33 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  30}.**.** The sq
340f0 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f  lite3_get_autoco
34100 6d 6d 69 74 28 29 20 69 6e 74 65 72 66 61 63 65  mmit() interface
34110 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
34120 6f 20 6f 72 0a 2a 2a 20 7a 65 72 6f 20 69 66 20  o or.** zero if 
34130 74 68 65 20 67 69 76 65 6e 20 64 61 74 61 62 61  the given databa
34140 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
34150 20 6f 72 20 69 73 20 6e 6f 74 20 69 6e 20 61 75   or is not in au
34160 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 2c 0a 2a  tocommit mode,.*
34170 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20  * respectively. 
34180 20 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64    Autocommit mod
34190 65 20 69 73 20 6f 6e 0a 2a 2a 20 62 79 20 64 65  e is on.** by de
341a0 66 61 75 6c 74 2e 20 20 41 75 74 6f 63 6f 6d 6d  fault.  Autocomm
341b0 69 74 20 6d 6f 64 65 20 69 73 20 64 69 73 61 62  it mode is disab
341c0 6c 65 64 20 62 79 20 61 20 5b 42 45 47 49 4e 5d  led by a [BEGIN]
341d0 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 41   statement..** A
341e0 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69  utocommit mode i
341f0 73 20 72 65 2d 65 6e 61 62 6c 65 64 20 62 79 20  s re-enabled by 
34200 61 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52  a [COMMIT] or [R
34210 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20  OLLBACK]..**.** 
34220 49 66 20 63 65 72 74 61 69 6e 20 6b 69 6e 64 73  If certain kinds
34230 20 6f 66 20 65 72 72 6f 72 73 20 6f 63 63 75 72   of errors occur
34240 20 6f 6e 20 61 20 73 74 61 74 65 6d 65 6e 74 20   on a statement 
34250 77 69 74 68 69 6e 20 61 20 6d 75 6c 74 69 2d 73  within a multi-s
34260 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 72 61 6e  tatement.** tran
34270 73 61 63 74 69 6f 6e 73 20 28 65 72 72 6f 72 73  sactions (errors
34280 20 69 6e 63 6c 75 64 69 6e 67 20 5b 53 51 4c 49   including [SQLI
34290 54 45 5f 46 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54  TE_FULL], [SQLIT
342a0 45 5f 49 4f 45 52 52 5d 2c 20 0a 2a 2a 20 5b 53  E_IOERR], .** [S
342b0 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53  QLITE_NOMEM], [S
342c0 51 4c 49 54 45 5f 42 55 53 59 5d 2c 20 61 6e 64  QLITE_BUSY], and
342d0 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55   [SQLITE_INTERRU
342e0 50 54 5d 29 20 74 68 65 6e 20 74 68 65 0a 2a 2a  PT]) then the.**
342f0 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6d 69 67   transaction mig
34300 68 74 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63  ht be rolled bac
34310 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e  k automatically.
34320 20 20 54 68 65 20 6f 6e 6c 79 20 77 61 79 20 74    The only way t
34330 6f 0a 2a 2a 20 66 69 6e 64 20 6f 75 74 20 69 66  o.** find out if
34340 20 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69   SQLite automati
34350 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63  cally rolled bac
34360 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f  k the transactio
34370 6e 20 61 66 74 65 72 0a 2a 2a 20 61 6e 20 65 72  n after.** an er
34380 72 6f 72 20 69 73 20 74 6f 20 75 73 65 20 74 68  ror is to use th
34390 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a  is function..**.
343a0 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
343b0 2a 0a 2a 2a 20 7b 46 31 32 39 33 31 7d 20 54 68  *.** {F12931} Th
343c0 65 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  e [sqlite3_get_a
343d0 75 74 6f 63 6f 6d 6d 69 74 28 44 29 5d 20 69 6e  utocommit(D)] in
343e0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
343f0 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20 20  non-zero or.**  
34400 20 20 20 20 20 20 20 20 7a 65 72 6f 20 69 66 20          zero if 
34410 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
34420 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 69 73 20 6f  nnection] D is o
34430 72 20 69 73 20 6e 6f 74 20 69 6e 20 61 75 74 6f  r is not in auto
34440 63 6f 6d 6d 69 74 0a 2a 2a 20 20 20 20 20 20 20  commit.**       
34450 20 20 20 6d 6f 64 65 2c 20 72 65 73 70 65 63 74     mode, respect
34460 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  ively..**.** {F1
34470 32 39 33 32 7d 20 41 75 74 6f 63 6f 6d 6d 69 74  2932} Autocommit
34480 20 6d 6f 64 65 20 69 73 20 6f 6e 20 62 79 20 64   mode is on by d
34490 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46  efault..**.** {F
344a0 31 32 39 33 33 7d 20 41 75 74 6f 63 6f 6d 6d 69  12933} Autocommi
344b0 74 20 6d 6f 64 65 20 69 73 20 64 69 73 61 62 6c  t mode is disabl
344c0 65 64 20 62 79 20 61 20 73 75 63 63 65 73 73 66  ed by a successf
344d0 75 6c 20 5b 42 45 47 49 4e 5d 20 73 74 61 74 65  ul [BEGIN] state
344e0 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  ment..**.** {F12
344f0 39 33 34 7d 20 41 75 74 6f 63 6f 6d 6d 69 74 20  934} Autocommit 
34500 6d 6f 64 65 20 69 73 20 65 6e 61 62 6c 65 64 20  mode is enabled 
34510 62 79 20 61 20 73 75 63 63 65 73 73 66 75 6c 20  by a successful 
34520 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f 4c  [COMMIT] or [ROL
34530 4c 42 41 43 4b 5d 0a 2a 2a 20 20 20 20 20 20 20  LBACK].**       
34540 20 20 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a     statement..**
34550 20 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49 54 41 54 49   .**.** LIMITATI
34560 4f 4e 53 3a 0a 2a 2a 2a 0a 2a 2a 20 7b 55 31 32  ONS:.***.** {U12
34570 39 33 36 7d 20 49 66 20 61 6e 6f 74 68 65 72 20  936} If another 
34580 74 68 72 65 61 64 20 63 68 61 6e 67 65 73 20 74  thread changes t
34590 68 65 20 61 75 74 6f 63 6f 6d 6d 69 74 20 73 74  he autocommit st
345a0 61 74 75 73 20 6f 66 20 74 68 65 20 64 61 74 61  atus of the data
345b0 62 61 73 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  base.**         
345c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c   connection whil
345d0 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69  e this routine i
345e0 73 20 72 75 6e 6e 69 6e 67 2c 20 74 68 65 6e 20  s running, then 
345f0 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
34600 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20  .**          is 
34610 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e  undefined..*/.in
34620 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75  t sqlite3_get_au
34630 74 6f 63 6f 6d 6d 69 74 28 73 71 6c 69 74 65 33  tocommit(sqlite3
34640 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
34650 52 45 46 3a 20 20 46 69 6e 64 20 54 68 65 20 44  REF:  Find The D
34660 61 74 61 62 61 73 65 20 48 61 6e 64 6c 65 20 4f  atabase Handle O
34670 66 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  f A Prepared Sta
34680 74 65 6d 65 6e 74 20 7b 46 31 33 31 32 30 7d 0a  tement {F13120}.
34690 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
346a0 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69 6e 74 65  3_db_handle inte
346b0 72 66 61 63 65 0a 2a 2a 20 72 65 74 75 72 6e 73  rface.** returns
346c0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 2a 5d 20   the [sqlite3*] 
346d0 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  database handle 
346e0 74 6f 20 77 68 69 63 68 20 61 0a 2a 2a 20 5b 70  to which a.** [p
346f0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
34700 74 5d 20 62 65 6c 6f 6e 67 73 2e 0a 2a 2a 20 54  t] belongs..** T
34710 68 65 20 64 61 74 61 62 61 73 65 20 68 61 6e 64  he database hand
34720 6c 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  le returned by s
34730 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65  qlite3_db_handle
34740 0a 2a 2a 20 69 73 20 74 68 65 20 73 61 6d 65 20  .** is the same 
34750 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  database handle 
34760 74 68 61 74 20 77 61 73 0a 2a 2a 20 74 68 65 20  that was.** the 
34770 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
34780 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70  o the [sqlite3_p
34790 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
347a0 69 74 73 20 76 61 72 69 61 6e 74 73 0a 2a 2a 20  its variants.** 
347b0 74 68 61 74 20 77 61 73 20 75 73 65 64 20 74 6f  that was used to
347c0 20 63 72 65 61 74 65 20 74 68 65 20 73 74 61 74   create the stat
347d0 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 66 69 72  ement in the fir
347e0 73 74 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  st place..**.** 
347f0 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
34800 2a 20 7b 46 31 33 31 32 33 7d 20 54 68 65 20 5b  * {F13123} The [
34810 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c  sqlite3_db_handl
34820 65 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20  e(S)] interface 
34830 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
34840 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f  r.**          to
34850 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
34860 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 73 73 6f 63  onnection] assoc
34870 69 61 74 65 64 20 77 69 74 68 0a 2a 2a 20 20 20  iated with.**   
34880 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64         [prepared
34890 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a   statement] S..*
348a0 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74  /.sqlite3 *sqlit
348b0 65 33 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c  e3_db_handle(sql
348c0 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a  ite3_stmt*);../*
348d0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 46  .** CAPI3REF:  F
348e0 69 6e 64 20 74 68 65 20 6e 65 78 74 20 70 72 65  ind the next pre
348f0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
34900 7b 46 31 33 31 34 30 7d 0a 2a 2a 0a 2a 2a 20 52  {F13140}.**.** R
34910 65 74 75 72 6e 20 61 20 70 6f 69 6e 74 65 72 20  eturn a pointer 
34920 74 6f 20 74 68 65 20 6e 65 78 74 20 5b 70 72 65  to the next [pre
34930 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
34940 20 61 66 74 65 72 20 70 53 74 6d 74 0a 2a 2a 20   after pStmt.** 
34950 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
34960 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
34970 74 69 6f 6e 5d 20 70 44 62 2e 20 20 49 66 20 70  tion] pDb.  If p
34980 53 74 6d 74 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20  Stmt is NULL.** 
34990 74 68 65 6e 20 72 65 74 75 72 6e 20 61 20 70 6f  then return a po
349a0 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66 69 72  inter to the fir
349b0 73 74 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  st [prepared sta
349c0 74 65 6d 65 6e 74 5d 20 61 73 73 6f 63 69 61 74  tement] associat
349d0 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b  ed.** with the [
349e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
349f0 69 6f 6e 5d 20 70 44 62 2e 20 20 49 66 20 6e 6f  ion] pDb.  If no
34a00 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
34a10 6d 65 6e 74 5d 0a 2a 2a 20 73 61 74 69 73 66 69  ment].** satisfi
34a20 65 73 20 74 68 65 20 63 6f 6e 64 69 74 69 6f 6e  es the condition
34a30 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e  s of this routin
34a40 65 2c 20 72 65 74 75 72 6e 20 4e 55 4c 4c 2e 0a  e, return NULL..
34a50 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
34a60 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 31 34 33 7d  :.**.** {F13143}
34a70 20 49 66 20 44 20 69 73 20 61 20 5b 64 61 74 61   If D is a [data
34a80 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
34a90 20 74 68 61 74 20 68 6f 6c 64 73 20 6f 6e 65 20   that holds one 
34aa0 6f 72 20 6d 6f 72 65 0a 2a 2a 20 20 20 20 20 20  or more.**      
34ab0 20 20 20 20 75 6e 66 69 6e 61 6c 69 7a 65 64 20      unfinalized 
34ac0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
34ad0 65 6e 74 73 5d 20 61 6e 64 20 53 20 69 73 20 61  ents] and S is a
34ae0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 0a 2a   NULL pointer,.*
34af0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20  *          then 
34b00 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74  [sqlite3_next_st
34b10 6d 74 28 44 2c 20 53 29 5d 20 72 6f 75 74 69 6e  mt(D, S)] routin
34b20 65 20 73 68 61 6c 6c 20 72 65 74 75 72 6e 20 61  e shall return a
34b30 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 20 20 20 20   pointer.**     
34b40 20 20 20 20 20 74 6f 20 6f 6e 65 20 6f 66 20 74       to one of t
34b50 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
34b60 74 65 6d 65 6e 74 73 5d 20 61 73 73 6f 63 69 61  tements] associa
34b70 74 65 64 20 77 69 74 68 20 44 2e 0a 2a 2a 0a 2a  ted with D..**.*
34b80 2a 20 7b 46 31 33 31 34 36 7d 20 49 66 20 44 20  * {F13146} If D 
34b90 69 73 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  is a [database c
34ba0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 20  onnection] that 
34bb0 68 6f 6c 64 73 20 6e 6f 0a 2a 2a 20 20 20 20 20  holds no.**     
34bc0 20 20 20 20 20 75 6e 66 69 6e 61 6c 69 7a 65 64       unfinalized
34bd0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
34be0 6d 65 6e 74 73 5d 20 61 6e 64 20 53 20 69 73 20  ments] and S is 
34bf0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 0a  a NULL pointer,.
34c00 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e  **          then
34c10 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73   [sqlite3_next_s
34c20 74 6d 74 28 44 2c 20 53 29 5d 20 72 6f 75 74 69  tmt(D, S)] routi
34c30 6e 65 20 73 68 61 6c 6c 20 72 65 74 75 72 6e 20  ne shall return 
34c40 61 20 4e 55 4c 4c 0a 2a 2a 20 20 20 20 20 20 20  a NULL.**       
34c50 20 20 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a     pointer..**.*
34c60 2a 20 7b 46 31 33 31 34 39 7d 20 49 66 20 53 20  * {F13149} If S 
34c70 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  is a [prepared s
34c80 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 5b 64 61  tatement] in [da
34c90 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
34ca0 6e 5d 20 44 0a 2a 2a 20 20 20 20 20 20 20 20 20  n] D.**         
34cb0 20 61 6e 64 20 53 20 69 73 20 6e 6f 74 20 74 68   and S is not th
34cc0 65 20 6c 61 73 74 20 5b 70 72 65 70 61 72 65 64  e last [prepared
34cd0 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 44   statement] in D
34ce0 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20  , then.**       
34cf0 20 20 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74     [sqlite3_next
34d00 5f 73 74 6d 74 28 44 2c 20 53 29 5d 20 72 6f 75  _stmt(D, S)] rou
34d10 74 69 6e 65 20 73 68 61 6c 6c 20 72 65 74 75 72  tine shall retur
34d20 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 20  n a pointer.**  
34d30 20 20 20 20 20 20 20 20 74 6f 20 74 68 65 20 6e          to the n
34d40 65 78 74 20 5b 70 72 65 70 61 72 65 64 20 73 74  ext [prepared st
34d50 61 74 65 6d 65 6e 74 5d 20 69 6e 20 44 20 61 66  atement] in D af
34d60 74 65 72 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  ter S..**.** {F1
34d70 33 31 35 32 7d 20 49 66 20 53 20 69 73 20 74 68  3152} If S is th
34d80 65 20 6c 61 73 74 20 5b 70 72 65 70 61 72 65 64  e last [prepared
34d90 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 5b   statement] in [
34da0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
34db0 69 6f 6e 5d 20 44 0a 2a 2a 20 20 20 20 20 20 20  ion] D.**       
34dc0 20 20 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33     then [sqlite3
34dd0 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c 20 53 29  _next_stmt(D, S)
34de0 5d 20 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20  ] routine shall 
34df0 72 65 74 75 72 6e 20 61 20 4e 55 4c 4c 0a 2a 2a  return a NULL.**
34e00 20 20 20 20 20 20 20 20 20 20 70 6f 69 6e 74 65            pointe
34e10 72 2e 0a 2a 2a 0a 2a 2f 0a 73 71 6c 69 74 65 33  r..**.*/.sqlite3
34e20 5f 73 74 6d 74 20 2a 73 71 6c 69 74 65 33 5f 6e  _stmt *sqlite3_n
34e30 65 78 74 5f 73 74 6d 74 28 73 71 6c 69 74 65 33  ext_stmt(sqlite3
34e40 20 2a 70 44 62 2c 20 73 71 6c 69 74 65 33 5f 73   *pDb, sqlite3_s
34e50 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 0a 2f  tmt *pStmt);.../
34e60 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
34e70 6f 6d 6d 69 74 20 41 6e 64 20 52 6f 6c 6c 62 61  ommit And Rollba
34e80 63 6b 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20  ck Notification 
34e90 43 61 6c 6c 62 61 63 6b 73 20 7b 46 31 32 39 35  Callbacks {F1295
34ea0 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  0}.**.** The sql
34eb0 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b  ite3_commit_hook
34ec0 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67  () interface reg
34ed0 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63  isters a callbac
34ee0 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f  k.** function to
34ef0 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   be invoked when
34f00 65 76 65 72 20 61 20 74 72 61 6e 73 61 63 74 69  ever a transacti
34f10 6f 6e 20 69 73 20 63 6f 6d 6d 69 74 74 65 64 2e  on is committed.
34f20 0a 2a 2a 20 41 6e 79 20 63 61 6c 6c 62 61 63 6b  .** Any callback
34f30 20 73 65 74 20 62 79 20 61 20 70 72 65 76 69 6f   set by a previo
34f40 75 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  us call to sqlit
34f50 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29  e3_commit_hook()
34f60 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65  .** for the same
34f70 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
34f80 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64  tion is overridd
34f90 65 6e 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  en..** The sqlit
34fa0 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b  e3_rollback_hook
34fb0 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67  () interface reg
34fc0 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63  isters a callbac
34fd0 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f  k.** function to
34fe0 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   be invoked when
34ff0 65 76 65 72 20 61 20 74 72 61 6e 73 61 63 74 69  ever a transacti
35000 6f 6e 20 69 73 20 63 6f 6d 6d 69 74 74 65 64 2e  on is committed.
35010 0a 2a 2a 20 41 6e 79 20 63 61 6c 6c 62 61 63 6b  .** Any callback
35020 20 73 65 74 20 62 79 20 61 20 70 72 65 76 69 6f   set by a previo
35030 75 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  us call to sqlit
35040 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29  e3_commit_hook()
35050 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65  .** for the same
35060 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
35070 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64  tion is overridd
35080 65 6e 2e 0a 2a 2a 20 54 68 65 20 70 41 72 67 20  en..** The pArg 
35090 61 72 67 75 6d 65 6e 74 20 69 73 20 70 61 73 73  argument is pass
350a0 65 64 20 74 68 72 6f 75 67 68 0a 2a 2a 20 74 6f  ed through.** to
350b0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 20 20   the callback.  
350c0 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  If the callback 
350d0 6f 6e 20 61 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b  on a commit hook
350e0 20 66 75 6e 63 74 69 6f 6e 20 0a 2a 2a 20 72 65   function .** re
350f0 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  turns non-zero, 
35100 74 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20  then the commit 
35110 69 73 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74  is converted int
35120 6f 20 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a  o a rollback..**
35130 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72 20 66  .** If another f
35140 75 6e 63 74 69 6f 6e 20 77 61 73 20 70 72 65 76  unction was prev
35150 69 6f 75 73 6c 79 20 72 65 67 69 73 74 65 72 65  iously registere
35160 64 2c 20 69 74 73 0a 2a 2a 20 70 41 72 67 20 76  d, its.** pArg v
35170 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 64  alue is returned
35180 2e 20 20 4f 74 68 65 72 77 69 73 65 20 4e 55 4c  .  Otherwise NUL
35190 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  L is returned..*
351a0 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 69 6e 67  *.** Registering
351b0 20 61 20 4e 55 4c 4c 20 66 75 6e 63 74 69 6f 6e   a NULL function
351c0 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 63 61   disables the ca
351d0 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 46 6f  llback..**.** Fo
351e0 72 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f  r the purposes o
351f0 66 20 74 68 69 73 20 41 50 49 2c 20 61 20 74 72  f this API, a tr
35200 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 73 61 69  ansaction is sai
35210 64 20 74 6f 20 68 61 76 65 20 62 65 65 6e 20 0a  d to have been .
35220 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 69  ** rolled back i
35230 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 22 52  f an explicit "R
35240 4f 4c 4c 42 41 43 4b 22 20 73 74 61 74 65 6d 65  OLLBACK" stateme
35250 6e 74 20 69 73 20 65 78 65 63 75 74 65 64 2c 20  nt is executed, 
35260 6f 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 6f  or.** an error o
35270 72 20 63 6f 6e 73 74 72 61 69 6e 74 20 63 61 75  r constraint cau
35280 73 65 73 20 61 6e 20 69 6d 70 6c 69 63 69 74 20  ses an implicit 
35290 72 6f 6c 6c 62 61 63 6b 20 74 6f 20 6f 63 63 75  rollback to occu
352a0 72 2e 0a 2a 2a 20 54 68 65 20 72 6f 6c 6c 62 61  r..** The rollba
352b0 63 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e  ck callback is n
352c0 6f 74 20 69 6e 76 6f 6b 65 64 20 69 66 20 61 20  ot invoked if a 
352d0 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 0a 2a  transaction is.*
352e0 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  * automatically 
352f0 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62 65 63 61  rolled back beca
35300 75 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65  use the database
35310 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63   connection is c
35320 6c 6f 73 65 64 2e 0a 2a 2a 20 54 68 65 20 72 6f  losed..** The ro
35330 6c 6c 62 61 63 6b 20 63 61 6c 6c 62 61 63 6b 20  llback callback 
35340 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69  is not invoked i
35350 66 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  f a transaction 
35360 69 73 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63  is.** rolled bac
35370 6b 20 62 65 63 61 75 73 65 20 61 20 63 6f 6d 6d  k because a comm
35380 69 74 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  it callback retu
35390 72 6e 65 64 20 6e 6f 6e 2d 7a 65 72 6f 2e 0a 2a  rned non-zero..*
353a0 2a 20 3c 74 6f 64 6f 3e 20 43 68 65 63 6b 20 6f  * <todo> Check o
353b0 6e 20 74 68 69 73 20 3c 2f 74 6f 64 6f 3e 0a 2a  n this </todo>.*
353c0 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 65  *.** These are e
353d0 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65  xperimental inte
353e0 72 66 61 63 65 73 20 61 6e 64 20 61 72 65 20 73  rfaces and are s
353f0 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65  ubject to change
35400 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
35410 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 35  TS:.**.** {F1295
35420 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
35430 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c 46 2c  commit_hook(D,F,
35440 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  P)] interface re
35450 67 69 73 74 65 72 73 20 74 68 65 0a 2a 2a 20 20  gisters the.**  
35460 20 20 20 20 20 20 20 20 63 61 6c 6c 62 61 63 6b          callback
35470 20 66 75 6e 63 74 69 6f 6e 20 46 20 74 6f 20 62   function F to b
35480 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61  e invoked with a
35490 72 67 75 6d 65 6e 74 20 50 20 77 68 65 6e 65 76  rgument P whenev
354a0 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  er.**          a
354b0 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6d   transaction com
354c0 6d 69 74 73 20 6f 6e 20 5b 64 61 74 61 62 61 73  mits on [databas
354d0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e  e connection] D.
354e0 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 35 32 7d 20  .**.** {F12952} 
354f0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d  The [sqlite3_com
35500 6d 69 74 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d  mit_hook(D,F,P)]
35510 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
35520 6e 73 20 74 68 65 20 50 0a 2a 2a 20 20 20 20 20  ns the P.**     
35530 20 20 20 20 20 61 72 67 75 6d 65 6e 74 20 66 72       argument fr
35540 6f 6d 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  om the previous 
35550 63 61 6c 6c 20 77 69 74 68 20 74 68 65 20 73 61  call with the sa
35560 6d 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  me .**          
35570 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
35580 74 69 6f 6e 20 5d 20 44 20 2c 20 6f 72 20 4e 55  tion ] D , or NU
35590 4c 4c 20 6f 6e 20 74 68 65 20 66 69 72 73 74 20  LL on the first 
355a0 63 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20  call.**         
355b0 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61   for a particula
355c0 72 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  r [database conn
355d0 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a  ection] D..**.**
355e0 20 7b 46 31 32 39 35 33 7d 20 45 61 63 68 20 63   {F12953} Each c
355f0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
35600 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 5d 20 6f  commit_hook()] o
35610 76 65 72 77 72 69 74 65 73 20 74 68 65 20 63 61  verwrites the ca
35620 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20  llback.**       
35630 20 20 20 72 65 67 69 73 74 65 72 65 64 20 62 79     registered by
35640 20 70 72 69 6f 72 20 63 61 6c 6c 73 2e 0a 2a 2a   prior calls..**
35650 0a 2a 2a 20 7b 46 31 32 39 35 34 7d 20 49 66 20  .** {F12954} If 
35660 74 68 65 20 46 20 61 72 67 75 6d 65 6e 74 20 74  the F argument t
35670 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69  o [sqlite3_commi
35680 74 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69  t_hook(D,F,P)] i
35690 73 20 4e 55 4c 4c 0a 2a 2a 20 20 20 20 20 20 20  s NULL.**       
356a0 20 20 20 74 68 65 6e 20 74 68 65 20 63 6f 6d 6d     then the comm
356b0 69 74 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b  it hook callback
356c0 20 69 73 20 63 61 6e 63 65 6c 65 64 20 61 6e 64   is canceled and
356d0 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20   no callback.** 
356e0 20 20 20 20 20 20 20 20 20 69 73 20 69 6e 76 6f           is invo
356f0 6b 65 64 20 77 68 65 6e 20 61 20 74 72 61 6e 73  ked when a trans
35700 61 63 74 69 6f 6e 20 63 6f 6d 6d 69 74 73 2e 0a  action commits..
35710 2a 2a 0a 2a 2a 20 7b 46 31 32 39 35 35 7d 20 49  **.** {F12955} I
35720 66 20 74 68 65 20 63 6f 6d 6d 69 74 20 63 61 6c  f the commit cal
35730 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f  lback returns no
35740 6e 2d 7a 65 72 6f 20 74 68 65 6e 20 74 68 65 20  n-zero then the 
35750 63 6f 6d 6d 69 74 20 69 73 0a 2a 2a 20 20 20 20  commit is.**    
35760 20 20 20 20 20 20 63 6f 6e 76 65 72 74 65 64 20        converted 
35770 69 6e 74 6f 20 61 20 72 6f 6c 6c 62 61 63 6b 2e  into a rollback.
35780 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 36 31 7d 20  .**.** {F12961} 
35790 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 6f 6c  The [sqlite3_rol
357a0 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c 46 2c 50  lback_hook(D,F,P
357b0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67  )] interface reg
357c0 69 73 74 65 72 73 20 74 68 65 0a 2a 2a 20 20 20  isters the.**   
357d0 20 20 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 20         callback 
357e0 66 75 6e 63 74 69 6f 6e 20 46 20 74 6f 20 62 65  function F to be
357f0 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 72   invoked with ar
35800 67 75 6d 65 6e 74 20 50 20 77 68 65 6e 65 76 65  gument P wheneve
35810 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20  r.**          a 
35820 74 72 61 6e 73 61 63 74 69 6f 6e 20 72 6f 6c 6c  transaction roll
35830 73 20 62 61 63 6b 20 6f 6e 20 5b 64 61 74 61 62  s back on [datab
35840 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
35850 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 36 32  D..**.** {F12962
35860 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  } The [sqlite3_r
35870 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c 46  ollback_hook(D,F
35880 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  ,P)] interface r
35890 65 74 75 72 6e 73 20 74 68 65 20 50 0a 2a 2a 20  eturns the P.** 
358a0 20 20 20 20 20 20 20 20 20 61 72 67 75 6d 65 6e           argumen
358b0 74 20 66 72 6f 6d 20 74 68 65 20 70 72 65 76 69  t from the previ
358c0 6f 75 73 20 63 61 6c 6c 20 77 69 74 68 20 74 68  ous call with th
358d0 65 20 73 61 6d 65 20 0a 2a 2a 20 20 20 20 20 20  e same .**      
358e0 20 20 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f      [database co
358f0 6e 6e 65 63 74 69 6f 6e 20 5d 20 44 20 2c 20 6f  nnection ] D , o
35900 72 20 4e 55 4c 4c 20 6f 6e 20 74 68 65 20 66 69  r NULL on the fi
35910 72 73 74 20 63 61 6c 6c 0a 2a 2a 20 20 20 20 20  rst call.**     
35920 20 20 20 20 20 66 6f 72 20 61 20 70 61 72 74 69       for a parti
35930 63 75 6c 61 72 20 5b 64 61 74 61 62 61 73 65 20  cular [database 
35940 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a  connection] D..*
35950 2a 0a 2a 2a 20 7b 46 31 32 39 36 33 7d 20 45 61  *.** {F12963} Ea
35960 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ch call to [sqli
35970 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f  te3_rollback_hoo
35980 6b 28 29 5d 20 6f 76 65 72 77 72 69 74 65 73 20  k()] overwrites 
35990 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  the callback.** 
359a0 20 20 20 20 20 20 20 20 20 72 65 67 69 73 74 65           registe
359b0 72 65 64 20 62 79 20 70 72 69 6f 72 20 63 61 6c  red by prior cal
359c0 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 36  ls..**.** {F1296
359d0 34 7d 20 49 66 20 74 68 65 20 46 20 61 72 67 75  4} If the F argu
359e0 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  ment to [sqlite3
359f0 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44  _rollback_hook(D
35a00 2c 46 2c 50 29 5d 20 69 73 20 4e 55 4c 4c 0a 2a  ,F,P)] is NULL.*
35a10 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20  *          then 
35a20 74 68 65 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f  the rollback hoo
35a30 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 63 61  k callback is ca
35a40 6e 63 65 6c 65 64 20 61 6e 64 20 6e 6f 20 63 61  nceled and no ca
35a50 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20  llback.**       
35a60 20 20 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68     is invoked wh
35a70 65 6e 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  en a transaction
35a80 20 72 6f 6c 6c 73 20 62 61 63 6b 2e 0a 2a 2f 0a   rolls back..*/.
35a90 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
35aa0 6d 6d 69 74 5f 68 6f 6f 6b 28 73 71 6c 69 74 65  mmit_hook(sqlite
35ab0 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a  3*, int(*)(void*
35ac0 29 2c 20 76 6f 69 64 2a 29 3b 0a 76 6f 69 64 20  ), void*);.void 
35ad0 2a 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63  *sqlite3_rollbac
35ae0 6b 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c  k_hook(sqlite3*,
35af0 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 29   void(*)(void *)
35b00 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  , void*);../*.**
35b10 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 20   CAPI3REF: Data 
35b20 43 68 61 6e 67 65 20 4e 6f 74 69 66 69 63 61 74  Change Notificat
35b30 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 20 7b 46  ion Callbacks {F
35b40 31 32 39 37 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  12970}.**.** The
35b50 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f   sqlite3_update_
35b60 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65  hook() interface
35b70 0a 2a 2a 20 72 65 67 69 73 74 65 72 73 20 61 20  .** registers a 
35b80 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
35b90 6e 20 77 69 74 68 20 74 68 65 20 64 61 74 61 62  n with the datab
35ba0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
35bb0 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65  dentified by the
35bc0 20 0a 2a 2a 20 66 69 72 73 74 20 61 72 67 75 6d   .** first argum
35bd0 65 6e 74 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65  ent to be invoke
35be0 64 20 77 68 65 6e 65 76 65 72 20 61 20 72 6f 77  d whenever a row
35bf0 20 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73   is updated, ins
35c00 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64  erted or deleted
35c10 2e 0a 2a 2a 20 41 6e 79 20 63 61 6c 6c 62 61 63  ..** Any callbac
35c20 6b 20 73 65 74 20 62 79 20 61 20 70 72 65 76 69  k set by a previ
35c30 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73  ous call to this
35c40 20 66 75 6e 63 74 69 6f 6e 20 66 6f 72 20 74 68   function for th
35c50 65 20 73 61 6d 65 20 0a 2a 2a 20 64 61 74 61 62  e same .** datab
35c60 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
35c70 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a  s overridden..**
35c80 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61  .** The second a
35c90 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
35ca0 6e 74 65 72 20 74 6f 20 74 68 65 20 66 75 6e 63  nter to the func
35cb0 74 69 6f 6e 20 74 6f 20 69 6e 76 6f 6b 65 20 77  tion to invoke w
35cc0 68 65 6e 20 61 20 0a 2a 2a 20 72 6f 77 20 69 73  hen a .** row is
35cd0 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72 74   updated, insert
35ce0 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 20 0a  ed or deleted. .
35cf0 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
35d00 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 61 6c  ument to the cal
35d10 6c 62 61 63 6b 20 69 73 0a 2a 2a 20 61 20 63 6f  lback is.** a co
35d20 70 79 20 6f 66 20 74 68 65 20 74 68 69 72 64 20  py of the third 
35d30 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
35d40 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28  te3_update_hook(
35d50 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  )..** The second
35d60 20 63 61 6c 6c 62 61 63 6b 20 0a 2a 2a 20 61 72   callback .** ar
35d70 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66  gument is one of
35d80 20 5b 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 5d   [SQLITE_INSERT]
35d90 2c 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45  , [SQLITE_DELETE
35da0 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 50 44  ] or [SQLITE_UPD
35db0 41 54 45 5d 2c 0a 2a 2a 20 64 65 70 65 6e 64 69  ATE],.** dependi
35dc0 6e 67 20 6f 6e 20 74 68 65 20 6f 70 65 72 61 74  ng on the operat
35dd0 69 6f 6e 20 74 68 61 74 20 63 61 75 73 65 64 20  ion that caused 
35de0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20  the callback to 
35df0 62 65 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 54  be invoked..** T
35e00 68 65 20 74 68 69 72 64 20 61 6e 64 20 0a 2a 2a  he third and .**
35e10 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
35e20 73 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  s to the callbac
35e30 6b 20 63 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65  k contain pointe
35e40 72 73 20 74 6f 20 74 68 65 20 64 61 74 61 62 61  rs to the databa
35e50 73 65 20 61 6e 64 20 0a 2a 2a 20 74 61 62 6c 65  se and .** table
35e60 20 6e 61 6d 65 20 63 6f 6e 74 61 69 6e 69 6e 67   name containing
35e70 20 74 68 65 20 61 66 66 65 63 74 65 64 20 72 6f   the affected ro
35e80 77 2e 0a 2a 2a 20 54 68 65 20 66 69 6e 61 6c 20  w..** The final 
35e90 63 61 6c 6c 62 61 63 6b 20 70 61 72 61 6d 65 74  callback paramet
35ea0 65 72 20 69 73 20 0a 2a 2a 20 74 68 65 20 72 6f  er is .** the ro
35eb0 77 69 64 20 6f 66 20 74 68 65 20 72 6f 77 2e 0a  wid of the row..
35ec0 2a 2a 20 49 6e 20 74 68 65 20 63 61 73 65 20 6f  ** In the case o
35ed0 66 20 61 6e 20 75 70 64 61 74 65 2c 20 74 68 69  f an update, thi
35ee0 73 20 69 73 20 74 68 65 20 72 6f 77 69 64 20 61  s is the rowid a
35ef0 66 74 65 72 20 0a 2a 2a 20 74 68 65 20 75 70 64  fter .** the upd
35f00 61 74 65 20 74 61 6b 65 73 20 70 6c 61 63 65 2e  ate takes place.
35f10 0a 2a 2a 0a 2a 2a 20 54 68 65 20 75 70 64 61 74  .**.** The updat
35f20 65 20 68 6f 6f 6b 20 69 73 20 6e 6f 74 20 69 6e  e hook is not in
35f30 76 6f 6b 65 64 20 77 68 65 6e 20 69 6e 74 65 72  voked when inter
35f40 6e 61 6c 20 73 79 73 74 65 6d 20 74 61 62 6c 65  nal system table
35f50 73 20 61 72 65 0a 2a 2a 20 6d 6f 64 69 66 69 65  s are.** modifie
35f60 64 20 28 69 2e 65 2e 20 73 71 6c 69 74 65 5f 6d  d (i.e. sqlite_m
35f70 61 73 74 65 72 20 61 6e 64 20 73 71 6c 69 74 65  aster and sqlite
35f80 5f 73 65 71 75 65 6e 63 65 29 2e 0a 2a 2a 0a 2a  _sequence)..**.*
35f90 2a 20 49 66 20 61 6e 6f 74 68 65 72 20 66 75 6e  * If another fun
35fa0 63 74 69 6f 6e 20 77 61 73 20 70 72 65 76 69 6f  ction was previo
35fb0 75 73 6c 79 20 72 65 67 69 73 74 65 72 65 64 2c  usly registered,
35fc0 20 69 74 73 20 70 41 72 67 20 76 61 6c 75 65 0a   its pArg value.
35fd0 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  ** is returned. 
35fe0 20 4f 74 68 65 72 77 69 73 65 20 4e 55 4c 4c 20   Otherwise NULL 
35ff0 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
36000 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
36010 2a 0a 2a 2a 20 7b 46 31 32 39 37 31 7d 20 54 68  *.** {F12971} Th
36020 65 20 5b 73 71 6c 69 74 65 33 5f 75 70 64 61 74  e [sqlite3_updat
36030 65 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69  e_hook(D,F,P)] i
36040 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20  nterface causes 
36050 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20  callback.**     
36060 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 20 46 20       function F 
36070 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69  to be invoked wi
36080 74 68 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  th first paramet
36090 65 72 20 50 20 77 68 65 6e 65 76 65 72 0a 2a 2a  er P whenever.**
360a0 20 20 20 20 20 20 20 20 20 20 61 20 74 61 62 6c            a tabl
360b0 65 20 72 6f 77 20 69 73 20 6d 6f 64 69 66 69 65  e row is modifie
360c0 64 2c 20 69 6e 73 65 72 74 65 64 2c 20 6f 72 20  d, inserted, or 
360d0 64 65 6c 65 74 65 64 20 6f 6e 0a 2a 2a 20 20 20  deleted on.**   
360e0 20 20 20 20 20 20 20 5b 64 61 74 61 62 61 73 65         [database
360f0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a   connection] D..
36100 2a 2a 0a 2a 2a 20 7b 46 31 32 39 37 33 7d 20 54  **.** {F12973} T
36110 68 65 20 5b 73 71 6c 69 74 65 33 5f 75 70 64 61  he [sqlite3_upda
36120 74 65 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20  te_hook(D,F,P)] 
36130 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
36140 73 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 20  s the value.**  
36150 20 20 20 20 20 20 20 20 6f 66 20 50 20 66 6f 72          of P for
36160 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61   the previous ca
36170 6c 6c 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b  ll on the same [
36180 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
36190 69 6f 6e 5d 20 44 2c 0a 2a 2a 20 20 20 20 20 20  ion] D,.**      
361a0 20 20 20 20 6f 72 20 4e 55 4c 4c 20 66 6f 72 20      or NULL for 
361b0 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 2e 0a  the first call..
361c0 2a 2a 0a 2a 2a 20 7b 46 31 32 39 37 35 7d 20 49  **.** {F12975} I
361d0 66 20 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f  f the update hoo
361e0 6b 20 63 61 6c 6c 62 61 63 6b 20 46 20 69 6e 20  k callback F in 
361f0 5b 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f  [sqlite3_update_
36200 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 0a 2a 2a 20  hook(D,F,P)].** 
36210 20 20 20 20 20 20 20 20 20 69 73 20 4e 55 4c 4c           is NULL
36220 20 74 68 65 6e 20 74 68 65 20 6e 6f 20 75 70 64   then the no upd
36230 61 74 65 20 63 61 6c 6c 62 61 63 6b 73 20 61 72  ate callbacks ar
36240 65 20 6d 61 64 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46  e made..**.** {F
36250 31 32 39 37 37 7d 20 45 61 63 68 20 63 61 6c 6c  12977} Each call
36260 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 75 70 64   to [sqlite3_upd
36270 61 74 65 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d  ate_hook(D,F,P)]
36280 20 6f 76 65 72 72 69 64 65 73 20 70 72 69 6f 72   overrides prior
36290 20 63 61 6c 6c 73 0a 2a 2a 20 20 20 20 20 20 20   calls.**       
362a0 20 20 20 74 6f 20 74 68 65 20 73 61 6d 65 20 69     to the same i
362b0 6e 74 65 72 66 61 63 65 20 6f 6e 20 74 68 65 20  nterface on the 
362c0 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63  same [database c
362d0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a  onnection] D..**
362e0 0a 2a 2a 20 7b 46 31 32 39 37 39 7d 20 54 68 65  .** {F12979} The
362f0 20 75 70 64 61 74 65 20 68 6f 6f 6b 20 63 61 6c   update hook cal
36300 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76  lback is not inv
36310 6f 6b 65 64 20 77 68 65 6e 20 69 6e 74 65 72 6e  oked when intern
36320 61 6c 20 73 79 73 74 65 6d 0a 2a 2a 20 20 20 20  al system.**    
36330 20 20 20 20 20 20 74 61 62 6c 65 73 20 73 75 63        tables suc
36340 68 20 61 73 20 73 71 6c 69 74 65 5f 6d 61 73 74  h as sqlite_mast
36350 65 72 20 61 6e 64 20 73 71 6c 69 74 65 5f 73 65  er and sqlite_se
36360 71 75 65 6e 63 65 20 61 72 65 20 6d 6f 64 69 66  quence are modif
36370 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39  ied..**.** {F129
36380 38 31 7d 20 54 68 65 20 73 65 63 6f 6e 64 20 70  81} The second p
36390 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
363a0 75 70 64 61 74 65 20 63 61 6c 6c 62 61 63 6b 20  update callback 
363b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20  .**          is 
363c0 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49  one of [SQLITE_I
363d0 4e 53 45 52 54 5d 2c 20 5b 53 51 4c 49 54 45 5f  NSERT], [SQLITE_
363e0 44 45 4c 45 54 45 5d 20 6f 72 20 5b 53 51 4c 49  DELETE] or [SQLI
363f0 54 45 5f 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 20  TE_UPDATE],.**  
36400 20 20 20 20 20 20 20 20 64 65 70 65 6e 64 69 6e          dependin
36410 67 20 6f 6e 20 74 68 65 20 6f 70 65 72 61 74 69  g on the operati
36420 6f 6e 20 74 68 61 74 20 63 61 75 73 65 64 20 74  on that caused t
36430 68 65 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 62  he callback to b
36440 65 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a  e invoked..**.**
36450 20 7b 46 31 32 39 38 33 7d 20 54 68 65 20 74 68   {F12983} The th
36460 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 61  ird and fourth a
36470 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20  rguments to the 
36480 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e  callback contain
36490 20 70 6f 69 6e 74 65 72 73 0a 2a 2a 20 20 20 20   pointers.**    
364a0 20 20 20 20 20 20 74 6f 20 7a 65 72 6f 2d 74 65        to zero-te
364b0 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73  rminated UTF-8 s
364c0 74 72 69 6e 67 73 20 77 68 69 63 68 20 61 72 65  trings which are
364d0 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 68   the names of th
364e0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 61  e.**          da
364f0 74 61 62 61 73 65 20 61 6e 64 20 74 61 62 6c 65  tabase and table
36500 20 74 68 61 74 20 69 73 20 62 65 69 6e 67 20 75   that is being u
36510 70 64 61 74 65 64 2e 0a 0a 2a 2a 20 7b 46 31 32  pdated...** {F12
36520 39 38 35 7d 20 54 68 65 20 66 69 6e 61 6c 20 63  985} The final c
36530 61 6c 6c 62 61 63 6b 20 70 61 72 61 6d 65 74 65  allback paramete
36540 72 20 69 73 20 74 68 65 20 72 6f 77 69 64 20 6f  r is the rowid o
36550 66 20 74 68 65 20 72 6f 77 20 61 66 74 65 72 0a  f the row after.
36560 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
36570 63 68 61 6e 67 65 20 6f 63 63 75 72 73 2e 0a 2a  change occurs..*
36580 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
36590 75 70 64 61 74 65 5f 68 6f 6f 6b 28 0a 20 20 73  update_hook(.  s
365a0 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64  qlite3*, .  void
365b0 28 2a 29 28 76 6f 69 64 20 2a 2c 69 6e 74 20 2c  (*)(void *,int ,
365c0 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 63 68 61  char const *,cha
365d0 72 20 63 6f 6e 73 74 20 2a 2c 73 71 6c 69 74 65  r const *,sqlite
365e0 33 5f 69 6e 74 36 34 29 2c 0a 20 20 76 6f 69 64  3_int64),.  void
365f0 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  *.);../*.** CAPI
36600 33 52 45 46 3a 20 20 45 6e 61 62 6c 65 20 4f 72  3REF:  Enable Or
36610 20 44 69 73 61 62 6c 65 20 53 68 61 72 65 64 20   Disable Shared 
36620 50 61 67 65 72 20 43 61 63 68 65 20 7b 46 31 30  Pager Cache {F10
36630 33 33 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  330}.**.** This 
36640 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20  routine enables 
36650 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 20  or disables the 
36660 73 68 61 72 69 6e 67 20 6f 66 20 74 68 65 20 64  sharing of the d
36670 61 74 61 62 61 73 65 20 63 61 63 68 65 0a 2a 2a  atabase cache.**
36680 20 61 6e 64 20 73 63 68 65 6d 61 20 64 61 74 61   and schema data
36690 20 73 74 72 75 63 74 75 72 65 73 20 62 65 74 77   structures betw
366a0 65 65 6e 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  een connections 
366b0 74 6f 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  to the same data
366c0 62 61 73 65 2e 0a 2a 2a 20 53 68 61 72 69 6e 67  base..** Sharing
366d0 20 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74   is enabled if t
366e0 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  he argument is t
366f0 72 75 65 20 61 6e 64 20 64 69 73 61 62 6c 65 64  rue and disabled
36700 20 69 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74   if the argument
36710 0a 2a 2a 20 69 73 20 66 61 6c 73 65 2e 0a 2a 2a  .** is false..**
36720 0a 2a 2a 20 43 61 63 68 65 20 73 68 61 72 69 6e  .** Cache sharin
36730 67 20 69 73 20 65 6e 61 62 6c 65 64 20 61 6e 64  g is enabled and
36740 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 66 6f 72   disabled.** for
36750 20 61 6e 20 65 6e 74 69 72 65 20 70 72 6f 63 65   an entire proce
36760 73 73 2e 20 7b 45 4e 44 7d 20 54 68 69 73 20 69  ss. {END} This i
36770 73 20 61 20 63 68 61 6e 67 65 20 61 73 20 6f 66  s a change as of
36780 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
36790 33 2e 35 2e 30 2e 0a 2a 2a 20 49 6e 20 70 72 69  3.5.0..** In pri
367a0 6f 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  or versions of S
367b0 51 4c 69 74 65 2c 20 73 68 61 72 69 6e 67 20 77  QLite, sharing w
367c0 61 73 0a 2a 2a 20 65 6e 61 62 6c 65 64 20 6f 72  as.** enabled or
367d0 20 64 69 73 61 62 6c 65 64 20 66 6f 72 20 65 61   disabled for ea
367e0 63 68 20 74 68 72 65 61 64 20 73 65 70 61 72 61  ch thread separa
367f0 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  tely..**.** The 
36800 63 61 63 68 65 20 73 68 61 72 69 6e 67 20 6d 6f  cache sharing mo
36810 64 65 20 73 65 74 20 62 79 20 74 68 69 73 20 69  de set by this i
36820 6e 74 65 72 66 61 63 65 20 65 66 66 65 63 74 73  nterface effects
36830 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 0a   all subsequent.
36840 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  ** calls to [sql
36850 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
36860 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
36870 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
36880 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 20 45 78  open16()]..** Ex
36890 69 73 74 69 6e 67 20 64 61 74 61 62 61 73 65 20  isting database 
368a0 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 63 6f 6e 74  connections cont
368b0 69 6e 75 65 20 75 73 65 20 74 68 65 20 73 68 61  inue use the sha
368c0 72 69 6e 67 20 6d 6f 64 65 0a 2a 2a 20 74 68 61  ring mode.** tha
368d0 74 20 77 61 73 20 69 6e 20 65 66 66 65 63 74 20  t was in effect 
368e0 61 74 20 74 68 65 20 74 69 6d 65 20 74 68 65 79  at the time they
368f0 20 77 65 72 65 20 6f 70 65 6e 65 64 2e 0a 2a 2a   were opened..**
36900 0a 2a 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c  .** Virtual tabl
36910 65 73 20 63 61 6e 6e 6f 74 20 62 65 20 75 73 65  es cannot be use
36920 64 20 77 69 74 68 20 61 20 73 68 61 72 65 64 20  d with a shared 
36930 63 61 63 68 65 2e 20 20 20 57 68 65 6e 20 73 68  cache.   When sh
36940 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 69 73  ared.** cache is
36950 20 65 6e 61 62 6c 65 64 2c 20 74 68 65 20 5b 73   enabled, the [s
36960 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f  qlite3_create_mo
36970 64 75 6c 65 28 29 5d 20 41 50 49 20 75 73 65 64  dule()] API used
36980 20 74 6f 20 72 65 67 69 73 74 65 72 0a 2a 2a 20   to register.** 
36990 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 77  virtual tables w
369a0 69 6c 6c 20 61 6c 77 61 79 73 20 72 65 74 75 72  ill always retur
369b0 6e 20 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a  n an error..**.*
369c0 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72  * This routine r
369d0 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
369e0 4b 5d 20 69 66 20 73 68 61 72 65 64 20 63 61 63  K] if shared cac
369f0 68 65 20 77 61 73 0a 2a 2a 20 65 6e 61 62 6c 65  he was.** enable
36a00 64 20 6f 72 20 64 69 73 61 62 6c 65 64 20 73 75  d or disabled su
36a10 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 41 6e 20  ccessfully.  An 
36a20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 0a 2a 2a 20  [error code].** 
36a30 69 73 20 72 65 74 75 72 6e 65 64 20 6f 74 68 65  is returned othe
36a40 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 53 68 61  rwise..**.** Sha
36a50 72 65 64 20 63 61 63 68 65 20 69 73 20 64 69 73  red cache is dis
36a60 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
36a70 2e 20 42 75 74 20 74 68 69 73 20 6d 69 67 68 74  . But this might
36a80 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 66 75   change in.** fu
36a90 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
36aa0 20 53 51 4c 69 74 65 2e 20 20 41 70 70 6c 69 63   SQLite.  Applic
36ab0 61 74 69 6f 6e 73 20 74 68 61 74 20 63 61 72 65  ations that care
36ac0 20 61 62 6f 75 74 20 73 68 61 72 65 64 0a 2a 2a   about shared.**
36ad0 20 63 61 63 68 65 20 73 65 74 74 69 6e 67 20 73   cache setting s
36ae0 68 6f 75 6c 64 20 73 65 74 20 69 74 20 65 78 70  hould set it exp
36af0 6c 69 63 69 74 6c 79 2e 0a 2a 2a 0a 2a 2a 20 49  licitly..**.** I
36b00 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 20 0a 2a  NVARIANTS:.** .*
36b10 2a 20 7b 46 31 30 33 33 31 7d 20 41 20 73 75 63  * {F10331} A suc
36b20 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69  cessful invocati
36b30 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 65  on of [sqlite3_e
36b40 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63  nable_shared_cac
36b50 68 65 28 42 29 5d 0a 2a 2a 20 20 20 20 20 20 20  he(B)].**       
36b60 20 20 20 77 69 6c 6c 20 65 6e 61 62 6c 65 20 6f     will enable o
36b70 72 20 64 69 73 61 62 6c 65 20 73 68 61 72 65 64  r disable shared
36b80 20 63 61 63 68 65 20 6d 6f 64 65 20 66 6f 72 20   cache mode for 
36b90 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74 6c 79  any subsequently
36ba0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 72 65  .**          cre
36bb0 61 74 65 64 20 5b 64 61 74 61 62 61 73 65 20 63  ated [database c
36bc0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 6e 20 74 68  onnection] in th
36bd0 65 20 73 61 6d 65 20 70 72 6f 63 65 73 73 2e 0a  e same process..
36be0 2a 2a 0a 2a 2a 20 7b 46 31 30 33 33 36 7d 20 57  **.** {F10336} W
36bf0 68 65 6e 20 73 68 61 72 65 64 20 63 61 63 68 65  hen shared cache
36c00 20 69 73 20 65 6e 61 62 6c 65 64 2c 20 74 68 65   is enabled, the
36c10 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
36c20 5f 6d 6f 64 75 6c 65 28 29 5d 0a 2a 2a 20 20 20  _module()].**   
36c30 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65         interface
36c40 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 72 65 74   will always ret
36c50 75 72 6e 20 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a  urn an error..**
36c60 0a 2a 2a 20 7b 46 31 30 33 33 37 7d 20 54 68 65  .** {F10337} The
36c70 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65   [sqlite3_enable
36c80 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28 42 29  _shared_cache(B)
36c90 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
36ca0 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  rns.**          
36cb0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 20 73  [SQLITE_OK] if s
36cc0 68 61 72 65 64 20 63 61 63 68 65 20 77 61 73 20  hared cache was 
36cd0 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62  enabled or disab
36ce0 6c 65 64 20 73 75 63 63 65 73 73 66 75 6c 6c 79  led successfully
36cf0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 33 33 39 7d  ..**.** {F10339}
36d00 20 53 68 61 72 65 64 20 63 61 63 68 65 20 69 73   Shared cache is
36d10 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66   disabled by def
36d20 61 75 6c 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ault..*/.int sql
36d30 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72  ite3_enable_shar
36d40 65 64 5f 63 61 63 68 65 28 69 6e 74 29 3b 0a 0a  ed_cache(int);..
36d50 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
36d60 20 41 74 74 65 6d 70 74 20 54 6f 20 46 72 65 65   Attempt To Free
36d70 20 48 65 61 70 20 4d 65 6d 6f 72 79 20 7b 46 31   Heap Memory {F1
36d80 37 33 34 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20  7340}.**.** The 
36d90 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f  sqlite3_release_
36da0 6d 65 6d 6f 72 79 28 29 20 69 6e 74 65 72 66 61  memory() interfa
36db0 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 0a 2a  ce attempts to.*
36dc0 2a 20 66 72 65 65 20 4e 20 62 79 74 65 73 20 6f  * free N bytes o
36dd0 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 62 79  f heap memory by
36de0 20 64 65 61 6c 6c 6f 63 61 74 69 6e 67 20 6e 6f   deallocating no
36df0 6e 2d 65 73 73 65 6e 74 69 61 6c 20 6d 65 6d 6f  n-essential memo
36e00 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e  ry.** allocation
36e10 73 20 68 65 6c 64 20 62 79 20 74 68 65 20 64 61  s held by the da
36e20 74 61 62 61 73 65 20 6c 69 62 72 61 72 79 2e 20  tabase library. 
36e30 7b 45 4e 44 7d 20 20 4d 65 6d 6f 72 79 20 75 73  {END}  Memory us
36e40 65 64 0a 2a 2a 20 74 6f 20 63 61 63 68 65 20 64  ed.** to cache d
36e50 61 74 61 62 61 73 65 20 70 61 67 65 73 20 74 6f  atabase pages to
36e60 20 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d   improve perform
36e70 61 6e 63 65 20 69 73 20 61 6e 20 65 78 61 6d 70  ance is an examp
36e80 6c 65 20 6f 66 0a 2a 2a 20 6e 6f 6e 2d 65 73 73  le of.** non-ess
36e90 65 6e 74 69 61 6c 20 6d 65 6d 6f 72 79 2e 20 20  ential memory.  
36ea0 53 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f  Sqlite3_release_
36eb0 6d 65 6d 6f 72 79 28 29 20 72 65 74 75 72 6e 73  memory() returns
36ec0 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
36ed0 66 20 62 79 74 65 73 20 61 63 74 75 61 6c 6c 79  f bytes actually
36ee0 20 66 72 65 65 64 2c 20 77 68 69 63 68 20 6d 69   freed, which mi
36ef0 67 68 74 20 62 65 20 6d 6f 72 65 20 6f 72 20 6c  ght be more or l
36f00 65 73 73 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20  ess.** than the 
36f10 61 6d 6f 75 6e 74 20 72 65 71 75 65 73 74 65 64  amount requested
36f20 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
36f30 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 34  TS:.**.** {F1734
36f40 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
36f50 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 4e  release_memory(N
36f60 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61 74 74  )] interface att
36f70 65 6d 70 74 73 20 74 6f 0a 2a 2a 20 20 20 20 20  empts to.**     
36f80 20 20 20 20 20 66 72 65 65 20 4e 20 62 79 74 65       free N byte
36f90 73 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 79  s of heap memory
36fa0 20 62 79 20 64 65 61 6c 6c 6f 63 61 74 69 6e 67   by deallocating
36fb0 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 0a 2a   non-essential.*
36fc0 2a 20 20 20 20 20 20 20 20 20 20 6d 65 6d 6f 72  *          memor
36fd0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 68 65  y allocations he
36fe0 6c 64 20 62 79 20 74 68 65 20 64 61 74 61 62 61  ld by the databa
36ff0 73 65 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a  se library..**.*
37000 2a 20 7b 46 31 36 33 34 32 7d 20 54 68 65 20 5b  * {F16342} The [
37010 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f  sqlite3_release_
37020 6d 65 6d 6f 72 79 28 4e 29 5d 20 72 65 74 75 72  memory(N)] retur
37030 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 0a 2a 2a  ns the number.**
37040 20 20 20 20 20 20 20 20 20 20 6f 66 20 62 79 74            of byt
37050 65 73 20 61 63 74 75 61 6c 6c 79 20 66 72 65 65  es actually free
37060 64 2c 20 77 68 69 63 68 20 6d 69 67 68 74 20 62  d, which might b
37070 65 20 6d 6f 72 65 20 6f 72 20 6c 65 73 73 0a 2a  e more or less.*
37080 2a 20 20 20 20 20 20 20 20 20 20 74 68 61 6e 20  *          than 
37090 74 68 65 20 61 6d 6f 75 6e 74 20 72 65 71 75 65  the amount reque
370a0 73 74 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  sted..*/.int sql
370b0 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d  ite3_release_mem
370c0 6f 72 79 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  ory(int);../*.**
370d0 20 43 41 50 49 33 52 45 46 3a 20 20 49 6d 70 6f   CAPI3REF:  Impo
370e0 73 65 20 41 20 4c 69 6d 69 74 20 4f 6e 20 48 65  se A Limit On He
370f0 61 70 20 53 69 7a 65 20 7b 46 31 37 33 35 30 7d  ap Size {F17350}
37100 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
37110 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d  e3_soft_heap_lim
37120 69 74 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a  it() interface.*
37130 2a 20 70 6c 61 63 65 73 20 61 20 22 73 6f 66 74  * places a "soft
37140 22 20 6c 69 6d 69 74 20 6f 6e 20 74 68 65 20 61  " limit on the a
37150 6d 6f 75 6e 74 20 6f 66 20 68 65 61 70 20 6d 65  mount of heap me
37160 6d 6f 72 79 20 74 68 61 74 20 6d 61 79 20 62 65  mory that may be
37170 20 61 6c 6c 6f 63 61 74 65 64 0a 2a 2a 20 62 79   allocated.** by
37180 20 53 51 4c 69 74 65 2e 20 49 66 20 61 6e 20 69   SQLite. If an i
37190 6e 74 65 72 6e 61 6c 20 61 6c 6c 6f 63 61 74 69  nternal allocati
371a0 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 20  on is requested 
371b0 0a 2a 2a 20 74 68 61 74 20 77 6f 75 6c 64 20 65  .** that would e
371c0 78 63 65 65 64 20 74 68 65 20 73 6f 66 74 20 68  xceed the soft h
371d0 65 61 70 20 6c 69 6d 69 74 2c 20 5b 73 71 6c 69  eap limit, [sqli
371e0 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f  te3_release_memo
371f0 72 79 28 29 5d 20 69 73 0a 2a 2a 20 69 6e 76 6f  ry()] is.** invo
37200 6b 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  ked one or more 
37210 74 69 6d 65 73 20 74 6f 20 66 72 65 65 20 75 70  times to free up
37220 20 73 6f 6d 65 20 73 70 61 63 65 20 62 65 66 6f   some space befo
37230 72 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 69 6f  re the allocatio
37240 6e 0a 2a 2a 20 69 73 20 6d 61 64 65 2e 0a 2a 2a  n.** is made..**
37250 0a 2a 2a 20 54 68 65 20 6c 69 6d 69 74 20 69 73  .** The limit is
37260 20 63 61 6c 6c 65 64 20 22 73 6f 66 74 22 2c 20   called "soft", 
37270 62 65 63 61 75 73 65 20 69 66 0a 2a 2a 20 5b 73  because if.** [s
37280 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d  qlite3_release_m
37290 65 6d 6f 72 79 28 29 5d 20 63 61 6e 6e 6f 74 0a  emory()] cannot.
372a0 2a 2a 20 66 72 65 65 20 73 75 66 66 69 63 69 65  ** free sufficie
372b0 6e 74 20 6d 65 6d 6f 72 79 20 74 6f 20 70 72 65  nt memory to pre
372c0 76 65 6e 74 20 74 68 65 20 6c 69 6d 69 74 20 66  vent the limit f
372d0 72 6f 6d 20 62 65 69 6e 67 20 65 78 63 65 65 64  rom being exceed
372e0 65 64 2c 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72  ed,.** the memor
372f0 79 20 69 73 20 61 6c 6c 6f 63 61 74 65 64 20 61  y is allocated a
37300 6e 79 77 61 79 20 61 6e 64 20 74 68 65 20 63 75  nyway and the cu
37310 72 72 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e 20  rrent operation 
37320 70 72 6f 63 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20  proceeds..**.** 
37330 41 20 6e 65 67 61 74 69 76 65 20 6f 72 20 7a 65  A negative or ze
37340 72 6f 20 76 61 6c 75 65 20 66 6f 72 20 4e 20 6d  ro value for N m
37350 65 61 6e 73 20 74 68 61 74 20 74 68 65 72 65 20  eans that there 
37360 69 73 20 6e 6f 20 73 6f 66 74 20 68 65 61 70 20  is no soft heap 
37370 6c 69 6d 69 74 20 61 6e 64 0a 2a 2a 20 5b 73 71  limit and.** [sq
37380 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65  lite3_release_me
37390 6d 6f 72 79 28 29 5d 20 77 69 6c 6c 20 6f 6e 6c  mory()] will onl
373a0 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e  y be called when
373b0 20 6d 65 6d 6f 72 79 20 69 73 20 65 78 68 61 75   memory is exhau
373c0 73 74 65 64 2e 0a 2a 2a 20 54 68 65 20 64 65 66  sted..** The def
373d0 61 75 6c 74 20 76 61 6c 75 65 20 66 6f 72 20 74  ault value for t
373e0 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d  he soft heap lim
373f0 69 74 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a  it is zero..**.*
37400 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61  * SQLite makes a
37410 20 62 65 73 74 20 65 66 66 6f 72 74 20 74 6f 20   best effort to 
37420 68 6f 6e 6f 72 20 74 68 65 20 73 6f 66 74 20 68  honor the soft h
37430 65 61 70 20 6c 69 6d 69 74 2e 20 20 0a 2a 2a 20  eap limit.  .** 
37440 42 75 74 20 69 66 20 74 68 65 20 73 6f 66 74 20  But if the soft 
37450 68 65 61 70 20 6c 69 6d 69 74 20 63 61 6e 6e 6f  heap limit canno
37460 74 20 62 65 20 68 6f 6e 6f 72 65 64 2c 20 65 78  t be honored, ex
37470 65 63 75 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20  ecution will.** 
37480 63 6f 6e 74 69 6e 75 65 20 77 69 74 68 6f 75 74  continue without
37490 20 65 72 72 6f 72 20 6f 72 20 6e 6f 74 69 66 69   error or notifi
374a0 63 61 74 69 6f 6e 2e 20 20 54 68 69 73 20 69 73  cation.  This is
374b0 20 77 68 79 20 74 68 65 20 6c 69 6d 69 74 20 69   why the limit i
374c0 73 20 0a 2a 2a 20 63 61 6c 6c 65 64 20 61 20 22  s .** called a "
374d0 73 6f 66 74 22 20 6c 69 6d 69 74 2e 20 20 49 74  soft" limit.  It
374e0 20 69 73 20 61 64 76 69 73 6f 72 79 20 6f 6e 6c   is advisory onl
374f0 79 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 74  y..**.** Prior t
37500 6f 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  o SQLite version
37510 20 33 2e 35 2e 30 2c 20 74 68 69 73 20 72 6f 75   3.5.0, this rou
37520 74 69 6e 65 20 6f 6e 6c 79 20 63 6f 6e 73 74 72  tine only constr
37530 61 69 6e 65 64 20 74 68 65 20 6d 65 6d 6f 72 79  ained the memory
37540 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 64 20 62 79  .** allocated by
37550 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64   a single thread
37560 20 2d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65   - the same thre
37570 61 64 20 69 6e 20 77 68 69 63 68 20 74 68 69 73  ad in which this
37580 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 75 6e 73   routine.** runs
37590 2e 20 20 42 65 67 69 6e 6e 69 6e 67 20 77 69 74  .  Beginning wit
375a0 68 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  h SQLite version
375b0 20 33 2e 35 2e 30 2c 20 74 68 65 20 73 6f 66 74   3.5.0, the soft
375c0 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 0a 2a   heap limit is.*
375d0 2a 20 61 70 70 6c 69 65 64 20 74 6f 20 61 6c 6c  * applied to all
375e0 20 74 68 72 65 61 64 73 2e 20 54 68 65 20 76 61   threads. The va
375f0 6c 75 65 20 73 70 65 63 69 66 69 65 64 20 66 6f  lue specified fo
37600 72 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20  r the soft heap 
37610 6c 69 6d 69 74 0a 2a 2a 20 69 73 20 61 6e 20 75  limit.** is an u
37620 70 70 65 72 20 62 6f 75 6e 64 20 6f 6e 20 74 68  pper bound on th
37630 65 20 74 6f 74 61 6c 20 6d 65 6d 6f 72 79 20 61  e total memory a
37640 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20 61 6c  llocation for al
37650 6c 20 74 68 72 65 61 64 73 2e 20 49 6e 0a 2a 2a  l threads. In.**
37660 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 74   version 3.5.0 t
37670 68 65 72 65 20 69 73 20 6e 6f 20 6d 65 63 68 61  here is no mecha
37680 6e 69 73 6d 20 66 6f 72 20 6c 69 6d 69 74 69 6e  nism for limitin
37690 67 20 74 68 65 20 68 65 61 70 20 75 73 61 67 65  g the heap usage
376a0 20 66 6f 72 0a 2a 2a 20 69 6e 64 69 76 69 64 75   for.** individu
376b0 61 6c 20 74 68 72 65 61 64 73 2e 0a 2a 2a 0a 2a  al threads..**.*
376c0 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
376d0 0a 2a 2a 20 7b 46 31 36 33 35 31 7d 20 54 68 65  .** {F16351} The
376e0 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68   [sqlite3_soft_h
376f0 65 61 70 5f 6c 69 6d 69 74 28 4e 29 5d 20 69 6e  eap_limit(N)] in
37700 74 65 72 66 61 63 65 20 70 6c 61 63 65 73 20 61  terface places a
37710 20 73 6f 66 74 20 6c 69 6d 69 74 0a 2a 2a 20 20   soft limit.**  
37720 20 20 20 20 20 20 20 20 6f 66 20 4e 20 62 79 74          of N byt
37730 65 73 20 6f 6e 20 74 68 65 20 61 6d 6f 75 6e 74  es on the amount
37740 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 20   of heap memory 
37750 74 68 61 74 20 6d 61 79 20 62 65 20 61 6c 6c 6f  that may be allo
37760 63 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  cated.**        
37770 20 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33    using [sqlite3
37780 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73  _malloc()] or [s
37790 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
377a0 5d 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 0a 2a  ] at any point.*
377b0 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 74 69  *          in ti
377c0 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 33 35  me..**.** {F1635
377d0 32 7d 20 49 66 20 61 20 63 61 6c 6c 20 74 6f 20  2} If a call to 
377e0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
377f0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
37800 65 61 6c 6c 6f 63 28 29 5d 20 77 6f 75 6c 64 0a  ealloc()] would.
37810 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61 75 73  **          caus
37820 65 20 74 68 65 20 74 6f 74 61 6c 20 61 6d 6f 75  e the total amou
37830 6e 74 20 6f 66 20 61 6c 6c 6f 63 61 74 65 64 20  nt of allocated 
37840 6d 65 6d 6f 72 79 20 74 6f 20 65 78 63 65 65 64  memory to exceed
37850 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
37860 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
37870 2c 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f  , then [sqlite3_
37880 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29  release_memory()
37890 5d 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20  ] is invoked.** 
378a0 20 20 20 20 20 20 20 20 20 69 6e 20 61 6e 20 61           in an a
378b0 74 74 65 6d 70 74 20 74 6f 20 72 65 64 75 63 65  ttempt to reduce
378c0 20 74 68 65 20 6d 65 6d 6f 72 79 20 75 73 61 67   the memory usag
378d0 65 20 70 72 69 6f 72 20 74 6f 20 70 72 6f 63 65  e prior to proce
378e0 65 64 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20  eding.**        
378f0 20 20 77 69 74 68 20 74 68 65 20 6d 65 6d 6f 72    with the memor
37900 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 74 74  y allocation att
37910 65 6d 70 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  empt..**.** {F16
37920 33 35 33 7d 20 43 61 6c 6c 73 20 74 6f 20 5b 73  353} Calls to [s
37930 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
37940 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61   or [sqlite3_rea
37950 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 74 72 69  lloc()] that tri
37960 67 67 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  gger.**         
37970 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 64   attempts to red
37980 75 63 65 20 6d 65 6d 6f 72 79 20 75 73 61 67 65  uce memory usage
37990 20 74 68 72 6f 75 67 68 20 74 68 65 20 73 6f 66   through the sof
379a0 74 20 68 65 61 70 20 6c 69 6d 69 74 0a 2a 2a 20  t heap limit.** 
379b0 20 20 20 20 20 20 20 20 20 6d 65 63 68 61 6e 69           mechani
379c0 73 6d 20 63 6f 6e 74 69 6e 75 65 20 65 76 65 6e  sm continue even
379d0 20 69 66 20 74 68 65 20 61 74 74 65 6d 70 74 20   if the attempt 
379e0 74 6f 20 72 65 64 75 63 65 20 6d 65 6d 6f 72 79  to reduce memory
379f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 75 73 61  .**          usa
37a00 67 65 20 69 73 20 75 6e 73 75 63 63 65 73 73 66  ge is unsuccessf
37a10 75 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 33 35  ul..**.** {F1635
37a20 34 7d 20 41 20 6e 65 67 61 74 69 76 65 20 6f 72  4} A negative or
37a30 20 7a 65 72 6f 20 76 61 6c 75 65 20 66 6f 72 20   zero value for 
37a40 4e 20 69 6e 20 61 20 63 61 6c 6c 20 74 6f 0a 2a  N in a call to.*
37a50 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
37a60 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69  te3_soft_heap_li
37a70 6d 69 74 28 4e 29 5d 20 6d 65 61 6e 73 20 74 68  mit(N)] means th
37a80 61 74 20 74 68 65 72 65 20 69 73 20 6e 6f 20 73  at there is no s
37a90 6f 66 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  oft.**          
37aa0 68 65 61 70 20 6c 69 6d 69 74 20 61 6e 64 20 5b  heap limit and [
37ab0 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f  sqlite3_release_
37ac0 6d 65 6d 6f 72 79 28 29 5d 20 77 69 6c 6c 20 6f  memory()] will o
37ad0 6e 6c 79 20 62 65 0a 2a 2a 20 20 20 20 20 20 20  nly be.**       
37ae0 20 20 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 6d     called when m
37af0 65 6d 6f 72 79 20 69 73 20 63 6f 6d 70 6c 65 74  emory is complet
37b00 65 6c 79 20 65 78 68 61 75 73 74 65 64 2e 0a 2a  ely exhausted..*
37b10 2a 0a 2a 2a 20 7b 46 31 36 33 35 35 7d 20 54 68  *.** {F16355} Th
37b20 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20  e default value 
37b30 66 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65 61  for the soft hea
37b40 70 20 6c 69 6d 69 74 20 69 73 20 7a 65 72 6f 2e  p limit is zero.
37b50 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 33 35 38 7d 20  .**.** {F16358} 
37b60 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71  Each call to [sq
37b70 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f  lite3_soft_heap_
37b80 6c 69 6d 69 74 28 4e 29 5d 20 6f 76 65 72 72 69  limit(N)] overri
37b90 64 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  des the.**      
37ba0 20 20 20 20 76 61 6c 75 65 73 20 73 65 74 20 62      values set b
37bb0 79 20 61 6c 6c 20 70 72 69 6f 72 20 63 61 6c 6c  y all prior call
37bc0 73 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  s..*/.void sqlit
37bd0 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d  e3_soft_heap_lim
37be0 69 74 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  it(int);../*.** 
37bf0 43 41 50 49 33 52 45 46 3a 20 20 45 78 74 72 61  CAPI3REF:  Extra
37c00 63 74 20 4d 65 74 61 64 61 74 61 20 41 62 6f 75  ct Metadata Abou
37c10 74 20 41 20 43 6f 6c 75 6d 6e 20 4f 66 20 41 20  t A Column Of A 
37c20 54 61 62 6c 65 20 7b 46 31 32 38 35 30 7d 0a 2a  Table {F12850}.*
37c30 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
37c40 65 0a 2a 2a 20 72 65 74 75 72 6e 73 20 6d 65 74  e.** returns met
37c50 61 2d 64 61 74 61 20 61 62 6f 75 74 20 61 20 73  a-data about a s
37c60 70 65 63 69 66 69 63 20 63 6f 6c 75 6d 6e 20 6f  pecific column o
37c70 66 20 61 20 73 70 65 63 69 66 69 63 20 64 61 74  f a specific dat
37c80 61 62 61 73 65 0a 2a 2a 20 74 61 62 6c 65 20 61  abase.** table a
37c90 63 63 65 73 73 69 62 6c 65 20 75 73 69 6e 67 20  ccessible using 
37ca0 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 68  the connection h
37cb0 61 6e 64 6c 65 20 70 61 73 73 65 64 20 61 73 20  andle passed as 
37cc0 74 68 65 20 66 69 72 73 74 20 66 75 6e 63 74 69  the first functi
37cd0 6f 6e 20 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e  on .** argument.
37ce0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6c 75 6d  .**.** The colum
37cf0 6e 20 69 73 20 69 64 65 6e 74 69 66 69 65 64 20  n is identified 
37d00 62 79 20 74 68 65 20 73 65 63 6f 6e 64 2c 20 74  by the second, t
37d10 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20  hird and fourth 
37d20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 0a 2a  parameters to .*
37d30 2a 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e  * this function.
37d40 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
37d50 6d 65 74 65 72 20 69 73 20 65 69 74 68 65 72 20  meter is either 
37d60 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
37d70 64 61 74 61 62 61 73 65 0a 2a 2a 20 28 69 2e 65  database.** (i.e
37d80 2e 20 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22  . "main", "temp"
37d90 20 6f 72 20 61 6e 20 61 74 74 61 63 68 65 64 20   or an attached 
37da0 64 61 74 61 62 61 73 65 29 20 63 6f 6e 74 61 69  database) contai
37db0 6e 69 6e 67 20 74 68 65 20 73 70 65 63 69 66 69  ning the specifi
37dc0 65 64 0a 2a 2a 20 74 61 62 6c 65 20 6f 72 20 4e  ed.** table or N
37dd0 55 4c 4c 2e 20 49 66 20 69 74 20 69 73 20 4e 55  ULL. If it is NU
37de0 4c 4c 2c 20 74 68 65 6e 20 61 6c 6c 20 61 74 74  LL, then all att
37df0 61 63 68 65 64 20 64 61 74 61 62 61 73 65 73 20  ached databases 
37e00 61 72 65 20 73 65 61 72 63 68 65 64 0a 2a 2a 20  are searched.** 
37e10 66 6f 72 20 74 68 65 20 74 61 62 6c 65 20 75 73  for the table us
37e20 69 6e 67 20 74 68 65 20 73 61 6d 65 20 61 6c 67  ing the same alg
37e30 6f 72 69 74 68 6d 20 61 73 20 74 68 65 20 64 61  orithm as the da
37e40 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20 75 73  tabase engine us
37e50 65 73 20 74 6f 20 0a 2a 2a 20 72 65 73 6f 6c 76  es to .** resolv
37e60 65 20 75 6e 71 75 61 6c 69 66 69 65 64 20 74 61  e unqualified ta
37e70 62 6c 65 20 72 65 66 65 72 65 6e 63 65 73 2e 0a  ble references..
37e80 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20  **.** The third 
37e90 61 6e 64 20 66 6f 75 72 74 68 20 70 61 72 61 6d  and fourth param
37ea0 65 74 65 72 73 20 74 6f 20 74 68 69 73 20 66 75  eters to this fu
37eb0 6e 63 74 69 6f 6e 20 61 72 65 20 74 68 65 20 74  nction are the t
37ec0 61 62 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 20  able and column 
37ed0 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  .** name of the 
37ee0 64 65 73 69 72 65 64 20 63 6f 6c 75 6d 6e 2c 20  desired column, 
37ef0 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 4e 65  respectively. Ne
37f00 69 74 68 65 72 20 6f 66 20 74 68 65 73 65 20 70  ither of these p
37f10 61 72 61 6d 65 74 65 72 73 20 0a 2a 2a 20 6d 61  arameters .** ma
37f20 79 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  y be NULL..**.**
37f30 20 4d 65 74 61 20 69 6e 66 6f 72 6d 61 74 69 6f   Meta informatio
37f40 6e 20 69 73 20 72 65 74 75 72 6e 65 64 20 62 79  n is returned by
37f50 20 77 72 69 74 69 6e 67 20 74 6f 20 74 68 65 20   writing to the 
37f60 6d 65 6d 6f 72 79 20 6c 6f 63 61 74 69 6f 6e 73  memory locations
37f70 20 70 61 73 73 65 64 20 61 73 0a 2a 2a 20 74 68   passed as.** th
37f80 65 20 35 74 68 20 61 6e 64 20 73 75 62 73 65 71  e 5th and subseq
37f90 75 65 6e 74 20 70 61 72 61 6d 65 74 65 72 73 20  uent parameters 
37fa0 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  to this function
37fb0 2e 20 41 6e 79 20 6f 66 20 74 68 65 73 65 20 0a  . Any of these .
37fc0 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 6d 61 79  ** arguments may
37fd0 20 62 65 20 4e 55 4c 4c 2c 20 69 6e 20 77 68 69   be NULL, in whi
37fe0 63 68 20 63 61 73 65 20 74 68 65 20 63 6f 72 72  ch case the corr
37ff0 65 73 70 6f 6e 64 69 6e 67 20 65 6c 65 6d 65 6e  esponding elemen
38000 74 20 6f 66 20 6d 65 74 61 20 0a 2a 2a 20 69 6e  t of meta .** in
38010 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 6f 6d 69  formation is omi
38020 74 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 70 72 65  tted..**.** <pre
38030 3e 0a 2a 2a 20 50 61 72 61 6d 65 74 65 72 20 20  >.** Parameter  
38040 20 20 20 4f 75 74 70 75 74 20 54 79 70 65 20 20     Output Type  
38050 20 20 20 20 44 65 73 63 72 69 70 74 69 6f 6e 0a      Description.
38060 2a 2a 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ** -------------
38070 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
38080 2d 2d 2d 2d 2d 2d 0a 2a 2a 0a 2a 2a 20 20 20 35  ------.**.**   5
38090 74 68 20 20 20 20 20 20 20 20 20 63 6f 6e 73 74  th         const
380a0 20 63 68 61 72 2a 20 20 20 20 20 20 44 61 74 61   char*      Data
380b0 20 74 79 70 65 0a 2a 2a 20 20 20 36 74 68 20 20   type.**   6th  
380c0 20 20 20 20 20 20 20 63 6f 6e 73 74 20 63 68 61         const cha
380d0 72 2a 20 20 20 20 20 20 4e 61 6d 65 20 6f 66 20  r*      Name of 
380e0 74 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6c 6c  the default coll
380f0 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 0a  ation sequence .
38100 2a 2a 20 20 20 37 74 68 20 20 20 20 20 20 20 20  **   7th        
38110 20 69 6e 74 20 20 20 20 20 20 20 20 20 20 20 20   int            
38120 20 20 54 72 75 65 20 69 66 20 74 68 65 20 63 6f    True if the co
38130 6c 75 6d 6e 20 68 61 73 20 61 20 4e 4f 54 20 4e  lumn has a NOT N
38140 55 4c 4c 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a  ULL constraint.*
38150 2a 20 20 20 38 74 68 20 20 20 20 20 20 20 20 20  *   8th         
38160 69 6e 74 20 20 20 20 20 20 20 20 20 20 20 20 20  int             
38170 20 54 72 75 65 20 69 66 20 74 68 65 20 63 6f 6c   True if the col
38180 75 6d 6e 20 69 73 20 70 61 72 74 20 6f 66 20 74  umn is part of t
38190 68 65 20 50 52 49 4d 41 52 59 20 4b 45 59 0a 2a  he PRIMARY KEY.*
381a0 2a 20 20 20 39 74 68 20 20 20 20 20 20 20 20 20  *   9th         
381b0 69 6e 74 20 20 20 20 20 20 20 20 20 20 20 20 20  int             
381c0 20 54 72 75 65 20 69 66 20 74 68 65 20 63 6f 6c   True if the col
381d0 75 6d 6e 20 69 73 20 41 55 54 4f 49 4e 43 52 45  umn is AUTOINCRE
381e0 4d 45 4e 54 0a 2a 2a 20 3c 2f 70 72 65 3e 0a 2a  MENT.** </pre>.*
381f0 2a 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 65 6d 6f  *.**.** The memo
38200 72 79 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79  ry pointed to by
38210 20 74 68 65 20 63 68 61 72 61 63 74 65 72 20 70   the character p
38220 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64  ointers returned
38230 20 66 6f 72 20 74 68 65 20 0a 2a 2a 20 64 65 63   for the .** dec
38240 6c 61 72 61 74 69 6f 6e 20 74 79 70 65 20 61 6e  laration type an
38250 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  d collation sequ
38260 65 6e 63 65 20 69 73 20 76 61 6c 69 64 20 6f 6e  ence is valid on
38270 6c 79 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78  ly until the nex
38280 74 20 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 61 6e  t .** call to an
38290 79 20 73 71 6c 69 74 65 20 41 50 49 20 66 75 6e  y sqlite API fun
382a0 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  ction..**.** If 
382b0 74 68 65 20 73 70 65 63 69 66 69 65 64 20 74 61  the specified ta
382c0 62 6c 65 20 69 73 20 61 63 74 75 61 6c 6c 79 20  ble is actually 
382d0 61 20 76 69 65 77 2c 20 74 68 65 6e 20 61 6e 20  a view, then an 
382e0 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
382f0 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  d..**.** If the 
38300 73 70 65 63 69 66 69 65 64 20 63 6f 6c 75 6d 6e  specified column
38310 20 69 73 20 22 72 6f 77 69 64 22 2c 20 22 6f 69   is "rowid", "oi
38320 64 22 20 6f 72 20 22 5f 72 6f 77 69 64 5f 22 20  d" or "_rowid_" 
38330 61 6e 64 20 61 6e 20 0a 2a 2a 20 49 4e 54 45 47  and an .** INTEG
38340 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 20 63  ER PRIMARY KEY c
38350 6f 6c 75 6d 6e 20 68 61 73 20 62 65 65 6e 20 65  olumn has been e
38360 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72  xplicitly declar
38370 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 75 74  ed, then the out
38380 70 75 74 20 0a 2a 2a 20 70 61 72 61 6d 65 74 65  put .** paramete
38390 72 73 20 61 72 65 20 73 65 74 20 66 6f 72 20 74  rs are set for t
383a0 68 65 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65  he explicitly de
383b0 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 2e 20 49  clared column. I
383c0 66 20 74 68 65 72 65 20 69 73 20 6e 6f 0a 2a 2a  f there is no.**
383d0 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c   explicitly decl
383e0 61 72 65 64 20 49 50 4b 20 63 6f 6c 75 6d 6e 2c  ared IPK column,
383f0 20 74 68 65 6e 20 74 68 65 20 6f 75 74 70 75 74   then the output
38400 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20   parameters are 
38410 73 65 74 20 61 73 20 0a 2a 2a 20 66 6f 6c 6c 6f  set as .** follo
38420 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a  ws:.**.** <pre>.
38430 2a 2a 20 20 20 20 20 64 61 74 61 20 74 79 70 65  **     data type
38440 3a 20 22 49 4e 54 45 47 45 52 22 0a 2a 2a 20 20  : "INTEGER".**  
38450 20 20 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71     collation seq
38460 75 65 6e 63 65 3a 20 22 42 49 4e 41 52 59 22 0a  uence: "BINARY".
38470 2a 2a 20 20 20 20 20 6e 6f 74 20 6e 75 6c 6c 3a  **     not null:
38480 20 30 0a 2a 2a 20 20 20 20 20 70 72 69 6d 61 72   0.**     primar
38490 79 20 6b 65 79 3a 20 31 0a 2a 2a 20 20 20 20 20  y key: 1.**     
384a0 61 75 74 6f 20 69 6e 63 72 65 6d 65 6e 74 3a 20  auto increment: 
384b0 30 0a 2a 2a 20 3c 2f 70 72 65 3e 0a 2a 2a 0a 2a  0.** </pre>.**.*
384c0 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  * This function 
384d0 6d 61 79 20 6c 6f 61 64 20 6f 6e 65 20 6f 72 20  may load one or 
384e0 6d 6f 72 65 20 73 63 68 65 6d 61 73 20 66 72 6f  more schemas fro
384f0 6d 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 73  m database files
38500 2e 20 49 66 20 61 6e 0a 2a 2a 20 65 72 72 6f 72  . If an.** error
38510 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 74   occurs during t
38520 68 69 73 20 70 72 6f 63 65 73 73 2c 20 6f 72 20  his process, or 
38530 69 66 20 74 68 65 20 72 65 71 75 65 73 74 65 64  if the requested
38540 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e   table or column
38550 0a 2a 2a 20 63 61 6e 6e 6f 74 20 62 65 20 66 6f  .** cannot be fo
38560 75 6e 64 2c 20 61 6e 20 53 51 4c 49 54 45 20 65  und, an SQLITE e
38570 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74  rror code is ret
38580 75 72 6e 65 64 20 61 6e 64 20 61 6e 20 65 72 72  urned and an err
38590 6f 72 20 6d 65 73 73 61 67 65 0a 2a 2a 20 6c 65  or message.** le
385a0 66 74 20 69 6e 20 74 68 65 20 64 61 74 61 62 61  ft in the databa
385b0 73 65 20 68 61 6e 64 6c 65 20 28 74 6f 20 62 65  se handle (to be
385c0 20 72 65 74 72 69 65 76 65 64 20 75 73 69 6e 67   retrieved using
385d0 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28   sqlite3_errmsg(
385e0 29 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 41  ))..**.** This A
385f0 50 49 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c  PI is only avail
38600 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72  able if the libr
38610 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64  ary was compiled
38620 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c   with the.** SQL
38630 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d  ITE_ENABLE_COLUM
38640 4e 5f 4d 45 54 41 44 41 54 41 20 70 72 65 70 72  N_METADATA prepr
38650 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 20 64  ocessor symbol d
38660 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73  efined..*/.int s
38670 71 6c 69 74 65 33 5f 74 61 62 6c 65 5f 63 6f 6c  qlite3_table_col
38680 75 6d 6e 5f 6d 65 74 61 64 61 74 61 28 0a 20 20  umn_metadata(.  
38690 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
386a0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43              /* C
386b0 6f 6e 6e 65 63 74 69 6f 6e 20 68 61 6e 64 6c 65  onnection handle
386c0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
386d0 20 2a 7a 44 62 4e 61 6d 65 2c 20 20 20 20 20 20   *zDbName,      
386e0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 6e 61    /* Database na
386f0 6d 65 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 20 20  me or NULL */.  
38700 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 54 61 62  const char *zTab
38710 6c 65 4e 61 6d 65 2c 20 20 20 20 20 2f 2a 20 54  leName,     /* T
38720 61 62 6c 65 20 6e 61 6d 65 20 2a 2f 0a 20 20 63  able name */.  c
38730 6f 6e 73 74 20 63 68 61 72 20 2a 7a 43 6f 6c 75  onst char *zColu
38740 6d 6e 4e 61 6d 65 2c 20 20 20 20 2f 2a 20 43 6f  mnName,    /* Co
38750 6c 75 6d 6e 20 6e 61 6d 65 20 2a 2f 0a 20 20 63  lumn name */.  c
38760 68 61 72 20 63 6f 6e 73 74 20 2a 2a 70 7a 44 61  har const **pzDa
38770 74 61 54 79 70 65 2c 20 20 20 20 2f 2a 20 4f 55  taType,    /* OU
38780 54 50 55 54 3a 20 44 65 63 6c 61 72 65 64 20 64  TPUT: Declared d
38790 61 74 61 20 74 79 70 65 20 2a 2f 0a 20 20 63 68  ata type */.  ch
387a0 61 72 20 63 6f 6e 73 74 20 2a 2a 70 7a 43 6f 6c  ar const **pzCol
387b0 6c 53 65 71 2c 20 20 20 20 20 2f 2a 20 4f 55 54  lSeq,     /* OUT
387c0 50 55 54 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 73  PUT: Collation s
387d0 65 71 75 65 6e 63 65 20 6e 61 6d 65 20 2a 2f 0a  equence name */.
387e0 20 20 69 6e 74 20 2a 70 4e 6f 74 4e 75 6c 6c 2c    int *pNotNull,
387f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
38800 20 4f 55 54 50 55 54 3a 20 54 72 75 65 20 69 66   OUTPUT: True if
38810 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 72   NOT NULL constr
38820 61 69 6e 74 20 65 78 69 73 74 73 20 2a 2f 0a 20  aint exists */. 
38830 20 69 6e 74 20 2a 70 50 72 69 6d 61 72 79 4b 65   int *pPrimaryKe
38840 79 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  y,           /* 
38850 4f 55 54 50 55 54 3a 20 54 72 75 65 20 69 66 20  OUTPUT: True if 
38860 63 6f 6c 75 6d 6e 20 70 61 72 74 20 6f 66 20 50  column part of P
38870 4b 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 41 75 74  K */.  int *pAut
38880 6f 69 6e 63 20 20 20 20 20 20 20 20 20 20 20 20  oinc            
38890 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72     /* OUTPUT: Tr
388a0 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 69 73 20  ue if column is 
388b0 61 75 74 6f 2d 69 6e 63 72 65 6d 65 6e 74 20 2a  auto-increment *
388c0 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.);../*.** CAPI
388d0 33 52 45 46 3a 20 4c 6f 61 64 20 41 6e 20 45 78  3REF: Load An Ex
388e0 74 65 6e 73 69 6f 6e 20 7b 46 31 32 36 30 30 7d  tension {F12600}
388f0 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36 30 31 7d 20  .**.** {F12601} 
38900 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64  The sqlite3_load
38910 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e 74  _extension() int
38920 65 72 66 61 63 65 0a 2a 2a 20 61 74 74 65 6d 70  erface.** attemp
38930 74 73 20 74 6f 20 6c 6f 61 64 20 61 6e 20 53 51  ts to load