/ Hex Artifact Content
Login

Artifact 85032a736b18b01df995212c5ace20d403245d88:


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 33 36 20 32 30 30 38 2f  in,v 1.336 2008/
05f0: 30 36 2f 31 38 20 31 38 3a 35 37 3a 34 32 20 64  06/18 18:57:42 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 0a 2a 2a 0a 2a 2a 20 3c 74 6f 64 6f 3e 57 68  ..**.** <todo>Wh
1f60: 61 74 20 68 61 70 70 65 6e 73 20 74 6f 20 70 65  at happens to pe
1f70: 6e 64 69 6e 67 20 74 72 61 6e 73 61 63 74 69 6f  nding transactio
1f80: 6e 73 3f 20 20 41 72 65 20 74 68 65 79 0a 2a 2a  ns?  Are they.**
1f90: 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2c 20 6f 72   rolled back, or
1fa0: 20 61 62 61 6e 64 6f 6e 65 64 3f 3c 2f 74 6f 64   abandoned?</tod
1fb0: 6f 3e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  o>.**.** INVARIA
1fc0: 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 30  NTS:.**.** {F120
1fd0: 31 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  11} The [sqlite3
1fe0: 5f 63 6c 6f 73 65 28 29 5d 20 69 6e 74 65 72 66  _close()] interf
1ff0: 61 63 65 20 64 65 73 74 72 6f 79 73 20 61 6e 20  ace destroys an 
2000: 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
2010: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c 6c  .**          all
2020: 6f 63 61 74 65 64 20 62 79 20 61 20 70 72 69 6f  ocated by a prio
2030: 72 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  r call to [sqlit
2040: 65 33 5f 6f 70 65 6e 28 29 5d 2c 0a 2a 2a 20 20  e3_open()],.**  
2050: 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
2060: 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72 20 5b  _open16()], or [
2070: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
2080: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 30 31  )]..**.** {F1201
2090: 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  2} The [sqlite3_
20a0: 63 6c 6f 73 65 28 29 5d 20 66 75 6e 63 74 69 6f  close()] functio
20b0: 6e 20 72 65 6c 65 61 73 65 73 20 61 6c 6c 20 6d  n releases all m
20c0: 65 6d 6f 72 79 20 75 73 65 64 20 62 79 20 74 68  emory used by th
20d0: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f  e.**          co
20e0: 6e 6e 65 63 74 69 6f 6e 20 61 6e 64 20 63 6c 6f  nnection and clo
20f0: 73 65 73 20 61 6c 6c 20 6f 70 65 6e 20 66 69 6c  ses all open fil
2100: 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 30 31  es..**.** {F1201
2110: 33 7d 20 49 66 20 74 68 65 20 64 61 74 61 62 61  3} If the databa
2120: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6f  se connection co
2130: 6e 74 61 69 6e 73 0a 2a 2a 20 20 20 20 20 20 20  ntains.**       
2140: 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61     [prepared sta
2150: 74 65 6d 65 6e 74 73 5d 20 74 68 61 74 20 68 61  tements] that ha
2160: 76 65 20 6e 6f 74 20 62 65 65 6e 0a 2a 2a 20 20  ve not been.**  
2170: 20 20 20 20 20 20 20 20 66 69 6e 61 6c 69 7a 65          finalize
2180: 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 69  d by [sqlite3_fi
2190: 6e 61 6c 69 7a 65 28 29 5d 2c 20 74 68 65 6e 20  nalize()], then 
21a0: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29  [sqlite3_close()
21b0: 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  ].**          re
21c0: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55  turns [SQLITE_BU
21d0: 53 59 5d 20 61 6e 64 20 6c 65 61 76 65 73 20 74  SY] and leaves t
21e0: 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70  he connection op
21f0: 65 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 30 31  en..**.** {F1201
2200: 34 7d 20 47 69 76 69 6e 67 20 73 71 6c 69 74 65  4} Giving sqlite
2210: 33 5f 63 6c 6f 73 65 28 29 20 61 20 4e 55 4c 4c  3_close() a NULL
2220: 20 70 6f 69 6e 74 65 72 20 69 73 20 61 20 68 61   pointer is a ha
2230: 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a  rmless no-op..**
2240: 0a 2a 2a 20 4c 49 4d 49 54 41 54 49 4f 4e 53 3a  .** LIMITATIONS:
2250: 0a 2a 2a 0a 2a 2a 20 7b 55 31 32 30 31 35 7d 20  .**.** {U12015} 
2260: 54 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  The parameter to
2270: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
2280: 29 5d 20 6d 75 73 74 20 62 65 20 61 6e 20 5b 73  )] must be an [s
2290: 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 0a 2a  qlite3] object.*
22a0: 2a 20 20 20 20 20 20 20 20 20 20 70 6f 69 6e 74  *          point
22b0: 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62  er previously ob
22c0: 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
22d0: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 6f 72 20  ite3_open()] or 
22e0: 74 68 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  the .**         
22f0: 20 65 71 75 69 76 61 6c 65 6e 74 2c 20 6f 72 20   equivalent, or 
2300: 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 55 31 32  NULL..**.** {U12
2310: 30 31 36 7d 20 54 68 65 20 70 61 72 61 6d 65 74  016} The paramet
2320: 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  er to [sqlite3_c
2330: 6c 6f 73 65 28 29 5d 20 6d 75 73 74 20 6e 6f 74  lose()] must not
2340: 20 68 61 76 65 20 62 65 65 6e 20 70 72 65 76 69   have been previ
2350: 6f 75 73 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20  ously.**        
2360: 20 20 63 6c 6f 73 65 64 2e 0a 2a 2f 0a 69 6e 74    closed..*/.int
2370: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 73   sqlite3_close(s
2380: 71 6c 69 74 65 33 20 2a 29 3b 0a 0a 2f 2a 0a 2a  qlite3 *);../*.*
2390: 2a 20 54 68 65 20 74 79 70 65 20 66 6f 72 20 61  * The type for a
23a0: 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
23b0: 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 6c  on..** This is l
23c0: 65 67 61 63 79 20 61 6e 64 20 64 65 70 72 65 63  egacy and deprec
23d0: 61 74 65 64 2e 20 20 49 74 20 69 73 20 69 6e 63  ated.  It is inc
23e0: 6c 75 64 65 64 20 66 6f 72 20 68 69 73 74 6f 72  luded for histor
23f0: 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69 62  ical.** compatib
2400: 69 6c 69 74 79 20 61 6e 64 20 69 73 20 6e 6f 74  ility and is not
2410: 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a 2f 0a   documented..*/.
2420: 74 79 70 65 64 65 66 20 69 6e 74 20 28 2a 73 71  typedef int (*sq
2430: 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63 6b 29 28  lite3_callback)(
2440: 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a  void*,int,char**
2450: 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a 2a  , char**);../*.*
2460: 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 6e 65 2d  * CAPI3REF: One-
2470: 53 74 65 70 20 51 75 65 72 79 20 45 78 65 63 75  Step Query Execu
2480: 74 69 6f 6e 20 49 6e 74 65 72 66 61 63 65 20 7b  tion Interface {
2490: 46 31 32 31 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68  F12100}.**.** Th
24a0: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
24b0: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 61 20   interface is a 
24c0: 63 6f 6e 76 65 6e 69 65 6e 74 20 77 61 79 20 6f  convenient way o
24d0: 66 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 6f 6e 65  f running.** one
24e0: 20 6f 72 20 6d 6f 72 65 20 53 51 4c 20 73 74 61   or more SQL sta
24f0: 74 65 6d 65 6e 74 73 20 77 69 74 68 6f 75 74 20  tements without 
2500: 61 20 6c 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e  a lot of C code.
2510: 20 20 54 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61    The.** SQL sta
2520: 74 65 6d 65 6e 74 73 20 61 72 65 20 70 61 73 73  tements are pass
2530: 65 64 20 69 6e 20 61 73 20 74 68 65 20 73 65 63  ed in as the sec
2540: 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
2550: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
2560: 28 29 2e 20 20 54 68 65 20 73 74 61 74 65 6d 65  ().  The stateme
2570: 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65  nts are evaluate
2580: 64 20 6f 6e 65 20 62 79 20 6f 6e 65 0a 2a 2a 20  d one by one.** 
2590: 75 6e 74 69 6c 20 65 69 74 68 65 72 20 61 6e 20  until either an 
25a0: 65 72 72 6f 72 20 6f 72 20 61 6e 20 69 6e 74 65  error or an inte
25b0: 72 72 75 70 74 20 69 73 20 65 6e 63 6f 75 6e 74  rrupt is encount
25c0: 65 72 65 64 20 6f 72 0a 2a 2a 20 75 6e 74 69 6c  ered or.** until
25d0: 20 74 68 65 79 20 61 72 65 20 61 6c 6c 20 64 6f   they are all do
25e0: 6e 65 2e 20 20 54 68 65 20 33 72 64 20 70 61 72  ne.  The 3rd par
25f0: 61 6d 65 74 65 72 20 69 73 20 61 6e 20 6f 70 74  ameter is an opt
2600: 69 6f 6e 61 6c 0a 2a 2a 20 63 61 6c 6c 62 61 63  ional.** callbac
2610: 6b 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65  k that is invoke
2620: 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20  d once for each 
2630: 72 6f 77 20 6f 66 20 61 6e 79 20 71 75 65 72 79  row of any query
2640: 20 72 65 73 75 6c 74 73 0a 2a 2a 20 70 72 6f 64   results.** prod
2650: 75 63 65 64 20 62 79 20 74 68 65 20 53 51 4c 20  uced by the SQL 
2660: 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 54 68 65  statements.  The
2670: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
2680: 65 6c 6c 73 20 77 68 65 72 65 0a 2a 2a 20 74 6f  ells where.** to
2690: 20 77 72 69 74 65 20 61 6e 79 20 65 72 72 6f 72   write any error
26a0: 20 6d 65 73 73 61 67 65 73 2e 0a 2a 2a 0a 2a 2a   messages..**.**
26b0: 20 54 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   The error messa
26c0: 67 65 20 70 61 73 73 65 64 20 62 61 63 6b 20 74  ge passed back t
26d0: 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70  hrough the 5th p
26e0: 61 72 61 6d 65 74 65 72 20 69 73 20 68 65 6c 64  arameter is held
26f0: 0a 2a 2a 20 69 6e 20 6d 65 6d 6f 72 79 20 6f 62  .** in memory ob
2700: 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
2710: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20  ite3_malloc()]. 
2720: 20 54 6f 20 61 76 6f 69 64 20 61 20 6d 65 6d 6f   To avoid a memo
2730: 72 79 20 6c 65 61 6b 2c 0a 2a 2a 20 74 68 65 20  ry leak,.** the 
2740: 63 61 6c 6c 69 6e 67 20 61 70 70 6c 69 63 61 74  calling applicat
2750: 69 6f 6e 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20  ion should call 
2760: 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
2770: 20 6f 6e 20 61 6e 79 20 65 72 72 6f 72 0a 2a 2a   on any error.**
2780: 20 6d 65 73 73 61 67 65 20 72 65 74 75 72 6e 65   message returne
2790: 64 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 74  d through the 5t
27a0: 68 20 70 61 72 61 6d 65 74 65 72 20 77 68 65 6e  h parameter when
27b0: 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64   it has finished
27c0: 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 65 72   using.** the er
27d0: 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a  ror message..**.
27e0: 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 74  ** If the SQL st
27f0: 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 32  atement in the 2
2800: 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
2810: 4e 55 4c 4c 20 6f 72 20 61 6e 20 65 6d 70 74 79  NULL or an empty
2820: 20 73 74 72 69 6e 67 0a 2a 2a 20 6f 72 20 61 20   string.** or a 
2830: 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e  string containin
2840: 67 20 6f 6e 6c 79 20 77 68 69 74 65 73 70 61 63  g only whitespac
2850: 65 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 2c 20  e and comments, 
2860: 74 68 65 6e 20 53 51 4c 0a 2a 2a 20 73 74 61 74  then SQL.** stat
2870: 65 6d 65 6e 74 73 20 61 72 65 20 65 76 61 6c 75  ements are evalu
2880: 61 74 65 64 20 61 6e 64 20 74 68 65 20 64 61 74  ated and the dat
2890: 61 62 61 73 65 20 69 73 20 75 6e 63 68 61 6e 67  abase is unchang
28a0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ed..**.** The sq
28b0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74  lite3_exec() int
28c0: 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d  erface is implem
28d0: 65 6e 74 65 64 20 69 6e 20 74 65 72 6d 73 20 6f  ented in terms o
28e0: 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  f.** [sqlite3_pr
28f0: 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71  epare_v2()], [sq
2900: 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 61  lite3_step()], a
2910: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  nd [sqlite3_fina
2920: 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  lize()]..** The 
2930: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 72  sqlite3_exec() r
2940: 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 68  outine does noth
2950: 69 6e 67 20 74 6f 20 74 68 65 20 64 61 74 61 62  ing to the datab
2960: 61 73 65 20 74 68 61 74 20 63 61 6e 6e 6f 74 20  ase that cannot 
2970: 62 65 20 64 6f 6e 65 0a 2a 2a 20 62 79 20 5b 73  be done.** by [s
2980: 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2990: 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73  2()], [sqlite3_s
29a0: 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c  tep()], and [sql
29b0: 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
29c0: 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
29d0: 54 53 3a 0a 2a 2a 20 0a 2a 2a 20 7b 46 31 32 31  TS:.** .** {F121
29e0: 30 31 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c  01} A successful
29f0: 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b   invocation of [
2a00: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 44 2c 53  sqlite3_exec(D,S
2a10: 2c 43 2c 41 2c 45 29 5d 0a 2a 2a 20 20 20 20 20  ,C,A,E)].**     
2a20: 20 20 20 20 20 73 68 61 6c 6c 20 65 76 61 6c 75       shall evalu
2a30: 61 74 65 20 61 6c 6c 20 6f 66 20 74 68 65 20 55  ate all of the U
2a40: 54 46 2d 38 20 65 6e 63 6f 64 65 64 2c 20 73 65  TF-8 encoded, se
2a50: 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65  micolon-separate
2a60: 64 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53  d,.**          S
2a70: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e  QL statements in
2a80: 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e   the zero-termin
2a90: 61 74 65 64 20 73 74 72 69 6e 67 20 53 20 77 69  ated string S wi
2aa0: 74 68 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20  thin the.**     
2ab0: 20 20 20 20 20 63 6f 6e 74 65 78 74 20 6f 66 20       context of 
2ac0: 74 68 65 20 44 20 5b 64 61 74 61 62 61 73 65 20  the D [database 
2ad0: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a  connection]..**.
2ae0: 2a 2a 20 7b 46 31 32 31 30 32 7d 20 49 66 20 74  ** {F12102} If t
2af0: 68 65 20 53 20 70 61 72 61 6d 65 74 65 72 20 74  he S parameter t
2b00: 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  o [sqlite3_exec(
2b10: 44 2c 53 2c 43 2c 41 2c 45 29 5d 20 69 73 20 4e  D,S,C,A,E)] is N
2b20: 55 4c 4c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20  ULL then.**     
2b30: 20 20 20 20 20 74 68 65 20 61 63 74 69 6f 6e 73       the actions
2b40: 20 6f 66 20 74 68 65 20 69 6e 74 65 72 66 61 63   of the interfac
2b50: 65 20 73 68 61 6c 6c 20 62 65 20 74 68 65 20 73  e shall be the s
2b60: 61 6d 65 20 61 73 20 69 66 20 74 68 65 0a 2a 2a  ame as if the.**
2b70: 20 20 20 20 20 20 20 20 20 20 53 20 70 61 72 61            S para
2b80: 6d 65 74 65 72 20 77 68 65 72 65 20 61 6e 20 65  meter where an e
2b90: 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  mpty string..**.
2ba0: 2a 2a 20 7b 46 31 32 31 30 34 7d 20 54 68 65 20  ** {F12104} The 
2bb0: 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
2bc0: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
2bd0: 20 73 68 61 6c 6c 20 62 65 20 5b 53 51 4c 49 54   shall be [SQLIT
2be0: 45 5f 4f 4b 5d 20 69 66 20 61 6c 6c 0a 2a 2a 20  E_OK] if all.** 
2bf0: 20 20 20 20 20 20 20 20 20 53 51 4c 20 73 74 61           SQL sta
2c00: 74 65 6d 65 6e 74 73 20 72 75 6e 20 73 75 63 63  tements run succ
2c10: 65 73 73 66 75 6c 6c 79 20 61 6e 64 20 74 6f 20  essfully and to 
2c20: 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a  completion..**.*
2c30: 2a 20 7b 46 31 32 31 30 35 7d 20 54 68 65 20 72  * {F12105} The r
2c40: 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 5b  eturn value of [
2c50: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20  sqlite3_exec()] 
2c60: 73 68 61 6c 6c 20 62 65 20 61 6e 20 61 70 70 72  shall be an appr
2c70: 6f 70 72 69 61 74 65 20 0a 2a 2a 20 20 20 20 20  opriate .**     
2c80: 20 20 20 20 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65       non-zero [e
2c90: 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 6e  rror code] if an
2ca0: 79 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  y SQL statement 
2cb0: 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  fails..**.** {F1
2cc0: 32 31 30 37 7d 20 49 66 20 6f 6e 65 20 6f 72 20  2107} If one or 
2cd0: 6d 6f 72 65 20 6f 66 20 74 68 65 20 53 51 4c 20  more of the SQL 
2ce0: 73 74 61 74 65 6d 65 6e 74 73 20 68 61 6e 64 65  statements hande
2cf0: 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78  d to [sqlite3_ex
2d00: 65 63 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  ec()].**        
2d10: 20 20 72 65 74 75 72 6e 20 72 65 73 75 6c 74 73    return results
2d20: 20 61 6e 64 20 74 68 65 20 33 72 64 20 70 61 72   and the 3rd par
2d30: 61 6d 65 74 65 72 20 69 73 20 6e 6f 74 20 4e 55  ameter is not NU
2d40: 4c 4c 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20  LL, then.**     
2d50: 20 20 20 20 20 74 68 65 20 63 61 6c 6c 62 61 63       the callbac
2d60: 6b 20 66 75 6e 63 74 69 6f 6e 20 73 70 65 63 69  k function speci
2d70: 66 69 65 64 20 62 79 20 74 68 65 20 33 72 64 20  fied by the 3rd 
2d80: 70 61 72 61 6d 65 74 65 72 20 73 68 61 6c 6c 20  parameter shall 
2d90: 62 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  be.**          i
2da0: 6e 76 6f 6b 65 64 20 6f 6e 63 65 20 66 6f 72 20  nvoked once for 
2db0: 65 61 63 68 20 72 6f 77 20 6f 66 20 72 65 73 75  each row of resu
2dc0: 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31 31  lt..**.** {F1211
2dd0: 30 7d 20 49 66 20 74 68 65 20 63 61 6c 6c 62 61  0} If the callba
2de0: 63 6b 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e  ck returns a non
2df0: 2d 7a 65 72 6f 20 76 61 6c 75 65 20 74 68 65 6e  -zero value then
2e00: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
2e10: 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 68  ].**          sh
2e20: 61 6c 6c 20 61 62 6f 72 74 20 74 68 65 20 53 51  all abort the SQ
2e30: 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 74 20 69  L statement it i
2e40: 73 20 63 75 72 72 65 6e 74 6c 79 20 65 76 61 6c  s currently eval
2e50: 75 61 74 69 6e 67 2c 0a 2a 2a 20 20 20 20 20 20  uating,.**      
2e60: 20 20 20 20 73 6b 69 70 20 61 6c 6c 20 73 75 62      skip all sub
2e70: 73 65 71 75 65 6e 74 20 53 51 4c 20 73 74 61 74  sequent SQL stat
2e80: 65 6d 65 6e 74 73 2c 20 61 6e 64 20 72 65 74 75  ements, and retu
2e90: 72 6e 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54  rn [SQLITE_ABORT
2ea0: 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31 31 33  ]..**.** {F12113
2eb0: 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65  } The [sqlite3_e
2ec0: 78 65 63 28 29 5d 20 72 6f 75 74 69 6e 65 20 73  xec()] routine s
2ed0: 68 61 6c 6c 20 70 61 73 73 20 69 74 73 20 34 74  hall pass its 4t
2ee0: 68 20 70 61 72 61 6d 65 74 65 72 20 74 68 72 6f  h parameter thro
2ef0: 75 67 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ugh.**          
2f00: 61 73 20 74 68 65 20 31 73 74 20 70 61 72 61 6d  as the 1st param
2f10: 65 74 65 72 20 6f 66 20 74 68 65 20 63 61 6c 6c  eter of the call
2f20: 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  back..**.** {F12
2f30: 31 31 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  116} The [sqlite
2f40: 33 5f 65 78 65 63 28 29 5d 20 72 6f 75 74 69 6e  3_exec()] routin
2f50: 65 20 73 65 74 73 20 74 68 65 20 32 6e 64 20 70  e sets the 2nd p
2f60: 61 72 61 6d 65 74 65 72 20 6f 66 20 69 74 73 0a  arameter of its.
2f70: 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c  **          call
2f80: 62 61 63 6b 20 74 6f 20 62 65 20 74 68 65 20 6e  back to be the n
2f90: 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
2fa0: 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20   in the current 
2fb0: 72 6f 77 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20  row of.**       
2fc0: 20 20 20 72 65 73 75 6c 74 2e 0a 2a 2a 0a 2a 2a     result..**.**
2fd0: 20 7b 46 31 32 31 31 39 7d 20 54 68 65 20 5b 73   {F12119} The [s
2fe0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 72  qlite3_exec()] r
2ff0: 6f 75 74 69 6e 65 20 73 65 74 73 20 74 68 65 20  outine sets the 
3000: 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66  3rd parameter of
3010: 20 69 74 73 20 0a 2a 2a 20 20 20 20 20 20 20 20   its .**        
3020: 20 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 62 65    callback to be
3030: 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
3040: 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73  nters to strings
3050: 20 68 6f 6c 64 69 6e 67 20 74 68 65 0a 2a 2a 20   holding the.** 
3060: 20 20 20 20 20 20 20 20 20 76 61 6c 75 65 73 20           values 
3070: 66 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e 20  for each column 
3080: 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72  in the current r
3090: 65 73 75 6c 74 20 73 65 74 20 72 6f 77 20 61 73  esult set row as
30a0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 62 74  .**          obt
30b0: 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
30c0: 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
30d0: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31 32  )]..**.** {F1212
30e0: 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  2} The [sqlite3_
30f0: 65 78 65 63 28 29 5d 20 72 6f 75 74 69 6e 65 20  exec()] routine 
3100: 73 65 74 73 20 74 68 65 20 34 74 68 20 70 61 72  sets the 4th par
3110: 61 6d 65 74 65 72 20 6f 66 20 69 74 73 0a 2a 2a  ameter of its.**
3120: 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c 62 61            callba
3130: 63 6b 20 74 6f 20 62 65 20 61 6e 20 61 72 72 61  ck to be an arra
3140: 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f  y of pointers to
3150: 20 73 74 72 69 6e 67 73 20 68 6f 6c 64 69 6e 67   strings holding
3160: 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
3170: 20 6e 61 6d 65 73 20 6f 66 20 72 65 73 75 6c 74   names of result
3180: 20 63 6f 6c 75 6d 6e 73 20 61 73 20 6f 62 74 61   columns as obta
3190: 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
31a0: 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29  e3_column_name()
31b0: 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31 32 35  ]..**.** {F12125
31c0: 7d 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72  } If the 3rd par
31d0: 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
31e0: 65 33 5f 65 78 65 63 28 29 5d 20 69 73 20 4e 55  e3_exec()] is NU
31f0: 4c 4c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20  LL then.**      
3200: 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 65 78 65      [sqlite3_exe
3210: 63 28 29 5d 20 6e 65 76 65 72 20 69 6e 76 6f 6b  c()] never invok
3220: 65 73 20 61 20 63 61 6c 6c 62 61 63 6b 2e 20 20  es a callback.  
3230: 41 6c 6c 20 71 75 65 72 79 0a 2a 2a 20 20 20 20  All query.**    
3240: 20 20 20 20 20 20 72 65 73 75 6c 74 73 20 61 72        results ar
3250: 65 20 73 69 6c 65 6e 74 6c 79 20 64 69 73 63 61  e silently disca
3260: 72 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  rded..**.** {F12
3270: 31 33 31 7d 20 49 66 20 61 6e 20 65 72 72 6f 72  131} If an error
3280: 20 6f 63 63 75 72 73 20 77 68 69 6c 65 20 70 61   occurs while pa
3290: 72 73 69 6e 67 20 6f 72 20 65 76 61 6c 75 61 74  rsing or evaluat
32a0: 69 6e 67 20 61 6e 79 20 6f 66 20 74 68 65 20 53  ing any of the S
32b0: 51 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 68  QL.**          h
32c0: 61 6e 64 65 64 20 69 6e 20 74 68 65 20 53 20 70  anded in the S p
32d0: 61 72 61 6d 65 74 65 72 20 6f 66 20 5b 73 71 6c  arameter of [sql
32e0: 69 74 65 33 5f 65 78 65 63 28 44 2c 53 2c 43 2c  ite3_exec(D,S,C,
32f0: 41 2c 45 29 5d 20 61 6e 64 20 69 66 0a 2a 2a 20  A,E)] and if.** 
3300: 20 20 20 20 20 20 20 20 20 74 68 65 20 45 20 70           the E p
3310: 61 72 61 6d 65 74 65 72 20 69 73 20 6e 6f 74 20  arameter is not 
3320: 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 73 71 6c 69  NULL, then [sqli
3330: 74 65 33 5f 65 78 65 63 28 29 5d 20 73 68 61 6c  te3_exec()] shal
3340: 6c 20 73 74 6f 72 65 0a 2a 2a 20 20 20 20 20 20  l store.**      
3350: 20 20 20 20 69 6e 20 2a 45 20 61 6e 20 61 70 70      in *E an app
3360: 72 6f 70 72 69 61 74 65 20 65 72 72 6f 72 20 6d  ropriate error m
3370: 65 73 73 61 67 65 20 77 72 69 74 74 65 6e 20 69  essage written i
3380: 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69  nto memory obtai
3390: 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ned.**          
33a0: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
33b0: 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  lloc()]..**.** {
33c0: 46 31 32 31 33 34 7d 20 54 68 65 20 5b 73 71 6c  F12134} The [sql
33d0: 69 74 65 33 5f 65 78 65 63 28 44 2c 53 2c 43 2c  ite3_exec(D,S,C,
33e0: 41 2c 45 29 5d 20 72 6f 75 74 69 6e 65 20 73 68  A,E)] routine sh
33f0: 61 6c 6c 20 73 65 74 20 74 68 65 20 76 61 6c 75  all set the valu
3400: 65 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20  e of.**         
3410: 20 2a 45 20 74 6f 20 4e 55 4c 4c 20 69 66 20 45   *E to NULL if E
3420: 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64   is not NULL and
3430: 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20 65 72   there are no er
3440: 72 6f 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  rors..**.** {F12
3450: 31 33 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  137} The [sqlite
3460: 33 5f 65 78 65 63 28 44 2c 53 2c 43 2c 41 2c 45  3_exec(D,S,C,A,E
3470: 29 5d 20 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c  )] function shal
3480: 6c 20 73 65 74 20 74 68 65 20 65 72 72 6f 72 20  l set the error 
3490: 63 6f 64 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  code.**         
34a0: 20 61 6e 64 20 6d 65 73 73 61 67 65 20 61 63 63   and message acc
34b0: 65 73 73 69 62 6c 65 20 76 69 61 20 5b 73 71 6c  essible via [sql
34c0: 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 2c  ite3_errcode()],
34d0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
34e0: 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2c  lite3_errmsg()],
34f0: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 72   and [sqlite3_er
3500: 72 6d 73 67 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a  rmsg16()]..**.**
3510: 20 7b 46 31 32 31 33 38 7d 20 49 66 20 74 68 65   {F12138} If the
3520: 20 53 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20   S parameter to 
3530: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 44 2c  [sqlite3_exec(D,
3540: 53 2c 43 2c 41 2c 45 29 5d 20 69 73 20 61 20 6e  S,C,A,E)] is a n
3550: 75 6c 6c 20 6f 72 20 65 6d 70 74 79 0a 2a 2a 20  ull or empty.** 
3560: 20 20 20 20 20 20 20 20 20 73 74 72 69 6e 67 20           string 
3570: 6f 72 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 74 68  or contains noth
3580: 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 77  ing other than w
3590: 68 69 74 65 73 70 61 63 65 2c 20 63 6f 6d 6d 65  hitespace, comme
35a0: 6e 74 73 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 20  nts, and/or.**  
35b0: 20 20 20 20 20 20 20 20 73 65 6d 69 63 6f 6c 6f          semicolo
35c0: 6e 73 2c 20 74 68 65 6e 20 72 65 73 75 6c 74 73  ns, then results
35d0: 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 65 72 72   of [sqlite3_err
35e0: 63 6f 64 65 28 29 5d 2c 0a 2a 2a 20 20 20 20 20  code()],.**     
35f0: 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 65 72       [sqlite3_er
3600: 72 6d 73 67 28 29 5d 2c 20 61 6e 64 20 5b 73 71  rmsg()], and [sq
3610: 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29  lite3_errmsg16()
3620: 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 68  ].**          sh
3630: 61 6c 6c 20 72 65 73 65 74 20 74 6f 20 69 6e 64  all reset to ind
3640: 69 63 61 74 65 20 6e 6f 20 65 72 72 6f 72 73 2e  icate no errors.
3650: 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49 54 41 54 49 4f  .**.** LIMITATIO
3660: 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 55 31 32 31 34  NS:.**.** {U1214
3670: 31 7d 20 54 68 65 20 66 69 72 73 74 20 70 61 72  1} The first par
3680: 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
3690: 65 33 5f 65 78 65 63 28 29 5d 20 6d 75 73 74 20  e3_exec()] must 
36a0: 62 65 20 61 6e 20 76 61 6c 69 64 20 61 6e 64 20  be an valid and 
36b0: 6f 70 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  open.**         
36c0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
36d0: 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 55  ction]..**.** {U
36e0: 31 32 31 34 32 7d 20 54 68 65 20 64 61 74 61 62  12142} The datab
36f0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d  ase connection m
3700: 75 73 74 20 6e 6f 74 20 62 65 20 63 6c 6f 73 65  ust not be close
3710: 64 20 77 68 69 6c 65 0a 2a 2a 20 20 20 20 20 20  d while.**      
3720: 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 65 78 65      [sqlite3_exe
3730: 63 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 2e  c()] is running.
3740: 0a 2a 2a 20 0a 2a 2a 20 7b 55 31 32 31 34 33 7d  .** .** {U12143}
3750: 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e   The calling fun
3760: 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65  ction should use
3770: 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
3780: 5d 20 74 6f 20 66 72 65 65 0a 2a 2a 20 20 20 20  ] to free.**    
3790: 20 20 20 20 20 20 74 68 65 20 6d 65 6d 6f 72 79        the memory
37a0: 20 74 68 61 74 20 2a 65 72 72 6d 73 67 20 69 73   that *errmsg is
37b0: 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 61   left pointing a
37c0: 74 20 6f 6e 63 65 20 74 68 65 20 65 72 72 6f 72  t once the error
37d0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 65 73  .**          mes
37e0: 73 61 67 65 20 69 73 20 6e 6f 20 6c 6f 6e 67 65  sage is no longe
37f0: 72 20 6e 65 65 64 65 64 2e 0a 2a 2a 0a 2a 2a 20  r needed..**.** 
3800: 7b 55 31 32 31 34 35 7d 20 54 68 65 20 53 51 4c  {U12145} The SQL
3810: 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
3820: 69 6e 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  in the 2nd param
3830: 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
3840: 5f 65 78 65 63 28 29 5d 0a 2a 2a 20 20 20 20 20  _exec()].**     
3850: 20 20 20 20 20 6d 75 73 74 20 72 65 6d 61 69 6e       must remain
3860: 20 75 6e 63 68 61 6e 67 65 64 20 77 68 69 6c 65   unchanged while
3870: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
3880: 5d 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f  ] is running..*/
3890: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 65  .int sqlite3_exe
38a0: 63 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 20  c(.  sqlite3*,  
38b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
38c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
38d0: 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62  /* An open datab
38e0: 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ase */.  const c
38f0: 68 61 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 20  har *sql,       
3900: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3910: 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65      /* SQL to be
3920: 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20   evaluated */.  
3930: 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28  int (*callback)(
3940: 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a  void*,int,char**
3950: 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61  ,char**),  /* Ca
3960: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
3970: 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20 20  */.  void *,    
3980: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3990: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
39a0: 2f 2a 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20  /* 1st argument 
39b0: 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20  to callback */. 
39c0: 20 63 68 61 72 20 2a 2a 65 72 72 6d 73 67 20 20   char **errmsg  
39d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
39e0: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45              /* E
39f0: 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e  rror msg written
3a00: 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a   here */.);../*.
3a10: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73  ** CAPI3REF: Res
3a20: 75 6c 74 20 43 6f 64 65 73 20 7b 46 31 30 32 31  ult Codes {F1021
3a30: 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  0}.** KEYWORDS: 
3a40: 53 51 4c 49 54 45 5f 4f 4b 20 7b 65 72 72 6f 72  SQLITE_OK {error
3a50: 20 63 6f 64 65 7d 20 7b 65 72 72 6f 72 20 63 6f   code} {error co
3a60: 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20  des}.**.** Many 
3a70: 53 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73  SQLite functions
3a80: 20 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67   return an integ
3a90: 65 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66  er result code f
3aa0: 72 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77  rom the set show
3ab0: 6e 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64  n.** here in ord
3ac0: 65 72 20 74 6f 20 69 6e 64 69 63 61 74 65 73 20  er to indicates 
3ad0: 73 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75  success or failu
3ae0: 72 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  re..**.** See al
3af0: 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52  so: [SQLITE_IOER
3b00: 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65  R_READ | extende
3b10: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 0a  d result codes].
3b20: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
3b30: 45 5f 4f 4b 20 20 20 20 20 20 20 20 20 20 20 30  E_OK           0
3b40: 20 20 20 2f 2a 20 53 75 63 63 65 73 73 66 75 6c     /* Successful
3b50: 20 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65   result */./* be
3b60: 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72  ginning-of-error
3b70: 2d 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e  -codes */.#defin
3b80: 65 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 20  e SQLITE_ERROR  
3b90: 20 20 20 20 20 20 31 20 20 20 2f 2a 20 53 51 4c        1   /* SQL
3ba0: 20 65 72 72 6f 72 20 6f 72 20 6d 69 73 73 69 6e   error or missin
3bb0: 67 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64  g database */.#d
3bc0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54  efine SQLITE_INT
3bd0: 45 52 4e 41 4c 20 20 20 20 20 32 20 20 20 2f 2a  ERNAL     2   /*
3be0: 20 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20   Internal logic 
3bf0: 65 72 72 6f 72 20 69 6e 20 53 51 4c 69 74 65 20  error in SQLite 
3c00: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
3c10: 45 5f 50 45 52 4d 20 20 20 20 20 20 20 20 20 33  E_PERM         3
3c20: 20 20 20 2f 2a 20 41 63 63 65 73 73 20 70 65 72     /* Access per
3c30: 6d 69 73 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a  mission denied *
3c40: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3c50: 5f 41 42 4f 52 54 20 20 20 20 20 20 20 20 34 20  _ABORT        4 
3c60: 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f    /* Callback ro
3c70: 75 74 69 6e 65 20 72 65 71 75 65 73 74 65 64 20  utine requested 
3c80: 61 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66  an abort */.#def
3c90: 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20  ine SQLITE_BUSY 
3ca0: 20 20 20 20 20 20 20 20 35 20 20 20 2f 2a 20 54          5   /* T
3cb0: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
3cc0: 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64   is locked */.#d
3cd0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
3ce0: 4b 45 44 20 20 20 20 20 20 20 36 20 20 20 2f 2a  KED       6   /*
3cf0: 20 41 20 74 61 62 6c 65 20 69 6e 20 74 68 65 20   A table in the 
3d00: 64 61 74 61 62 61 73 65 20 69 73 20 6c 6f 63 6b  database is lock
3d10: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
3d20: 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20  LITE_NOMEM      
3d30: 20 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f    7   /* A mallo
3d40: 63 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64  c() failed */.#d
3d50: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
3d60: 44 4f 4e 4c 59 20 20 20 20 20 38 20 20 20 2f 2a  DONLY     8   /*
3d70: 20 41 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74   Attempt to writ
3d80: 65 20 61 20 72 65 61 64 6f 6e 6c 79 20 64 61 74  e a readonly dat
3d90: 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65  abase */.#define
3da0: 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50   SQLITE_INTERRUP
3db0: 54 20 20 20 20 39 20 20 20 2f 2a 20 4f 70 65 72  T    9   /* Oper
3dc0: 61 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64  ation terminated
3dd0: 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 74 65   by sqlite3_inte
3de0: 72 72 75 70 74 28 29 2a 2f 0a 23 64 65 66 69 6e  rrupt()*/.#defin
3df0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 20  e SQLITE_IOERR  
3e00: 20 20 20 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d       10   /* Som
3e10: 65 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20 49  e kind of disk I
3e20: 2f 4f 20 65 72 72 6f 72 20 6f 63 63 75 72 72 65  /O error occurre
3e30: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
3e40: 49 54 45 5f 43 4f 52 52 55 50 54 20 20 20 20 20  ITE_CORRUPT     
3e50: 31 31 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61  11   /* The data
3e60: 62 61 73 65 20 64 69 73 6b 20 69 6d 61 67 65 20  base disk image 
3e70: 69 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a  is malformed */.
3e80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
3e90: 4f 54 46 4f 55 4e 44 20 20 20 20 31 32 20 20 20  OTFOUND    12   
3ea0: 2f 2a 20 4e 4f 54 20 55 53 45 44 2e 20 54 61 62  /* NOT USED. Tab
3eb0: 6c 65 20 6f 72 20 72 65 63 6f 72 64 20 6e 6f 74  le or record not
3ec0: 20 66 6f 75 6e 64 20 2a 2f 0a 23 64 65 66 69 6e   found */.#defin
3ed0: 65 20 53 51 4c 49 54 45 5f 46 55 4c 4c 20 20 20  e SQLITE_FULL   
3ee0: 20 20 20 20 20 31 33 20 20 20 2f 2a 20 49 6e 73       13   /* Ins
3ef0: 65 72 74 69 6f 6e 20 66 61 69 6c 65 64 20 62 65  ertion failed be
3f00: 63 61 75 73 65 20 64 61 74 61 62 61 73 65 20 69  cause database i
3f10: 73 20 66 75 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e  s full */.#defin
3f20: 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45  e SQLITE_CANTOPE
3f30: 4e 20 20 20 20 31 34 20 20 20 2f 2a 20 55 6e 61  N    14   /* Una
3f40: 62 6c 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20  ble to open the 
3f50: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f  database file */
3f60: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3f70: 50 52 4f 54 4f 43 4f 4c 20 20 20 20 31 35 20 20  PROTOCOL    15  
3f80: 20 2f 2a 20 4e 4f 54 20 55 53 45 44 2e 20 44 61   /* NOT USED. Da
3f90: 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74  tabase lock prot
3fa0: 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64  ocol error */.#d
3fb0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50  efine SQLITE_EMP
3fc0: 54 59 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a  TY       16   /*
3fd0: 20 44 61 74 61 62 61 73 65 20 69 73 20 65 6d 70   Database is emp
3fe0: 74 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ty */.#define SQ
3ff0: 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20 20  LITE_SCHEMA     
4000: 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61 74   17   /* The dat
4010: 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61  abase schema cha
4020: 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nged */.#define 
4030: 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 20  SQLITE_TOOBIG   
4040: 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69 6e     18   /* Strin
4050: 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 64  g or BLOB exceed
4060: 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a  s size limit */.
4070: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
4080: 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20 20  ONSTRAINT  19   
4090: 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f 20  /* Abort due to 
40a0: 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61  constraint viola
40b0: 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  tion */.#define 
40c0: 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 20  SQLITE_MISMATCH 
40d0: 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20     20   /* Data 
40e0: 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f  type mismatch */
40f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4100: 4d 49 53 55 53 45 20 20 20 20 20 20 32 31 20 20  MISUSE      21  
4110: 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65 64   /* Library used
4120: 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a   incorrectly */.
4130: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
4140: 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20 20 20  OLFS       22   
4150: 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74 75  /* Uses OS featu
4160: 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 65  res not supporte
4170: 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65  d on host */.#de
4180: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48  fine SQLITE_AUTH
4190: 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20          23   /* 
41a0: 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65  Authorization de
41b0: 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nied */.#define 
41c0: 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 20  SQLITE_FORMAT   
41d0: 20 20 20 32 34 20 20 20 2f 2a 20 41 75 78 69 6c     24   /* Auxil
41e0: 69 61 72 79 20 64 61 74 61 62 61 73 65 20 66 6f  iary database fo
41f0: 72 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64  rmat error */.#d
4200: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e  efine SQLITE_RAN
4210: 47 45 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a  GE       25   /*
4220: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74   2nd parameter t
4230: 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f  o sqlite3_bind o
4240: 75 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23  ut of range */.#
4250: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
4260: 54 41 44 42 20 20 20 20 20 20 32 36 20 20 20 2f  TADB      26   /
4270: 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 74 68  * File opened th
4280: 61 74 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61  at is not a data
4290: 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65  base file */.#de
42a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 4f 57 20  fine SQLITE_ROW 
42b0: 20 20 20 20 20 20 20 20 31 30 30 20 20 2f 2a 20          100  /* 
42c0: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68  sqlite3_step() h
42d0: 61 73 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 72  as another row r
42e0: 65 61 64 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  eady */.#define 
42f0: 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20 20 20 20  SQLITE_DONE     
4300: 20 20 20 31 30 31 20 20 2f 2a 20 73 71 6c 69 74     101  /* sqlit
4310: 65 33 5f 73 74 65 70 28 29 20 68 61 73 20 66 69  e3_step() has fi
4320: 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67  nished executing
4330: 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72   */./* end-of-er
4340: 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a  ror-codes */../*
4350: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 78  .** CAPI3REF: Ex
4360: 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f  tended Result Co
4370: 64 65 73 20 7b 46 31 30 32 32 30 7d 0a 2a 2a 20  des {F10220}.** 
4380: 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e  KEYWORDS: {exten
4390: 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 7d 20  ded error code} 
43a0: 7b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  {extended error 
43b0: 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52  codes}.** KEYWOR
43c0: 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 65  DS: {extended re
43d0: 73 75 6c 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a  sult codes}.**.*
43e0: 2a 20 49 6e 20 69 74 73 20 64 65 66 61 75 6c 74  * In its default
43f0: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20   configuration, 
4400: 53 51 4c 69 74 65 20 41 50 49 20 72 6f 75 74 69  SQLite API routi
4410: 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f  nes return one o
4420: 66 20 32 36 20 69 6e 74 65 67 65 72 0a 2a 2a 20  f 26 integer.** 
4430: 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 72 65 73  [SQLITE_OK | res
4440: 75 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77  ult codes].  How
4450: 65 76 65 72 2c 20 65 78 70 65 72 69 65 6e 63 65  ever, experience
4460: 20 68 61 73 20 73 68 6f 77 6e 20 74 68 61 74 0a   has shown that.
4470: 2a 2a 20 6d 61 6e 79 20 6f 66 20 74 68 65 73 65  ** many of these
4480: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72   result codes ar
4490: 65 20 74 6f 6f 20 63 6f 75 72 73 65 2d 67 72 61  e too course-gra
44a0: 69 6e 65 64 2e 20 20 54 68 65 79 20 64 6f 20 6e  ined.  They do n
44b0: 6f 74 20 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a  ot provide as.**
44c0: 20 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f   much informatio
44d0: 6e 20 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73  n about problems
44e0: 20 61 73 20 70 72 6f 67 72 61 6d 6d 65 72 73 20   as programmers 
44f0: 6d 69 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20  might like.  In 
4500: 61 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20  an effort to.** 
4510: 61 64 64 72 65 73 73 20 74 68 69 73 2c 20 6e 65  address this, ne
4520: 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  wer versions of 
4530: 53 51 4c 69 74 65 20 28 76 65 72 73 69 6f 6e 20  SQLite (version 
4540: 33 2e 33 2e 38 20 61 6e 64 20 6c 61 74 65 72 29  3.3.8 and later)
4550: 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70 70   include.** supp
4560: 6f 72 74 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  ort for addition
4570: 61 6c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  al result codes 
4580: 74 68 61 74 20 70 72 6f 76 69 64 65 20 6d 6f 72  that provide mor
4590: 65 20 64 65 74 61 69 6c 65 64 20 69 6e 66 6f 72  e detailed infor
45a0: 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20  mation.** about 
45b0: 65 72 72 6f 72 73 2e 20 54 68 65 20 65 78 74 65  errors. The exte
45c0: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
45d0: 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20 6f 72  s are enabled or
45e0: 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 66 6f 72   disabled.** for
45f0: 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63   each database c
4600: 6f 6e 6e 65 63 74 69 6f 6e 20 75 73 69 6e 67 20  onnection using 
4610: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 74  the [sqlite3_ext
4620: 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64  ended_result_cod
4630: 65 73 28 29 5d 0a 2a 2a 20 41 50 49 2e 0a 2a 2a  es()].** API..**
4640: 20 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68 65   .** Some of the
4650: 20 61 76 61 69 6c 61 62 6c 65 20 65 78 74 65 6e   available exten
4660: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
4670: 20 61 72 65 20 6c 69 73 74 65 64 20 68 65 72 65   are listed here
4680: 2e 0a 2a 2a 20 4f 6e 65 20 6d 61 79 20 65 78 70  ..** One may exp
4690: 65 63 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ect the number o
46a0: 66 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  f extended resul
46b0: 74 20 63 6f 64 65 73 20 77 69 6c 6c 20 62 65 20  t codes will be 
46c0: 65 78 70 61 6e 64 0a 2a 2a 20 6f 76 65 72 20 74  expand.** over t
46d0: 69 6d 65 2e 20 20 53 6f 66 74 77 61 72 65 20 74  ime.  Software t
46e0: 68 61 74 20 75 73 65 73 20 65 78 74 65 6e 64 65  hat uses extende
46f0: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 73  d result codes s
4700: 68 6f 75 6c 64 20 65 78 70 65 63 74 0a 2a 2a 20  hould expect.** 
4710: 74 6f 20 73 65 65 20 6e 65 77 20 72 65 73 75 6c  to see new resul
4720: 74 20 63 6f 64 65 73 20 69 6e 20 66 75 74 75 72  t codes in futur
4730: 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
4740: 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Lite..**.** The 
4750: 53 51 4c 49 54 45 5f 4f 4b 20 72 65 73 75 6c 74  SQLITE_OK result
4760: 20 63 6f 64 65 20 77 69 6c 6c 20 6e 65 76 65 72   code will never
4770: 20 62 65 20 65 78 74 65 6e 64 65 64 2e 20 20 49   be extended.  I
4780: 74 20 77 69 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a  t will always.**
4790: 20 62 65 20 65 78 61 63 74 6c 79 20 7a 65 72 6f   be exactly zero
47a0: 2e 0a 2a 2a 20 0a 2a 2a 20 49 4e 56 41 52 49 41  ..** .** INVARIA
47b0: 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 32  NTS:.**.** {F102
47c0: 32 33 7d 20 54 68 65 20 73 79 6d 62 6f 6c 69 63  23} The symbolic
47d0: 20 6e 61 6d 65 20 66 6f 72 20 61 6e 20 65 78 74   name for an ext
47e0: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
47f0: 65 20 61 6c 77 61 79 73 20 63 6f 6e 74 61 69 6e  e always contain
4800: 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20  s.**          a 
4810: 72 65 6c 61 74 65 64 20 70 72 69 6d 61 72 79 20  related primary 
4820: 72 65 73 75 6c 74 20 63 6f 64 65 20 61 73 20 61  result code as a
4830: 20 70 72 65 66 69 78 2e 0a 2a 2a 0a 2a 2a 20 7b   prefix..**.** {
4840: 46 31 30 32 32 34 7d 20 50 72 69 6d 61 72 79 20  F10224} Primary 
4850: 72 65 73 75 6c 74 20 63 6f 64 65 20 6e 61 6d 65  result code name
4860: 73 20 63 6f 6e 74 61 69 6e 20 61 20 73 69 6e 67  s contain a sing
4870: 6c 65 20 22 5f 22 20 63 68 61 72 61 63 74 65 72  le "_" character
4880: 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 32 32 35 7d  ..**.** {F10225}
4890: 20 45 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   Extended result
48a0: 20 63 6f 64 65 20 6e 61 6d 65 73 20 63 6f 6e 74   code names cont
48b0: 61 69 6e 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20  ain two or more 
48c0: 22 5f 22 20 63 68 61 72 61 63 74 65 72 73 2e 0a  "_" characters..
48d0: 2a 2a 0a 2a 2a 20 7b 46 31 30 32 32 36 7d 20 54  **.** {F10226} T
48e0: 68 65 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65  he numeric value
48f0: 20 6f 66 20 61 6e 20 65 78 74 65 6e 64 65 64 20   of an extended 
4900: 72 65 73 75 6c 74 20 63 6f 64 65 20 63 6f 6e 74  result code cont
4910: 61 69 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  ains the.**     
4920: 20 20 20 20 20 6e 75 6d 65 72 69 63 20 76 61 6c       numeric val
4930: 75 65 20 6f 66 20 69 74 73 20 63 6f 72 72 65 73  ue of its corres
4940: 70 6f 6e 64 69 6e 67 20 70 72 69 6d 61 72 79 20  ponding primary 
4950: 72 65 73 75 6c 74 20 63 6f 64 65 20 69 6e 0a 2a  result code in.*
4960: 2a 20 20 20 20 20 20 20 20 20 20 69 74 73 20 6c  *          its l
4970: 65 61 73 74 20 73 69 67 6e 69 66 69 63 61 6e 74  east significant
4980: 20 38 20 62 69 74 73 2e 0a 2a 2f 0a 23 64 65 66   8 bits..*/.#def
4990: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
49a0: 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20  _READ           
49b0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
49c0: 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69   | (1<<8)).#defi
49d0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
49e0: 53 48 4f 52 54 5f 52 45 41 44 20 20 20 20 20 20  SHORT_READ      
49f0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
4a00: 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (2<<8)).#defin
4a10: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 57  e SQLITE_IOERR_W
4a20: 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20 20  RITE            
4a30: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
4a40: 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (3<<8)).#define
4a50: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53   SQLITE_IOERR_FS
4a60: 59 4e 43 20 20 20 20 20 20 20 20 20 20 20 20 20  YNC             
4a70: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4a80: 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (4<<8)).#define 
4a90: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52  SQLITE_IOERR_DIR
4aa0: 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20 20 28  _FSYNC         (
4ab0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
4ac0: 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  5<<8)).#define S
4ad0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52 55 4e  QLITE_IOERR_TRUN
4ae0: 43 41 54 45 20 20 20 20 20 20 20 20 20 20 28 53  CATE          (S
4af0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 36  QLITE_IOERR | (6
4b00: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
4b10: 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 54 41 54  LITE_IOERR_FSTAT
4b20: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
4b30: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 37 3c  LITE_IOERR | (7<
4b40: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
4b50: 49 54 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b  ITE_IOERR_UNLOCK
4b60: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
4b70: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c 3c  ITE_IOERR | (8<<
4b80: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4b90: 54 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b 20  TE_IOERR_RDLOCK 
4ba0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4bb0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c 38  TE_IOERR | (9<<8
4bc0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
4bd0: 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 20 20  E_IOERR_DELETE  
4be0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
4bf0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c 38  E_IOERR | (10<<8
4c00: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
4c10: 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 20  E_IOERR_BLOCKED 
4c20: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
4c30: 45 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c 38  E_IOERR | (11<<8
4c40: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
4c50: 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20 20  E_IOERR_NOMEM   
4c60: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
4c70: 45 5f 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c 38  E_IOERR | (12<<8
4c80: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
4c90: 45 5f 49 4f 45 52 52 5f 41 43 43 45 53 53 20 20  E_IOERR_ACCESS  
4ca0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
4cb0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 33 3c 3c 38  E_IOERR | (13<<8
4cc0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
4cd0: 45 5f 49 4f 45 52 52 5f 43 48 45 43 4b 52 45 53  E_IOERR_CHECKRES
4ce0: 45 52 56 45 44 4c 4f 43 4b 20 28 53 51 4c 49 54  ERVEDLOCK (SQLIT
4cf0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 34 3c 3c 38  E_IOERR | (14<<8
4d00: 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  ))../*.** CAPI3R
4d10: 45 46 3a 20 46 6c 61 67 73 20 46 6f 72 20 46 69  EF: Flags For Fi
4d20: 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61 74 69 6f  le Open Operatio
4d30: 6e 73 20 7b 46 31 30 32 33 30 7d 0a 2a 2a 0a 2a  ns {F10230}.**.*
4d40: 2a 20 54 68 65 73 65 20 62 69 74 20 76 61 6c 75  * These bit valu
4d50: 65 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20  es are intended 
4d60: 66 6f 72 20 75 73 65 20 69 6e 20 74 68 65 0a 2a  for use in the.*
4d70: 2a 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  * 3rd parameter 
4d80: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
4d90: 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72  open_v2()] inter
4da0: 66 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74  face and.** in t
4db0: 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
4dc0: 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65   to the xOpen me
4dd0: 74 68 6f 64 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  thod of the.** [
4de0: 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
4df0: 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ect..*/.#define 
4e00: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
4e10: 4f 4e 4c 59 20 20 20 20 20 20 20 20 20 30 78 30  ONLY         0x0
4e20: 30 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20  0000001.#define 
4e30: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
4e40: 57 52 49 54 45 20 20 20 20 20 20 20 20 30 78 30  WRITE        0x0
4e50: 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20  0000002.#define 
4e60: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
4e70: 54 45 20 20 20 20 20 20 20 20 20 20 20 30 78 30  TE           0x0
4e80: 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20  0000004.#define 
4e90: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
4ea0: 54 45 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78 30  TEONCLOSE    0x0
4eb0: 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20  0000008.#define 
4ec0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
4ed0: 55 53 49 56 45 20 20 20 20 20 20 20 20 30 78 30  USIVE        0x0
4ee0: 30 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20  0000010.#define 
4ef0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e  SQLITE_OPEN_MAIN
4f00: 5f 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30  _DB          0x0
4f10: 30 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20  0000100.#define 
4f20: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50  SQLITE_OPEN_TEMP
4f30: 5f 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30  _DB          0x0
4f40: 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20  0000200.#define 
4f50: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e  SQLITE_OPEN_TRAN
4f60: 53 49 45 4e 54 5f 44 42 20 20 20 20 20 30 78 30  SIENT_DB     0x0
4f70: 30 30 30 30 34 30 30 0a 23 64 65 66 69 6e 65 20  0000400.#define 
4f80: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e  SQLITE_OPEN_MAIN
4f90: 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30  _JOURNAL     0x0
4fa0: 30 30 30 30 38 30 30 0a 23 64 65 66 69 6e 65 20  0000800.#define 
4fb0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50  SQLITE_OPEN_TEMP
4fc0: 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30  _JOURNAL     0x0
4fd0: 30 30 30 31 30 30 30 0a 23 64 65 66 69 6e 65 20  0001000.#define 
4fe0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a  SQLITE_OPEN_SUBJ
4ff0: 4f 55 52 4e 41 4c 20 20 20 20 20 20 20 30 78 30  OURNAL       0x0
5000: 30 30 30 32 30 30 30 0a 23 64 65 66 69 6e 65 20  0002000.#define 
5010: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54  SQLITE_OPEN_MAST
5020: 45 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30  ER_JOURNAL   0x0
5030: 30 30 30 34 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43  0004000../*.** C
5040: 41 50 49 33 52 45 46 3a 20 44 65 76 69 63 65 20  API3REF: Device 
5050: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20  Characteristics 
5060: 7b 46 31 30 32 34 30 7d 0a 2a 2a 0a 2a 2a 20 54  {F10240}.**.** T
5070: 68 65 20 78 44 65 76 69 63 65 43 61 70 61 62 69  he xDeviceCapabi
5080: 6c 69 74 69 65 73 20 6d 65 74 68 6f 64 20 6f 66  lities method of
5090: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f   the [sqlite3_io
50a0: 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a  _methods].** obj
50b0: 65 63 74 20 72 65 74 75 72 6e 73 20 61 6e 20 69  ect returns an i
50c0: 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20  nteger which is 
50d0: 61 20 76 65 63 74 6f 72 20 6f 66 20 74 68 65 20  a vector of the 
50e0: 74 68 65 73 65 0a 2a 2a 20 62 69 74 20 76 61 6c  these.** bit val
50f0: 75 65 73 20 65 78 70 72 65 73 73 69 6e 67 20 49  ues expressing I
5100: 2f 4f 20 63 68 61 72 61 63 74 65 72 69 73 74 69  /O characteristi
5110: 63 73 20 6f 66 20 74 68 65 20 6d 61 73 73 20 73  cs of the mass s
5120: 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69 63 65  torage.** device
5130: 20 74 68 61 74 20 68 6f 6c 64 73 20 74 68 65 20   that holds the 
5140: 66 69 6c 65 20 74 68 61 74 20 74 68 65 20 5b 73  file that the [s
5150: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
5160: 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74 6f 2e  s].** refers to.
5170: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54  .**.** The SQLIT
5180: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70  E_IOCAP_ATOMIC p
5190: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
51a0: 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66  at all writes of
51b0: 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65  .** any size are
51c0: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51   atomic.  The SQ
51d0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
51e0: 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d  Cnnn values.** m
51f0: 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20  ean that writes 
5200: 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61  of blocks that a
5210: 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20  re nnn bytes in 
5220: 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20  size and.** are 
5230: 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64  aligned to an ad
5240: 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61  dress which is a
5250: 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70  n integer multip
5260: 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65  le of.** nnn are
5270: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51   atomic.  The SQ
5280: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f  LITE_IOCAP_SAFE_
5290: 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61  APPEND value mea
52a0: 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20  ns.** that when 
52b0: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64  data is appended
52c0: 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20   to a file, the 
52d0: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64  data is appended
52e0: 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74  .** first then t
52f0: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66  he size of the f
5300: 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c  ile is extended,
5310: 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72   never the other
5320: 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20  .** way around. 
5330: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
5340: 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f  P_SEQUENTIAL pro
5350: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
5360: 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** information 
5370: 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69  is written to di
5380: 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f  sk in the same o
5390: 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a  rder as calls.**
53a0: 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2f   to xWrite()..*/
53b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
53c0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20 20 20  IOCAP_ATOMIC    
53d0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31        0x00000001
53e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
53f0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 20  IOCAP_ATOMIC512 
5400: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32        0x00000002
5410: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5420: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20  IOCAP_ATOMIC1K  
5430: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34        0x00000004
5440: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5450: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20  IOCAP_ATOMIC2K  
5460: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 38        0x00000008
5470: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5480: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20  IOCAP_ATOMIC4K  
5490: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30        0x00000010
54a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
54b0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20  IOCAP_ATOMIC8K  
54c0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30        0x00000020
54d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
54e0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20  IOCAP_ATOMIC16K 
54f0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30        0x00000040
5500: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5510: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20  IOCAP_ATOMIC32K 
5520: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 38 30        0x00000080
5530: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5540: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20  IOCAP_ATOMIC64K 
5550: 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30        0x00000100
5560: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5570: 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e  IOCAP_SAFE_APPEN
5580: 44 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30  D     0x00000200
5590: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
55a0: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
55b0: 20 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30        0x00000400
55c0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
55d0: 3a 20 46 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c  : File Locking L
55e0: 65 76 65 6c 73 20 7b 46 31 30 32 35 30 7d 0a 2a  evels {F10250}.*
55f0: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73  *.** SQLite uses
5600: 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e   one of these in
5610: 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20  teger values as 
5620: 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72  the second.** ar
5630: 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20  gument to calls 
5640: 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20  it makes to the 
5650: 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c  xLock() and xUnl
5660: 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a  ock() methods.**
5670: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   of an [sqlite3_
5680: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
5690: 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ct..*/.#define S
56a0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20  QLITE_LOCK_NONE 
56b0: 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69           0.#defi
56c0: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53  ne SQLITE_LOCK_S
56d0: 48 41 52 45 44 20 20 20 20 20 20 20 20 31 0a 23  HARED        1.#
56e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
56f0: 43 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20 20  CK_RESERVED     
5700: 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
5710: 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20  E_LOCK_PENDING  
5720: 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
5730: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55  QLITE_LOCK_EXCLU
5740: 53 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a  SIVE     4../*.*
5750: 2a 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63  * CAPI3REF: Sync
5760: 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65  hronization Type
5770: 20 46 6c 61 67 73 20 7b 46 31 30 32 36 30 7d 0a   Flags {F10260}.
5780: 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69 74  **.** When SQLit
5790: 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 78 53  e invokes the xS
57a0: 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f 66 20  ync() method of 
57b0: 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69  an.** [sqlite3_i
57c0: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
57d0: 74 20 69 74 20 75 73 65 73 20 61 20 63 6f 6d 62  t it uses a comb
57e0: 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68  ination of.** th
57f0: 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75  ese integer valu
5800: 65 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  es as the second
5810: 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
5820: 20 57 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45   When the SQLITE
5830: 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 66  _SYNC_DATAONLY f
5840: 6c 61 67 20 69 73 20 75 73 65 64 2c 20 69 74 20  lag is used, it 
5850: 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 0a 2a  means that the.*
5860: 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e  * sync operation
5870: 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 66   only needs to f
5880: 6c 75 73 68 20 64 61 74 61 20 74 6f 20 6d 61 73  lush data to mas
5890: 73 20 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f 64  s storage.  Inod
58a0: 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  e.** information
58b0: 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 66 6c 75   need not be flu
58c0: 73 68 65 64 2e 20 54 68 65 20 53 51 4c 49 54 45  shed. The SQLITE
58d0: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 66 6c 61  _SYNC_NORMAL fla
58e0: 67 20 6d 65 61 6e 73 20 0a 2a 2a 20 74 6f 20 75  g means .** to u
58f0: 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28  se normal fsync(
5900: 29 20 73 65 6d 61 6e 74 69 63 73 2e 20 54 68 65  ) semantics. The
5910: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
5920: 4c 20 66 6c 61 67 20 6d 65 61 6e 73 20 0a 2a 2a  L flag means .**
5930: 20 74 6f 20 75 73 65 20 4d 61 63 20 4f 53 2d 58   to use Mac OS-X
5940: 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 20   style fullsync 
5950: 69 6e 73 74 65 61 64 20 6f 66 20 66 73 79 6e 63  instead of fsync
5960: 28 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ()..*/.#define S
5970: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
5980: 4c 20 20 20 20 20 20 20 20 30 78 30 30 30 30 32  L        0x00002
5990: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
59a0: 53 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20  SYNC_FULL       
59b0: 20 20 20 30 78 30 30 30 30 33 0a 23 64 65 66 69     0x00003.#defi
59c0: 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44  ne SQLITE_SYNC_D
59d0: 41 54 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30  ATAONLY      0x0
59e0: 30 30 31 30 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  0010.../*.** CAP
59f0: 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66  I3REF: OS Interf
5a00: 61 63 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61  ace Open File Ha
5a10: 6e 64 6c 65 20 7b 46 31 31 31 31 30 7d 0a 2a 2a  ndle {F11110}.**
5a20: 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f  .** An [sqlite3_
5a30: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70  file] object rep
5a40: 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20  resents an open 
5a50: 66 69 6c 65 20 69 6e 20 74 68 65 20 4f 53 0a 2a  file in the OS.*
5a60: 2a 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65  * interface laye
5a70: 72 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f  r.  Individual O
5a80: 53 20 69 6e 74 65 72 66 61 63 65 20 69 6d 70 6c  S interface impl
5a90: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c  ementations will
5aa0: 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75 62 63  .** want to subc
5ab0: 6c 61 73 73 20 74 68 69 73 20 6f 62 6a 65 63 74  lass this object
5ac0: 20 62 79 20 61 70 70 65 6e 64 69 6e 67 20 61 64   by appending ad
5ad0: 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a  ditional fields.
5ae0: 2a 2a 20 66 6f 72 20 74 68 65 69 72 20 6f 77 6e  ** for their own
5af0: 20 75 73 65 2e 20 20 54 68 65 20 70 4d 65 74 68   use.  The pMeth
5b00: 6f 64 73 20 65 6e 74 72 79 20 69 73 20 61 20 70  ods entry is a p
5b10: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ointer to an.** 
5b20: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
5b30: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74  ods] object that
5b40: 20 64 65 66 69 6e 65 73 20 6d 65 74 68 6f 64 73   defines methods
5b50: 20 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a   for performing.
5b60: 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e  ** I/O operation
5b70: 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66 69  s on the open fi
5b80: 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  le..*/.typedef s
5b90: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69  truct sqlite3_fi
5ba0: 6c 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b  le sqlite3_file;
5bb0: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
5bc0: 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73  file {.  const s
5bd0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f  truct sqlite3_io
5be0: 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f  _methods *pMetho
5bf0: 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20  ds;  /* Methods 
5c00: 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65  for an open file
5c10: 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
5c20: 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72  PI3REF: OS Inter
5c30: 66 61 63 65 20 46 69 6c 65 20 56 69 72 74 75 61  face File Virtua
5c40: 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63 74  l Methods Object
5c50: 20 7b 46 31 31 31 32 30 7d 0a 2a 2a 0a 2a 2a 20   {F11120}.**.** 
5c60: 45 76 65 72 79 20 66 69 6c 65 20 6f 70 65 6e 65  Every file opene
5c70: 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65  d by the [sqlite
5c80: 33 5f 76 66 73 5d 20 78 4f 70 65 6e 20 6d 65 74  3_vfs] xOpen met
5c90: 68 6f 64 20 63 6f 6e 74 61 69 6e 73 20 61 20 70  hod contains a p
5ca0: 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 61 6e 20  ointer to.** an 
5cb0: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
5cc0: 20 6f 62 6a 65 63 74 2e 20 20 54 68 69 73 20 6f   object.  This o
5cd0: 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68  bject defines th
5ce0: 65 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 75 73 65  e.** methods use
5cf0: 64 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72  d to perform var
5d00: 69 6f 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 20  ious operations 
5d10: 61 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65 6e  against the open
5d20: 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   file..**.** The
5d30: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
5d40: 74 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20  to xSync may be 
5d50: 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53  one of [SQLITE_S
5d60: 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a  YNC_NORMAL] or.*
5d70: 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  * [SQLITE_SYNC_F
5d80: 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74  ULL].  The first
5d90: 20 63 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e   choice is the n
5da0: 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a  ormal fsync()..*
5db0: 20 20 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f    The second cho
5dc0: 69 63 65 20 69 73 20 61 6e 0a 2a 2a 20 4f 53 2d  ice is an.** OS-
5dd0: 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63  X style fullsync
5de0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59  .  The SQLITE_SY
5df0: 4e 43 5f 44 41 54 41 20 66 6c 61 67 20 6d 61 79  NC_DATA flag may
5e00: 20 62 65 20 4f 52 65 64 20 69 6e 20 74 6f 0a 2a   be ORed in to.*
5e10: 2a 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20  * indicate that 
5e20: 6f 6e 6c 79 20 74 68 65 20 64 61 74 61 20 6f 66  only the data of
5e30: 20 74 68 65 20 66 69 6c 65 20 61 6e 64 20 6e 6f   the file and no
5e40: 74 20 69 74 73 20 69 6e 6f 64 65 20 6e 65 65 64  t its inode need
5e50: 73 20 74 6f 20 62 65 0a 2a 2a 20 73 79 6e 63 65  s to be.** synce
5e60: 64 2e 0a 2a 2a 20 0a 2a 2a 20 54 68 65 20 69 6e  d..** .** The in
5e70: 74 65 67 65 72 20 76 61 6c 75 65 73 20 74 6f 20  teger values to 
5e80: 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c  xLock() and xUnl
5e90: 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f 66  ock() are one of
5ea0: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
5eb0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f   [SQLITE_LOCK_NO
5ec0: 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  NE],.** <li> [SQ
5ed0: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44  LITE_LOCK_SHARED
5ee0: 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
5ef0: 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44  TE_LOCK_RESERVED
5f00: 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
5f10: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d  TE_LOCK_PENDING]
5f20: 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  , or.** <li> [SQ
5f30: 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53  LITE_LOCK_EXCLUS
5f40: 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  IVE]..** </ul>.*
5f50: 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65 61  * xLock() increa
5f60: 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55  ses the lock. xU
5f70: 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 61 73 65  nlock() decrease
5f80: 73 20 74 68 65 20 6c 6f 63 6b 2e 20 20 0a 2a 2a  s the lock.  .**
5f90: 20 54 68 65 20 78 43 68 65 63 6b 52 65 73 65 72   The xCheckReser
5fa0: 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64  vedLock() method
5fb0: 20 6c 6f 6f 6b 73 0a 2a 2a 20 74 6f 20 73 65 65   looks.** to see
5fc0: 20 69 66 20 61 6e 79 20 64 61 74 61 62 61 73 65   if any database
5fd0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 65 69 74   connection, eit
5fe0: 68 65 72 20 69 6e 20 74 68 69 73 0a 2a 2a 20 70  her in this.** p
5ff0: 72 6f 63 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d  rocess or in som
6000: 65 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2c  e other process,
6010: 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 6e 20 52   is holding an R
6020: 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44  ESERVED,.** PEND
6030: 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53 49 56  ING, or EXCLUSIV
6040: 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69  E lock on the fi
6050: 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20  le.  It returns 
6060: 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63 68 20  true.** if such 
6070: 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20 61 6e  a lock exists an
6080: 64 20 66 61 6c 73 65 20 69 66 20 6e 6f 74 2e 0a  d false if not..
6090: 2a 2a 20 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65  ** .** The xFile
60a0: 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64  Control() method
60b0: 20 69 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e   is a generic in
60c0: 74 65 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c  terface that all
60d0: 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46  ows custom.** VF
60e0: 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
60f0: 73 20 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f  s to directly co
6100: 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69  ntrol an open fi
6110: 6c 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  le using the.** 
6120: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
6130: 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61  ntrol()] interfa
6140: 63 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ce.  The second 
6150: 22 6f 70 22 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  "op" argument.**
6160: 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6f   is an integer o
6170: 70 63 6f 64 65 2e 20 20 20 54 68 65 20 74 68 69  pcode.   The thi
6180: 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69  rd.** argument i
6190: 73 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e  s a generic poin
61a0: 74 65 72 20 77 68 69 63 68 20 69 73 20 69 6e 74  ter which is int
61b0: 65 6e 64 65 64 20 74 6f 20 62 65 20 61 20 70 6f  ended to be a po
61c0: 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 61 20 73 74  inter.** to a st
61d0: 72 75 63 74 75 72 65 20 74 68 61 74 20 6d 61 79  ructure that may
61e0: 20 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e   contain argumen
61f0: 74 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77  ts or space in w
6200: 68 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65  hich to.** write
6210: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20   return values. 
6220: 20 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20   Potential uses 
6230: 66 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  for xFileControl
6240: 28 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66  () might be.** f
6250: 75 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62  unctions to enab
6260: 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b  le blocking lock
6270: 73 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c  s with timeouts,
6280: 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a   to change the.*
6290: 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65  * locking strate
62a0: 67 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20  gy (for example 
62b0: 74 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20  to use dot-file 
62c0: 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69  locks), to inqui
62d0: 72 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20  re.** about the 
62e0: 73 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b  status of a lock
62f0: 2c 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74  , or to break st
6300: 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20  ale locks.  The 
6310: 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72  SQLite.** core r
6320: 65 73 65 72 76 65 73 20 6f 70 63 6f 64 65 73 20  eserves opcodes 
6330: 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f  less than 100 fo
6340: 72 20 69 74 73 20 6f 77 6e 20 75 73 65 2e 20 0a  r its own use. .
6350: 2a 2a 20 41 20 5b 53 51 4c 49 54 45 5f 46 43 4e  ** A [SQLITE_FCN
6360: 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 7c 20 6c  TL_LOCKSTATE | l
6370: 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20  ist of opcodes] 
6380: 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 69 73  less than 100 is
6390: 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41   available..** A
63a0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
63b0: 20 64 65 66 69 6e 65 20 61 20 63 75 73 74 6f 6d   define a custom
63c0: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65   xFileControl me
63d0: 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73 65 20  thod should use 
63e0: 6f 70 63 6f 64 65 73 20 0a 2a 2a 20 67 72 65 61  opcodes .** grea
63f0: 74 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f 20  ter than 100 to 
6400: 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e  avoid conflicts.
6410: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63 74  .**.** The xSect
6420: 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64 20  orSize() method 
6430: 72 65 74 75 72 6e 73 20 74 68 65 20 73 65 63 74  returns the sect
6440: 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a  or size of the.*
6450: 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 75 6e  * device that un
6460: 64 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c 65  derlies the file
6470: 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20 73 69  .  The sector si
6480: 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e  ze is the.** min
6490: 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74 20  imum write that 
64a0: 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64  can be performed
64b0: 20 77 69 74 68 6f 75 74 20 64 69 73 74 75 72 62   without disturb
64c0: 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74  ing.** other byt
64d0: 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e 20  es in the file. 
64e0: 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61 72   The xDeviceChar
64f0: 61 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a 2a  acteristics().**
6500: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
6510: 61 20 62 69 74 20 76 65 63 74 6f 72 20 64 65 73  a bit vector des
6520: 63 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f 72  cribing behavior
6530: 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65  s of the.** unde
6540: 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a  rlying device:.*
6550: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
6560: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6570: 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20  ATOMIC].** <li> 
6580: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
6590: 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC512].** <li>
65a0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
65b0: 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC1K].** <li>
65c0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
65d0: 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC2K].** <li>
65e0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
65f0: 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC4K].** <li>
6600: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
6610: 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC8K].** <li>
6620: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
6630: 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69  TOMIC16K].** <li
6640: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6650: 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c  ATOMIC32K].** <l
6660: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
6670: 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c  _ATOMIC64K].** <
6680: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
6690: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a  P_SAFE_APPEND].*
66a0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
66b0: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d  OCAP_SEQUENTIAL]
66c0: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
66d0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
66e0: 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79  _ATOMIC property
66f0: 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20   means that all 
6700: 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79  writes of.** any
6710: 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63   size are atomic
6720: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
6730: 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61  CAP_ATOMICnnn va
6740: 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61  lues.** mean tha
6750: 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63  t writes of bloc
6760: 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20  ks that are nnn 
6770: 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e  bytes in size an
6780: 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64  d.** are aligned
6790: 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77   to an address w
67a0: 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67  hich is an integ
67b0: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a  er multiple of.*
67c0: 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63  * nnn are atomic
67d0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
67e0: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
67f0: 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74  value means.** t
6800: 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73  hat when data is
6810: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66   appended to a f
6820: 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73  ile, the data is
6830: 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72   appended.** fir
6840: 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65  st then the size
6850: 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   of the file is 
6860: 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20  extended, never 
6870: 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79  the other.** way
6880: 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51   around.  The SQ
6890: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
68a0: 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d  NTIAL property m
68b0: 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66  eans that.** inf
68c0: 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74  ormation is writ
68d0: 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74  ten to disk in t
68e0: 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73  he same order as
68f0: 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72   calls.** to xWr
6900: 69 74 65 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 65  ite()..*/.typede
6910: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
6920: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69  _io_methods sqli
6930: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a  te3_io_methods;.
6940: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69  struct sqlite3_i
6950: 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e  o_methods {.  in
6960: 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e  t iVersion;.  in
6970: 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69  t (*xClose)(sqli
6980: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e  te3_file*);.  in
6990: 74 20 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74  t (*xRead)(sqlit
69a0: 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c  e3_file*, void*,
69b0: 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74   int iAmt, sqlit
69c0: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b  e3_int64 iOfst);
69d0: 0a 20 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29  .  int (*xWrite)
69e0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
69f0: 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
6a00: 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69   iAmt, sqlite3_i
6a10: 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69  nt64 iOfst);.  i
6a20: 6e 74 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28  nt (*xTruncate)(
6a30: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73  sqlite3_file*, s
6a40: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a  qlite3_int64 siz
6a50: 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e  e);.  int (*xSyn
6a60: 63 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  c)(sqlite3_file*
6a70: 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20  , int flags);.  
6a80: 69 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29  int (*xFileSize)
6a90: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
6aa0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70  sqlite3_int64 *p
6ab0: 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78  Size);.  int (*x
6ac0: 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69  Lock)(sqlite3_fi
6ad0: 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74  le*, int);.  int
6ae0: 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69   (*xUnlock)(sqli
6af0: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b  te3_file*, int);
6b00: 0a 20 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52  .  int (*xCheckR
6b10: 65 73 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c  eservedLock)(sql
6b20: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
6b30: 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74  *pResOut);.  int
6b40: 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29   (*xFileControl)
6b50: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
6b60: 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41  int op, void *pA
6b70: 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65  rg);.  int (*xSe
6b80: 63 74 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65  ctorSize)(sqlite
6b90: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  3_file*);.  int 
6ba0: 28 2a 78 44 65 76 69 63 65 43 68 61 72 61 63 74  (*xDeviceCharact
6bb0: 65 72 69 73 74 69 63 73 29 28 73 71 6c 69 74 65  eristics)(sqlite
6bc0: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 41  3_file*);.  /* A
6bd0: 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64  dditional method
6be0: 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69  s may be added i
6bf0: 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
6c00: 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43  s */.};../*.** C
6c10: 41 50 49 33 52 45 46 3a 20 53 74 61 6e 64 61 72  API3REF: Standar
6c20: 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f  d File Control O
6c30: 70 63 6f 64 65 73 20 7b 46 31 31 33 31 30 7d 0a  pcodes {F11310}.
6c40: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65  **.** These inte
6c50: 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ger constants ar
6c60: 65 20 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68  e opcodes for th
6c70: 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d  e xFileControl m
6c80: 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20  ethod.** of the 
6c90: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
6ca0: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20  ods] object and 
6cb0: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
6cc0: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a  file_control()].
6cd0: 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  ** interface..**
6ce0: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
6cf0: 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d  FCNTL_LOCKSTATE]
6d00: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
6d10: 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20  for debugging.  
6d20: 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63  This.** opcode c
6d30: 61 75 73 65 73 20 74 68 65 20 78 46 69 6c 65 43  auses the xFileC
6d40: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f  ontrol method to
6d50: 20 77 72 69 74 65 20 74 68 65 20 63 75 72 72 65   write the curre
6d60: 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74  nt state of.** t
6d70: 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20  he lock (one of 
6d80: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e  [SQLITE_LOCK_NON
6d90: 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  E], [SQLITE_LOCK
6da0: 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51  _SHARED],.** [SQ
6db0: 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56  LITE_LOCK_RESERV
6dc0: 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  ED], [SQLITE_LOC
6dd0: 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b  K_PENDING], or [
6de0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c  SQLITE_LOCK_EXCL
6df0: 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20  USIVE]).** into 
6e00: 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74 20  an integer that 
6e10: 74 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e  the pArg argumen
6e20: 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69  t points to. Thi
6e30: 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20  s capability.** 
6e40: 69 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 74  is used during t
6e50: 65 73 74 69 6e 67 20 61 6e 64 20 6f 6e 6c 79 20  esting and only 
6e60: 6e 65 65 64 73 20 74 6f 20 62 65 20 73 75 70 70  needs to be supp
6e70: 6f 72 74 65 64 20 77 68 65 6e 20 53 51 4c 49 54  orted when SQLIT
6e80: 45 5f 54 45 53 54 0a 2a 2a 20 69 73 20 64 65 66  E_TEST.** is def
6e90: 69 6e 65 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  ined..*/.#define
6ea0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f   SQLITE_FCNTL_LO
6eb0: 43 4b 53 54 41 54 45 20 20 20 20 20 20 20 20 31  CKSTATE        1
6ec0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
6ed0: 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 20 7b  : Mutex Handle {
6ee0: 46 31 37 31 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 68  F17110}.**.** Th
6ef0: 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77  e mutex module w
6f00: 69 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66  ithin SQLite def
6f10: 69 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75  ines [sqlite3_mu
6f20: 74 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a  tex] to be an.**
6f30: 20 61 62 73 74 72 61 63 74 20 74 79 70 65 20 66   abstract type f
6f40: 6f 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63  or a mutex objec
6f50: 74 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63  t.  The SQLite c
6f60: 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a  ore never looks.
6f70: 2a 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e  ** at the intern
6f80: 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  al representatio
6f90: 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33  n of an [sqlite3
6fa0: 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c  _mutex].  It onl
6fb0: 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20  y.** deals with 
6fc0: 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20  pointers to the 
6fd0: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20  [sqlite3_mutex] 
6fe0: 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75  object..**.** Mu
6ff0: 74 65 78 65 73 20 61 72 65 20 63 72 65 61 74 65  texes are create
7000: 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
7010: 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e  _mutex_alloc()].
7020: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
7030: 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ct sqlite3_mutex
7040: 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a   sqlite3_mutex;.
7050: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
7060: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 62   OS Interface Ob
7070: 6a 65 63 74 20 7b 46 31 31 31 34 30 7d 0a 2a 2a  ject {F11140}.**
7080: 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20  .** An instance 
7090: 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 64  of this object d
70a0: 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72  efines the inter
70b0: 66 61 63 65 20 62 65 74 77 65 65 6e 20 74 68 65  face between the
70c0: 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f 72 65 20  .** SQLite core 
70d0: 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69  and the underlyi
70e0: 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  ng operating sys
70f0: 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a  tem.  The "vfs".
7100: 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f  ** in the name o
7110: 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61  f the object sta
7120: 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c  nds for "virtual
7130: 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 0a 2a   file system"..*
7140: 2a 0a 2a 2a 20 54 68 65 20 69 56 65 72 73 69 6f  *.** The iVersio
7150: 6e 20 66 69 65 6c 64 20 69 73 20 69 6e 69 74 69  n field is initi
7160: 61 6c 6c 79 20 31 20 62 75 74 20 6d 61 79 20 62  ally 1 but may b
7170: 65 20 6c 61 72 67 65 72 20 66 6f 72 20 66 75 74  e larger for fut
7180: 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20  ure.** versions 
7190: 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 64 64 69  of SQLite.  Addi
71a0: 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61  tional fields ma
71b0: 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 74 6f  y be appended to
71c0: 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20   this.** object 
71d0: 77 68 65 6e 20 74 68 65 20 69 56 65 72 73 69 6f  when the iVersio
71e0: 6e 20 76 61 6c 75 65 20 69 73 20 69 6e 63 72 65  n value is incre
71f0: 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ased..**.** The 
7200: 73 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69  szOsFile field i
7210: 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  s the size of th
7220: 65 20 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71  e subclassed [sq
7230: 6c 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73  lite3_file].** s
7240: 74 72 75 63 74 75 72 65 20 75 73 65 64 20 62 79  tructure used by
7250: 20 74 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61   this VFS.  mxPa
7260: 74 68 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61  thname is the ma
7270: 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a  ximum length of.
7280: 2a 2a 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e  ** a pathname in
7290: 20 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a   this VFS..**.**
72a0: 20 52 65 67 69 73 74 65 72 65 64 20 73 71 6c 69   Registered sqli
72b0: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20  te3_vfs objects 
72c0: 61 72 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69  are kept on a li
72d0: 6e 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64  nked list formed
72e0: 20 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74   by.** the pNext
72f0: 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b   pointer.  The [
7300: 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69  sqlite3_vfs_regi
7310: 73 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b  ster()].** and [
7320: 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65  sqlite3_vfs_unre
7330: 67 69 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66  gister()] interf
7340: 61 63 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73  aces manage this
7350: 20 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68   list.** in a th
7360: 72 65 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20  read-safe way.  
7370: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  The [sqlite3_vfs
7380: 5f 66 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61  _find()] interfa
7390: 63 65 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74  ce.** searches t
73a0: 68 65 20 6c 69 73 74 2e 0a 2a 2a 0a 2a 2a 20 54  he list..**.** T
73b0: 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20 69  he pNext field i
73c0: 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64  s the only field
73d0: 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f   in the sqlite3_
73e0: 76 66 73 20 0a 2a 2a 20 73 74 72 75 63 74 75 72  vfs .** structur
73f0: 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69  e that SQLite wi
7400: 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20  ll ever modify. 
7410: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c   SQLite will onl
7420: 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d  y access.** or m
7430: 6f 64 69 66 79 20 74 68 69 73 20 66 69 65 6c 64  odify this field
7440: 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61   while holding a
7450: 20 70 61 72 74 69 63 75 6c 61 72 20 73 74 61 74   particular stat
7460: 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65  ic mutex..** The
7470: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
7480: 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79  uld never modify
7490: 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e   anything within
74a0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   the sqlite3_vfs
74b0: 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20  .** object once 
74c0: 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62  the object has b
74d0: 65 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a  een registered..
74e0: 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20  **.** The zName 
74f0: 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20  field holds the 
7500: 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20  name of the VFS 
7510: 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d  module.  The nam
7520: 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69  e must.** be uni
7530: 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56  que across all V
7540: 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a  FS modules..**.*
7550: 2a 20 7b 46 31 31 31 34 31 7d 20 53 51 4c 69 74  * {F11141} SQLit
7560: 65 20 77 69 6c 6c 20 67 75 61 72 61 6e 74 65 65  e will guarantee
7570: 20 74 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e   that the zFilen
7580: 61 6d 65 20 73 74 72 69 6e 67 20 70 61 73 73 65  ame string passe
7590: 64 20 74 6f 0a 2a 2a 20 78 4f 70 65 6e 28 29 20  d to.** xOpen() 
75a0: 69 73 20 61 20 66 75 6c 6c 20 70 61 74 68 6e 61  is a full pathna
75b0: 6d 65 20 61 73 20 67 65 6e 65 72 61 74 65 64 20  me as generated 
75c0: 62 79 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65  by xFullPathname
75d0: 28 29 20 61 6e 64 0a 2a 2a 20 74 68 61 74 20 74  () and.** that t
75e0: 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62  he string will b
75f0: 65 20 76 61 6c 69 64 20 61 6e 64 20 75 6e 63 68  e valid and unch
7600: 61 6e 67 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f  anged until xClo
7610: 73 65 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65  se() is.** calle
7620: 64 2e 20 20 7b 45 4e 44 7d 20 53 6f 20 74 68 65  d.  {END} So the
7630: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
7640: 63 61 6e 20 73 74 6f 72 65 20 61 20 70 6f 69 6e  can store a poin
7650: 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69  ter to the.** fi
7660: 6c 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65  lename if it nee
7670: 64 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74  ds to remember t
7680: 68 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20  he filename for 
7690: 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 0a  some reason..**.
76a0: 2a 2a 20 7b 46 31 31 31 34 32 7d 20 54 68 65 20  ** {F11142} The 
76b0: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
76c0: 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64  o xOpen() includ
76d0: 65 73 20 61 6c 6c 20 62 69 74 73 20 73 65 74 20  es all bits set 
76e0: 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 67 73 20  in.** the flags 
76f0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c  argument to [sql
7700: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e  ite3_open_v2()].
7710: 20 20 4f 72 20 69 66 20 5b 73 71 6c 69 74 65 33    Or if [sqlite3
7720: 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b  _open()].** or [
7730: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
7740: 5d 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20  ] is used, then 
7750: 66 6c 61 67 73 20 69 6e 63 6c 75 64 65 73 20 61  flags includes a
7760: 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49  t least.** [SQLI
7770: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
7780: 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45  E] | [SQLITE_OPE
7790: 4e 5f 43 52 45 41 54 45 5d 2e 20 7b 45 4e 44 7d  N_CREATE]. {END}
77a0: 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 6f  .** If xOpen() o
77b0: 70 65 6e 73 20 61 20 66 69 6c 65 20 72 65 61 64  pens a file read
77c0: 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 65  -only then it se
77d0: 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f  ts *pOutFlags to
77e0: 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c  .** include [SQL
77f0: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
7800: 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 74 73 20  Y].  Other bits 
7810: 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61  in *pOutFlags ma
7820: 79 20 62 65 0a 2a 2a 20 73 65 74 2e 0a 2a 2a 20  y be.** set..** 
7830: 0a 2a 2a 20 7b 46 31 31 31 34 33 7d 20 53 51 4c  .** {F11143} SQL
7840: 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64  ite will also ad
7850: 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c  d one of the fol
7860: 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20  lowing flags to 
7870: 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63  the xOpen().** c
7880: 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f  all, depending o
7890: 6e 20 74 68 65 20 6f 62 6a 65 63 74 20 62 65 69  n the object bei
78a0: 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a 20 0a 2a  ng opened:.** .*
78b0: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20  * <ul>.** <li>  
78c0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49  [SQLITE_OPEN_MAI
78d0: 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  N_DB].** <li>  [
78e0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e  SQLITE_OPEN_MAIN
78f0: 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69  _JOURNAL].** <li
7900: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
7910: 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e  TEMP_DB].** <li>
7920: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54    [SQLITE_OPEN_T
7930: 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  EMP_JOURNAL].** 
7940: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
7950: 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 5d  EN_TRANSIENT_DB]
7960: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
7970: 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41  E_OPEN_SUBJOURNA
7980: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
7990: 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f  ITE_OPEN_MASTER_
79a0: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c  JOURNAL].** </ul
79b0: 3e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68  > {END}.**.** Th
79c0: 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65  e file I/O imple
79d0: 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73  mentation can us
79e0: 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70  e the object typ
79f0: 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68  e flags to.** ch
7a00: 61 6e 67 65 73 20 74 68 65 20 77 61 79 20 69 74  anges the way it
7a10: 20 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c 65   deals with file
7a20: 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  s.  For example,
7a30: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a   an application.
7a40: 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74  ** that does not
7a50: 20 63 61 72 65 20 61 62 6f 75 74 20 63 72 61 73   care about cras
7a60: 68 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72 6f  h recovery or ro
7a70: 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b  llback might mak
7a80: 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66  e.** the open of
7a90: 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20   a journal file 
7aa0: 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73  a no-op.  Writes
7ab0: 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c   to this journal
7ac0: 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62   would.** also b
7ad0: 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e  e no-ops, and an
7ae0: 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61  y attempt to rea
7af0: 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f  d the journal wo
7b00: 75 6c 64 20 72 65 74 75 72 6e 20 0a 2a 2a 20 53  uld return .** S
7b10: 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72  QLITE_IOERR.  Or
7b20: 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
7b30: 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e  ion might recogn
7b40: 69 7a 65 20 74 68 61 74 20 61 20 64 61 74 61 62  ize that a datab
7b50: 61 73 65 20 0a 2a 2a 20 66 69 6c 65 20 77 69 6c  ase .** file wil
7b60: 6c 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d  l be doing page-
7b70: 61 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72  aligned sector r
7b80: 65 61 64 73 20 61 6e 64 20 77 72 69 74 65 73 20  eads and writes 
7b90: 69 6e 20 61 20 72 61 6e 64 6f 6d 20 0a 2a 2a 20  in a random .** 
7ba0: 6f 72 64 65 72 20 61 6e 64 20 73 65 74 20 75 70  order and set up
7bb0: 20 69 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74   its I/O subsyst
7bc0: 65 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a  em accordingly..
7bd0: 2a 2a 20 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69  ** .** SQLite mi
7be0: 67 68 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65  ght also add one
7bf0: 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   of the followin
7c00: 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78  g flags to the x
7c10: 4f 70 65 6e 0a 2a 2a 20 6d 65 74 68 6f 64 3a 0a  Open.** method:.
7c20: 2a 2a 20 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  ** .** <ul>.** <
7c30: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  li> [SQLITE_OPEN
7c40: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a  _DELETEONCLOSE].
7c50: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
7c60: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a  OPEN_EXCLUSIVE].
7c70: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 0a 2a 2a 20  ** </ul>.** .** 
7c80: 7b 46 31 31 31 34 35 7d 20 54 68 65 20 5b 53 51  {F11145} The [SQ
7c90: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
7ca0: 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65  ONCLOSE] flag me
7cb0: 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f  ans the file sho
7cc0: 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65  uld be.** delete
7cd0: 64 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f  d when it is clo
7ce0: 73 65 64 2e 20 20 7b 46 31 31 31 34 36 7d 20 54  sed.  {F11146} T
7cf0: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
7d00: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a  DELETEONCLOSE].*
7d10: 2a 20 77 69 6c 6c 20 62 65 20 73 65 74 20 66 6f  * will be set fo
7d20: 72 20 54 45 4d 50 20 20 64 61 74 61 62 61 73 65  r TEMP  database
7d30: 73 2c 20 6a 6f 75 72 6e 61 6c 73 20 61 6e 64 20  s, journals and 
7d40: 66 6f 72 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e  for subjournals.
7d50: 20 0a 2a 2a 20 7b 46 31 31 31 34 37 7d 20 54 68   .** {F11147} Th
7d60: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45  e [SQLITE_OPEN_E
7d70: 58 43 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 6d  XCLUSIVE] flag m
7d80: 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68  eans the file sh
7d90: 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 64 0a 2a  ould be opened.*
7da0: 2a 20 66 6f 72 20 65 78 63 6c 75 73 69 76 65 20  * for exclusive 
7db0: 61 63 63 65 73 73 2e 20 20 54 68 69 73 20 66 6c  access.  This fl
7dc0: 61 67 20 69 73 20 73 65 74 20 66 6f 72 20 61 6c  ag is set for al
7dd0: 6c 20 66 69 6c 65 73 20 65 78 63 65 70 74 0a 2a  l files except.*
7de0: 2a 20 66 6f 72 20 74 68 65 20 6d 61 69 6e 20 64  * for the main d
7df0: 61 74 61 62 61 73 65 20 66 69 6c 65 2e 20 7b 45  atabase file. {E
7e00: 4e 44 7d 0a 2a 2a 20 0a 2a 2a 20 7b 46 31 31 31  ND}.** .** {F111
7e10: 34 38 7d 20 41 74 20 6c 65 61 73 74 20 73 7a 4f  48} At least szO
7e20: 73 46 69 6c 65 20 62 79 74 65 73 20 6f 66 20 6d  sFile bytes of m
7e30: 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63 61  emory are alloca
7e40: 74 65 64 20 62 79 20 53 51 4c 69 74 65 20 0a 2a  ted by SQLite .*
7e50: 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b  * to hold the  [
7e60: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73 74  sqlite3_file] st
7e70: 72 75 63 74 75 72 65 20 70 61 73 73 65 64 20 61  ructure passed a
7e80: 73 20 74 68 65 20 74 68 69 72 64 20 0a 2a 2a 20  s the third .** 
7e90: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65  argument to xOpe
7ea0: 6e 2e 20 20 7b 45 4e 44 7d 20 20 54 68 65 20 78  n.  {END}  The x
7eb0: 4f 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73  Open method does
7ec0: 20 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20   not have to.** 
7ed0: 61 6c 6c 6f 63 61 74 65 20 74 68 65 20 73 74 72  allocate the str
7ee0: 75 63 74 75 72 65 3b 20 69 74 20 73 68 6f 75 6c  ucture; it shoul
7ef0: 64 20 6a 75 73 74 20 66 69 6c 6c 20 69 74 20 69  d just fill it i
7f00: 6e 2e 0a 2a 2a 20 0a 2a 2a 20 7b 46 31 31 31 34  n..** .** {F1114
7f10: 39 7d 20 54 68 65 20 66 6c 61 67 73 20 61 72 67  9} The flags arg
7f20: 75 6d 65 6e 74 20 74 6f 20 78 41 63 63 65 73 73  ument to xAccess
7f30: 28 29 20 6d 61 79 20 62 65 20 5b 53 51 4c 49 54  () may be [SQLIT
7f40: 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 5d  E_ACCESS_EXISTS]
7f50: 20 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f 72   .** to test for
7f60: 20 74 68 65 20 65 78 69 73 74 65 6e 63 65 20 6f   the existence o
7f70: 66 20 61 20 66 69 6c 65 2c 0a 2a 2a 20 6f 72 20  f a file,.** or 
7f80: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52  [SQLITE_ACCESS_R
7f90: 45 41 44 57 52 49 54 45 5d 20 74 6f 20 74 65 73  EADWRITE] to tes
7fa0: 74 20 74 6f 20 73 65 65 0a 2a 2a 20 69 66 20 61  t to see.** if a
7fb0: 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c   file is readabl
7fc0: 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20  e and writable, 
7fd0: 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53  or [SQLITE_ACCES
7fe0: 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65  S_READ].** to te
7ff0: 73 74 20 74 6f 20 73 65 65 20 69 66 20 61 20 66  st to see if a f
8000: 69 6c 65 20 69 73 20 61 74 20 6c 65 61 73 74 20  ile is at least 
8010: 72 65 61 64 61 62 6c 65 2e 20 20 7b 45 4e 44 7d  readable.  {END}
8020: 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65   The file can be
8030: 20 61 20 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79   a .** directory
8040: 2e 0a 2a 2a 20 0a 2a 2a 20 7b 46 31 31 31 35 30  ..** .** {F11150
8050: 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c  } SQLite will al
8060: 77 61 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 74  ways allocate at
8070: 20 6c 65 61 73 74 20 6d 78 50 61 74 68 6e 61 6d   least mxPathnam
8080: 65 2b 31 20 62 79 74 65 73 20 66 6f 72 0a 2a 2a  e+1 bytes for.**
8090: 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66   the output buff
80a0: 65 72 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65  er xFullPathname
80b0: 2e 20 7b 46 31 31 31 35 31 7d 20 54 68 65 20 65  . {F11151} The e
80c0: 78 61 63 74 0a 2a 2a 20 73 69 7a 65 20 6f 66 20  xact.** size of 
80d0: 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 65  the output buffe
80e0: 72 20 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64  r is also passed
80f0: 20 61 73 20 61 20 70 61 72 61 6d 65 74 65 72 20   as a parameter 
8100: 74 6f 20 62 6f 74 68 20 0a 2a 2a 20 6d 65 74 68  to both .** meth
8110: 6f 64 73 2e 20 7b 45 4e 44 7d 20 49 66 20 74 68  ods. {END} If th
8120: 65 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 20  e output buffer 
8130: 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f  is not large eno
8140: 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e  ugh, [SQLITE_CAN
8150: 54 4f 50 45 4e 5d 0a 2a 2a 20 73 68 6f 75 6c 64  TOPEN].** should
8160: 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 41 73   be returned. As
8170: 20 74 68 69 73 20 69 73 20 68 61 6e 64 6c 65 64   this is handled
8180: 20 61 73 20 61 20 66 61 74 61 6c 20 65 72 72 6f   as a fatal erro
8190: 72 20 62 79 20 53 51 4c 69 74 65 2c 0a 2a 2a 20  r by SQLite,.** 
81a0: 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  vfs implementati
81b0: 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61  ons should endea
81c0: 76 6f 72 20 74 6f 20 70 72 65 76 65 6e 74 20 74  vor to prevent t
81d0: 68 69 73 20 62 79 20 73 65 74 74 69 6e 67 20 0a  his by setting .
81e0: 2a 2a 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f  ** mxPathname to
81f0: 20 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20   a sufficiently 
8200: 6c 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 20  large value..** 
8210: 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e  .** The xRandomn
8220: 65 73 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c  ess(), xSleep(),
8230: 20 61 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d   and xCurrentTim
8240: 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  e() interfaces.*
8250: 2a 20 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74  * are not strict
8260: 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74 68 65  ly a part of the
8270: 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 74   filesystem, but
8280: 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63   they are.** inc
8290: 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56 46 53  luded in the VFS
82a0: 20 73 74 72 75 63 74 75 72 65 20 66 6f 72 20 63   structure for c
82b0: 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20  ompleteness..** 
82c0: 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28  The xRandomness(
82d0: 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d  ) function attem
82e0: 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20 6e 42  pts to return nB
82f0: 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66  ytes bytes.** of
8300: 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 61   good-quality ra
8310: 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f  ndomness into zO
8320: 75 74 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20  ut.  The return 
8330: 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 20  value is.** the 
8340: 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66  actual number of
8350: 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d   bytes of random
8360: 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 2e 20 20  ness obtained.  
8370: 54 68 65 0a 2a 2a 20 78 53 6c 65 65 70 28 29 20  The.** xSleep() 
8380: 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20 74 68  method causes th
8390: 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 64  e calling thread
83a0: 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61 74   to sleep for at
83b0: 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e 75  .** least the nu
83c0: 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65 63  mber of microsec
83d0: 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 54 68 65  onds given.  The
83e0: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 0a   xCurrentTime().
83f0: 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e  ** method return
8400: 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e  s a Julian Day N
8410: 75 6d 62 65 72 20 66 6f 72 20 74 68 65 20 63 75  umber for the cu
8420: 72 72 65 6e 74 20 64 61 74 65 20 61 6e 64 0a 2a  rrent date and.*
8430: 2a 20 74 69 6d 65 2e 0a 2a 2f 0a 74 79 70 65 64  * time..*/.typed
8440: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
8450: 33 5f 76 66 73 20 73 71 6c 69 74 65 33 5f 76 66  3_vfs sqlite3_vf
8460: 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  s;.struct sqlite
8470: 33 5f 76 66 73 20 7b 0a 20 20 69 6e 74 20 69 56  3_vfs {.  int iV
8480: 65 72 73 69 6f 6e 3b 20 20 20 20 20 20 20 20 20  ersion;         
8490: 20 20 20 2f 2a 20 53 74 72 75 63 74 75 72 65 20     /* Structure 
84a0: 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 2a  version number *
84b0: 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69 6c 65  /.  int szOsFile
84c0: 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ;            /* 
84d0: 53 69 7a 65 20 6f 66 20 73 75 62 63 6c 61 73 73  Size of subclass
84e0: 65 64 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20  ed sqlite3_file 
84f0: 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74 68 6e  */.  int mxPathn
8500: 61 6d 65 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  ame;          /*
8510: 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20 70 61   Maximum file pa
8520: 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20 2a 2f  thname length */
8530: 0a 20 20 73 71 6c 69 74 65 33 5f 76 66 73 20 2a  .  sqlite3_vfs *
8540: 70 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a 20 4e  pNext;      /* N
8550: 65 78 74 20 72 65 67 69 73 74 65 72 65 64 20 56  ext registered V
8560: 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  FS */.  const ch
8570: 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20 20 20  ar *zName;      
8580: 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 69 73   /* Name of this
8590: 20 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79   virtual file sy
85a0: 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  stem */.  void *
85b0: 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20  pAppData;       
85c0: 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20 74 6f     /* Pointer to
85d0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 70 65   application-spe
85e0: 63 69 66 69 63 20 64 61 74 61 20 2a 2f 0a 20 20  cific data */.  
85f0: 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c  int (*xOpen)(sql
8600: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
8610: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71   char *zName, sq
8620: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20 20 20  lite3_file*,.   
8630: 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20              int 
8640: 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f 75 74  flags, int *pOut
8650: 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a  Flags);.  int (*
8660: 78 44 65 6c 65 74 65 29 28 73 71 6c 69 74 65 33  xDelete)(sqlite3
8670: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
8680: 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 73 79  r *zName, int sy
8690: 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74 20 28 2a  ncDir);.  int (*
86a0: 78 41 63 63 65 73 73 29 28 73 71 6c 69 74 65 33  xAccess)(sqlite3
86b0: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
86c0: 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 66 6c  r *zName, int fl
86d0: 61 67 73 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75  ags, int *pResOu
86e0: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 75 6c  t);.  int (*xFul
86f0: 6c 50 61 74 68 6e 61 6d 65 29 28 73 71 6c 69 74  lPathname)(sqlit
8700: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
8710: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20  har *zName, int 
8720: 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f 75 74  nOut, char *zOut
8730: 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c  );.  void *(*xDl
8740: 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66  Open)(sqlite3_vf
8750: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
8760: 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20 76 6f  zFilename);.  vo
8770: 69 64 20 28 2a 78 44 6c 45 72 72 6f 72 29 28 73  id (*xDlError)(s
8780: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74  qlite3_vfs*, int
8790: 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 45   nByte, char *zE
87a0: 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64 20 2a  rrMsg);.  void *
87b0: 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c 69 74 65  (*xDlSym)(sqlite
87c0: 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f  3_vfs*,void*, co
87d0: 6e 73 74 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f  nst char *zSymbo
87e0: 6c 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c  l);.  void (*xDl
87f0: 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76  Close)(sqlite3_v
8800: 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69  fs*, void*);.  i
8810: 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73  nt (*xRandomness
8820: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
8830: 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20  int nByte, char 
8840: 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a  *zOut);.  int (*
8850: 78 53 6c 65 65 70 29 28 73 71 6c 69 74 65 33 5f  xSleep)(sqlite3_
8860: 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73  vfs*, int micros
8870: 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28  econds);.  int (
8880: 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 29 28 73  *xCurrentTime)(s
8890: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75  qlite3_vfs*, dou
88a0: 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  ble*);.  int (*x
88b0: 47 65 74 4c 61 73 74 45 72 72 6f 72 29 28 73 71  GetLastError)(sq
88c0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c  lite3_vfs*, int,
88d0: 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 20 4e   char *);.  /* N
88e0: 65 77 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65  ew fields may be
88f0: 20 61 70 70 65 6e 64 65 64 20 69 6e 20 66 69 67   appended in fig
8900: 75 72 65 20 76 65 72 73 69 6f 6e 73 2e 20 20 54  ure versions.  T
8910: 68 65 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a  he iVersion.  **
8920: 20 76 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72   value will incr
8930: 65 6d 65 6e 74 20 77 68 65 6e 65 76 65 72 20 74  ement whenever t
8940: 68 69 73 20 68 61 70 70 65 6e 73 2e 20 2a 2f 0a  his happens. */.
8950: 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
8960: 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68  EF: Flags for th
8970: 65 20 78 41 63 63 65 73 73 20 56 46 53 20 6d 65  e xAccess VFS me
8980: 74 68 6f 64 20 7b 46 31 31 31 39 30 7d 0a 2a 2a  thod {F11190}.**
8990: 0a 2a 2a 20 7b 46 31 31 31 39 31 7d 20 54 68 65  .** {F11191} The
89a0: 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74  se integer const
89b0: 61 6e 74 73 20 63 61 6e 20 62 65 20 75 73 65 64  ants can be used
89c0: 20 61 73 20 74 68 65 20 74 68 69 72 64 20 70 61   as the third pa
89d0: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68  rameter to.** th
89e0: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
89f0: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   of an [sqlite3_
8a00: 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20 7b 45 4e  vfs] object. {EN
8a10: 44 7d 20 20 54 68 65 79 20 64 65 74 65 72 6d 69  D}  They determi
8a20: 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20  ne.** what kind 
8a30: 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74  of permissions t
8a40: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
8a50: 64 20 69 73 0a 2a 2a 20 6c 6f 6f 6b 69 6e 67 20  d is.** looking 
8a60: 66 6f 72 2e 20 20 7b 46 31 31 31 39 32 7d 20 57  for.  {F11192} W
8a70: 69 74 68 20 5b 53 51 4c 49 54 45 5f 41 43 43 45  ith [SQLITE_ACCE
8a80: 53 53 5f 45 58 49 53 54 53 5d 2c 20 74 68 65 20  SS_EXISTS], the 
8a90: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a  xAccess method.*
8aa0: 2a 20 73 69 6d 70 6c 79 20 63 68 65 63 6b 73 20  * simply checks 
8ab0: 74 6f 20 73 65 65 20 69 66 20 74 68 65 20 66 69  to see if the fi
8ac0: 6c 65 20 65 78 69 73 74 73 2e 20 7b 46 31 31 31  le exists. {F111
8ad0: 39 33 7d 20 57 69 74 68 0a 2a 2a 20 53 51 4c 49  93} With.** SQLI
8ae0: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52  TE_ACCESS_READWR
8af0: 49 54 45 2c 20 74 68 65 20 78 41 63 63 65 73 73  ITE, the xAccess
8b00: 20 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20 74   method checks t
8b10: 6f 20 73 65 65 0a 2a 2a 20 69 66 20 74 68 65 20  o see.** if the 
8b20: 66 69 6c 65 20 69 73 20 62 6f 74 68 20 72 65 61  file is both rea
8b30: 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62  dable and writab
8b40: 6c 65 2e 20 20 7b 46 31 31 31 39 34 7d 20 57 69  le.  {F11194} Wi
8b50: 74 68 0a 2a 2a 20 53 51 4c 49 54 45 5f 41 43 43  th.** SQLITE_ACC
8b60: 45 53 53 5f 52 45 41 44 20 74 68 65 20 78 41 63  ESS_READ the xAc
8b70: 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63  cess method.** c
8b80: 68 65 63 6b 73 20 74 6f 20 73 65 65 20 69 66 20  hecks to see if 
8b90: 74 68 65 20 66 69 6c 65 20 69 73 20 72 65 61 64  the file is read
8ba0: 61 62 6c 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  able..*/.#define
8bb0: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45   SQLITE_ACCESS_E
8bc0: 58 49 53 54 53 20 20 20 20 30 0a 23 64 65 66 69  XISTS    0.#defi
8bd0: 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  ne SQLITE_ACCESS
8be0: 5f 52 45 41 44 57 52 49 54 45 20 31 0a 23 64 65  _READWRITE 1.#de
8bf0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45  fine SQLITE_ACCE
8c00: 53 53 5f 52 45 41 44 20 20 20 20 20 20 32 0a 0a  SS_READ      2..
8c10: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
8c20: 49 6e 69 74 69 61 6c 69 7a 65 20 54 68 65 20 53  Initialize The S
8c30: 51 4c 69 74 65 20 4c 69 62 72 61 72 79 20 7b 46  QLite Library {F
8c40: 31 30 31 33 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  10130}.**.** The
8c50: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
8c60: 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 6e  ize() routine in
8c70: 69 74 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a  itializes the.**
8c80: 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20   SQLite library 
8c90: 70 72 69 6f 72 20 74 6f 20 75 73 65 2e 20 20 54  prior to use.  T
8ca0: 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  he sqlite3_shutd
8cb0: 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a  own() routine.**
8cc0: 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79   deallocates any
8cd0: 20 72 65 73 6f 75 72 63 65 73 20 74 68 61 74 20   resources that 
8ce0: 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62  were allocated b
8cf0: 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  y sqlite3_initia
8d00: 6c 69 7a 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 20  lize()..**.** A 
8d10: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
8d20: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
8d30: 61 6e 20 22 65 66 66 65 63 74 69 76 65 22 20 63  an "effective" c
8d40: 61 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a 20  all if it is.** 
8d50: 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73  the first time s
8d60: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
8d70: 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 64  e() is invoked d
8d80: 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74 69  uring the lifeti
8d90: 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f  me of.** the pro
8da0: 63 65 73 73 2c 20 6f 72 20 69 66 20 69 74 20 69  cess, or if it i
8db0: 73 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65  s the first time
8dc0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
8dd0: 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ize() is invoked
8de0: 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20  .** following a 
8df0: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
8e00: 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 4f 6e 6c  shutdown().  Onl
8e10: 79 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63  y an effective c
8e20: 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65  all.** of sqlite
8e30: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64  3_initialize() d
8e40: 6f 65 73 20 61 6e 79 20 69 6e 69 74 69 61 6c 69  oes any initiali
8e50: 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68  zation.  All oth
8e60: 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20  er calls.** are 
8e70: 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e  harmless no-ops.
8e80: 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73    In other words
8e90: 2c 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33  ,.** the sqlite3
8ea0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f  _initialize() ro
8eb0: 75 74 69 6e 65 20 6d 61 79 20 62 65 20 63 61 6c  utine may be cal
8ec0: 6c 65 64 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d  led multiple tim
8ed0: 65 73 0a 2a 2a 20 77 69 74 68 6f 75 74 20 63 6f  es.** without co
8ee0: 6e 73 65 71 75 65 6e 63 65 2e 20 20 53 65 63 6f  nsequence.  Seco
8ef0: 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e  nd and subsequen
8f00: 74 20 65 76 61 6c 75 61 74 69 6f 6e 73 20 6f 66  t evaluations of
8f10: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  .** sqlite3_init
8f20: 69 61 6c 69 7a 65 28 29 20 61 72 65 20 6e 6f 2d  ialize() are no-
8f30: 6f 70 73 2e 20 20 54 68 65 20 73 71 6c 69 74 65  ops.  The sqlite
8f40: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72  3_initialize() r
8f50: 6f 75 74 69 6e 65 0a 2a 2a 20 6f 6e 6c 79 20 77  outine.** only w
8f60: 6f 72 6b 73 20 74 68 65 20 66 69 72 73 74 20 74  orks the first t
8f70: 69 6d 65 20 69 74 20 69 73 20 63 61 6c 6c 65 64  ime it is called
8f80: 20 66 6f 72 20 61 20 70 72 6f 63 65 73 73 2c 20   for a process, 
8f90: 6f 72 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20  or the first.** 
8fa0: 74 69 6d 65 20 69 74 20 69 73 20 63 61 6c 6c 65  time it is calle
8fb0: 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f  d after sqlite3_
8fc0: 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 49 6e 20  shutdown().  In 
8fd0: 61 6c 6c 20 6f 74 68 65 72 20 63 61 73 65 73 2c  all other cases,
8fe0: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  .** sqlite3_init
8ff0: 69 61 6c 69 7a 65 28 29 20 72 65 74 75 72 6e 73  ialize() returns
9000: 20 53 51 4c 49 54 45 5f 4f 4b 20 77 69 74 68 6f   SQLITE_OK witho
9010: 75 74 20 64 6f 69 6e 67 20 61 6e 79 20 72 65 61  ut doing any rea
9020: 6c 20 77 6f 72 6b 2e 0a 2a 2a 0a 2a 2a 20 41 6d  l work..**.** Am
9030: 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e 67 73  ong other things
9040: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  , sqlite3_initia
9050: 6c 69 7a 65 28 29 20 73 68 61 6c 6c 20 69 6e 76  lize() shall inv
9060: 6f 6b 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  oke.** [sqlite3_
9070: 6d 75 74 65 78 5f 69 6e 69 74 28 29 5d 20 61 6e  mutex_init()] an
9080: 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  d sqlite3_os_ini
9090: 74 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c  t().  Similarly,
90a0: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
90b0: 6e 28 29 0a 2a 2a 20 73 68 61 6c 6c 20 69 6e 76  n().** shall inv
90c0: 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  oke [sqlite3_mut
90d0: 65 78 5f 65 6e 64 28 29 5d 20 61 6e 64 20 73 71  ex_end()] and sq
90e0: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a  lite3_os_end()..
90f0: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
9100: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72  3_initialize() r
9110: 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 53  outine returns S
9120: 51 4c 49 54 45 5f 4f 4b 20 6f 6e 20 73 75 63 63  QLITE_OK on succ
9130: 65 73 73 2e 0a 2a 2a 20 49 66 20 66 6f 72 20 73  ess..** If for s
9140: 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69  ome reason, sqli
9150: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
9160: 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e   is unable to in
9170: 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20  itialize.** the 
9180: 6c 69 62 72 61 72 79 20 28 70 65 72 68 61 70 73  library (perhaps
9190: 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f   it is unable to
91a0: 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65 64   allocate a need
91b0: 65 64 20 72 65 73 6f 75 72 63 65 20 73 75 63 68  ed resource such
91c0: 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 29 20  .** as a mutex) 
91d0: 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20 5b 65  it returns an [e
91e0: 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65 72  rror code] other
91f0: 20 74 68 61 6e 20 53 51 4c 49 54 45 5f 4f 4b 2e   than SQLITE_OK.
9200: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
9210: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
9220: 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65  routine is calle
9230: 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20  d internally by 
9240: 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51  many other.** SQ
9250: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20  Lite interfaces 
9260: 73 6f 20 74 68 61 74 20 61 6e 20 61 70 70 6c 69  so that an appli
9270: 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64  cation usually d
9280: 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a  oes not need to.
9290: 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  ** invoke sqlite
92a0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64  3_initialize() d
92b0: 69 72 65 63 74 6c 79 2e 20 20 46 6f 72 20 65 78  irectly.  For ex
92c0: 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f  ample, [sqlite3_
92d0: 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73  open()].** calls
92e0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
92f0: 69 7a 65 28 29 20 73 6f 20 74 68 65 20 53 51 4c  ize() so the SQL
9300: 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c  ite library will
9310: 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   be automaticall
9320: 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64  y.** initialized
9330: 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f   when [sqlite3_o
9340: 70 65 6e 28 29 5d 20 69 73 20 63 61 6c 6c 65 64  pen()] is called
9350: 20 69 66 20 69 74 20 68 61 73 20 6e 6f 74 20 62   if it has not b
9360: 65 20 69 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a  e initialized.**
9370: 20 61 6c 72 65 61 64 79 2e 20 20 48 6f 77 65 76   already.  Howev
9380: 65 72 2c 20 69 66 20 53 51 4c 69 74 65 20 69 73  er, if SQLite is
9390: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74   compiled with t
93a0: 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41  he SQLITE_OMIT_A
93b0: 55 54 4f 49 4e 49 54 0a 2a 2a 20 63 6f 6d 70 69  UTOINIT.** compi
93c0: 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20  le-time option, 
93d0: 74 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61 74  then the automat
93e0: 69 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ic calls to sqli
93f0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
9400: 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64 20  .** are omitted 
9410: 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74  and the applicat
9420: 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73 71  ion must call sq
9430: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
9440: 28 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70  () directly.** p
9450: 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e  rior to using an
9460: 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  y other SQLite i
9470: 6e 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20 6d  nterface.  For m
9480: 61 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69  aximum portabili
9490: 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65 63  ty,.** it is rec
94a0: 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70  ommended that ap
94b0: 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61 79  plications alway
94c0: 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  s invoke sqlite3
94d0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a  _initialize().**
94e0: 20 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72 20   directly prior 
94f0: 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68  to using any oth
9500: 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
9510: 61 63 65 2e 20 20 46 75 74 75 72 65 20 72 65 6c  ace.  Future rel
9520: 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69  eases.** of SQLi
9530: 74 65 20 6d 61 79 20 72 65 71 75 69 72 65 20 74  te may require t
9540: 68 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 77  his.  In other w
9550: 6f 72 64 73 2c 20 74 68 65 20 62 65 68 61 76 69  ords, the behavi
9560: 6f 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a 20  or exhibited.** 
9570: 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63  when SQLite is c
9580: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 53 51 4c  ompiled with SQL
9590: 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49  ITE_OMIT_AUTOINI
95a0: 54 20 6d 69 67 68 74 20 62 65 63 6f 6d 65 20 74  T might become t
95b0: 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20 62 65  he.** default be
95c0: 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66  havior in some f
95d0: 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66  uture release of
95e0: 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54   SQLite..**.** T
95f0: 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  he sqlite3_os_in
9600: 69 74 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65  it() routine doe
9610: 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74  s operating-syst
9620: 65 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 69  em specific.** i
9630: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66  nitialization of
9640: 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
9650: 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69 74 65  ary.  The sqlite
9660: 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f  3_os_end().** ro
9670: 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74 68 65  utine undoes the
9680: 20 65 66 66 65 63 74 20 6f 66 20 73 71 6c 69 74   effect of sqlit
9690: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54  e3_os_init().  T
96a0: 79 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20  ypical tasks.** 
96b0: 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74 68 65  performed by the
96c0: 73 65 20 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c  se routines incl
96d0: 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f  ude allocation o
96e0: 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  r deallocation.*
96f0: 2a 20 6f 66 20 73 74 61 74 69 63 20 72 65 73 6f  * of static reso
9700: 75 72 63 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a  urces, initializ
9710: 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20  ation of global 
9720: 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65  variables,.** se
9730: 74 74 69 6e 67 20 75 70 20 61 20 64 65 66 61 75  tting up a defau
9740: 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
9750: 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65 74 74   module, or sett
9760: 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65 66 61  ing up.** a defa
9770: 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ult configuratio
9780: 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  n using [sqlite3
9790: 5f 63 6f 6e 66 69 67 28 29 5d 2e 20 20 0a 2a 2a  _config()].  .**
97a0: 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
97b0: 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72  ion should never
97c0: 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 73   invoke either s
97d0: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
97e0: 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  .** or sqlite3_o
97f0: 73 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c 79  s_end() directly
9800: 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  .  The applicati
9810: 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69  on should only i
9820: 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33  nvoke.** sqlite3
9830: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e  _initialize() an
9840: 64 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  d sqlite3_shutdo
9850: 77 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69 74  wn().  The sqlit
9860: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20  e3_os_init().** 
9870: 69 6e 74 65 72 66 61 63 65 20 69 73 20 63 61 6c  interface is cal
9880: 6c 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  led automaticall
9890: 79 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69  y by sqlite3_ini
98a0: 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 20 0a 2a  tialize() and .*
98b0: 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  * sqlite3_os_end
98c0: 28 29 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20  () is called by 
98d0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
98e0: 28 29 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65  ().  Appropriate
98f0: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
9900: 6f 6e 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  ons for sqlite3_
9910: 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71  os_init() and sq
9920: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a  lite3_os_end().*
9930: 2a 20 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f  * are built into
9940: 20 53 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20   SQLite when it 
9950: 69 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20  is compiled for 
9960: 75 6e 69 78 2c 20 77 69 6e 64 6f 77 73 2c 20 6f  unix, windows, o
9970: 72 20 6f 73 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20  r os/2..** When 
9980: 62 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 20  built for other 
9990: 70 6c 61 74 66 6f 72 6d 73 20 28 75 73 69 6e 67  platforms (using
99a0: 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 53 5f 4f   the SQLITE_OS_O
99b0: 54 48 45 52 3d 31 20 63 6f 6d 70 69 6c 65 2d 74  THER=1 compile-t
99c0: 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74  ime.** option) t
99d0: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
99e0: 75 73 74 20 73 75 70 70 6c 79 20 61 20 73 75 69  ust supply a sui
99f0: 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  table implementa
9a00: 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69  tion for.** sqli
9a10: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e  te3_os_init() an
9a20: 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  d sqlite3_os_end
9a30: 28 29 2e 20 20 41 6e 20 61 70 70 6c 69 63 61 74  ().  An applicat
9a40: 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20  ion-supplied.** 
9a50: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
9a60: 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  f sqlite3_os_ini
9a70: 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  t() or sqlite3_o
9a80: 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20  s_end().** must 
9a90: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b  return SQLITE_OK
9aa0: 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20   on success and 
9ab0: 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f  some other [erro
9ac0: 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20  r code] upon.** 
9ad0: 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20  failure..*/.int 
9ae0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
9af0: 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71  ze(void);.int sq
9b00: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 76  lite3_shutdown(v
9b10: 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  oid);.int sqlite
9b20: 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b  3_os_init(void);
9b30: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f  .int sqlite3_os_
9b40: 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a  end(void);../*.*
9b50: 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66  * CAPI3REF: Conf
9b60: 69 67 75 72 69 6e 67 20 54 68 65 20 53 51 4c 69  iguring The SQLi
9b70: 74 65 20 4c 69 62 72 61 72 79 20 7b 46 31 30 31  te Library {F101
9b80: 34 35 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  45}.**.** The sq
9b90: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
9ba0: 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64  nterface is used
9bb0: 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20   to make global 
9bc0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a  configuration.**
9bd0: 20 63 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69   changes to SQLi
9be0: 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74  te in order to t
9bf0: 75 6e 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68  une SQLite to th
9c00: 65 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 73  e specific needs
9c10: 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69   of.** the appli
9c20: 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66  cation.  The def
9c30: 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69  ault configurati
9c40: 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  on is recommende
9c50: 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70  d for most.** ap
9c60: 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73  plications and s
9c70: 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69  o this routine i
9c80: 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65  s usually not ne
9c90: 63 65 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a  cessary.  It is.
9ca0: 2a 2a 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73  ** provided to s
9cb0: 75 70 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c  upport rare appl
9cc0: 69 63 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e  ications with un
9cd0: 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a  usual needs..**.
9ce0: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63  ** The sqlite3_c
9cf0: 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
9d00: 65 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73  e is not threads
9d10: 61 66 65 2e 20 20 54 68 65 20 61 70 70 6c 69 63  afe.  The applic
9d20: 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e  ation.** must in
9d30: 73 75 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 68  sure that no oth
9d40: 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
9d50: 61 63 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 64  aces are invoked
9d60: 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72   by other.** thr
9d70: 65 61 64 73 20 77 68 69 6c 65 20 73 71 6c 69 74  eads while sqlit
9d80: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 72  e3_config() is r
9d90: 75 6e 6e 69 6e 67 2e 20 20 46 75 72 74 68 65 72  unning.  Further
9da0: 6d 6f 72 65 2c 20 73 71 6c 69 74 65 33 5f 63 6f  more, sqlite3_co
9db0: 6e 66 69 67 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e  nfig().** may on
9dc0: 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 72  ly be invoked pr
9dd0: 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 79 20 69  ior to library i
9de0: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73  nitialization us
9df0: 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
9e00: 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72  initialize()] or
9e10: 20 61 66 74 65 72 20 73 68 75 74 64 6f 77 6e 20   after shutdown 
9e20: 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74  by [sqlite3_shut
9e30: 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 4e 6f 74 65  down()]..** Note
9e40: 2c 20 68 6f 77 65 76 65 72 2c 20 74 68 61 74 20  , however, that 
9e50: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
9e60: 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61   can be called a
9e70: 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a  s part of the.**
9e80: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
9e90: 6f 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  of an applicatio
9ea0: 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c 69 74  n-defined [sqlit
9eb0: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a  e3_os_init()]..*
9ec0: 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  *.** The first a
9ed0: 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
9ee0: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 61  e3_config() is a
9ef0: 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51  n integer.** [SQ
9f00: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
9f10: 4c 45 54 48 52 45 41 44 20 7c 20 63 6f 6e 66 69  LETHREAD | confi
9f20: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d  guration option]
9f30: 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 73   that determines
9f40: 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70 65 72 74  .** what propert
9f50: 79 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20 74  y of SQLite is t
9f60: 6f 20 62 65 20 63 6f 6e 66 69 67 75 72 65 64 2e  o be configured.
9f70: 20 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 67    Subsequent arg
9f80: 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64  uments.** vary d
9f90: 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
9fa0: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
9fb0: 49 4e 47 4c 45 54 48 52 45 41 44 20 7c 20 63 6f  INGLETHREAD | co
9fc0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
9fd0: 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69  on].** in the fi
9fe0: 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  rst argument..**
9ff0: 0a 2a 2a 20 57 68 65 6e 20 61 20 63 6f 6e 66 69  .** When a confi
a000: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
a010: 69 73 20 73 65 74 2c 20 73 71 6c 69 74 65 33 5f  is set, sqlite3_
a020: 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e 73  config() returns
a030: 20 53 51 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a 20 49   SQLITE_OK..** I
a040: 66 20 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20  f the option is 
a050: 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74  unknown or SQLit
a060: 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73  e is unable to s
a070: 65 74 20 74 68 65 20 6f 70 74 69 6f 6e 20 0a 2a  et the option .*
a080: 2a 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74  * then this rout
a090: 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 6e 6f  ine returns a no
a0a0: 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f  n-zero [error co
a0b0: 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  de]..*/.int sqli
a0c0: 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20  te3_config(int, 
a0d0: 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ...);../*.** CAP
a0e0: 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c  I3REF: Memory Al
a0f0: 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65  location Routine
a100: 73 20 7b 46 31 30 31 35 35 7d 0a 2a 2a 0a 2a 2a  s {F10155}.**.**
a110: 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   An instance of 
a120: 74 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69  this object defi
a130: 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63  nes the interfac
a140: 65 20 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65  e between SQLite
a150: 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65  .** and low-leve
a160: 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
a170: 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 20 20 0a  ion routines.  .
a180: 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63  **.** This objec
a190: 74 20 69 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c  t is used in onl
a1a0: 79 20 6f 6e 65 20 70 6c 61 63 65 20 69 6e 20 74  y one place in t
a1b0: 68 65 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  he SQLite interf
a1c0: 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65  ace..** A pointe
a1d0: 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65  r to an instance
a1e0: 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20   of this object 
a1f0: 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20  is the argument 
a200: 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
a210: 6f 6e 66 69 67 5d 20 77 68 65 6e 20 74 68 65 20  onfig] when the 
a220: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
a230: 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49  tion is.** [SQLI
a240: 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
a250: 5d 2e 20 20 42 79 20 63 72 65 61 74 69 6e 67 20  ].  By creating 
a260: 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
a270: 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e  his object.** an
a280: 64 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20  d passing it to 
a290: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d  [sqlite3_config]
a2a0: 20 64 75 72 69 6e 67 20 63 6f 6e 66 69 67 75 72   during configur
a2b0: 61 74 69 6f 6e 2c 20 61 6e 0a 2a 2a 20 61 70 70  ation, an.** app
a2c0: 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 70 65  lication can spe
a2d0: 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74  cify an alternat
a2e0: 69 76 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ive memory alloc
a2f0: 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 0a  ation subsystem.
a300: 2a 2a 20 66 6f 72 20 53 51 4c 69 74 65 20 74 6f  ** for SQLite to
a310: 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20   use for all of 
a320: 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f  its dynamic memo
a330: 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20  ry needs..**.** 
a340: 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 69 74 65  Note that SQLite
a350: 20 63 6f 6d 65 73 20 77 69 74 68 20 61 20 62 75   comes with a bu
a360: 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c  ilt-in memory al
a370: 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 69 73 0a  locator that is.
a380: 2a 2a 20 70 65 72 66 65 63 74 6c 79 20 61 64 65  ** perfectly ade
a390: 71 75 61 74 65 20 66 6f 72 20 74 68 65 20 6f 76  quate for the ov
a3a0: 65 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72  erwhelming major
a3b0: 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69  ity of applicati
a3c0: 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20  ons.** and that 
a3d0: 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 6f  this object is o
a3e0: 6e 6c 79 20 75 73 65 66 75 6c 20 74 6f 20 61 20  nly useful to a 
a3f0: 74 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66  tiny minority of
a400: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
a410: 20 77 69 74 68 20 73 70 65 63 69 61 6c 69 7a 65   with specialize
a420: 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  d memory allocat
a430: 69 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 73  ion requirements
a440: 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69  .  This object i
a450: 73 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 64  s.** also used d
a460: 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20 6f 66  uring testing of
a470: 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72   SQLite in order
a480: 20 74 6f 20 73 70 65 63 69 66 79 20 61 6e 20 61   to specify an a
a490: 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65  lternative.** me
a4a0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74  mory allocator t
a4b0: 68 61 74 20 73 69 6d 75 6c 61 74 65 73 20 6d 65  hat simulates me
a4c0: 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f  mory out-of-memo
a4d0: 72 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e  ry conditions in
a4e0: 0a 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 72  .** order to ver
a4f0: 69 66 79 20 74 68 61 74 20 53 51 4c 69 74 65 20  ify that SQLite 
a500: 72 65 63 6f 76 65 72 73 20 67 72 61 63 65 66 75  recovers gracefu
a510: 6c 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a  lly from such.**
a520: 20 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a   conditions..**.
a530: 2a 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63 2c 20  ** The xMalloc, 
a540: 78 46 72 65 65 2c 20 61 6e 64 20 78 52 65 61 6c  xFree, and xReal
a550: 6c 6f 63 20 6d 65 74 68 6f 64 73 20 73 68 6f 75  loc methods shou
a560: 6c 64 20 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65  ld work like the
a570: 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20 66 72  .** malloc(), fr
a580: 65 65 28 29 2c 20 61 6e 64 20 72 65 61 6c 6c 6f  ee(), and reallo
a590: 63 28 29 20 66 75 6e 63 74 69 6f 6e 73 20 66 72  c() functions fr
a5a0: 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20  om the standard 
a5b0: 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 78  library..**.** x
a5c0: 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 75  Size should retu
a5d0: 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64  rn the allocated
a5e0: 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72   size of a memor
a5f0: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  y allocation.** 
a600: 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69  previously obtai
a610: 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63  ned from xMalloc
a620: 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54   or xRealloc.  T
a630: 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a  he allocated siz
a640: 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61  e.** is always a
a650: 74 20 6c 65 61 73 74 20 61 73 20 62 69 67 20 61  t least as big a
a660: 73 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20  s the requested 
a670: 73 69 7a 65 20 62 75 74 20 6d 61 79 20 62 65 20  size but may be 
a680: 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  larger..**.** Th
a690: 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f  e xRoundup metho
a6a0: 64 20 72 65 74 75 72 6e 73 20 77 68 61 74 20 77  d returns what w
a6b0: 6f 75 6c 64 20 62 65 20 74 68 65 20 61 6c 6c 6f  ould be the allo
a6c0: 63 61 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a  cated size of.**
a6d0: 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
a6e0: 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 72  tion given a par
a6f0: 74 69 63 75 6c 61 72 20 72 65 71 75 65 73 74 65  ticular requeste
a700: 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65  d size.  Most me
a710: 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f  mory.** allocato
a720: 72 73 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f  rs round up memo
a730: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61  ry allocations a
a740: 74 20 6c 65 61 73 74 20 74 6f 20 74 68 65 20 6e  t least to the n
a750: 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20  ext multiple.** 
a760: 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f  of 8.  Some allo
a770: 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20  cators round up 
a780: 74 6f 20 61 20 6c 61 72 67 65 72 20 6d 75 6c 74  to a larger mult
a790: 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f 77  iple or to a pow
a7a0: 65 72 20 6f 66 20 32 2e 20 0a 2a 2a 0a 2a 2a 20  er of 2. .**.** 
a7b0: 54 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64  The xInit method
a7c0: 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65   initializes the
a7d0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
a7e0: 72 2e 20 20 28 46 6f 72 20 65 78 61 6d 70 6c 65  r.  (For example
a7f0: 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20 61 6c  ,.** it might al
a800: 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 71 75 69  locate any requi
a810: 72 65 20 6d 75 74 65 78 65 73 20 6f 72 20 69 6e  re mutexes or in
a820: 69 74 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61  itialize interna
a830: 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72 75 63 74  l data.** struct
a840: 75 72 65 73 2e 20 20 54 68 65 20 78 53 68 75 74  ures.  The xShut
a850: 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 69  down method is i
a860: 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72 65 63 74  nvoked (indirect
a870: 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ly) by.** [sqlit
a880: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 61  e3_shutdown()] a
a890: 6e 64 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f  nd should deallo
a8a0: 63 61 74 65 20 61 6e 79 20 72 65 73 6f 75 72 63  cate any resourc
a8b0: 65 73 20 61 63 71 75 69 72 65 64 0a 2a 2a 20 62  es acquired.** b
a8c0: 79 20 78 49 6e 69 74 2e 20 20 54 68 65 20 70 41  y xInit.  The pA
a8d0: 70 70 44 61 74 61 20 70 6f 69 6e 74 65 72 20 69  ppData pointer i
a8e0: 73 20 75 73 65 64 20 61 73 20 74 68 65 20 6f 6e  s used as the on
a8f0: 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  ly parameter to.
a900: 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20 78 53 68  ** xInit and xSh
a910: 75 74 64 6f 77 6e 2e 0a 2a 2f 0a 74 79 70 65 64  utdown..*/.typed
a920: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
a930: 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71  3_mem_methods sq
a940: 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
a950: 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  s;.struct sqlite
a960: 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a  3_mem_methods {.
a970: 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f    void *(*xMallo
a980: 63 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20  c)(int);        
a990: 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63   /* Memory alloc
a9a0: 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a  ation function *
a9b0: 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46 72 65 65  /.  void (*xFree
a9c0: 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20  )(void*);       
a9d0: 20 20 20 2f 2a 20 46 72 65 65 20 61 20 70 72 69     /* Free a pri
a9e0: 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f  or allocation */
a9f0: 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c  .  void *(*xReal
aa00: 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b  loc)(void*,int);
aa10: 20 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20 61    /* Resize an a
aa20: 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69  llocation */.  i
aa30: 6e 74 20 28 2a 78 53 69 7a 65 29 28 76 6f 69 64  nt (*xSize)(void
aa40: 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a  *);           /*
aa50: 20 52 65 74 75 72 6e 20 74 68 65 20 73 69 7a 65   Return the size
aa60: 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f   of an allocatio
aa70: 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f  n */.  int (*xRo
aa80: 75 6e 64 75 70 29 28 69 6e 74 29 3b 20 20 20 20  undup)(int);    
aa90: 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75        /* Round u
aaa0: 70 20 72 65 71 75 65 73 74 20 73 69 7a 65 20 74  p request size t
aab0: 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a  o allocation siz
aac0: 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e  e */.  int (*xIn
aad0: 69 74 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  it)(void*);     
aae0: 20 20 20 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c        /* Initial
aaf0: 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  ize the memory a
ab00: 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f  llocator */.  vo
ab10: 69 64 20 28 2a 78 53 68 75 74 64 6f 77 6e 29 28  id (*xShutdown)(
ab20: 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20  void*);      /* 
ab30: 44 65 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65  Deinitialize the
ab40: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
ab50: 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70  r */.  void *pAp
ab60: 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20  pData;          
ab70: 20 20 20 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e        /* Argumen
ab80: 74 20 74 6f 20 78 49 6e 69 74 28 29 20 61 6e 64  t to xInit() and
ab90: 20 78 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a   xShutdown() */.
aba0: 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
abb0: 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 69 6f  EF: Configuratio
abc0: 6e 20 4f 70 74 69 6f 6e 73 20 7b 46 31 30 31 36  n Options {F1016
abd0: 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  0}.**.** These c
abe0: 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65  onstants are the
abf0: 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67   available integ
ac00: 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  er configuration
ac10: 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a   options that.**
ac20: 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61   can be passed a
ac30: 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  s the first argu
ac40: 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c  ment to the [sql
ac50: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69  ite3_config()] i
ac60: 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 0a 2a 2a  nterface..** .**
ac70: 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c   <dl>.** <dt>SQL
ac80: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
ac90: 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20  ETHREAD</dt>.** 
aca0: 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f  <dd>There are no
acb0: 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
acc0: 69 73 20 6f 70 74 69 6f 6e 2e 20 20 54 68 69 73  is option.  This
acd0: 20 6f 70 74 69 6f 6e 20 64 69 73 61 62 6c 65 73   option disables
ace0: 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67  .** all mutexing
acf0: 20 61 6e 64 20 70 75 74 73 20 53 51 4c 69 74 65   and puts SQLite
ad00: 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68 65   into a mode whe
ad10: 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62  re it can only b
ad20: 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 61 20 73  e used.** by a s
ad30: 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 3c 2f 64  ingle thread.</d
ad40: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
ad50: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
ad60: 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c  THREAD</dt>.** <
ad70: 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20  dd>There are no 
ad80: 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69  arguments to thi
ad90: 73 20 6f 70 74 69 6f 6e 2e 20 20 54 68 69 73 20  s option.  This 
ada0: 6f 70 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 0a  option disables.
adb0: 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b  ** mutexing on [
adc0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
add0: 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72  ion] and [prepar
ade0: 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62  ed statement] ob
adf0: 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70  jects..** The ap
ae00: 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 72 65 73  plication is res
ae10: 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73 65 72  ponsible for ser
ae20: 69 61 6c 69 7a 69 6e 67 20 61 63 63 65 73 73 20  ializing access 
ae30: 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  to.** [database 
ae40: 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64  connections] and
ae50: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
ae60: 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74 68  ments].  But oth
ae70: 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72  er mutexes.** ar
ae80: 65 20 65 6e 61 62 6c 65 64 20 73 6f 20 74 68 61  e enabled so tha
ae90: 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65  t SQLite will be
aea0: 20 73 61 66 65 20 74 6f 20 75 73 65 20 69 6e 20   safe to use in 
aeb0: 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64  a multi-threaded
aec0: 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 2e  .** environment.
aed0: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
aee0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
aef0: 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a  RIALIZED</dt>.**
af00: 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
af10: 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
af20: 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 54 68 69  his option.  Thi
af30: 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65 73  s option enables
af40: 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73 20  .** all mutexes 
af50: 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 72 65  including the re
af60: 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65 78  cursive.** mutex
af70: 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20  es on [database 
af80: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20  connection] and 
af90: 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
afa0: 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a  ent] objects..**
afb0: 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20 28 77   In this mode (w
afc0: 68 69 63 68 20 69 73 20 74 68 65 20 64 65 66 61  hich is the defa
afd0: 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74 65 20  ult when SQLite 
afe0: 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
aff0: 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 48 52 45 41  .** SQLITE_THREA
b000: 44 53 41 46 45 3d 31 29 20 74 68 65 20 53 51 4c  DSAFE=1) the SQL
b010: 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c  ite library will
b020: 20 69 74 73 65 6c 66 20 73 65 72 69 61 6c 69 7a   itself serializ
b030: 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b  e access.** to [
b040: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
b050: 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61  ions] and [prepa
b060: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20  red statements] 
b070: 73 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 61  so that the.** a
b080: 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 66 72  pplication is fr
b090: 65 65 20 74 6f 20 75 73 65 20 74 68 65 20 73 61  ee to use the sa
b0a0: 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  me [database con
b0b0: 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a  nection] or the.
b0c0: 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65  ** same [prepare
b0d0: 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20  d statement] in 
b0e0: 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64  different thread
b0f0: 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69  s at the same ti
b100: 6d 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  me.</dd>.**.** <
b110: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
b120: 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20  _MALLOC</dt>.** 
b130: 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20  <dd>This option 
b140: 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
b150: 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
b160: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
b170: 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20  .** instance of 
b180: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  the [sqlite3_mem
b190: 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
b1a0: 75 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65  ure.  The argume
b1b0: 6e 74 20 73 70 65 63 69 66 69 63 73 0a 2a 2a 20  nt specifics.** 
b1c0: 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d  alternative low-
b1d0: 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c  level memory all
b1e0: 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
b1f0: 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70   to be used in p
b200: 6c 61 63 65 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f  lace.** the memo
b210: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f  ry allocation ro
b220: 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74  utines built int
b230: 6f 20 53 51 4c 69 74 65 2e 3c 2f 64 64 3e 0a 2a  o SQLite.</dd>.*
b240: 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
b250: 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43  CONFIG_GETMALLOC
b260: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69  </dt>.** <dd>Thi
b270: 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  s option takes a
b280: 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
b290: 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e   which is a poin
b2a0: 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73  ter to an.** ins
b2b0: 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71  tance of the [sq
b2c0: 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
b2d0: 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54  s] structure.  T
b2e0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  he [sqlite3_mem_
b2f0: 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75  methods].** stru
b300: 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20  cture is filled 
b310: 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74  with the current
b320: 6c 79 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72  ly defined memor
b330: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75  y allocation rou
b340: 74 69 6e 65 73 2e 0a 2a 2a 20 54 68 69 73 20 6f  tines..** This o
b350: 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65  ption can be use
b360: 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68  d to overload th
b370: 65 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79  e default memory
b380: 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72   allocation.** r
b390: 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77  outines with a w
b3a0: 72 61 70 70 65 72 20 74 68 61 74 20 73 69 6d 75  rapper that simu
b3b0: 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61  lations memory a
b3c0: 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72  llocation failur
b3d0: 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d  e or.** tracks m
b3e0: 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 66 6f 72  emory usage, for
b3f0: 20 65 78 61 6d 70 6c 65 2e 3c 2f 64 64 3e 0a 2a   example.</dd>.*
b400: 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
b410: 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
b420: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69  </dt>.** <dd>Thi
b430: 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73  s option takes s
b440: 69 6e 67 6c 65 20 62 6f 6f 6c 65 61 6e 20 61 72  ingle boolean ar
b450: 67 75 6d 65 6e 74 20 77 68 69 63 68 20 65 6e 61  gument which ena
b460: 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73  bles or disables
b470: 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c 65 63 74 69  .** the collecti
b480: 6f 6e 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c  on of memory all
b490: 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69  ocation statisti
b4a0: 63 73 2e 20 20 57 68 65 6e 20 64 69 73 61 62 6c  cs.  When disabl
b4b0: 65 64 2c 20 74 68 65 0a 2a 2a 20 66 6f 6c 6c 6f  ed, the.** follo
b4c0: 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e 74 65  wing SQLite inte
b4d0: 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f  rfaces become no
b4e0: 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a  n-operational:.*
b4f0: 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c  *   <ul>.**   <l
b500: 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  i> [sqlite3_memo
b510: 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20  ry_used()].**   
b520: 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65  <li> [sqlite3_me
b530: 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
b540: 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c  ].**   <li> [sql
b550: 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c  ite3_soft_heap_l
b560: 69 6d 69 74 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69  imit()].**   <li
b570: 3e 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79  > sqlite3_memory
b580: 5f 73 74 61 74 75 73 28 29 0a 2a 2a 20 20 20 3c  _status().**   <
b590: 2f 75 6c 3e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a  /ul>.** </dd>.**
b5a0: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
b5b0: 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3c 2f 64  ONFIG_SCRATCH</d
b5c0: 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f  t>.** <dd>This o
b5d0: 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20  ption specifies 
b5e0: 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20  a static memory 
b5f0: 62 75 66 66 65 72 20 74 68 61 74 20 53 51 4c 69  buffer that SQLi
b600: 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a  te can use for.*
b610: 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79  * scratch memory
b620: 2e 20 20 54 68 65 72 65 20 61 72 65 20 74 68 72  .  There are thr
b630: 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 20 41  ee arguments:  A
b640: 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
b650: 6d 65 6d 6f 72 79 2c 20 74 68 65 0a 2a 2a 20 73  memory, the.** s
b660: 69 7a 65 20 6f 66 20 65 61 63 68 20 73 63 72 61  ize of each scra
b670: 74 63 68 20 62 75 66 66 65 72 20 28 73 7a 29 2c  tch buffer (sz),
b680: 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20   and the number 
b690: 6f 66 20 62 75 66 66 65 72 73 20 28 4e 29 2e 20  of buffers (N). 
b6a0: 20 54 68 65 20 73 7a 0a 2a 2a 20 61 72 67 75 6d   The sz.** argum
b6b0: 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 6d 75  ent must be a mu
b6c0: 6c 74 69 70 6c 65 20 6f 66 20 31 36 2e 20 54 68  ltiple of 16. Th
b6d0: 65 20 66 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d  e first.** argum
b6e0: 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f 69 6e 74  ent should point
b6f0: 20 74 6f 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f   to an allocatio
b700: 6e 20 6f 66 20 61 74 20 6c 65 61 73 74 20 28 73  n of at least (s
b710: 7a 2b 31 29 2a 4e 20 62 79 74 65 73 20 6f 66 20  z+1)*N bytes of 
b720: 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 53 51 4c 69 74  memory..** SQLit
b730: 65 20 77 69 6c 6c 20 75 73 65 20 6e 6f 20 6d 6f  e will use no mo
b740: 72 65 20 74 68 61 6e 20 6f 6e 65 20 73 63 72 61  re than one scra
b750: 74 63 68 20 62 75 66 66 65 72 20 61 74 20 6f 6e  tch buffer at on
b760: 63 65 20 70 65 72 20 74 68 72 65 61 64 2c 20 73  ce per thread, s
b770: 6f 0a 2a 2a 20 4e 20 73 68 6f 75 6c 64 20 62 65  o.** N should be
b780: 20 73 65 74 20 74 6f 20 74 68 65 20 65 78 70 65   set to the expe
b790: 63 74 65 64 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  cted maximum num
b7a0: 62 65 72 20 6f 66 20 74 68 72 65 61 64 73 2e 20  ber of threads. 
b7b0: 20 54 68 65 20 73 7a 20 0a 2a 2a 20 70 61 72 61   The sz .** para
b7c0: 6d 65 74 65 72 20 73 68 6f 75 6c 64 20 62 65 20  meter should be 
b7d0: 36 20 74 69 6d 65 73 20 74 68 65 20 73 69 7a 65  6 times the size
b7e0: 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20   of the largest 
b7f0: 64 61 74 61 62 61 73 65 20 70 61 67 65 20 73 69  database page si
b800: 7a 65 2e 0a 2a 2a 20 53 63 72 61 74 63 68 20 62  ze..** Scratch b
b810: 75 66 66 65 72 73 20 61 72 65 20 75 73 65 64 20  uffers are used 
b820: 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 62  as part of the b
b830: 74 72 65 65 20 62 61 6c 61 6e 63 65 20 6f 70 65  tree balance ope
b840: 72 61 74 69 6f 6e 2e 20 20 49 66 0a 2a 2a 20 54  ration.  If.** T
b850: 68 65 20 62 74 72 65 65 20 62 61 6c 61 6e 63 65  he btree balance
b860: 72 20 6e 65 65 64 73 20 61 64 64 69 74 69 6f 6e  r needs addition
b870: 61 6c 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64  al memory beyond
b880: 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 65   what is provide
b890: 64 20 62 79 0a 2a 2a 20 73 63 72 61 74 63 68 20  d by.** scratch 
b8a0: 62 75 66 66 65 72 73 20 6f 72 20 69 66 20 6e 6f  buffers or if no
b8b0: 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72 20   scratch buffer 
b8c0: 73 70 61 63 65 20 69 73 20 73 70 65 63 69 66 69  space is specifi
b8d0: 65 64 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 0a  ed, then SQLite.
b8e0: 2a 2a 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69  ** goes to [sqli
b8f0: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 74 6f  te3_malloc()] to
b900: 20 6f 62 74 61 69 6e 20 74 68 65 20 6d 65 6d 6f   obtain the memo
b910: 72 79 20 69 74 20 6e 65 65 64 73 2e 0a 2a 2a 20  ry it needs..** 
b920: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
b930: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
b940: 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20  GECACHE</dt>.** 
b950: 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20  <dd>This option 
b960: 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74  specifies a stat
b970: 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  ic memory buffer
b980: 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e   that SQLite can
b990: 20 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20   use for.** the 
b9a0: 64 61 74 61 62 61 73 65 20 70 61 67 65 20 63 61  database page ca
b9b0: 63 68 65 2e 20 20 54 68 65 72 65 20 61 72 65 20  che.  There are 
b9c0: 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a  three arguments:
b9d0: 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f  .** A pointer to
b9e0: 20 74 68 65 20 6d 65 6d 6f 72 79 2c 20 74 68 65   the memory, the
b9f0: 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68  .** size of each
ba00: 20 70 61 67 65 20 62 75 66 66 65 72 20 28 73 7a   page buffer (sz
ba10: 29 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65  ), and the numbe
ba20: 72 20 6f 66 20 70 61 67 65 73 20 28 4e 29 2e 20  r of pages (N). 
ba30: 20 54 68 65 20 73 7a 0a 2a 2a 20 61 72 67 75 6d   The sz.** argum
ba40: 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 70 6f  ent must be a po
ba50: 77 65 72 20 6f 66 20 74 77 6f 20 62 65 74 77 65  wer of two betwe
ba60: 65 6e 20 35 31 32 20 61 6e 64 20 33 32 37 36 38  en 512 and 32768
ba70: 2e 20 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20  .  The first.** 
ba80: 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20  argument should 
ba90: 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61 6c 6c 6f  point to an allo
baa0: 63 61 74 69 6f 6e 20 6f 66 20 61 74 20 6c 65 61  cation of at lea
bab0: 73 74 20 28 73 7a 2b 34 29 2a 4e 20 62 79 74 65  st (sz+4)*N byte
bac0: 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20  s of memory..** 
bad0: 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20  SQLite will use 
bae0: 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69  the memory provi
baf0: 64 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  ded by the first
bb00: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 61 74   argument to sat
bb10: 69 73 66 79 0a 2a 2a 20 69 74 73 20 6d 65 6d 6f  isfy.** its memo
bb20: 72 79 20 6e 65 65 64 73 20 66 6f 72 20 74 68 65  ry needs for the
bb30: 20 66 69 72 73 74 20 4e 20 70 61 67 65 73 20 74   first N pages t
bb40: 68 61 74 20 69 74 20 61 64 64 73 20 74 6f 20 63  hat it adds to c
bb50: 61 63 68 65 2e 20 20 49 66 20 0a 2a 2a 20 61 64  ache.  If .** ad
bb60: 64 69 74 69 6f 6e 61 6c 20 70 61 67 65 20 63 61  ditional page ca
bb70: 63 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65  che memory is ne
bb80: 65 64 65 64 20 62 65 79 6f 6e 64 20 77 68 61 74  eded beyond what
bb90: 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 0a   is provided by.
bba0: 2a 2a 20 74 68 69 73 20 6f 70 74 69 6f 6e 2c 20  ** this option, 
bbb0: 74 68 65 6e 20 53 51 4c 69 74 65 20 67 6f 65 73  then SQLite goes
bbc0: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   to [sqlite3_mal
bbd0: 6c 6f 63 28 29 5d 20 66 6f 72 20 74 68 65 20 61  loc()] for the a
bbe0: 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 73 74 6f  dditional.** sto
bbf0: 72 61 67 65 20 73 70 61 63 65 2e 0a 2a 2a 20 3c  rage space..** <
bc00: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
bc10: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41  QLITE_CONFIG_HEA
bc20: 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  P</dt>.** <dd>Th
bc30: 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66  is option specif
bc40: 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d  ies a static mem
bc50: 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74 20  ory buffer that 
bc60: 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a  SQLite will use.
bc70: 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74  ** for all of it
bc80: 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79  s dynamic memory
bc90: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64   allocation need
bca0: 73 20 62 65 79 6f 6e 64 20 74 68 6f 73 65 20 70  s beyond those p
bcb0: 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f 72 20 62  rovided.** for b
bcc0: 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  y [SQLITE_CONFIG
bcd0: 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 20 5b 53  _SCRATCH] and [S
bce0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
bcf0: 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 72  ECACHE]..** Ther
bd00: 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75  e are three argu
bd10: 6d 65 6e 74 73 3a 20 41 20 70 6f 69 6e 74 65 72  ments: A pointer
bd20: 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 20   to the memory, 
bd30: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
bd40: 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65   bytes in the me
bd50: 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64  mory buffer, and
bd60: 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c   the minimum all
bd70: 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 20 20 57  ocation size.  W
bd80: 68 65 6e 0a 2a 2a 20 74 68 69 73 20 63 6f 6e 66  hen.** this conf
bd90: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
bda0: 20 69 73 20 75 73 65 64 2c 20 53 51 4c 69 74 65   is used, SQLite
bdb0: 20 6e 65 76 65 72 20 63 61 6c 6c 73 20 74 68 65   never calls the
bdc0: 20 73 79 73 74 65 6d 0a 2a 2a 20 6d 61 6c 6c 6f   system.** mallo
bdd0: 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  c() implementati
bde0: 6f 6e 20 62 75 74 20 69 6e 73 74 65 61 64 20 75  on but instead u
bdf0: 73 65 73 20 74 68 65 20 73 75 70 70 6c 69 65 64  ses the supplied
be00: 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 0a 2a   memory buffer.*
be10: 2a 20 74 6f 20 73 61 74 69 73 66 79 20 61 6c 6c  * to satisfy all
be20: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
be30: 28 29 5d 20 72 65 71 75 65 73 74 73 2e 0a 2a 2a  ()] requests..**
be40: 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74   </dd>.**.** <dt
be50: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
be60: 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  UTEX</dt>.** <dd
be70: 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  >This option tak
be80: 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
be90: 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
bea0: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a  pointer to an.**
beb0: 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
bec0: 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
bed0: 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
bee0: 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e  re.  The argumen
bef0: 74 20 73 70 65 63 69 66 69 63 73 0a 2a 2a 20 61  t specifics.** a
bf00: 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c  lternative low-l
bf10: 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 74 69  evel mutex routi
bf20: 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 20 69  nes to be used i
bf30: 6e 20 70 6c 61 63 65 0a 2a 2a 20 74 68 65 20 6d  n place.** the m
bf40: 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 62 75  utex routines bu
bf50: 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e  ilt into SQLite.
bf60: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
bf70: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
bf80: 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20  TMALLOC</dt>.** 
bf90: 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20  <dd>This option 
bfa0: 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
bfb0: 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
bfc0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
bfd0: 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20  .** instance of 
bfe0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  the [sqlite3_mut
bff0: 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  ex_methods] stru
c000: 63 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b  cture.  The.** [
c010: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
c020: 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74  thods].** struct
c030: 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69  ure is filled wi
c040: 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79  th the currently
c050: 20 64 65 66 69 6e 65 64 20 6d 75 74 65 78 20 72   defined mutex r
c060: 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 54 68 69 73  outines..** This
c070: 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75   option can be u
c080: 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20  sed to overload 
c090: 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65  the default mute
c0a0: 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  x allocation.** 
c0b0: 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20  routines with a 
c0c0: 77 72 61 70 70 65 72 20 75 73 65 64 20 74 6f 20  wrapper used to 
c0d0: 74 72 61 63 6b 20 6d 75 74 65 78 20 75 73 61 67  track mutex usag
c0e0: 65 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63  e for performanc
c0f0: 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f  e.** profiling o
c100: 72 20 74 65 73 74 69 6e 67 2c 20 66 6f 72 20 65  r testing, for e
c110: 78 61 6d 70 6c 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a  xample.</dd>.**.
c120: 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 20 0a 23 64 65  ** </dl>.*/ .#de
c130: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
c140: 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20  IG_SINGLETHREAD 
c150: 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64   1  /* nil */.#d
c160: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
c170: 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20  FIG_MULTITHREAD 
c180: 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23    2  /* nil */.#
c190: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
c1a0: 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20  NFIG_SERIALIZED 
c1b0: 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a     3  /* nil */.
c1c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
c1d0: 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20  ONFIG_MALLOC    
c1e0: 20 20 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 65      4  /* sqlite
c1f0: 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a  3_mem_methods* *
c200: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
c210: 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f  _CONFIG_GETMALLO
c220: 43 20 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69  C     5  /* sqli
c230: 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a  te3_mem_methods*
c240: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
c250: 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
c260: 48 20 20 20 20 20 20 20 36 20 20 2f 2a 20 76 6f  H       6  /* vo
c270: 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74  id*, int sz, int
c280: 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51   N */.#define SQ
c290: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
c2a0: 43 41 43 48 45 20 20 20 20 20 37 20 20 2f 2a 20  CACHE     7  /* 
c2b0: 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69  void*, int sz, i
c2c0: 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nt N */.#define 
c2d0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45  SQLITE_CONFIG_HE
c2e0: 41 50 20 20 20 20 20 20 20 20 20 20 38 20 20 2f  AP          8  /
c2f0: 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79  * void*, int nBy
c300: 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23  te, int min */.#
c310: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
c320: 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 20  NFIG_MEMSTATUS  
c330: 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e     9  /* boolean
c340: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
c350: 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20  TE_CONFIG_MUTEX 
c360: 20 20 20 20 20 20 20 31 30 20 20 2f 2a 20 73 71         10  /* sq
c370: 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
c380: 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ods* */.#define 
c390: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
c3a0: 54 4d 55 54 45 58 20 20 20 20 20 31 31 20 20 2f  TMUTEX     11  /
c3b0: 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  * sqlite3_mutex_
c3c0: 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 0a 0a 2f 2a  methods* */.../*
c3d0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e  .** CAPI3REF: En
c3e0: 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20  able Or Disable 
c3f0: 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20  Extended Result 
c400: 43 6f 64 65 73 20 7b 46 31 32 32 30 30 7d 0a 2a  Codes {F12200}.*
c410: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
c420: 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74  _extended_result
c430: 5f 63 6f 64 65 73 28 29 20 72 6f 75 74 69 6e 65  _codes() routine
c440: 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61   enables or disa
c450: 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  bles the.** [SQL
c460: 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c  ITE_IOERR_READ |
c470: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
c480: 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65 20   codes] feature 
c490: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 54 68  of SQLite..** Th
c4a0: 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  e extended resul
c4b0: 74 20 63 6f 64 65 73 20 61 72 65 20 64 69 73 61  t codes are disa
c4c0: 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20  bled by default 
c4d0: 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a  for historical.*
c4e0: 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  * compatibility.
c4f0: 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
c500: 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 30 31  S:.**.** {F12201
c510: 7d 20 45 61 63 68 20 6e 65 77 20 5b 64 61 74 61  } Each new [data
c520: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
c530: 20 73 68 61 6c 6c 20 68 61 76 65 20 74 68 65 20   shall have the 
c540: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 65 78  .**          [ex
c550: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
c560: 64 65 73 5d 20 66 65 61 74 75 72 65 0a 2a 2a 20  des] feature.** 
c570: 20 20 20 20 20 20 20 20 20 64 69 73 61 62 6c 65           disable
c580: 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a  d by default..**
c590: 0a 2a 2a 20 7b 46 31 32 32 30 32 7d 20 54 68 65  .** {F12202} The
c5a0: 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64   [sqlite3_extend
c5b0: 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28  ed_result_codes(
c5c0: 44 2c 46 29 5d 20 69 6e 74 65 72 66 61 63 65 20  D,F)] interface 
c5d0: 73 68 61 6c 6c 20 65 6e 61 62 6c 65 0a 2a 2a 20  shall enable.** 
c5e0: 20 20 20 20 20 20 20 20 20 5b 65 78 74 65 6e 64           [extend
c5f0: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  ed result codes]
c600: 20 66 6f 72 20 74 68 65 20 0a 2a 2a 20 20 20 20   for the .**    
c610: 20 20 20 20 20 20 5b 64 61 74 61 62 61 73 65 20        [database 
c620: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 69 66  connection] D if
c630: 20 74 68 65 20 46 20 70 61 72 61 6d 65 74 65 72   the F parameter
c640: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20  .**          is 
c650: 74 72 75 65 2c 20 6f 72 20 64 69 73 61 62 6c 65  true, or disable
c660: 20 74 68 65 6d 20 69 66 20 46 20 69 73 20 66 61   them if F is fa
c670: 6c 73 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  lse..*/.int sqli
c680: 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73  te3_extended_res
c690: 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74 65  ult_codes(sqlite
c6a0: 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a  3*, int onoff);.
c6b0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
c6c0: 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77   Last Insert Row
c6d0: 69 64 20 7b 46 31 32 32 32 30 7d 0a 2a 2a 0a 2a  id {F12220}.**.*
c6e0: 2a 20 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20  * Each entry in 
c6f0: 61 6e 20 53 51 4c 69 74 65 20 74 61 62 6c 65 20  an SQLite table 
c700: 68 61 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d  has a unique 64-
c710: 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e  bit signed.** in
c720: 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c 65 64  teger key called
c730: 20 74 68 65 20 22 72 6f 77 69 64 22 2e 20 54 68   the "rowid". Th
c740: 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79  e rowid is alway
c750: 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61  s available.** a
c760: 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 20  s an undeclared 
c770: 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57  column named ROW
c780: 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57  ID, OID, or _ROW
c790: 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  ID_ as long as t
c7a0: 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72  hose.** names ar
c7b0: 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 20  e not also used 
c7c0: 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65  by explicitly de
c7d0: 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20  clared columns. 
c7e0: 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20  If.** the table 
c7f0: 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20  has a column of 
c800: 74 79 70 65 20 49 4e 54 45 47 45 52 20 50 52 49  type INTEGER PRI
c810: 4d 41 52 59 20 4b 45 59 20 74 68 65 6e 20 74 68  MARY KEY then th
c820: 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20  at column.** is 
c830: 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f  another alias fo
c840: 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a  r the rowid..**.
c850: 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
c860: 72 65 74 75 72 6e 73 20 74 68 65 20 72 6f 77 69  returns the rowi
c870: 64 20 6f 66 20 74 68 65 20 6d 6f 73 74 20 72 65  d of the most re
c880: 63 65 6e 74 0a 2a 2a 20 73 75 63 63 65 73 73 66  cent.** successf
c890: 75 6c 20 49 4e 53 45 52 54 20 69 6e 74 6f 20 74  ul INSERT into t
c8a0: 68 65 20 64 61 74 61 62 61 73 65 20 66 72 6f 6d  he database from
c8b0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
c8c0: 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 73 68 6f 77  nnection.** show
c8d0: 6e 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  n in the first a
c8e0: 72 67 75 6d 65 6e 74 2e 20 20 49 66 20 6e 6f 20  rgument.  If no 
c8f0: 73 75 63 63 65 73 73 66 75 6c 20 69 6e 73 65 72  successful inser
c900: 74 73 0a 2a 2a 20 68 61 76 65 20 65 76 65 72 20  ts.** have ever 
c910: 6f 63 63 75 72 72 65 64 20 6f 6e 20 74 68 69 73  occurred on this
c920: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
c930: 74 69 6f 6e 2c 20 7a 65 72 6f 20 69 73 20 72 65  tion, zero is re
c940: 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66  turned..**.** If
c950: 20 61 6e 20 49 4e 53 45 52 54 20 6f 63 63 75 72   an INSERT occur
c960: 73 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67  s within a trigg
c970: 65 72 2c 20 74 68 65 6e 20 74 68 65 20 72 6f 77  er, then the row
c980: 69 64 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6e 73  id of the.** ins
c990: 65 72 74 65 64 20 72 6f 77 20 69 73 20 72 65 74  erted row is ret
c9a0: 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 72 6f  urned by this ro
c9b0: 75 74 69 6e 65 20 61 73 20 6c 6f 6e 67 20 61 73  utine as long as
c9c0: 20 74 68 65 20 74 72 69 67 67 65 72 0a 2a 2a 20   the trigger.** 
c9d0: 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20 42 75 74  is running.  But
c9e0: 20 6f 6e 63 65 20 74 68 65 20 74 72 69 67 67 65   once the trigge
c9f0: 72 20 74 65 72 6d 69 6e 61 74 65 73 2c 20 74 68  r terminates, th
ca00: 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
ca10: 0a 2a 2a 20 62 79 20 74 68 69 73 20 72 6f 75 74  .** by this rout
ca20: 69 6e 65 20 72 65 76 65 72 74 73 20 74 6f 20 74  ine reverts to t
ca30: 68 65 20 6c 61 73 74 20 76 61 6c 75 65 20 69 6e  he last value in
ca40: 73 65 72 74 65 64 20 62 65 66 6f 72 65 20 74 68  serted before th
ca50: 65 0a 2a 2a 20 74 72 69 67 67 65 72 20 66 69 72  e.** trigger fir
ca60: 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 49 4e 53  ed..**.** An INS
ca70: 45 52 54 20 74 68 61 74 20 66 61 69 6c 73 20 64  ERT that fails d
ca80: 75 65 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 69  ue to a constrai
ca90: 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20  nt violation is 
caa0: 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 73  not a.** success
cab0: 66 75 6c 20 69 6e 73 65 72 74 20 61 6e 64 20 64  ful insert and d
cac0: 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74  oes not change t
cad0: 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
cae0: 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75  d by this.** rou
caf0: 74 69 6e 65 2e 20 20 54 68 75 73 20 49 4e 53 45  tine.  Thus INSE
cb00: 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45  RT OR FAIL, INSE
cb10: 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e  RT OR IGNORE, IN
cb20: 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b  SERT OR ROLLBACK
cb30: 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20  ,.** and INSERT 
cb40: 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f  OR ABORT make no
cb50: 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20   changes to the 
cb60: 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
cb70: 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  this.** routine 
cb80: 77 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72  when their inser
cb90: 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 57 68 65  tion fails.  Whe
cba0: 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c  n INSERT OR REPL
cbb0: 41 43 45 20 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65  ACE .** encounte
cbc0: 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20  rs a constraint 
cbd0: 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f  violation, it do
cbe0: 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68  es not fail.  Th
cbf0: 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74  e.** INSERT cont
cc00: 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74  inues to complet
cc10: 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74 69  ion after deleti
cc20: 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63 61 75  ng rows that cau
cc30: 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74  sed.** the const
cc40: 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f  raint problem so
cc50: 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41   INSERT OR REPLA
cc60: 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63  CE will always c
cc70: 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74  hange.** the ret
cc80: 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69  urn value of thi
cc90: 73 20 69 6e 74 65 72 66 61 63 65 2e 20 0a 2a 2a  s interface. .**
cca0: 0a 2a 2a 20 46 6f 72 20 74 68 65 20 70 75 72 70  .** For the purp
ccb0: 6f 73 65 73 20 6f 66 20 74 68 69 73 20 72 6f 75  oses of this rou
ccc0: 74 69 6e 65 2c 20 61 6e 20 69 6e 73 65 72 74 20  tine, an insert 
ccd0: 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f  is considered to
cce0: 0a 2a 2a 20 62 65 20 73 75 63 63 65 73 73 66 75  .** be successfu
ccf0: 6c 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20  l even if it is 
cd00: 73 75 62 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c  subsequently rol
cd10: 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  led back..**.** 
cd20: 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
cd30: 2a 20 7b 46 31 32 32 32 31 7d 20 54 68 65 20 5b  * {F12221} The [
cd40: 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73  sqlite3_last_ins
cd50: 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 66 75 6e  ert_rowid()] fun
cd60: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
cd70: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 6f  e.**          ro
cd80: 77 69 64 20 6f 66 20 74 68 65 20 6d 6f 73 74 20  wid of the most 
cd90: 72 65 63 65 6e 74 20 73 75 63 63 65 73 73 66 75  recent successfu
cda0: 6c 20 69 6e 73 65 72 74 20 64 6f 6e 65 0a 2a 2a  l insert done.**
cdb0: 20 20 20 20 20 20 20 20 20 20 6f 6e 20 74 68 65            on the
cdc0: 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
cdd0: 6f 6e 6e 65 63 74 69 6f 6e 20 61 6e 64 20 77 69  onnection and wi
cde0: 74 68 69 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a  thin the same.**
cdf0: 20 20 20 20 20 20 20 20 20 20 6f 72 20 68 69 67            or hig
ce00: 68 65 72 20 6c 65 76 65 6c 20 74 72 69 67 67 65  her level trigge
ce10: 72 20 63 6f 6e 74 65 78 74 2c 20 6f 72 20 7a 65  r context, or ze
ce20: 72 6f 20 69 66 20 74 68 65 72 65 20 68 61 76 65  ro if there have
ce30: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 65 65  .**          bee
ce40: 6e 20 6e 6f 20 71 75 61 6c 69 66 79 69 6e 67 20  n no qualifying 
ce50: 69 6e 73 65 72 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b  inserts..**.** {
ce60: 46 31 32 32 32 33 7d 20 54 68 65 20 5b 73 71 6c  F12223} The [sql
ce70: 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
ce80: 5f 72 6f 77 69 64 28 29 5d 20 66 75 6e 63 74 69  _rowid()] functi
ce90: 6f 6e 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20  on returns.**   
cea0: 20 20 20 20 20 20 20 73 61 6d 65 20 76 61 6c 75         same valu
ceb0: 65 20 77 68 65 6e 20 63 61 6c 6c 65 64 20 66 72  e when called fr
cec0: 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 72 69 67  om the same trig
ced0: 67 65 72 20 63 6f 6e 74 65 78 74 0a 2a 2a 20 20  ger context.**  
cee0: 20 20 20 20 20 20 20 20 69 6d 6d 65 64 69 61 74          immediat
cef0: 65 6c 79 20 62 65 66 6f 72 65 20 61 6e 64 20 61  ely before and a
cf00: 66 74 65 72 20 61 20 52 4f 4c 4c 42 41 43 4b 2e  fter a ROLLBACK.
cf10: 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49 54 41 54 49 4f  .**.** LIMITATIO
cf20: 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 55 31 32 32 33  NS:.**.** {U1223
cf30: 32 7d 20 49 66 20 61 20 73 65 70 61 72 61 74 65  2} If a separate
cf40: 20 74 68 72 65 61 64 20 64 6f 65 73 20 61 20 6e   thread does a n
cf50: 65 77 20 69 6e 73 65 72 74 20 6f 6e 20 74 68 65  ew insert on the
cf60: 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20   same.**        
cf70: 20 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65    database conne
cf80: 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 65 20  ction while the 
cf90: 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e  [sqlite3_last_in
cfa0: 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a  sert_rowid()].**
cfb0: 20 20 20 20 20 20 20 20 20 20 66 75 6e 63 74 69            functi
cfc0: 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e  on is running an
cfd0: 64 20 74 68 75 73 20 63 68 61 6e 67 65 73 20 74  d thus changes t
cfe0: 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20 72  he last insert r
cff0: 6f 77 69 64 2c 0a 2a 2a 20 20 20 20 20 20 20 20  owid,.**        
d000: 20 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65    then the value
d010: 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
d020: 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
d030: 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a  t_rowid()] is.**
d040: 20 20 20 20 20 20 20 20 20 20 75 6e 70 72 65 64            unpred
d050: 69 63 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 68  ictable and migh
d060: 74 20 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 68  t not equal eith
d070: 65 72 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 68  er the old or th
d080: 65 20 6e 65 77 0a 2a 2a 20 20 20 20 20 20 20 20  e new.**        
d090: 20 20 6c 61 73 74 20 69 6e 73 65 72 74 20 72 6f    last insert ro
d0a0: 77 69 64 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f  wid..*/.sqlite3_
d0b0: 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c 61  int64 sqlite3_la
d0c0: 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
d0d0: 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
d0e0: 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75 6e  * CAPI3REF: Coun
d0f0: 74 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 20  t The Number Of 
d100: 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 20 7b 46  Rows Modified {F
d110: 31 32 32 34 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69  12240}.**.** Thi
d120: 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  s function retur
d130: 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
d140: 20 64 61 74 61 62 61 73 65 20 72 6f 77 73 20 74   database rows t
d150: 68 61 74 20 77 65 72 65 20 63 68 61 6e 67 65 64  hat were changed
d160: 0a 2a 2a 20 6f 72 20 69 6e 73 65 72 74 65 64 20  .** or inserted 
d170: 6f 72 20 64 65 6c 65 74 65 64 20 62 79 20 74 68  or deleted by th
d180: 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20  e most recently 
d190: 63 6f 6d 70 6c 65 74 65 64 20 53 51 4c 20 73 74  completed SQL st
d1a0: 61 74 65 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 74 68  atement.** on th
d1b0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 70 65  e connection spe
d1c0: 63 69 66 69 65 64 20 62 79 20 74 68 65 20 66 69  cified by the fi
d1d0: 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20 20  rst parameter.  
d1e0: 4f 6e 6c 79 0a 2a 2a 20 63 68 61 6e 67 65 73 20  Only.** changes 
d1f0: 74 68 61 74 20 61 72 65 20 64 69 72 65 63 74 6c  that are directl
d200: 79 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  y specified by t
d210: 68 65 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  he INSERT, UPDAT
d220: 45 2c 20 6f 72 0a 2a 2a 20 44 45 4c 45 54 45 20  E, or.** DELETE 
d230: 73 74 61 74 65 6d 65 6e 74 20 61 72 65 20 63 6f  statement are co
d240: 75 6e 74 65 64 2e 20 20 41 75 78 69 6c 69 61 72  unted.  Auxiliar
d250: 79 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64  y changes caused
d260: 20 62 79 0a 2a 2a 20 74 72 69 67 67 65 72 73 20   by.** triggers 
d270: 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e  are not counted.
d280: 20 55 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65   Use the [sqlite
d290: 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
d2a0: 29 5d 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74  )] function.** t
d2b0: 6f 20 66 69 6e 64 20 74 68 65 20 74 6f 74 61 6c  o find the total
d2c0: 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 6e 67   number of chang
d2d0: 65 73 20 69 6e 63 6c 75 64 69 6e 67 20 63 68 61  es including cha
d2e0: 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20 74  nges caused by t
d2f0: 72 69 67 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 41  riggers..**.** A
d300: 20 22 72 6f 77 20 63 68 61 6e 67 65 22 20 69 73   "row change" is
d310: 20 61 20 63 68 61 6e 67 65 20 74 6f 20 61 20 73   a change to a s
d320: 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20 61 20 73  ingle row of a s
d330: 69 6e 67 6c 65 20 74 61 62 6c 65 0a 2a 2a 20 63  ingle table.** c
d340: 61 75 73 65 64 20 62 79 20 61 6e 20 49 4e 53 45  aused by an INSE
d350: 52 54 2c 20 44 45 4c 45 54 45 2c 20 6f 72 20 55  RT, DELETE, or U
d360: 50 44 41 54 45 20 73 74 61 74 65 6d 65 6e 74 2e  PDATE statement.
d370: 20 20 52 6f 77 73 20 74 68 61 74 0a 2a 2a 20 61    Rows that.** a
d380: 72 65 20 63 68 61 6e 67 65 64 20 61 73 20 73 69  re changed as si
d390: 64 65 20 65 66 66 65 63 74 73 20 6f 66 20 52 45  de effects of RE
d3a0: 50 4c 41 43 45 20 63 6f 6e 73 74 72 61 69 6e 74  PLACE constraint
d3b0: 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 0a 2a 2a 20   resolution,.** 
d3c0: 72 6f 6c 6c 62 61 63 6b 2c 20 41 42 4f 52 54 20  rollback, ABORT 
d3d0: 70 72 6f 63 65 73 73 69 6e 67 2c 20 44 52 4f 50  processing, DROP
d3e0: 20 54 41 42 4c 45 2c 20 6f 72 20 62 79 20 61 6e   TABLE, or by an
d3f0: 79 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 63 68 61  y other.** mecha
d400: 6e 69 73 6d 73 20 64 6f 20 6e 6f 74 20 63 6f 75  nisms do not cou
d410: 6e 74 20 61 73 20 64 69 72 65 63 74 20 72 6f 77  nt as direct row
d420: 20 63 68 61 6e 67 65 73 2e 0a 2a 2a 0a 2a 2a 20   changes..**.** 
d430: 41 20 22 74 72 69 67 67 65 72 20 63 6f 6e 74 65  A "trigger conte
d440: 78 74 22 20 69 73 20 61 20 73 63 6f 70 65 20 6f  xt" is a scope o
d450: 66 20 65 78 65 63 75 74 69 6f 6e 20 74 68 61 74  f execution that
d460: 20 62 65 67 69 6e 73 20 61 6e 64 0a 2a 2a 20 65   begins and.** e
d470: 6e 64 73 20 77 69 74 68 20 74 68 65 20 73 63 72  nds with the scr
d480: 69 70 74 20 6f 66 20 61 20 74 72 69 67 67 65 72  ipt of a trigger
d490: 2e 20 20 4d 6f 73 74 20 53 51 4c 20 73 74 61 74  .  Most SQL stat
d4a0: 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a 20 65 76  ements are.** ev
d4b0: 61 6c 75 61 74 65 64 20 6f 75 74 73 69 64 65 20  aluated outside 
d4c0: 6f 66 20 61 6e 79 20 74 72 69 67 67 65 72 2e 20  of any trigger. 
d4d0: 20 54 68 69 73 20 69 73 20 74 68 65 20 22 74 6f   This is the "to
d4e0: 70 20 6c 65 76 65 6c 22 0a 2a 2a 20 74 72 69 67  p level".** trig
d4f0: 67 65 72 20 63 6f 6e 74 65 78 74 2e 20 20 49 66  ger context.  If
d500: 20 61 20 74 72 69 67 67 65 72 20 66 69 72 65 73   a trigger fires
d510: 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65   from the top le
d520: 76 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20 74 72  vel, a.** new tr
d530: 69 67 67 65 72 20 63 6f 6e 74 65 78 74 20 69 73  igger context is
d540: 20 65 6e 74 65 72 65 64 20 66 6f 72 20 74 68 65   entered for the
d550: 20 64 75 72 61 74 69 6f 6e 20 6f 66 20 74 68 61   duration of tha
d560: 74 20 6f 6e 65 0a 2a 2a 20 74 72 69 67 67 65 72  t one.** trigger
d570: 2e 20 20 53 75 62 74 72 69 67 67 65 72 73 20 63  .  Subtriggers c
d580: 72 65 61 74 65 20 73 75 62 63 6f 6e 74 65 78 74  reate subcontext
d590: 73 20 66 6f 72 20 74 68 65 69 72 20 64 75 72 61  s for their dura
d5a0: 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c  tion..**.** Call
d5b0: 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  ing [sqlite3_exe
d5c0: 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  c()] or [sqlite3
d5d0: 5f 73 74 65 70 28 29 5d 20 72 65 63 75 72 73 69  _step()] recursi
d5e0: 76 65 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74  vely does.** not
d5f0: 20 63 72 65 61 74 65 20 61 20 6e 65 77 20 74 72   create a new tr
d600: 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a  igger context..*
d610: 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69  *.** This functi
d620: 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  on returns the n
d630: 75 6d 62 65 72 20 6f 66 20 64 69 72 65 63 74 20  umber of direct 
d640: 72 6f 77 20 63 68 61 6e 67 65 73 20 69 6e 20 74  row changes in t
d650: 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e  he.** most recen
d660: 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  t INSERT, UPDATE
d670: 2c 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74  , or DELETE stat
d680: 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65  ement within the
d690: 20 73 61 6d 65 0a 2a 2a 20 74 72 69 67 67 65 72   same.** trigger
d6a0: 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20   context..**.** 
d6b0: 53 6f 20 77 68 65 6e 20 63 61 6c 6c 65 64 20 66  So when called f
d6c0: 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65  rom the top leve
d6d0: 6c 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  l, this function
d6e0: 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20   returns the.** 
d6f0: 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65  number of change
d700: 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65  s in the most re
d710: 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44  cent INSERT, UPD
d720: 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a  ATE, or DELETE.*
d730: 2a 20 74 68 61 74 20 61 6c 73 6f 20 6f 63 63 75  * that also occu
d740: 72 72 65 64 20 61 74 20 74 68 65 20 74 6f 70 20  rred at the top 
d750: 6c 65 76 65 6c 2e 0a 2a 2a 20 57 69 74 68 69 6e  level..** Within
d760: 20 74 68 65 20 62 6f 64 79 20 6f 66 20 61 20 74   the body of a t
d770: 72 69 67 67 65 72 2c 20 74 68 65 20 73 71 6c 69  rigger, the sqli
d780: 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69 6e  te3_changes() in
d790: 74 65 72 66 61 63 65 0a 2a 2a 20 63 61 6e 20 62  terface.** can b
d7a0: 65 20 63 61 6c 6c 65 64 20 74 6f 20 66 69 6e 64  e called to find
d7b0: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
d7c0: 2a 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65  * changes in the
d7d0: 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63   most recently c
d7e0: 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 52 54 2c  ompleted INSERT,
d7f0: 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45   UPDATE, or DELE
d800: 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  TE.** statement 
d810: 77 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20  within the body 
d820: 6f 66 20 74 68 65 20 73 61 6d 65 20 74 72 69 67  of the same trig
d830: 67 65 72 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c  ger..** However,
d840: 20 74 68 65 20 6e 75 6d 62 65 72 20 72 65 74 75   the number retu
d850: 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e  rned does not in
d860: 63 6c 75 64 65 20 69 6e 20 63 68 61 6e 67 65 73  clude in changes
d870: 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20 73 75  .** caused by su
d880: 62 74 72 69 67 67 65 72 73 20 73 69 6e 63 65 20  btriggers since 
d890: 74 68 65 79 20 68 61 76 65 20 74 68 65 69 72 20  they have their 
d8a0: 6f 77 6e 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a  own context..**.
d8b0: 2a 2a 20 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d  ** SQLite implem
d8c0: 65 6e 74 73 20 74 68 65 20 63 6f 6d 6d 61 6e 64  ents the command
d8d0: 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61   "DELETE FROM ta
d8e0: 62 6c 65 22 20 77 69 74 68 6f 75 74 0a 2a 2a 20  ble" without.** 
d8f0: 61 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 62  a WHERE clause b
d900: 79 20 64 72 6f 70 70 69 6e 67 20 61 6e 64 20 72  y dropping and r
d910: 65 63 72 65 61 74 69 6e 67 20 74 68 65 20 74 61  ecreating the ta
d920: 62 6c 65 2e 20 20 28 54 68 69 73 20 69 73 20 6d  ble.  (This is m
d930: 75 63 68 0a 2a 2a 20 66 61 73 74 65 72 20 74 68  uch.** faster th
d940: 61 6e 20 67 6f 69 6e 67 20 74 68 72 6f 75 67 68  an going through
d950: 20 61 6e 64 20 64 65 6c 65 74 69 6e 67 20 69 6e   and deleting in
d960: 64 69 76 69 64 75 61 6c 20 65 6c 65 6d 65 6e 74  dividual element
d970: 73 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 61  s from the.** ta
d980: 62 6c 65 2e 29 20 20 42 65 63 61 75 73 65 20 6f  ble.)  Because o
d990: 66 20 74 68 69 73 20 6f 70 74 69 6d 69 7a 61 74  f this optimizat
d9a0: 69 6f 6e 2c 20 74 68 65 20 64 65 6c 65 74 69 6f  ion, the deletio
d9b0: 6e 73 20 69 6e 0a 2a 2a 20 22 44 45 4c 45 54 45  ns in.** "DELETE
d9c0: 20 46 52 4f 4d 20 74 61 62 6c 65 22 20 61 72 65   FROM table" are
d9d0: 20 6e 6f 74 20 72 6f 77 20 63 68 61 6e 67 65 73   not row changes
d9e0: 20 61 6e 64 20 77 69 6c 6c 20 6e 6f 74 20 62 65   and will not be
d9f0: 20 63 6f 75 6e 74 65 64 0a 2a 2a 20 62 79 20 74   counted.** by t
da00: 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  he sqlite3_chang
da10: 65 73 28 29 20 6f 72 20 5b 73 71 6c 69 74 65 33  es() or [sqlite3
da20: 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
da30: 5d 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 20  ] functions..** 
da40: 54 6f 20 67 65 74 20 61 6e 20 61 63 63 75 72 61  To get an accura
da50: 74 65 20 63 6f 75 6e 74 20 6f 66 20 74 68 65 20  te count of the 
da60: 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 64  number of rows d
da70: 65 6c 65 74 65 64 2c 20 75 73 65 0a 2a 2a 20 22  eleted, use.** "
da80: 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c  DELETE FROM tabl
da90: 65 20 57 48 45 52 45 20 31 22 20 69 6e 73 74 65  e WHERE 1" inste
daa0: 61 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  ad..**.** INVARI
dab0: 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  ANTS:.**.** {F12
dac0: 32 34 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  241} The [sqlite
dad0: 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 66 75 6e  3_changes()] fun
dae0: 63 74 69 6f 6e 20 73 68 61 6c 6c 20 72 65 74 75  ction shall retu
daf0: 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  rn the number of
db00: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 6f 77  .**          row
db10: 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20   changes caused 
db20: 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  by the most rece
db30: 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  nt INSERT, UPDAT
db40: 45 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  E,.**          o
db50: 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65  r DELETE stateme
db60: 6e 74 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64  nt on the same d
db70: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
db80: 6f 6e 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20  on and.**       
db90: 20 20 20 77 69 74 68 69 6e 20 74 68 65 20 73 61     within the sa
dba0: 6d 65 20 6f 72 20 68 69 67 68 65 72 20 74 72 69  me or higher tri
dbb0: 67 67 65 72 20 63 6f 6e 74 65 78 74 2c 20 6f 72  gger context, or
dbc0: 20 7a 65 72 6f 20 69 66 20 74 68 65 72 65 20 68   zero if there h
dbd0: 61 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ave.**          
dbe0: 6e 6f 74 20 62 65 65 6e 20 61 6e 79 20 71 75 61  not been any qua
dbf0: 6c 69 66 79 69 6e 67 20 72 6f 77 20 63 68 61 6e  lifying row chan
dc00: 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32  ges..**.** {F122
dc10: 34 33 7d 20 53 74 61 74 65 6d 65 6e 74 73 20 6f  43} Statements o
dc20: 66 20 74 68 65 20 66 6f 72 6d 20 22 44 45 4c 45  f the form "DELE
dc30: 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 6e 61 6d  TE FROM tablenam
dc40: 65 22 20 77 69 74 68 20 6e 6f 0a 2a 2a 20 20 20  e" with no.**   
dc50: 20 20 20 20 20 20 20 57 48 45 52 45 20 63 6c 61         WHERE cla
dc60: 75 73 65 20 73 68 61 6c 6c 20 63 61 75 73 65 20  use shall cause 
dc70: 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
dc80: 20 74 6f 20 0a 2a 2a 20 20 20 20 20 20 20 20 20   to .**         
dc90: 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65   [sqlite3_change
dca0: 73 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 20 7a  s()] to return z
dcb0: 65 72 6f 2c 20 72 65 67 61 72 64 6c 65 73 73 20  ero, regardless 
dcc0: 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  of the.**       
dcd0: 20 20 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77     number of row
dce0: 73 20 6f 72 69 67 69 6e 61 6c 6c 79 20 69 6e 20  s originally in 
dcf0: 74 68 65 20 74 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a  the table..**.**
dd00: 20 4c 49 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a   LIMITATIONS:.**
dd10: 0a 2a 2a 20 7b 55 31 32 32 35 32 7d 20 49 66 20  .** {U12252} If 
dd20: 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  a separate threa
dd30: 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20  d makes changes 
dd40: 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  on the same data
dd50: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
dd60: 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68 69 6c  **          whil
dd70: 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  e [sqlite3_chang
dd80: 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67  es()] is running
dd90: 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20   then the value 
dda0: 72 65 74 75 72 6e 65 64 0a 2a 2a 20 20 20 20 20  returned.**     
ddb0: 20 20 20 20 20 69 73 20 75 6e 70 72 65 64 69 63       is unpredic
ddc0: 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65  table and not me
ddd0: 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74  aningful..*/.int
dde0: 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
ddf0: 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
de00: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74  ** CAPI3REF: Tot
de10: 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77  al Number Of Row
de20: 73 20 4d 6f 64 69 66 69 65 64 20 7b 46 31 32 32  s Modified {F122
de30: 36 30 7d 0a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20  60}.***.** This 
de40: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
de50: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72   the number of r
de60: 6f 77 20 63 68 61 6e 67 65 73 20 63 61 75 73 65  ow changes cause
de70: 64 0a 2a 2a 20 62 79 20 49 4e 53 45 52 54 2c 20  d.** by INSERT, 
de80: 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45  UPDATE or DELETE
de90: 20 73 74 61 74 65 6d 65 6e 74 73 20 73 69 6e 63   statements sinc
dea0: 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 68  e the database h
deb0: 61 6e 64 6c 65 0a 2a 2a 20 77 61 73 20 6f 70 65  andle.** was ope
dec0: 6e 65 64 2e 20 20 54 68 65 20 63 6f 75 6e 74 20  ned.  The count 
ded0: 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 63 68 61  includes all cha
dee0: 6e 67 65 73 20 66 72 6f 6d 20 61 6c 6c 20 74 72  nges from all tr
def0: 69 67 67 65 72 0a 2a 2a 20 63 6f 6e 74 65 78 74  igger.** context
df00: 73 2e 20 20 42 75 74 20 74 68 65 20 63 6f 75 6e  s.  But the coun
df10: 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75  t does not inclu
df20: 64 65 20 63 68 61 6e 67 65 73 20 75 73 65 64 20  de changes used 
df30: 74 6f 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20  to.** implement 
df40: 52 45 50 4c 41 43 45 20 63 6f 6e 73 74 72 61 69  REPLACE constrai
df50: 6e 74 73 2c 20 64 6f 20 72 6f 6c 6c 62 61 63 6b  nts, do rollback
df60: 73 20 6f 72 20 41 42 4f 52 54 20 70 72 6f 63 65  s or ABORT proce
df70: 73 73 69 6e 67 2c 0a 2a 2a 20 6f 72 20 44 52 4f  ssing,.** or DRO
df80: 50 20 74 61 62 6c 65 20 70 72 6f 63 65 73 73 69  P table processi
df90: 6e 67 2e 0a 2a 2a 20 54 68 65 20 63 68 61 6e 67  ng..** The chang
dfa0: 65 73 0a 2a 2a 20 61 72 65 20 63 6f 75 6e 74 65  es.** are counte
dfb0: 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65  d as soon as the
dfc0: 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20   statement that 
dfd0: 6d 61 6b 65 73 20 74 68 65 6d 20 69 73 20 63 6f  makes them is co
dfe0: 6d 70 6c 65 74 65 64 20 0a 2a 2a 20 28 77 68 65  mpleted .** (whe
dff0: 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  n the statement 
e000: 68 61 6e 64 6c 65 20 69 73 20 70 61 73 73 65 64  handle is passed
e010: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
e020: 65 74 28 29 5d 20 6f 72 20 0a 2a 2a 20 5b 73 71  et()] or .** [sq
e030: 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
e040: 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  ])..**.** SQLite
e050: 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20   implements the 
e060: 63 6f 6d 6d 61 6e 64 20 22 44 45 4c 45 54 45 20  command "DELETE 
e070: 46 52 4f 4d 20 74 61 62 6c 65 22 20 77 69 74 68  FROM table" with
e080: 6f 75 74 0a 2a 2a 20 61 20 57 48 45 52 45 20 63  out.** a WHERE c
e090: 6c 61 75 73 65 20 62 79 20 64 72 6f 70 70 69 6e  lause by droppin
e0a0: 67 20 61 6e 64 20 72 65 63 72 65 61 74 69 6e 67  g and recreating
e0b0: 20 74 68 65 20 74 61 62 6c 65 2e 20 20 28 54 68   the table.  (Th
e0c0: 69 73 20 69 73 20 6d 75 63 68 0a 2a 2a 20 66 61  is is much.** fa
e0d0: 73 74 65 72 20 74 68 61 6e 20 67 6f 69 6e 67 0a  ster than going.
e0e0: 2a 2a 20 74 68 72 6f 75 67 68 20 61 6e 64 20 64  ** through and d
e0f0: 65 6c 65 74 69 6e 67 20 69 6e 64 69 76 69 64 75  eleting individu
e100: 61 6c 20 65 6c 65 6d 65 6e 74 73 20 66 72 6f 6d  al elements from
e110: 20 74 68 65 20 74 61 62 6c 65 2e 29 20 20 42 65   the table.)  Be
e120: 63 61 75 73 65 20 6f 66 0a 2a 2a 20 74 68 69 73  cause of.** this
e130: 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 2c 20 74   optimization, t
e140: 68 65 20 63 68 61 6e 67 65 20 63 6f 75 6e 74 20  he change count 
e150: 66 6f 72 20 22 44 45 4c 45 54 45 20 46 52 4f 4d  for "DELETE FROM
e160: 20 74 61 62 6c 65 22 20 77 69 6c 6c 20 62 65 0a   table" will be.
e170: 2a 2a 20 7a 65 72 6f 20 72 65 67 61 72 64 6c 65  ** zero regardle
e180: 73 73 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72  ss of the number
e190: 20 6f 66 20 65 6c 65 6d 65 6e 74 73 20 74 68 61   of elements tha
e1a0: 74 20 77 65 72 65 20 6f 72 69 67 69 6e 61 6c 6c  t were originall
e1b0: 79 20 69 6e 20 74 68 65 0a 2a 2a 20 74 61 62 6c  y in the.** tabl
e1c0: 65 2e 20 54 6f 20 67 65 74 20 61 6e 20 61 63 63  e. To get an acc
e1d0: 75 72 61 74 65 20 63 6f 75 6e 74 20 6f 66 20 74  urate count of t
e1e0: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77  he number of row
e1f0: 73 20 64 65 6c 65 74 65 64 2c 20 75 73 65 0a 2a  s deleted, use.*
e200: 2a 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74  * "DELETE FROM t
e210: 61 62 6c 65 20 57 48 45 52 45 20 31 22 20 69 6e  able WHERE 1" in
e220: 73 74 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  stead..**.** See
e230: 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74   also the [sqlit
e240: 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e  e3_changes()] in
e250: 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49  terface..**.** I
e260: 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 20 0a 2a  NVARIANTS:.** .*
e270: 2a 20 7b 46 31 32 32 36 31 7d 20 54 68 65 20 5b  * {F12261} The [
e280: 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
e290: 61 6e 67 65 73 28 29 5d 20 72 65 74 75 72 6e 73  anges()] returns
e2a0: 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65   the total numbe
e2b0: 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66  r.**          of
e2c0: 20 72 6f 77 20 63 68 61 6e 67 65 73 20 63 61 75   row changes cau
e2d0: 73 65 64 20 62 79 20 49 4e 53 45 52 54 2c 20 55  sed by INSERT, U
e2e0: 50 44 41 54 45 2c 20 61 6e 64 2f 6f 72 20 44 45  PDATE, and/or DE
e2f0: 4c 45 54 45 0a 2a 2a 20 20 20 20 20 20 20 20 20  LETE.**         
e300: 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 74   statements on t
e310: 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73  he same [databas
e320: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 69  e connection], i
e330: 6e 20 61 6e 79 0a 2a 2a 20 20 20 20 20 20 20 20  n any.**        
e340: 20 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78    trigger contex
e350: 74 2c 20 73 69 6e 63 65 20 74 68 65 20 64 61 74  t, since the dat
e360: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
e370: 20 77 61 73 0a 2a 2a 20 20 20 20 20 20 20 20 20   was.**         
e380: 20 63 72 65 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20   created..**.** 
e390: 7b 46 31 32 32 36 33 7d 20 53 74 61 74 65 6d 65  {F12263} Stateme
e3a0: 6e 74 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20  nts of the form 
e3b0: 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62  "DELETE FROM tab
e3c0: 6c 65 6e 61 6d 65 22 20 77 69 74 68 20 6e 6f 0a  lename" with no.
e3d0: 2a 2a 20 20 20 20 20 20 20 20 20 20 57 48 45 52  **          WHER
e3e0: 45 20 63 6c 61 75 73 65 20 73 68 61 6c 6c 20 6e  E clause shall n
e3f0: 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61  ot change the va
e400: 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  lue returned.** 
e410: 20 20 20 20 20 20 20 20 20 62 79 20 5b 73 71 6c           by [sql
e420: 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
e430: 65 73 28 29 5d 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49  es()].**.** LIMI
e440: 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b  TATIONS:.**.** {
e450: 55 31 32 32 36 34 7d 20 49 66 20 61 20 73 65 70  U12264} If a sep
e460: 61 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b  arate thread mak
e470: 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68  es changes on th
e480: 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
e490: 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20  connection.**   
e4a0: 20 20 20 20 20 20 20 77 68 69 6c 65 20 5b 73 71         while [sq
e4b0: 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
e4c0: 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e  ges()] is runnin
e4d0: 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65  g then the value
e4e0: 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65   .**          re
e4f0: 74 75 72 6e 65 64 20 69 73 20 75 6e 70 72 65 64  turned is unpred
e500: 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20  ictable and not 
e510: 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69  meaningful..*/.i
e520: 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  nt sqlite3_total
e530: 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33  _changes(sqlite3
e540: 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
e550: 52 45 46 3a 20 49 6e 74 65 72 72 75 70 74 20 41  REF: Interrupt A
e560: 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75   Long-Running Qu
e570: 65 72 79 20 7b 46 31 32 32 37 30 7d 0a 2a 2a 0a  ery {F12270}.**.
e580: 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  ** This function
e590: 20 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e 64   causes any pend
e5a0: 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70 65  ing database ope
e5b0: 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20  ration to abort 
e5c0: 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74  and.** return at
e5d0: 20 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f 70   its earliest op
e5e0: 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73 20  portunity. This 
e5f0: 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69 63  routine is typic
e600: 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69  ally.** called i
e610: 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 20  n response to a 
e620: 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63 68  user action such
e630: 20 61 73 20 70 72 65 73 73 69 6e 67 20 22 43 61   as pressing "Ca
e640: 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c  ncel".** or Ctrl
e650: 2d 43 20 77 68 65 72 65 20 74 68 65 20 75 73 65  -C where the use
e660: 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71  r wants a long q
e670: 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 74  uery operation t
e680: 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69  o halt.** immedi
e690: 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20  ately..**.** It 
e6a0: 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20  is safe to call 
e6b0: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66 72 6f  this routine fro
e6c0: 6d 20 61 20 74 68 72 65 61 64 20 64 69 66 66 65  m a thread diffe
e6d0: 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a  rent from the.**
e6e0: 20 74 68 72 65 61 64 20 74 68 61 74 20 69 73 20   thread that is 
e6f0: 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e  currently runnin
e700: 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f  g the database o
e710: 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 20 69  peration.  But i
e720: 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66 65  t.** is not safe
e730: 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f   to call this ro
e740: 75 74 69 6e 65 20 77 69 74 68 20 61 20 64 61 74  utine with a dat
e750: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
e760: 20 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73   that.** is clos
e770: 65 64 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73  ed or might clos
e780: 65 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33  e before sqlite3
e790: 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72 65 74  _interrupt() ret
e7a0: 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  urns..**.** If a
e7b0: 6e 20 53 51 4c 20 69 73 20 76 65 72 79 20 6e 65  n SQL is very ne
e7c0: 61 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74  arly finished at
e7d0: 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e 20 73   the time when s
e7e0: 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
e7f0: 28 29 0a 2a 2a 20 69 73 20 63 61 6c 6c 65 64 2c  ().** is called,
e800: 20 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e   then it might n
e810: 6f 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72  ot have an oppor
e820: 74 75 6e 69 74 79 20 74 6f 20 62 65 20 69 6e 74  tunity to be int
e830: 65 72 72 75 70 74 65 64 2e 0a 2a 2a 20 49 74 20  errupted..** It 
e840: 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74  might continue t
e850: 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a  o completion..**
e860: 20 41 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f   An SQL operatio
e870: 6e 20 74 68 61 74 20 69 73 20 69 6e 74 65 72 72  n that is interr
e880: 75 70 74 65 64 20 77 69 6c 6c 20 72 65 74 75 72  upted will retur
e890: 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54  n.** [SQLITE_INT
e8a0: 45 52 52 55 50 54 5d 2e 20 20 49 66 20 74 68 65  ERRUPT].  If the
e8b0: 20 69 6e 74 65 72 72 75 70 74 65 64 20 53 51 4c   interrupted SQL
e8c0: 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e   operation is an
e8d0: 0a 2a 2a 20 49 4e 53 45 52 54 2c 20 55 50 44 41  .** INSERT, UPDA
e8e0: 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 20 74 68  TE, or DELETE th
e8f0: 61 74 20 69 73 20 69 6e 73 69 64 65 20 61 6e 20  at is inside an 
e900: 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63  explicit transac
e910: 74 69 6f 6e 2c 20 0a 2a 2a 20 74 68 65 6e 20 74  tion, .** then t
e920: 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61  he entire transa
e930: 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 72 6f  ction will be ro
e940: 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61  lled back automa
e950: 74 69 63 61 6c 6c 79 2e 0a 2a 2a 20 41 20 63 61  tically..** A ca
e960: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e  ll to sqlite3_in
e970: 74 65 72 72 75 70 74 28 29 20 68 61 73 20 6e 6f  terrupt() has no
e980: 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20 73   effect on SQL s
e990: 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61  tatements.** tha
e9a0: 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66  t are started af
e9b0: 74 65 72 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  ter sqlite3_inte
e9c0: 72 72 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e  rrupt() returns.
e9d0: 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
e9e0: 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 37 31  S:.**.** {F12271
e9f0: 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 69  } The [sqlite3_i
ea00: 6e 74 65 72 72 75 70 74 28 29 5d 20 69 6e 74 65  nterrupt()] inte
ea10: 72 66 61 63 65 20 77 69 6c 6c 20 66 6f 72 63 65  rface will force
ea20: 20 61 6c 6c 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20   all running.** 
ea30: 20 20 20 20 20 20 20 20 20 53 51 4c 20 73 74 61           SQL sta
ea40: 74 65 6d 65 6e 74 73 20 61 73 73 6f 63 69 61 74  tements associat
ea50: 65 64 20 77 69 74 68 20 74 68 65 20 73 61 6d 65  ed with the same
ea60: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
ea70: 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  tion.**         
ea80: 20 74 6f 20 68 61 6c 74 20 61 66 74 65 72 20 70   to halt after p
ea90: 72 6f 63 65 73 73 69 6e 67 20 61 74 20 6d 6f 73  rocessing at mos
eaa0: 74 20 6f 6e 65 20 61 64 64 69 74 69 6f 6e 61 6c  t one additional
eab0: 20 72 6f 77 20 6f 66 0a 2a 2a 20 20 20 20 20 20   row of.**      
eac0: 20 20 20 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20      data..**.** 
ead0: 7b 46 31 32 32 37 32 7d 20 41 6e 79 20 53 51 4c  {F12272} Any SQL
eae0: 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20   statement that 
eaf0: 69 73 20 69 6e 74 65 72 72 75 70 74 65 64 20 62  is interrupted b
eb00: 79 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  y [sqlite3_inter
eb10: 72 75 70 74 28 29 5d 0a 2a 2a 20 20 20 20 20 20  rupt()].**      
eb20: 20 20 20 20 77 69 6c 6c 20 72 65 74 75 72 6e 20      will return 
eb30: 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50  [SQLITE_INTERRUP
eb40: 54 5d 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49 54 41  T]..**.** LIMITA
eb50: 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 55 31  TIONS:.**.** {U1
eb60: 32 32 37 39 7d 20 49 66 20 74 68 65 20 64 61 74  2279} If the dat
eb70: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
eb80: 20 63 6c 6f 73 65 73 20 77 68 69 6c 65 20 5b 73   closes while [s
eb90: 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
eba0: 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ()].**          
ebb0: 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20  is running then 
ebc0: 62 61 64 20 74 68 69 6e 67 73 20 77 69 6c 6c 20  bad things will 
ebd0: 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a  likely happen..*
ebe0: 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 69  /.void sqlite3_i
ebf0: 6e 74 65 72 72 75 70 74 28 73 71 6c 69 74 65 33  nterrupt(sqlite3
ec00: 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
ec10: 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49  REF: Determine I
ec20: 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65  f An SQL Stateme
ec30: 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 65 20 7b  nt Is Complete {
ec40: 46 31 30 35 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 68  F10510}.**.** Th
ec50: 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
ec60: 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6d 6d   useful for comm
ec70: 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74  and-line input t
ec80: 6f 20 64 65 74 65 72 6d 69 6e 65 20 69 66 20 74  o determine if t
ec90: 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20  he.** currently 
eca0: 65 6e 74 65 72 65 64 20 74 65 78 74 20 73 65 65  entered text see
ecb0: 6d 73 20 74 6f 20 66 6f 72 6d 20 63 6f 6d 70 6c  ms to form compl
ecc0: 65 74 65 20 61 20 53 51 4c 20 73 74 61 74 65 6d  ete a SQL statem
ecd0: 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64  ent or.** if add
ece0: 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73  itional input is
ecf0: 20 6e 65 65 64 65 64 20 62 65 66 6f 72 65 20 73   needed before s
ed00: 65 6e 64 69 6e 67 20 74 68 65 20 74 65 78 74 20  ending the text 
ed10: 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66  into.** SQLite f
ed20: 6f 72 20 70 61 72 73 69 6e 67 2e 20 20 54 68 65  or parsing.  The
ed30: 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
ed40: 72 6e 20 74 72 75 65 20 69 66 20 74 68 65 20 69  rn true if the i
ed50: 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61  nput string.** a
ed60: 70 70 65 61 72 73 20 74 6f 20 62 65 20 61 20 63  ppears to be a c
ed70: 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74  omplete SQL stat
ed80: 65 6d 65 6e 74 2e 20 20 41 20 73 74 61 74 65 6d  ement.  A statem
ed90: 65 6e 74 20 69 73 20 6a 75 64 67 65 64 20 74 6f  ent is judged to
eda0: 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20   be.** complete 
edb0: 69 66 20 69 74 20 65 6e 64 73 20 77 69 74 68 20  if it ends with 
edc0: 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65  a semicolon toke
edd0: 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 66  n and is not a f
ede0: 72 61 67 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a 20  ragment of a.** 
edf0: 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 73  CREATE TRIGGER s
ee00: 74 61 74 65 6d 65 6e 74 2e 20 20 53 65 6d 69 63  tatement.  Semic
ee10: 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20 65  olons that are e
ee20: 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a 2a  mbedded within.*
ee30: 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c  * string literal
ee40: 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65 6e  s or quoted iden
ee50: 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72 20  tifier names or 
ee60: 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74  comments are not
ee70: 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74 20  .** independent 
ee80: 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72 65  tokens (they are
ee90: 20 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f 6b   part of the tok
eea0: 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65 79  en in which they
eeb0: 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64   are.** embedded
eec0: 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f  ) and thus do no
eed0: 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74 61  t count as a sta
eee0: 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f  tement terminato
eef0: 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  r..**.** These r
ef00: 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70  outines do not p
ef10: 61 72 73 65 20 74 68 65 20 53 51 4c 20 61 6e 64  arse the SQL and
ef20: 0a 2a 2a 20 73 6f 20 77 69 6c 6c 20 6e 6f 74 20  .** so will not 
ef30: 64 65 74 65 63 74 20 73 79 6e 74 61 63 74 69 63  detect syntactic
ef40: 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63 74 20 53  ally incorrect S
ef50: 51 4c 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  QL..**.** INVARI
ef60: 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 30  ANTS:.**.** {F10
ef70: 35 31 31 7d 20 54 68 65 20 73 71 6c 69 74 65 33  511} The sqlite3
ef80: 5f 63 6f 6d 70 6c 65 74 65 28 29 20 61 6e 64 20  _complete() and 
ef90: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
efa0: 31 36 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a  16() functions.*
efb0: 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72  *          retur
efc0: 6e 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f  n true (non-zero
efd0: 29 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66  ) if and only if
efe0: 20 74 68 65 20 6c 61 73 74 0a 2a 2a 20 20 20 20   the last.**    
eff0: 20 20 20 20 20 20 6e 6f 6e 2d 77 68 69 74 65 73        non-whites
f000: 70 61 63 65 20 74 6f 6b 65 6e 20 69 6e 20 74 68  pace token in th
f010: 65 69 72 20 69 6e 70 75 74 20 69 73 20 61 20 73  eir input is a s
f020: 65 6d 69 63 6f 6c 6f 6e 20 74 68 61 74 0a 2a 2a  emicolon that.**
f030: 20 20 20 20 20 20 20 20 20 20 69 73 20 6e 6f 74            is not
f040: 20 69 6e 20 62 65 74 77 65 65 6e 20 74 68 65 20   in between the 
f050: 42 45 47 49 4e 20 61 6e 64 20 45 4e 44 20 6f 66  BEGIN and END of
f060: 20 61 20 43 52 45 41 54 45 20 54 52 49 47 47 45   a CREATE TRIGGE
f070: 52 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74  R.**          st
f080: 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 4c  atement..**.** L
f090: 49 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a  IMITATIONS:.**.*
f0a0: 2a 20 7b 55 31 30 35 31 32 7d 20 54 68 65 20 69  * {U10512} The i
f0b0: 6e 70 75 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  nput to sqlite3_
f0c0: 63 6f 6d 70 6c 65 74 65 28 29 20 6d 75 73 74 20  complete() must 
f0d0: 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  be a zero-termin
f0e0: 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  ated.**         
f0f0: 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a   UTF-8 string..*
f100: 2a 0a 2a 2a 20 7b 55 31 30 35 31 33 7d 20 54 68  *.** {U10513} Th
f110: 65 20 69 6e 70 75 74 20 74 6f 20 73 71 6c 69 74  e input to sqlit
f120: 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20  e3_complete16() 
f130: 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74  must be a zero-t
f140: 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 20 20 20  erminated.**    
f150: 20 20 20 20 20 20 55 54 46 2d 31 36 20 73 74 72        UTF-16 str
f160: 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79  ing in native by
f170: 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74  te order..*/.int
f180: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
f190: 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  e(const char *sq
f1a0: 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
f1b0: 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74  complete16(const
f1c0: 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a   void *sql);../*
f1d0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
f1e0: 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63  gister A Callbac
f1f0: 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49  k To Handle SQLI
f200: 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73 20 7b  TE_BUSY Errors {
f210: 46 31 32 33 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 68  F12310}.**.** Th
f220: 69 73 20 72 6f 75 74 69 6e 65 20 69 64 65 6e 74  is routine ident
f230: 69 66 69 65 73 20 61 20 63 61 6c 6c 62 61 63 6b  ifies a callback
f240: 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 6d   function that m
f250: 69 67 68 74 20 62 65 0a 2a 2a 20 69 6e 76 6f 6b  ight be.** invok
f260: 65 64 20 77 68 65 6e 65 76 65 72 20 61 6e 20 61  ed whenever an a
f270: 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74  ttempt is made t
f280: 6f 20 6f 70 65 6e 20 61 20 64 61 74 61 62 61 73  o open a databas
f290: 65 20 74 61 62 6c 65 20 0a 2a 2a 20 74 68 61 74  e table .** that
f2a0: 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20   another thread 
f2b0: 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73 20 6c  or process has l
f2c0: 6f 63 6b 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65  ocked..** If the
f2d0: 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69   busy callback i
f2e0: 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51  s NULL, then [SQ
f2f0: 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 6f 72  LITE_BUSY].** or
f300: 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42   [SQLITE_IOERR_B
f310: 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69 73 20 72 65  LOCKED].** is re
f320: 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65  turned immediate
f330: 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65  ly upon encounte
f340: 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a  ring the lock..*
f350: 2a 20 49 66 20 74 68 65 20 62 75 73 79 20 63 61  * If the busy ca
f360: 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20 4e 55  llback is not NU
f370: 4c 4c 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20  LL, then the.** 
f380: 63 61 6c 6c 62 61 63 6b 20 77 69 6c 6c 20 62 65  callback will be
f390: 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 77   invoked with tw
f3a0: 6f 20 61 72 67 75 6d 65 6e 74 73 2e 20 20 54 68  o arguments.  Th
f3b0: 65 0a 2a 2a 20 66 69 72 73 74 20 61 72 67 75 6d  e.** first argum
f3c0: 65 6e 74 20 74 6f 20 74 68 65 20 68 61 6e 64 6c  ent to the handl
f3d0: 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  er is a copy of 
f3e0: 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65  the void* pointe
f3f0: 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68  r which.** is th
f400: 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
f410: 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65   to this routine
f420: 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72  .  The second ar
f430: 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65  gument to.** the
f440: 20 68 61 6e 64 6c 65 72 20 69 73 20 74 68 65 20   handler is the 
f450: 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20  number of times 
f460: 74 68 61 74 20 74 68 65 20 62 75 73 79 20 68 61  that the busy ha
f470: 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65 65  ndler has.** bee
f480: 6e 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68  n invoked for th
f490: 69 73 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74  is locking event
f4a0: 2e 20 20 20 49 66 20 74 68 65 0a 2a 2a 20 62 75  .   If the.** bu
f4b0: 73 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  sy callback retu
f4c0: 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61  rns 0, then no a
f4d0: 64 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70  dditional attemp
f4e0: 74 73 20 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a  ts are made to.*
f4f0: 2a 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74  * access the dat
f500: 61 62 61 73 65 20 61 6e 64 20 5b 53 51 4c 49 54  abase and [SQLIT
f510: 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49  E_BUSY] or [SQLI
f520: 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
f530: 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  ] is returned..*
f540: 2a 20 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63  * If the callbac
f550: 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  k returns non-ze
f560: 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65 72  ro, then another
f570: 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d   attempt.** is m
f580: 61 64 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20  ade to open the 
f590: 64 61 74 61 62 61 73 65 20 66 6f 72 20 72 65 61  database for rea
f5a0: 64 69 6e 67 20 61 6e 64 20 74 68 65 20 63 79 63  ding and the cyc
f5b0: 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a  le repeats..**.*
f5c0: 2a 20 54 68 65 20 70 72 65 73 65 6e 63 65 20 6f  * The presence o
f5d0: 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72  f a busy handler
f5e0: 20 64 6f 65 73 20 6e 6f 74 20 67 75 61 72 61 6e   does not guaran
f5f0: 74 65 65 20 74 68 61 74 0a 2a 2a 20 69 74 20 77  tee that.** it w
f600: 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 20 77  ill be invoked w
f610: 68 65 6e 20 74 68 65 72 65 20 69 73 20 6c 6f 63  hen there is loc
f620: 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 0a 2a 2a  k contention..**
f630: 20 49 66 20 53 51 4c 69 74 65 20 64 65 74 65 72   If SQLite deter
f640: 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76 6f 6b  mines that invok
f650: 69 6e 67 20 74 68 65 20 62 75 73 79 20 68 61 6e  ing the busy han
f660: 64 6c 65 72 20 63 6f 75 6c 64 20 72 65 73 75 6c  dler could resul
f670: 74 20 69 6e 0a 2a 2a 20 61 20 64 65 61 64 6c 6f  t in.** a deadlo
f680: 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20 61  ck, it will go a
f690: 68 65 61 64 20 61 6e 64 20 72 65 74 75 72 6e 20  head and return 
f6a0: 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72  [SQLITE_BUSY] or
f6b0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52  .** [SQLITE_IOER
f6c0: 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e 73 74 65  R_BLOCKED] inste
f6d0: 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74  ad of invoking t
f6e0: 68 65 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64 6c  he.** busy handl
f6f0: 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20  er..** Consider 
f700: 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65  a scenario where
f710: 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20   one process is 
f720: 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c  holding a read l
f730: 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69  ock that.** it i
f740: 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d  s trying to prom
f750: 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72 76 65  ote to a reserve
f760: 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20  d lock and.** a 
f770: 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69  second process i
f780: 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65  s holding a rese
f790: 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69  rved lock that i
f7a0: 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74  t is trying.** t
f7b0: 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20  o promote to an 
f7c0: 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20  exclusive lock. 
f7d0: 20 54 68 65 20 66 69 72 73 74 20 70 72 6f 63 65   The first proce
f7e0: 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65  ss cannot procee
f7f0: 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20  d.** because it 
f800: 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68  is blocked by th
f810: 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65  e second and the
f820: 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20   second process 
f830: 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65  cannot.** procee
f840: 64 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20  d because it is 
f850: 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66  blocked by the f
f860: 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70  irst.  If both p
f870: 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f  rocesses.** invo
f880: 6b 65 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ke the busy hand
f890: 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69  lers, neither wi
f8a0: 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67  ll make any prog
f8b0: 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65  ress.  Therefore
f8c0: 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75  ,.** SQLite retu
f8d0: 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  rns [SQLITE_BUSY
f8e0: 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20  ] for the first 
f8f0: 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20  process, hoping 
f900: 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c  that this.** wil
f910: 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66 69 72  l induce the fir
f920: 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65  st process to re
f930: 6c 65 61 73 65 20 69 74 73 20 72 65 61 64 20 6c  lease its read l
f940: 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a  ock and allow.**
f950: 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63   the second proc
f960: 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a  ess to proceed..
f970: 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c  **.** The defaul
f980: 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  t busy callback 
f990: 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54  is NULL..**.** T
f9a0: 68 65 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  he [SQLITE_BUSY]
f9b0: 20 65 72 72 6f 72 20 69 73 20 63 6f 6e 76 65 72   error is conver
f9c0: 74 65 64 20 74 6f 20 5b 53 51 4c 49 54 45 5f 49  ted to [SQLITE_I
f9d0: 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a  OERR_BLOCKED].**
f9e0: 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20   when SQLite is 
f9f0: 69 6e 20 74 68 65 20 6d 69 64 64 6c 65 20 6f 66  in the middle of
fa00: 20 61 20 6c 61 72 67 65 20 74 72 61 6e 73 61 63   a large transac
fa10: 74 69 6f 6e 20 77 68 65 72 65 20 61 6c 6c 20 74  tion where all t
fa20: 68 65 0a 2a 2a 20 63 68 61 6e 67 65 73 20 77 69  he.** changes wi
fa30: 6c 6c 20 6e 6f 74 20 66 69 74 20 69 6e 74 6f 20  ll not fit into 
fa40: 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 20 63 61  the in-memory ca
fa50: 63 68 65 2e 20 20 53 51 4c 69 74 65 20 77 69 6c  che.  SQLite wil
fa60: 6c 0a 2a 2a 20 61 6c 72 65 61 64 79 20 68 6f 6c  l.** already hol
fa70: 64 20 61 20 52 45 53 45 52 56 45 44 20 6c 6f 63  d a RESERVED loc
fa80: 6b 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73  k on the databas
fa90: 65 20 66 69 6c 65 2c 20 62 75 74 20 69 74 20 6e  e file, but it n
faa0: 65 65 64 73 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f  eeds.** to promo
fab0: 74 65 20 74 68 69 73 20 6c 6f 63 6b 20 74 6f 20  te this lock to 
fac0: 45 58 43 4c 55 53 49 56 45 20 73 6f 20 74 68 61  EXCLUSIVE so tha
fad0: 74 20 69 74 20 63 61 6e 20 73 70 69 6c 6c 20 63  t it can spill c
fae0: 61 63 68 65 0a 2a 2a 20 70 61 67 65 73 20 69 6e  ache.** pages in
faf0: 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20  to the database 
fb00: 66 69 6c 65 20 77 69 74 68 6f 75 74 20 68 61 72  file without har
fb10: 6d 20 74 6f 20 63 6f 6e 63 75 72 72 65 6e 74 0a  m to concurrent.
fb20: 2a 2a 20 72 65 61 64 65 72 73 2e 20 20 49 66 20  ** readers.  If 
fb30: 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  it is unable to 
fb40: 70 72 6f 6d 6f 74 65 20 74 68 65 20 6c 6f 63 6b  promote the lock
fb50: 2c 20 74 68 65 6e 20 74 68 65 20 69 6e 2d 6d 65  , then the in-me
fb60: 6d 6f 72 79 0a 2a 2a 20 63 61 63 68 65 20 77 69  mory.** cache wi
fb70: 6c 6c 20 62 65 20 6c 65 66 74 20 69 6e 20 61 6e  ll be left in an
fb80: 20 69 6e 63 6f 6e 73 69 73 74 65 6e 74 20 73 74   inconsistent st
fb90: 61 74 65 20 61 6e 64 20 73 6f 20 74 68 65 20 65  ate and so the e
fba0: 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 69 73 20  rror.** code is 
fbb0: 70 72 6f 6d 6f 74 65 64 20 66 72 6f 6d 20 74 68  promoted from th
fbc0: 65 20 72 65 6c 61 74 69 76 65 6c 79 20 62 65 6e  e relatively ben
fbd0: 69 67 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  ign [SQLITE_BUSY
fbe0: 5d 20 74 6f 0a 2a 2a 20 74 68 65 20 6d 6f 72 65  ] to.** the more
fbf0: 20 73 65 76 65 72 65 20 5b 53 51 4c 49 54 45 5f   severe [SQLITE_
fc00: 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 20  IOERR_BLOCKED]. 
fc10: 20 54 68 69 73 20 65 72 72 6f 72 20 63 6f 64 65   This error code
fc20: 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 6f   promotion.** fo
fc30: 72 63 65 73 20 61 6e 20 61 75 74 6f 6d 61 74 69  rces an automati
fc40: 63 20 72 6f 6c 6c 62 61 63 6b 20 6f 66 20 74 68  c rollback of th
fc50: 65 20 63 68 61 6e 67 65 73 2e 20 20 53 65 65 20  e changes.  See 
fc60: 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22  the.** <a href="
fc70: 68 74 74 70 3a 2f 2f 77 77 77 2e 73 71 6c 69 74  http://www.sqlit
fc80: 65 2e 6f 72 67 2f 63 76 73 74 72 61 63 2f 77 69  e.org/cvstrac/wi
fc90: 6b 69 3f 70 3d 43 6f 72 72 75 70 74 69 6f 6e 46  ki?p=CorruptionF
fca0: 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f  ollowingBusyErro
fcb0: 72 22 3e 0a 2a 2a 20 43 6f 72 72 75 70 74 69 6f  r">.** Corruptio
fcc0: 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72  nFollowingBusyEr
fcd0: 72 6f 72 3c 2f 61 3e 20 77 69 6b 69 20 70 61 67  ror</a> wiki pag
fce0: 65 20 66 6f 72 20 61 20 64 69 73 63 75 73 73 69  e for a discussi
fcf0: 6f 6e 20 6f 66 20 77 68 79 0a 2a 2a 20 74 68 69  on of why.** thi
fd00: 73 20 69 73 20 69 6d 70 6f 72 74 61 6e 74 2e 0a  s is important..
fd10: 2a 2a 09 0a 2a 2a 20 54 68 65 72 65 20 63 61 6e  **..** There can
fd20: 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c   only be a singl
fd30: 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64  e busy handler d
fd40: 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68 20  efined for each 
fd50: 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
fd60: 65 63 74 69 6f 6e 2e 20 20 53 65 74 74 69 6e 67  ection.  Setting
fd70: 20 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64   a new busy hand
fd80: 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79 20 70  ler clears any p
fd90: 72 65 76 69 6f 75 73 20 6f 6e 65 2e 20 0a 2a 2a  revious one. .**
fda0: 20 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69   Note that calli
fdb0: 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  ng [sqlite3_busy
fdc0: 5f 74 69 6d 65 6f 75 74 28 29 5d 20 77 69 6c 6c  _timeout()] will
fdd0: 20 61 6c 73 6f 20 73 65 74 20 6f 72 20 63 6c 65   also set or cle
fde0: 61 72 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68  ar.** the busy h
fdf0: 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 4e  andler..**.** IN
fe00: 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
fe10: 7b 46 31 32 33 31 31 7d 20 54 68 65 20 5b 73 71  {F12311} The [sq
fe20: 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
fe30: 65 72 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 72  er()] function r
fe40: 65 70 6c 61 63 65 73 20 74 68 65 20 62 75 73 79  eplaces the busy
fe50: 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 20 20 20 20   handler.**     
fe60: 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 20 69 6e       callback in
fe70: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
fe80: 6e 6e 65 63 74 69 6f 6e 20 69 64 65 6e 74 69 66  nnection identif
fe90: 69 65 64 20 62 79 20 74 68 65 20 31 73 74 0a 2a  ied by the 1st.*
fea0: 2a 20 20 20 20 20 20 20 20 20 20 70 61 72 61 6d  *          param
feb0: 65 74 65 72 20 77 69 74 68 20 61 20 6e 65 77 20  eter with a new 
fec0: 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 64 65  busy handler ide
fed0: 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20 32  ntified by the 2
fee0: 6e 64 20 61 6e 64 20 33 72 64 0a 2a 2a 20 20 20  nd and 3rd.**   
fef0: 20 20 20 20 20 20 20 70 61 72 61 6d 65 74 65 72         parameter
ff00: 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 31 32  s..**.** {F12312
ff10: 7d 20 54 68 65 20 64 65 66 61 75 6c 74 20 62 75  } The default bu
ff20: 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 6e  sy handler for n
ff30: 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ew database conn
ff40: 65 63 74 69 6f 6e 73 20 69 73 20 4e 55 4c 4c 2e  ections is NULL.
ff50: 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 31 34 7d 20  .**.** {F12314} 
ff60: 57 68 65 6e 20 74 77 6f 20 6f 72 20 6d 6f 72 65  When two or more
ff70: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
ff80: 74 69 6f 6e 20 73 68 61 72 65 20 61 20 5b 73 71  tion share a [sq
ff90: 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61  lite3_enable_sha
ffa0: 72 65 64 5f 63 61 63 68 65 20 7c 20 63 6f 6d 6d  red_cache | comm
ffb0: 6f 6e 20 63 61 63 68 65 5d 2c 0a 2a 2a 20 20 20  on cache],.**   
ffc0: 20 20 20 20 20 20 20 74 68 65 20 62 75 73 79 20         the busy 
ffd0: 68 61 6e 64 6c 65 72 20 66 6f 72 20 74 68 65 20  handler for the 
ffe0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
fff0: 69 6f 6e 20 63 75 72 72 65 6e 74 6c 79 20 75 73  ion currently us
10000 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ing.**          
10010 74 68 65 20 63 61 63 68 65 20 69 73 20 69 6e 76  the cache is inv
10020 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 20 63 61  oked when the ca
10030 63 68 65 20 65 6e 63 6f 75 6e 74 65 72 73 20 61  che encounters a
10040 20 6c 6f 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31   lock..**.** {F1
10050 32 33 31 36 7d 20 49 66 20 61 20 62 75 73 79 20  2316} If a busy 
10060 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b  handler callback
10070 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74   returns zero, t
10080 68 65 6e 20 74 68 65 20 53 51 4c 69 74 65 0a 2a  hen the SQLite.*
10090 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 72  *          inter
100a0 66 61 63 65 20 74 68 61 74 20 70 72 6f 76 6f 6b  face that provok
100b0 65 64 20 74 68 65 20 6c 6f 63 6b 69 6e 67 20 65  ed the locking e
100c0 76 65 6e 74 20 77 69 6c 6c 20 72 65 74 75 72 6e  vent will return
100d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51  .**          [SQ
100e0 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a  LITE_BUSY]..**.*
100f0 2a 20 7b 46 31 32 33 31 38 7d 20 53 51 4c 69 74  * {F12318} SQLit
10100 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 73 20 74  e will invokes t
10110 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
10120 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e  with two argumen
10130 74 73 20 77 68 69 63 68 0a 2a 2a 20 20 20 20 20  ts which.**     
10140 20 20 20 20 20 61 72 65 20 61 20 63 6f 70 79 20       are a copy 
10150 6f 66 20 74 68 65 20 70 6f 69 6e 74 65 72 20 73  of the pointer s
10160 75 70 70 6c 69 65 64 20 62 79 20 74 68 65 20 33  upplied by the 3
10170 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  rd parameter to.
10180 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
10190 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
101a0 72 28 29 5d 20 61 6e 64 20 61 20 63 6f 75 6e 74  r()] and a count
101b0 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   of the number o
101c0 66 20 70 72 69 6f 72 0a 2a 2a 20 20 20 20 20 20  f prior.**      
101d0 20 20 20 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20      invocations 
101e0 6f 66 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  of the busy hand
101f0 6c 65 72 20 66 6f 72 20 74 68 65 20 73 61 6d 65  ler for the same
10200 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e 0a   locking event..
10210 2a 2a 0a 2a 2a 20 4c 49 4d 49 54 41 54 49 4f 4e  **.** LIMITATION
10220 53 3a 0a 2a 2a 0a 2a 2a 20 7b 55 31 32 33 31 39  S:.**.** {U12319
10230 7d 20 41 20 62 75 73 79 20 68 61 6e 64 6c 65 72  } A busy handler
10240 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c   should not call
10250 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62   close the datab
10260 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
10270 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 70 72  *          or pr
10280 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
10290 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
102a0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a  e busy handler..
102b0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
102c0 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69  usy_handler(sqli
102d0 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69  te3*, int(*)(voi
102e0 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b  d*,int), void*);
102f0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
10300 3a 20 53 65 74 20 41 20 42 75 73 79 20 54 69 6d  : Set A Busy Tim
10310 65 6f 75 74 20 7b 46 31 32 33 34 30 7d 0a 2a 2a  eout {F12340}.**
10320 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
10330 20 73 65 74 73 20 61 20 5b 73 71 6c 69 74 65 33   sets a [sqlite3
10340 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20  _busy_handler | 
10350 62 75 73 79 20 68 61 6e 64 6c 65 72 5d 0a 2a 2a  busy handler].**
10360 20 74 68 61 74 20 73 6c 65 65 70 73 20 66 6f 72   that sleeps for
10370 20 61 20 77 68 69 6c 65 20 77 68 65 6e 20 61 0a   a while when a.
10380 2a 2a 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b  ** table is lock
10390 65 64 2e 20 20 54 68 65 20 68 61 6e 64 6c 65 72  ed.  The handler
103a0 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74   will sleep mult
103b0 69 70 6c 65 20 74 69 6d 65 73 20 75 6e 74 69 6c  iple times until
103c0 20 0a 2a 2a 20 61 74 20 6c 65 61 73 74 20 22 6d   .** at least "m
103d0 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  s" milliseconds 
103e0 6f 66 20 73 6c 65 65 70 69 6e 67 20 68 61 76 65  of sleeping have
103f0 20 62 65 65 6e 20 64 6f 6e 65 2e 20 7b 46 31 32   been done. {F12
10400 33 34 33 7d 20 41 66 74 65 72 0a 2a 2a 20 22 6d  343} After.** "m
10410 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  s" milliseconds 
10420 6f 66 20 73 6c 65 65 70 69 6e 67 2c 20 74 68 65  of sleeping, the
10430 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73   handler returns
10440 20 30 20 77 68 69 63 68 0a 2a 2a 20 63 61 75 73   0 which.** caus
10450 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  es [sqlite3_step
10460 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 20 5b 53  ()] to return [S
10470 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b  QLITE_BUSY] or [
10480 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
10490 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c  CKED]..**.** Cal
104a0 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e  ling this routin
104b0 65 20 77 69 74 68 20 61 6e 20 61 72 67 75 6d 65  e with an argume
104c0 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20  nt less than or 
104d0 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a  equal to zero.**
104e0 20 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62   turns off all b
104f0 75 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a  usy handlers..**
10500 0a 2a 2a 20 54 68 65 72 65 20 63 61 6e 20 6f 6e  .** There can on
10510 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62  ly be a single b
10520 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20  usy handler for 
10530 61 20 70 61 72 74 69 63 75 6c 61 72 20 64 61 74  a particular dat
10540 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
10550 69 6f 6e 2e 20 20 49 66 20 61 6e 6f 74 68 65 72  ion.  If another
10560 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 77 61   busy handler wa
10570 73 20 64 65 66 69 6e 65 64 20 20 0a 2a 2a 20 28  s defined  .** (
10580 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62  using [sqlite3_b
10590 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20  usy_handler()]) 
105a0 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67  prior to calling
105b0 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65  .** this routine
105c0 2c 20 74 68 61 74 20 6f 74 68 65 72 20 62 75 73  , that other bus
105d0 79 20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65  y handler is cle
105e0 61 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  ared..**.** INVA
105f0 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  RIANTS:.**.** {F
10600 31 32 33 34 31 7d 20 54 68 65 20 5b 73 71 6c 69  12341} The [sqli
10610 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74  te3_busy_timeout
10620 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 6f 76 65  ()] function ove
10630 72 72 69 64 65 73 20 61 6e 79 20 70 72 69 6f 72  rrides any prior
10640 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
10650 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f  lite3_busy_timeo
10660 75 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ut()] or [sqlite
10670 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29  3_busy_handler()
10680 5d 20 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20  ] setting.**    
10690 20 20 20 20 20 20 6f 6e 20 74 68 65 20 73 61 6d        on the sam
106a0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
106b0 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  ction..**.** {F1
106c0 32 33 34 33 7d 20 49 66 20 74 68 65 20 32 6e 64  2343} If the 2nd
106d0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
106e0 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65  qlite3_busy_time
106f0 6f 75 74 28 29 5d 20 69 73 20 6c 65 73 73 20 74  out()] is less t
10700 68 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  han.**          
10710 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f  or equal to zero
10720 2c 20 74 68 65 6e 20 74 68 65 20 62 75 73 79 20  , then the busy 
10730 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72  handler is clear
10740 65 64 20 73 6f 20 74 68 61 74 0a 2a 2a 20 20 20  ed so that.**   
10750 20 20 20 20 20 20 20 61 6c 6c 20 73 75 62 73 65         all subse
10760 71 75 65 6e 74 20 6c 6f 63 6b 69 6e 67 20 65 76  quent locking ev
10770 65 6e 74 73 20 69 6d 6d 65 64 69 61 74 65 6c 79  ents immediately
10780 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
10790 42 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  BUSY]..**.** {F1
107a0 32 33 34 34 7d 20 49 66 20 74 68 65 20 32 6e 64  2344} If the 2nd
107b0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
107c0 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65  qlite3_busy_time
107d0 6f 75 74 28 29 5d 20 69 73 20 61 20 70 6f 73 69  out()] is a posi
107e0 74 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  tive.**         
107f0 20 6e 75 6d 62 65 72 20 4e 2c 20 74 68 65 6e 20   number N, then 
10800 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69  a busy handler i
10810 73 20 73 65 74 20 74 68 61 74 20 72 65 70 65 61  s set that repea
10820 74 65 64 6c 79 20 63 61 6c 6c 73 0a 2a 2a 20 20  tedly calls.**  
10830 20 20 20 20 20 20 20 20 74 68 65 20 78 53 6c 65          the xSle
10840 65 70 28 29 20 6d 65 74 68 6f 64 20 69 6e 20 74  ep() method in t
10850 68 65 20 56 46 53 20 69 6e 74 65 72 66 61 63 65  he VFS interface
10860 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68   until either th
10870 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6c 6f  e.**          lo
10880 63 6b 20 63 6c 65 61 72 73 20 6f 72 20 75 6e 74  ck clears or unt
10890 69 6c 20 74 68 65 20 63 75 6d 75 6c 61 74 69 76  il the cumulativ
108a0 65 20 73 6c 65 65 70 20 74 69 6d 65 20 72 65 70  e sleep time rep
108b0 6f 72 74 65 64 20 62 61 63 6b 0a 2a 2a 20 20 20  orted back.**   
108c0 20 20 20 20 20 20 20 62 79 20 78 53 6c 65 65 70         by xSleep
108d0 28 29 20 65 78 63 65 65 64 73 20 4e 20 6d 69 6c  () exceeds N mil
108e0 6c 69 73 65 63 6f 6e 64 73 2e 0a 2a 2f 0a 69 6e  liseconds..*/.in
108f0 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74  t sqlite3_busy_t
10900 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c  imeout(sqlite3*,
10910 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a   int ms);../*.**
10920 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 65   CAPI3REF: Conve
10930 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 20  nience Routines 
10940 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 72  For Running Quer
10950 69 65 73 20 7b 46 31 32 33 37 30 7d 0a 2a 2a 0a  ies {F12370}.**.
10960 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41  ** Definition: A
10970 20 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c 65   <b>result table
10980 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64  </b> is memory d
10990 61 74 61 20 73 74 72 75 63 74 75 72 65 20 63 72  ata structure cr
109a0 65 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a 20  eated by the.** 
109b0 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62  [sqlite3_get_tab
109c0 6c 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  le()] interface.
109d0 20 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65    A result table
109e0 20 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20   records the.** 
109f0 63 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20 72  complete query r
10a00 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20  esults from one 
10a10 6f 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73 2e  or more queries.
10a20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65  .**.** The table
10a30 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 61   conceptually ha
10a40 73 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  s a number of ro
10a50 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20  ws and columns. 
10a60 20 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75   But.** these nu
10a70 6d 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70 61  mbers are not pa
10a80 72 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  rt of the result
10a90 20 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 20   table itself.  
10aa0 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73  These.** numbers
10ab0 20 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73 65   are obtained se
10ac0 70 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e  parately.  Let N
10ad0 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   be the number o
10ae0 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20  f rows.** and M 
10af0 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  be the number of
10b00 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20   columns..**.** 
10b10 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69  A result table i
10b20 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f  s an array of po
10b30 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74  inters to zero-t
10b40 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46  erminated.** UTF
10b50 2d 38 20 73 74 72 69 6e 67 73 2e 20 20 54 68 65  -8 strings.  The
10b60 72 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65  re are (N+1)*M e
10b70 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61  lements in the a
10b80 72 72 61 79 2e 20 20 0a 2a 2a 20 54 68 65 20 66  rray.  .** The f
10b90 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73 20  irst M pointers 
10ba0 70 6f 69 6e 74 20 74 6f 20 7a 65 72 6f 2d 74 65  point to zero-te
10bb0 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73  rminated strings
10bc0 20 74 68 61 74 20 0a 2a 2a 20 63 6f 6e 74 61 69   that .** contai
10bd0 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74  n the names of t
10be0 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54  he columns..** T
10bf0 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74  he remaining ent
10c00 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74  ries all point t
10c10 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 2e  o query results.
10c20 20 20 4e 55 4c 4c 0a 2a 2a 20 76 61 6c 75 65 73    NULL.** values
10c30 20 61 72 65 20 67 69 76 65 20 61 20 4e 55 4c 4c   are give a NULL
10c40 20 70 6f 69 6e 74 65 72 2e 20 20 41 6c 6c 20 6f   pointer.  All o
10c50 74 68 65 72 20 76 61 6c 75 65 73 20 61 72 65 20  ther values are 
10c60 69 6e 0a 2a 2a 20 74 68 65 69 72 20 55 54 46 2d  in.** their UTF-
10c70 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  8 zero-terminate
10c80 64 20 73 74 72 69 6e 67 20 72 65 70 72 65 73 65  d string represe
10c90 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75 72  ntation as retur
10ca0 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ned by.** [sqlit
10cb0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
10cc0 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c  ]..**.** A resul
10cd0 74 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f  t table might co
10ce0 6e 73 69 73 74 73 20 6f 66 20 6f 6e 65 20 6f 72  nsists of one or
10cf0 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c   more memory all
10d00 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20  ocations..** It 
10d10 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 70  is not safe to p
10d20 61 73 73 20 61 20 72 65 73 75 6c 74 20 74 61 62  ass a result tab
10d30 6c 65 20 64 69 72 65 63 74 6c 79 20 74 6f 20 5b  le directly to [
10d40 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e  sqlite3_free()].
10d50 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62  .** A result tab
10d60 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 64 65 61  le should be dea
10d70 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 20 5b  llocated using [
10d80 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
10d90 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 73 20  le()]..**.** As 
10da0 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68  an example of th
10db0 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66  e result table f
10dc0 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61  ormat, suppose a
10dd0 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a   query result.**
10de0 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a   is as follows:.
10df0 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
10e00 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20  e><pre>.**      
10e10 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20    Name        | 
10e20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d  Age.**        --
10e30 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
10e40 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20  -----.**        
10e50 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34 33  Alice       | 43
10e60 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20  .**        Bob  
10e70 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20         | 28.**  
10e80 20 20 20 20 20 20 43 69 6e 64 79 20 20 20 20 20        Cindy     
10e90 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e    | 21.** </pre>
10ea0 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
10eb0 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 77  .** There are tw
10ec0 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20  o column (M==2) 
10ed0 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73 20 28  and three rows (
10ee0 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65  N==3).  Thus the
10ef0 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65  .** result table
10f00 20 68 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20   has 8 entries. 
10f10 20 53 75 70 70 6f 73 65 20 74 68 65 20 72 65 73   Suppose the res
10f20 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f  ult table is sto
10f30 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72  red.** in an arr
10f40 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c  ay names azResul
10f50 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c  t.  Then azResul
10f60 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e  t holds this con
10f70 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  tent:.**.** <blo
10f80 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
10f90 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
10fa0 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22  &#91;0] = "Name"
10fb0 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
10fc0 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41  sult&#91;1] = "A
10fd0 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  ge";.**        a
10fe0 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d  zResult&#91;2] =
10ff0 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20   "Alice";.**    
11000 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
11010 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20  ;3] = "43";.**  
11020 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
11030 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a  91;4] = "Bob";.*
11040 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
11050 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b  t&#91;5] = "28";
11060 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
11070 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69  ult&#91;6] = "Ci
11080 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  ndy";.**        
11090 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20  azResult&#91;7] 
110a0 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65  = "21";.** </pre
110b0 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
110c0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
110d0 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75 6e  _get_table() fun
110e0 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73 20  ction evaluates 
110f0 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73  one or more.** s
11100 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74  emicolon-separat
11110 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ed SQL statement
11120 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65  s in the zero-te
11130 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a  rminated UTF-8.*
11140 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73 20  * string of its 
11150 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20  2nd parameter.  
11160 49 74 20 72 65 74 75 72 6e 73 20 61 20 72 65 73  It returns a res
11170 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68 65  ult table to the
11180 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76 65  .** pointer give
11190 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70 61 72  n in its 3rd par
111a0 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66  ameter..**.** Af
111b0 74 65 72 20 74 68 65 20 63 61 6c 6c 69 6e 67 20  ter the calling 
111c0 66 75 6e 63 74 69 6f 6e 20 68 61 73 20 66 69 6e  function has fin
111d0 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 65 20  ished using the 
111e0 72 65 73 75 6c 74 2c 20 69 74 20 73 68 6f 75 6c  result, it shoul
111f0 64 20 0a 2a 2a 20 70 61 73 73 20 74 68 65 20 70  d .** pass the p
11200 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 72 65  ointer to the re
11210 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 73 71  sult table to sq
11220 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
11230 28 29 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 0a  () in order to .
11240 2a 2a 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d  ** release the m
11250 65 6d 6f 72 79 20 74 68 61 74 20 77 61 73 20 6d  emory that was m
11260 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61 75 73  alloced.  Becaus
11270 65 20 6f 66 20 74 68 65 20 77 61 79 20 74 68 65  e of the way the
11280 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61   .** [sqlite3_ma
11290 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e 73 20  lloc()] happens 
112a0 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33 5f 67  within sqlite3_g
112b0 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 68 65 20  et_table(), the 
112c0 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74  calling.** funct
112d0 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72 79  ion must not try
112e0 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65   to call [sqlite
112f0 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65 63 74  3_free()] direct
11300 6c 79 2e 20 20 4f 6e 6c 79 20 0a 2a 2a 20 5b 73  ly.  Only .** [s
11310 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
11320 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74 6f 20  e()] is able to 
11330 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f  release the memo
11340 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e 64 20  ry properly and 
11350 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68  safely..**.** Th
11360 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  e sqlite3_get_ta
11370 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ble() interface 
11380 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61  is implemented a
11390 73 20 61 20 77 72 61 70 70 65 72 20 61 72 6f 75  s a wrapper arou
113a0 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  nd.** [sqlite3_e
113b0 78 65 63 28 29 5d 2e 20 20 54 68 65 20 73 71 6c  xec()].  The sql
113c0 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
113d0 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f   routine does no
113e0 74 20 68 61 76 65 20 61 63 63 65 73 73 0a 2a 2a  t have access.**
113f0 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c   to any internal
11400 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73   data structures
11410 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 74 20   of SQLite.  It 
11420 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 70 75  uses only the pu
11430 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63  blic.** interfac
11440 65 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 20  e defined here. 
11450 20 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e 63   As a consequenc
11460 65 2c 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f  e, errors that o
11470 63 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77  ccur in the.** w
11480 72 61 70 70 65 72 20 6c 61 79 65 72 20 6f 75 74  rapper layer out
11490 73 69 64 65 20 6f 66 20 74 68 65 20 69 6e 74 65  side of the inte
114a0 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78  rnal [sqlite3_ex
114b0 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e  ec()] call are n
114c0 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64 20  ot.** reflected 
114d0 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  in subsequent ca
114e0 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
114f0 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a  errcode()] or.**
11500 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
11510 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ()]..**.** INVAR
11520 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31  IANTS:.**.** {F1
11530 32 33 37 31 7d 20 49 66 20 61 20 5b 73 71 6c 69  2371} If a [sqli
11540 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d  te3_get_table()]
11550 20 66 61 69 6c 73 20 61 20 6d 65 6d 6f 72 79 20   fails a memory 
11560 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e  allocation, then
11570 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 74 20  .**          it 
11580 66 72 65 65 73 20 74 68 65 20 72 65 73 75 6c 74  frees the result
11590 20 74 61 62 6c 65 20 75 6e 64 65 72 20 63 6f 6e   table under con
115a0 73 74 72 75 63 74 69 6f 6e 2c 20 61 62 6f 72 74  struction, abort
115b0 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
115c0 20 20 71 75 65 72 79 20 69 6e 20 70 72 6f 63 65    query in proce
115d0 73 73 2c 20 73 6b 69 70 73 20 61 6e 79 20 73 75  ss, skips any su
115e0 62 73 65 71 75 65 6e 74 20 71 75 65 72 69 65 73  bsequent queries
115f0 2c 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 20 20  , sets the.**   
11600 20 20 20 20 20 20 20 2a 72 65 73 75 6c 74 70 20         *resultp 
11610 6f 75 74 70 75 74 20 70 6f 69 6e 74 65 72 20 74  output pointer t
11620 6f 20 4e 55 4c 4c 20 61 6e 64 20 72 65 74 75 72  o NULL and retur
11630 6e 73 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  ns [SQLITE_NOMEM
11640 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 37 33  ]..**.** {F12373
11650 7d 20 49 66 20 74 68 65 20 6e 63 6f 6c 75 6d 6e  } If the ncolumn
11660 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
11670 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
11680 28 29 5d 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 0a  ()] is not NULL.
11690 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e  **          then
116a0 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61   [sqlite3_get_ta
116b0 62 6c 65 28 29 5d 20 77 72 69 74 65 20 74 68 65  ble()] write the
116c0 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
116d0 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20  ns in the.**    
116e0 20 20 20 20 20 20 72 65 73 75 6c 74 20 73 65 74        result set
116f0 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 69 6e   of the query in
11700 74 6f 20 2a 6e 63 6f 6c 75 6d 6e 20 69 66 20 74  to *ncolumn if t
11710 68 65 20 71 75 65 72 79 20 69 73 0a 2a 2a 20 20  he query is.**  
11720 20 20 20 20 20 20 20 20 73 75 63 63 65 73 73 66          successf
11730 75 6c 20 28 69 66 20 74 68 65 20 66 75 6e 63 74  ul (if the funct
11740 69 6f 6e 20 72 65 74 75 72 6e 73 20 53 51 4c 49  ion returns SQLI
11750 54 45 5f 4f 4b 29 2e 0a 2a 2a 0a 2a 2a 20 7b 46  TE_OK)..**.** {F
11760 31 32 33 37 34 7d 20 49 66 20 74 68 65 20 6e 72  12374} If the nr
11770 6f 77 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  ow parameter to 
11780 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62  [sqlite3_get_tab
11790 6c 65 28 29 5d 20 69 73 20 6e 6f 74 20 4e 55 4c  le()] is not NUL
117a0 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  L.**          th
117b0 65 6e 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  en [sqlite3_get_
117c0 74 61 62 6c 65 28 29 5d 20 77 72 69 74 65 20 74  table()] write t
117d0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77  he number of row
117e0 73 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20  s in the.**     
117f0 20 20 20 20 20 72 65 73 75 6c 74 20 73 65 74 20       result set 
11800 6f 66 20 74 68 65 20 71 75 65 72 79 20 69 6e 74  of the query int
11810 6f 20 2a 6e 72 6f 77 20 69 66 20 74 68 65 20 71  o *nrow if the q
11820 75 65 72 79 20 69 73 0a 2a 2a 20 20 20 20 20 20  uery is.**      
11830 20 20 20 20 73 75 63 63 65 73 73 66 75 6c 20 28      successful (
11840 69 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  if the function 
11850 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f  returns SQLITE_O
11860 4b 29 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 37  K)..**.** {F1237
11870 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  6} The [sqlite3_
11880 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 66 75 6e  get_table()] fun
11890 63 74 69 6f 6e 20 73 65 74 73 20 69 74 73 20 2a  ction sets its *
118a0 6e 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 0a 2a 2a  ncolumn value.**
118b0 20 20 20 20 20 20 20 20 20 20 74 6f 20 74 68 65            to the
118c0 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
118d0 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ns in the result
118e0 20 73 65 74 20 6f 66 20 74 68 65 20 71 75 65 72   set of the quer
118f0 79 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20  y in the.**     
11900 20 20 20 20 20 73 71 6c 20 70 61 72 61 6d 65 74       sql paramet
11910 65 72 2c 20 6f 72 20 74 6f 20 7a 65 72 6f 20 69  er, or to zero i
11920 66 20 74 68 65 20 71 75 65 72 79 20 69 6e 20 73  f the query in s
11930 71 6c 20 68 61 73 20 61 6e 20 65 6d 70 74 79 0a  ql has an empty.
11940 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 73 75  **          resu
11950 6c 74 20 73 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73  lt set..*/.int s
11960 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
11970 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20  (.  sqlite3*,   
11980 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20            /* An 
11990 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f  open database */
119a0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  .  const char *s
119b0 71 6c 2c 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  ql,      /* SQL 
119c0 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20  to be evaluated 
119d0 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70 52 65  */.  char ***pRe
119e0 73 75 6c 74 2c 20 20 20 20 20 20 2f 2a 20 52 65  sult,      /* Re
119f0 73 75 6c 74 73 20 6f 66 20 74 68 65 20 71 75 65  sults of the que
11a00 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 6e 72 6f  ry */.  int *nro
11a10 77 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  w,            /*
11a20 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c   Number of resul
11a30 74 20 72 6f 77 73 20 77 72 69 74 74 65 6e 20 68  t rows written h
11a40 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 6e 63  ere */.  int *nc
11a50 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 20 2f  olumn,         /
11a60 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75  * Number of resu
11a70 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74  lt columns writt
11a80 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 61  en here */.  cha
11a90 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20 20 20  r **errmsg      
11aa0 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20     /* Error msg 
11ab0 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a  written here */.
11ac0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
11ad0 66 72 65 65 5f 74 61 62 6c 65 28 63 68 61 72 20  free_table(char 
11ae0 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a  **result);../*.*
11af0 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6f 72 6d  * CAPI3REF: Form
11b00 61 74 74 65 64 20 53 74 72 69 6e 67 20 50 72 69  atted String Pri
11b10 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 20  nting Functions 
11b20 7b 46 31 37 34 30 30 7d 0a 2a 2a 0a 2a 2a 20 54  {F17400}.**.** T
11b30 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
11b40 65 20 77 6f 72 6b 61 6c 69 6b 65 73 20 6f 66 20  e workalikes of 
11b50 74 68 65 20 22 70 72 69 6e 74 66 28 29 22 20 66  the "printf()" f
11b60 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f  amily of functio
11b70 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73  ns.** from the s
11b80 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
11b90 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  y..**.** The sql
11ba0 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61  ite3_mprintf() a
11bb0 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69  nd sqlite3_vmpri
11bc0 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 73 20 77  ntf() routines w
11bd0 72 69 74 65 20 74 68 65 69 72 0a 2a 2a 20 72 65  rite their.** re
11be0 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72  sults into memor
11bf0 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
11c00 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
11c10 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e  )]..** The strin
11c20 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  gs returned by t
11c30 68 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65  hese two routine
11c40 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72  s should be.** r
11c50 65 6c 65 61 73 65 64 20 62 79 20 5b 73 71 6c 69  eleased by [sqli
11c60 74 65 33 5f 66 72 65 65 28 29 5d 2e 20 20 20 42  te3_free()].   B
11c70 6f 74 68 20 72 6f 75 74 69 6e 65 73 20 72 65 74  oth routines ret
11c80 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f  urn a.** NULL po
11c90 69 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 74 65  inter if [sqlite
11ca0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75  3_malloc()] is u
11cb0 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74  nable to allocat
11cc0 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f  e enough.** memo
11cd0 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72  ry to hold the r
11ce0 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e  esulting string.
11cf0 0a 2a 2a 0a 2a 2a 20 49 6e 20 73 71 6c 69 74 65  .**.** In sqlite
11d00 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75  3_snprintf() rou
11d10 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20  tine is similar 
11d20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20  to "snprintf()" 
11d30 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e  from.** the stan
11d40 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20  dard C library. 
11d50 20 54 68 65 20 72 65 73 75 6c 74 20 69 73 20 77   The result is w
11d60 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a  ritten into the.
11d70 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c 69  ** buffer suppli
11d80 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
11d90 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65   parameter whose
11da0 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62   size is given b
11db0 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70  y.** the first p
11dc0 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74  arameter. Note t
11dd0 68 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66  hat the order of
11de0 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77   the.** first tw
11df0 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20  o parameters is 
11e00 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e  reversed from sn
11e10 70 72 69 6e 74 66 28 29 2e 20 20 54 68 69 73 20  printf().  This 
11e20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69  is an.** histori
11e30 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74 68 61  cal accident tha
11e40 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 78 65  t cannot be fixe
11e50 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69  d without breaki
11e60 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20  ng.** backwards 
11e70 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20 20  compatibility.  
11e80 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 74 20 73  Note also that s
11e90 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
11ea0 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 70  ).** returns a p
11eb0 6f 69 6e 74 65 72 20 74 6f 20 69 74 73 20 62 75  ointer to its bu
11ec0 66 66 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20  ffer instead of 
11ed0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
11ee0 20 63 68 61 72 61 63 74 65 72 73 20 61 63 74 75   characters actu
11ef0 61 6c 6c 79 20 77 72 69 74 74 65 6e 20 69 6e 74  ally written int
11f00 6f 20 74 68 65 20 62 75 66 66 65 72 2e 20 20 57  o the buffer.  W
11f10 65 20 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20  e admit that.** 
11f20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  the number of ch
11f30 61 72 61 63 74 65 72 73 20 77 72 69 74 74 65 6e  aracters written
11f40 20 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72 65   would be a more
11f50 20 75 73 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a   useful return.*
11f60 2a 20 76 61 6c 75 65 20 62 75 74 20 77 65 20 63  * value but we c
11f70 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  annot change the
11f80 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
11f90 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  of sqlite3_snpri
11fa0 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74  ntf().** now wit
11fb0 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 63 6f  hout breaking co
11fc0 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a  mpatibility..**.
11fd0 2a 2a 20 41 73 20 6c 6f 6e 67 20 61 73 20 74 68  ** As long as th
11fe0 65 20 62 75 66 66 65 72 20 73 69 7a 65 20 69 73  e buffer size is
11ff0 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65   greater than ze
12000 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70 72  ro, sqlite3_snpr
12010 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e  intf().** guaran
12020 74 65 65 73 20 74 68 61 74 20 74 68 65 20 62 75  tees that the bu
12030 66 66 65 72 20 69 73 20 61 6c 77 61 79 73 20 7a  ffer is always z
12040 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20  ero-terminated. 
12050 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61   The first.** pa
12060 72 61 6d 65 74 65 72 20 22 6e 22 20 69 73 20 74  rameter "n" is t
12070 68 65 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66  he total size of
12080 20 74 68 65 20 62 75 66 66 65 72 2c 20 69 6e 63   the buffer, inc
12090 6c 75 64 69 6e 67 20 73 70 61 63 65 20 66 6f 72  luding space for
120a0 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74 65 72  .** the zero ter
120b0 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68 65  minator.  So the
120c0 20 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e 67 20   longest string 
120d0 74 68 61 74 20 63 61 6e 20 62 65 20 63 6f 6d 70  that can be comp
120e0 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65  letely.** writte
120f0 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68  n will be n-1 ch
12100 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  aracters..**.** 
12110 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
12120 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d  ll implement som
12130 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72  e additional for
12140 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f  matting.** optio
12150 6e 73 20 74 68 61 74 20 61 72 65 20 75 73 65 66  ns that are usef
12160 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75 63 74  ul for construct
12170 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ing SQL statemen
12180 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68  ts..** All of th
12190 65 20 75 73 75 61 6c 20 70 72 69 6e 74 66 28 29  e usual printf()
121a0 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69   formatting opti
121b0 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e 20 61  ons apply.  In a
121c0 64 64 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a  ddition, there.*
121d0 2a 20 69 73 20 61 72 65 20 22 25 71 22 2c 20 22  * is are "%q", "
121e0 25 51 22 2c 20 61 6e 64 20 22 25 7a 22 20 6f 70  %Q", and "%z" op
121f0 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tions..**.** The
12200 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73   %q option works
12210 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68 61 74   like %s in that
12220 20 69 74 20 73 75 62 73 74 69 74 75 74 65 73 20   it substitutes 
12230 61 20 6e 75 6c 6c 2d 74 65 72 6d 69 6e 61 74 65  a null-terminate
12240 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d  d.** string from
12250 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c 69   the argument li
12260 73 74 2e 20 20 42 75 74 20 25 71 20 61 6c 73 6f  st.  But %q also
12270 20 64 6f 75 62 6c 65 73 20 65 76 65 72 79 20 27   doubles every '
12280 5c 27 27 20 63 68 61 72 61 63 74 65 72 2e 0a 2a  \'' character..*
12290 2a 20 25 71 20 69 73 20 64 65 73 69 67 6e 65 64  * %q is designed
122a0 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20   for use inside 
122b0 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c  a string literal
122c0 2e 20 20 42 79 20 64 6f 75 62 6c 69 6e 67 20 65  .  By doubling e
122d0 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72  ach '\''.** char
122e0 61 63 74 65 72 20 69 74 20 65 73 63 61 70 65 73  acter it escapes
122f0 20 74 68 61 74 20 63 68 61 72 61 63 74 65 72 20   that character 
12300 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f  and allows it to
12310 20 62 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74   be inserted int
12320 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 2e  o.** the string.
12330 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70  .**.** For examp
12340 6c 65 2c 20 73 6f 20 73 6f 6d 65 20 73 74 72 69  le, so some stri
12350 6e 67 20 76 61 72 69 61 62 6c 65 20 63 6f 6e 74  ng variable cont
12360 61 69 6e 73 20 74 65 78 74 20 61 73 20 66 6f 6c  ains text as fol
12370 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
12380 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
12390 20 20 63 68 61 72 20 2a 7a 54 65 78 74 20 3d 20    char *zText = 
123a0 22 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61  "It's a happy da
123b0 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  y!";.** </pre></
123c0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
123d0 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65 20 74 68  * One can use th
123e0 69 73 20 74 65 78 74 20 69 6e 20 61 6e 20 53 51  is text in an SQ
123f0 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20 66  L statement as f
12400 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
12410 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
12420 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d  **  char *zSQL =
12430 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
12440 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61  ("INSERT INTO ta
12450 62 6c 65 20 56 41 4c 55 45 53 28 27 25 71 27 29  ble VALUES('%q')
12460 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73  ", zText);.**  s
12470 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20  qlite3_exec(db, 
12480 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a  zSQL, 0, 0, 0);.
12490 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65  **  sqlite3_free
124a0 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65  (zSQL);.** </pre
124b0 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
124c0 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65  *.** Because the
124d0 20 25 71 20 66 6f 72 6d 61 74 20 73 74 72 69 6e   %q format strin
124e0 67 20 69 73 20 75 73 65 64 2c 20 74 68 65 20 27  g is used, the '
124f0 5c 27 27 20 63 68 61 72 61 63 74 65 72 20 69 6e  \'' character in
12500 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65 73 63   zText.** is esc
12510 61 70 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c  aped and the SQL
12520 20 67 65 6e 65 72 61 74 65 64 20 69 73 20 61 73   generated is as
12530 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
12540 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
12550 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54  >.**  INSERT INT
12560 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28  O table1 VALUES(
12570 27 49 74 27 27 73 20 61 20 68 61 70 70 79 20 64  'It''s a happy d
12580 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  ay!').** </pre><
12590 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
125a0 2a 2a 20 54 68 69 73 20 69 73 20 63 6f 72 72 65  ** This is corre
125b0 63 74 2e 20 20 48 61 64 20 77 65 20 75 73 65 64  ct.  Had we used
125c0 20 25 73 20 69 6e 73 74 65 61 64 20 6f 66 20 25   %s instead of %
125d0 71 2c 20 74 68 65 20 67 65 6e 65 72 61 74 65 64  q, the generated
125e0 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61   SQL.** would ha
125f0 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74  ve looked like t
12600 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  his:.**.** <bloc
12610 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
12620 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62   INSERT INTO tab
12630 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 73  le1 VALUES('It's
12640 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29 3b   a happy day!');
12650 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
12660 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
12670 69 73 20 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c  is second exampl
12680 65 20 69 73 20 61 6e 20 53 51 4c 20 73 79 6e 74  e is an SQL synt
12690 61 78 20 65 72 72 6f 72 2e 20 20 41 73 20 61 20  ax error.  As a 
126a0 67 65 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f 75  general rule you
126b0 0a 2a 2a 20 73 68 6f 75 6c 64 20 61 6c 77 61 79  .** should alway
126c0 73 20 75 73 65 20 25 71 20 69 6e 73 74 65 61 64  s use %q instead
126d0 20 6f 66 20 25 73 20 77 68 65 6e 20 69 6e 73 65   of %s when inse
126e0 72 74 69 6e 67 20 74 65 78 74 20 69 6e 74 6f 20  rting text into 
126f0 61 20 73 74 72 69 6e 67 20 0a 2a 2a 20 6c 69 74  a string .** lit
12700 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  eral..**.** The 
12710 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20  %Q option works 
12720 6c 69 6b 65 20 25 71 20 65 78 63 65 70 74 20 69  like %q except i
12730 74 20 61 6c 73 6f 20 61 64 64 73 20 73 69 6e 67  t also adds sing
12740 6c 65 20 71 75 6f 74 65 73 20 61 72 6f 75 6e 64  le quotes around
12750 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69 64 65 20  .** the outside 
12760 6f 66 20 74 68 65 20 74 6f 74 61 6c 20 73 74 72  of the total str
12770 69 6e 67 2e 20 20 4f 72 20 69 66 20 74 68 65 20  ing.  Or if the 
12780 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65  parameter in the
12790 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6c 69 73   argument.** lis
127a0 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  t is a NULL poin
127b0 74 65 72 2c 20 25 51 20 73 75 62 73 74 69 74 75  ter, %Q substitu
127c0 74 65 73 20 74 68 65 20 74 65 78 74 20 22 4e 55  tes the text "NU
127d0 4c 4c 22 20 28 77 69 74 68 6f 75 74 20 73 69 6e  LL" (without sin
127e0 67 6c 65 0a 2a 2a 20 71 75 6f 74 65 73 29 20 69  gle.** quotes) i
127f0 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20 25  n place of the %
12800 51 20 6f 70 74 69 6f 6e 2e 20 7b 45 4e 44 7d 20  Q option. {END} 
12810 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65   So, for example
12820 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a  , one could say:
12830 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
12840 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61  te><pre>.**  cha
12850 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65  r *zSQL = sqlite
12860 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52  3_mprintf("INSER
12870 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c  T INTO table VAL
12880 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78 74 29  UES(%Q)", zText)
12890 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78  ;.**  sqlite3_ex
128a0 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20  ec(db, zSQL, 0, 
128b0 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  0, 0);.**  sqlit
128c0 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a  e3_free(zSQL);.*
128d0 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
128e0 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  uote>.**.** The 
128f0 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c 6c 20  code above will 
12900 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65 63 74  render a correct
12910 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69   SQL statement i
12920 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61  n the zSQL.** va
12930 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66 20 74  riable even if t
12940 68 65 20 7a 54 65 78 74 20 76 61 72 69 61 62 6c  he zText variabl
12950 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  e is a NULL poin
12960 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 22  ter..**.** The "
12970 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f  %z" formatting o
12980 70 74 69 6f 6e 20 77 6f 72 6b 73 20 65 78 61 63  ption works exac
12990 74 6c 79 20 6c 69 6b 65 20 22 25 73 22 20 77 69  tly like "%s" wi
129a0 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69  th the.** additi
129b0 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20 74 68  on that after th
129c0 65 20 73 74 72 69 6e 67 20 68 61 73 20 62 65 65  e string has bee
129d0 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65  n read and copie
129e0 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65  d into.** the re
129f0 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66  sult, [sqlite3_f
12a00 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64  ree()] is called
12a10 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74   on the input st
12a20 72 69 6e 67 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a  ring. {END}.**.*
12a30 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
12a40 0a 2a 2a 20 7b 46 31 37 34 30 33 7d 20 20 54 68  .** {F17403}  Th
12a50 65 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e  e [sqlite3_mprin
12a60 74 66 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  tf()] and [sqlit
12a70 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 5d 20 69  e3_vmprintf()] i
12a80 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 20 20 20  nterfaces.**    
12a90 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 65 69         return ei
12aa0 74 68 65 72 20 70 6f 69 6e 74 65 72 73 20 74 6f  ther pointers to
12ab0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
12ac0 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73 20 68   UTF-8 strings h
12ad0 65 6c 64 20 69 6e 0a 2a 2a 20 20 20 20 20 20 20  eld in.**       
12ae0 20 20 20 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69      memory obtai
12af0 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
12b00 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 4e  3_malloc()] or N
12b10 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 69 66 0a  ULL pointers if.
12b20 2a 2a 20 20 20 20 20 20 20 20 20 20 20 61 20 63  **           a c
12b30 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
12b40 6d 61 6c 6c 6f 63 28 29 5d 20 66 61 69 6c 73 2e  malloc()] fails.
12b50 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 34 30 36 7d 20  .**.** {F17406} 
12b60 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 6e   The [sqlite3_sn
12b70 70 72 69 6e 74 66 28 29 5d 20 69 6e 74 65 72 66  printf()] interf
12b80 61 63 65 20 77 72 69 74 65 73 20 61 20 7a 65 72  ace writes a zer
12b90 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
12ba0 20 20 20 20 20 20 20 20 20 20 55 54 46 2d 38 20            UTF-8 
12bb0 73 74 72 69 6e 67 20 69 6e 74 6f 20 74 68 65 20  string into the 
12bc0 62 75 66 66 65 72 20 70 6f 69 6e 74 65 64 20 74  buffer pointed t
12bd0 6f 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20  o by the second 
12be0 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20  parameter.**    
12bf0 20 20 20 20 20 20 20 70 72 6f 76 69 64 65 64 20         provided 
12c00 74 68 61 74 20 74 68 65 20 66 69 72 73 74 20 70  that the first p
12c10 61 72 61 6d 65 74 65 72 20 69 73 20 67 72 65 61  arameter is grea
12c20 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2e 0a 2a  ter than zero..*
12c30 2a 0a 2a 2a 20 7b 46 31 37 34 30 37 7d 20 20 54  *.** {F17407}  T
12c40 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72  he [sqlite3_snpr
12c50 69 6e 74 66 28 29 5d 20 69 6e 74 65 72 66 61 63  intf()] interfac
12c60 65 20 64 6f 65 73 20 6e 6f 74 20 77 72 69 74 65  e does not write
12c70 73 20 73 6c 6f 74 73 20 6f 66 0a 2a 2a 20 20 20  s slots of.**   
12c80 20 20 20 20 20 20 20 20 69 74 73 20 6f 75 74 70          its outp
12c90 75 74 20 62 75 66 66 65 72 20 28 74 68 65 20 73  ut buffer (the s
12ca0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 29  econd parameter)
12cb0 20 6f 75 74 73 69 64 65 20 74 68 65 20 72 61 6e   outside the ran
12cc0 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  ge.**           
12cd0 6f 66 20 30 20 74 68 72 6f 75 67 68 20 4e 2d 31  of 0 through N-1
12ce0 20 28 77 68 65 72 65 20 4e 20 69 73 20 74 68 65   (where N is the
12cf0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
12d00 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72  ).**           r
12d10 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65  egardless of the
12d20 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73   length of the s
12d30 74 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20  tring.**        
12d40 20 20 20 72 65 71 75 65 73 74 65 64 20 62 79 20     requested by 
12d50 74 68 65 20 66 6f 72 6d 61 74 20 73 70 65 63 69  the format speci
12d60 66 69 63 61 74 69 6f 6e 2e 0a 2a 2a 20 20 20 0a  fication..**   .
12d70 2a 2f 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33  */.char *sqlite3
12d80 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63  _mprintf(const c
12d90 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20  har*,...);.char 
12da0 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74  *sqlite3_vmprint
12db0 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76  f(const char*, v
12dc0 61 5f 6c 69 73 74 29 3b 0a 63 68 61 72 20 2a 73  a_list);.char *s
12dd0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
12de0 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20  int,char*,const 
12df0 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a  char*, ...);../*
12e00 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65  .** CAPI3REF: Me
12e10 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20  mory Allocation 
12e20 53 75 62 73 79 73 74 65 6d 20 7b 46 31 37 33 30  Subsystem {F1730
12e30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  0}.**.** The SQL
12e40 69 74 65 20 63 6f 72 65 20 20 75 73 65 73 20 74  ite core  uses t
12e50 68 65 73 65 20 74 68 72 65 65 20 72 6f 75 74 69  hese three routi
12e60 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69  nes for all of i
12e70 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e  ts own.** intern
12e80 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  al memory alloca
12e90 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72  tion needs. "Cor
12ea0 65 22 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f  e" in the previo
12eb0 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64  us sentence.** d
12ec0 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20  oes not include 
12ed0 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d  operating-system
12ee0 20 73 70 65 63 69 66 69 63 20 56 46 53 20 69 6d   specific VFS im
12ef0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54  plementation.  T
12f00 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46  he.** Windows VF
12f10 53 20 75 73 65 73 20 6e 61 74 69 76 65 20 6d 61  S uses native ma
12f20 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28  lloc() and free(
12f30 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61  ) for some opera
12f40 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tions..**.** The
12f50 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
12f60 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
12f70 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
12f80 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d   block.** of mem
12f90 6f 72 79 20 61 74 20 6c 65 61 73 74 20 4e 20 62  ory at least N b
12fa0 79 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20  ytes in length, 
12fb0 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 70  where N is the p
12fc0 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 49 66 20  arameter..** If 
12fd0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
12fe0 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f 62   is unable to ob
12ff0 74 61 69 6e 20 73 75 66 66 69 63 69 65 6e 74 20  tain sufficient 
13000 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20  free.** memory, 
13010 69 74 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c  it returns a NUL
13020 4c 20 70 6f 69 6e 74 65 72 2e 20 20 49 66 20 74  L pointer.  If t
13030 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20 74  he parameter N t
13040 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c  o.** sqlite3_mal
13050 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72  loc() is zero or
13060 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 73   negative then s
13070 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
13080 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c  returns.** a NUL
13090 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
130a0 20 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33   Calling sqlite3
130b0 5f 66 72 65 65 28 29 20 77 69 74 68 20 61 20 70  _free() with a p
130c0 6f 69 6e 74 65 72 20 70 72 65 76 69 6f 75 73 6c  ointer previousl
130d0 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79  y returned.** by
130e0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
130f0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61  ) or sqlite3_rea
13100 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73 65 73 20  lloc() releases 
13110 74 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a  that memory so.*
13120 2a 20 74 68 61 74 20 69 74 20 6d 69 67 68 74 20  * that it might 
13130 62 65 20 72 65 75 73 65 64 2e 20 20 54 68 65 20  be reused.  The 
13140 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 72  sqlite3_free() r
13150 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e  outine is.** a n
13160 6f 2d 6f 70 20 69 66 20 69 73 20 63 61 6c 6c 65  o-op if is calle
13170 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f  d with a NULL po
13180 69 6e 74 65 72 2e 20 20 50 61 73 73 69 6e 67 20  inter.  Passing 
13190 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  a NULL pointer.*
131a0 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65  * to sqlite3_fre
131b0 65 28 29 20 69 73 20 68 61 72 6d 6c 65 73 73 2e  e() is harmless.
131c0 20 20 41 66 74 65 72 20 62 65 69 6e 67 20 66 72    After being fr
131d0 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73  eed, memory.** s
131e0 68 6f 75 6c 64 20 6e 65 69 74 68 65 72 20 62 65  hould neither be
131f0 20 72 65 61 64 20 6e 6f 72 20 77 72 69 74 74 65   read nor writte
13200 6e 2e 20 20 45 76 65 6e 20 72 65 61 64 69 6e 67  n.  Even reading
13210 20 70 72 65 76 69 6f 75 73 6c 79 20 66 72 65 65   previously free
13220 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68  d.** memory migh
13230 74 20 72 65 73 75 6c 74 20 69 6e 20 61 20 73 65  t result in a se
13240 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74  gmentation fault
13250 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65   or other severe
13260 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72   error..** Memor
13270 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20  y corruption, a 
13280 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75  segmentation fau
13290 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20 73 65 76  lt, or other sev
132a0 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67  ere error.** mig
132b0 68 74 20 72 65 73 75 6c 74 20 69 66 20 73 71 6c  ht result if sql
132c0 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 63  ite3_free() is c
132d0 61 6c 6c 65 64 20 77 69 74 68 20 61 20 6e 6f 6e  alled with a non
132e0 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68  -NULL pointer th
132f0 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62  at.** was not ob
13300 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69  tained from sqli
13310 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20  te3_malloc() or 
13320 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 2e 0a  sqlite3_free()..
13330 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
13340 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 6e 74 65  3_realloc() inte
13350 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74  rface attempts t
13360 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72  o resize a.** pr
13370 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ior memory alloc
13380 61 74 69 6f 6e 20 74 6f 20 62 65 20 61 74 20 6c  ation to be at l
13390 65 61 73 74 20 4e 20 62 79 74 65 73 2c 20 77 68  east N bytes, wh
133a0 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20  ere N is the.** 
133b0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
133c0 2e 20 20 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c  .  The memory al
133d0 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 72  location to be r
133e0 65 73 69 7a 65 64 20 69 73 20 74 68 65 20 66 69  esized is the fi
133f0 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  rst.** parameter
13400 2e 20 20 49 66 20 74 68 65 20 66 69 72 73 74 20  .  If the first 
13410 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
13420 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a  ite3_realloc().*
13430 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  * is a NULL poin
13440 74 65 72 20 74 68 65 6e 20 69 74 73 20 62 65 68  ter then its beh
13450 61 76 69 6f 72 20 69 73 20 69 64 65 6e 74 69 63  avior is identic
13460 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a  al to calling.**
13470 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
13480 4e 29 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  N) where N is th
13490 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
134a0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  er to sqlite3_re
134b0 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 49 66 20 74  alloc()..** If t
134c0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
134d0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
134e0 65 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f  ealloc() is zero
134f0 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20   or.** negative 
13500 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
13510 72 20 69 73 20 65 78 61 63 74 6c 79 20 74 68 65  r is exactly the
13520 20 73 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67   same as calling
13530 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65  .** sqlite3_free
13540 28 50 29 20 77 68 65 72 65 20 50 20 69 73 20 74  (P) where P is t
13550 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
13560 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  er to sqlite3_re
13570 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 53 71 6c 69  alloc()..** Sqli
13580 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65  te3_realloc() re
13590 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
135a0 74 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  to a memory allo
135b0 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20  cation.** of at 
135c0 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e  least N bytes in
135d0 20 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66   size or NULL if
135e0 20 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f   sufficient memo
135f0 72 79 20 69 73 20 75 6e 61 76 61 69 6c 61 62 6c  ry is unavailabl
13600 65 2e 0a 2a 2a 20 49 66 20 4d 20 69 73 20 74 68  e..** If M is th
13610 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72  e size of the pr
13620 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20  ior allocation, 
13630 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79  then min(N,M) by
13640 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72  tes.** of the pr
13650 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61  ior allocation a
13660 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74  re copied into t
13670 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20  he beginning of 
13680 62 75 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a  buffer returned.
13690 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65  ** by sqlite3_re
136a0 61 6c 6c 6f 63 28 29 20 61 6e 64 20 74 68 65 20  alloc() and the 
136b0 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
136c0 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20 49 66   is freed..** If
136d0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
136e0 28 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c  () returns NULL,
136f0 20 74 68 65 6e 20 74 68 65 20 70 72 69 6f 72 20   then the prior 
13700 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 73  allocation.** is
13710 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a   not freed..**.*
13720 2a 20 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74  * The memory ret
13730 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
13740 5f 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 73 71  _malloc() and sq
13750 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a  lite3_realloc().
13760 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69  ** is always ali
13770 67 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74  gned to at least
13780 20 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64   an 8 byte bound
13790 61 72 79 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a  ary. {END}.**.**
137a0 20 54 68 65 20 64 65 66 61 75 6c 74 20 69 6d 70   The default imp
137b0 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f  lementation.** o
137c0 66 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  f the memory all
137d0 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65  ocation subsyste
137e0 6d 20 75 73 65 73 20 74 68 65 20 6d 61 6c 6c 6f  m uses the mallo
137f0 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29 0a 2a  c(), realloc().*
13800 2a 20 61 6e 64 20 66 72 65 65 28 29 20 70 72 6f  * and free() pro
13810 76 69 64 65 64 20 62 79 20 74 68 65 20 73 74 61  vided by the sta
13820 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e  ndard C library.
13830 20 7b 46 31 37 33 38 32 7d 20 48 6f 77 65 76 65   {F17382} Howeve
13840 72 2c 20 69 66 20 0a 2a 2a 20 53 51 4c 69 74 65  r, if .** SQLite
13850 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
13860 68 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  h the following 
13870 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
13880 61 63 72 6f 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  acro.**.** <bloc
13890 6b 71 75 6f 74 65 3e 20 53 51 4c 49 54 45 5f 4d  kquote> SQLITE_M
138a0 45 4d 4f 52 59 5f 53 49 5a 45 3d 3c 69 3e 4e 4e  EMORY_SIZE=<i>NN
138b0 4e 3c 2f 69 3e 20 3c 2f 62 6c 6f 63 6b 71 75 6f  N</i> </blockquo
138c0 74 65 3e 0a 2a 2a 0a 2a 2a 20 77 68 65 72 65 20  te>.**.** where 
138d0 3c 69 3e 4e 4e 4e 3c 2f 69 3e 20 69 73 20 61 6e  <i>NNN</i> is an
138e0 20 69 6e 74 65 67 65 72 2c 20 74 68 65 6e 20 53   integer, then S
138f0 51 4c 69 74 65 20 63 72 65 61 74 65 20 61 20 73  QLite create a s
13900 74 61 74 69 63 0a 2a 2a 20 61 72 72 61 79 20 6f  tatic.** array o
13910 66 20 61 74 20 6c 65 61 73 74 20 3c 69 3e 4e 4e  f at least <i>NN
13920 4e 3c 2f 69 3e 20 62 79 74 65 73 20 69 6e 20 73  N</i> bytes in s
13930 69 7a 65 20 61 6e 64 20 75 73 65 20 74 68 61 74  ize and use that
13940 20 61 72 72 61 79 0a 2a 2a 20 66 6f 72 20 61 6c   array.** for al
13950 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63  l of its dynamic
13960 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
13970 6f 6e 20 6e 65 65 64 73 2e 20 7b 45 4e 44 7d 20  on needs. {END} 
13980 20 41 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 6d   Additional.** m
13990 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
139a0 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61  options may be a
139b0 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
139c0 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 49  eleases..**.** I
139d0 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  n SQLite version
139e0 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31   3.5.0 and 3.5.1
139f0 2c 20 69 74 20 77 61 73 20 70 6f 73 73 69 62 6c  , it was possibl
13a00 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74  e to define.** t
13a10 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d  he SQLITE_OMIT_M
13a20 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e  EMORY_ALLOCATION
13a30 20 77 68 69 63 68 20 77 6f 75 6c 64 20 63 61 75   which would cau
13a40 73 65 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a  se the built-in.
13a50 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
13a60 6e 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  n of these routi
13a70 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69 74 74 65  nes to be omitte
13a80 64 2e 20 20 54 68 61 74 20 63 61 70 61 62 69 6c  d.  That capabil
13a90 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e  ity.** is no lon
13aa0 67 65 72 20 70 72 6f 76 69 64 65 64 2e 20 20 4f  ger provided.  O
13ab0 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d  nly built-in mem
13ac0 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63  ory allocators c
13ad0 61 6e 20 62 65 0a 2a 2a 20 75 73 65 64 2e 0a 2a  an be.** used..*
13ae0 2a 0a 2a 2a 20 54 68 65 20 57 69 6e 64 6f 77 73  *.** The Windows
13af0 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61   OS interface la
13b00 79 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 74 68 65  yer calls.** the
13b10 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29   system malloc()
13b20 20 61 6e 64 20 66 72 65 65 28 29 20 64 69 72 65   and free() dire
13b30 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65 72  ctly when conver
13b40 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65  ting.** filename
13b50 73 20 62 65 74 77 65 65 6e 20 74 68 65 20 55 54  s between the UT
13b60 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73 65  F-8 encoding use
13b70 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61  d by SQLite.** a
13b80 6e 64 20 77 68 61 74 65 76 65 72 20 66 69 6c 65  nd whatever file
13b90 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69 73  name encoding is
13ba0 20 75 73 65 64 20 62 79 20 74 68 65 20 70 61 72   used by the par
13bb0 74 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a  ticular Windows.
13bc0 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e  ** installation.
13bd0 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74    Memory allocat
13be0 69 6f 6e 20 65 72 72 6f 72 73 20 61 72 65 20 64  ion errors are d
13bf0 65 74 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20  etected, but.** 
13c00 74 68 65 79 20 61 72 65 20 72 65 70 6f 72 74 65  they are reporte
13c10 64 20 62 61 63 6b 20 61 73 20 5b 53 51 4c 49 54  d back as [SQLIT
13c20 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a  E_CANTOPEN] or.*
13c30 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d  * [SQLITE_IOERR]
13c40 20 72 61 74 68 65 72 20 74 68 61 6e 20 5b 53 51   rather than [SQ
13c50 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a  LITE_NOMEM]..**.
13c60 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
13c70 2a 0a 2a 2a 20 7b 46 31 37 33 30 33 7d 20 20 54  *.** {F17303}  T
13c80 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  he [sqlite3_mall
13c90 6f 63 28 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  oc(N)] interface
13ca0 20 72 65 74 75 72 6e 73 20 65 69 74 68 65 72 20   returns either 
13cb0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 0a 2a 2a  a pointer to .**
13cc0 20 20 20 20 20 20 20 20 20 20 20 6e 65 77 6c 79             newly
13cd0 20 63 68 65 63 6b 65 64 2d 6f 75 74 20 62 6c 6f   checked-out blo
13ce0 63 6b 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e  ck of at least N
13cf0 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79   bytes of memory
13d00 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 68  .**           th
13d10 61 74 20 69 73 20 38 2d 62 79 74 65 20 61 6c 69  at is 8-byte ali
13d20 67 6e 65 64 2c 20 0a 2a 2a 20 20 20 20 20 20 20  gned, .**       
13d30 20 20 20 20 6f 72 20 69 74 20 72 65 74 75 72 6e      or it return
13d40 73 20 4e 55 4c 4c 20 69 66 20 69 74 20 69 73 20  s NULL if it is 
13d50 75 6e 61 62 6c 65 20 74 6f 20 66 75 6c 66 69 6c  unable to fulfil
13d60 6c 20 74 68 65 20 72 65 71 75 65 73 74 2e 0a 2a  l the request..*
13d70 2a 0a 2a 2a 20 7b 46 31 37 33 30 34 7d 20 20 54  *.** {F17304}  T
13d80 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  he [sqlite3_mall
13d90 6f 63 28 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  oc(N)] interface
13da0 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
13db0 70 6f 69 6e 74 65 72 20 69 66 0a 2a 2a 20 20 20  pointer if.**   
13dc0 20 20 20 20 20 20 20 20 4e 20 69 73 20 6c 65 73          N is les
13dd0 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20  s than or equal 
13de0 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 7b  to zero..**.** {
13df0 46 31 37 33 30 35 7d 20 20 54 68 65 20 5b 73 71  F17305}  The [sq
13e00 6c 69 74 65 33 5f 66 72 65 65 28 50 29 5d 20 69  lite3_free(P)] i
13e10 6e 74 65 72 66 61 63 65 20 72 65 6c 65 61 73 65  nterface release
13e20 73 20 6d 65 6d 6f 72 79 20 70 72 65 76 69 6f 75  s memory previou
13e30 73 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  sly.**          
13e40 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b   returned from [
13e50 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
13e60 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
13e70 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 20 20 20  alloc()],.**    
13e80 20 20 20 20 20 20 20 6d 61 6b 69 6e 67 20 69 74         making it
13e90 20 61 76 61 69 6c 61 62 6c 65 20 66 6f 72 20 72   available for r
13ea0 65 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37  euse..**.** {F17
13eb0 33 30 36 7d 20 20 41 20 63 61 6c 6c 20 74 6f 20  306}  A call to 
13ec0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 4e 55  [sqlite3_free(NU
13ed0 4c 4c 29 5d 20 69 73 20 61 20 68 61 72 6d 6c 65  LL)] is a harmle
13ee0 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20  ss no-op..**.** 
13ef0 7b 46 31 37 33 31 30 7d 20 20 41 20 63 61 6c 6c  {F17310}  A call
13f00 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 61   to [sqlite3_rea
13f10 6c 6c 6f 63 28 30 2c 4e 29 5d 20 69 73 20 65 71  lloc(0,N)] is eq
13f20 75 69 76 61 6c 65 6e 74 20 74 6f 20 61 20 63 61  uivalent to a ca
13f30 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  ll.**           
13f40 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  to [sqlite3_mall
13f50 6f 63 28 4e 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46  oc(N)]..**.** {F
13f60 31 37 33 31 32 7d 20 20 41 20 63 61 6c 6c 20 74  17312}  A call t
13f70 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  o [sqlite3_reall
13f80 6f 63 28 50 2c 30 29 5d 20 69 73 20 65 71 75 69  oc(P,0)] is equi
13f90 76 61 6c 65 6e 74 20 74 6f 20 61 20 63 61 6c 6c  valent to a call
13fa0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 6f  .**           to
13fb0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 50   [sqlite3_free(P
13fc0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 31  )]..**.** {F1731
13fd0 35 7d 20 20 54 68 65 20 53 51 4c 69 74 65 20 63  5}  The SQLite c
13fe0 6f 72 65 20 75 73 65 73 20 5b 73 71 6c 69 74 65  ore uses [sqlite
13ff0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71  3_malloc()], [sq
14000 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
14010 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 61  ,.**           a
14020 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  nd [sqlite3_free
14030 28 29 5d 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69  ()] for all of i
14040 74 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ts memory alloca
14050 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 20 20 20 20  tion and.**     
14060 20 20 20 20 20 20 64 65 61 6c 6c 6f 63 61 74 69        deallocati
14070 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20  on needs..**.** 
14080 7b 46 31 37 33 31 38 7d 20 20 54 68 65 20 5b 73  {F17318}  The [s
14090 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 50  qlite3_realloc(P
140a0 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  ,N)] interface r
140b0 65 74 75 72 6e 73 20 65 69 74 68 65 72 20 61 20  eturns either a 
140c0 70 6f 69 6e 74 65 72 0a 2a 2a 20 20 20 20 20 20  pointer.**      
140d0 20 20 20 20 20 74 6f 20 61 20 62 6c 6f 63 6b 20       to a block 
140e0 6f 66 20 63 68 65 63 6b 65 64 2d 6f 75 74 20 6d  of checked-out m
140f0 65 6d 6f 72 79 20 6f 66 20 61 74 20 6c 65 61 73  emory of at leas
14100 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  t N bytes in siz
14110 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74  e.**           t
14120 68 61 74 20 69 73 20 38 2d 62 79 74 65 20 61 6c  hat is 8-byte al
14130 69 67 6e 65 64 2c 20 6f 72 20 61 20 4e 55 4c 4c  igned, or a NULL
14140 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
14150 7b 46 31 37 33 32 31 7d 20 20 57 68 65 6e 20 5b  {F17321}  When [
14160 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
14170 50 2c 4e 29 5d 20 72 65 74 75 72 6e 73 20 61 20  P,N)] returns a 
14180 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  non-NULL pointer
14190 2c 20 69 74 20 66 69 72 73 74 0a 2a 2a 20 20 20  , it first.**   
141a0 20 20 20 20 20 20 20 20 63 6f 70 69 65 73 20 74          copies t
141b0 68 65 20 66 69 72 73 74 20 4b 20 62 79 74 65 73  he first K bytes
141c0 20 6f 66 20 63 6f 6e 74 65 6e 74 20 66 72 6f 6d   of content from
141d0 20 50 20 69 6e 74 6f 20 74 68 65 20 6e 65 77 6c   P into the newl
141e0 79 20 61 6c 6c 6f 63 61 74 65 64 0a 2a 2a 20 20  y allocated.**  
141f0 20 20 20 20 20 20 20 20 20 77 68 65 72 65 20 4b           where K
14200 20 69 73 20 74 68 65 20 6c 65 73 73 65 72 20 6f   is the lesser o
14210 66 20 4e 20 61 6e 64 20 74 68 65 20 73 69 7a 65  f N and the size
14220 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 50   of the buffer P
14230 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 32 32 7d  ..**.** {F17322}
14240 20 20 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f    When [sqlite3_
14250 72 65 61 6c 6c 6f 63 28 50 2c 4e 29 5d 20 72 65  realloc(P,N)] re
14260 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c  turns a non-NULL
14270 20 70 6f 69 6e 74 65 72 2c 20 69 74 20 66 69 72   pointer, it fir
14280 73 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  st.**           
14290 72 65 6c 65 61 73 65 73 20 74 68 65 20 62 75 66  releases the buf
142a0 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  fer P..**.** {F1
142b0 37 33 32 33 7d 20 20 57 68 65 6e 20 5b 73 71 6c  7323}  When [sql
142c0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 50 2c 4e  ite3_realloc(P,N
142d0 29 5d 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c  )] returns NULL,
142e0 20 74 68 65 20 62 75 66 66 65 72 20 50 20 69 73   the buffer P is
142f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6e 6f  .**           no
14300 74 20 6d 6f 64 69 66 69 65 64 20 6f 72 20 72 65  t modified or re
14310 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 4c 49  leased..**.** LI
14320 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a  MITATIONS:.**.**
14330 20 7b 55 31 37 33 35 30 7d 20 20 54 68 65 20 70   {U17350}  The p
14340 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 73  ointer arguments
14350 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65   to [sqlite3_fre
14360 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
14370 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20  3_realloc()].** 
14380 20 20 20 20 20 20 20 20 20 20 6d 75 73 74 20 62            must b
14390 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72  e either NULL or
143a0 20 65 6c 73 65 20 61 20 70 6f 69 6e 74 65 72 20   else a pointer 
143b0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20  obtained from a 
143c0 70 72 69 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  prior.**        
143d0 20 20 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66     invocation of
143e0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
143f0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
14400 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20  realloc()] that 
14410 68 61 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  has.**          
14420 20 6e 6f 74 20 62 65 65 6e 20 72 65 6c 65 61 73   not been releas
14430 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 55 31 37 33 35  ed..**.** {U1735
14440 31 7d 20 20 54 68 65 20 61 70 70 6c 69 63 61 74  1}  The applicat
14450 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61  ion must not rea
14460 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70  d or write any p
14470 61 72 74 20 6f 66 20 0a 2a 2a 20 20 20 20 20 20  art of .**      
14480 20 20 20 20 20 61 20 62 6c 6f 63 6b 20 6f 66 20       a block of 
14490 6d 65 6d 6f 72 79 20 61 66 74 65 72 20 69 74 20  memory after it 
144a0 68 61 73 20 62 65 65 6e 20 72 65 6c 65 61 73 65  has been release
144b0 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20  d using.**      
144c0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 66 72       [sqlite3_fr
144d0 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ee()] or [sqlite
144e0 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a  3_realloc()]..**
144f0 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  .*/.void *sqlite
14500 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76  3_malloc(int);.v
14510 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61  oid *sqlite3_rea
14520 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29  lloc(void*, int)
14530 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66  ;.void sqlite3_f
14540 72 65 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  ree(void*);../*.
14550 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d  ** CAPI3REF: Mem
14560 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74  ory Allocator St
14570 61 74 69 73 74 69 63 73 20 7b 46 31 37 33 37 30  atistics {F17370
14580 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70  }.**.** SQLite p
14590 72 6f 76 69 64 65 73 20 74 68 65 73 65 20 74 77  rovides these tw
145a0 6f 20 69 6e 74 65 72 66 61 63 65 73 20 66 6f 72  o interfaces for
145b0 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68   reporting on th
145c0 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74  e status.** of t
145d0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  he [sqlite3_mall
145e0 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  oc()], [sqlite3_
145f0 66 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71  free()], and [sq
14600 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
14610 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  .** the memory a
14620 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73  llocation subsys
14630 74 65 6d 20 69 6e 63 6c 75 64 65 64 20 77 69 74  tem included wit
14640 68 69 6e 20 74 68 65 20 53 51 4c 69 74 65 2e 0a  hin the SQLite..
14650 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
14660 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 37 31 7d  :.**.** {F17371}
14670 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65   The [sqlite3_me
14680 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 72 6f 75  mory_used()] rou
14690 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
146a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 75 6d  .**          num
146b0 62 65 72 20 6f 66 20 62 79 74 65 73 20 6f 66 20  ber of bytes of 
146c0 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e 74 6c 79  memory currently
146d0 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 0a 2a 2a   outstanding .**
146e0 20 20 20 20 20 20 20 20 20 20 28 6d 61 6c 6c 6f            (mallo
146f0 63 65 64 20 62 75 74 20 6e 6f 74 20 66 72 65 65  ced but not free
14700 64 29 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 37  d)..**.** {F1737
14710 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  3} The [sqlite3_
14720 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
14730 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75  ()] routine retu
14740 72 6e 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a  rns the maximum.
14750 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c 75  **          valu
14760 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 65  e of [sqlite3_me
14770 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 0a 2a 2a  mory_used()] .**
14780 20 20 20 20 20 20 20 20 20 20 73 69 6e 63 65 20            since 
14790 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d  the high-water m
147a0 61 72 6b 20 77 61 73 20 6c 61 73 74 20 72 65 73  ark was last res
147b0 65 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 37  et..**.** {F1737
147c0 34 7d 20 54 68 65 20 76 61 6c 75 65 73 20 72 65  4} The values re
147d0 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
147e0 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
147f0 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20  ] and.**        
14800 20 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72    [sqlite3_memor
14810 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 69  y_highwater()] i
14820 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76 65 72 68  nclude any overh
14830 65 61 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ead.**          
14840 61 64 64 65 64 20 62 79 20 53 51 4c 69 74 65 20  added by SQLite 
14850 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74  in its implement
14860 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65  ation of [sqlite
14870 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20  3_malloc()],.** 
14880 20 20 20 20 20 20 20 20 20 62 75 74 20 6e 6f 74           but not
14890 20 6f 76 65 72 68 65 61 64 20 61 64 64 65 64 20   overhead added 
148a0 62 79 20 74 68 65 20 61 6e 79 20 75 6e 64 65 72  by the any under
148b0 6c 79 69 6e 67 20 73 79 73 74 65 6d 20 6c 69 62  lying system lib
148c0 72 61 72 79 0a 2a 2a 20 20 20 20 20 20 20 20 20  rary.**         
148d0 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 5b   routines that [
148e0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
148f0 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 20 0a  ] may call..** .
14900 2a 2a 20 7b 46 31 37 33 37 35 7d 20 54 68 65 20  ** {F17375} The 
14910 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77 61 74 65  memory high-wate
14920 72 20 6d 61 72 6b 20 69 73 20 72 65 73 65 74 20  r mark is reset 
14930 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 76  to the current v
14940 61 6c 75 65 20 6f 66 0a 2a 2a 20 20 20 20 20 20  alue of.**      
14950 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d      [sqlite3_mem
14960 6f 72 79 5f 75 73 65 64 28 29 5d 20 69 66 20 61  ory_used()] if a
14970 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70  nd only if the p
14980 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 20  arameter to.**  
14990 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
149a0 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
149b0 72 28 29 5d 20 69 73 20 74 72 75 65 2e 20 20 54  r()] is true.  T
149c0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
149d0 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 79  d.**          by
149e0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
149f0 5f 68 69 67 68 77 61 74 65 72 28 31 29 5d 20 69  _highwater(1)] i
14a00 73 20 74 68 65 20 68 69 67 68 2d 77 61 74 65 72  s the high-water
14a10 20 6d 61 72 6b 0a 2a 2a 20 20 20 20 20 20 20 20   mark.**        
14a20 20 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 72    prior to the r
14a30 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33  eset..*/.sqlite3
14a40 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d  _int64 sqlite3_m
14a50 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 29  emory_used(void)
14a60 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  ;.sqlite3_int64 
14a70 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
14a80 69 67 68 77 61 74 65 72 28 69 6e 74 20 72 65 73  ighwater(int res
14a90 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20  etFlag);../*.** 
14aa0 43 41 50 49 33 52 45 46 3a 20 50 73 65 75 64 6f  CAPI3REF: Pseudo
14ab0 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47  -Random Number G
14ac0 65 6e 65 72 61 74 6f 72 20 7b 46 31 37 33 39 30  enerator {F17390
14ad0 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63  }.**.** SQLite c
14ae0 6f 6e 74 61 69 6e 73 20 61 20 68 69 67 68 2d 71  ontains a high-q
14af0 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d 72 61  uality pseudo-ra
14b00 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65 6e 65  ndom number gene
14b10 72 61 74 6f 72 20 28 50 52 4e 47 29 20 75 73 65  rator (PRNG) use
14b20 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74 20 72  d to.** select r
14b30 61 6e 64 6f 6d 20 52 4f 57 49 44 73 20 77 68 65  andom ROWIDs whe
14b40 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e 65 77 20  n inserting new 
14b50 72 65 63 6f 72 64 73 20 69 6e 74 6f 20 61 20 74  records into a t
14b60 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72  able that.** alr
14b70 65 61 64 79 20 75 73 65 73 20 74 68 65 20 6c 61  eady uses the la
14b80 72 67 65 73 74 20 70 6f 73 73 69 62 6c 65 20 52  rgest possible R
14b90 4f 57 49 44 2e 20 20 54 68 65 20 50 52 4e 47 20  OWID.  The PRNG 
14ba0 69 73 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72  is also used for
14bb0 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e  .** the build-in
14bc0 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61   random() and ra
14bd0 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66  ndomblob() SQL f
14be0 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20  unctions.  This 
14bf0 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73  interface allows
14c00 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  .** applications
14c10 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 73   to access the s
14c20 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68  ame PRNG for oth
14c30 65 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a  er purposes..**.
14c40 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 74 68 69  ** A call to thi
14c50 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73  s routine stores
14c60 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64   N bytes of rand
14c70 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66  omness into buff
14c80 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  er P..**.** The 
14c90 66 69 72 73 74 20 74 69 6d 65 20 74 68 69 73 20  first time this 
14ca0 72 6f 75 74 69 6e 65 20 69 73 20 69 6e 76 6f 6b  routine is invok
14cb0 65 64 20 28 65 69 74 68 65 72 20 69 6e 74 65 72  ed (either inter
14cc0 6e 61 6c 6c 79 20 6f 72 20 62 79 0a 2a 2a 20 74  nally or by.** t
14cd0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 20  he application) 
14ce0 74 68 65 20 50 52 4e 47 20 69 73 20 73 65 65 64  the PRNG is seed
14cf0 65 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e  ed using randomn
14d00 65 73 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20  ess obtained.** 
14d10 66 72 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d  from the xRandom
14d20 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 74  ness method of t
14d30 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69  he default [sqli
14d40 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e  te3_vfs] object.
14d50 0a 2a 2a 20 4f 6e 20 61 6c 6c 20 73 75 62 73 65  .** On all subse
14d60 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e  quent invocation
14d70 73 2c 20 74 68 65 20 70 73 65 75 64 6f 2d 72 61  s, the pseudo-ra
14d80 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e 65  ndomness is gene
14d90 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61  rated.** interna
14da0 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f 75 74 20  lly and without 
14db0 72 65 63 6f 75 72 73 65 20 74 6f 20 74 68 65 20  recourse to the 
14dc0 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 52  [sqlite3_vfs] xR
14dd0 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74  andomness.** met
14de0 68 6f 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  hod..**.** INVAR
14df0 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31  IANTS:.**.** {F1
14e00 37 33 39 32 7d 20 54 68 65 20 5b 73 71 6c 69 74  7392} The [sqlit
14e10 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 4e 2c  e3_randomness(N,
14e20 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 72  P)] interface wr
14e30 69 74 65 73 20 4e 20 62 79 74 65 73 20 6f 66 0a  ites N bytes of.
14e40 2a 2a 20 20 20 20 20 20 20 20 20 20 68 69 67 68  **          high
14e50 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d  -quality pseudo-
14e60 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20  randomness into 
14e70 62 75 66 66 65 72 20 50 2e 0a 2a 2f 0a 76 6f 69  buffer P..*/.voi
14e80 64 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d  d sqlite3_random
14e90 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64  ness(int N, void
14ea0 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50   *P);../*.** CAP
14eb0 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54  I3REF: Compile-T
14ec0 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f  ime Authorizatio
14ed0 6e 20 43 61 6c 6c 62 61 63 6b 73 20 7b 46 31 32  n Callbacks {F12
14ee0 35 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  500}.**.** This 
14ef0 72 6f 75 74 69 6e 65 20 72 65 67 69 73 74 65 72  routine register
14f00 73 20 61 20 61 75 74 68 6f 72 69 7a 65 72 20 63  s a authorizer c
14f10 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 61 20 70  allback with a p
14f20 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61  articular.** [da
14f30 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
14f40 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20 69 6e 20  n], supplied in 
14f50 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
14f60 6e 74 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f  nt..** The autho
14f70 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
14f80 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c  s invoked as SQL
14f90 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20   statements are 
14fa0 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a  being compiled.*
14fb0 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72  * by [sqlite3_pr
14fc0 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20  epare()] or its 
14fd0 76 61 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 65  variants [sqlite
14fe0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c  3_prepare_v2()],
14ff0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
15000 70 61 72 65 31 36 28 29 5d 20 61 6e 64 20 5b 73  pare16()] and [s
15010 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
15020 5f 76 32 28 29 5d 2e 20 20 41 74 20 76 61 72 69  _v2()].  At vari
15030 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75  ous.** points du
15040 72 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61  ring the compila
15050 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73  tion process, as
15060 20 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20   logic is being 
15070 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65  created.** to pe
15080 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63  rform various ac
15090 74 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f  tions, the autho
150a0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
150b0 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20  s invoked to.** 
150c0 73 65 65 20 69 66 20 74 68 6f 73 65 20 61 63 74  see if those act
150d0 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64  ions are allowed
150e0 2e 20 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65  .  The authorize
150f0 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c  r callback shoul
15100 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c  d.** return [SQL
15110 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77  ITE_OK] to allow
15120 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51   the action, [SQ
15130 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20  LITE_IGNORE] to 
15140 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20  disallow the.** 
15150 73 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e 20  specific action 
15160 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 51  but allow the SQ
15170 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63  L statement to c
15180 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a  ontinue to be.**
15190 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53   compiled, or [S
151a0 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63  QLITE_DENY] to c
151b0 61 75 73 65 20 74 68 65 20 65 6e 74 69 72 65 20  ause the entire 
151c0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  SQL statement to
151d0 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20   be.** rejected 
151e0 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20  with an error.  
151f0 20 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a   If the authoriz
15200 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  er callback retu
15210 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65  rns.** any value
15220 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
15230 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51  ITE_IGNORE], [SQ
15240 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51  LITE_OK], or [SQ
15250 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68  LITE_DENY].** th
15260 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  en [sqlite3_prep
15270 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75  are_v2()] or equ
15280 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61  ivalent call tha
15290 74 20 74 72 69 67 67 65 72 65 64 0a 2a 2a 20 74  t triggered.** t
152a0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69  he authorizer wi
152b0 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20  ll fail with an 
152c0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a  error message..*
152d0 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61  *.** When the ca
152e0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b  llback returns [
152f0 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74  SQLITE_OK], that
15300 20 6d 65 61 6e 73 20 74 68 65 20 6f 70 65 72 61   means the opera
15310 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65  tion.** requeste
15320 64 20 69 73 20 6f 6b 2e 20 20 57 68 65 6e 20 74  d is ok.  When t
15330 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
15340 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59  rns [SQLITE_DENY
15350 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ], the.** [sqlit
15360 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
15370 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63   or equivalent c
15380 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72  all that trigger
15390 65 64 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72  ed the.** author
153a0 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77  izer will fail w
153b0 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73  ith an error mes
153c0 73 61 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 20  sage explaining 
153d0 74 68 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 69  that.** access i
153e0 73 20 64 65 6e 69 65 64 2e 20 20 49 66 20 74 68  s denied.  If th
153f0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 64  e authorizer cod
15400 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41  e is [SQLITE_REA
15410 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61  D].** and the ca
15420 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b  llback returns [
15430 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74  SQLITE_IGNORE] t
15440 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70  hen the.** [prep
15450 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
15460 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e  statement is con
15470 73 74 72 75 63 74 65 64 20 74 6f 20 73 75 62 73  structed to subs
15480 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c  titute.** a NULL
15490 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20   value in place 
154a0 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c  of the table col
154b0 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68  umn that would h
154c0 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64  ave.** been read
154d0 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20   if [SQLITE_OK] 
154e0 68 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65  had been returne
154f0 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  d.  The [SQLITE_
15500 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72  IGNORE].** retur
15510 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  n can be used to
15520 20 64 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74   deny an untrust
15530 65 64 20 75 73 65 72 20 61 63 63 65 73 73 20 74  ed user access t
15540 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20  o individual.** 
15550 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62  columns of a tab
15560 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  le..**.** The fi
15570 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
15580 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
15590 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f  callback is a co
155a0 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 74 68 69  py of.** the thi
155b0 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
155c0 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  the sqlite3_set_
155d0 61 75 74 68 6f 72 69 7a 65 72 28 29 20 69 6e 74  authorizer() int
155e0 65 72 66 61 63 65 2e 0a 2a 2a 20 54 68 65 20 73  erface..** The s
155f0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
15600 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
15610 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 0a 2a  is an integer .*
15620 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c  * [SQLITE_COPY |
15630 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68   action code] th
15640 61 74 20 73 70 65 63 69 66 69 65 73 20 74 68 65  at specifies the
15650 20 70 61 72 74 69 63 75 6c 61 72 20 61 63 74 69   particular acti
15660 6f 6e 0a 2a 2a 20 74 6f 20 62 65 20 61 75 74 68  on.** to be auth
15670 6f 72 69 7a 65 64 2e 20 54 68 65 20 74 68 69 72  orized. The thir
15680 64 20 74 68 72 6f 75 67 68 20 73 69 78 74 68 0a  d through sixth.
15690 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  ** parameters to
156a0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72   the callback ar
156b0 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  e zero-terminate
156c0 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 63  d strings that c
156d0 6f 6e 74 61 69 6e 20 0a 2a 2a 20 61 64 64 69 74  ontain .** addit
156e0 69 6f 6e 61 6c 20 64 65 74 61 69 6c 73 20 61 62  ional details ab
156f0 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20 74  out the action t
15700 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e  o be authorized.
15710 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72  .**.** An author
15720 69 7a 65 72 20 69 73 20 75 73 65 64 20 77 68 65  izer is used whe
15730 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  n [sqlite3_prepa
15740 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a  re | preparing].
15750 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
15760 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73  s from an untrus
15770 74 65 64 0a 2a 2a 20 73 6f 75 72 63 65 2c 20 74  ted.** source, t
15780 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68  o ensure that th
15790 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
157a0 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61   do not try to a
157b0 63 63 65 73 73 20 64 61 74 61 0a 2a 2a 20 74 68  ccess data.** th
157c0 61 74 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20  at they are not 
157d0 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c 20  allowed to see, 
157e0 6f 72 20 74 68 61 74 20 74 68 65 79 20 64 6f 20  or that they do 
157f0 6e 6f 74 20 74 72 79 20 74 6f 0a 2a 2a 20 65 78  not try to.** ex
15800 65 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 20  ecute malicious 
15810 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20  statements that 
15820 64 61 6d 61 67 65 20 74 68 65 20 64 61 74 61 62  damage the datab
15830 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61  ase.  For.** exa
15840 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61  mple, an applica
15850 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61  tion may allow a
15860 20 75 73 65 72 20 74 6f 20 65 6e 74 65 72 20 61   user to enter a
15870 72 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20  rbitrary.** SQL 
15880 71 75 65 72 69 65 73 20 66 6f 72 20 65 76 61 6c  queries for eval
15890 75 61 74 69 6f 6e 20 62 79 20 61 20 64 61 74 61  uation by a data
158a0 62 61 73 65 2e 20 20 42 75 74 20 74 68 65 20 61  base.  But the a
158b0 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a  pplication does.
158c0 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20  ** not want the 
158d0 75 73 65 72 20 74 6f 20 62 65 20 61 62 6c 65 20  user to be able 
158e0 74 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 61 72  to make arbitrar
158f0 79 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65  y changes to the
15900 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 41  .** database.  A
15910 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 75  n authorizer cou
15920 6c 64 20 74 68 65 6e 20 62 65 20 70 75 74 20 69  ld then be put i
15930 6e 20 70 6c 61 63 65 20 77 68 69 6c 65 20 74 68  n place while th
15940 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 65  e.** user-entere
15950 64 20 53 51 4c 20 69 73 20 62 65 69 6e 67 20 5b  d SQL is being [
15960 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20  sqlite3_prepare 
15970 7c 20 70 72 65 70 61 72 65 64 5d 20 74 68 61 74  | prepared] that
15980 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65 76  .** disallows ev
15990 65 72 79 74 68 69 6e 67 20 65 78 63 65 70 74 20  erything except 
159a0 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
159b0 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69  nts..**.** Appli
159c0 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6e 65 65  cations that nee
159d0 64 20 74 6f 20 70 72 6f 63 65 73 73 20 53 51 4c  d to process SQL
159e0 20 66 72 6f 6d 20 75 6e 74 72 75 73 74 65 64 20   from untrusted 
159f0 73 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74  sources.** might
15a00 20 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c   also consider l
15a10 6f 77 65 72 69 6e 67 20 72 65 73 6f 75 72 63 65  owering resource
15a20 20 6c 69 6d 69 74 73 20 75 73 69 6e 67 20 5b 73   limits using [s
15a30 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a  qlite3_limit()].
15a40 2a 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20  ** and limiting 
15a50 64 61 74 61 62 61 73 65 20 73 69 7a 65 20 75 73  database size us
15a60 69 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70 61 67  ing the [max_pag
15a70 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41  e_count] [PRAGMA
15a80 5d 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e  ].** in addition
15a90 20 74 6f 20 75 73 69 6e 67 20 61 6e 20 61 75 74   to using an aut
15aa0 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 4f  horizer..**.** O
15ab0 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 75 74  nly a single aut
15ac0 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 20 69  horizer can be i
15ad0 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 74  n place on a dat
15ae0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
15af0 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 20  .** at a time.  
15b00 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c  Each call to sql
15b10 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
15b20 7a 65 72 20 6f 76 65 72 72 69 64 65 73 20 74 68  zer overrides th
15b30 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 61  e.** previous ca
15b40 6c 6c 2e 20 20 44 69 73 61 62 6c 65 20 74 68 65  ll.  Disable the
15b50 20 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20 69   authorizer by i
15b60 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c  nstalling a NULL
15b70 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68   callback..** Th
15b80 65 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20  e authorizer is 
15b90 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
15ba0 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  ult..**.** Note 
15bb0 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69  that the authori
15bc0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
15bd0 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72  invoked only dur
15be0 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ing .** [sqlite3
15bf0 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69  _prepare()] or i
15c00 74 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75  ts variants.  Au
15c10 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e  thorization is n
15c20 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20  ot.** performed 
15c30 64 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  during statement
15c40 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b   evaluation in [
15c50 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
15c60 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
15c70 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 30 31  S:.**.** {F12501
15c80 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  } The [sqlite3_s
15c90 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 44 2c  et_authorizer(D,
15ca0 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  ...)] interface 
15cb0 72 65 67 69 73 74 65 72 73 20 61 0a 2a 2a 20 20  registers a.**  
15cc0 20 20 20 20 20 20 20 20 61 75 74 68 6f 72 69 7a          authoriz
15cd0 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68  er callback with
15ce0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
15cf0 74 69 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46  tion D..**.** {F
15d00 31 32 35 30 32 7d 20 54 68 65 20 61 75 74 68 6f  12502} The autho
15d10 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
15d20 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c  s invoked as SQL
15d30 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 0a   statements are.
15d40 2a 2a 20 20 20 20 20 20 20 20 20 20 62 65 69 6e  **          bein
15d50 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 0a 2a 2a  g compiled.**.**
15d60 20 7b 46 31 32 35 30 33 7d 20 49 66 20 74 68 65   {F12503} If the
15d70 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
15d80 62 61 63 6b 20 72 65 74 75 72 6e 73 20 61 6e 79  back returns any
15d90 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61   value other tha
15da0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53  n.**          [S
15db0 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b  QLITE_IGNORE], [
15dc0 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b  SQLITE_OK], or [
15dd0 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 68 65  SQLITE_DENY] the
15de0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  n.**          th
15df0 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  e [sqlite3_prepa
15e00 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69  re_v2()] or equi
15e10 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74  valent call that
15e20 20 63 61 75 73 65 64 0a 2a 2a 20 20 20 20 20 20   caused.**      
15e30 20 20 20 20 74 68 65 20 61 75 74 68 6f 72 69 7a      the authoriz
15e40 65 72 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 72  er callback to r
15e50 75 6e 20 73 68 61 6c 6c 20 66 61 69 6c 20 77 69  un shall fail wi
15e60 74 68 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20  th an.**        
15e70 20 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d    [SQLITE_ERROR]
15e80 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20   error code and 
15e90 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 65  an appropriate e
15ea0 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a  rror message..**
15eb0 0a 2a 2a 20 7b 46 31 32 35 30 34 7d 20 57 68 65  .** {F12504} Whe
15ec0 6e 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  n the authorizer
15ed0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
15ee0 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74  s [SQLITE_OK], t
15ef0 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20  he operation.** 
15f00 20 20 20 20 20 20 20 20 20 64 65 73 63 72 69 62           describ
15f10 65 64 20 69 73 20 63 6f 64 65 64 20 6e 6f 72 6d  ed is coded norm
15f20 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  ally..**.** {F12
15f30 35 30 35 7d 20 57 68 65 6e 20 74 68 65 20 61 75  505} When the au
15f40 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
15f50 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  k returns [SQLIT
15f60 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20  E_DENY], the.** 
15f70 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
15f80 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
15f90 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61  or equivalent ca
15fa0 6c 6c 20 74 68 61 74 20 63 61 75 73 65 64 20 74  ll that caused t
15fb0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  he.**          a
15fc0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
15fd0 63 6b 20 74 6f 20 72 75 6e 20 73 68 61 6c 6c 20  ck to run shall 
15fe0 66 61 69 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20  fail.**         
15ff0 20 77 69 74 68 20 61 6e 20 5b 53 51 4c 49 54 45   with an [SQLITE
16000 5f 45 52 52 4f 52 5d 20 65 72 72 6f 72 20 63 6f  _ERROR] error co
16010 64 65 20 61 6e 64 20 61 6e 20 65 72 72 6f 72 20  de and an error 
16020 6d 65 73 73 61 67 65 0a 2a 2a 20 20 20 20 20 20  message.**      
16030 20 20 20 20 65 78 70 6c 61 69 6e 69 6e 67 20 74      explaining t
16040 68 61 74 20 61 63 63 65 73 73 20 69 73 20 64 65  hat access is de
16050 6e 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  nied..**.** {F12
16060 35 30 36 7d 20 49 66 20 74 68 65 20 61 75 74 68  506} If the auth
16070 6f 72 69 7a 65 72 20 63 6f 64 65 20 28 74 68 65  orizer code (the
16080 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74   2nd parameter t
16090 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  o the authorizer
160a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c  .**          cal
160b0 6c 62 61 63 6b 29 20 69 73 20 5b 53 51 4c 49 54  lback) is [SQLIT
160c0 45 5f 52 45 41 44 5d 20 61 6e 64 20 74 68 65 20  E_READ] and the 
160d0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
160e0 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20  ack returns.**  
160f0 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f          [SQLITE_
16100 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65  IGNORE] then the
16110 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
16120 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74  ent is construct
16130 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20  ed to.**        
16140 20 20 69 6e 73 65 72 74 20 61 20 4e 55 4c 4c 20    insert a NULL 
16150 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f  value in place o
16160 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75  f the table colu
16170 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61  mn that would ha
16180 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62  ve.**          b
16190 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51 4c  een read if [SQL
161a0 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e  ITE_OK] had been
161b0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
161c0 20 7b 46 31 32 35 30 37 7d 20 49 66 20 74 68 65   {F12507} If the
161d0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 64 65   authorizer code
161e0 20 28 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65   (the 2nd parame
161f0 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f  ter to the autho
16200 72 69 7a 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  rizer.**        
16210 20 20 63 61 6c 6c 62 61 63 6b 29 20 69 73 20 61    callback) is a
16220 6e 79 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68  nything other th
16230 61 6e 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d  an [SQLITE_READ]
16240 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20  , then.**       
16250 20 20 20 61 20 72 65 74 75 72 6e 20 6f 66 20 5b     a return of [
16260 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 68  SQLITE_IGNORE] h
16270 61 73 20 74 68 65 20 73 61 6d 65 20 65 66 66 65  as the same effe
16280 63 74 20 61 73 20 5b 53 51 4c 49 54 45 5f 44 45  ct as [SQLITE_DE
16290 4e 59 5d 2e 20 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  NY]. .**.** {F12
162a0 35 31 30 7d 20 54 68 65 20 66 69 72 73 74 20 70  510} The first p
162b0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
162c0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
162d0 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ack is a copy of
162e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
162f0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
16300 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
16310 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
16320 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  )] interface..**
16330 0a 2a 2a 20 7b 46 31 32 35 31 31 7d 20 54 68 65  .** {F12511} The
16340 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
16350 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  r to the callbac
16360 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  k is an integer 
16370 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51  .**          [SQ
16380 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69  LITE_COPY | acti
16390 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70  on code] that sp
163a0 65 63 69 66 69 65 73 20 74 68 65 20 70 61 72 74  ecifies the part
163b0 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 0a 2a 2a  icular action.**
163c0 20 20 20 20 20 20 20 20 20 20 74 6f 20 62 65 20            to be 
163d0 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a  authorized..**.*
163e0 2a 20 7b 46 31 32 35 31 32 7d 20 54 68 65 20 74  * {F12512} The t
163f0 68 69 72 64 20 74 68 72 6f 75 67 68 20 73 69 78  hird through six
16400 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  th parameters to
16410 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72   the callback ar
16420 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65  e.**          ze
16430 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74  ro-terminated st
16440 72 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61  rings that conta
16450 69 6e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  in .**          
16460 61 64 64 69 74 69 6f 6e 61 6c 20 64 65 74 61 69  additional detai
16470 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61 63 74  ls about the act
16480 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72  ion to be author
16490 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  ized..**.** {F12
164a0 35 32 30 7d 20 45 61 63 68 20 63 61 6c 6c 20 74  520} Each call t
164b0 6f 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  o [sqlite3_set_a
164c0 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 6f 76 65  uthorizer()] ove
164d0 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 20 20  rrides the.**   
164e0 20 20 20 20 20 20 20 61 6e 79 20 70 72 65 76 69         any previ
164f0 6f 75 73 6c 79 20 69 6e 73 74 61 6c 6c 65 64 20  ously installed 
16500 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a  authorizer..**.*
16510 2a 20 7b 46 31 32 35 32 31 7d 20 41 20 4e 55 4c  * {F12521} A NUL
16520 4c 20 61 75 74 68 6f 72 69 7a 65 72 20 6d 65 61  L authorizer mea
16530 6e 73 20 74 68 61 74 20 6e 6f 20 61 75 74 68 6f  ns that no autho
16540 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 20 20 20 20  rization.**     
16550 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 20 69 73       callback is
16560 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20   invoked..**.** 
16570 7b 46 31 32 35 32 32 7d 20 54 68 65 20 64 65 66  {F12522} The def
16580 61 75 6c 74 20 61 75 74 68 6f 72 69 7a 65 72 20  ault authorizer 
16590 69 73 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20  is NULL..*/.int 
165a0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
165b0 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 65  orizer(.  sqlite
165c0 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 74  3*,.  int (*xAut
165d0 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  h)(void*,int,con
165e0 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  st char*,const c
165f0 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
16600 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20  ,const char*),. 
16610 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61 74 61   void *pUserData
16620 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
16630 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20  REF: Authorizer 
16640 52 65 74 75 72 6e 20 43 6f 64 65 73 20 7b 46 31  Return Codes {F1
16650 32 35 39 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20  2590}.**.** The 
16660 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
16670 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72  horizer | author
16680 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75  izer callback fu
16690 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20  nction] must.** 
166a0 72 65 74 75 72 6e 20 65 69 74 68 65 72 20 5b 53  return either [S
166b0 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65  QLITE_OK] or one
166c0 20 6f 66 20 74 68 65 73 65 20 74 77 6f 20 63 6f   of these two co
166d0 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 72  nstants in order
166e0 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 51  .** to signal SQ
166f0 4c 69 74 65 20 77 68 65 74 68 65 72 20 6f 72 20  Lite whether or 
16700 6e 6f 74 20 74 68 65 20 61 63 74 69 6f 6e 20 69  not the action i
16710 73 20 70 65 72 6d 69 74 74 65 64 2e 20 20 53 65  s permitted.  Se
16720 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  e the.** [sqlite
16730 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
16740 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 64 6f   | authorizer do
16750 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72  cumentation] for
16760 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69   additional.** i
16770 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 23  nformation..*/.#
16780 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
16790 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72  NY   1   /* Abor
167a0 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  t the SQL statem
167b0 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ent with an erro
167c0 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  r */.#define SQL
167d0 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f  ITE_IGNORE 2   /
167e0 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63  * Don't allow ac
167f0 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20  cess, but don't 
16800 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f  generate an erro
16810 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  r */../*.** CAPI
16820 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72  3REF: Authorizer
16830 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 20 7b 46   Action Codes {F
16840 31 32 35 35 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  12550}.**.** The
16850 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
16860 74 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65  thorizer()] inte
16870 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20  rface registers 
16880 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  a callback funct
16890 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 69  ion.** that is i
168a0 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f 72  nvoked to author
168b0 69 7a 65 72 20 63 65 72 74 61 69 6e 20 53 51 4c  izer certain SQL
168c0 20 73 74 61 74 65 6d 65 6e 74 20 61 63 74 69 6f   statement actio
168d0 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f  ns.  The.** seco
168e0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
168f0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  the callback is 
16900 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20  an integer code 
16910 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a  that specifies.*
16920 2a 20 77 68 61 74 20 61 63 74 69 6f 6e 20 69 73  * what action is
16930 20 62 65 69 6e 67 20 61 75 74 68 6f 72 69 7a 65   being authorize
16940 64 2e 20 20 54 68 65 73 65 20 61 72 65 20 74 68  d.  These are th
16950 65 20 69 6e 74 65 67 65 72 20 61 63 74 69 6f 6e  e integer action
16960 20 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a 20 74   codes that.** t
16970 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
16980 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65 20 70 61  llback may be pa
16990 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ssed..**.** Thes
169a0 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 76 61  e action code va
169b0 6c 75 65 73 20 73 69 67 6e 69 66 79 20 77 68 61  lues signify wha
169c0 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72 61 74  t kind of operat
169d0 69 6f 6e 20 69 73 20 74 6f 20 62 65 20 0a 2a 2a  ion is to be .**
169e0 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68   authorized.  Th
169f0 65 20 33 72 64 20 61 6e 64 20 34 74 68 20 70 61  e 3rd and 4th pa
16a00 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20  rameters to the 
16a10 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a  authorization.**
16a20 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
16a30 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 72 61 6d  on will be param
16a40 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65  eters or NULL de
16a50 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63 68  pending on which
16a60 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64   of these.** cod
16a70 65 73 20 69 73 20 75 73 65 64 20 61 73 20 74 68  es is used as th
16a80 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
16a90 65 72 2e 20 20 54 68 65 20 35 74 68 20 70 61 72  er.  The 5th par
16aa0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a  ameter to the.**
16ab0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
16ac0 62 61 63 6b 20 69 73 20 74 68 65 20 6e 61 6d 65  back is the name
16ad0 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
16ae0 20 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22   ("main", "temp"
16af0 2c 20 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20 61  , .** etc.) if a
16b00 70 70 6c 69 63 61 62 6c 65 2e 20 20 54 68 65 20  pplicable.  The 
16b10 36 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  6th parameter to
16b20 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
16b30 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74  callback.** is t
16b40 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 69  he name of the i
16b50 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65  nner-most trigge
16b60 72 20 6f 72 20 76 69 65 77 20 74 68 61 74 20 69  r or view that i
16b70 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
16b80 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73 20  r.** the access 
16b90 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20  attempt or NULL 
16ba0 69 66 20 74 68 69 73 20 61 63 63 65 73 73 20 61  if this access a
16bb0 74 74 65 6d 70 74 20 69 73 20 64 69 72 65 63 74  ttempt is direct
16bc0 6c 79 20 66 72 6f 6d 20 0a 2a 2a 20 74 6f 70 2d  ly from .** top-
16bd0 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a  level SQL code..
16be0 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
16bf0 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 35 31 7d  :.**.** {F12551}
16c00 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
16c10 6d 65 74 65 72 20 74 6f 20 61 6e 20 0a 2a 2a 20  meter to an .** 
16c20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
16c30 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
16c40 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61   | authorizer ca
16c50 6c 6c 62 61 63 6b 5d 20 69 73 20 61 6c 77 61 79  llback] is alway
16c60 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20  s an integer.** 
16c70 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45           [SQLITE
16c80 5f 43 4f 50 59 20 7c 20 61 75 74 68 6f 72 69 7a  _COPY | authoriz
16c90 65 72 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70  er code] that sp
16ca0 65 63 69 66 69 65 73 20 77 68 61 74 20 61 63 74  ecifies what act
16cb0 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ion.**          
16cc0 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72 69  is being authori
16cd0 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35  zed..**.** {F125
16ce0 35 32 7d 20 54 68 65 20 33 72 64 20 61 6e 64 20  52} The 3rd and 
16cf0 34 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74  4th parameters t
16d00 6f 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 20 20  o the .**       
16d10 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f     [sqlite3_set_
16d20 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74  authorizer | aut
16d30 68 6f 72 69 7a 61 74 69 6f 6e 20 63 61 6c 6c 62  horization callb
16d40 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 0a 2a 2a  ack function].**
16d50 20 20 20 20 20 20 20 20 20 20 77 69 6c 6c 20 62            will b
16d60 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20  e parameters or 
16d70 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f  NULL depending o
16d80 6e 20 77 68 69 63 68 20 0a 2a 2a 20 20 20 20 20  n which .**     
16d90 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 43 4f 50       [SQLITE_COP
16da0 59 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63  Y | authorizer c
16db0 6f 64 65 5d 20 69 73 20 75 73 65 64 20 61 73 20  ode] is used as 
16dc0 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
16dd0 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  eter..**.** {F12
16de0 35 35 33 7d 20 54 68 65 20 35 74 68 20 70 61 72  553} The 5th par
16df0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a  ameter to the.**
16e00 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
16e10 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
16e20 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63  r | authorizer c
16e30 61 6c 6c 62 61 63 6b 5d 20 69 73 20 74 68 65 20  allback] is the 
16e40 6e 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  name.**         
16e50 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
16e60 20 28 65 78 61 6d 70 6c 65 3a 20 22 6d 61 69 6e   (example: "main
16e70 22 2c 20 22 74 65 6d 70 22 2c 20 65 74 63 2e 29  ", "temp", etc.)
16e80 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 0a   if applicable..
16e90 2a 2a 0a 2a 2a 20 7b 46 31 32 35 35 34 7d 20 54  **.** {F12554} T
16ea0 68 65 20 36 74 68 20 70 61 72 61 6d 65 74 65 72  he 6th parameter
16eb0 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   to the.**      
16ec0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 65 74      [sqlite3_set
16ed0 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75  _authorizer | au
16ee0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
16ef0 6b 5d 20 69 73 20 74 68 65 20 6e 61 6d 65 0a 2a  k] is the name.*
16f00 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 74 68  *          of th
16f10 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69  e inner-most tri
16f20 67 67 65 72 20 6f 72 20 76 69 65 77 20 74 68 61  gger or view tha
16f30 74 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65  t is responsible
16f40 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20   for.**         
16f50 20 74 68 65 20 61 63 63 65 73 73 20 61 74 74 65   the access atte
16f60 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74  mpt or NULL if t
16f70 68 69 73 20 61 63 63 65 73 73 20 61 74 74 65 6d  his access attem
16f80 70 74 20 69 73 20 64 69 72 65 63 74 6c 79 20 66  pt is directly f
16f90 72 6f 6d 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  rom .**         
16fa0 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63   top-level SQL c
16fb0 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a  ode..*/./*******
16fc0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
16fd0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
16fe0 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a  **** 3rd *******
16ff0 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a  ***** 4th ******
17000 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  *****/.#define S
17010 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e 44  QLITE_CREATE_IND
17020 45 58 20 20 20 20 20 20 20 20 20 20 31 20 20 20  EX          1   
17030 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
17040 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
17050 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
17060 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42 4c  LITE_CREATE_TABL
17070 45 20 20 20 20 20 20 20 20 20 20 32 20 20 20 2f  E          2   /
17080 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
17090 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
170a0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
170b0 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
170c0 49 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f 2a  INDEX     3   /*
170d0 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
170e0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
170f0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
17100 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54  TE_CREATE_TEMP_T
17110 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a 20  ABLE     4   /* 
17120 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
17130 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
17140 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
17150 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 52  E_CREATE_TEMP_TR
17160 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20 54  IGGER   5   /* T
17170 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
17180 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
17190 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
171a0 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 45  _CREATE_TEMP_VIE
171b0 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56 69  W      6   /* Vi
171c0 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
171d0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
171e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
171f0 43 52 45 41 54 45 5f 54 52 49 47 47 45 52 20 20  CREATE_TRIGGER  
17200 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72 69        7   /* Tri
17210 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
17220 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
17230 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
17240 52 45 41 54 45 5f 56 49 45 57 20 20 20 20 20 20  REATE_VIEW      
17250 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65 77       8   /* View
17260 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
17270 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
17280 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
17290 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20  LETE            
172a0 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 65      9   /* Table
172b0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
172c0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
172d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
172e0 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20  P_INDEX         
172f0 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 20    10   /* Index 
17300 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
17310 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
17320 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
17330 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  _TABLE          
17340 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   11   /* Table N
17350 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
17360 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
17370 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
17380 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 20  TEMP_INDEX      
17390 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61  12   /* Index Na
173a0 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
173b0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
173c0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
173d0 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20 31  EMP_TABLE      1
173e0 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  3   /* Table Nam
173f0 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
17400 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
17410 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
17420 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20 31 34  MP_TRIGGER    14
17430 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
17440 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
17450 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
17460 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d   SQLITE_DROP_TEM
17470 50 5f 56 49 45 57 20 20 20 20 20 20 20 31 35 20  P_VIEW       15 
17480 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
17490 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
174a0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
174b0 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 47  SQLITE_DROP_TRIG
174c0 47 45 52 20 20 20 20 20 20 20 20 20 31 36 20 20  GER         16  
174d0 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
174e0 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
174f0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
17500 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 20  QLITE_DROP_VIEW 
17510 20 20 20 20 20 20 20 20 20 20 20 31 37 20 20 20             17   
17520 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
17530 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
17540 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
17550 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20 20  LITE_INSERT     
17560 20 20 20 20 20 20 20 20 20 20 31 38 20 20 20 2f            18   /
17570 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
17580 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
17590 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
175a0 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20 20  ITE_PRAGMA      
175b0 20 20 20 20 20 20 20 20 20 31 39 20 20 20 2f 2a           19   /*
175c0 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 20   Pragma Name    
175d0 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c   1st arg or NULL
175e0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
175f0 54 45 5f 52 45 41 44 20 20 20 20 20 20 20 20 20  TE_READ         
17600 20 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20          20   /* 
17610 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
17620 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20  Column Name     
17630 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
17640 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20  E_SELECT        
17650 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4e         21   /* N
17660 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e  ULL            N
17670 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
17680 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
17690 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 20  _TRANSACTION    
176a0 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4e 55        22   /* NU
176b0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e 55  LL            NU
176c0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
176d0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
176e0 55 50 44 41 54 45 20 20 20 20 20 20 20 20 20 20  UPDATE          
176f0 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61 62       23   /* Tab
17700 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c  le Name      Col
17710 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  umn Name     */.
17720 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
17730 54 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20  TTACH           
17740 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 65      24   /* File
17750 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c 4c  name        NULL
17760 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
17770 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
17780 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20  TACH            
17790 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61 62     25   /* Datab
177a0 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20  ase Name   NULL 
177b0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
177c0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54  efine SQLITE_ALT
177d0 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20  ER_TABLE        
177e0 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62 61    26   /* Databa
177f0 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 20  se Name   Table 
17800 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
17810 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 4e  fine SQLITE_REIN
17820 44 45 58 20 20 20 20 20 20 20 20 20 20 20 20 20  DEX             
17830 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e   27   /* Index N
17840 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
17850 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
17860 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59  ine SQLITE_ANALY
17870 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ZE              
17880 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  28   /* Table Na
17890 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
178a0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
178b0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
178c0 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 32  _VTABLE        2
178d0 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  9   /* Table Nam
178e0 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61  e      Module Na
178f0 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
17900 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54  e SQLITE_DROP_VT
17910 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 33 30  ABLE          30
17920 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
17930 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d        Module Nam
17940 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
17950 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e   SQLITE_FUNCTION
17960 20 20 20 20 20 20 20 20 20 20 20 20 20 33 31 20               31 
17970 20 20 2f 2a 20 46 75 6e 63 74 69 6f 6e 20 4e 61    /* Function Na
17980 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20  me   NULL       
17990 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
179a0 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20  SQLITE_COPY     
179b0 20 20 20 20 20 20 20 20 20 20 20 20 20 30 20 20               0  
179c0 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73   /* No longer us
179d0 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ed */../*.** CAP
179e0 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41  I3REF: Tracing A
179f0 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e  nd Profiling Fun
17a00 63 74 69 6f 6e 73 20 7b 46 31 32 32 38 30 7d 0a  ctions {F12280}.
17a10 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
17a20 69 6e 65 73 20 72 65 67 69 73 74 65 72 20 63 61  ines register ca
17a30 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73  llback functions
17a40 20 74 68 61 74 20 63 61 6e 20 62 65 20 75 73 65   that can be use
17a50 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67  d for.** tracing
17a60 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 74   and profiling t
17a70 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20  he execution of 
17a80 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  SQL statements..
17a90 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61  **.** The callba
17aa0 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69  ck function regi
17ab0 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65  stered by sqlite
17ac0 33 5f 74 72 61 63 65 28 29 20 69 73 20 69 6e 76  3_trace() is inv
17ad0 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f  oked at.** vario
17ae0 75 73 20 74 69 6d 65 73 20 77 68 65 6e 20 61 6e  us times when an
17af0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69   SQL statement i
17b00 73 20 62 65 69 6e 67 20 72 75 6e 20 62 79 20 5b  s being run by [
17b10 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
17b20 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b  .** The callback
17b30 20 72 65 74 75 72 6e 73 20 61 20 55 54 46 2d 38   returns a UTF-8
17b40 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68   rendering of th
17b50 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
17b60 74 65 78 74 0a 2a 2a 20 61 73 20 74 68 65 20 73  text.** as the s
17b70 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20 62  tatement first b
17b80 65 67 69 6e 73 20 65 78 65 63 75 74 69 6e 67 2e  egins executing.
17b90 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 63 61 6c    Additional cal
17ba0 6c 62 61 63 6b 73 20 6f 63 63 75 72 0a 2a 2a 20  lbacks occur.** 
17bb0 61 73 20 65 61 63 68 20 74 72 69 67 67 65 72 65  as each triggere
17bc0 64 20 73 75 62 70 72 6f 67 72 61 6d 20 69 73 20  d subprogram is 
17bd0 65 6e 74 65 72 65 64 2e 20 20 54 68 65 20 63 61  entered.  The ca
17be0 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74 72 69 67  llbacks for trig
17bf0 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20  gers.** contain 
17c00 61 20 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d  a UTF-8 SQL comm
17c10 65 6e 74 20 74 68 61 74 20 69 64 65 6e 74 69 66  ent that identif
17c20 69 65 73 20 74 68 65 20 74 72 69 67 67 65 72 2e  ies the trigger.
17c30 0a 2a 2a 20 0a 2a 2a 20 54 68 65 20 63 61 6c 6c  .** .** The call
17c40 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65  back function re
17c50 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69  gistered by sqli
17c60 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 69 73  te3_profile() is
17c70 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65   invoked.** as e
17c80 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ach SQL statemen
17c90 74 20 66 69 6e 69 73 68 65 73 2e 20 20 54 68 65  t finishes.  The
17ca0 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63   profile callbac
17cb0 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68  k contains.** th
17cc0 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65  e original state
17cd0 6d 65 6e 74 20 74 65 78 74 20 61 6e 64 20 61 6e  ment text and an
17ce0 20 65 73 74 69 6d 61 74 65 20 6f 66 20 77 61 6c   estimate of wal
17cf0 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20  l-clock time.** 
17d00 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74  of how long that
17d10 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20   statement took 
17d20 74 6f 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  to run..**.** Th
17d30 65 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c  e sqlite3_profil
17d40 65 28 29 20 41 50 49 20 69 73 20 63 75 72 72 65  e() API is curre
17d50 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 64 20  ntly considered 
17d60 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64  experimental and
17d70 0a 2a 2a 20 69 73 20 73 75 62 6a 65 63 74 20 74  .** is subject t
17d80 6f 20 63 68 61 6e 67 65 20 6f 72 20 72 65 6d 6f  o change or remo
17d90 76 61 6c 20 69 6e 20 61 20 66 75 74 75 72 65 20  val in a future 
17da0 72 65 6c 65 61 73 65 2e 0a 2a 2a 0a 2a 2a 20 54  release..**.** T
17db0 68 65 20 74 72 69 67 67 65 72 20 72 65 70 6f 72  he trigger repor
17dc0 74 69 6e 67 20 66 65 61 74 75 72 65 20 6f 66 20  ting feature of 
17dd0 74 68 65 20 74 72 61 63 65 20 63 61 6c 6c 62 61  the trace callba
17de0 63 6b 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64  ck is considered
17df0 0a 2a 2a 20 65 78 70 65 72 69 6d 65 6e 74 61 6c  .** experimental
17e00 20 61 6e 64 20 69 73 20 73 75 62 6a 65 63 74 20   and is subject 
17e10 74 6f 20 63 68 61 6e 67 65 20 6f 72 20 72 65 6d  to change or rem
17e20 6f 76 61 6c 20 69 6e 20 66 75 74 75 72 65 20 72  oval in future r
17e30 65 6c 65 61 73 65 73 2e 0a 2a 2a 20 46 75 74 75  eleases..** Futu
17e40 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
17e50 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f  QLite might also
17e60 20 61 64 64 20 6e 65 77 20 74 72 61 63 65 20 63   add new trace c
17e70 61 6c 6c 62 61 63 6b 20 0a 2a 2a 20 69 6e 76 6f  allback .** invo
17e80 63 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49  cations..**.** I
17e90 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
17ea0 20 7b 46 31 32 32 38 31 7d 20 54 68 65 20 63 61   {F12281} The ca
17eb0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
17ec0 72 65 67 69 73 74 65 72 65 64 20 62 79 20 5b 73  registered by [s
17ed0 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 5d 20  qlite3_trace()] 
17ee0 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77  is.**          w
17ef0 68 65 6e 65 76 65 72 20 61 6e 20 53 51 4c 20 73  henever an SQL s
17f00 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20 62  tatement first b
17f10 65 67 69 6e 73 20 74 6f 20 65 78 65 63 75 74 65  egins to execute
17f20 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20   and.**         
17f30 20 77 68 65 6e 65 76 65 72 20 61 20 74 72 69 67   whenever a trig
17f40 67 65 72 20 73 75 62 70 72 6f 67 72 61 6d 20 66  ger subprogram f
17f50 69 72 73 74 20 62 65 67 69 6e 73 20 74 6f 20 72  irst begins to r
17f60 75 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 38  un..**.** {F1228
17f70 32 7d 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20  2} Each call to 
17f80 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29  [sqlite3_trace()
17f90 5d 20 6f 76 65 72 72 69 64 65 73 20 74 68 65 20  ] overrides the 
17fa0 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a 20 20 20  previously.**   
17fb0 20 20 20 20 20 20 20 72 65 67 69 73 74 65 72 65         registere
17fc0 64 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b  d trace callback
17fd0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 38 33 7d  ..**.** {F12283}
17fe0 20 41 20 4e 55 4c 4c 20 74 72 61 63 65 20 63 61   A NULL trace ca
17ff0 6c 6c 62 61 63 6b 20 64 69 73 61 62 6c 65 73 20  llback disables 
18000 74 72 61 63 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b  tracing..**.** {
18010 46 31 32 32 38 34 7d 20 54 68 65 20 66 69 72 73  F12284} The firs
18020 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
18030 65 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b  e trace callback
18040 20 69 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a   is a copy of.**
18050 20 20 20 20 20 20 20 20 20 20 74 68 65 20 70 6f            the po
18060 69 6e 74 65 72 20 77 68 69 63 68 20 77 61 73 20  inter which was 
18070 74 68 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74  the 3rd argument
18080 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74 72 61   to [sqlite3_tra
18090 63 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  ce()]..**.** {F1
180a0 32 32 38 35 7d 20 54 68 65 20 73 65 63 6f 6e 64  2285} The second
180b0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
180c0 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 20   trace callback 
180d0 69 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20  is a.**         
180e0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
180f0 20 55 54 46 38 20 73 74 72 69 6e 67 20 63 6f 6e   UTF8 string con
18100 74 61 69 6e 69 6e 67 20 74 68 65 20 6f 72 69 67  taining the orig
18110 69 6e 61 6c 20 74 65 78 74 0a 2a 2a 20 20 20 20  inal text.**    
18120 20 20 20 20 20 20 6f 66 20 74 68 65 20 53 51 4c        of the SQL
18130 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20 69 74   statement as it
18140 20 77 61 73 20 70 61 73 73 65 64 20 69 6e 74 6f   was passed into
18150 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
18160 65 5f 76 32 28 29 5d 0a 2a 2a 20 20 20 20 20 20  e_v2()].**      
18170 20 20 20 20 6f 72 20 74 68 65 20 65 71 75 69 76      or the equiv
18180 61 6c 65 6e 74 2c 20 6f 72 20 61 6e 20 53 51 4c  alent, or an SQL
18190 20 63 6f 6d 6d 65 6e 74 20 69 6e 64 69 63 61 74   comment indicat
181a0 69 6e 67 20 74 68 65 20 62 65 67 69 6e 6e 69 6e  ing the beginnin
181b0 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66  g.**          of
181c0 20 61 20 74 72 69 67 67 65 72 20 73 75 62 70 72   a trigger subpr
181d0 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  ogram..**.** {F1
181e0 32 32 38 37 7d 20 54 68 65 20 63 61 6c 6c 62 61  2287} The callba
181f0 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69  ck function regi
18200 73 74 65 72 65 64 20 62 79 20 5b 73 71 6c 69 74  stered by [sqlit
18210 65 33 5f 70 72 6f 66 69 6c 65 28 29 5d 20 69 73  e3_profile()] is
18220 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 20 20 20 20   invoked.**     
18230 20 20 20 20 20 61 73 20 65 61 63 68 20 53 51 4c       as each SQL
18240 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73   statement finis
18250 68 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32  hes..**.** {F122
18260 38 38 7d 20 54 68 65 20 66 69 72 73 74 20 70 61  88} The first pa
18270 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 70  rameter to the p
18280 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20  rofile callback 
18290 69 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20  is a copy of.** 
182a0 20 20 20 20 20 20 20 20 20 74 68 65 20 33 72 64           the 3rd
182b0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
182c0 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29  qlite3_profile()
182d0 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 38 39  ]..**.** {F12289
182e0 7d 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72  } The second par
182f0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 70 72  ameter to the pr
18300 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 69  ofile callback i
18310 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  s a.**          
18320 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
18330 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68 61  UTF-8 string tha
18340 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 63  t contains the c
18350 6f 6d 70 6c 65 74 65 20 74 65 78 74 20 6f 66 0a  omplete text of.
18360 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
18370 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73  SQL statement as
18380 20 69 74 20 77 61 73 20 70 72 6f 63 65 73 73 65   it was processe
18390 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72  d by [sqlite3_pr
183a0 65 70 61 72 65 5f 76 32 28 29 5d 0a 2a 2a 20 20  epare_v2()].**  
183b0 20 20 20 20 20 20 20 20 6f 72 20 74 68 65 20 65          or the e
183c0 71 75 69 76 61 6c 65 6e 74 2e 0a 2a 2a 0a 2a 2a  quivalent..**.**
183d0 20 7b 46 31 32 32 39 30 7d 20 54 68 65 20 74 68   {F12290} The th
183e0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
183f0 20 74 68 65 20 70 72 6f 66 69 6c 65 20 20 63 61   the profile  ca
18400 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 65 73 74  llback is an est
18410 69 6d 61 74 65 0a 2a 2a 20 20 20 20 20 20 20 20  imate.**        
18420 20 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20    of the number 
18430 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 20 6f  of nanoseconds o
18440 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d  f wall-clock tim
18450 65 20 72 65 71 75 69 72 65 64 20 74 6f 0a 2a 2a  e required to.**
18460 20 20 20 20 20 20 20 20 20 20 72 75 6e 20 74 68            run th
18470 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
18480 66 72 6f 6d 20 73 74 61 72 74 20 74 6f 20 66 69  from start to fi
18490 6e 69 73 68 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73  nish..*/.void *s
184a0 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c  qlite3_trace(sql
184b0 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72  ite3*, void(*xTr
184c0 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74  ace)(void*,const
184d0 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b   char*), void*);
184e0 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70  .void *sqlite3_p
184f0 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c  rofile(sqlite3*,
18500 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69  .   void(*xProfi
18510 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20  le)(void*,const 
18520 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69  char*,sqlite3_ui
18530 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a  nt64), void*);..
18540 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
18550 51 75 65 72 79 20 50 72 6f 67 72 65 73 73 20 43  Query Progress C
18560 61 6c 6c 62 61 63 6b 73 20 7b 46 31 32 39 31 30  allbacks {F12910
18570 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  }.**.** This rou
18580 74 69 6e 65 20 63 6f 6e 66 69 67 75 72 65 73 20  tine configures 
18590 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  a callback funct
185a0 69 6f 6e 20 2d 20 74 68 65 0a 2a 2a 20 70 72 6f  ion - the.** pro
185b0 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 2d  gress callback -
185c0 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64   that is invoked
185d0 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75   periodically du
185e0 72 69 6e 67 20 6c 6f 6e 67 0a 2a 2a 20 72 75 6e  ring long.** run
185f0 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 20 5b 73  ning calls to [s
18600 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20  qlite3_exec()], 
18610 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
18620 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
18630 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 2e 20 20  _get_table()].  
18640 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20   An example use 
18650 66 6f 72 20 74 68 69 73 20 0a 2a 2a 20 69 6e 74  for this .** int
18660 65 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65  erface is to kee
18670 70 20 61 20 47 55 49 20 75 70 64 61 74 65 64 20  p a GUI updated 
18680 64 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71  during a large q
18690 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  uery..**.** If t
186a0 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c  he progress call
186b0 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e  back returns non
186c0 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 61  -zero, the opera
186d0 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72  tion is.** inter
186e0 72 75 70 74 65 64 2e 20 20 54 68 69 73 20 66 65  rupted.  This fe
186f0 61 74 75 72 65 20 63 61 6e 20 62 65 20 75 73 65  ature can be use
18700 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61  d to implement a
18710 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 74  .** "Cancel" but
18720 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 64 69 61  ton on a GUI dia
18730 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 49  log box..**.** I
18740 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
18750 20 7b 46 31 32 39 31 31 7d 20 54 68 65 20 63 61   {F12911} The ca
18760 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
18770 72 65 67 69 73 74 65 72 65 64 20 62 79 20 5b 73  registered by [s
18780 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f  qlite3_progress_
18790 68 61 6e 64 6c 65 72 28 29 5d 0a 2a 2a 20 20 20  handler()].**   
187a0 20 20 20 20 20 20 20 69 73 20 69 6e 76 6f 6b 65         is invoke
187b0 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64  d periodically d
187c0 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69  uring long runni
187d0 6e 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 20  ng calls to.**  
187e0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
187f0 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _step()]..**.** 
18800 7b 46 31 32 39 31 32 7d 20 54 68 65 20 70 72 6f  {F12912} The pro
18810 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 69  gress callback i
18820 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 65 20 66  s invoked once f
18830 6f 72 20 65 76 65 72 79 20 4e 20 76 69 72 74 75  or every N virtu
18840 61 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d  al.**          m
18850 61 63 68 69 6e 65 20 6f 70 63 6f 64 65 73 2c 20  achine opcodes, 
18860 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73  where N is the s
18870 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
18880 6f 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  o .**          t
18890 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 67  he [sqlite3_prog
188a0 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 29 5d 20  ress_handler()] 
188b0 63 61 6c 6c 20 74 68 61 74 20 72 65 67 69 73 74  call that regist
188c0 65 72 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  ered.**         
188d0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 20 20   the callback.  
188e0 3c 74 6f 64 6f 3e 57 68 61 74 20 69 66 20 4e 20  <todo>What if N 
188f0 69 73 20 6c 65 73 73 20 74 68 61 6e 20 31 3f 3c  is less than 1?<
18900 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 7b 46 31  /todo>.**.** {F1
18910 32 39 31 33 7d 20 54 68 65 20 70 72 6f 67 72 65  2913} The progre
18920 73 73 20 63 61 6c 6c 62 61 63 6b 20 69 74 73 65  ss callback itse
18930 6c 66 20 69 73 20 69 64 65 6e 74 69 66 69 65 64  lf is identified
18940 20 62 79 20 74 68 65 20 74 68 69 72 64 0a 2a 2a   by the third.**
18950 20 20 20 20 20 20 20 20 20 20 61 72 67 75 6d 65            argume
18960 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70  nt to [sqlite3_p
18970 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28  rogress_handler(
18980 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 31  )]..**.** {F1291
18990 34 7d 20 54 68 65 20 66 6f 75 72 74 68 20 61 72  4} The fourth ar
189a0 67 75 6d 65 6e 74 20 5b 73 71 6c 69 74 65 33 5f  gument [sqlite3_
189b0 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72  progress_handler
189c0 28 29 5d 20 69 73 20 61 0a 2a 2a 2a 20 20 20 20  ()] is a.***    
189d0 20 20 20 20 20 76 6f 69 64 20 70 6f 69 6e 74 65       void pointe
189e0 72 20 70 61 73 73 65 64 20 74 6f 20 74 68 65 20  r passed to the 
189f0 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63  progress callbac
18a00 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 75  k.**          fu
18a10 6e 63 74 69 6f 6e 20 65 61 63 68 20 74 69 6d 65  nction each time
18a20 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a   it is invoked..
18a30 2a 2a 0a 2a 2a 20 7b 46 31 32 39 31 35 7d 20 49  **.** {F12915} I
18a40 66 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  f a call to [sql
18a50 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65 73  ite3_step()] res
18a60 75 6c 74 73 20 69 6e 20 66 65 77 65 72 20 74 68  ults in fewer th
18a70 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e  an.**          N
18a80 20 6f 70 63 6f 64 65 73 20 62 65 69 6e 67 20 65   opcodes being e
18a90 78 65 63 75 74 65 64 2c 0a 2a 2a 20 20 20 20 20  xecuted,.**     
18aa0 20 20 20 20 20 74 68 65 6e 20 74 68 65 20 70 72       then the pr
18ab0 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20  ogress callback 
18ac0 69 73 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 64  is never invoked
18ad0 2e 20 7b 45 4e 44 7d 0a 2a 2a 20 0a 2a 2a 20 7b  . {END}.** .** {
18ae0 46 31 32 39 31 36 7d 20 45 76 65 72 79 20 63 61  F12916} Every ca
18af0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70  ll to [sqlite3_p
18b00 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28  rogress_handler(
18b10 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  )].**          o
18b20 76 65 72 77 72 69 74 65 73 20 61 6e 79 20 70 72  verwrites any pr
18b30 65 76 69 6f 75 73 6c 79 20 72 65 67 69 73 74 65  eviously registe
18b40 72 65 64 20 70 72 6f 67 72 65 73 73 20 68 61 6e  red progress han
18b50 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  dler..**.** {F12
18b60 39 31 37 7d 20 49 66 20 74 68 65 20 70 72 6f 67  917} If the prog
18b70 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6c  ress handler cal
18b80 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 20 74 68  lback is NULL th
18b90 65 6e 20 6e 6f 20 70 72 6f 67 72 65 73 73 0a 2a  en no progress.*
18ba0 2a 20 20 20 20 20 20 20 20 20 20 68 61 6e 64 6c  *          handl
18bb0 65 72 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a  er is invoked..*
18bc0 2a 0a 2a 2a 20 7b 46 31 32 39 31 38 7d 20 49 66  *.** {F12918} If
18bd0 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 61   the progress ca
18be0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 61  llback returns a
18bf0 20 72 65 73 75 6c 74 20 6f 74 68 65 72 20 74 68   result other th
18c00 61 6e 20 30 2c 20 74 68 65 6e 0a 2a 2a 20 20 20  an 0, then.**   
18c10 20 20 20 20 20 20 20 74 68 65 20 62 65 68 61 76         the behav
18c20 69 6f 72 20 69 73 20 61 20 69 66 20 5b 73 71 6c  ior is a if [sql
18c30 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
18c40 5d 20 68 61 64 20 62 65 65 6e 20 63 61 6c 6c 65  ] had been calle
18c50 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  d..*/.void sqlit
18c60 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64  e3_progress_hand
18c70 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  ler(sqlite3*, in
18c80 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29  t, int(*)(void*)
18c90 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  , void*);../*.**
18ca0 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 69   CAPI3REF: Openi
18cb0 6e 67 20 41 20 4e 65 77 20 44 61 74 61 62 61 73  ng A New Databas
18cc0 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 7b 46 31  e Connection {F1
18cd0 32 37 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  2700}.**.** Thes
18ce0 65 20 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20  e routines open 
18cf0 61 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61  an SQLite databa
18d00 73 65 20 66 69 6c 65 20 77 68 6f 73 65 20 6e 61  se file whose na
18d10 6d 65 0a 2a 2a 20 69 73 20 67 69 76 65 6e 20 62  me.** is given b
18d20 79 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61  y the filename a
18d30 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20  rgument..** The 
18d40 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
18d50 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64  t is interpreted
18d60 20 61 73 20 55 54 46 2d 38 0a 2a 2a 20 66 6f 72   as UTF-8.** for
18d70 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
18d80 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f  ] and [sqlite3_o
18d90 70 65 6e 5f 76 32 28 29 5d 20 61 6e 64 20 61 73  pen_v2()] and as
18da0 20 55 54 46 2d 31 36 0a 2a 2a 20 69 6e 20 74 68   UTF-16.** in th
18db0 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
18dc0 64 65 72 20 66 6f 72 20 5b 73 71 6c 69 74 65 33  der for [sqlite3
18dd0 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 20 41  _open16()]..** A
18de0 6e 20 5b 73 71 6c 69 74 65 33 2a 5d 20 68 61 6e  n [sqlite3*] han
18df0 64 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 20 72  dle is usually r
18e00 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62  eturned in *ppDb
18e10 2c 20 65 76 65 6e 0a 2a 2a 20 69 66 20 61 6e 20  , even.** if an 
18e20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54  error occurs.  T
18e30 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f  he only exceptio
18e40 6e 20 69 73 20 69 66 20 53 51 4c 69 74 65 20 69  n is if SQLite i
18e50 73 20 75 6e 61 62 6c 65 0a 2a 2a 20 74 6f 20 61  s unable.** to a
18e60 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74  llocate memory t
18e70 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69  o hold the [sqli
18e80 74 65 33 5d 20 6f 62 6a 65 63 74 2c 20 61 20 4e  te3] object, a N
18e90 55 4c 4c 20 77 69 6c 6c 0a 2a 2a 20 62 65 20 77  ULL will.** be w
18ea0 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44  ritten into *ppD
18eb0 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70  b instead of a p
18ec0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ointer to the [s
18ed0 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a  qlite3] object..
18ee0 2a 2a 20 49 66 20 74 68 65 20 64 61 74 61 62 61  ** If the databa
18ef0 73 65 20 69 73 20 6f 70 65 6e 65 64 20 28 61 6e  se is opened (an
18f00 64 2f 6f 72 20 63 72 65 61 74 65 64 29 0a 2a 2a  d/or created).**
18f10 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20 74   successfully, t
18f20 68 65 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  hen [SQLITE_OK] 
18f30 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74  is returned.  Ot
18f40 68 65 72 77 69 73 65 20 61 6e 0a 2a 2a 20 65 72  herwise an.** er
18f50 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 75  ror code is retu
18f60 72 6e 65 64 2e 20 20 54 68 65 0a 2a 2a 20 5b 73  rned.  The.** [s
18f70 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
18f80 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72   or [sqlite3_err
18f90 6d 73 67 31 36 28 29 5d 20 20 72 6f 75 74 69 6e  msg16()]  routin
18fa0 65 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  es can be used t
18fb0 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45  o obtain.** an E
18fc0 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 65 20  nglish language 
18fd0 64 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 74  description of t
18fe0 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20  he error..**.** 
18ff0 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f  The default enco
19000 64 69 6e 67 20 66 6f 72 20 74 68 65 20 64 61 74  ding for the dat
19010 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 55 54  abase will be UT
19020 46 2d 38 20 69 66 0a 2a 2a 20 5b 73 71 6c 69 74  F-8 if.** [sqlit
19030 65 33 5f 6f 70 65 6e 28 29 5d 20 6f 72 20 5b 73  e3_open()] or [s
19040 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
19050 5d 20 69 73 20 63 61 6c 6c 65 64 20 61 6e 64 0a  ] is called and.
19060 2a 2a 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65  ** UTF-16 in the
19070 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
19080 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f  er if [sqlite3_o
19090 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65 64  pen16()] is used
190a0 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20  ..**.** Whether 
190b0 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20  or not an error 
190c0 6f 63 63 75 72 73 20 77 68 65 6e 20 69 74 20 69  occurs when it i
190d0 73 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72  s opened, resour
190e0 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65  ces.** associate
190f0 64 20 77 69 74 68 20 74 68 65 20 5b 73 71 6c 69  d with the [sqli
19100 74 65 33 2a 5d 20 68 61 6e 64 6c 65 20 73 68 6f  te3*] handle sho
19110 75 6c 64 20 62 65 20 72 65 6c 65 61 73 65 64 20  uld be released 
19120 62 79 20 70 61 73 73 69 6e 67 20 69 74 0a 2a 2a  by passing it.**
19130 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f   to [sqlite3_clo
19140 73 65 28 29 5d 20 77 68 65 6e 20 69 74 20 69 73  se()] when it is
19150 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75 69   no longer requi
19160 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  red..**.** The [
19170 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
19180 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72  )] interface wor
19190 6b 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33  ks like [sqlite3
191a0 5f 6f 70 65 6e 28 29 5d 20 0a 2a 2a 20 65 78 63  _open()] .** exc
191b0 65 70 74 20 74 68 61 74 20 69 74 20 61 63 63 65  ept that it acce
191c0 70 74 73 20 74 77 6f 20 61 64 64 69 74 69 6f 6e  pts two addition
191d0 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20 66 6f  al parameters fo
191e0 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e  r additional con
191f0 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65  trol.** over the
19200 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f   new database co
19210 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65 20 66  nnection.  The f
19220 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 63  lags parameter c
19230 61 6e 20 62 65 0a 2a 2a 20 6f 6e 65 20 6f 66 3a  an be.** one of:
19240 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c  .**.** <ol>.** <
19250 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
19260 4e 5f 52 45 41 44 4f 4e 4c 59 5d 0a 2a 2a 20 3c  N_READONLY].** <
19270 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
19280 4e 5f 52 45 41 44 57 52 49 54 45 5d 0a 2a 2a 20  N_READWRITE].** 
19290 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
192a0 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20  EN_READWRITE] | 
192b0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45  [SQLITE_OPEN_CRE
192c0 41 54 45 5d 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a  ATE].** </ol>.**
192d0 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 76 61  .** The first va
192e0 6c 75 65 20 6f 70 65 6e 73 20 74 68 65 20 64 61  lue opens the da
192f0 74 61 62 61 73 65 20 72 65 61 64 2d 6f 6e 6c 79  tabase read-only
19300 2e 20 0a 2a 2a 20 49 66 20 74 68 65 20 64 61 74  . .** If the dat
19310 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 20 70  abase does not p
19320 72 65 76 69 6f 75 73 6c 79 20 65 78 69 73 74 2c  reviously exist,
19330 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74   an error is ret
19340 75 72 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65  urned..** The se
19350 63 6f 6e 64 20 6f 70 74 69 6f 6e 20 6f 70 65 6e  cond option open
19360 73 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  s.** the databas
19370 65 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e  e for reading an
19380 64 20 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73  d writing if pos
19390 73 69 62 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e  sible, or readin
193a0 67 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 69 66 20  g only if.** if 
193b0 74 68 65 20 66 69 6c 65 20 69 73 20 77 72 69 74  the file is writ
193c0 65 20 70 72 6f 74 65 63 74 65 64 2e 20 20 49 6e  e protected.  In
193d0 20 65 69 74 68 65 72 20 63 61 73 65 20 74 68 65   either case the
193e0 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 6d 75 73   database.** mus
193f0 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 20  t already exist 
19400 6f 72 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72  or an error is r
19410 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 74 68  eturned.  The th
19420 69 72 64 20 6f 70 74 69 6f 6e 0a 2a 2a 20 6f 70  ird option.** op
19430 65 6e 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ens the database
19440 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64   for reading and
19450 20 77 72 69 74 69 6e 67 20 61 6e 64 20 63 72 65   writing and cre
19460 61 74 65 73 20 69 74 20 69 66 20 69 74 20 64 6f  ates it if it do
19470 65 73 0a 2a 2a 20 6e 6f 74 20 61 6c 72 65 61 64  es.** not alread
19480 79 20 65 78 69 73 74 2e 0a 2a 2a 20 54 68 65 20  y exist..** The 
19490 74 68 69 72 64 20 6f 70 74 69 6f 6e 73 20 69 73  third options is
194a0 20 62 65 68 61 76 69 6f 72 20 74 68 61 74 20 69   behavior that i
194b0 73 20 61 6c 77 61 79 73 20 75 73 65 64 20 66 6f  s always used fo
194c0 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  r [sqlite3_open(
194d0 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74  )].** and [sqlit
194e0 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a  e3_open16()]..**
194f0 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 70  .** If the 3rd p
19500 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
19510 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20  ite3_open_v2()] 
19520 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68  is not one of th
19530 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  e.** combination
19540 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 74 68  s shown above th
19550 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
19560 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
19570 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 6c 65 6e  .** If the filen
19580 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a  ame is ":memory:
19590 22 2c 20 74 68 65 6e 20 61 6e 20 70 72 69 76 61  ", then an priva
195a0 74 65 0a 2a 2a 20 69 6e 2d 6d 65 6d 6f 72 79 20  te.** in-memory 
195b0 64 61 74 61 62 61 73 65 20 69 73 20 63 72 65 61  database is crea
195c0 74 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e  ted for the conn
195d0 65 63 74 69 6f 6e 2e 20 20 54 68 69 73 20 69 6e  ection.  This in
195e0 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 64 61 74 61 62  -memory.** datab
195f0 61 73 65 20 77 69 6c 6c 20 76 61 6e 69 73 68 20  ase will vanish 
19600 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  when the databas
19610 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
19620 63 6c 6f 73 65 64 2e 20 20 46 75 74 75 72 65 0a  closed.  Future.
19630 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20 53 51  ** version of SQ
19640 4c 69 74 65 20 6d 69 67 68 74 20 6d 61 6b 65 20  Lite might make 
19650 75 73 65 20 6f 66 20 61 64 64 69 74 69 6f 6e 61  use of additiona
19660 6c 20 73 70 65 63 69 61 6c 20 66 69 6c 65 6e 61  l special filena
19670 6d 65 73 0a 2a 2a 20 74 68 61 74 20 62 65 67 69  mes.** that begi
19680 6e 20 77 69 74 68 20 74 68 65 20 22 3a 22 20 63  n with the ":" c
19690 68 61 72 61 63 74 65 72 2e 20 20 49 74 20 69 73  haracter.  It is
196a0 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61   recommended tha
196b0 74 20 0a 2a 2a 20 77 68 65 6e 20 61 20 64 61 74  t .** when a dat
196c0 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 72  abase filename r
196d0 65 61 6c 6c 79 20 64 6f 65 73 20 62 65 67 69 6e  eally does begin
196e0 20 77 69 74 68 0a 2a 2a 20 22 3a 22 20 74 68 61   with.** ":" tha
196f0 74 20 79 6f 75 20 70 72 65 66 69 78 20 74 68 65  t you prefix the
19700 20 66 69 6c 65 6e 61 6d 65 20 77 69 74 68 20 61   filename with a
19710 20 70 61 74 68 6e 61 6d 65 20 6c 69 6b 65 20 22   pathname like "
19720 2e 2f 22 20 74 6f 0a 2a 2a 20 61 76 6f 69 64 20  ./" to.** avoid 
19730 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a  ambiguity..**.**
19740 20 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65   If the filename
19750 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72   is an empty str
19760 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 69 76  ing, then a priv
19770 61 74 65 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a  ate temporary.**
19780 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 73   on-disk databas
19790 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61 74 65  e will be create
197a0 64 2e 20 20 54 68 69 73 20 70 72 69 76 61 74 65  d.  This private
197b0 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62   database will b
197c0 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c  e.** automatical
197d0 6c 79 20 64 65 6c 65 74 65 64 20 61 73 20 73 6f  ly deleted as so
197e0 6f 6e 20 61 73 20 74 68 65 20 64 61 74 61 62 61  on as the databa
197f0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
19800 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54   closed..**.** T
19810 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
19820 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ter to sqlite3_o
19830 70 65 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20  pen_v2() is the 
19840 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  name of the.** [
19850 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
19860 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73  ect that defines
19870 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
19880 79 73 74 65 6d 20 0a 2a 2a 20 69 6e 74 65 72 66  ystem .** interf
19890 61 63 65 20 74 68 61 74 20 74 68 65 20 6e 65 77  ace that the new
198a0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
198b0 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e  tion should use.
198c0 20 20 49 66 20 74 68 65 0a 2a 2a 20 66 6f 75 72    If the.** four
198d0 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
198e0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
198f0 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20  hen the default 
19900 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 0a 2a 2a  [sqlite3_vfs].**
19910 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e   object is used.
19920 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74  .**.** <b>Note t
19930 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 72 73 3a  o Windows users:
19940 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f 64 69  </b>  The encodi
19950 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68 65 20  ng used for the 
19960 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
19970 74 0a 2a 2a 20 6f 66 20 5b 73 71 6c 69 74 65 33  t.** of [sqlite3
19980 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20 5b 73 71  _open()] and [sq
19990 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
199a0 20 6d 75 73 74 20 62 65 20 55 54 46 2d 38 2c 20   must be UTF-8, 
199b0 6e 6f 74 20 77 68 61 74 65 76 65 72 0a 2a 2a 20  not whatever.** 
199c0 63 6f 64 65 70 61 67 65 20 69 73 20 63 75 72 72  codepage is curr
199d0 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e 20 20  ently defined.  
199e0 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69  Filenames contai
199f0 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e  ning internation
19a00 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73  al.** characters
19a10 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74   must be convert
19a20 65 64 20 74 6f 20 55 54 46 2d 38 20 70 72 69 6f  ed to UTF-8 prio
19a30 72 20 74 6f 20 70 61 73 73 69 6e 67 20 74 68 65  r to passing the
19a40 6d 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  m into.** [sqlit
19a50 65 33 5f 6f 70 65 6e 28 29 5d 20 6f 72 20 5b 73  e3_open()] or [s
19a60 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
19a70 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  ]..**.** INVARIA
19a80 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37  NTS:.**.** {F127
19a90 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  01} The [sqlite3
19aa0 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
19ab0 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e  e3_open16()], an
19ac0 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  d.**          [s
19ad0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
19ae0 5d 20 69 6e 74 65 72 66 61 63 65 73 20 63 72 65  ] interfaces cre
19af0 61 74 65 20 61 20 6e 65 77 0a 2a 2a 20 20 20 20  ate a new.**    
19b00 20 20 20 20 20 20 5b 64 61 74 61 62 61 73 65 20        [database 
19b10 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 73 73 6f  connection] asso
19b20 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a 20 20  ciated with.**  
19b30 20 20 20 20 20 20 20 20 74 68 65 20 64 61 74 61          the data
19b40 62 61 73 65 20 66 69 6c 65 20 67 69 76 65 6e 20  base file given 
19b50 69 6e 20 74 68 65 69 72 20 66 69 72 73 74 20 70  in their first p
19b60 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
19b70 7b 46 31 32 37 30 32 7d 20 54 68 65 20 66 69 6c  {F12702} The fil
19b80 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69  ename argument i
19b90 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
19ba0 20 55 54 46 2d 38 0a 2a 2a 20 20 20 20 20 20 20   UTF-8.**       
19bb0 20 20 20 66 6f 72 20 5b 73 71 6c 69 74 65 33 5f     for [sqlite3_
19bc0 6f 70 65 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  open()] and [sql
19bd0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20  ite3_open_v2()] 
19be0 61 6e 64 20 61 73 20 55 54 46 2d 31 36 0a 2a 2a  and as UTF-16.**
19bf0 20 20 20 20 20 20 20 20 20 20 69 6e 20 74 68 65            in the
19c00 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
19c10 65 72 20 66 6f 72 20 5b 73 71 6c 69 74 65 33 5f  er for [sqlite3_
19c20 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a  open16()]..**.**
19c30 20 7b 46 31 32 37 30 33 7d 20 41 20 73 75 63 63   {F12703} A succ
19c40 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f  essful invocatio
19c50 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70  n of [sqlite3_op
19c60 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
19c70 6f 70 65 6e 31 36 28 29 5d 2c 20 0a 2a 2a 20 20  open16()], .**  
19c80 20 20 20 20 20 20 20 20 6f 72 20 5b 73 71 6c 69          or [sqli
19c90 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 77  te3_open_v2()] w
19ca0 72 69 74 65 73 20 61 20 70 6f 69 6e 74 65 72 20  rites a pointer 
19cb0 74 6f 20 61 20 6e 65 77 0a 2a 2a 20 20 20 20 20  to a new.**     
19cc0 20 20 20 20 20 5b 64 61 74 61 62 61 73 65 20 63       [database c
19cd0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 6e 74 6f 20  onnection] into 
19ce0 2a 70 70 44 62 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  *ppDb..**.** {F1
19cf0 32 37 30 34 7d 20 54 68 65 20 5b 73 71 6c 69 74  2704} The [sqlit
19d00 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c  e3_open()], [sql
19d10 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20  ite3_open16()], 
19d20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  and.**          
19d30 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
19d40 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 72  ()] interfaces r
19d50 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b  eturn [SQLITE_OK
19d60 5d 20 75 70 6f 6e 20 73 75 63 63 65 73 73 2c 0a  ] upon success,.
19d70 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 61  **          or a
19d80 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65  n appropriate [e
19d90 72 72 6f 72 20 63 6f 64 65 5d 20 6f 6e 20 66 61  rror code] on fa
19da0 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  ilure..**.** {F1
19db0 32 37 30 36 7d 20 54 68 65 20 64 65 66 61 75 6c  2706} The defaul
19dc0 74 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20  t text encoding 
19dd0 66 6f 72 20 61 20 6e 65 77 20 64 61 74 61 62 61  for a new databa
19de0 73 65 20 63 72 65 61 74 65 64 20 75 73 69 6e 67  se created using
19df0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
19e00 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 6f 72  lite3_open()] or
19e10 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
19e20 32 28 29 5d 20 77 69 6c 6c 20 62 65 20 55 54 46  2()] will be UTF
19e30 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 30  -8..**.** {F1270
19e40 37 7d 20 54 68 65 20 64 65 66 61 75 6c 74 20 74  7} The default t
19e50 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72  ext encoding for
19e60 20 61 20 6e 65 77 20 64 61 74 61 62 61 73 65 20   a new database 
19e70 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a  created using.**
19e80 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
19e90 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 77 69 6c  e3_open16()] wil
19ea0 6c 20 62 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a  l be UTF-16..**.
19eb0 2a 2a 20 7b 46 31 32 37 30 39 7d 20 54 68 65 20  ** {F12709} The 
19ec0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 46 2c  [sqlite3_open(F,
19ed0 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20 69 73  D)] interface is
19ee0 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 0a 2a   equivalent to.*
19ef0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
19f00 74 65 33 5f 6f 70 65 6e 5f 76 32 28 46 2c 44 2c  te3_open_v2(F,D,
19f10 47 2c 30 29 5d 20 77 68 65 72 65 20 74 68 65 20  G,0)] where the 
19f20 47 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a  G parameter is.*
19f30 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49  *          [SQLI
19f40 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
19f50 45 5d 7c 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  E]|[SQLITE_OPEN_
19f60 43 52 45 41 54 45 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  CREATE]..**.** {
19f70 46 31 32 37 31 31 7d 20 49 66 20 74 68 65 20 47  F12711} If the G
19f80 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
19f90 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 46  qlite3_open_v2(F
19fa0 2c 44 2c 47 2c 56 29 5d 20 63 6f 6e 74 61 69 6e  ,D,G,V)] contain
19fb0 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
19fc0 20 20 62 69 74 20 76 61 6c 75 65 20 5b 53 51 4c    bit value [SQL
19fd0 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
19fe0 59 5d 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  Y] then the data
19ff0 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 0a 2a  base is opened.*
1a000 2a 20 20 20 20 20 20 20 20 20 20 66 6f 72 20 72  *          for r
1a010 65 61 64 69 6e 67 20 6f 6e 6c 79 2e 0a 2a 2a 0a  eading only..**.
1a020 2a 2a 20 7b 46 31 32 37 31 32 7d 20 49 66 20 74  ** {F12712} If t
1a030 68 65 20 47 20 70 61 72 61 6d 65 74 65 72 20 74  he G parameter t
1a040 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  o [sqlite3_open_
1a050 76 32 28 46 2c 44 2c 47 2c 56 29 5d 20 63 6f 6e  v2(F,D,G,V)] con
1a060 74 61 69 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20  tains the.**    
1a070 20 20 20 20 20 20 62 69 74 20 76 61 6c 75 65 20        bit value 
1a080 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
1a090 44 57 52 49 54 45 5d 20 74 68 65 6e 20 74 68 65  DWRITE] then the
1a0a0 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
1a0b0 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ned.**          
1a0c0 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74  reading and writ
1a0d0 69 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c  ing if possible,
1a0e0 20 6f 72 20 66 6f 72 20 72 65 61 64 69 6e 67 20   or for reading 
1a0f0 6f 6e 6c 79 20 69 66 20 74 68 65 0a 2a 2a 20 20  only if the.**  
1a100 20 20 20 20 20 20 20 20 66 69 6c 65 20 69 73 20          file is 
1a110 77 72 69 74 65 20 70 72 6f 74 65 63 74 65 64 20  write protected 
1a120 62 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  by the operating
1a130 20 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 7b   system..**.** {
1a140 46 31 32 37 31 33 7d 20 49 66 20 74 68 65 20 47  F12713} If the G
1a150 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
1a160 71 6c 69 74 65 33 5f 6f 70 65 6e 28 76 32 28 46  qlite3_open(v2(F
1a170 2c 44 2c 47 2c 56 29 5d 20 6f 6d 69 74 73 20 74  ,D,G,V)] omits t
1a180 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62  he.**          b
1a190 69 74 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45  it value [SQLITE
1a1a0 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20 61 6e  _OPEN_CREATE] an
1a1b0 64 20 74 68 65 20 64 61 74 61 62 61 73 65 20 64  d the database d
1a1c0 6f 65 73 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 20  oes not.**      
1a1d0 20 20 20 20 70 72 65 76 69 6f 75 73 6c 79 20 65      previously e
1a1e0 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69  xist, an error i
1a1f0 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
1a200 2a 20 7b 46 31 32 37 31 34 7d 20 49 66 20 74 68  * {F12714} If th
1a210 65 20 47 20 70 61 72 61 6d 65 74 65 72 20 74 6f  e G parameter to
1a220 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 76   [sqlite3_open(v
1a230 32 28 46 2c 44 2c 47 2c 56 29 5d 20 63 6f 6e 74  2(F,D,G,V)] cont
1a240 61 69 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  ains the.**     
1a250 20 20 20 20 20 62 69 74 20 76 61 6c 75 65 20 5b       bit value [
1a260 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
1a270 54 45 5d 20 61 6e 64 20 74 68 65 20 64 61 74 61  TE] and the data
1a280 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a  base does not.**
1a290 20 20 20 20 20 20 20 20 20 20 70 72 65 76 69 6f            previo
1a2a0 75 73 6c 79 20 65 78 69 73 74 2c 20 74 68 65 6e  usly exist, then
1a2b0 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d   an attempt is m
1a2c0 61 64 65 20 74 6f 20 63 72 65 61 74 65 20 61 6e  ade to create an
1a2d0 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  d.**          in
1a2e0 69 74 69 61 6c 69 7a 65 20 74 68 65 20 64 61 74  itialize the dat
1a2f0 61 62 61 73 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  abase..**.** {F1
1a300 32 37 31 37 7d 20 49 66 20 74 68 65 20 66 69 6c  2717} If the fil
1a310 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 74  ename argument t
1a320 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  o [sqlite3_open(
1a330 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
1a340 6e 31 36 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20  n16()],.**      
1a350 20 20 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f      or [sqlite3_
1a360 6f 70 65 6e 5f 76 32 28 29 5d 20 69 73 20 22 3a  open_v2()] is ":
1a370 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61  memory:", then a
1a380 6e 20 70 72 69 76 61 74 65 2c 0a 2a 2a 20 20 20  n private,.**   
1a390 20 20 20 20 20 20 20 65 70 68 65 6d 65 72 61 6c         ephemeral
1a3a0 2c 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61  , in-memory data
1a3b0 62 61 73 65 20 69 73 20 63 72 65 61 74 65 64 20  base is created 
1a3c0 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69  for the connecti
1a3d0 6f 6e 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  on..**          
1a3e0 3c 74 6f 64 6f 3e 49 73 20 53 51 4c 49 54 45 5f  <todo>Is SQLITE_
1a3f0 4f 50 45 4e 5f 43 52 45 41 54 45 7c 53 51 4c 49  OPEN_CREATE|SQLI
1a400 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
1a410 45 20 72 65 71 75 69 72 65 64 0a 2a 2a 20 20 20  E required.**   
1a420 20 20 20 20 20 20 20 69 6e 20 73 71 6c 69 74 65         in sqlite
1a430 33 5f 6f 70 65 6e 5f 76 32 28 29 3f 3c 2f 74 6f  3_open_v2()?</to
1a440 64 6f 3e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 31  do>.**.** {F1271
1a450 39 7d 20 49 66 20 74 68 65 20 66 69 6c 65 6e 61  9} If the filena
1a460 6d 65 20 69 73 20 4e 55 4c 4c 20 6f 72 20 61 6e  me is NULL or an
1a470 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74   empty string, t
1a480 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 0a 2a  hen a private,.*
1a490 2a 20 20 20 20 20 20 20 20 20 20 65 70 68 65 6d  *          ephem
1a4a0 65 72 61 6c 20 6f 6e 2d 64 69 73 6b 20 64 61 74  eral on-disk dat
1a4b0 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72  abase will be cr
1a4c0 65 61 74 65 64 2e 0a 2a 2a 20 20 20 20 20 20 20  eated..**       
1a4d0 20 20 20 3c 74 6f 64 6f 3e 49 73 20 53 51 4c 49     <todo>Is SQLI
1a4e0 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 7c 53  TE_OPEN_CREATE|S
1a4f0 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
1a500 52 49 54 45 20 72 65 71 75 69 72 65 64 0a 2a 2a  RITE required.**
1a510 20 20 20 20 20 20 20 20 20 20 69 6e 20 73 71 6c            in sql
1a520 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 3f 3c  ite3_open_v2()?<
1a530 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 7b 46 31  /todo>.**.** {F1
1a540 32 37 32 31 7d 20 54 68 65 20 5b 64 61 74 61 62  2721} The [datab
1a550 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
1a560 63 72 65 61 74 65 64 20 62 79 20 0a 2a 2a 20 20  created by .**  
1a570 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
1a580 5f 6f 70 65 6e 5f 76 32 28 46 2c 44 2c 47 2c 56  _open_v2(F,D,G,V
1a590 29 5d 20 77 69 6c 6c 20 75 73 65 20 74 68 65 0a  )] will use the.
1a5a0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
1a5b0 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
1a5c0 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74   identified by t
1a5d0 68 65 20 56 20 70 61 72 61 6d 65 74 65 72 2c 20  he V parameter, 
1a5e0 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  or.**          t
1a5f0 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69  he default [sqli
1a600 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20  te3_vfs] object 
1a610 69 73 20 56 20 69 73 20 61 20 4e 55 4c 4c 20 70  is V is a NULL p
1a620 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46  ointer..**.** {F
1a630 31 32 37 32 33 7d 20 54 77 6f 20 5b 64 61 74 61  12723} Two [data
1a640 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1a650 7c 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  | database conne
1a660 63 74 69 6f 6e 73 5d 20 77 69 6c 6c 20 73 68 61  ctions] will sha
1a670 72 65 20 61 20 63 6f 6d 6d 6f 6e 20 63 61 63 68  re a common cach
1a680 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 66  e.**          if
1a690 20 62 6f 74 68 20 77 65 72 65 20 6f 70 65 6e 65   both were opene
1a6a0 64 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20  d with the same 
1a6b0 56 46 53 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  VFS.**          
1a6c0 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 65  while [sqlite3_e
1a6d0 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63  nable_shared_cac
1a6e0 68 65 20 7c 20 73 68 61 72 65 64 20 63 61 63 68  he | shared cach
1a6f0 65 20 6d 6f 64 65 20 77 61 73 20 65 6e 61 62 6c  e mode was enabl
1a700 65 64 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20  ed] and.**      
1a710 20 20 20 20 69 66 20 62 6f 74 68 20 66 69 6c 65      if both file
1a720 6e 61 6d 65 73 20 63 6f 6d 70 61 72 65 20 65 71  names compare eq
1a730 75 61 6c 20 75 73 69 6e 67 20 6d 65 6d 63 6d 70  ual using memcmp
1a740 28 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  ().**          a
1a750 66 74 65 72 20 68 61 76 69 6e 67 20 62 65 65 6e  fter having been
1a760 20 70 72 6f 63 65 73 73 65 64 20 62 79 20 74 68   processed by th
1a770 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c  e [sqlite3_vfs |
1a780 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 5d 20   xFullPathname] 
1a790 6d 65 74 68 6f 64 20 6f 66 0a 2a 2a 20 20 20 20  method of.**    
1a7a0 20 20 20 20 20 20 74 68 65 20 56 46 53 2e 0a 2a        the VFS..*
1a7b0 2a 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  *.*/.int sqlite3
1a7c0 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63  _open(.  const c
1a7d0 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20  har *filename,  
1a7e0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c   /* Database fil
1a7f0 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f  ename (UTF-8) */
1a800 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44  .  sqlite3 **ppD
1a810 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55  b          /* OU
1a820 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e  T: SQLite db han
1a830 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71  dle */.);.int sq
1a840 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20  lite3_open16(.  
1a850 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c 65  const void *file
1a860 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62  name,   /* Datab
1a870 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54  ase filename (UT
1a880 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74  F-16) */.  sqlit
1a890 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20  e3 **ppDb       
1a8a0 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74     /* OUT: SQLit
1a8b0 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29  e db handle */.)
1a8c0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70  ;.int sqlite3_op
1a8d0 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 63  en_v2(.  const c
1a8e0 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20  har *filename,  
1a8f0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c   /* Database fil
1a900 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f  ename (UTF-8) */
1a910 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44  .  sqlite3 **ppD
1a920 62 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55  b,         /* OU
1a930 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e  T: SQLite db han
1a940 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61  dle */.  int fla
1a950 67 73 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  gs,             
1a960 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63   /* Flags */.  c
1a970 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73 20  onst char *zVfs 
1a980 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f         /* Name o
1a990 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20  f VFS module to 
1a9a0 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  use */.);../*.**
1a9b0 20 43 41 50 49 33 52 45 46 3a 20 45 72 72 6f 72   CAPI3REF: Error
1a9c0 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 73 73 61   Codes And Messa
1a9d0 67 65 73 20 7b 46 31 32 38 30 30 7d 0a 2a 2a 0a  ges {F12800}.**.
1a9e0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65  ** The sqlite3_e
1a9f0 72 72 63 6f 64 65 28 29 20 69 6e 74 65 72 66 61  rrcode() interfa
1aa00 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ce returns the n
1aa10 75 6d 65 72 69 63 0a 2a 2a 20 5b 53 51 4c 49 54  umeric.** [SQLIT
1aa20 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f  E_OK | result co
1aa30 64 65 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49  de] or [SQLITE_I
1aa40 4f 45 52 52 5f 52 45 41 44 20 7c 20 65 78 74 65  OERR_READ | exte
1aa50 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
1aa60 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d 6f 73  ].** for the mos
1aa70 74 20 72 65 63 65 6e 74 20 66 61 69 6c 65 64 20  t recent failed 
1aa80 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61  sqlite3_* API ca
1aa90 6c 6c 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a  ll associated.**
1aaa0 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5d 20   with [sqlite3] 
1aab0 68 61 6e 64 6c 65 20 27 64 62 27 2e 20 49 66 20  handle 'db'. If 
1aac0 61 20 70 72 69 6f 72 20 41 50 49 20 63 61 6c 6c  a prior API call
1aad0 20 66 61 69 6c 65 64 20 62 75 74 20 74 68 65 0a   failed but the.
1aae0 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 41  ** most recent A
1aaf0 50 49 20 63 61 6c 6c 20 73 75 63 63 65 65 64 65  PI call succeede
1ab00 64 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  d, the return va
1ab10 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  lue from sqlite3
1ab20 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69 73  _errcode().** is
1ab30 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
1ab40 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72  * The sqlite3_er
1ab50 72 6d 73 67 28 29 20 61 6e 64 20 73 71 6c 69 74  rmsg() and sqlit
1ab60 65 33 5f 65 72 72 6d 73 67 31 36 28 29 20 72 65  e3_errmsg16() re
1ab70 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e  turn English-lan
1ab80 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 20 74 68  guage.** text th
1ab90 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65  at describes the
1aba0 20 65 72 72 6f 72 2c 20 61 73 20 65 69 74 68 65   error, as eithe
1abb0 72 20 55 54 46 38 20 6f 72 20 55 54 46 31 36 20  r UTF8 or UTF16 
1abc0 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a  respectively..**
1abd0 20 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20   Memory to hold 
1abe0 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
1abf0 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61  e string is mana
1ac00 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a  ged internally..
1ac10 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
1ac20 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  on does not need
1ac30 20 74 6f 20 77 6f 72 72 79 20 77 69 74 68 20 66   to worry with f
1ac40 72 65 65 69 6e 67 20 74 68 65 20 72 65 73 75 6c  reeing the resul
1ac50 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74  t..** However, t
1ac60 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e 67 20  he error string 
1ac70 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77 72 69  might be overwri
1ac80 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61  tten or dealloca
1ac90 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 71  ted by.** subseq
1aca0 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74  uent calls to ot
1acb0 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
1acc0 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e 0a  face functions..
1acd0 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
1ace0 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 38 30 31 7d  :.**.** {F12801}
1acf0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 72   The [sqlite3_er
1ad00 72 63 6f 64 65 28 44 29 5d 20 69 6e 74 65 72 66  rcode(D)] interf
1ad10 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
1ad20 6e 75 6d 65 72 69 63 0a 2a 2a 20 20 20 20 20 20  numeric.**      
1ad30 20 20 20 20 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c      [SQLITE_OK |
1ad40 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72   result code] or
1ad50 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51  .**          [SQ
1ad60 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20  LITE_IOERR_READ 
1ad70 7c 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  | extended resul
1ad80 74 20 63 6f 64 65 5d 0a 2a 2a 20 20 20 20 20 20  t code].**      
1ad90 20 20 20 20 66 6f 72 20 74 68 65 20 6d 6f 73 74      for the most
1ada0 20 72 65 63 65 6e 74 6c 79 20 66 61 69 6c 65 64   recently failed
1adb0 20 69 6e 74 65 72 66 61 63 65 20 63 61 6c 6c 20   interface call 
1adc0 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 20 20  associated.**   
1add0 20 20 20 20 20 20 20 77 69 74 68 20 5b 64 61 74         with [dat
1ade0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1adf0 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 38  ] D..**.** {F128
1ae00 30 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  03} The [sqlite3
1ae10 5f 65 72 72 6d 73 67 28 44 29 5d 20 61 6e 64 20  _errmsg(D)] and 
1ae20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31  [sqlite3_errmsg1
1ae30 36 28 44 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  6(D)].**        
1ae40 20 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 74    interfaces ret
1ae50 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67  urn English-lang
1ae60 75 61 67 65 20 74 65 78 74 20 74 68 61 74 20 64  uage text that d
1ae70 65 73 63 72 69 62 65 73 0a 2a 2a 20 20 20 20 20  escribes.**     
1ae80 20 20 20 20 20 74 68 65 20 65 72 72 6f 72 20 69       the error i
1ae90 6e 20 74 68 65 20 6d 6f 73 74 6c 79 20 72 65 63  n the mostly rec
1aea0 65 6e 74 6c 79 20 66 61 69 6c 65 64 20 69 6e 74  ently failed int
1aeb0 65 72 66 61 63 65 20 63 61 6c 6c 2c 0a 2a 2a 20  erface call,.** 
1aec0 20 20 20 20 20 20 20 20 20 65 6e 63 6f 64 65 64           encoded
1aed0 20 61 73 20 65 69 74 68 65 72 20 55 54 46 38 20   as either UTF8 
1aee0 6f 72 20 55 54 46 31 36 20 72 65 73 70 65 63 74  or UTF16 respect
1aef0 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  ively..**.** {F1
1af00 32 38 30 37 7d 20 54 68 65 20 73 74 72 69 6e 67  2807} The string
1af10 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  s returned by [s
1af20 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
1af30 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 72   and [sqlite3_er
1af40 72 6d 73 67 31 36 28 29 5d 0a 2a 2a 20 20 20 20  rmsg16()].**    
1af50 20 20 20 20 20 20 61 72 65 20 76 61 6c 69 64 20        are valid 
1af60 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20 53  until the next S
1af70 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 20  QLite interface 
1af80 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  call..**.** {F12
1af90 38 30 38 7d 20 43 61 6c 6c 73 20 74 6f 20 41 50  808} Calls to AP
1afa0 49 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20  I routines that 
1afb0 64 6f 20 6e 6f 74 20 72 65 74 75 72 6e 20 61 6e  do not return an
1afc0 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 20   error code.**  
1afd0 20 20 20 20 20 20 20 20 28 65 78 61 6d 70 6c 65          (example
1afe0 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  : [sqlite3_data_
1aff0 63 6f 75 6e 74 28 29 5d 29 20 64 6f 20 6e 6f 74  count()]) do not
1b000 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 68 61  .**          cha
1b010 6e 67 65 20 74 68 65 20 65 72 72 6f 72 20 63 6f  nge the error co
1b020 64 65 20 6f 72 20 6d 65 73 73 61 67 65 20 72 65  de or message re
1b030 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 20 20 20  turned by.**    
1b040 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 65        [sqlite3_e
1b050 72 72 63 6f 64 65 28 29 5d 2c 20 5b 73 71 6c 69  rrcode()], [sqli
1b060 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2c 20 6f  te3_errmsg()], o
1b070 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  r [sqlite3_errms
1b080 67 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46  g16()]..**.** {F
1b090 31 32 38 30 39 7d 20 49 6e 74 65 72 66 61 63 65  12809} Interface
1b0a0 73 20 74 68 61 74 20 61 72 65 20 6e 6f 74 20 61  s that are not a
1b0b0 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61  ssociated with a
1b0c0 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 20 20 20   specific.**    
1b0d0 20 20 20 20 20 20 5b 64 61 74 61 62 61 73 65 20        [database 
1b0e0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 65 78 61  connection] (exa
1b0f0 6d 70 6c 65 73 3a 0a 2a 2a 20 20 20 20 20 20 20  mples:.**       
1b100 20 20 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69     [sqlite3_mpri
1b110 6e 74 66 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  ntf()] or [sqlit
1b120 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64  e3_enable_shared
1b130 5f 63 61 63 68 65 28 29 5d 0a 2a 2a 20 20 20 20  _cache()].**    
1b140 20 20 20 20 20 20 64 6f 20 6e 6f 74 20 63 68 61        do not cha
1b150 6e 67 65 20 74 68 65 20 76 61 6c 75 65 73 20 72  nge the values r
1b160 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 20 20  eturned by.**   
1b170 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
1b180 65 72 72 63 6f 64 65 28 29 5d 2c 20 5b 73 71 6c  errcode()], [sql
1b190 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2c 20  ite3_errmsg()], 
1b1a0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  or [sqlite3_errm
1b1b0 73 67 31 36 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20  sg16()]..*/.int 
1b1c0 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
1b1d0 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 63 6f  sqlite3 *db);.co
1b1e0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
1b1f0 33 5f 65 72 72 6d 73 67 28 73 71 6c 69 74 65 33  3_errmsg(sqlite3
1b200 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  *);.const void *
1b210 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
1b220 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
1b230 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c  ** CAPI3REF: SQL
1b240 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63   Statement Objec
1b250 74 20 7b 46 31 33 30 30 30 7d 0a 2a 2a 20 4b 45  t {F13000}.** KE
1b260 59 57 4f 52 44 53 3a 20 7b 70 72 65 70 61 72 65  YWORDS: {prepare
1b270 64 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70 72  d statement} {pr
1b280 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1b290 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74  s}.**.** An inst
1b2a0 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
1b2b0 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61  ect represents a
1b2c0 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74   single SQL stat
1b2d0 65 6d 65 6e 74 2e 20 20 54 68 69 73 0a 2a 2a 20  ement.  This.** 
1b2e0 6f 62 6a 65 63 74 20 69 73 20 76 61 72 69 6f 75  object is variou
1b2f0 73 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 61 20 22  sly known as a "
1b300 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1b310 6e 74 22 20 6f 72 20 61 20 0a 2a 2a 20 22 63 6f  nt" or a .** "co
1b320 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 61 74 65  mpiled SQL state
1b330 6d 65 6e 74 22 20 6f 72 20 73 69 6d 70 6c 79 20  ment" or simply 
1b340 61 73 20 61 20 22 73 74 61 74 65 6d 65 6e 74 22  as a "statement"
1b350 2e 0a 2a 2a 20 0a 2a 2a 20 54 68 65 20 6c 69 66  ..** .** The lif
1b360 65 20 6f 66 20 61 20 73 74 61 74 65 6d 65 6e 74  e of a statement
1b370 20 6f 62 6a 65 63 74 20 67 6f 65 73 20 73 6f 6d   object goes som
1b380 65 74 68 69 6e 67 20 6c 69 6b 65 20 74 68 69 73  ething like this
1b390 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20  :.**.** <ol>.** 
1b3a0 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68 65 20  <li> Create the 
1b3b0 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71  object using [sq
1b3c0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1b3d0 28 29 5d 20 6f 72 20 61 20 72 65 6c 61 74 65 64  ()] or a related
1b3e0 0a 2a 2a 20 20 20 20 20 20 66 75 6e 63 74 69 6f  .**      functio
1b3f0 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20  n..** <li> Bind 
1b400 76 61 6c 75 65 73 20 74 6f 20 68 6f 73 74 20 70  values to host p
1b410 61 72 61 6d 65 74 65 72 73 20 75 73 69 6e 67 0a  arameters using.
1b420 2a 2a 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33  **      [sqlite3
1b430 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c  _bind_blob | sql
1b440 69 74 65 33 5f 62 69 6e 64 5f 2a 20 69 6e 74 65  ite3_bind_* inte
1b450 72 66 61 63 65 73 5d 2e 0a 2a 2a 20 3c 6c 69 3e  rfaces]..** <li>
1b460 20 52 75 6e 20 74 68 65 20 53 51 4c 20 62 79 20   Run the SQL by 
1b470 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
1b480 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20  _step()] one or 
1b490 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c  more times..** <
1b4a0 6c 69 3e 20 52 65 73 65 74 20 74 68 65 20 73 74  li> Reset the st
1b4b0 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73  atement using [s
1b4c0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
1b4d0 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20  then go back.** 
1b4e0 20 20 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20       to step 2. 
1b4f0 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72   Do this zero or
1b500 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20   more times..** 
1b510 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65  <li> Destroy the
1b520 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73   object using [s
1b530 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
1b540 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a  )]..** </ol>.**.
1b550 2a 2a 20 52 65 66 65 72 20 74 6f 20 64 6f 63 75  ** Refer to docu
1b560 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e 20 69 6e 64  mentation on ind
1b570 69 76 69 64 75 61 6c 20 6d 65 74 68 6f 64 73 20  ividual methods 
1b580 61 62 6f 76 65 20 66 6f 72 20 61 64 64 69 74 69  above for additi
1b590 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  onal.** informat
1b5a0 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ion..*/.typedef 
1b5b0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 73  struct sqlite3_s
1b5c0 74 6d 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  tmt sqlite3_stmt
1b5d0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1b5e0 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69  F: Run-time Limi
1b5f0 74 73 20 7b 46 31 32 37 36 30 7d 0a 2a 2a 0a 2a  ts {F12760}.**.*
1b600 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65  * This interface
1b610 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a 65   allows the size
1b620 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e 73   of various cons
1b630 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69 6d  tructs to be lim
1b640 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e  ited.** on a con
1b650 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65  nection by conne
1b660 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54 68  ction basis.  Th
1b670 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
1b680 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74  r is the.** [dat
1b690 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1b6a0 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69 73  ] whose limit is
1b6b0 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71 75   to be set or qu
1b6c0 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73  eried.  The.** s
1b6d0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
1b6e0 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c  is one of the [l
1b6f0 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 5d  imit categories]
1b700 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a 2a   that define a.*
1b710 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74  * class of const
1b720 72 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a 65  ructs to be size
1b730 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20 74   limited.  The t
1b740 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69  hird parameter i
1b750 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d  s the.** new lim
1b760 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e 73  it for that cons
1b770 74 72 75 63 74 2e 20 20 54 68 65 20 66 75 6e 63  truct.  The func
1b780 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
1b790 20 6f 6c 64 20 6c 69 6d 69 74 2e 0a 2a 2a 0a 2a   old limit..**.*
1b7a0 2a 20 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d  * If the new lim
1b7b0 69 74 20 69 73 20 61 20 6e 65 67 61 74 69 76 65  it is a negative
1b7c0 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d   number, the lim
1b7d0 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e  it is unchanged.
1b7e0 0a 2a 2a 20 46 6f 72 20 74 68 65 20 6c 69 6d 69  .** For the limi
1b7f0 74 20 63 61 74 65 67 6f 72 79 20 6f 66 20 53 51  t category of SQ
1b800 4c 49 54 45 5f 4c 49 4d 49 54 5f 58 59 5a 20 74  LITE_LIMIT_XYZ t
1b810 68 65 72 65 20 69 73 20 61 20 68 61 72 64 20 75  here is a hard u
1b820 70 70 65 72 0a 2a 2a 20 62 6f 75 6e 64 20 73 65  pper.** bound se
1b830 74 20 62 79 20 61 20 63 6f 6d 70 69 6c 65 2d 74  t by a compile-t
1b840 69 6d 65 20 43 2d 70 72 65 70 72 6f 63 65 73 73  ime C-preprocess
1b850 20 6d 61 63 72 6f 20 6e 61 6d 65 64 20 53 51 4c   macro named SQL
1b860 49 54 45 5f 4d 41 58 5f 58 59 5a 2e 0a 2a 2a 20  ITE_MAX_XYZ..** 
1b870 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69  (The "_LIMIT_" i
1b880 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20 63 68  n the name is ch
1b890 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22  anged to "_MAX_"
1b8a0 2e 29 0a 2a 2a 20 41 74 74 65 6d 70 74 73 20 74  .).** Attempts t
1b8b0 6f 20 69 6e 63 72 65 61 73 65 20 61 20 6c 69 6d  o increase a lim
1b8c0 69 74 20 61 62 6f 76 65 20 69 74 73 20 68 61 72  it above its har
1b8d0 64 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61 72  d upper bound ar
1b8e0 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72  e.** silently tr
1b8f0 75 6e 63 61 74 65 64 20 74 6f 20 74 68 65 20 68  uncated to the h
1b900 61 72 64 20 75 70 70 65 72 20 6c 69 6d 69 74 2e  ard upper limit.
1b910 0a 2a 2a 0a 2a 2a 20 52 75 6e 20 74 69 6d 65 20  .**.** Run time 
1b920 6c 69 6d 69 74 73 20 61 72 65 20 69 6e 74 65 6e  limits are inten
1b930 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 61  ded for use in a
1b940 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
1b950 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20   manage.** both 
1b960 74 68 65 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e  their own intern
1b970 61 6c 20 64 61 74 61 62 61 73 65 20 61 6e 64 20  al database and 
1b980 61 6c 73 6f 20 64 61 74 61 62 61 73 65 73 20 74  also databases t
1b990 68 61 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c  hat are controll
1b9a0 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73 74  ed.** by untrust
1b9b0 65 64 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72  ed external sour
1b9c0 63 65 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65  ces.  An example
1b9d0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67   application mig
1b9e0 68 74 20 62 65 20 61 0a 2a 2a 20 77 65 62 62 72  ht be a.** webbr
1b9f0 6f 77 73 65 72 20 74 68 61 74 20 68 61 73 20 69  owser that has i
1ba00 74 73 20 6f 77 6e 20 64 61 74 61 62 61 73 65 73  ts own databases
1ba10 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 68 69 73   for storing his
1ba20 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61  tory and.** sepa
1ba30 72 61 74 65 20 64 61 74 61 62 61 73 65 73 20 63  rate databases c
1ba40 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76  ontrolled by Jav
1ba50 61 53 63 72 69 70 74 20 61 70 70 6c 69 63 61 74  aScript applicat
1ba60 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a  ions downloaded.
1ba70 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e 74 65 72  ** off the Inter
1ba80 6e 65 74 2e 20 20 54 68 65 20 69 6e 74 65 72 6e  net.  The intern
1ba90 61 6c 20 64 61 74 61 62 61 73 65 73 20 63 61 6e  al databases can
1baa0 20 62 65 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a   be given the.**
1bab0 20 6c 61 72 67 65 2c 20 64 65 66 61 75 6c 74 20   large, default 
1bac0 6c 69 6d 69 74 73 2e 20 20 44 61 74 61 62 61 73  limits.  Databas
1bad0 65 73 20 6d 61 6e 61 67 65 64 20 62 79 20 65 78  es managed by ex
1bae0 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 20 63  ternal sources c
1baf0 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d  an.** be given m
1bb00 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69  uch smaller limi
1bb10 74 73 20 64 65 73 69 67 6e 65 64 20 74 6f 20 70  ts designed to p
1bb20 72 65 76 65 6e 74 20 61 20 64 65 6e 69 61 6c 20  revent a denial 
1bb30 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a 20 61 74  of service.** at
1bb40 74 61 63 68 2e 20 20 44 65 76 65 6c 6f 70 65 72  tach.  Developer
1bb50 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 77 61 6e  s might also wan
1bb60 74 20 74 6f 20 75 73 65 20 74 68 65 20 5b 73 71  t to use the [sq
1bb70 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
1bb80 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72  izer()].** inter
1bb90 66 61 63 65 20 74 6f 20 66 75 72 74 68 65 72 20  face to further 
1bba0 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74 65  control untruste
1bbb0 64 20 53 51 4c 2e 20 20 54 68 65 20 73 69 7a 65  d SQL.  The size
1bbc0 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
1bbd0 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 61  .** created by a
1bbe0 6e 20 75 6e 74 72 75 73 74 65 64 20 73 63 72 69  n untrusted scri
1bbf0 70 74 20 63 61 6e 20 62 65 20 63 6f 6e 74 61 69  pt can be contai
1bc00 6e 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a  ned using the.**
1bc10 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74   [max_page_count
1bc20 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a  ] [PRAGMA]..**.*
1bc30 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65  * This interface
1bc40 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 63 6f   is currently co
1bc50 6e 73 69 64 65 72 65 64 20 65 78 70 65 72 69 6d  nsidered experim
1bc60 65 6e 74 61 6c 20 61 6e 64 20 69 73 20 73 75 62  ental and is sub
1bc70 6a 65 63 74 0a 2a 2a 20 74 6f 20 63 68 61 6e 67  ject.** to chang
1bc80 65 20 6f 72 20 72 65 6d 6f 76 61 6c 20 77 69 74  e or removal wit
1bc90 68 6f 75 74 20 70 72 69 6f 72 20 6e 6f 74 69 63  hout prior notic
1bca0 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  e..**.** INVARIA
1bcb0 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37  NTS:.**.** {F127
1bcc0 36 32 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c  62} A successful
1bcd0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
1bce0 33 5f 6c 69 6d 69 74 28 44 2c 43 2c 56 29 5d 20  3_limit(D,C,V)] 
1bcf0 77 68 65 72 65 20 56 20 69 73 0a 2a 2a 20 20 20  where V is.**   
1bd00 20 20 20 20 20 20 20 70 6f 73 69 74 69 76 65 20         positive 
1bd10 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20  changes the.**  
1bd20 20 20 20 20 20 20 20 20 6c 69 6d 69 74 20 6f 6e          limit on
1bd30 20 74 68 65 20 73 69 7a 65 20 6f 66 20 63 6f 6e   the size of con
1bd40 73 74 72 75 63 74 20 43 20 69 6e 20 5b 64 61 74  struct C in [dat
1bd50 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1bd60 5d 20 44 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ] D.**          
1bd70 74 6f 20 74 68 65 20 6c 65 73 73 65 72 20 6f 66  to the lesser of
1bd80 20 56 20 61 6e 64 20 74 68 65 20 68 61 72 64 20   V and the hard 
1bd90 75 70 70 65 72 20 62 6f 75 6e 64 20 6f 6e 20 74  upper bound on t
1bda0 68 65 20 73 69 7a 65 0a 2a 2a 20 20 20 20 20 20  he size.**      
1bdb0 20 20 20 20 6f 66 20 43 20 74 68 61 74 20 69 73      of C that is
1bdc0 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d   set at compile-
1bdd0 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  time..**.** {F12
1bde0 37 36 36 7d 20 41 20 73 75 63 63 65 73 73 66 75  766} A successfu
1bdf0 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  l call to [sqlit
1be00 65 33 5f 6c 69 6d 69 74 28 44 2c 43 2c 56 29 5d  e3_limit(D,C,V)]
1be10 20 77 68 65 72 65 20 56 20 69 73 20 6e 65 67 61   where V is nega
1be20 74 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  tive.**         
1be30 20 6c 65 61 76 65 73 20 74 68 65 20 73 74 61 74   leaves the stat
1be40 65 20 6f 66 20 5b 64 61 74 61 62 61 73 65 20 63  e of [database c
1be50 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 75 6e 63  onnection] D unc
1be60 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46  hanged..**.** {F
1be70 31 32 37 36 39 7d 20 41 20 73 75 63 63 65 73 73  12769} A success
1be80 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ful call to [sql
1be90 69 74 65 33 5f 6c 69 6d 69 74 28 44 2c 43 2c 56  ite3_limit(D,C,V
1bea0 29 5d 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a  )] returns the.*
1beb0 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c 75 65  *          value
1bec0 20 6f 66 20 74 68 65 20 6c 69 6d 69 74 20 6f 6e   of the limit on
1bed0 20 74 68 65 20 73 69 7a 65 20 6f 66 20 63 6f 6e   the size of con
1bee0 73 74 72 75 63 74 20 43 20 69 6e 0a 2a 2a 20 20  struct C in.**  
1bef0 20 20 20 20 20 20 20 20 69 6e 20 5b 64 61 74 61          in [data
1bf00 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1bf10 20 44 20 61 73 20 69 74 20 77 61 73 20 70 72 69   D as it was pri
1bf20 6f 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 2e 0a  or to the call..
1bf30 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c  */.int sqlite3_l
1bf40 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c 20 69  imit(sqlite3*, i
1bf50 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 56 61  nt id, int newVa
1bf60 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  l);../*.** CAPI3
1bf70 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69  REF: Run-Time Li
1bf80 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73 20 7b  mit Categories {
1bf90 46 31 32 37 39 30 7d 0a 2a 2a 20 4b 45 59 57 4f  F12790}.** KEYWO
1bfa0 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65  RDS: {limit cate
1bfb0 67 6f 72 79 7d 20 7b 6c 69 6d 69 74 20 63 61 74  gory} {limit cat
1bfc0 65 67 6f 72 69 65 73 7d 0a 2a 2a 20 0a 2a 2a 20  egories}.** .** 
1bfd0 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
1bfe0 64 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20 61  define various a
1bff0 73 70 65 63 74 73 20 6f 66 20 61 20 5b 64 61 74  spects of a [dat
1c000 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1c010 5d 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65  ].** that can be
1c020 20 6c 69 6d 69 74 65 64 20 69 6e 20 73 69 7a 65   limited in size
1c030 20 62 79 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71   by calls to [sq
1c040 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a  lite3_limit()]..
1c050 2a 2a 20 54 68 65 20 6d 65 61 6e 69 6e 67 73 20  ** The meanings 
1c060 6f 66 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c  of the various l
1c070 69 6d 69 74 73 20 61 72 65 20 61 73 20 66 6f 6c  imits are as fol
1c080 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  lows:.**.** <dl>
1c090 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  .** <dt>SQLITE_L
1c0a0 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e  IMIT_LENGTH</dt>
1c0b0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
1c0c0 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79 0a  mum size of any.
1c0d0 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20 62 6c 6f  ** string or blo
1c0e0 62 20 6f 72 20 74 61 62 6c 65 20 72 6f 77 2e 3c  b or table row.<
1c0f0 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
1c100 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c  LITE_LIMIT_SQL_L
1c110 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ENGTH</dt>.** <d
1c120 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  d>The maximum le
1c130 6e 67 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73  ngth of an SQL s
1c140 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a  tatement.</dd>.*
1c150 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
1c160 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74  LIMIT_COLUMN</dt
1c170 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
1c180 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63  imum number of c
1c190 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c  olumns in a tabl
1c1a0 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20  e definition or 
1c1b0 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74  in the.** result
1c1c0 20 73 65 74 20 6f 66 20 61 20 53 45 4c 45 43 54   set of a SELECT
1c1d0 20 6f 72 20 74 68 65 20 6d 61 78 69 6d 75 6d 20   or the maximum 
1c1e0 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
1c1f0 73 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a  s in an index.**
1c200 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45 52 20   or in an ORDER 
1c210 42 59 20 6f 72 20 47 52 4f 55 50 20 42 59 20 63  BY or GROUP BY c
1c220 6c 61 75 73 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  lause.</dd>.**.*
1c230 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  * <dt>SQLITE_LIM
1c240 49 54 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f 64  IT_EXPR_DEPTH</d
1c250 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
1c260 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 74  ximum depth of t
1c270 68 65 20 70 61 72 73 65 20 74 72 65 65 20 6f 6e  he parse tree on
1c280 20 61 6e 79 20 65 78 70 72 65 73 73 69 6f 6e 2e   any expression.
1c290 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
1c2a0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d  SQLITE_LIMIT_COM
1c2b0 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74  POUND_SELECT</dt
1c2c0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
1c2d0 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74  imum number of t
1c2e0 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75  erms in a compou
1c2f0 6e 64 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d  nd SELECT statem
1c300 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ent.</dd>.**.** 
1c310 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
1c320 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a  _VDBE_OP</dt>.**
1c330 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
1c340 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 72   number of instr
1c350 75 63 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 72  uctions in a vir
1c360 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f  tual machine pro
1c370 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20  gram.** used to 
1c380 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c  implement an SQL
1c390 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e   statement.</dd>
1c3a0 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
1c3b0 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e  E_LIMIT_FUNCTION
1c3c0 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  _ARG</dt>.** <dd
1c3d0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
1c3e0 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73  ber of arguments
1c3f0 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c   on a function.<
1c400 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
1c410 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41  QLITE_LIMIT_ATTA
1c420 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  CHED</dt>.** <dd
1c430 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
1c440 62 65 72 20 6f 66 20 61 74 74 61 63 68 65 64 20  ber of attached 
1c450 64 61 74 61 62 61 73 65 73 2e 3c 2f 64 64 3e 0a  databases.</dd>.
1c460 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
1c470 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54  _LIMIT_LIKE_PATT
1c480 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a  ERN_LENGTH</dt>.
1c490 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
1c4a0 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65  um length of the
1c4b0 20 70 61 74 74 65 72 6e 20 61 72 67 75 6d 65 6e   pattern argumen
1c4c0 74 20 74 6f 20 74 68 65 20 4c 49 4b 45 20 6f 72  t to the LIKE or
1c4d0 0a 2a 2a 20 47 4c 4f 42 20 6f 70 65 72 61 74 6f  .** GLOB operato
1c4e0 72 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  rs.</dd>.**.** <
1c4f0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
1c500 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c  VARIABLE_NUMBER<
1c510 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
1c520 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
1c530 66 20 76 61 72 69 61 62 6c 65 73 20 69 6e 20 61  f variables in a
1c540 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  n SQL statement 
1c550 74 68 61 74 20 63 61 6e 0a 2a 2a 20 62 65 20 62  that can.** be b
1c560 6f 75 6e 64 2e 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f  ound.</dd>.** </
1c570 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  dl>.*/.#define S
1c580 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47  QLITE_LIMIT_LENG
1c590 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TH              
1c5a0 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20        0.#define 
1c5b0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c  SQLITE_LIMIT_SQL
1c5c0 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20  _LENGTH         
1c5d0 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
1c5e0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f   SQLITE_LIMIT_CO
1c5f0 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20  LUMN            
1c600 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e          2.#defin
1c610 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45  e SQLITE_LIMIT_E
1c620 58 50 52 5f 44 45 50 54 48 20 20 20 20 20 20 20  XPR_DEPTH       
1c630 20 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69           3.#defi
1c640 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
1c650 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20  COMPOUND_SELECT 
1c660 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66            4.#def
1c670 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
1c680 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20  _VDBE_OP        
1c690 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65             5.#de
1c6a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
1c6b0 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20  T_FUNCTION_ARG  
1c6c0 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64              6.#d
1c6d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
1c6e0 49 54 5f 41 54 54 41 43 48 45 44 20 20 20 20 20  IT_ATTACHED     
1c6f0 20 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23               7.#
1c700 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
1c710 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e  MIT_LIKE_PATTERN
1c720 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a  _LENGTH       8.
1c730 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
1c740 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
1c750 4d 42 45 52 20 20 20 20 20 20 20 20 20 20 20 39  MBER           9
1c760 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1c770 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53  : Compiling An S
1c780 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 7b 46 31  QL Statement {F1
1c790 33 30 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65  3010}.**.** To e
1c7a0 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20 71 75  xecute an SQL qu
1c7b0 65 72 79 2c 20 69 74 20 6d 75 73 74 20 66 69 72  ery, it must fir
1c7c0 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 69  st be compiled i
1c7d0 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65 0a  nto a byte-code.
1c7e0 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e 67  ** program using
1c7f0 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72 6f   one of these ro
1c800 75 74 69 6e 65 73 2e 20 0a 2a 2a 0a 2a 2a 20 54  utines. .**.** T
1c810 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
1c820 74 20 22 64 62 22 20 69 73 20 61 6e 20 5b 64 61  t "db" is an [da
1c830 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1c840 6e 5d 20 0a 2a 2a 20 6f 62 74 61 69 6e 65 64 20  n] .** obtained 
1c850 66 72 6f 6d 20 61 20 70 72 69 6f 72 20 63 61 6c  from a prior cal
1c860 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  l to [sqlite3_op
1c870 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
1c880 6f 70 65 6e 5f 76 32 28 29 5d 0a 2a 2a 20 6f 72  open_v2()].** or
1c890 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
1c8a0 28 29 5d 2e 20 0a 2a 2a 20 54 68 65 20 73 65 63  ()]. .** The sec
1c8b0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 22 7a 53  ond argument "zS
1c8c0 71 6c 22 20 69 73 20 74 68 65 20 73 74 61 74 65  ql" is the state
1c8d0 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69  ment to be compi
1c8e0 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20  led, encoded.** 
1c8f0 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20  as either UTF-8 
1c900 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20  or UTF-16.  The 
1c910 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
1c920 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  ) and sqlite3_pr
1c930 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e  epare_v2().** in
1c940 74 65 72 66 61 63 65 73 20 75 73 65 73 20 55 54  terfaces uses UT
1c950 46 2d 38 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  F-8 and sqlite3_
1c960 70 72 65 70 61 72 65 31 36 28 29 20 61 6e 64 20  prepare16() and 
1c970 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1c980 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54  6_v2().** use UT
1c990 46 2d 31 36 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a  F-16. {END}.**.*
1c9a0 2a 20 49 66 20 74 68 65 20 6e 42 79 74 65 20 61  * If the nByte a
1c9b0 72 67 75 6d 65 6e 74 20 69 73 20 6c 65 73 73 0a  rgument is less.
1c9c0 2a 2a 20 74 68 61 6e 20 7a 65 72 6f 2c 20 74 68  ** than zero, th
1c9d0 65 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20  en zSql is read 
1c9e0 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  up to the first 
1c9f0 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e  zero terminator.
1ca00 0a 2a 2a 20 49 66 20 6e 42 79 74 65 20 69 73 20  .** If nByte is 
1ca10 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68  non-negative, th
1ca20 65 6e 20 69 74 20 69 73 20 74 68 65 20 6d 61 78  en it is the max
1ca30 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 0a  imum number of .
1ca40 2a 2a 20 62 79 74 65 73 20 72 65 61 64 20 66 72  ** bytes read fr
1ca50 6f 6d 20 7a 53 71 6c 2e 20 20 57 68 65 6e 20 6e  om zSql.  When n
1ca60 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  Byte is non-nega
1ca70 74 69 76 65 2c 20 74 68 65 0a 2a 2a 20 7a 53 71  tive, the.** zSq
1ca80 6c 20 73 74 72 69 6e 67 20 65 6e 64 73 20 61 74  l string ends at
1ca90 20 65 69 74 68 65 72 20 74 68 65 20 66 69 72 73   either the firs
1caa0 74 20 27 5c 30 30 30 27 20 6f 72 20 27 5c 75 30  t '\000' or '\u0
1cab0 30 30 30 27 20 63 68 61 72 61 63 74 65 72 20 6f  000' character o
1cac0 72 20 0a 2a 2a 20 74 68 65 20 6e 42 79 74 65 2d  r .** the nByte-
1cad0 74 68 20 62 79 74 65 2c 20 77 68 69 63 68 65 76  th byte, whichev
1cae0 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 20  er comes first. 
1caf0 49 66 20 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e  If the caller kn
1cb00 6f 77 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20  ows.** that the 
1cb10 73 75 70 70 6c 69 65 64 20 73 74 72 69 6e 67 20  supplied string 
1cb20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65  is nul-terminate
1cb30 64 2c 20 74 68 65 6e 20 74 68 65 72 65 20 69 73  d, then there is
1cb40 20 61 20 73 6d 61 6c 6c 0a 2a 2a 20 70 65 72 66   a small.** perf
1cb50 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e 74 61 67  ormance advantag
1cb60 65 20 74 6f 20 62 65 20 68 61 64 20 62 79 20 70  e to be had by p
1cb70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 74 65 20  assing an nByte 
1cb80 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 20 0a  parameter that .
1cb90 2a 2a 20 69 73 20 65 71 75 61 6c 20 74 6f 20 74  ** is equal to t
1cba0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
1cbb0 65 73 20 69 6e 20 74 68 65 20 69 6e 70 75 74 20  es in the input 
1cbc0 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64  string <i>includ
1cbd0 69 6e 67 3c 2f 69 3e 20 0a 2a 2a 20 74 68 65 20  ing</i> .** the 
1cbe0 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 20 62  nul-terminator b
1cbf0 79 74 65 73 2e 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a  ytes.{END}.**.**
1cc00 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65   *pzTail is made
1cc10 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65   to point to the
1cc20 20 66 69 72 73 74 20 62 79 74 65 20 70 61 73 74   first byte past
1cc30 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 0a   the end of the.
1cc40 2a 2a 20 66 69 72 73 74 20 53 51 4c 20 73 74 61  ** first SQL sta
1cc50 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20  tement in zSql. 
1cc60 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
1cc70 6f 6e 6c 79 20 63 6f 6d 70 69 6c 65 20 74 68 65  only compile the
1cc80 20 66 69 72 73 74 0a 2a 2a 20 73 74 61 74 65 6d   first.** statem
1cc90 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20  ent in zSql, so 
1cca0 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 20  *pzTail is left 
1ccb0 70 6f 69 6e 74 69 6e 67 20 74 6f 20 77 68 61 74  pointing to what
1ccc0 20 72 65 6d 61 69 6e 73 0a 2a 2a 20 75 6e 63 6f   remains.** unco
1ccd0 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 2a 70  mpiled..**.** *p
1cce0 70 53 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f  pStmt is left po
1ccf0 69 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70  inting to a comp
1cd00 69 6c 65 64 20 5b 70 72 65 70 61 72 65 64 20 73  iled [prepared s
1cd10 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63  tatement] that c
1cd20 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65  an be.** execute
1cd30 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
1cd40 5f 73 74 65 70 28 29 5d 2e 20 20 4f 72 20 69 66  _step()].  Or if
1cd50 20 74 68 65 72 65 20 69 73 20 61 6e 20 65 72 72   there is an err
1cd60 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69 73 0a 2a  or, *ppStmt is.*
1cd70 2a 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 20 20  * set to NULL.  
1cd80 49 66 20 74 68 65 20 69 6e 70 75 74 20 74 65 78  If the input tex
1cd90 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51  t contains no SQ
1cda0 4c 20 28 69 66 20 74 68 65 20 69 6e 70 75 74 0a  L (if the input.
1cdb0 2a 2a 20 69 73 20 61 6e 64 20 65 6d 70 74 79 20  ** is and empty 
1cdc0 73 74 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d  string or a comm
1cdd0 65 6e 74 29 20 74 68 65 6e 20 2a 70 70 53 74 6d  ent) then *ppStm
1cde0 74 20 69 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c  t is set to NULL
1cdf0 2e 0a 2a 2a 20 7b 55 31 33 30 31 38 7d 20 54 68  ..** {U13018} Th
1ce00 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64  e calling proced
1ce10 75 72 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62  ure is responsib
1ce20 6c 65 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20  le for deleting 
1ce30 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20  the.** compiled 
1ce40 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  SQL statement.**
1ce50 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
1ce60 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74 65  finalize()] afte
1ce70 72 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65  r it has finishe
1ce80 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 0a 2a 2a  d with it..**.**
1ce90 20 4f 6e 20 73 75 63 63 65 73 73 2c 20 5b 53 51   On success, [SQ
1cea0 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75  LITE_OK] is retu
1ceb0 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65  rned.  Otherwise
1cec0 20 61 6e 20 0a 2a 2a 20 5b 65 72 72 6f 72 20 63   an .** [error c
1ced0 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ode] is returned
1cee0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
1cef0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1cf00 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
1cf10 70 61 72 65 31 36 5f 76 32 28 29 20 69 6e 74 65  pare16_v2() inte
1cf20 72 66 61 63 65 73 20 61 72 65 0a 2a 2a 20 72 65  rfaces are.** re
1cf30 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c  commended for al
1cf40 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 20  l new programs. 
1cf50 54 68 65 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e  The two older in
1cf60 74 65 72 66 61 63 65 73 20 61 72 65 20 72 65 74  terfaces are ret
1cf70 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63  ained.** for bac
1cf80 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
1cf90 6c 69 74 79 2c 20 62 75 74 20 74 68 65 69 72 20  lity, but their 
1cfa0 75 73 65 20 69 73 20 64 69 73 63 6f 75 72 61 67  use is discourag
1cfb0 65 64 2e 0a 2a 2a 20 49 6e 20 74 68 65 20 22 76  ed..** In the "v
1cfc0 32 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74  2" interfaces, t
1cfd0 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74  he prepared stat
1cfe0 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73  ement.** that is
1cff0 20 72 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b   returned (the [
1d000 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62  sqlite3_stmt] ob
1d010 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61  ject) contains a
1d020 20 63 6f 70 79 20 6f 66 20 74 68 65 20 0a 2a 2a   copy of the .**
1d030 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65   original SQL te
1d040 78 74 2e 20 7b 45 4e 44 7d 20 54 68 69 73 20 63  xt. {END} This c
1d050 61 75 73 65 73 20 74 68 65 20 5b 73 71 6c 69 74  auses the [sqlit
1d060 65 33 5f 73 74 65 70 28 29 5d 20 69 6e 74 65 72  e3_step()] inter
1d070 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76  face to.** behav
1d080 65 20 61 20 64 69 66 66 65 72 65 6e 74 6c 79 20  e a differently 
1d090 69 6e 20 74 77 6f 20 77 61 79 73 3a 0a 2a 2a 0a  in two ways:.**.
1d0a0 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a  ** <ol>.** <li>.
1d0b0 2a 2a 20 49 66 20 74 68 65 20 64 61 74 61 62 61  ** If the databa
1d0c0 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65  se schema change
1d0d0 73 2c 20 69 6e 73 74 65 61 64 20 6f 66 20 72 65  s, instead of re
1d0e0 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f  turning [SQLITE_
1d0f0 53 43 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a  SCHEMA] as it.**
1d100 20 61 6c 77 61 79 73 20 75 73 65 64 20 74 6f 20   always used to 
1d110 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  do, [sqlite3_ste
1d120 70 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61  p()] will automa
1d130 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c  tically recompil
1d140 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61  e the SQL.** sta
1d150 74 65 6d 65 6e 74 20 61 6e 64 20 74 72 79 20 74  tement and try t
1d160 6f 20 72 75 6e 20 69 74 20 61 67 61 69 6e 2e 20  o run it again. 
1d170 20 49 66 20 74 68 65 20 73 63 68 65 6d 61 20 68   If the schema h
1d180 61 73 20 63 68 61 6e 67 65 64 20 69 6e 0a 2a 2a  as changed in.**
1d190 20 61 20 77 61 79 20 74 68 61 74 20 6d 61 6b 65   a way that make
1d1a0 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  s the statement 
1d1b0 6e 6f 20 6c 6f 6e 67 65 72 20 76 61 6c 69 64 2c  no longer valid,
1d1c0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1d1d0 5d 20 77 69 6c 6c 20 73 74 69 6c 6c 0a 2a 2a 20  ] will still.** 
1d1e0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 53  return [SQLITE_S
1d1f0 43 48 45 4d 41 5d 2e 20 20 42 75 74 20 75 6e 6c  CHEMA].  But unl
1d200 69 6b 65 20 74 68 65 20 6c 65 67 61 63 79 20 62  ike the legacy b
1d210 65 68 61 76 69 6f 72 2c 20 0a 2a 2a 20 5b 53 51  ehavior, .** [SQ
1d220 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 69 73 20  LITE_SCHEMA] is 
1d230 6e 6f 77 20 61 20 66 61 74 61 6c 20 65 72 72 6f  now a fatal erro
1d240 72 2e 20 20 43 61 6c 6c 69 6e 67 0a 2a 2a 20 5b  r.  Calling.** [
1d250 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1d260 76 32 28 29 5d 20 61 67 61 69 6e 20 77 69 6c 6c  v2()] again will
1d270 20 6e 6f 74 20 6d 61 6b 65 20 74 68 65 0a 2a 2a   not make the.**
1d280 20 65 72 72 6f 72 20 67 6f 20 61 77 61 79 2e 20   error go away. 
1d290 20 4e 6f 74 65 3a 20 75 73 65 20 5b 73 71 6c 69   Note: use [sqli
1d2a0 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 74 6f  te3_errmsg()] to
1d2b0 20 66 69 6e 64 20 74 68 65 20 74 65 78 74 0a 2a   find the text.*
1d2c0 2a 20 6f 66 20 74 68 65 20 70 61 72 73 69 6e 67  * of the parsing
1d2d0 20 65 72 72 6f 72 20 74 68 61 74 20 72 65 73 75   error that resu
1d2e0 6c 74 73 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54  lts in an [SQLIT
1d2f0 45 5f 53 43 48 45 4d 41 5d 20 72 65 74 75 72 6e  E_SCHEMA] return
1d300 2e 20 7b 45 4e 44 7d 0a 2a 2a 20 3c 2f 6c 69 3e  . {END}.** </li>
1d310 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 57  .**.** <li>.** W
1d320 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63  hen an error occ
1d330 75 72 73 2c 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  urs, .** [sqlite
1d340 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 72  3_step()] will r
1d350 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65  eturn one of the
1d360 20 64 65 74 61 69 6c 65 64 20 0a 2a 2a 20 5b 65   detailed .** [e
1d370 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b  rror codes] or [
1d380 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63  extended error c
1d390 6f 64 65 73 5d 2e 20 0a 2a 2a 20 54 68 65 20 6c  odes]. .** The l
1d3a0 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 20 77  egacy behavior w
1d3b0 61 73 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33  as that [sqlite3
1d3c0 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f  _step()] would o
1d3d0 6e 6c 79 20 72 65 74 75 72 6e 20 61 20 67 65 6e  nly return a gen
1d3e0 65 72 69 63 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  eric.** [SQLITE_
1d3f0 45 52 52 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f  ERROR] result co
1d400 64 65 20 61 6e 64 20 79 6f 75 20 77 6f 75 6c 64  de and you would
1d410 20 68 61 76 65 20 74 6f 20 6d 61 6b 65 20 61 20   have to make a 
1d420 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 0a 2a  second call to.*
1d430 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
1d440 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ()] in order to 
1d450 66 69 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79  find the underly
1d460 69 6e 67 20 63 61 75 73 65 20 6f 66 20 74 68 65  ing cause of the
1d470 20 70 72 6f 62 6c 65 6d 2e 0a 2a 2a 20 57 69 74   problem..** Wit
1d480 68 20 74 68 65 20 22 76 32 22 20 70 72 65 70 61  h the "v2" prepa
1d490 72 65 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74  re interfaces, t
1d4a0 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 72 65  he underlying re
1d4b0 61 73 6f 6e 20 66 6f 72 20 74 68 65 20 65 72 72  ason for the err
1d4c0 6f 72 20 69 73 0a 2a 2a 20 72 65 74 75 72 6e 65  or is.** returne
1d4d0 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a  d immediately..*
1d4e0 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e  * </li>.** </ol>
1d4f0 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
1d500 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 30 31 31  S:.**.** {F13011
1d510 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 70  } The [sqlite3_p
1d520 72 65 70 61 72 65 28 64 62 2c 7a 53 71 6c 2c 2e  repare(db,zSql,.
1d530 2e 2e 29 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 20  ..)] and.**     
1d540 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 70 72       [sqlite3_pr
1d550 65 70 61 72 65 5f 76 32 28 64 62 2c 7a 53 71 6c  epare_v2(db,zSql
1d560 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65  ,...)] interface
1d570 73 20 69 6e 74 65 72 70 72 65 74 20 74 68 65 0a  s interpret the.
1d580 2a 2a 20 20 20 20 20 20 20 20 20 20 74 65 78 74  **          text
1d590 20 69 6e 20 74 68 65 69 72 20 7a 53 71 6c 20 70   in their zSql p
1d5a0 61 72 61 6d 65 74 65 72 20 61 73 20 55 54 46 2d  arameter as UTF-
1d5b0 38 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 30 31 32  8..**.** {F13012
1d5c0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 70  } The [sqlite3_p
1d5d0 72 65 70 61 72 65 31 36 28 64 62 2c 7a 53 71 6c  repare16(db,zSql
1d5e0 2c 2e 2e 2e 29 5d 20 61 6e 64 0a 2a 2a 20 20 20  ,...)] and.**   
1d5f0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
1d600 70 72 65 70 61 72 65 31 36 5f 76 32 28 64 62 2c  prepare16_v2(db,
1d610 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72  zSql,...)] inter
1d620 66 61 63 65 73 20 69 6e 74 65 72 70 72 65 74 20  faces interpret 
1d630 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
1d640 74 65 78 74 20 69 6e 20 74 68 65 69 72 20 7a 53  text in their zS
1d650 71 6c 20 70 61 72 61 6d 65 74 65 72 20 61 73 20  ql parameter as 
1d660 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61  UTF-16 in the na
1d670 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e  tive byte order.
1d680 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 30 31 33 7d 20  .**.** {F13013} 
1d690 49 66 20 74 68 65 20 6e 42 79 74 65 20 61 72 67  If the nByte arg
1d6a0 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65  ument to [sqlite
1d6b0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 64 62 2c  3_prepare_v2(db,
1d6c0 7a 53 71 6c 2c 6e 42 79 74 65 2c 2e 2e 2e 29 5d  zSql,nByte,...)]
1d6d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64  .**          and
1d6e0 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 69 73   its variants is
1d6f0 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c   less than zero,
1d700 20 74 68 65 6e 20 53 51 4c 20 74 65 78 74 20 69   then SQL text i
1d710 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  s.**          re
1d720 61 64 20 66 72 6f 6d 20 7a 53 71 6c 20 69 73 20  ad from zSql is 
1d730 72 65 61 64 20 75 70 20 74 6f 20 74 68 65 20 66  read up to the f
1d740 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e  irst zero termin
1d750 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  ator..**.** {F13
1d760 30 31 34 7d 20 49 66 20 74 68 65 20 6e 42 79 74  014} If the nByt
1d770 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73  e argument to [s
1d780 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1d790 32 28 64 62 2c 7a 53 71 6c 2c 6e 42 79 74 65 2c  2(db,zSql,nByte,
1d7a0 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  ...)].**        
1d7b0 20 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e    and its varian
1d7c0 74 73 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69  ts is non-negati
1d7d0 76 65 2c 20 74 68 65 6e 20 61 74 20 6d 6f 73 74  ve, then at most
1d7e0 20 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a   nBytes bytes.**
1d7f0 20 20 20 20 20 20 20 20 20 20 53 51 4c 20 74 65            SQL te
1d800 78 74 20 69 73 20 72 65 61 64 20 66 72 6f 6d 20  xt is read from 
1d810 7a 53 71 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  zSql..**.** {F13
1d820 30 31 35 7d 20 49 6e 20 5b 73 71 6c 69 74 65 33  015} In [sqlite3
1d830 5f 70 72 65 70 61 72 65 5f 76 32 28 64 62 2c 7a  _prepare_v2(db,z
1d840 53 71 6c 2c 4e 2c 50 2c 70 7a 54 61 69 6c 29 5d  Sql,N,P,pzTail)]
1d850 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74   and its variant
1d860 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 66  s.**          if
1d870 20 74 68 65 20 7a 53 71 6c 20 69 6e 70 75 74 20   the zSql input 
1d880 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 6d 6f  text contains mo
1d890 72 65 20 74 68 61 6e 20 6f 6e 65 20 53 51 4c 20  re than one SQL 
1d8a0 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 20 20 20  statement.**    
1d8b0 20 20 20 20 20 20 61 6e 64 20 70 7a 54 61 69 6c        and pzTail
1d8c0 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68   is not NULL, th
1d8d0 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61  en *pzTail is ma
1d8e0 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74  de to point to t
1d8f0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  he.**          f
1d900 69 72 73 74 20 62 79 74 65 20 70 61 73 74 20 74  irst byte past t
1d910 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66 69  he end of the fi
1d920 72 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  rst SQL statemen
1d930 74 20 69 6e 20 7a 53 71 6c 2e 0a 2a 2a 20 20 20  t in zSql..**   
1d940 20 20 20 20 20 20 20 3c 74 6f 64 6f 3e 57 68 61         <todo>Wha
1d950 74 20 64 6f 65 73 20 2a 70 7a 54 61 69 6c 20 70  t does *pzTail p
1d960 6f 69 6e 74 20 74 6f 20 69 66 20 74 68 65 72 65  oint to if there
1d970 20 69 73 20 6f 6e 65 20 73 74 61 74 65 6d 65 6e   is one statemen
1d980 74 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20  t?</todo>.**.** 
1d990 7b 46 31 33 30 31 36 7d 20 41 20 73 75 63 63 65  {F13016} A succe
1d9a0 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73  ssful call to [s
1d9b0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1d9c0 32 28 64 62 2c 7a 53 71 6c 2c 4e 2c 70 70 53 74  2(db,zSql,N,ppSt
1d9d0 6d 74 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20  mt,...)].**     
1d9e0 20 20 20 20 20 6f 72 20 6f 6e 65 20 6f 66 20 69       or one of i
1d9f0 74 73 20 76 61 72 69 61 6e 74 73 20 77 72 69 74  ts variants writ
1da00 65 73 20 69 6e 74 6f 20 2a 70 70 53 74 6d 74 20  es into *ppStmt 
1da10 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e  a pointer to a n
1da20 65 77 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ew.**          [
1da30 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1da40 6e 74 5d 20 6f 72 20 61 20 70 6f 69 6e 74 65 72  nt] or a pointer
1da50 20 74 6f 20 4e 55 4c 4c 0a 2a 2a 20 20 20 20 20   to NULL.**     
1da60 20 20 20 20 20 69 66 20 7a 53 71 6c 20 63 6f 6e       if zSql con
1da70 74 61 69 6e 73 20 6e 6f 74 68 69 6e 67 20 6f 74  tains nothing ot
1da80 68 65 72 20 74 68 61 6e 20 77 68 69 74 65 73 70  her than whitesp
1da90 61 63 65 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 2e  ace or comments.
1daa0 20 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 30 31 39 7d   .**.** {F13019}
1dab0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72   The [sqlite3_pr
1dac0 65 70 61 72 65 5f 76 32 28 29 5d 20 69 6e 74 65  epare_v2()] inte
1dad0 72 66 61 63 65 20 61 6e 64 20 69 74 73 20 76 61  rface and its va
1dae0 72 69 61 6e 74 73 20 72 65 74 75 72 6e 0a 2a 2a  riants return.**
1daf0 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54            [SQLIT
1db00 45 5f 4f 4b 5d 20 6f 72 20 61 6e 20 61 70 70 72  E_OK] or an appr
1db10 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63  opriate [error c
1db20 6f 64 65 5d 20 75 70 6f 6e 20 66 61 69 6c 75 72  ode] upon failur
1db30 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 30 32 31  e..**.** {F13021
1db40 7d 20 42 65 66 6f 72 65 20 5b 73 71 6c 69 74 65  } Before [sqlite
1db50 33 5f 70 72 65 70 61 72 65 28 64 62 2c 7a 53 71  3_prepare(db,zSq
1db60 6c 2c 6e 42 79 74 65 2c 70 70 53 74 6d 74 2c 70  l,nByte,ppStmt,p
1db70 7a 54 61 69 6c 29 5d 20 6f 72 20 69 74 73 0a 2a  zTail)] or its.*
1db80 2a 20 20 20 20 20 20 20 20 20 20 76 61 72 69 61  *          varia
1db90 6e 74 73 20 72 65 74 75 72 6e 73 20 61 6e 20 65  nts returns an e
1dba0 72 72 6f 72 20 28 61 6e 79 20 76 61 6c 75 65 20  rror (any value 
1dbb0 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
1dbc0 54 45 5f 4f 4b 5d 29 0a 2a 2a 20 20 20 20 20 20  TE_OK]).**      
1dbd0 20 20 20 20 69 74 20 66 69 72 73 74 20 73 65 74      it first set
1dbe0 73 20 2a 70 70 53 74 6d 74 20 74 6f 20 4e 55 4c  s *ppStmt to NUL
1dbf0 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  L..*/.int sqlite
1dc00 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73 71 6c  3_prepare(.  sql
1dc10 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
1dc20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
1dc30 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
1dc40 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20  st char *zSql,  
1dc50 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
1dc60 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63  ement, UTF-8 enc
1dc70 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
1dc80 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
1dc90 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
1dca0 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
1dcb0 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
1dcc0 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
1dcd0 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
1dce0 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
1dcf0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a   const char **pz
1dd00 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
1dd10 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
1dd20 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
1dd30 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  ql */.);.int sql
1dd40 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1dd50 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
1dd60 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
1dd70 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
1dd80 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
1dd90 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
1dda0 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
1ddb0 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  -8 encoded */.  
1ddc0 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
1ddd0 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
1dde0 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
1ddf0 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
1de00 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
1de10 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
1de20 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
1de30 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
1de40 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  r **pzTail     /
1de50 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
1de60 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
1de70 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69   of zSql */.);.i
1de80 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
1de90 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20  re16(.  sqlite3 
1dea0 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
1deb0 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
1dec0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
1ded0 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  id *zSql,       
1dee0 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
1def0 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64  , UTF-16 encoded
1df00 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
1df10 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
1df20 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
1df30 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
1df40 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
1df50 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
1df60 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
1df70 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
1df80 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c  st void **pzTail
1df90 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
1dfa0 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
1dfb0 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
1dfc0 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
1dfd0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 0a 20  _prepare16_v2(. 
1dfe0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
1dff0 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
1e000 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
1e010 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71   const void *zSq
1e020 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
1e030 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31  statement, UTF-1
1e040 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  6 encoded */.  i
1e050 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
1e060 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
1e070 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
1e080 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
1e090 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
1e0a0 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
1e0b0 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
1e0c0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
1e0d0 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
1e0e0 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
1e0f0 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
1e100 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f  of zSql */.);../
1e110 2a 0a 2a 2a 20 43 41 50 49 52 45 46 3a 20 52 65  *.** CAPIREF: Re
1e120 74 72 69 65 76 69 6e 67 20 53 74 61 74 65 6d 65  trieving Stateme
1e130 6e 74 20 53 51 4c 20 7b 46 31 33 31 30 30 7d 0a  nt SQL {F13100}.
1e140 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72  **.** This inter
1e150 66 61 63 65 20 20 63 61 6e 20 62 65 20 75 73 65  face  can be use
1e160 64 20 74 6f 20 72 65 74 72 69 65 76 65 20 61 20  d to retrieve a 
1e170 73 61 76 65 64 20 63 6f 70 79 20 6f 66 20 74 68  saved copy of th
1e180 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 51  e original.** SQ
1e190 4c 20 74 65 78 74 20 75 73 65 64 20 74 6f 20 63  L text used to c
1e1a0 72 65 61 74 65 20 61 20 5b 70 72 65 70 61 72 65  reate a [prepare
1e1b0 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  d statement]..**
1e1c0 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
1e1d0 2a 2a 0a 2a 2a 20 7b 46 31 33 31 30 31 7d 20 49  **.** {F13101} I
1e1e0 66 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  f the [prepared 
1e1f0 73 74 61 74 65 6d 65 6e 74 5d 20 70 61 73 73 65  statement] passe
1e200 64 20 61 73 20 0a 2a 2a 20 20 20 20 20 20 20 20  d as .**        
1e210 20 20 74 68 65 20 61 6e 20 61 72 67 75 6d 65 6e    the an argumen
1e220 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 71  t to [sqlite3_sq
1e230 6c 28 29 5d 20 77 61 73 20 63 6f 6d 70 69 6c 65  l()] was compile
1e240 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f  d.**          co
1e250 6d 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74  mpiled using eit
1e260 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  her [sqlite3_pre
1e270 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a  pare_v2()] or.**
1e280 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
1e290 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
1e2a0 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  )],.**          
1e2b0 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 73 71  then [sqlite3_sq
1e2c0 6c 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 72 65  l()] function re
1e2d0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
1e2e0 74 6f 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20  to a.**         
1e2f0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1e300 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69   string containi
1e310 6e 67 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65  ng a UTF-8 rende
1e320 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20  ring.**         
1e330 20 6f 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c   of the original
1e340 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a   SQL statement..
1e350 2a 2a 0a 2a 2a 20 7b 46 31 33 31 30 32 7d 20 49  **.** {F13102} I
1e360 66 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  f the [prepared 
1e370 73 74 61 74 65 6d 65 6e 74 5d 20 70 61 73 73 65  statement] passe
1e380 64 20 61 73 20 0a 2a 2a 20 20 20 20 20 20 20 20  d as .**        
1e390 20 20 74 68 65 20 61 6e 20 61 72 67 75 6d 65 6e    the an argumen
1e3a0 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 71  t to [sqlite3_sq
1e3b0 6c 28 29 5d 20 77 61 73 20 63 6f 6d 70 69 6c 65  l()] was compile
1e3c0 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f  d.**          co
1e3d0 6d 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74  mpiled using eit
1e3e0 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  her [sqlite3_pre
1e3f0 70 61 72 65 28 29 5d 20 6f 72 0a 2a 2a 20 20 20  pare()] or.**   
1e400 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
1e410 70 72 65 70 61 72 65 31 36 28 29 5d 2c 0a 2a 2a  prepare16()],.**
1e420 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 5b            then [
1e430 73 71 6c 69 74 65 33 5f 73 71 6c 28 29 5d 20 66  sqlite3_sql()] f
1e440 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
1e450 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
1e460 2a 2a 0a 2a 2a 20 7b 46 31 33 31 30 33 7d 20 54  **.** {F13103} T
1e470 68 65 20 73 74 72 69 6e 67 20 72 65 74 75 72 6e  he string return
1e480 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73  ed by [sqlite3_s
1e490 71 6c 28 53 29 5d 20 69 73 20 76 61 6c 69 64 20  ql(S)] is valid 
1e4a0 75 6e 74 69 6c 20 74 68 65 0a 2a 2a 20 20 20 20  until the.**    
1e4b0 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20        [prepared 
1e4c0 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 73 20  statement] S is 
1e4d0 64 65 6c 65 74 65 64 20 75 73 69 6e 67 20 5b 73  deleted using [s
1e4e0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
1e4f0 53 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  S)]..*/.const ch
1e500 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28  ar *sqlite3_sql(
1e510 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
1e520 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
1e530 49 33 52 45 46 3a 20 20 44 79 6e 61 6d 69 63 61  I3REF:  Dynamica
1e540 6c 6c 79 20 54 79 70 65 64 20 56 61 6c 75 65 20  lly Typed Value 
1e550 4f 62 6a 65 63 74 20 20 7b 46 31 35 30 30 30 7d  Object  {F15000}
1e560 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70  .** KEYWORDS: {p
1e570 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
1e580 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65  _value} {unprote
1e590 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
1e5a0 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  ue}.**.** SQLite
1e5b0 20 75 73 65 73 20 74 68 65 20 73 71 6c 69 74 65   uses the sqlite
1e5c0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74  3_value object t
1e5d0 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20  o represent all 
1e5e0 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63  values.** that c
1e5f0 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20  an be stored in 
1e600 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65  a database table
1e610 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73  ..** SQLite uses
1e620 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 20   dynamic typing 
1e630 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20 69  for the values i
1e640 74 20 73 74 6f 72 65 73 2e 20 20 0a 2a 2a 20 56  t stores.  .** V
1e650 61 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e 20  alues stored in 
1e660 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
1e670 6a 65 63 74 73 20 63 61 6e 20 62 65 0a 2a 2a 20  jects can be.** 
1e680 62 65 20 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f  be integers, flo
1e690 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75  ating point valu
1e6a0 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f  es, strings, BLO
1e6b0 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a  Bs, or NULL..**.
1e6c0 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f 76 61  ** An sqlite3_va
1e6d0 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 62  lue object may b
1e6e0 65 20 65 69 74 68 65 72 20 22 70 72 6f 74 65 63  e either "protec
1e6f0 74 65 64 22 20 6f 72 20 22 75 6e 70 72 6f 74 65  ted" or "unprote
1e700 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69  cted"..** Some i
1e710 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72  nterfaces requir
1e720 65 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 71  e a protected sq
1e730 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74  lite3_value.  Ot
1e740 68 65 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  her interfaces.*
1e750 2a 20 77 69 6c 6c 20 61 63 63 65 70 74 20 65 69  * will accept ei
1e760 74 68 65 72 20 61 20 70 72 6f 74 65 63 74 65 64  ther a protected
1e770 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74   or an unprotect
1e780 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
1e790 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74 65 72  ..** Every inter
1e7a0 66 61 63 65 20 74 68 61 74 20 61 63 63 65 70 74  face that accept
1e7b0 73 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  s sqlite3_value 
1e7c0 61 72 67 75 6d 65 6e 74 73 20 73 70 65 63 69 66  arguments specif
1e7d0 69 65 73 20 0a 2a 2a 20 77 68 65 74 68 65 72 20  ies .** whether 
1e7e0 6f 72 20 6e 6f 74 20 69 74 20 72 65 71 75 69 72  or not it requir
1e7f0 65 73 20 61 20 70 72 6f 74 65 63 74 65 64 20 73  es a protected s
1e800 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a  qlite3_value..**
1e810 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 22 70  .** The terms "p
1e820 72 6f 74 65 63 74 65 64 22 20 61 6e 64 20 22 75  rotected" and "u
1e830 6e 70 72 6f 74 65 63 74 65 64 22 20 72 65 66 65  nprotected" refe
1e840 72 20 74 6f 20 77 68 65 74 68 65 72 20 6f 72 20  r to whether or 
1e850 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69  not.** a mutex i
1e860 73 20 68 65 6c 64 2e 20 20 41 20 69 6e 74 65 72  s held.  A inter
1e870 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 68 65 6c  nal mutex is hel
1e880 64 20 66 6f 72 20 61 20 70 72 6f 74 65 63 74 65  d for a protecte
1e890 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  d.** sqlite3_val
1e8a0 75 65 20 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f  ue object but no
1e8b0 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66   mutex is held f
1e8c0 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65  or an unprotecte
1e8d0 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  d.** sqlite3_val
1e8e0 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 53  ue object.  If S
1e8f0 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
1e900 64 20 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74  d to be single-t
1e910 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 69 74 68  hreaded.** (with
1e920 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
1e930 46 45 3d 30 20 61 6e 64 20 77 69 74 68 20 5b 73  FE=0 and with [s
1e940 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66  qlite3_threadsaf
1e950 65 28 29 5d 20 72 65 74 75 72 6e 69 6e 67 20 30  e()] returning 0
1e960 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65 20  ).** then there 
1e970 69 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f  is no distinctio
1e980 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 70 72 6f  n between.** pro
1e990 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f  tected and unpro
1e9a0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
1e9b0 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e 64  alue objects and
1e9c0 20 74 68 65 79 20 63 61 6e 20 62 65 0a 2a 2a 20   they can be.** 
1e9d0 75 73 65 64 20 69 6e 74 65 72 63 68 61 6e 67 65  used interchange
1e9e0 61 62 6c 65 2e 20 20 48 6f 77 65 76 65 72 2c 20  able.  However, 
1e9f0 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65  for maximum code
1ea00 20 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74 0a   portability it.
1ea10 2a 2a 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  ** is recommende
1ea20 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69  d that applicati
1ea30 6f 6e 73 20 6d 61 6b 65 20 74 68 65 20 64 69 73  ons make the dis
1ea40 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e  tinction between
1ea50 0a 2a 2a 20 62 65 74 77 65 65 6e 20 70 72 6f 74  .** between prot
1ea60 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74  ected and unprot
1ea70 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
1ea80 6c 75 65 20 6f 62 6a 65 63 74 73 20 65 76 65 6e  lue objects even
1ea90 20 69 66 0a 2a 2a 20 74 68 65 79 20 61 72 65 20   if.** they are 
1eaa0 73 69 6e 67 6c 65 20 74 68 72 65 61 64 65 64 2e  single threaded.
1eab0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
1eac0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
1ead0 20 74 68 61 74 20 61 72 65 20 70 61 73 73 65 64   that are passed
1eae0 20 61 73 20 70 61 72 61 6d 65 74 65 72 73 20 69   as parameters i
1eaf0 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65  nto the.** imple
1eb00 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 0a 2a 2a  mentation of .**
1eb10 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
1eb20 5f 66 75 6e 63 74 69 6f 6e 20 7c 20 61 70 70 6c  _function | appl
1eb30 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
1eb40 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a  SQL functions].*
1eb50 2a 20 61 72 65 20 70 72 6f 74 65 63 74 65 64 2e  * are protected.
1eb60 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
1eb70 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72 65 74  value object ret
1eb80 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c  urned by.** [sql
1eb90 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
1eba0 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74 65 63  e()] is unprotec
1ebb0 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63  ted..** Unprotec
1ebc0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
1ebd0 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e  e objects may on
1ebe0 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68 0a  ly be used with.
1ebf0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  ** [sqlite3_resu
1ec00 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20  lt_value()] and 
1ec10 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61  [sqlite3_bind_va
1ec20 6c 75 65 28 29 5d 2e 20 20 0a 2a 2a 20 54 68 65  lue()].  .** The
1ec30 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
1ec40 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76  blob | sqlite3_v
1ec50 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d  alue_type()] fam
1ec60 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66  ily of.** interf
1ec70 61 63 65 73 20 72 65 71 75 69 72 65 20 70 72 6f  aces require pro
1ec80 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
1ec90 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f  alue objects..*/
1eca0 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
1ecb0 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  Mem sqlite3_valu
1ecc0 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  e;../*.** CAPI3R
1ecd0 45 46 3a 20 20 53 51 4c 20 46 75 6e 63 74 69 6f  EF:  SQL Functio
1ece0 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74  n Context Object
1ecf0 20 7b 46 31 36 30 30 31 7d 0a 2a 2a 0a 2a 2a 20   {F16001}.**.** 
1ed00 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77  The context in w
1ed10 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63  hich an SQL func
1ed20 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73  tion executes is
1ed30 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a   stored in an.**
1ed40 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
1ed50 20 6f 62 6a 65 63 74 2e 20 20 41 20 70 6f 69 6e   object.  A poin
1ed60 74 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74 65  ter to an sqlite
1ed70 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 20 6f 62 6a  3_context.** obj
1ed80 65 63 74 20 69 73 20 61 6c 77 61 79 73 20 66 69  ect is always fi
1ed90 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
1eda0 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72   .** [sqlite3_cr
1edb0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 20 7c 20  eate_function | 
1edc0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
1edd0 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
1ede0 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  s]..** The appli
1edf0 63 61 74 69 6f 6e 65 64 2d 64 65 66 69 6e 65 64  cationed-defined
1ee00 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d   SQL function im
1ee10 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c  plementation wil
1ee20 6c 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20 70  l pass this.** p
1ee30 6f 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20 69  ointer through i
1ee40 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  nto calls to.** 
1ee50 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
1ee60 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 72 65  int | sqlite3_re
1ee70 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  sult()],.** [sql
1ee80 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
1ee90 6f 6e 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 5b 73  ontext()],.** [s
1eea0 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61  qlite3_user_data
1eeb0 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
1eec0 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64  _context_db_hand
1eed0 6c 65 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  le()],.** [sqlit
1eee0 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29  e3_get_auxdata()
1eef0 5d 2c 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74  ], and/or [sqlit
1ef00 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
1ef10 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  ]..*/.typedef st
1ef20 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e  ruct sqlite3_con
1ef30 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e  text sqlite3_con
1ef40 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  text;../*.** CAP
1ef50 49 33 52 45 46 3a 20 20 42 69 6e 64 69 6e 67 20  I3REF:  Binding 
1ef60 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70 61 72  Values To Prepar
1ef70 65 64 20 53 74 61 74 65 6d 65 6e 74 73 20 7b 46  ed Statements {F
1ef80 31 33 35 30 30 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20  13500}.**.** In 
1ef90 74 68 65 20 53 51 4c 20 73 74 72 69 6e 67 73 20  the SQL strings 
1efa0 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65  input to [sqlite
1efb0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
1efc0 61 6e 64 20 69 74 73 0a 2a 2a 20 76 61 72 69 61  and its.** varia
1efd0 6e 74 73 2c 20 6c 69 74 65 72 61 6c 73 20 6d 61  nts, literals ma
1efe0 79 20 62 65 20 72 65 70 6c 61 63 65 20 62 79 20  y be replace by 
1eff0 61 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 6f  a parameter in o
1f000 6e 65 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 66  ne.** of these f
1f010 6f 72 6d 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  orms:.**.** <ul>
1f020 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c  .** <li>  ?.** <
1f030 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69  li>  ?NNN.** <li
1f040 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20  >  :VVV.** <li> 
1f050 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24   @VVV.** <li>  $
1f060 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  VVV.** </ul>.**.
1f070 2a 2a 20 49 6e 20 74 68 65 20 70 61 72 61 6d 65  ** In the parame
1f080 74 65 72 20 66 6f 72 6d 73 20 73 68 6f 77 6e 20  ter forms shown 
1f090 61 62 6f 76 65 20 4e 4e 4e 20 69 73 20 61 6e 20  above NNN is an 
1f0a0 69 6e 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c  integer literal,
1f0b0 0a 2a 2a 20 56 56 56 20 61 6c 70 68 61 2d 6e 75  .** VVV alpha-nu
1f0c0 6d 65 72 69 63 20 70 61 72 61 6d 65 74 65 72 20  meric parameter 
1f0d0 6e 61 6d 65 2e 0a 2a 2a 20 54 68 65 20 76 61 6c  name..** The val
1f0e0 75 65 73 20 6f 66 20 74 68 65 73 65 20 70 61 72  ues of these par
1f0f0 61 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63 61  ameters (also ca
1f100 6c 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61 6d  lled "host param
1f110 65 74 65 72 20 6e 61 6d 65 73 22 0a 2a 2a 20 6f  eter names".** o
1f120 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74 65 72  r "SQL parameter
1f130 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65  s").** can be se
1f140 74 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69  t using the sqli
1f150 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
1f160 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68 65  tines defined he
1f170 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  re..**.** The fi
1f180 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
1f190 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
1f1a0 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 61 6c  _*() routines al
1f1b0 77 61 79 73 0a 2a 2a 20 69 73 20 61 20 70 6f 69  ways.** is a poi
1f1c0 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c  nter to the [sql
1f1d0 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63  ite3_stmt] objec
1f1e0 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a  t returned from.
1f1f0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
1f200 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73  are_v2()] or its
1f210 20 76 61 72 69 61 6e 74 73 2e 20 54 68 65 20 73   variants. The s
1f220 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e  econd.** argumen
1f230 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f  t is the index o
1f240 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
1f250 74 6f 20 62 65 20 73 65 74 2e 20 54 68 65 0a 2a  to be set. The.*
1f260 2a 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  * first paramete
1f270 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f  r has an index o
1f280 66 20 31 2e 20 20 57 68 65 6e 20 74 68 65 20 73  f 1.  When the s
1f290 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 70 61 72  ame named.** par
1f2a0 61 6d 65 74 65 72 20 69 73 20 75 73 65 64 20 6d  ameter is used m
1f2b0 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73  ore than once, s
1f2c0 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71  econd and subseq
1f2d0 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e  uent.** occurren
1f2e0 63 65 73 20 68 61 76 65 20 74 68 65 20 73 61 6d  ces have the sam
1f2f0 65 20 69 6e 64 65 78 20 61 73 20 74 68 65 20 66  e index as the f
1f300 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65 2e  irst occurrence.
1f310 20 0a 2a 2a 20 54 68 65 20 69 6e 64 65 78 20 66   .** The index f
1f320 6f 72 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74  or named paramet
1f330 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65  ers can be looke
1f340 64 20 75 70 20 75 73 69 6e 67 20 74 68 65 0a 2a  d up using the.*
1f350 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
1f360 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29  parameter_name()
1f370 5d 20 41 50 49 20 69 66 20 64 65 73 69 72 65 64  ] API if desired
1f380 2e 20 20 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20  .  The index.** 
1f390 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d  for "?NNN" param
1f3a0 65 74 65 72 73 20 69 73 20 74 68 65 20 76 61 6c  eters is the val
1f3b0 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 54 68  ue of NNN..** Th
1f3c0 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74  e NNN value must
1f3d0 20 62 65 20 62 65 74 77 65 65 6e 20 31 20 61 6e   be between 1 an
1f3e0 64 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69  d the compile-ti
1f3f0 6d 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  me.** parameter 
1f400 53 51 4c 49 54 45 5f 4d 41 58 5f 56 41 52 49 41  SQLITE_MAX_VARIA
1f410 42 4c 45 5f 4e 55 4d 42 45 52 20 28 64 65 66 61  BLE_NUMBER (defa
1f420 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e  ult value: 999).
1f430 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72 64  .**.** The third
1f440 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
1f450 20 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 74   value to bind t
1f460 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e  o the parameter.
1f470 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 0a  .**.** In those.
1f480 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  ** routines that
1f490 20 68 61 76 65 20 61 20 66 6f 75 72 74 68 20 61   have a fourth a
1f4a0 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c  rgument, its val
1f4b0 75 65 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  ue is the number
1f4c0 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20 69 6e 20   of bytes.** in 
1f4d0 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20  the parameter.  
1f4e0 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65  To be clear: the
1f4f0 20 76 61 6c 75 65 20 69 73 20 74 68 65 20 6e 75   value is the nu
1f500 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 73  mber of <u>bytes
1f510 3c 2f 75 3e 0a 2a 2a 20 69 6e 20 74 68 65 20 76  </u>.** in the v
1f520 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75  alue, not the nu
1f530 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65  mber of characte
1f540 72 73 2e 20 0a 2a 2a 20 49 66 20 74 68 65 20 66  rs. .** If the f
1f550 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
1f560 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
1f570 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73   length of the s
1f580 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20  tring is.** the 
1f590 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
1f5a0 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  up to the first 
1f5b0 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e  zero terminator.
1f5c0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 66 74 68  .**.** The fifth
1f5d0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
1f5e0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29  ite3_bind_blob()
1f5f0 2c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  , sqlite3_bind_t
1f600 65 78 74 28 29 2c 20 61 6e 64 0a 2a 2a 20 73 71  ext(), and.** sq
1f610 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
1f620 36 28 29 20 69 73 20 61 20 64 65 73 74 72 75 63  6() is a destruc
1f630 74 6f 72 20 75 73 65 64 20 74 6f 20 64 69 73 70  tor used to disp
1f640 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20  ose of the BLOB 
1f650 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74  or.** string aft
1f660 65 72 20 53 51 4c 69 74 65 20 68 61 73 20 66 69  er SQLite has fi
1f670 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 20  nished with it. 
1f680 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67  If the fifth arg
1f690 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20  ument is.** the 
1f6a0 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53  special value [S
1f6b0 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74  QLITE_STATIC], t
1f6c0 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d  hen SQLite assum
1f6d0 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69  es that the.** i
1f6e0 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e  nformation is in
1f6f0 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67   static, unmanag
1f700 65 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65  ed space and doe
1f710 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65  s not need to be
1f720 20 66 72 65 65 64 2e 0a 2a 2a 20 49 66 20 74 68   freed..** If th
1f730 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74  e fifth argument
1f740 20 68 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b   has the value [
1f750 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54  SQLITE_TRANSIENT
1f760 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74  ], then.** SQLit
1f770 65 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20  e makes its own 
1f780 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20  private copy of 
1f790 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61  the data immedia
1f7a0 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20  tely, before.** 
1f7b0 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
1f7c0 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  _*() routine ret
1f7d0 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  urns..**.** The 
1f7e0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72  sqlite3_bind_zer
1f7f0 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20  oblob() routine 
1f800 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20  binds a BLOB of 
1f810 6c 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a  length N that.**
1f820 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20   is filled with 
1f830 7a 65 72 6f 73 2e 20 20 41 20 7a 65 72 6f 62 6c  zeros.  A zerobl
1f840 6f 62 20 75 73 65 73 20 61 20 66 69 78 65 64 20  ob uses a fixed 
1f850 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79  amount of memory
1f860 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74  .** (just an int
1f870 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 20  eger to hold it 
1f880 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69  size) while it i
1f890 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65  s being processe
1f8a0 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20  d..** Zeroblobs 
1f8b0 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20  are intended to 
1f8c0 73 65 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f  serve as placeho
1f8d0 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20  lders for BLOBs 
1f8e0 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74  whose.** content
1f8f0 20 69 73 20 6c 61 74 65 72 20 77 72 69 74 74 65   is later writte
1f900 6e 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c  n using .** [sql
1f910 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c  ite3_blob_open |
1f920 20 69 6e 63 72 65 6d 65 6e 74 20 42 4c 4f 42 20   increment BLOB 
1f930 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 20 41  I/O] routines. A
1f940 20 6e 65 67 61 74 69 76 65 0a 2a 2a 20 76 61 6c   negative.** val
1f950 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62  ue for the zerob
1f960 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61  lob results in a
1f970 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f   zero-length BLO
1f980 42 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  B..**.** The sql
1f990 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
1f9a0 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63  utines must be c
1f9b0 61 6c 6c 65 64 20 61 66 74 65 72 0a 2a 2a 20 5b  alled after.** [
1f9c0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1f9d0 76 32 28 29 5d 20 28 61 6e 64 20 69 74 73 20 76  v2()] (and its v
1f9e0 61 72 69 61 6e 74 73 29 20 6f 72 20 5b 73 71 6c  ariants) or [sql
1f9f0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61 6e  ite3_reset()] an
1fa00 64 0a 2a 2a 20 62 65 66 6f 72 65 20 5b 73 71 6c  d.** before [sql
1fa10 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a  ite3_step()]..**
1fa20 20 42 69 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f   Bindings are no
1fa30 74 20 63 6c 65 61 72 65 64 20 62 79 20 74 68 65  t cleared by the
1fa40 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
1fa50 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 55  )] routine..** U
1fa60 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72  nbound parameter
1fa70 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65  s are interprete
1fa80 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  d as NULL..**.**
1fa90 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
1faa0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
1fab0 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f 72  K] on success or
1fac0 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 20 69   an error code i
1fad0 66 0a 2a 2a 20 61 6e 79 74 68 69 6e 67 20 67 6f  f.** anything go
1fae0 65 73 20 77 72 6f 6e 67 2e 20 20 5b 53 51 4c 49  es wrong.  [SQLI
1faf0 54 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74  TE_RANGE] is ret
1fb00 75 72 6e 65 64 20 69 66 20 74 68 65 20 70 61 72  urned if the par
1fb10 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20  ameter.** index 
1fb20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e  is out of range.
1fb30 20 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d    [SQLITE_NOMEM]
1fb40 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20   is returned if 
1fb50 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a  malloc() fails..
1fb60 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  ** [SQLITE_MISUS
1fb70 45 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75  E] might be retu
1fb80 72 6e 65 64 20 69 66 20 74 68 65 73 65 20 72 6f  rned if these ro
1fb90 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65  utines are calle
1fba0 64 20 6f 6e 20 61 0a 2a 2a 20 76 69 72 74 75 61  d on a.** virtua
1fbb0 6c 20 6d 61 63 68 69 6e 65 20 74 68 61 74 20 69  l machine that i
1fbc0 73 20 74 68 65 20 77 72 6f 6e 67 20 73 74 61 74  s the wrong stat
1fbd0 65 20 6f 72 20 77 68 69 63 68 20 68 61 73 20 61  e or which has a
1fbe0 6c 72 65 61 64 79 20 62 65 65 6e 20 66 69 6e 61  lready been fina
1fbf0 6c 69 7a 65 64 2e 0a 2a 2a 20 44 65 74 65 63 74  lized..** Detect
1fc00 69 6f 6e 20 6f 66 20 6d 69 73 75 73 65 20 69 73  ion of misuse is
1fc10 20 75 6e 72 65 6c 69 61 62 6c 65 2e 20 20 41 70   unreliable.  Ap
1fc20 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c  plications shoul
1fc30 64 20 6e 6f 74 20 64 65 70 65 6e 64 0a 2a 2a 20  d not depend.** 
1fc40 6f 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  on SQLITE_MISUSE
1fc50 20 72 65 74 75 72 6e 73 2e 20 20 53 51 4c 49 54   returns.  SQLIT
1fc60 45 5f 4d 49 53 55 53 45 20 69 73 20 69 6e 74 65  E_MISUSE is inte
1fc70 6e 64 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65  nded to indicate
1fc80 20 61 0a 2a 2a 20 61 20 6c 6f 67 69 63 20 65 72   a.** a logic er
1fc90 72 6f 72 20 69 6e 20 74 68 65 20 61 70 70 6c 69  ror in the appli
1fca0 63 61 74 69 6f 6e 2e 20 20 46 75 74 75 72 65 20  cation.  Future 
1fcb0 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
1fcc0 74 65 20 6d 69 67 68 74 0a 2a 2a 20 70 61 6e 69  te might.** pani
1fcd0 63 20 72 61 74 68 65 72 20 74 68 61 6e 20 72 65  c rather than re
1fce0 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55  turn SQLITE_MISU
1fcf0 53 45 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  SE..**.** See al
1fd00 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  so: [sqlite3_bin
1fd10 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
1fd20 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  t()],.** [sqlite
1fd30 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
1fd40 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a  _name()], and.**
1fd50 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
1fd60 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
1fd70 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  ]..**.** INVARIA
1fd80 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35  NTS:.**.** {F135
1fd90 30 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  06} The [sqlite3
1fda0 5f 70 72 65 70 61 72 65 20 7c 20 53 51 4c 20 73  _prepare | SQL s
1fdb0 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65  tatement compile
1fdc0 72 5d 20 72 65 63 6f 67 6e 69 7a 65 73 0a 2a 2a  r] recognizes.**
1fdd0 20 20 20 20 20 20 20 20 20 20 74 6f 6b 65 6e 73            tokens
1fde0 20 6f 66 20 74 68 65 20 66 6f 72 6d 73 20 22 3f   of the forms "?
1fdf0 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 24 56 56 56  ", "?NNN", "$VVV
1fe00 22 2c 20 22 3a 56 56 56 22 2c 20 61 6e 64 20 22  ", ":VVV", and "
1fe10 40 56 56 56 22 0a 2a 2a 20 20 20 20 20 20 20 20  @VVV".**        
1fe20 20 20 61 73 20 53 51 4c 20 70 61 72 61 6d 65 74    as SQL paramet
1fe30 65 72 73 2c 20 77 68 65 72 65 20 4e 4e 4e 20 69  ers, where NNN i
1fe40 73 20 61 6e 79 20 73 65 71 75 65 6e 63 65 20 6f  s any sequence o
1fe50 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a  f one or more.**
1fe60 20 20 20 20 20 20 20 20 20 20 64 69 67 69 74 73            digits
1fe70 20 61 6e 64 20 77 68 65 72 65 20 56 56 56 20 69   and where VVV i
1fe80 73 20 61 6e 79 20 73 65 71 75 65 6e 63 65 20 6f  s any sequence o
1fe90 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 0a 2a  f one or more .*
1fea0 2a 20 20 20 20 20 20 20 20 20 20 61 6c 70 68 61  *          alpha
1feb0 6e 75 6d 65 72 69 63 20 63 68 61 72 61 63 74 65  numeric characte
1fec0 72 73 20 6f 72 20 22 3a 3a 22 20 6f 70 74 69 6f  rs or "::" optio
1fed0 6e 61 6c 6c 79 20 66 6f 6c 6c 6f 77 65 64 20 62  nally followed b
1fee0 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20  y.**          a 
1fef0 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e  string containin
1ff00 67 20 6e 6f 20 73 70 61 63 65 73 20 61 6e 64 20  g no spaces and 
1ff10 63 6f 6e 74 61 69 6e 65 64 20 77 69 74 68 69 6e  contained within
1ff20 20 70 61 72 65 6e 74 68 65 73 65 73 2e 0a 2a 2a   parentheses..**
1ff30 0a 2a 2a 20 7b 46 31 33 35 30 39 7d 20 54 68 65  .** {F13509} The
1ff40 20 69 6e 69 74 69 61 6c 20 76 61 6c 75 65 20 6f   initial value o
1ff50 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74  f an SQL paramet
1ff60 65 72 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  er is NULL..**.*
1ff70 2a 20 7b 46 31 33 35 31 32 7d 20 54 68 65 20 69  * {F13512} The i
1ff80 6e 64 65 78 20 6f 66 20 61 6e 20 22 3f 22 20 53  ndex of an "?" S
1ff90 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  QL parameter is 
1ffa0 6f 6e 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20  one larger than 
1ffb0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
1ffc0 6c 61 72 67 65 73 74 20 69 6e 64 65 78 20 6f 66  largest index of
1ffd0 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74   SQL parameter t
1ffe0 6f 20 74 68 65 20 6c 65 66 74 2c 20 6f 72 20 31  o the left, or 1
1fff0 20 69 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   if.**          
20000 74 68 65 20 22 3f 22 20 69 73 20 74 68 65 20 6c  the "?" is the l
20010 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61  eftmost SQL para
20020 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  meter..**.** {F1
20030 33 35 31 35 7d 20 54 68 65 20 69 6e 64 65 78 20  3515} The index 
20040 6f 66 20 61 6e 20 22 3f 4e 4e 4e 22 20 53 51 4c  of an "?NNN" SQL
20050 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
20060 65 20 69 6e 74 65 67 65 72 20 4e 4e 4e 2e 0a 2a  e integer NNN..*
20070 2a 0a 2a 2a 20 7b 46 31 33 35 31 38 7d 20 54 68  *.** {F13518} Th
20080 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 22 3a  e index of an ":
20090 56 56 56 22 2c 20 22 24 56 56 56 22 2c 20 6f 72  VVV", "$VVV", or
200a0 20 22 40 56 56 56 22 20 53 51 4c 20 70 61 72 61   "@VVV" SQL para
200b0 6d 65 74 65 72 20 69 73 0a 2a 2a 20 20 20 20 20  meter is.**     
200c0 20 20 20 20 20 74 68 65 20 73 61 6d 65 20 61 73       the same as
200d0 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 6c 65   the index of le
200e0 66 74 6d 6f 73 74 20 6f 63 63 75 72 72 65 6e 63  ftmost occurrenc
200f0 65 73 20 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a  es of the same.*
20100 2a 20 20 20 20 20 20 20 20 20 20 70 61 72 61 6d  *          param
20110 65 74 65 72 2c 20 6f 72 20 6f 6e 65 20 6d 6f 72  eter, or one mor
20120 65 20 74 68 61 6e 20 74 68 65 20 6c 61 72 67 65  e than the large
20130 73 74 20 69 6e 64 65 78 20 6f 76 65 72 20 61 6c  st index over al
20140 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 61  l.**          pa
20150 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20  rameters to the 
20160 6c 65 66 74 20 69 66 20 74 68 69 73 20 69 73 20  left if this is 
20170 74 68 65 20 66 69 72 73 74 20 6f 63 63 75 72 72  the first occurr
20180 65 6e 63 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  ence.**         
20190 20 6f 66 20 74 68 69 73 20 70 61 72 61 6d 65 74   of this paramet
201a0 65 72 2c 20 6f 72 20 31 20 69 66 20 74 68 69 73  er, or 1 if this
201b0 20 69 73 20 74 68 65 20 6c 65 66 74 6d 6f 73 74   is the leftmost
201c0 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
201d0 2a 20 7b 46 31 33 35 32 31 7d 20 54 68 65 20 5b  * {F13521} The [
201e0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20  sqlite3_prepare 
201f0 7c 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  | SQL statement 
20200 63 6f 6d 70 69 6c 65 72 5d 20 66 61 69 6c 20 77  compiler] fail w
20210 69 74 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ith.**          
20220 61 6e 20 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45  an [SQLITE_RANGE
20230 5d 20 65 72 72 6f 72 20 69 66 20 74 68 65 20 69  ] error if the i
20240 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70  ndex of an SQL p
20250 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20  arameter.**     
20260 20 20 20 20 20 69 73 20 6c 65 73 73 20 74 68 61       is less tha
20270 6e 20 31 20 6f 72 20 67 72 65 61 74 65 72 20 74  n 1 or greater t
20280 68 61 6e 20 53 51 4c 49 54 45 5f 4d 41 58 5f 56  han SQLITE_MAX_V
20290 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 2e 0a  ARIABLE_NUMBER..
202a0 2a 2a 0a 2a 2a 20 7b 46 31 33 35 32 34 7d 20 43  **.** {F13524} C
202b0 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
202c0 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 73 71 6c  _bind_text | sql
202d0 69 74 65 33 5f 62 69 6e 64 28 53 2c 4e 2c 56 2c  ite3_bind(S,N,V,
202e0 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  ...)].**        
202f0 20 20 61 73 73 6f 63 69 61 74 65 20 74 68 65 20    associate the 
20300 76 61 6c 75 65 20 56 20 77 69 74 68 20 61 6c 6c  value V with all
20310 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20   SQL parameters 
20320 68 61 76 69 6e 67 20 61 6e 0a 2a 2a 20 20 20 20  having an.**    
20330 20 20 20 20 20 20 69 6e 64 65 78 20 6f 66 20 4e        index of N
20340 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65   in the [prepare
20350 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a  d statement] S..
20360 2a 2a 0a 2a 2a 20 7b 46 31 33 35 32 37 7d 20 43  **.** {F13527} C
20370 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
20380 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 73 71 6c  _bind_text | sql
20390 69 74 65 33 5f 62 69 6e 64 28 53 2c 4e 2c 2e 2e  ite3_bind(S,N,..
203a0 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  .)].**          
203b0 6f 76 65 72 72 69 64 65 20 70 72 69 6f 72 20 63  override prior c
203c0 61 6c 6c 73 20 77 69 74 68 20 74 68 65 20 73 61  alls with the sa
203d0 6d 65 20 76 61 6c 75 65 73 20 6f 66 20 53 20 61  me values of S a
203e0 6e 64 20 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  nd N..**.** {F13
203f0 35 33 30 7d 20 42 69 6e 64 69 6e 67 73 20 65 73  530} Bindings es
20400 74 61 62 6c 69 73 68 65 64 20 62 79 20 5b 73 71  tablished by [sq
20410 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20  lite3_bind_text 
20420 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 53  | sqlite3_bind(S
20430 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ,...)].**       
20440 20 20 20 70 65 72 73 69 73 74 20 61 63 72 6f 73     persist acros
20450 73 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  s calls to [sqli
20460 74 65 33 5f 72 65 73 65 74 28 53 29 5d 2e 0a 2a  te3_reset(S)]..*
20470 2a 0a 2a 2a 20 7b 46 31 33 35 33 33 7d 20 49 6e  *.** {F13533} In
20480 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
20490 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e  e3_bind_blob(S,N
204a0 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20  ,V,L,D)],.**    
204b0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62        [sqlite3_b
204c0 69 6e 64 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c  ind_text(S,N,V,L
204d0 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20  ,D)], or.**     
204e0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69       [sqlite3_bi
204f0 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c  nd_text16(S,N,V,
20500 4c 2c 44 29 5d 20 53 51 4c 69 74 65 20 62 69 6e  L,D)] SQLite bin
20510 64 73 20 74 68 65 20 66 69 72 73 74 20 4c 0a 2a  ds the first L.*
20520 2a 20 20 20 20 20 20 20 20 20 20 62 79 74 65 73  *          bytes
20530 20 6f 66 20 74 68 65 20 62 6c 6f 62 20 6f 72 20   of the blob or 
20540 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 64 20 74  string pointed t
20550 6f 20 62 79 20 56 2c 20 77 68 65 6e 20 4c 0a 2a  o by V, when L.*
20560 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 6e 6f  *          is no
20570 6e 2d 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a  n-negative..**.*
20580 2a 20 7b 46 31 33 35 33 36 7d 20 49 6e 20 63 61  * {F13536} In ca
20590 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
205a0 62 69 6e 64 5f 74 65 78 74 28 53 2c 4e 2c 56 2c  bind_text(S,N,V,
205b0 4c 2c 44 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20  L,D)] or.**     
205c0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69       [sqlite3_bi
205d0 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c  nd_text16(S,N,V,
205e0 4c 2c 44 29 5d 20 53 51 4c 69 74 65 20 62 69 6e  L,D)] SQLite bin
205f0 64 73 20 63 68 61 72 61 63 74 65 72 73 0a 2a 2a  ds characters.**
20600 20 20 20 20 20 20 20 20 20 20 66 72 6f 6d 20 56            from V
20610 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72   through the fir
20620 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65  st zero characte
20630 72 20 77 68 65 6e 20 4c 20 69 73 20 6e 65 67 61  r when L is nega
20640 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  tive..**.** {F13
20650 35 33 39 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f  539} In calls to
20660 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
20670 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c  lob(S,N,V,L,D)],
20680 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
20690 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
206a0 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 20 6f 72 0a  S,N,V,L,D)], or.
206b0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
206c0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
206d0 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 77 68 65  (S,N,V,L,D)] whe
206e0 6e 20 44 20 69 73 20 74 68 65 20 73 70 65 63 69  n D is the speci
206f0 61 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63  al.**          c
20700 6f 6e 73 74 61 6e 74 20 5b 53 51 4c 49 54 45 5f  onstant [SQLITE_
20710 53 54 41 54 49 43 5d 2c 20 53 51 4c 69 74 65 20  STATIC], SQLite 
20720 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65  assumes that the
20730 20 76 61 6c 75 65 20 56 0a 2a 2a 20 20 20 20 20   value V.**     
20740 20 20 20 20 20 69 73 20 68 65 6c 64 20 69 6e 20       is held in 
20750 73 74 61 74 69 63 20 75 6e 6d 61 6e 61 67 65 64  static unmanaged
20760 20 73 70 61 63 65 20 74 68 61 74 20 77 69 6c 6c   space that will
20770 20 6e 6f 74 20 63 68 61 6e 67 65 0a 2a 2a 20 20   not change.**  
20780 20 20 20 20 20 20 20 20 64 75 72 69 6e 67 20 74          during t
20790 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 20 74  he lifetime of t
207a0 68 65 20 62 69 6e 64 69 6e 67 2e 0a 2a 2a 0a 2a  he binding..**.*
207b0 2a 20 7b 46 31 33 35 34 32 7d 20 49 6e 20 63 61  * {F13542} In ca
207c0 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
207d0 62 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56 2c  bind_blob(S,N,V,
207e0 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  L,D)],.**       
207f0 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64     [sqlite3_bind
20800 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29  _text(S,N,V,L,D)
20810 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  ], or.**        
20820 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f    [sqlite3_bind_
20830 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44  text16(S,N,V,L,D
20840 29 5d 20 77 68 65 6e 20 44 20 69 73 20 74 68 65  )] when D is the
20850 20 73 70 65 63 69 61 6c 0a 2a 2a 20 20 20 20 20   special.**     
20860 20 20 20 20 20 63 6f 6e 73 74 61 6e 74 20 5b 53       constant [S
20870 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d  QLITE_TRANSIENT]
20880 2c 20 74 68 65 20 72 6f 75 74 69 6e 65 20 6d 61  , the routine ma
20890 6b 65 73 20 61 20 0a 2a 2a 20 20 20 20 20 20 20  kes a .**       
208a0 20 20 20 70 72 69 76 61 74 65 20 63 6f 70 79 20     private copy 
208b0 6f 66 20 56 20 76 61 6c 75 65 20 62 65 66 6f 72  of V value befor
208c0 65 20 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  e it returns..**
208d0 0a 2a 2a 20 7b 46 31 33 35 34 35 7d 20 49 6e 20  .** {F13545} In 
208e0 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
208f0 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c  3_bind_blob(S,N,
20900 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20  V,L,D)],.**     
20910 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69       [sqlite3_bi
20920 6e 64 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c  nd_text(S,N,V,L,
20930 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20  D)], or.**      
20940 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e      [sqlite3_bin
20950 64 5f 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c  d_text16(S,N,V,L
20960 2c 44 29 5d 20 77 68 65 6e 20 44 20 69 73 20 61  ,D)] when D is a
20970 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 20   pointer to.**  
20980 20 20 20 20 20 20 20 20 61 20 66 75 6e 63 74 69          a functi
20990 6f 6e 2c 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b  on, SQLite invok
209a0 65 73 20 74 68 61 74 20 66 75 6e 63 74 69 6f 6e  es that function
209b0 20 74 6f 20 64 65 73 74 72 6f 79 20 74 68 65 0a   to destroy the.
209c0 2a 2a 20 20 20 20 20 20 20 20 20 20 56 20 76 61  **          V va
209d0 6c 75 65 20 61 66 74 65 72 20 69 74 20 68 61 73  lue after it has
209e0 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20   finished using 
209f0 74 68 65 20 56 20 76 61 6c 75 65 2e 0a 2a 2a 0a  the V value..**.
20a00 2a 2a 20 7b 46 31 33 35 34 38 7d 20 49 6e 20 63  ** {F13548} In c
20a10 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
20a20 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 53  _bind_zeroblob(S
20a30 2c 4e 2c 56 2c 4c 29 5d 20 74 68 65 20 76 61 6c  ,N,V,L)] the val
20a40 75 65 20 62 6f 75 6e 64 0a 2a 2a 20 20 20 20 20  ue bound.**     
20a50 20 20 20 20 20 69 73 20 61 20 62 6c 6f 62 20 6f       is a blob o
20a60 66 20 4c 20 62 79 74 65 73 2c 20 6f 72 20 61 20  f L bytes, or a 
20a70 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 62 6c 6f 62  zero-length blob
20a80 20 69 66 20 4c 20 69 73 20 6e 65 67 61 74 69 76   if L is negativ
20a90 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 35 31  e..**.** {F13551
20aa0 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73  } In calls to [s
20ab0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75  qlite3_bind_valu
20ac0 65 28 53 2c 4e 2c 56 29 5d 20 74 68 65 20 56 20  e(S,N,V)] the V 
20ad0 61 72 67 75 6d 65 6e 74 20 6d 61 79 0a 2a 2a 20  argument may.** 
20ae0 20 20 20 20 20 20 20 20 20 62 65 20 65 69 74 68           be eith
20af0 65 72 20 61 20 5b 70 72 6f 74 65 63 74 65 64 20  er a [protected 
20b00 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
20b10 62 6a 65 63 74 20 6f 72 20 61 6e 0a 2a 2a 20 20  bject or an.**  
20b20 20 20 20 20 20 20 20 20 5b 75 6e 70 72 6f 74 65          [unprote
20b30 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
20b40 75 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 69  ue] object..*/.i
20b50 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
20b60 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d  blob(sqlite3_stm
20b70 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76  t*, int, const v
20b80 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69  oid*, int n, voi
20b90 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e  d(*)(void*));.in
20ba0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64  t sqlite3_bind_d
20bb0 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74  ouble(sqlite3_st
20bc0 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65  mt*, int, double
20bd0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
20be0 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  ind_int(sqlite3_
20bf0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29  stmt*, int, int)
20c00 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
20c10 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33  nd_int64(sqlite3
20c20 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c  _stmt*, int, sql
20c30 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74  ite3_int64);.int
20c40 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75   sqlite3_bind_nu
20c50 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ll(sqlite3_stmt*
20c60 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69  , int);.int sqli
20c70 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71  te3_bind_text(sq
20c80 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
20c90 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69  , const char*, i
20ca0 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f  nt n, void(*)(vo
20cb0 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74  id*));.int sqlit
20cc0 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 73  e3_bind_text16(s
20cd0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
20ce0 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  t, const void*, 
20cf0 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
20d00 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  d*));.int sqlite
20d10 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c  3_bind_value(sql
20d20 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
20d30 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76   const sqlite3_v
20d40 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
20d50 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f  te3_bind_zeroblo
20d60 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  b(sqlite3_stmt*,
20d70 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f   int, int n);../
20d80 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
20d90 75 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72  umber Of SQL Par
20da0 61 6d 65 74 65 72 73 20 7b 46 31 33 36 30 30 7d  ameters {F13600}
20db0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
20dc0 69 6e 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ine can be used 
20dd0 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62  to find the numb
20de0 65 72 20 6f 66 20 53 51 4c 20 70 61 72 61 6d 65  er of SQL parame
20df0 74 65 72 73 0a 2a 2a 20 69 6e 20 61 20 70 72 65  ters.** in a pre
20e00 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 2e  pared statement.
20e10 20 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73    SQL parameters
20e20 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74   are tokens of t
20e30 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20  he.** form "?", 
20e40 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20  "?NNN", ":AAA", 
20e50 22 24 41 41 41 22 2c 20 6f 72 20 22 40 41 41 41  "$AAA", or "@AAA
20e60 22 20 74 68 61 74 20 73 65 72 76 65 20 61 73 0a  " that serve as.
20e70 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20  ** placeholders 
20e80 66 6f 72 20 76 61 6c 75 65 73 20 74 68 61 74 20  for values that 
20e90 61 72 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  are [sqlite3_bin
20ea0 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a  d_blob | bound].
20eb0 2a 2a 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65  ** to the parame
20ec0 74 65 72 73 20 61 74 20 61 20 6c 61 74 65 72 20  ters at a later 
20ed0 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  time..**.** This
20ee0 20 72 6f 75 74 69 6e 65 20 61 63 74 75 61 6c 6c   routine actuall
20ef0 79 20 72 65 74 75 72 6e 73 20 74 68 65 20 69 6e  y returns the in
20f00 64 65 78 20 6f 66 20 74 68 65 20 6c 61 72 67 65  dex of the large
20f10 73 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  st parameter..**
20f20 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65   For all forms e
20f30 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73  xcept ?NNN, this
20f40 20 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64   will correspond
20f50 20 74 6f 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   to the number o
20f60 66 0a 2a 2a 20 75 6e 69 71 75 65 20 70 61 72 61  f.** unique para
20f70 6d 65 74 65 72 73 2e 20 20 49 66 20 70 61 72 61  meters.  If para
20f80 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 3f 4e  meters of the ?N
20f90 4e 4e 20 61 72 65 20 75 73 65 64 2c 20 74 68 65  NN are used, the
20fa0 72 65 20 6d 61 79 0a 2a 2a 20 62 65 20 67 61 70  re may.** be gap
20fb0 73 20 69 6e 20 74 68 65 20 6c 69 73 74 2e 0a 2a  s in the list..*
20fc0 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
20fd0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
20fe0 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
20ff0 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
21000 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
21010 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  me()], and.** [s
21020 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
21030 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
21040 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
21050 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 36 30 31 7d  :.**.** {F13601}
21060 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   The [sqlite3_bi
21070 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
21080 6e 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65  nt(S)] interface
21090 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20   returns.**     
210a0 20 20 20 20 20 74 68 65 20 6c 61 72 67 65 73 74       the largest
210b0 20 69 6e 64 65 78 20 6f 66 20 61 6c 6c 20 53 51   index of all SQ
210c0 4c 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20  L parameters in 
210d0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
210e0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
210f0 65 6e 74 5d 20 53 2c 20 6f 72 20 30 20 69 66 20  ent] S, or 0 if 
21100 53 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f  S.**          co
21110 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 70 61  ntains no SQL pa
21120 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 69 6e 74  rameters..*/.int
21130 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61   sqlite3_bind_pa
21140 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73 71  rameter_count(sq
21150 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
21160 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
21170 61 6d 65 20 4f 66 20 41 20 48 6f 73 74 20 50 61  ame Of A Host Pa
21180 72 61 6d 65 74 65 72 20 7b 46 31 33 36 32 30 7d  rameter {F13620}
21190 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
211a0 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ine returns a po
211b0 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6e 61 6d  inter to the nam
211c0 65 20 6f 66 20 74 68 65 20 6e 2d 74 68 0a 2a 2a  e of the n-th.**
211d0 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69   SQL parameter i
211e0 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  n a [prepared st
211f0 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 53 51 4c  atement]..** SQL
21200 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74   parameters of t
21210 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f  he form "?NNN" o
21220 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41  r ":AAA" or "@AA
21230 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20  A" or "$AAA".** 
21240 68 61 76 65 20 61 20 6e 61 6d 65 20 77 68 69 63  have a name whic
21250 68 20 69 73 20 74 68 65 20 73 74 72 69 6e 67 20  h is the string 
21260 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22  "?NNN" or ":AAA"
21270 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24   or "@AAA" or "$
21280 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 74 69  AAA".** respecti
21290 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65  vely..** In othe
212a0 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e 69  r words, the ini
212b0 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 20  tial ":" or "$" 
212c0 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a  or "@" or "?".**
212d0 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73 20   is included as 
212e0 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d 65  part of the name
212f0 2e 0a 2a 2a 20 50 61 72 61 6d 65 74 65 72 73 20  ..** Parameters 
21300 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 20  of the form "?" 
21310 77 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77  without a follow
21320 69 6e 67 20 69 6e 74 65 67 65 72 20 68 61 76 65  ing integer have
21330 20 6e 6f 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20   no name..**.** 
21340 54 68 65 20 66 69 72 73 74 20 68 6f 73 74 20 70  The first host p
21350 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20  arameter has an 
21360 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20  index of 1, not 
21370 30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  0..**.** If the 
21380 76 61 6c 75 65 20 6e 20 69 73 20 6f 75 74 20 6f  value n is out o
21390 66 20 72 61 6e 67 65 20 6f 72 20 69 66 20 74 68  f range or if th
213a0 65 20 6e 2d 74 68 20 70 61 72 61 6d 65 74 65 72  e n-th parameter
213b0 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c   is.** nameless,
213c0 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65   then NULL is re
213d0 74 75 72 6e 65 64 2e 20 20 54 68 65 20 72 65 74  turned.  The ret
213e0 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a  urned string is.
213f0 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 74 68 65  ** always in the
21400 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20   UTF-8 encoding 
21410 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61 6d 65  even if the name
21420 64 20 70 61 72 61 6d 65 74 65 72 20 77 61 73 0a  d parameter was.
21430 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70  ** originally sp
21440 65 63 69 66 69 65 64 20 61 73 20 55 54 46 2d 31  ecified as UTF-1
21450 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72  6 in [sqlite3_pr
21460 65 70 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a 2a  epare16()] or.**
21470 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
21480 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a  e16_v2()]..**.**
21490 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
214a0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
214b0 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a  lite3_bind()],.*
214c0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
214d0 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
214e0 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
214f0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
21500 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a  er_index()]..**.
21510 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
21520 2a 0a 2a 2a 20 7b 46 31 33 36 32 31 7d 20 54 68  *.** {F13621} Th
21530 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
21540 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 53  parameter_name(S
21550 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  ,N)] interface r
21560 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20  eturns.**       
21570 20 20 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65     a UTF-8 rende
21580 72 69 6e 67 20 6f 66 20 74 68 65 20 6e 61 6d 65  ring of the name
21590 20 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72 61   of the SQL para
215a0 6d 65 74 65 72 20 69 6e 0a 2a 2a 20 20 20 20 20  meter in.**     
215b0 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73       [prepared s
215c0 74 61 74 65 6d 65 6e 74 5d 20 53 20 68 61 76 69  tatement] S havi
215d0 6e 67 20 69 6e 64 65 78 20 4e 2c 20 6f 72 0a 2a  ng index N, or.*
215e0 2a 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20  *          NULL 
215f0 69 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 53  if there is no S
21600 51 4c 20 70 61 72 61 6d 65 74 65 72 20 77 69 74  QL parameter wit
21610 68 20 69 6e 64 65 78 20 4e 20 6f 72 20 69 66 20  h index N or if 
21620 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
21630 70 61 72 61 6d 65 74 65 72 20 77 69 74 68 20 69  parameter with i
21640 6e 64 65 78 20 4e 20 69 73 20 61 6e 20 61 6e 6f  ndex N is an ano
21650 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 72  nymous parameter
21660 20 22 3f 22 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63   "?"..*/.const c
21670 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e  har *sqlite3_bin
21680 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
21690 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
216a0 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
216b0 49 33 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 20  I3REF: Index Of 
216c0 41 20 50 61 72 61 6d 65 74 65 72 20 57 69 74 68  A Parameter With
216d0 20 41 20 47 69 76 65 6e 20 4e 61 6d 65 20 7b 46   A Given Name {F
216e0 31 33 36 34 30 7d 0a 2a 2a 0a 2a 2a 20 52 65 74  13640}.**.** Ret
216f0 75 72 6e 20 74 68 65 20 69 6e 64 65 78 20 6f 66  urn the index of
21700 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65   an SQL paramete
21710 72 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65  r given its name
21720 2e 20 20 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20  .  The.** index 
21730 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69  value returned i
21740 73 20 73 75 69 74 61 62 6c 65 20 66 6f 72 20 75  s suitable for u
21750 73 65 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  se as the second
21760 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f  .** parameter to
21770 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
21780 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
21790 28 29 5d 2e 20 20 41 20 7a 65 72 6f 0a 2a 2a 20  ()].  A zero.** 
217a0 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6e  is returned if n
217b0 6f 20 6d 61 74 63 68 69 6e 67 20 70 61 72 61 6d  o matching param
217c0 65 74 65 72 20 69 73 20 66 6f 75 6e 64 2e 20 20  eter is found.  
217d0 54 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  The parameter.**
217e0 20 6e 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69   name must be gi
217f0 76 65 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65  ven in UTF-8 eve
21800 6e 20 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61  n if the origina
21810 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77  l statement.** w
21820 61 73 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d  as prepared from
21830 20 55 54 46 2d 31 36 20 74 65 78 74 20 75 73 69   UTF-16 text usi
21840 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ng [sqlite3_prep
21850 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a  are16_v2()]..**.
21860 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
21870 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
21880 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c  sqlite3_bind()],
21890 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
218a0 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
218b0 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  t()], and.** [sq
218c0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
218d0 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a  eter_index()]..*
218e0 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
218f0 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 36 34 31 7d 20  .**.** {F13641} 
21900 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  The [sqlite3_bin
21910 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
21920 78 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63  x(S,N)] interfac
21930 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20  e returns.**    
21940 20 20 20 20 20 20 74 68 65 20 69 6e 64 65 78 20        the index 
21950 6f 66 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  of SQL parameter
21960 20 69 6e 20 5b 70 72 65 70 61 72 65 64 20 73 74   in [prepared st
21970 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 20 20 20 20  atement].**     
21980 20 20 20 20 20 53 20 77 68 6f 73 65 20 6e 61 6d       S whose nam
21990 65 20 6d 61 74 63 68 65 73 20 74 68 65 20 55 54  e matches the UT
219a0 46 2d 38 20 73 74 72 69 6e 67 20 4e 2c 20 6f 72  F-8 string N, or
219b0 20 30 20 69 66 20 74 68 65 72 65 20 69 73 0a 2a   0 if there is.*
219c0 2a 20 20 20 20 20 20 20 20 20 20 6e 6f 20 6d 61  *          no ma
219d0 74 63 68 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  tch..*/.int sqli
219e0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
219f0 65 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 33  er_index(sqlite3
21a00 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68  _stmt*, const ch
21a10 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a  ar *zName);../*.
21a20 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73  ** CAPI3REF: Res
21a30 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20  et All Bindings 
21a40 4f 6e 20 41 20 50 72 65 70 61 72 65 64 20 53 74  On A Prepared St
21a50 61 74 65 6d 65 6e 74 20 7b 46 31 33 36 36 30 7d  atement {F13660}
21a60 0a 2a 2a 0a 2a 2a 20 43 6f 6e 74 72 61 72 79 20  .**.** Contrary 
21a70 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e  to the intuition
21a80 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74   of many, [sqlit
21a90 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73  e3_reset()] does
21aa0 20 6e 6f 74 0a 2a 2a 20 72 65 73 65 74 20 74 68   not.** reset th
21ab0 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
21ac0 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d  blob | bindings]
21ad0 20 6f 6e 20 61 20 0a 2a 2a 20 5b 70 72 65 70 61   on a .** [prepa
21ae0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20  red statement]. 
21af0 20 55 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e   Use this routin
21b00 65 20 74 6f 0a 2a 2a 20 72 65 73 65 74 20 61 6c  e to.** reset al
21b10 6c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  l host parameter
21b20 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  s to NULL..**.**
21b30 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
21b40 2a 2a 20 7b 46 31 33 36 36 31 7d 20 54 68 65 20  ** {F13661} The 
21b50 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62  [sqlite3_clear_b
21b60 69 6e 64 69 6e 67 73 28 53 29 5d 20 69 6e 74 65  indings(S)] inte
21b70 72 66 61 63 65 20 72 65 73 65 74 73 20 61 6c 6c  rface resets all
21b80 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53 51 4c  .**          SQL
21b90 20 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69   parameter bindi
21ba0 6e 67 73 20 69 6e 20 5b 70 72 65 70 61 72 65 64  ngs in [prepared
21bb0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a   statement] S.**
21bc0 20 20 20 20 20 20 20 20 20 20 62 61 63 6b 20 74            back t
21bd0 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73  o NULL..*/.int s
21be0 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e  qlite3_clear_bin
21bf0 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74  dings(sqlite3_st
21c00 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
21c10 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66  I3REF: Number Of
21c20 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65   Columns In A Re
21c30 73 75 6c 74 20 53 65 74 20 7b 46 31 33 37 31 30  sult Set {F13710
21c40 7d 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 74  }.**.** Return t
21c50 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
21c60 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75  umns in the resu
21c70 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65 64 20  lt set returned 
21c80 62 79 20 74 68 65 20 0a 2a 2a 20 5b 70 72 65 70  by the .** [prep
21c90 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
21ca0 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   This routine re
21cb0 74 75 72 6e 73 20 30 0a 2a 2a 20 69 66 20 70 53  turns 0.** if pS
21cc0 74 6d 74 20 69 73 20 61 6e 20 53 51 4c 20 73 74  tmt is an SQL st
21cd0 61 74 65 6d 65 6e 74 20 74 68 61 74 20 64 6f 65  atement that doe
21ce0 73 20 6e 6f 74 20 72 65 74 75 72 6e 20 64 61 74  s not return dat
21cf0 61 20 28 66 6f 72 20 0a 2a 2a 20 65 78 61 6d 70  a (for .** examp
21d00 6c 65 20 61 6e 20 55 50 44 41 54 45 29 2e 0a 2a  le an UPDATE)..*
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 37 31 31 7d 20  .**.** {F13711} 
21d30 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  The [sqlite3_col
21d40 75 6d 6e 5f 63 6f 75 6e 74 28 53 29 5d 20 69 6e  umn_count(S)] in
21d50 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
21d60 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
21d70 20 20 20 20 20 20 20 20 20 20 63 6f 6c 75 6d 6e            column
21d80 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20  s in the result 
21d90 73 65 74 20 67 65 6e 65 72 61 74 65 64 20 62 79  set generated by
21da0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
21db0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
21dc0 6d 65 6e 74 5d 20 53 2c 20 6f 72 20 30 20 69 66  ment] S, or 0 if
21dd0 20 53 20 64 6f 65 73 20 6e 6f 74 20 67 65 6e 65   S does not gene
21de0 72 61 74 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  rate.**         
21df0 20 61 20 72 65 73 75 6c 74 20 73 65 74 2e 0a 2a   a result set..*
21e00 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  /.int sqlite3_co
21e10 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74  lumn_count(sqlit
21e20 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
21e30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
21e40 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49  : Column Names I
21e50 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 20 7b  n A Result Set {
21e60 46 31 33 37 32 30 7d 0a 2a 2a 0a 2a 2a 20 54 68  F13720}.**.** Th
21e70 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
21e80 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 61 73 73  urn the name ass
21e90 69 67 6e 65 64 20 74 6f 20 61 20 70 61 72 74 69  igned to a parti
21ea0 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  cular column.** 
21eb0 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  in the result se
21ec0 74 20 6f 66 20 61 20 53 45 4c 45 43 54 20 73 74  t of a SELECT st
21ed0 61 74 65 6d 65 6e 74 2e 20 20 54 68 65 20 73 71  atement.  The sq
21ee0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
21ef0 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  e().** interface
21f00 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
21f10 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72  er to a zero-ter
21f20 6d 69 6e 61 74 65 64 20 55 54 46 38 20 73 74 72  minated UTF8 str
21f30 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74  ing.** and sqlit
21f40 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36  e3_column_name16
21f50 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  () returns a poi
21f60 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74  nter to a zero-t
21f70 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46  erminated.** UTF
21f80 31 36 20 73 74 72 69 6e 67 2e 20 20 54 68 65 20  16 string.  The 
21f90 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
21fa0 69 73 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  is the.** [prepa
21fb0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
21fc0 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74  hat implements t
21fd0 68 65 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d  he SELECT statem
21fe0 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f  ent..** The seco
21ff0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
22000 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65  the column numbe
22010 72 2e 20 20 54 68 65 20 6c 65 66 74 2d 6d 6f 73  r.  The left-mos
22020 74 20 63 6f 6c 75 6d 6e 20 69 73 0a 2a 2a 20 6e  t column is.** n
22030 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 54  umber 0..**.** T
22040 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
22050 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 20 76 61  ng pointer is va
22060 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 68 65 72  lid until either
22070 20 74 68 65 20 0a 2a 2a 20 5b 70 72 65 70 61 72   the .** [prepar
22080 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73  ed statement] is
22090 20 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73   destroyed by [s
220a0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
220b0 29 5d 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74  )].** or until t
220c0 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 73 71 6c  he next call sql
220d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
220e0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f  () or sqlite3_co
220f0 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 0a 2a 2a  lumn_name16().**
22100 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c   on the same col
22110 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 73 71  umn..**.** If sq
22120 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66  lite3_malloc() f
22130 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20  ails during the 
22140 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69  processing of ei
22150 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20  ther routine.** 
22160 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72  (for example dur
22170 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e  ing a conversion
22180 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55   from UTF-8 to U
22190 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a  TF-16) then a.**
221a0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73   NULL pointer is
221b0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
221c0 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72   The name of a r
221d0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20  esult column is 
221e0 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  the value of the
221f0 20 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72   "AS" clause for
22200 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c  .** that column,
22210 20 69 66 20 74 68 65 72 65 20 69 73 20 61 6e 20   if there is an 
22220 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74  AS clause.  If t
22230 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c  here is no AS cl
22240 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ause.** then the
22250 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c   name of the col
22260 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69  umn is unspecifi
22270 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67  ed and may chang
22280 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65  e from.** one re
22290 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20  lease of SQLite 
222a0 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2a 0a  to the next..**.
222b0 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
222c0 2a 0a 2a 2a 20 7b 46 31 33 37 32 31 7d 20 41 20  *.** {F13721} A 
222d0 73 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63  successful invoc
222e0 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71  ation of the [sq
222f0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
22300 65 28 53 2c 4e 29 5d 0a 2a 2a 20 20 20 20 20 20  e(S,N)].**      
22310 20 20 20 20 69 6e 74 65 72 66 61 63 65 20 72 65      interface re
22320 74 75 72 6e 73 20 74 68 65 20 6e 61 6d 65 0a 2a  turns the name.*
22330 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 74 68  *          of th
22340 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 28 77 68  e Nth column (wh
22350 65 72 65 20 30 20 69 73 20 74 68 65 20 6c 65 66  ere 0 is the lef
22360 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 29 20 66  t-most column) f
22370 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  or the.**       
22380 20 20 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66     result set of
22390 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
223a0 6d 65 6e 74 5d 20 53 20 61 73 20 61 0a 2a 2a 20  ment] S as a.** 
223b0 20 20 20 20 20 20 20 20 20 7a 65 72 6f 2d 74 65           zero-te
223c0 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73  rminated UTF-8 s
223d0 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  tring..**.** {F1
223e0 33 37 32 33 7d 20 41 20 73 75 63 63 65 73 73 66  3723} A successf
223f0 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  ul invocation of
22400 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
22410 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e 29  lumn_name16(S,N)
22420 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  ].**          in
22430 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
22440 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 20 20 20 20  the name.**     
22450 20 20 20 20 20 6f 66 20 74 68 65 20 4e 74 68 20       of the Nth 
22460 63 6f 6c 75 6d 6e 20 28 77 68 65 72 65 20 30 20  column (where 0 
22470 69 73 20 74 68 65 20 6c 65 66 74 2d 6d 6f 73 74  is the left-most
22480 20 63 6f 6c 75 6d 6e 29 20 66 6f 72 20 74 68 65   column) for the
22490 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 73  .**          res
224a0 75 6c 74 20 73 65 74 20 6f 66 20 5b 70 72 65 70  ult set of [prep
224b0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
224c0 53 20 61 73 20 61 0a 2a 2a 20 20 20 20 20 20 20  S as a.**       
224d0 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74     zero-terminat
224e0 65 64 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  ed UTF-16 string
224f0 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
22500 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a  yte order..**.**
22510 20 7b 46 31 33 37 32 34 7d 20 54 68 65 20 5b 73   {F13724} The [s
22520 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
22530 6d 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  me()] and [sqlit
22540 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36  e3_column_name16
22550 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ()].**          
22560 69 6e 74 65 72 66 61 63 65 73 20 72 65 74 75 72  interfaces retur
22570 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  n a NULL pointer
22580 20 69 66 20 74 68 65 79 20 61 72 65 20 75 6e 61   if they are una
22590 62 6c 65 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20  ble to.**       
225a0 20 20 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f     allocate memo
225b0 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 69 72  ry to hold their
225c0 20 6e 6f 72 6d 61 6c 20 72 65 74 75 72 6e 20 73   normal return s
225d0 74 72 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46  trings..**.** {F
225e0 31 33 37 32 35 7d 20 49 66 20 74 68 65 20 4e 20  13725} If the N 
225f0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
22600 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
22610 65 28 53 2c 4e 29 5d 20 6f 72 0a 2a 2a 20 20 20  e(S,N)] or.**   
22620 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
22630 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 53 2c  column_name16(S,
22640 4e 29 5d 20 69 73 20 6f 75 74 20 6f 66 20 72 61  N)] is out of ra
22650 6e 67 65 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a  nge, then the.**
22660 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 66            interf
22670 61 63 65 73 20 72 65 74 75 72 6e 20 61 20 4e 55  aces return a NU
22680 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 0a  LL pointer..** .
22690 2a 2a 20 7b 46 31 33 37 32 36 7d 20 54 68 65 20  ** {F13726} The 
226a0 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64  strings returned
226b0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   by [sqlite3_col
226c0 75 6d 6e 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 61  umn_name(S,N)] a
226d0 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  nd.**          [
226e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
226f0 61 6d 65 31 36 28 53 2c 4e 29 5d 20 61 72 65 20  ame16(S,N)] are 
22700 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20  valid until the 
22710 6e 65 78 74 0a 2a 2a 20 20 20 20 20 20 20 20 20  next.**         
22720 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72 20   call to either 
22730 72 6f 75 74 69 6e 65 20 77 69 74 68 20 74 68 65  routine with the
22740 20 73 61 6d 65 20 53 20 61 6e 64 20 4e 20 70 61   same S and N pa
22750 72 61 6d 65 74 65 72 73 0a 2a 2a 20 20 20 20 20  rameters.**     
22760 20 20 20 20 20 6f 72 20 75 6e 74 69 6c 20 5b 73       or until [s
22770 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
22780 53 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 0a 2a  S)] is called..*
22790 2a 0a 2a 2a 20 7b 46 31 33 37 32 37 7d 20 57 68  *.** {F13727} Wh
227a0 65 6e 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75  en a result colu
227b0 6d 6e 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d  mn of a [SELECT]
227c0 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6e 74 61   statement conta
227d0 69 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ins.**          
227e0 61 6e 20 41 53 20 63 6c 61 75 73 65 2c 20 74 68  an AS clause, th
227f0 65 20 6e 61 6d 65 20 6f 66 20 74 68 61 74 20 63  e name of that c
22800 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20 69 64 65  olumn is the ide
22810 6e 74 69 66 69 65 72 0a 2a 2a 20 20 20 20 20 20  ntifier.**      
22820 20 20 20 20 74 6f 20 74 68 65 20 72 69 67 68 74      to the right
22830 20 6f 66 20 74 68 65 20 41 53 20 6b 65 79 77 6f   of the AS keywo
22840 72 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  rd..*/.const cha
22850 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
22860 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  n_name(sqlite3_s
22870 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f  tmt*, int N);.co
22880 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
22890 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
228a0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
228b0 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt N);../*.** CA
228c0 50 49 33 52 45 46 3a 20 53 6f 75 72 63 65 20 4f  PI3REF: Source O
228d0 66 20 44 61 74 61 20 49 6e 20 41 20 51 75 65 72  f Data In A Quer
228e0 79 20 52 65 73 75 6c 74 20 7b 46 31 33 37 34 30  y Result {F13740
228f0 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  }.**.** These ro
22900 75 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61  utines provide a
22910 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d   means to determ
22920 69 6e 65 20 77 68 61 74 20 63 6f 6c 75 6d 6e 20  ine what column 
22930 6f 66 20 77 68 61 74 0a 2a 2a 20 74 61 62 6c 65  of what.** table
22940 20 69 6e 20 77 68 69 63 68 20 64 61 74 61 62 61   in which databa
22950 73 65 20 61 20 72 65 73 75 6c 74 20 6f 66 20 61  se a result of a
22960 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e   SELECT statemen
22970 74 20 63 6f 6d 65 73 20 66 72 6f 6d 2e 0a 2a 2a  t comes from..**
22980 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   The name of the
22990 20 64 61 74 61 62 61 73 65 20 6f 72 20 74 61 62   database or tab
229a0 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e  le or column can
229b0 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a   be returned as.
229c0 2a 2a 20 65 69 74 68 65 72 20 61 20 55 54 46 38  ** either a UTF8
229d0 20 6f 72 20 55 54 46 31 36 20 73 74 72 69 6e 67   or UTF16 string
229e0 2e 20 20 54 68 65 20 5f 64 61 74 61 62 61 73 65  .  The _database
229f0 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  _ routines retur
22a00 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  n.** the databas
22a10 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61 62  e name, the _tab
22a20 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74  le_ routines ret
22a30 75 72 6e 20 74 68 65 20 74 61 62 6c 65 20 6e 61  urn the table na
22a40 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f  me, and.** the o
22a50 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20  rigin_ routines 
22a60 72 65 74 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d  return the colum
22a70 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 54 68 65 20 72  n name..** The r
22a80 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69  eturned string i
22a90 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 0a 2a 2a  s valid until.**
22aa0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
22ab0 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 73  tatement] is des
22ac0 74 72 6f 79 65 64 20 75 73 69 6e 67 0a 2a 2a 20  troyed using.** 
22ad0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
22ae0 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68  e()] or until th
22af0 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69  e same informati
22b00 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 0a  on is requested.
22b10 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69  ** again in a di
22b20 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67  fferent encoding
22b30 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65  ..**.** The name
22b40 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 74  s returned are t
22b50 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61  he original un-a
22b60 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20  liased names of 
22b70 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c  the.** database,
22b80 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75   table, and colu
22b90 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  mn..**.** The fi
22ba0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
22bb0 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61  the following ca
22bc0 6c 6c 73 20 69 73 20 61 20 5b 70 72 65 70 61 72  lls is a [prepar
22bd0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
22be0 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  * These function
22bf0 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61  s return informa
22c00 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e  tion about the N
22c10 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e  th column return
22c20 65 64 20 62 79 20 0a 2a 2a 20 74 68 65 20 73 74  ed by .** the st
22c30 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e  atement, where N
22c40 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66   is the second f
22c50 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74  unction argument
22c60 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 4e  ..**.** If the N
22c70 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e  th column return
22c80 65 64 20 62 79 20 74 68 65 20 73 74 61 74 65 6d  ed by the statem
22c90 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65 73  ent is an expres
22ca0 73 69 6f 6e 0a 2a 2a 20 6f 72 20 73 75 62 71 75  sion.** or subqu
22cb0 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61  ery and is not a
22cc0 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74   column value, t
22cd0 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65  hen all of these
22ce0 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 72 65   functions.** re
22cf0 74 75 72 6e 20 4e 55 4c 4c 2e 20 20 54 68 65 73  turn NULL.  Thes
22d00 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 20  e routine might 
22d10 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c  also return NULL
22d20 20 69 66 20 61 20 6d 65 6d 6f 72 79 0a 2a 2a 20   if a memory.** 
22d30 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72  allocation error
22d40 20 6f 63 63 75 72 73 2e 20 20 4f 74 68 65 72 77   occurs.  Otherw
22d50 69 73 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e  ise, they return
22d60 20 74 68 65 20 0a 2a 2a 20 6e 61 6d 65 20 6f 66   the .** name of
22d70 20 74 68 65 20 61 74 74 61 63 68 65 64 20 64 61   the attached da
22d80 74 61 62 61 73 65 2c 20 74 61 62 6c 65 20 61 6e  tabase, table an
22d90 64 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75  d column that qu
22da0 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f  ery result.** co
22db0 6c 75 6d 6e 20 77 61 73 20 65 78 74 72 61 63 74  lumn was extract
22dc0 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 41  ed from..**.** A
22dd0 73 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72  s with all other
22de0 20 53 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68   SQLite APIs, th
22df0 6f 73 65 20 70 6f 73 74 66 69 78 65 64 20 77 69  ose postfixed wi
22e00 74 68 20 22 31 36 22 20 72 65 74 75 72 6e 0a 2a  th "16" return.*
22e10 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64  * UTF-16 encoded
22e20 20 73 74 72 69 6e 67 73 2c 20 74 68 65 20 6f 74   strings, the ot
22e30 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 65  her functions re
22e40 74 75 72 6e 20 55 54 46 2d 38 2e 20 7b 45 4e 44  turn UTF-8. {END
22e50 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 41 50  }.**.** These AP
22e60 49 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 69  Is are only avai
22e70 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62  lable if the lib
22e80 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65  rary was compile
22e90 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 53  d with the .** S
22ea0 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c  QLITE_ENABLE_COL
22eb0 55 4d 4e 5f 4d 45 54 41 44 41 54 41 20 70 72 65  UMN_METADATA pre
22ec0 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c  processor symbol
22ed0 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20   defined..**.** 
22ee0 7b 55 31 33 37 35 31 7d 0a 2a 2a 20 49 66 20 74  {U13751}.** If t
22ef0 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61  wo or more threa
22f00 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d  ds call one or m
22f10 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75  ore of these rou
22f20 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68  tines against th
22f30 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72  e same.** prepar
22f40 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64  ed statement and
22f50 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73   column at the s
22f60 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68  ame time then th
22f70 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a  e results are.**
22f80 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
22f90 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
22fa0 0a 2a 2a 20 7b 46 31 33 37 34 31 7d 20 54 68 65  .** {F13741} The
22fb0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
22fc0 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 53  _database_name(S
22fd0 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  ,N)] interface r
22fe0 65 74 75 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a  eturns either.**
22ff0 20 20 20 20 20 20 20 20 20 20 74 68 65 20 55 54            the UT
23000 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  F-8 zero-termina
23010 74 65 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  ted name of the 
23020 64 61 74 61 62 61 73 65 20 66 72 6f 6d 20 77 68  database from wh
23030 69 63 68 20 74 68 65 20 0a 2a 2a 20 20 20 20 20  ich the .**     
23040 20 20 20 20 20 4e 74 68 20 72 65 73 75 6c 74 20       Nth result 
23050 63 6f 6c 75 6d 6e 20 6f 66 20 5b 70 72 65 70 61  column of [prepa
23060 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
23070 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73   .**          is
23080 20 65 78 74 72 61 63 74 65 64 2c 20 6f 72 20 4e   extracted, or N
23090 55 4c 4c 20 69 66 20 74 68 65 20 4e 74 68 20 63  ULL if the Nth c
230a0 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20 61 0a  olumn of S is a.
230b0 2a 2a 20 20 20 20 20 20 20 20 20 20 67 65 6e 65  **          gene
230c0 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e 20 6f  ral expression o
230d0 72 20 69 66 20 75 6e 61 62 6c 65 20 74 6f 20 61  r if unable to a
230e0 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 0a 2a  llocate memory.*
230f0 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 73 74  *          to st
23100 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a  ore the name..**
23110 20 20 20 20 20 20 20 20 20 20 0a 2a 2a 20 7b 46            .** {F
23120 31 33 37 34 32 7d 20 54 68 65 20 5b 73 71 6c 69  13742} The [sqli
23130 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62  te3_column_datab
23140 61 73 65 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d  ase_name16(S,N)]
23150 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
23160 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20  ns either.**    
23170 20 20 20 20 20 20 74 68 65 20 55 54 46 2d 31 36        the UTF-16
23180 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
23190 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a  er.**          z
231a0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e  ero-terminated n
231b0 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ame of the datab
231c0 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68 20 74  ase from which t
231d0 68 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  he .**          
231e0 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  Nth result colum
231f0 6e 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73  n of [prepared s
23200 74 61 74 65 6d 65 6e 74 5d 20 53 20 0a 2a 2a 20  tatement] S .** 
23210 20 20 20 20 20 20 20 20 20 69 73 20 65 78 74 72           is extr
23220 61 63 74 65 64 2c 20 6f 72 20 4e 55 4c 4c 20 69  acted, or NULL i
23230 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  f the Nth column
23240 20 6f 66 20 53 20 69 73 20 61 0a 2a 2a 20 20 20   of S is a.**   
23250 20 20 20 20 20 20 20 67 65 6e 65 72 61 6c 20 65         general e
23260 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 69 66 20  xpression or if 
23270 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61  unable to alloca
23280 74 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20 20  te memory.**    
23290 20 20 20 20 20 20 74 6f 20 73 74 6f 72 65 20 74        to store t
232a0 68 65 20 6e 61 6d 65 2e 0a 2a 2a 20 20 20 20 20  he name..**     
232b0 20 20 20 20 20 0a 2a 2a 20 7b 46 31 33 37 34 33       .** {F13743
232c0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
232d0 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65  olumn_table_name
232e0 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  (S,N)] interface
232f0 20 72 65 74 75 72 6e 73 20 65 69 74 68 65 72 0a   returns either.
23300 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
23310 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69  UTF-8 zero-termi
23320 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66 20 74 68  nated name of th
23330 65 20 74 61 62 6c 65 20 66 72 6f 6d 20 77 68 69  e table from whi
23340 63 68 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 20  ch the .**      
23350 20 20 20 20 4e 74 68 20 72 65 73 75 6c 74 20 63      Nth result c
23360 6f 6c 75 6d 6e 20 6f 66 20 5b 70 72 65 70 61 72  olumn of [prepar
23370 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
23380 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20  .**          is 
23390 65 78 74 72 61 63 74 65 64 2c 20 6f 72 20 4e 55  extracted, or NU
233a0 4c 4c 20 69 66 20 74 68 65 20 4e 74 68 20 63 6f  LL if the Nth co
233b0 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20 61 0a 2a  lumn of S is a.*
233c0 2a 20 20 20 20 20 20 20 20 20 20 67 65 6e 65 72  *          gener
233d0 61 6c 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72  al expression or
233e0 20 69 66 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c   if unable to al
233f0 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 0a 2a 2a  locate memory.**
23400 20 20 20 20 20 20 20 20 20 20 74 6f 20 73 74 6f            to sto
23410 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 20  re the name..** 
23420 20 20 20 20 20 20 20 20 20 0a 2a 2a 20 7b 46 31           .** {F1
23430 33 37 34 34 7d 20 54 68 65 20 5b 73 71 6c 69 74  3744} The [sqlit
23440 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f  e3_column_table_
23450 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20 69 6e 74  name16(S,N)] int
23460 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 65  erface returns e
23470 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  ither.**        
23480 20 20 74 68 65 20 55 54 46 2d 31 36 20 6e 61 74    the UTF-16 nat
23490 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 0a 2a  ive byte order.*
234a0 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 2d  *          zero-
234b0 74 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20  terminated name 
234c0 6f 66 20 74 68 65 20 74 61 62 6c 65 20 66 72 6f  of the table fro
234d0 6d 20 77 68 69 63 68 20 74 68 65 20 0a 2a 2a 20  m which the .** 
234e0 20 20 20 20 20 20 20 20 20 4e 74 68 20 72 65 73           Nth res
234f0 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 5b 70  ult column of [p
23500 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
23510 74 5d 20 53 20 0a 2a 2a 20 20 20 20 20 20 20 20  t] S .**        
23520 20 20 69 73 20 65 78 74 72 61 63 74 65 64 2c 20    is extracted, 
23530 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 4e  or NULL if the N
23540 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69  th column of S i
23550 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  s a.**          
23560 67 65 6e 65 72 61 6c 20 65 78 70 72 65 73 73 69  general expressi
23570 6f 6e 20 6f 72 20 69 66 20 75 6e 61 62 6c 65 20  on or if unable 
23580 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f  to allocate memo
23590 72 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  ry.**          t
235a0 6f 20 73 74 6f 72 65 20 74 68 65 20 6e 61 6d 65  o store the name
235b0 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 0a 2a  ..**          .*
235c0 2a 20 7b 46 31 33 37 34 35 7d 20 54 68 65 20 5b  * {F13745} The [
235d0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f  sqlite3_column_o
235e0 72 69 67 69 6e 5f 6e 61 6d 65 28 53 2c 4e 29 5d  rigin_name(S,N)]
235f0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
23600 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20  ns either.**    
23610 20 20 20 20 20 20 74 68 65 20 55 54 46 2d 38 20        the UTF-8 
23620 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
23630 6e 61 6d 65 20 6f 66 20 74 68 65 20 74 61 62 6c  name of the tabl
23640 65 20 63 6f 6c 75 6d 6e 20 66 72 6f 6d 20 77 68  e column from wh
23650 69 63 68 20 74 68 65 20 0a 2a 2a 20 20 20 20 20  ich the .**     
23660 20 20 20 20 20 4e 74 68 20 72 65 73 75 6c 74 20       Nth result 
23670 63 6f 6c 75 6d 6e 20 6f 66 20 5b 70 72 65 70 61  column of [prepa
23680 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
23690 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73   .**          is
236a0 20 65 78 74 72 61 63 74 65 64 2c 20 6f 72 20 4e   extracted, or N
236b0 55 4c 4c 20 69 66 20 74 68 65 20 4e 74 68 20 63  ULL if the Nth c
236c0 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20 61 0a  olumn of S is a.
236d0 2a 2a 20 20 20 20 20 20 20 20 20 20 67 65 6e 65  **          gene
236e0 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e 20 6f  ral expression o
236f0 72 20 69 66 20 75 6e 61 62 6c 65 20 74 6f 20 61  r if unable to a
23700 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 0a 2a  llocate memory.*
23710 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 73 74  *          to st
23720 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a  ore the name..**
23730 20 20 20 20 20 20 20 20 20 20 0a 2a 2a 20 7b 46            .** {F
23740 31 33 37 34 36 7d 20 54 68 65 20 5b 73 71 6c 69  13746} The [sqli
23750 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69  te3_column_origi
23760 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20 69  n_name16(S,N)] i
23770 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
23780 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20   either.**      
23790 20 20 20 20 74 68 65 20 55 54 46 2d 31 36 20 6e      the UTF-16 n
237a0 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
237b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72  .**          zer
237c0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d  o-terminated nam
237d0 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63  e of the table c
237e0 6f 6c 75 6d 6e 20 66 72 6f 6d 20 77 68 69 63 68  olumn from which
237f0 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 20 20 20   the .**        
23800 20 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c    Nth result col
23810 75 6d 6e 20 6f 66 20 5b 70 72 65 70 61 72 65 64  umn of [prepared
23820 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 0a 2a   statement] S .*
23830 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 65 78  *          is ex
23840 74 72 61 63 74 65 64 2c 20 6f 72 20 4e 55 4c 4c  tracted, or NULL
23850 20 69 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75   if the Nth colu
23860 6d 6e 20 6f 66 20 53 20 69 73 20 61 0a 2a 2a 20  mn of S is a.** 
23870 20 20 20 20 20 20 20 20 20 67 65 6e 65 72 61 6c           general
23880 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 69   expression or i
23890 66 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f  f unable to allo
238a0 63 61 74 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20  cate memory.**  
238b0 20 20 20 20 20 20 20 20 74 6f 20 73 74 6f 72 65          to store
238c0 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 20 20 20   the name..**   
238d0 20 20 20 20 20 20 20 0a 2a 2a 20 7b 46 31 33 37         .** {F137
238e0 34 38 7d 20 54 68 65 20 72 65 74 75 72 6e 20 76  48} The return v
238f0 61 6c 75 65 73 20 66 72 6f 6d 0a 2a 2a 20 20 20  alues from.**   
23900 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
23910 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
23920 6e 61 6d 65 7c 63 6f 6c 75 6d 6e 20 6d 65 74 61  name|column meta
23930 64 61 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d  data interfaces]
23940 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 72 65  .**          are
23950 20 76 61 6c 69 64 0a 2a 2a 20 20 20 20 20 20 20   valid.**       
23960 20 20 20 66 6f 72 20 74 68 65 20 6c 69 66 65 74     for the lifet
23970 69 6d 65 20 6f 66 20 74 68 65 20 5b 70 72 65 70  ime of the [prep
23980 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a  ared statement].
23990 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 75  **          or u
239a0 6e 74 69 6c 20 74 68 65 20 65 6e 63 6f 64 69 6e  ntil the encodin
239b0 67 20 69 73 20 63 68 61 6e 67 65 64 20 62 79 20  g is changed by 
239c0 61 6e 6f 74 68 65 72 20 6d 65 74 61 64 61 74 61  another metadata
239d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74  .**          int
239e0 65 72 66 61 63 65 20 63 61 6c 6c 20 66 6f 72 20  erface call for 
239f0 74 68 65 20 73 61 6d 65 20 70 72 65 70 61 72 65  the same prepare
23a00 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20  d statement and 
23a10 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 4c 49  column..**.** LI
23a20 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a  MITATIONS:.**.**
23a30 20 7b 55 31 33 37 35 31 7d 20 49 66 20 74 77 6f   {U13751} If two
23a40 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73   or more threads
23a50 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72   call one or mor
23a60 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  e.**          [s
23a70 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61  qlite3_column_da
23a80 74 61 62 61 73 65 5f 6e 61 6d 65 7c 63 6f 6c 75  tabase_name|colu
23a90 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65  mn metadata inte
23aa0 72 66 61 63 65 73 5d 0a 2a 2a 20 20 20 20 20 20  rfaces].**      
23ab0 20 20 20 20 74 68 65 20 73 61 6d 65 20 5b 70 72      the same [pr
23ac0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
23ad0 5d 20 61 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c  ] and result col
23ae0 75 6d 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  umn.**          
23af0 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
23b00 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
23b10 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
23b20 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
23b30 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
23b40 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c  atabase_name(sql
23b50 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
23b60 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
23b70 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61  ite3_column_data
23b80 62 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69  base_name16(sqli
23b90 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
23ba0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
23bb0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65  te3_column_table
23bc0 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
23bd0 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
23be0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
23bf0 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31  lumn_table_name1
23c00 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
23c10 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72  int);.const char
23c20 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
23c30 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c  _origin_name(sql
23c40 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
23c50 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
23c60 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67  ite3_column_orig
23c70 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  in_name16(sqlite
23c80 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f  3_stmt*,int);../
23c90 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
23ca0 65 63 6c 61 72 65 64 20 44 61 74 61 74 79 70 65  eclared Datatype
23cb0 20 4f 66 20 41 20 51 75 65 72 79 20 52 65 73 75   Of A Query Resu
23cc0 6c 74 20 7b 46 31 33 37 36 30 7d 0a 2a 2a 0a 2a  lt {F13760}.**.*
23cd0 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61  * The first para
23ce0 6d 65 74 65 72 20 69 73 20 61 20 5b 70 72 65 70  meter is a [prep
23cf0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
23d00 20 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61   .** If this sta
23d10 74 65 6d 65 6e 74 20 69 73 20 61 20 53 45 4c 45  tement is a SELE
23d20 43 54 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64  CT statement and
23d30 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
23d40 6f 66 20 74 68 65 20 0a 2a 2a 20 72 65 74 75 72  of the .** retur
23d50 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f  ned result set o
23d60 66 20 74 68 61 74 20 53 45 4c 45 43 54 20 69 73  f that SELECT is
23d70 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20   a table column 
23d80 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65  (not an.** expre
23d90 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72  ssion or subquer
23da0 79 29 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c  y) then the decl
23db0 61 72 65 64 20 74 79 70 65 20 6f 66 20 74 68 65  ared type of the
23dc0 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e   table.** column
23dd0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 49   is returned.  I
23de0 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  f the Nth column
23df0 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
23e00 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72  et is an.** expr
23e10 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65  ession or subque
23e20 72 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20  ry, then a NULL 
23e30 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72  pointer is retur
23e40 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 72 65 74 75  ned..** The retu
23e50 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 61  rned string is a
23e60 6c 77 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f  lways UTF-8 enco
23e70 64 65 64 2e 20 20 7b 45 4e 44 7d 20 0a 2a 2a 20  ded.  {END} .** 
23e80 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 6e 20  For example, in 
23e90 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68  the database sch
23ea0 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54  ema:.**.** CREAT
23eb0 45 20 54 41 42 4c 45 20 74 31 28 63 31 20 56 41  E TABLE t1(c1 VA
23ec0 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 41 6e  RIANT);.**.** An
23ed0 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  d the following 
23ee0 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c  statement compil
23ef0 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54  ed:.**.** SELECT
23f00 20 63 31 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d   c1 + 1, c1 FROM
23f10 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 54 68 65 6e 20   t1;.**.** Then 
23f20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 6f 75  this routine wou
23f30 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 73 74  ld return the st
23f40 72 69 6e 67 20 22 56 41 52 49 41 4e 54 22 20 66  ring "VARIANT" f
23f50 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a  or the second.**
23f60 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28   result column (
23f70 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c  i==1), and a NUL
23f80 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68  L pointer for th
23f90 65 20 66 69 72 73 74 20 72 65 73 75 6c 74 20 63  e first result c
23fa0 6f 6c 75 6d 6e 0a 2a 2a 20 28 69 3d 3d 30 29 2e  olumn.** (i==0).
23fb0 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73  .**.** SQLite us
23fc0 65 73 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74  es dynamic run-t
23fd0 69 6d 65 20 74 79 70 69 6e 67 2e 20 20 53 6f 20  ime typing.  So 
23fe0 6a 75 73 74 20 62 65 63 61 75 73 65 20 61 20 63  just because a c
23ff0 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c  olumn.** is decl
24000 61 72 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20  ared to contain 
24010 61 20 70 61 72 74 69 63 75 6c 61 72 20 74 79 70  a particular typ
24020 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20  e does not mean 
24030 74 68 61 74 20 74 68 65 0a 2a 2a 20 64 61 74 61  that the.** data
24040 20 73 74 6f 72 65 64 20 69 6e 20 74 68 61 74 20   stored in that 
24050 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68 65  column is of the
24060 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 2e 20   declared type. 
24070 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74   SQLite is.** st
24080 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20 62 75  rongly typed, bu
24090 74 20 74 68 65 20 74 79 70 69 6e 67 20 69 73 20  t the typing is 
240a0 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61 74  dynamic not stat
240b0 69 63 2e 20 20 54 79 70 65 0a 2a 2a 20 69 73 20  ic.  Type.** is 
240c0 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
240d0 69 6e 64 69 76 69 64 75 61 6c 20 76 61 6c 75 65  individual value
240e0 73 2c 20 6e 6f 74 20 77 69 74 68 20 74 68 65 20  s, not with the 
240f0 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73  containers.** us
24100 65 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65  ed to hold those
24110 20 76 61 6c 75 65 73 2e 0a 2a 2a 0a 2a 2a 20 49   values..**.** I
24120 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
24130 20 7b 46 31 33 37 36 31 7d 20 20 41 20 73 75 63   {F13761}  A suc
24140 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
24150 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
24160 64 65 63 6c 74 79 70 65 28 53 2c 4e 29 5d 0a 2a  decltype(S,N)].*
24170 2a 20 20 20 20 20 20 20 20 20 20 20 72 65 74 75  *           retu
24180 72 6e 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69  rns a zero-termi
24190 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69  nated UTF-8 stri
241a0 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  ng containing th
241b0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74  e.**           t
241c0 68 65 20 64 65 63 6c 61 72 65 64 20 64 61 74 61  he declared data
241d0 74 79 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c  type of the tabl
241e0 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 61 70  e column that ap
241f0 70 65 61 72 73 0a 2a 2a 20 20 20 20 20 20 20 20  pears.**        
24200 20 20 20 61 73 20 74 68 65 20 4e 74 68 20 63 6f     as the Nth co
24210 6c 75 6d 6e 20 28 6e 75 6d 62 65 72 65 64 20 66  lumn (numbered f
24220 72 6f 6d 20 30 29 20 6f 66 20 74 68 65 20 72 65  rom 0) of the re
24230 73 75 6c 74 20 73 65 74 20 74 6f 20 74 68 65 0a  sult set to the.
24240 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 70 72  **           [pr
24250 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
24260 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37  ] S..**.** {F137
24270 36 32 7d 20 20 41 20 73 75 63 63 65 73 73 66 75  62}  A successfu
24280 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  l call to [sqlit
24290 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79  e3_column_declty
242a0 70 65 31 36 28 53 2c 4e 29 5d 0a 2a 2a 20 20 20  pe16(S,N)].**   
242b0 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 73 20          returns 
242c0 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
242d0 64 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20  d UTF-16 native 
242e0 62 79 74 65 20 6f 72 64 65 72 20 73 74 72 69 6e  byte order strin
242f0 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 63  g.**           c
24300 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 64 65  ontaining the de
24310 63 6c 61 72 65 64 20 64 61 74 61 74 79 70 65 20  clared datatype 
24320 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c  of the table col
24330 75 6d 6e 20 74 68 61 74 20 61 70 70 65 61 72 73  umn that appears
24340 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 61 73  .**           as
24350 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
24360 28 6e 75 6d 62 65 72 65 64 20 66 72 6f 6d 20 30  (numbered from 0
24370 29 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  ) of the result 
24380 73 65 74 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20  set to the.**   
24390 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65          [prepare
243a0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a  d statement] S..
243b0 2a 2a 0a 2a 2a 20 7b 46 31 33 37 36 33 7d 20 20  **.** {F13763}  
243c0 49 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61  If N is less tha
243d0 6e 20 30 20 6f 72 20 4e 20 69 73 20 67 72 65 61  n 0 or N is grea
243e0 74 65 72 20 74 68 61 6e 20 6f 72 20 65 71 75 61  ter than or equa
243f0 6c 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20  l to.**         
24400 20 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20    the number of 
24410 63 6f 6c 75 6d 6e 73 20 69 6e 20 5b 70 72 65 70  columns in [prep
24420 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
24430 53 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6f  S.**           o
24440 72 20 69 66 20 74 68 65 20 4e 74 68 20 63 6f 6c  r if the Nth col
24450 75 6d 6e 20 6f 66 20 53 20 69 73 20 61 6e 20 65  umn of S is an e
24460 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62  xpression or sub
24470 71 75 65 72 79 20 72 61 74 68 65 72 0a 2a 2a 20  query rather.** 
24480 20 20 20 20 20 20 20 20 20 20 74 68 61 6e 20 61            than a
24490 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 6f 72   table column or
244a0 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   if a memory all
244b0 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 0a  ocation failure.
244c0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6f 63 63  **           occ
244d0 75 72 73 20 64 75 72 69 6e 67 20 65 6e 63 6f 64  urs during encod
244e0 69 6e 67 20 63 6f 6e 76 65 72 73 69 6f 6e 73 2c  ing conversions,
244f0 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20   then.**        
24500 20 20 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c     calls to [sql
24510 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c  ite3_column_decl
24520 74 79 70 65 28 53 2c 4e 29 5d 20 6f 72 0a 2a 2a  type(S,N)] or.**
24530 20 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69             [sqli
24540 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74  te3_column_declt
24550 79 70 65 31 36 28 53 2c 4e 29 5d 20 72 65 74 75  ype16(S,N)] retu
24560 72 6e 20 4e 55 4c 4c 2e 0a 2a 2f 0a 63 6f 6e 73  rn NULL..*/.cons
24570 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
24580 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28  column_decltype(
24590 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
245a0 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  t);.const void *
245b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
245c0 65 63 6c 74 79 70 65 31 36 28 73 71 6c 69 74 65  ecltype16(sqlite
245d0 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f  3_stmt*,int);../
245e0 2a 20 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  * .** CAPI3REF: 
245f0 20 45 76 61 6c 75 61 74 65 20 41 6e 20 53 51 4c   Evaluate An SQL
24600 20 53 74 61 74 65 6d 65 6e 74 20 7b 46 31 33 32   Statement {F132
24610 30 30 7d 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20  00}.**.** After 
24620 61 6e 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  an [prepared sta
24630 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e  tement] has been
24640 20 70 72 65 70 61 72 65 64 20 77 69 74 68 20 61   prepared with a
24650 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 65 69 74 68   call.** to eith
24660 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  er [sqlite3_prep
24670 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71  are_v2()] or [sq
24680 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
24690 76 32 28 29 5d 20 6f 72 20 74 6f 20 6f 6e 65 20  v2()] or to one 
246a0 6f 66 0a 2a 2a 20 74 68 65 20 6c 65 67 61 63 79  of.** the legacy
246b0 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c   interfaces [sql
246c0 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
246d0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
246e0 61 72 65 31 36 28 29 5d 2c 0a 2a 2a 20 74 68 65  are16()],.** the
246f0 6e 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  n this function 
24700 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 6f  must be called o
24710 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73  ne or more times
24720 20 74 6f 20 65 76 61 6c 75 61 74 65 20 74 68 65   to evaluate the
24730 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 0a   .** statement..
24740 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c  **.** The detail
24750 73 20 6f 66 20 74 68 65 20 62 65 68 61 76 69 6f  s of the behavio
24760 72 20 6f 66 20 74 68 69 73 20 73 71 6c 69 74 65  r of this sqlite
24770 33 5f 73 74 65 70 28 29 20 69 6e 74 65 72 66 61  3_step() interfa
24780 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20  ce depend.** on 
24790 77 68 65 74 68 65 72 20 74 68 65 20 73 74 61 74  whether the stat
247a0 65 6d 65 6e 74 20 77 61 73 20 70 72 65 70 61 72  ement was prepar
247b0 65 64 20 75 73 69 6e 67 20 74 68 65 20 6e 65 77  ed using the new
247c0 65 72 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  er "v2" interfac
247d0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  e.** [sqlite3_pr
247e0 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
247f0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
24800 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 68 65 20  16_v2()] or the 
24810 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20  older legacy.** 
24820 69 6e 74 65 72 66 61 63 65 20 5b 73 71 6c 69 74  interface [sqlit
24830 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e  e3_prepare()] an
24840 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
24850 72 65 31 36 28 29 5d 2e 20 20 54 68 65 20 75 73  re16()].  The us
24860 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20  e of the.** new 
24870 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69  "v2" interface i
24880 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f  s recommended fo
24890 72 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f  r new applicatio
248a0 6e 73 20 62 75 74 20 74 68 65 20 6c 65 67 61 63  ns but the legac
248b0 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 77  y.** interface w
248c0 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20  ill continue to 
248d0 62 65 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a  be supported..**
248e0 0a 2a 2a 20 49 6e 20 74 68 65 20 6c 65 67 61 63  .** In the legac
248f0 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65  y interface, the
24900 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 77 69   return value wi
24910 6c 6c 20 62 65 20 65 69 74 68 65 72 20 5b 53 51  ll be either [SQ
24920 4c 49 54 45 5f 42 55 53 59 5d 2c 20 0a 2a 2a 20  LITE_BUSY], .** 
24930 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b  [SQLITE_DONE], [
24940 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51  SQLITE_ROW], [SQ
24950 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20  LITE_ERROR], or 
24960 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e  [SQLITE_MISUSE].
24970 0a 2a 2a 20 57 69 74 68 20 74 68 65 20 22 76 32  .** With the "v2
24980 22 20 69 6e 74 65 72 66 61 63 65 2c 20 61 6e 79  " interface, any
24990 20 6f 66 20 74 68 65 20 6f 74 68 65 72 20 5b 53   of the other [S
249a0 51 4c 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c  QLITE_OK | resul
249b0 74 20 63 6f 64 65 5d 0a 2a 2a 20 6f 72 20 5b 53  t code].** or [S
249c0 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44  QLITE_IOERR_READ
249d0 20 7c 20 65 78 74 65 6e 64 65 64 20 72 65 73 75   | extended resu
249e0 6c 74 20 63 6f 64 65 5d 20 6d 69 67 68 74 20 62  lt code] might b
249f0 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a  e returned as.**
24a00 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51   well..**.** [SQ
24a10 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73  LITE_BUSY] means
24a20 20 74 68 61 74 20 74 68 65 20 64 61 74 61 62 61   that the databa
24a30 73 65 20 65 6e 67 69 6e 65 20 77 61 73 20 75 6e  se engine was un
24a40 61 62 6c 65 20 74 6f 20 61 63 71 75 69 72 65 20  able to acquire 
24a50 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
24a60 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64 73 20 74  locks it needs t
24a70 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20 49  o do its job.  I
24a80 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
24a90 69 73 20 61 20 43 4f 4d 4d 49 54 0a 2a 2a 20 6f  is a COMMIT.** o
24aa0 72 20 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65  r occurs outside
24ab0 20 6f 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20   of an explicit 
24ac0 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65  transaction, the
24ad0 6e 20 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20  n you can retry 
24ae0 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  the.** statement
24af0 2e 20 20 49 66 20 74 68 65 20 73 74 61 74 65 6d  .  If the statem
24b00 65 6e 74 20 69 73 20 6e 6f 74 20 61 20 43 4f 4d  ent is not a COM
24b10 4d 49 54 20 61 6e 64 20 6f 63 63 75 72 73 20 77  MIT and occurs w
24b20 69 74 68 69 6e 20 61 0a 2a 2a 20 65 78 70 6c 69  ithin a.** expli
24b30 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  cit transaction 
24b40 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20  then you should 
24b50 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61  rollback the tra
24b60 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a  nsaction before.
24b70 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a  ** continuing..*
24b80 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  *.** [SQLITE_DON
24b90 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  E] means that th
24ba0 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20  e statement has 
24bb0 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69  finished executi
24bc0 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c  ng.** successful
24bd0 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65  ly.  sqlite3_ste
24be0 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62  p() should not b
24bf0 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f  e called again o
24c00 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a  n this virtual.*
24c10 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75  * machine withou
24c20 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20  t first calling 
24c30 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
24c40 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 76  ] to reset the v
24c50 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e  irtual.** machin
24c60 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e  e back to its in
24c70 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a  itial state..**.
24c80 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 74  ** If the SQL st
24c90 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78  atement being ex
24ca0 65 63 75 74 65 64 20 72 65 74 75 72 6e 73 20 61  ecuted returns a
24cb0 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20 0a 2a  ny data, then .*
24cc0 2a 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 69  * [SQLITE_ROW] i
24cd0 73 20 72 65 74 75 72 6e 65 64 20 65 61 63 68 20  s returned each 
24ce0 74 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f  time a new row o
24cf0 66 20 64 61 74 61 20 69 73 20 72 65 61 64 79 0a  f data is ready.
24d00 2a 2a 20 66 6f 72 20 70 72 6f 63 65 73 73 69 6e  ** for processin
24d10 67 20 62 79 20 74 68 65 20 63 61 6c 6c 65 72 2e  g by the caller.
24d20 20 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20   The values may 
24d30 62 65 20 61 63 63 65 73 73 65 64 20 75 73 69 6e  be accessed usin
24d40 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  g.** the [sqlite
24d50 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 63  3_column_int | c
24d60 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e  olumn access fun
24d70 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69  ctions]..** sqli
24d80 74 65 33 5f 73 74 65 70 28 29 20 69 73 20 63 61  te3_step() is ca
24d90 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f 20 72 65  lled again to re
24da0 74 72 69 65 76 65 20 74 68 65 20 6e 65 78 74 20  trieve the next 
24db0 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 20  row of data..** 
24dc0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  .** [SQLITE_ERRO
24dd0 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20  R] means that a 
24de0 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 28  run-time error (
24df0 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73 74 72  such as a constr
24e00 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f  aint.** violatio
24e10 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65 64 2e  n) has occurred.
24e20 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29    sqlite3_step()
24e30 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63   should not be c
24e40 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a  alled again on.*
24e50 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69  * the VM. More i
24e60 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62  nformation may b
24e70 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69  e found by calli
24e80 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ng [sqlite3_errm
24e90 73 67 28 29 5d 2e 0a 2a 2a 20 57 69 74 68 20 74  sg()]..** With t
24ea0 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66  he legacy interf
24eb0 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 70 65 63  ace, a more spec
24ec0 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20  ific error code 
24ed0 28 65 78 61 6d 70 6c 65 3a 0a 2a 2a 20 5b 53 51  (example:.** [SQ
24ee0 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c  LITE_INTERRUPT],
24ef0 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d   [SQLITE_SCHEMA]
24f00 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50  , [SQLITE_CORRUP
24f10 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 68  T], and so forth
24f20 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 61  ).** can be obta
24f30 69 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20  ined by calling 
24f40 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
24f50 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65  ] on the.** [pre
24f60 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
24f70 2e 20 20 49 6e 20 74 68 65 20 22 76 32 22 20 69  .  In the "v2" i
24f80 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65  nterface,.** the
24f90 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65   more specific e
24fa0 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74  rror code is ret
24fb0 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 20 62  urned directly b
24fc0 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  y sqlite3_step()
24fd0 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ..**.** [SQLITE_
24fe0 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 68  MISUSE] means th
24ff0 61 74 20 74 68 65 20 74 68 69 73 20 72 6f 75 74  at the this rout
25000 69 6e 65 20 77 61 73 20 63 61 6c 6c 65 64 20 69  ine was called i
25010 6e 61 70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a  nappropriately..
25020 2a 2a 20 50 65 72 68 61 70 73 20 69 74 20 77 61  ** Perhaps it wa
25030 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70  s called on a [p
25040 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
25050 74 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 61  t] that has.** a
25060 6c 72 65 61 64 79 20 62 65 65 6e 20 5b 73 71 6c  lready been [sql
25070 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20  ite3_finalize | 
25080 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e  finalized] or on
25090 20 6f 6e 65 20 74 68 61 74 20 68 61 64 20 0a 2a   one that had .*
250a0 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74  * previously ret
250b0 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 52  urned [SQLITE_ER
250c0 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ROR] or [SQLITE_
250d0 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f  DONE].  Or it co
250e0 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 61  uld.** be the ca
250f0 73 65 20 74 68 61 74 20 74 68 65 20 73 61 6d 65  se that the same
25100 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
25110 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 73  tion is being us
25120 65 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20  ed by two or.** 
25130 6d 6f 72 65 20 74 68 72 65 61 64 73 20 61 74 20  more threads at 
25140 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20  the same moment 
25150 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 3c  in time..**.** <
25160 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63  b>Goofy Interfac
25170 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 0a 2a 2a 20  e Alert:</b>.** 
25180 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e  In the legacy in
25190 74 65 72 66 61 63 65 2c 20 0a 2a 2a 20 74 68 65  terface, .** the
251a0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
251b0 41 50 49 20 61 6c 77 61 79 73 20 72 65 74 75 72  API always retur
251c0 6e 73 20 61 20 67 65 6e 65 72 69 63 20 65 72 72  ns a generic err
251d0 6f 72 20 63 6f 64 65 2c 0a 2a 2a 20 5b 53 51 4c  or code,.** [SQL
251e0 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c  ITE_ERROR], foll
251f0 6f 77 69 6e 67 20 61 6e 79 20 65 72 72 6f 72 20  owing any error 
25200 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
25210 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 61 6e 64 20  TE_BUSY].** and 
25220 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e  [SQLITE_MISUSE].
25230 20 20 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 20    You must call 
25240 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
25250 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
25260 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20  _finalize()] in 
25270 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e  order to find on
25280 65 20 6f 66 20 74 68 65 20 73 70 65 63 69 66 69  e of the specifi
25290 63 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65  c.** [error code
252a0 73 5d 20 74 68 61 74 20 62 65 74 74 65 72 20 64  s] that better d
252b0 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72  escribes the err
252c0 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20  or..** We admit 
252d0 74 68 61 74 20 74 68 69 73 20 69 73 20 61 20 67  that this is a g
252e0 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68  oofy design.  Th
252f0 65 20 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65  e problem has be
25300 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68  en fixed.** with
25310 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
25320 61 63 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65  ace.  If you pre
25330 70 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72  pare all of your
25340 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
25350 2a 2a 20 75 73 69 6e 67 20 65 69 74 68 65 72 20  ** using either 
25360 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
25370 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  _v2()] or [sqlit
25380 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
25390 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66  )] instead.** of
253a0 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c   the legacy [sql
253b0 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
253c0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  and [sqlite3_pre
253d0 70 61 72 65 31 36 28 29 5d 2c 20 74 68 65 6e 20  pare16()], then 
253e0 74 68 65 20 0a 2a 2a 20 6d 6f 72 65 20 73 70 65  the .** more spe
253f0 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64  cific [error cod
25400 65 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64  es] are returned
25410 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20   directly.** by 
25420 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20  sqlite3_step(). 
25430 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 20   The use of the 
25440 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69  "v2" interface i
25450 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a  s recommended..*
25460 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
25470 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 32 30 32 7d 20  .**.** {F13202} 
25480 20 49 66 20 5b 70 72 65 70 61 72 65 64 20 73 74   If [prepared st
25490 61 74 65 6d 65 6e 74 5d 20 53 20 69 73 20 72 65  atement] S is re
254a0 61 64 79 20 74 6f 20 62 65 0a 2a 2a 20 20 20 20  ady to be.**    
254b0 20 20 20 20 20 20 20 72 75 6e 2c 20 74 68 65 6e         run, then
254c0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
254d0 29 5d 20 61 64 76 61 6e 63 65 73 20 74 68 61 74  )] advances that
254e0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
254f0 65 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ent.**          
25500 20 75 6e 74 69 6c 20 74 6f 20 63 6f 6d 70 6c 65   until to comple
25510 74 69 6f 6e 20 6f 72 20 75 6e 74 69 6c 20 69 74  tion or until it
25520 20 69 73 20 72 65 61 64 79 20 74 6f 20 72 65 74   is ready to ret
25530 75 72 6e 20 61 6e 6f 74 68 65 72 0a 2a 2a 20 20  urn another.**  
25540 20 20 20 20 20 20 20 20 20 72 6f 77 20 6f 66 20           row of 
25550 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f  the result set o
25560 72 20 61 6e 20 69 6e 74 65 72 72 75 70 74 20 6f  r an interrupt o
25570 72 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72  r run-time error
25580 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b   occurs..**.** {
25590 46 31 35 33 30 34 7d 20 20 57 68 65 6e 20 61 20  F15304}  When a 
255a0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
255b0 5f 73 74 65 70 28 53 29 5d 20 63 61 75 73 65 73  _step(S)] causes
255c0 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 20 20 20   the .**        
255d0 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61     [prepared sta
255e0 74 65 6d 65 6e 74 5d 20 53 20 74 6f 20 72 75 6e  tement] S to run
255f0 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2c 0a   to completion,.
25600 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 68 65  **           the
25610 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
25620 73 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e  s [SQLITE_DONE].
25630 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 33 30 36 7d 20  .**.** {F15306} 
25640 20 57 68 65 6e 20 61 20 63 61 6c 6c 20 74 6f 20   When a call to 
25650 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
25660 5d 20 73 74 6f 70 73 20 62 65 63 61 75 73 65 20  ] stops because 
25670 69 74 20 69 73 20 72 65 61 64 79 0a 2a 2a 20 20  it is ready.**  
25680 20 20 20 20 20 20 20 20 20 74 6f 20 72 65 74 75           to retu
25690 72 6e 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 6f  rn another row o
256a0 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
256b0 2c 20 69 74 20 72 65 74 75 72 6e 73 0a 2a 2a 20  , it returns.** 
256c0 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54            [SQLIT
256d0 45 5f 52 4f 57 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46  E_ROW]..**.** {F
256e0 31 35 33 30 38 7d 20 20 49 66 20 61 20 63 61 6c  15308}  If a cal
256f0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
25700 65 70 28 53 29 5d 20 65 6e 63 6f 75 6e 74 65 72  ep(S)] encounter
25710 73 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  s an.**         
25720 20 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72    [sqlite3_inter
25730 72 75 70 74 7c 69 6e 74 65 72 72 75 70 74 5d 20  rupt|interrupt] 
25740 6f 72 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72  or a run-time er
25750 72 6f 72 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ror,.**         
25760 20 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20    it returns an 
25770 61 70 70 72 6f 70 72 69 61 74 65 20 65 72 72 6f  appropriate erro
25780 72 20 63 6f 64 65 20 74 68 61 74 20 69 73 20 6e  r code that is n
25790 6f 74 20 6f 6e 65 20 6f 66 0a 2a 2a 20 20 20 20  ot one of.**    
257a0 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 4f         [SQLITE_O
257b0 4b 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  K], [SQLITE_ROW]
257c0 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  , or [SQLITE_DON
257d0 45 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 33 31  E]..**.** {F1531
257e0 30 7d 20 20 49 66 20 61 6e 20 5b 73 71 6c 69 74  0}  If an [sqlit
257f0 65 33 5f 69 6e 74 65 72 72 75 70 74 7c 69 6e 74  e3_interrupt|int
25800 65 72 72 75 70 74 5d 20 6f 72 20 72 75 6e 2d 74  errupt] or run-t
25810 69 6d 65 20 65 72 72 6f 72 0a 2a 2a 20 20 20 20  ime error.**    
25820 20 20 20 20 20 20 20 6f 63 63 75 72 73 20 64 75         occurs du
25830 72 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 5b  ring a call to [
25840 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
25850 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 66 6f  .**           fo
25860 72 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  r a [prepared st
25870 61 74 65 6d 65 6e 74 5d 20 53 20 63 72 65 61 74  atement] S creat
25880 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20  ed using.**     
25890 20 20 20 20 20 20 6c 65 67 61 63 79 20 69 6e 74        legacy int
258a0 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33  erfaces [sqlite3
258b0 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 0a 2a  _prepare()] or.*
258c0 2a 20 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  *           [sql
258d0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
258e0 5d 20 74 68 65 6e 20 74 68 65 20 66 75 6e 63 74  ] then the funct
258f0 69 6f 6e 20 72 65 74 75 72 6e 73 20 65 69 74 68  ion returns eith
25900 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  er.**           
25910 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20  [SQLITE_ERROR], 
25920 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 20 6f  [SQLITE_BUSY], o
25930 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  r [SQLITE_MISUSE
25940 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
25950 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73  3_step(sqlite3_s
25960 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
25970 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f  PI3REF: Number o
25980 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72  f columns in a r
25990 65 73 75 6c 74 20 73 65 74 20 7b 46 31 33 37 37  esult set {F1377
259a0 30 7d 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20  0}.**.** Return 
259b0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 76 61  the number of va
259c0 6c 75 65 73 20 69 6e 20 74 68 65 20 63 75 72 72  lues in the curr
259d0 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72  ent row of the r
259e0 65 73 75 6c 74 20 73 65 74 2e 0a 2a 2a 0a 2a 2a  esult set..**.**
259f0 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
25a00 2a 2a 20 7b 46 31 33 37 37 31 7d 20 20 41 66 74  ** {F13771}  Aft
25a10 65 72 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71  er a call to [sq
25a20 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 74  lite3_step(S)] t
25a30 68 61 74 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20  hat returns.**  
25a40 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45           [SQLITE
25a50 5f 52 4f 57 5d 2c 20 74 68 65 20 5b 73 71 6c 69  _ROW], the [sqli
25a60 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 53  te3_data_count(S
25a70 29 5d 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 20 20  )] routine.**   
25a80 20 20 20 20 20 20 20 20 77 69 6c 6c 20 72 65 74          will ret
25a90 75 72 6e 20 74 68 65 20 73 61 6d 65 20 76 61 6c  urn the same val
25aa0 75 65 20 61 73 20 74 68 65 0a 2a 2a 20 20 20 20  ue as the.**    
25ab0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
25ac0 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 53 29 5d  column_count(S)]
25ad0 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   function..**.**
25ae0 20 7b 46 31 33 37 37 32 7d 20 20 41 66 74 65 72   {F13772}  After
25af0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
25b00 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 20  )] has returned 
25b10 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20  any value other 
25b20 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  than.**         
25b30 20 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f    [SQLITE_ROW] o
25b40 72 20 62 65 66 6f 72 65 20 5b 73 71 6c 69 74 65  r before [sqlite
25b50 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20 62  3_step(S)] has b
25b60 65 65 6e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  een .**         
25b70 20 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20    called on the 
25b80 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
25b90 65 6e 74 5d 20 66 6f 72 0a 2a 2a 20 20 20 20 20  ent] for.**     
25ba0 20 20 20 20 20 20 74 68 65 20 66 69 72 73 74 20        the first 
25bb0 74 69 6d 65 20 73 69 6e 63 65 20 69 74 20 77 61  time since it wa
25bc0 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  s [sqlite3_prepa
25bd0 72 65 7c 70 72 65 70 61 72 65 64 5d 0a 2a 2a 20  re|prepared].** 
25be0 20 20 20 20 20 20 20 20 20 20 6f 72 20 5b 73 71            or [sq
25bf0 6c 69 74 65 33 5f 72 65 73 65 74 7c 72 65 73 65  lite3_reset|rese
25c00 74 5d 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33  t], the [sqlite3
25c10 5f 64 61 74 61 5f 63 6f 75 6e 74 28 53 29 5d 0a  _data_count(S)].
25c20 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72 6f 75  **           rou
25c30 74 69 6e 65 20 72 65 74 75 72 6e 73 20 7a 65 72  tine returns zer
25c40 6f 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  o..*/.int sqlite
25c50 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c  3_data_count(sql
25c60 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
25c70 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
25c80 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20  EF: Fundamental 
25c90 44 61 74 61 74 79 70 65 73 20 7b 46 31 30 32 36  Datatypes {F1026
25ca0 35 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  5}.** KEYWORDS: 
25cb0 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a  SQLITE_TEXT.**.*
25cc0 2a 20 7b 46 31 30 32 36 36 7d 45 76 65 72 79 20  * {F10266}Every 
25cd0 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20  value in SQLite 
25ce0 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20  has one of five 
25cf0 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61  fundamental data
25d00 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  types:.**.** <ul
25d10 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74  >.** <li> 64-bit
25d20 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a   signed integer.
25d30 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49  ** <li> 64-bit I
25d40 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  EEE floating poi
25d50 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69  nt number.** <li
25d60 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e  > string.** <li>
25d70 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55   BLOB.** <li> NU
25d80 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 20 7b 45 4e 44  LL.** </ul> {END
25d90 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  }.**.** These co
25da0 6e 73 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65  nstants are code
25db0 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68  s for each of th
25dc0 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a  ose types..**.**
25dd0 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 53   Note that the S
25de0 51 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74  QLITE_TEXT const
25df0 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65  ant was also use
25e00 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73  d in SQLite vers
25e10 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63  ion 2.** for a c
25e20 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72  ompletely differ
25e30 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f  ent meaning.  So
25e40 66 74 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b  ftware that link
25e50 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a  s against both.*
25e60 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  * SQLite version
25e70 20 32 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65   2 and SQLite ve
25e80 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75  rsion 3 should u
25e90 73 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20  se SQLITE3_TEXT 
25ea0 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45  not.** SQLITE_TE
25eb0 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  XT..*/.#define S
25ec0 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20 31  QLITE_INTEGER  1
25ed0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
25ee0 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66 69  FLOAT    2.#defi
25ef0 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20  ne SQLITE_BLOB  
25f00 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c     4.#define SQL
25f10 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23  ITE_NULL     5.#
25f20 69 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58  ifdef SQLITE_TEX
25f30 54 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45  T.# undef SQLITE
25f40 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64 65  _TEXT.#else.# de
25f50 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 54  fine SQLITE_TEXT
25f60 20 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23 64       3.#endif.#d
25f70 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 45  efine SQLITE3_TE
25f80 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20  XT     3../*.** 
25f90 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74  CAPI3REF: Result
25fa0 73 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20  s Values From A 
25fb0 51 75 65 72 79 20 7b 46 31 33 38 30 30 7d 0a 2a  Query {F13800}.*
25fc0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
25fd0 6e 65 73 20 66 6f 72 6d 20 74 68 65 20 22 72 65  nes form the "re
25fe0 73 75 6c 74 20 73 65 74 20 71 75 65 72 79 22 20  sult set query" 
25ff0 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
26000 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
26010 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69  return informati
26020 6f 6e 20 61 62 6f 75 74 0a 2a 2a 20 61 20 73 69  on about.** a si
26030 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  ngle column of t
26040 68 65 20 63 75 72 72 65 6e 74 20 72 65 73 75 6c  he current resul
26050 74 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79  t row of a query
26060 2e 20 20 49 6e 20 65 76 65 72 79 0a 2a 2a 20 63  .  In every.** c
26070 61 73 65 20 74 68 65 20 66 69 72 73 74 20 61 72  ase the first ar
26080 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e  gument is a poin
26090 74 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20 5b  ter to the .** [
260a0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
260b0 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65 69 6e  nt] that is bein
260c0 67 0a 2a 2a 20 65 76 61 6c 75 61 74 65 64 20 28  g.** evaluated (
260d0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  the [sqlite3_stm
260e0 74 2a 5d 20 74 68 61 74 20 77 61 73 20 72 65 74  t*] that was ret
260f0 75 72 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b  urned from .** [
26100 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
26110 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20  v2()] or one of 
26120 69 74 73 20 76 61 72 69 61 6e 74 73 29 20 61 6e  its variants) an
26130 64 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20  d.** the second 
26140 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
26150 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c  index of the col
26160 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e  umn for which in
26170 66 6f 72 6d 61 74 69 6f 6e 20 0a 2a 2a 20 73 68  formation .** sh
26180 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64  ould be returned
26190 2e 20 20 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74  .  The left-most
261a0 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72   column of the r
261b0 65 73 75 6c 74 20 73 65 74 0a 2a 2a 20 68 61 73  esult set.** has
261c0 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 30 2e 0a   an index of 0..
261d0 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c  **.** If the SQL
261e0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f   statement is no
261f0 74 20 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e  t currently poin
26200 74 20 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77  t to a valid row
26210 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 74  , or if the.** t
26220 68 65 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20  he column index 
26230 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c  is out of range,
26240 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 75   the result is u
26250 6e 64 65 66 69 6e 65 64 2e 20 0a 2a 2a 20 54 68  ndefined. .** Th
26260 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79  ese routines may
26270 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20   only be called 
26280 77 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65  when the most re
26290 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  cent call to.** 
262a0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
262b0 20 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53   has returned [S
262c0 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e  QLITE_ROW] and n
262d0 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74  either.** [sqlit
262e0 65 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20  e3_reset()] nor 
262f0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
26300 65 28 29 5d 20 68 61 73 20 62 65 65 6e 20 63 61  e()] has been ca
26310 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e  ll subsequently.
26320 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 68  .** If any of th
26330 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
26340 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73   called after [s
26350 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
26360 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  or.** [sqlite3_f
26370 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66  inalize()] or af
26380 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ter [sqlite3_ste
26390 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65  p()] has returne
263a0 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f  d.** something o
263b0 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
263c0 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 75  E_ROW], the resu
263d0 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
263e0 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65  d..** If [sqlite
263f0 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71  3_step()] or [sq
26400 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
26410 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  r [sqlite3_final
26420 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61  ize()].** are ca
26430 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64 69 66 66  lled from a diff
26440 65 72 65 6e 74 20 74 68 72 65 61 64 20 77 68 69  erent thread whi
26450 6c 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20  le any of these 
26460 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20  routines.** are 
26470 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 68  pending, then th
26480 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
26490 64 65 66 69 6e 65 64 2e 20 20 0a 2a 2a 0a 2a 2a  defined.  .**.**
264a0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c   The sqlite3_col
264b0 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 74 69  umn_type() routi
264c0 6e 65 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 5b  ne returns .** [
264d0 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c  SQLITE_INTEGER |
264e0 20 64 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20   datatype code] 
264f0 66 6f 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20  for the initial 
26500 64 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20  data type.** of 
26510 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  the result colum
26520 6e 2e 20 20 54 68 65 20 72 65 74 75 72 6e 65 64  n.  The returned
26530 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66   value is one of
26540 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52   [SQLITE_INTEGER
26550 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c  ],.** [SQLITE_FL
26560 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45  OAT], [SQLITE_TE
26570 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f  XT], [SQLITE_BLO
26580 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e  B], or [SQLITE_N
26590 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75 65  ULL].  The value
265a0 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20  .** returned by 
265b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
265c0 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65  ype() is only me
265d0 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74  aningful if no t
265e0 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f  ype.** conversio
265f0 6e 73 20 68 61 76 65 20 6f 63 63 75 72 72 65 64  ns have occurred
26600 20 61 73 20 64 65 73 63 72 69 62 65 64 20 62 65   as described be
26610 6c 6f 77 2e 20 20 41 66 74 65 72 20 61 20 74 79  low.  After a ty
26620 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a  pe conversion,.*
26630 2a 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  * the value retu
26640 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
26650 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73  column_type() is
26660 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 46 75 74   undefined.  Fut
26670 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20  ure.** versions 
26680 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63 68  of SQLite may ch
26690 61 6e 67 65 20 74 68 65 20 62 65 68 61 76 69 6f  ange the behavio
266a0 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r of sqlite3_col
266b0 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f  umn_type().** fo
266c0 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20 63  llowing a type c
266d0 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  onversion..**.**
266e0 20 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69   If the result i
266f0 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d  s a BLOB or UTF-
26700 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68  8 string then th
26710 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
26720 5f 62 79 74 65 73 28 29 20 0a 2a 2a 20 72 6f 75  _bytes() .** rou
26730 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
26740 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
26750 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72   in that BLOB or
26760 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 49 66 20 74   string..** If t
26770 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55  he result is a U
26780 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68  TF-16 string, th
26790 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
267a0 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72  n_bytes() conver
267b0 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67  ts.** the string
267c0 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68   to UTF-8 and th
267d0 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  en returns the n
267e0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a  umber of bytes..
267f0 2a 2a 20 49 66 20 74 68 65 20 72 65 73 75 6c 74  ** If the result
26800 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61   is a numeric va
26810 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33  lue then sqlite3
26820 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
26830 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  uses.** [sqlite3
26840 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20  _snprintf()] to 
26850 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c  convert that val
26860 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73 74  ue to a UTF-8 st
26870 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73  ring and returns
26880 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
26890 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20  f bytes in that 
268a0 73 74 72 69 6e 67 2e 0a 2a 2a 20 54 68 65 20 76  string..** The v
268b0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 64 6f  alue returned do
268c0 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74  es not include t
268d0 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  he zero terminat
268e0 6f 72 20 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a  or at the end.**
268f0 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 2e 20   of the string. 
26900 20 46 6f 72 20 63 6c 61 72 69 74 79 3a 20 74 68   For clarity: th
26910 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
26920 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
26930 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68  f.** bytes in th
26940 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68  e string, not th
26950 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72  e number of char
26960 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 53 74  acters..**.** St
26970 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62  rings returned b
26980 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
26990 5f 74 65 78 74 28 29 20 61 6e 64 20 73 71 6c 69  _text() and sqli
269a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
269b0 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70  6(),.** even emp
269c0 74 79 20 73 74 72 69 6e 67 73 2c 20 61 72 65 20  ty strings, are 
269d0 61 6c 77 61 79 73 20 7a 65 72 6f 20 74 65 72 6d  always zero term
269e0 69 6e 61 74 65 64 2e 20 20 54 68 65 20 72 65 74  inated.  The ret
269f0 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f  urn.** value fro
26a00 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  m sqlite3_column
26a10 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a 65  _blob() for a ze
26a20 72 6f 2d 6c 65 6e 67 74 68 20 62 6c 6f 62 20 69  ro-length blob i
26a30 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 0a 2a  s an arbitrary.*
26a40 2a 20 70 6f 69 6e 74 65 72 2c 20 70 6f 73 73 69  * pointer, possi
26a50 62 6c 79 20 65 76 65 6e 20 61 20 4e 55 4c 4c 20  bly even a NULL 
26a60 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54  pointer..**.** T
26a70 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
26a80 6e 5f 62 79 74 65 73 31 36 28 29 20 72 6f 75 74  n_bytes16() rout
26a90 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74  ine is similar t
26aa0 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
26ab0 5f 62 79 74 65 73 28 29 0a 2a 2a 20 62 75 74 20  _bytes().** but 
26ac0 6c 65 61 76 65 73 20 74 68 65 20 72 65 73 75 6c  leaves the resul
26ad0 74 20 69 6e 20 55 54 46 2d 31 36 20 69 6e 20 6e  t in UTF-16 in n
26ae0 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
26af0 20 69 6e 73 74 65 61 64 20 6f 66 20 55 54 46 2d   instead of UTF-
26b00 38 2e 20 20 0a 2a 2a 20 54 68 65 20 7a 65 72 6f  8.  .** The zero
26b10 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 73 20 6e   terminator is n
26b20 6f 74 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74  ot included in t
26b30 68 69 73 20 63 6f 75 6e 74 2e 0a 2a 2a 0a 2a 2a  his count..**.**
26b40 20 54 68 65 20 6f 62 6a 65 63 74 20 72 65 74 75   The object retu
26b50 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
26b60 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d  _column_value()]
26b70 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f   is an.** [unpro
26b80 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
26b90 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 41  alue] object.  A
26ba0 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71  n unprotected sq
26bb0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
26bc0 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62  ct.** may only b
26bd0 65 20 75 73 65 64 20 77 69 74 68 20 5b 73 71 6c  e used with [sql
26be0 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28  ite3_bind_value(
26bf0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
26c00 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e  result_value()].
26c10 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e 70 72  .** If the [unpr
26c20 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
26c30 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72 65  value] object re
26c40 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71  turned by.** [sq
26c50 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
26c60 75 65 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e  ue()] is used in
26c70 20 61 6e 79 20 6f 74 68 65 72 20 77 61 79 2c 20   any other way, 
26c80 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a  including calls.
26c90 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c  ** to routines l
26ca0 69 6b 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ike .** [sqlite3
26cb0 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b  _value_int()], [
26cc0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
26cd0 78 74 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74  xt()], or [sqlit
26ce0 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29  e3_value_bytes()
26cf0 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62  ],.** then the b
26d00 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
26d10 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ined..**.** Thes
26d20 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d  e routines attem
26d30 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  pt to convert th
26d40 65 20 76 61 6c 75 65 20 77 68 65 72 65 20 61 70  e value where ap
26d50 70 72 6f 70 72 69 61 74 65 2e 20 20 46 6f 72 0a  propriate.  For.
26d60 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74  ** example, if t
26d70 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72  he internal repr
26d80 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c  esentation is FL
26d90 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74 20 72  OAT and a text r
26da0 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75  esult.** is requ
26db0 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f  ested, [sqlite3_
26dc0 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75  snprintf()] is u
26dd0 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74  sed internally t
26de0 6f 20 64 6f 20 74 68 65 20 63 6f 6e 76 65 72 73  o do the convers
26df0 69 6f 6e 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63  ion.** automatic
26e00 61 6c 6c 79 2e 20 20 54 68 65 20 66 6f 6c 6c 6f  ally.  The follo
26e10 77 69 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69  wing table detai
26e20 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f  ls the conversio
26e30 6e 73 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 61  ns that.** are a
26e40 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62  pplied:.**.** <b
26e50 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74  lockquote>.** <t
26e60 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e  able border="1">
26e70 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74  .** <tr><th> Int
26e80 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74  ernal<br>Type <t
26e90 68 3e 20 52 65 71 75 65 73 74 65 64 3c 62 72 3e  h> Requested<br>
26ea0 54 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65  Type <th>  Conve
26eb0 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e  rsion.**.** <tr>
26ec0 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74  <td>  NULL    <t
26ed0 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
26ee0 3e 20 52 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a  > Result is 0.**
26ef0 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
26f00 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20     <td>  FLOAT  
26f10 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
26f20 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e   0.0.** <tr><td>
26f30 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20    NULL    <td>  
26f40 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 52 65   TEXT    <td> Re
26f50 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69  sult is NULL poi
26f60 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  nter.** <tr><td>
26f70 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20    NULL    <td>  
26f80 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52 65   BLOB    <td> Re
26f90 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69  sult is NULL poi
26fa0 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  nter.** <tr><td>
26fb0 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20   INTEGER  <td>  
26fc0 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f  FLOAT    <td> Co
26fd0 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74 65 67  nvert from integ
26fe0 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c  er to float.** <
26ff0 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20  tr><td> INTEGER 
27000 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
27010 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65  <td> ASCII rende
27020 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e 74 65  ring of the inte
27030 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ger.** <tr><td> 
27040 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20  INTEGER  <td>   
27050 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d  BLOB    <td> Sam
27060 65 20 61 73 20 66 6f 72 20 49 4e 54 45 47 45 52  e as for INTEGER
27070 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74  ->TEXT.** <tr><t
27080 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e  d>  FLOAT   <td>
27090 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20   INTEGER   <td> 
270a0 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 66 6c 6f  Convert from flo
270b0 61 74 20 74 6f 20 69 6e 74 65 67 65 72 0a 2a 2a  at to integer.**
270c0 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54   <tr><td>  FLOAT
270d0 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20     <td>   TEXT  
270e0 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e    <td> ASCII ren
270f0 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c  dering of the fl
27100 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  oat.** <tr><td> 
27110 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20   FLOAT   <td>   
27120 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d  BLOB    <td> Sam
27130 65 20 61 73 20 46 4c 4f 41 54 2d 3e 54 45 58 54  e as FLOAT->TEXT
27140 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45  .** <tr><td>  TE
27150 58 54 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  XT    <td> INTEG
27160 45 52 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74  ER   <td> Use at
27170 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  oi().** <tr><td>
27180 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20    TEXT    <td>  
27190 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 55 73  FLOAT    <td> Us
271a0 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e  e atof().** <tr>
271b0 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74  <td>  TEXT    <t
271c0 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
271d0 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c  > No change.** <
271e0 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20  tr><td>  BLOB   
271f0 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
27200 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20  <td> Convert to 
27210 54 45 58 54 20 74 68 65 6e 20 75 73 65 20 61 74  TEXT then use at
27220 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  oi().** <tr><td>
27230 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20    BLOB    <td>  
27240 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f  FLOAT    <td> Co
27250 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20 74 68  nvert to TEXT th
27260 65 6e 20 75 73 65 20 61 74 6f 66 28 29 0a 2a 2a  en use atof().**
27270 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20   <tr><td>  BLOB 
27280 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20     <td>   TEXT  
27290 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 72    <td> Add a zer
272a0 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 20  o terminator if 
272b0 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c  needed.** </tabl
272c0 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f  e>.** </blockquo
272d0 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61  te>.**.** The ta
272e0 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b 65 73 20  ble above makes 
272f0 72 65 66 65 72 65 6e 63 65 20 74 6f 20 73 74 61  reference to sta
27300 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 20  ndard C library 
27310 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f 69 28 29  functions atoi()
27320 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28 29 2e 20  .** and atof(). 
27330 20 53 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74   SQLite does not
27340 20 72 65 61 6c 6c 79 20 75 73 65 20 74 68 65 73   really use thes
27350 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 49 74  e functions.  It
27360 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f 77 6e 20   has its.** own 
27370 65 71 75 69 76 61 6c 65 6e 74 20 69 6e 74 65 72  equivalent inter
27380 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e 20 20 54  nal routines.  T
27390 68 65 20 61 74 6f 69 28 29 20 61 6e 64 20 61 74  he atoi() and at
273a0 6f 66 28 29 20 6e 61 6d 65 73 20 61 72 65 0a 2a  of() names are.*
273b0 2a 20 75 73 65 64 20 69 6e 20 74 68 65 20 74 61  * used in the ta
273c0 62 6c 65 20 66 6f 72 20 62 72 65 76 69 74 79 20  ble for brevity 
273d0 61 6e 64 20 62 65 63 61 75 73 65 20 74 68 65 79  and because they
273e0 20 61 72 65 20 66 61 6d 69 6c 69 61 72 20 74 6f   are familiar to
273f0 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 6f 67 72   most.** C progr
27400 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f  ammers..**.** No
27410 74 65 20 74 68 61 74 20 77 68 65 6e 20 74 79 70  te that when typ
27420 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63  e conversions oc
27430 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 20 72 65  cur, pointers re
27440 74 75 72 6e 65 64 20 62 79 20 70 72 69 6f 72 0a  turned by prior.
27450 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ** calls to sqli
27460 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
27470 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ), sqlite3_colum
27480 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72  n_text(), and/or
27490 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
274a0 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d 61 79 20  mn_text16() may 
274b0 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 20  be invalidated. 
274c0 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65 72 73  .** Type convers
274d0 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65 72  ions and pointer
274e0 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d   invalidations m
274f0 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e  ight occur.** in
27500 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63   the following c
27510 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ases:.**.** <ul>
27520 0a 2a 2a 20 3c 6c 69 3e 3c 70 3e 20 20 54 68 65  .** <li><p>  The
27530 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74   initial content
27540 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73   is a BLOB and s
27550 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
27560 78 74 28 29 20 0a 2a 2a 20 20 20 20 20 20 20 20  xt() .**        
27570 20 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c    or sqlite3_col
27580 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20  umn_text16() is 
27590 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d  called.  A zero-
275a0 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74  terminator might
275b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 65 65  .**          nee
275c0 64 20 74 6f 20 62 65 20 61 64 64 65 64 20 74 6f  d to be added to
275d0 20 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f 70 3e   the string.</p>
275e0 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  </li>.**.** <li>
275f0 3c 70 3e 20 20 54 68 65 20 69 6e 69 74 69 61 6c  <p>  The initial
27600 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d   content is UTF-
27610 38 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74  8 text and sqlit
27620 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
27630 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20  6() or.**       
27640 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d     sqlite3_colum
27650 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61  n_text16() is ca
27660 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65  lled.  The conte
27670 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65  nt must be conve
27680 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  rted.**         
27690 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 70 3e 3c   to UTF-16.</p><
276a0 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 3c  /li>.**.** <li><
276b0 70 3e 20 20 54 68 65 20 69 6e 69 74 69 61 6c 20  p>  The initial 
276c0 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 31  content is UTF-1
276d0 36 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74  6 text and sqlit
276e0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
276f0 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  ) or.**         
27700 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
27710 74 65 78 74 28 29 20 69 73 20 63 61 6c 6c 65 64  text() is called
27720 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d  .  The content m
27730 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64  ust be converted
27740 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20  .**          to 
27750 55 54 46 2d 38 2e 3c 2f 70 3e 3c 2f 6c 69 3e 0a  UTF-8.</p></li>.
27760 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 43  ** </ul>.**.** C
27770 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65  onversions betwe
27780 65 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20  en UTF-16be and 
27790 55 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77  UTF-16le are alw
277a0 61 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63  ays done in plac
277b0 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20  e and do.** not 
277c0 69 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72 69  invalidate a pri
277d0 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75  or pointer, thou
277e0 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65  gh of course the
277f0 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
27800 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74  buffer.** that t
27810 68 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72  he prior pointer
27820 20 70 6f 69 6e 74 73 20 74 6f 20 77 69 6c 6c 20   points to will 
27830 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69  have been modifi
27840 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73  ed.  Other kinds
27850 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f  .** of conversio
27860 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c  n are done in pl
27870 61 63 65 20 77 68 65 6e 20 69 74 20 69 73 20 70  ace when it is p
27880 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d  ossible, but som
27890 65 74 69 6d 65 20 69 74 20 69 73 0a 2a 2a 20 6e  etime it is.** n
278a0 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e 64 20  ot possible and 
278b0 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73 20 70  in those cases p
278c0 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 61 72  rior pointers ar
278d0 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 20 20  e invalidated.  
278e0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 73  .**.** The safes
278f0 74 20 61 6e 64 20 65 61 73 69 65 73 74 20 74 6f  t and easiest to
27900 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79   remember policy
27910 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68   is to invoke th
27920 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20  ese routines.** 
27930 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f  in one of the fo
27940 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a  llowing ways:.**
27950 0a 2a 2a 20 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c  .**  <ul>.**  <l
27960 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  i>sqlite3_column
27970 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64  _text() followed
27980 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
27990 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a  mn_bytes()</li>.
279a0 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f  **  <li>sqlite3_
279b0 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f  column_blob() fo
279c0 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65  llowed by sqlite
279d0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
279e0 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71  </li>.**  <li>sq
279f0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
27a00 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62  t16() followed b
27a10 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
27a20 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a  _bytes16()</li>.
27a30 2a 2a 20 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  **  </ul>.**.** 
27a40 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
27a50 79 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20  you should call 
27a60 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
27a70 65 78 74 28 29 2c 20 73 71 6c 69 74 65 33 5f 63  ext(), sqlite3_c
27a80 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 0a 2a 2a  olumn_blob(),.**
27a90 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   or sqlite3_colu
27aa0 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 69 72 73  mn_text16() firs
27ab0 74 20 74 6f 20 66 6f 72 63 65 20 74 68 65 20 72  t to force the r
27ac0 65 73 75 6c 74 20 69 6e 74 6f 20 74 68 65 20 64  esult into the d
27ad0 65 73 69 72 65 64 0a 2a 2a 20 66 6f 72 6d 61 74  esired.** format
27ae0 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71  , then invoke sq
27af0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
27b00 65 73 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  es() or sqlite3_
27b10 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
27b20 20 74 6f 0a 2a 2a 20 66 69 6e 64 20 74 68 65 20   to.** find the 
27b30 73 69 7a 65 20 6f 66 20 74 68 65 20 72 65 73 75  size of the resu
27b40 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20  lt.  Do not mix 
27b50 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
27b60 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72  column_text() or
27b70 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
27b80 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63  mn_blob() with c
27b90 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
27ba0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
27bb0 2e 20 20 41 6e 64 20 64 6f 20 6e 6f 74 0a 2a 2a  .  And do not.**
27bc0 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20 73 71   mix calls to sq
27bd0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
27be0 74 31 36 28 29 20 77 69 74 68 20 63 61 6c 6c 73  t16() with calls
27bf0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
27c00 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a  mn_bytes()..**.*
27c10 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 73 20 72  * The pointers r
27c20 65 74 75 72 6e 65 64 20 61 72 65 20 76 61 6c 69  eturned are vali
27c30 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65 20 63  d until a type c
27c40 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73  onversion occurs
27c50 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 64   as.** described
27c60 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c   above, or until
27c70 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
27c80 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
27c90 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  set()] or.** [sq
27ca0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
27cb0 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68  ] is called.  Th
27cc0 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75  e memory space u
27cd0 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69  sed to hold stri
27ce0 6e 67 73 0a 2a 2a 20 61 6e 64 20 62 6c 6f 62 73  ngs.** and blobs
27cf0 20 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61   is freed automa
27d00 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e  tically.  Do <b>
27d10 6e 6f 74 3c 2f 62 3e 20 70 61 73 73 20 74 68 65  not</b> pass the
27d20 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e   pointers return
27d30 65 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  ed.** [sqlite3_c
27d40 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b  olumn_blob()], [
27d50 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
27d60 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74  ext()], etc. int
27d70 6f 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  o .** [sqlite3_f
27d80 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  ree()]..**.** If
27d90 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
27da0 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  tion error occur
27db0 73 20 64 75 72 69 6e 67 20 74 68 65 20 65 76 61  s during the eva
27dc0 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a  luation of any.*
27dd0 2a 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  * of these routi
27de0 6e 65 73 2c 20 61 20 64 65 66 61 75 6c 74 20 76  nes, a default v
27df0 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 64  alue is returned
27e00 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 76  .  The default v
27e10 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 65  alue.** is eithe
27e20 72 20 74 68 65 20 69 6e 74 65 67 65 72 20 30 2c  r the integer 0,
27e30 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f   the floating po
27e40 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20  int number 0.0, 
27e50 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69  or a NULL.** poi
27e60 6e 74 65 72 2e 20 20 53 75 62 73 65 71 75 65 6e  nter.  Subsequen
27e70 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  t calls to [sqli
27e80 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 77  te3_errcode()] w
27e90 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53  ill return.** [S
27ea0 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a  QLITE_NOMEM]..**
27eb0 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
27ec0 2a 2a 0a 2a 2a 20 7b 46 31 33 38 30 33 7d 20 54  **.** {F13803} T
27ed0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
27ee0 6d 6e 5f 62 6c 6f 62 28 53 2c 4e 29 5d 20 69 6e  mn_blob(S,N)] in
27ef0 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73  terface converts
27f00 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
27f10 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74   Nth column in t
27f20 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f  he current row o
27f30 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
27f40 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20   for.**         
27f50 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
27f60 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20 62  ment] S into a b
27f70 6c 6f 62 20 61 6e 64 20 74 68 65 6e 20 72 65 74  lob and then ret
27f80 75 72 6e 73 20 61 0a 2a 2a 20 20 20 20 20 20 20  urns a.**       
27f90 20 20 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68     pointer to th
27fa0 65 20 63 6f 6e 76 65 72 74 65 64 20 76 61 6c 75  e converted valu
27fb0 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 30 36  e..**.** {F13806
27fc0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
27fd0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 53 2c 4e 29  olumn_bytes(S,N)
27fe0 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
27ff0 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  rns the.**      
28000 20 20 20 20 6e 75 6d 62 65 72 20 6f 66 20 62 79      number of by
28010 74 65 73 20 69 6e 20 74 68 65 20 62 6c 6f 62 20  tes in the blob 
28020 6f 72 20 73 74 72 69 6e 67 20 28 65 78 63 6c 75  or string (exclu
28030 73 69 76 65 20 6f 66 20 74 68 65 0a 2a 2a 20 20  sive of the.**  
28040 20 20 20 20 20 20 20 20 7a 65 72 6f 20 74 65 72          zero ter
28050 6d 69 6e 61 74 6f 72 20 6f 6e 20 74 68 65 20 73  minator on the s
28060 74 72 69 6e 67 29 20 74 68 61 74 20 77 61 73 20  tring) that was 
28070 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a  returned by the.
28080 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 6f 73 74  **          most
28090 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20   recent call to 
280a0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
280b0 62 6c 6f 62 28 53 2c 4e 29 5d 20 6f 72 0a 2a 2a  blob(S,N)] or.**
280c0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
280d0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 53  e3_column_text(S
280e0 2c 4e 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  ,N)]..**.** {F13
280f0 38 30 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  809} The [sqlite
28100 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
28110 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  (S,N)] interface
28120 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20   returns the.** 
28130 20 20 20 20 20 20 20 20 20 6e 75 6d 62 65 72 20           number 
28140 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  of bytes in the 
28150 73 74 72 69 6e 67 20 28 65 78 63 6c 75 73 69 76  string (exclusiv
28160 65 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20  e of the.**     
28170 20 20 20 20 20 7a 65 72 6f 20 74 65 72 6d 69 6e       zero termin
28180 61 74 6f 72 20 6f 6e 20 74 68 65 20 73 74 72 69  ator on the stri
28190 6e 67 29 20 74 68 61 74 20 77 61 73 20 72 65 74  ng) that was ret
281a0 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20  urned by the.** 
281b0 20 20 20 20 20 20 20 20 20 6d 6f 73 74 20 72 65           most re
281c0 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  cent call to [sq
281d0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
281e0 74 31 36 28 53 2c 4e 29 5d 2e 0a 2a 2a 0a 2a 2a  t16(S,N)]..**.**
281f0 20 7b 46 31 33 38 31 32 7d 20 54 68 65 20 5b 73   {F13812} The [s
28200 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f  qlite3_column_do
28210 75 62 6c 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72  uble(S,N)] inter
28220 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68  face converts th
28230 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74  e.**          Nt
28240 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20  h column in the 
28250 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74  current row of t
28260 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f  he result set fo
28270 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  r.**          [p
28280 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
28290 74 5d 20 53 20 69 6e 74 6f 20 61 20 66 6c 6f 61  t] S into a floa
282a0 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65  ting point value
282b0 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20   and.**         
282c0 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20   returns a copy 
282d0 6f 66 20 74 68 61 74 20 76 61 6c 75 65 2e 0a 2a  of that value..*
282e0 2a 0a 2a 2a 20 7b 46 31 33 38 31 35 7d 20 54 68  *.** {F13815} Th
282f0 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
28300 6e 5f 69 6e 74 28 53 2c 4e 29 5d 20 69 6e 74 65  n_int(S,N)] inte
28310 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74  rface converts t
28320 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e  he.**          N
28330 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65  th column in the
28340 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20   current row of 
28350 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 66  the result set f
28360 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  or.**          [
28370 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
28380 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20 36 34 2d  nt] S into a 64-
28390 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
283a0 65 72 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20  er and.**       
283b0 20 20 20 72 65 74 75 72 6e 73 20 74 68 65 20 6c     returns the l
283c0 6f 77 65 72 20 33 32 20 62 69 74 73 20 6f 66 20  ower 32 bits of 
283d0 74 68 61 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a  that integer..**
283e0 0a 2a 2a 20 7b 46 31 33 38 31 38 7d 20 54 68 65  .** {F13818} The
283f0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
28400 5f 69 6e 74 36 34 28 53 2c 4e 29 5d 20 69 6e 74  _int64(S,N)] int
28410 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20  erface converts 
28420 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
28430 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68  Nth column in th
28440 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66  e current row of
28450 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
28460 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  for.**          
28470 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
28480 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20 36 34  ent] S into a 64
28490 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
284a0 67 65 72 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20  ger and.**      
284b0 20 20 20 20 72 65 74 75 72 6e 73 20 61 20 63 6f      returns a co
284c0 70 79 20 6f 66 20 74 68 61 74 20 69 6e 74 65 67  py of that integ
284d0 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 32  er..**.** {F1382
284e0 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
284f0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 53 2c 4e 29  column_text(S,N)
28500 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76  ] interface conv
28510 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  erts the.**     
28520 20 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20       Nth column 
28530 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72  in the current r
28540 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ow of the result
28550 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20   set for.**     
28560 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73       [prepared s
28570 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f  tatement] S into
28580 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
28590 65 64 20 55 54 46 2d 38 20 0a 2a 2a 20 20 20 20  ed UTF-8 .**    
285a0 20 20 20 20 20 20 73 74 72 69 6e 67 20 61 6e 64        string and
285b0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
285c0 65 72 20 74 6f 20 74 68 61 74 20 73 74 72 69 6e  er to that strin
285d0 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 32 34  g..**.** {F13824
285e0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
285f0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 53 2c 4e  olumn_text16(S,N
28600 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e  )] interface con
28610 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20  verts the.**    
28620 20 20 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e        Nth column
28630 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20   in the current 
28640 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c  row of the resul
28650 74 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20  t set for.**    
28660 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20        [prepared 
28670 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74  statement] S int
28680 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  o a zero-termina
28690 74 65 64 20 32 2d 62 79 74 65 0a 2a 2a 20 20 20  ted 2-byte.**   
286a0 20 20 20 20 20 20 20 61 6c 69 67 6e 65 64 20 55         aligned U
286b0 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74  TF-16 native byt
286c0 65 20 6f 72 64 65 72 0a 2a 2a 20 20 20 20 20 20  e order.**      
286d0 20 20 20 20 73 74 72 69 6e 67 20 61 6e 64 20 72      string and r
286e0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
286f0 20 74 6f 20 74 68 61 74 20 73 74 72 69 6e 67 2e   to that string.
28700 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 32 37 7d 20  .**.** {F13827} 
28710 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  The [sqlite3_col
28720 75 6d 6e 5f 74 79 70 65 28 53 2c 4e 29 5d 20 69  umn_type(S,N)] i
28730 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
28740 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 6e 65  .**          one
28750 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c   of [SQLITE_NULL
28760 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47  ], [SQLITE_INTEG
28770 45 52 5d 2c 20 5b 53 51 4c 49 54 45 5f 46 4c 4f  ER], [SQLITE_FLO
28780 41 54 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  AT],.**         
28790 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20   [SQLITE_TEXT], 
287a0 6f 72 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d  or [SQLITE_BLOB]
287b0 20 61 73 20 61 70 70 72 6f 70 72 69 61 74 65 20   as appropriate 
287c0 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  for.**          
287d0 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69  the Nth column i
287e0 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f  n the current ro
287f0 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  w of the result 
28800 73 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20  set for.**      
28810 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74      [prepared st
28820 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a  atement] S..**.*
28830 2a 20 7b 46 31 33 38 33 30 7d 20 54 68 65 20 5b  * {F13830} The [
28840 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
28850 61 6c 75 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72  alue(S,N)] inter
28860 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 0a 2a  face returns a.*
28870 2a 20 20 20 20 20 20 20 20 20 20 70 6f 69 6e 74  *          point
28880 65 72 20 74 6f 20 61 6e 20 5b 75 6e 70 72 6f 74  er to an [unprot
28890 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
288a0 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72 20  lue] object for 
288b0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
288c0 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68  Nth column in th
288d0 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66  e current row of
288e0 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
288f0 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  for.**          
28900 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
28910 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 63 6f 6e 73 74  ent] S..*/.const
28920 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
28930 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74  olumn_blob(sqlit
28940 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
28950 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ol);.int sqlite3
28960 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71  _column_bytes(sq
28970 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
28980 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69   iCol);.int sqli
28990 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
289a0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
289b0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75  , int iCol);.dou
289c0 62 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ble sqlite3_colu
289d0 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65  mn_double(sqlite
289e0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
289f0 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
28a00 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74  column_int(sqlit
28a10 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
28a20 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74  ol);.sqlite3_int
28a30 36 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  64 sqlite3_colum
28a40 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  n_int64(sqlite3_
28a50 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
28a60 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64  ;.const unsigned
28a70 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
28a80 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74  olumn_text(sqlit
28a90 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
28aa0 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  ol);.const void 
28ab0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
28ac0 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73  text16(sqlite3_s
28ad0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
28ae0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
28af0 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33  umn_type(sqlite3
28b00 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
28b10 29 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  );.sqlite3_value
28b20 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
28b30 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73  _value(sqlite3_s
28b40 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
28b50 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
28b60 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72 65 70  : Destroy A Prep
28b70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f  ared Statement O
28b80 62 6a 65 63 74 20 7b 46 31 33 33 30 30 7d 0a 2a  bject {F13300}.*
28b90 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
28ba0 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63  _finalize() func
28bb0 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74  tion is called t
28bc0 6f 20 64 65 6c 65 74 65 20 61 20 0a 2a 2a 20 5b  o delete a .** [
28bd0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
28be0 6e 74 5d 2e 20 49 66 20 74 68 65 20 73 74 61 74  nt]. If the stat
28bf0 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 65 78 65  ement was.** exe
28c00 63 75 74 65 64 20 73 75 63 63 65 73 73 66 75 6c  cuted successful
28c10 6c 79 2c 20 6f 72 20 6e 6f 74 20 65 78 65 63 75  ly, or not execu
28c20 74 65 64 20 61 74 20 61 6c 6c 2c 20 74 68 65 6e  ted at all, then
28c30 20 53 51 4c 49 54 45 5f 4f 4b 20 69 73 20 72 65   SQLITE_OK is re
28c40 74 75 72 6e 65 64 2e 0a 2a 2a 20 49 66 20 65 78  turned..** If ex
28c50 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 20 73  ecution of the s
28c60 74 61 74 65 6d 65 6e 74 20 66 61 69 6c 65 64 20  tatement failed 
28c70 74 68 65 6e 20 61 6e 20 0a 2a 2a 20 5b 65 72 72  then an .** [err
28c80 6f 72 20 63 6f 64 65 5d 20 6f 72 20 5b 65 78 74  or code] or [ext
28c90 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65  ended error code
28ca0 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64  ].** is returned
28cb0 2e 20 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  . .**.** This ro
28cc0 75 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61 6c  utine can be cal
28cd0 6c 65 64 20 61 74 20 61 6e 79 20 70 6f 69 6e 74  led at any point
28ce0 20 64 75 72 69 6e 67 20 74 68 65 20 65 78 65 63   during the exec
28cf0 75 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20  ution of the.** 
28d00 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
28d10 65 6e 74 5d 2e 20 20 49 66 20 74 68 65 20 76 69  ent].  If the vi
28d20 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 68 61  rtual machine ha
28d30 73 20 6e 6f 74 20 0a 2a 2a 20 63 6f 6d 70 6c 65  s not .** comple
28d40 74 65 64 20 65 78 65 63 75 74 69 6f 6e 20 77 68  ted execution wh
28d50 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  en this routine 
28d60 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 61 74 20  is called, that 
28d70 69 73 20 6c 69 6b 65 0a 2a 2a 20 65 6e 63 6f 75  is like.** encou
28d80 6e 74 65 72 69 6e 67 20 61 6e 20 65 72 72 6f 72  ntering an error
28d90 20 6f 72 20 61 6e 20 69 6e 74 65 72 72 75 70 74   or an interrupt
28da0 2e 20 20 28 53 65 65 20 5b 73 71 6c 69 74 65 33  .  (See [sqlite3
28db0 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 2e 29 20  _interrupt()].) 
28dc0 0a 2a 2a 20 49 6e 63 6f 6d 70 6c 65 74 65 20 75  .** Incomplete u
28dd0 70 64 61 74 65 73 20 6d 61 79 20 62 65 20 72 6f  pdates may be ro
28de0 6c 6c 65 64 20 62 61 63 6b 20 61 6e 64 20 74 72  lled back and tr
28df0 61 6e 73 61 63 74 69 6f 6e 73 20 63 61 6e 63 65  ansactions cance
28e00 6c 65 64 2c 20 20 0a 2a 2a 20 64 65 70 65 6e 64  led,  .** depend
28e10 69 6e 67 20 6f 6e 20 74 68 65 20 63 69 72 63 75  ing on the circu
28e20 6d 73 74 61 6e 63 65 73 2c 20 61 6e 64 20 74 68  mstances, and th
28e30 65 20 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64  e .** [error cod
28e40 65 5d 20 72 65 74 75 72 6e 65 64 20 77 69 6c 6c  e] returned will
28e50 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52   be [SQLITE_ABOR
28e60 54 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  T]..**.** INVARI
28e70 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 31  ANTS:.**.** {F11
28e80 33 30 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  302} The [sqlite
28e90 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 5d 20 69  3_finalize(S)] i
28ea0 6e 74 65 72 66 61 63 65 20 64 65 73 74 72 6f 79  nterface destroy
28eb0 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
28ec0 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74    [prepared stat
28ed0 65 6d 65 6e 74 5d 20 53 20 61 6e 64 20 72 65 6c  ement] S and rel
28ee0 65 61 73 65 73 20 61 6c 6c 0a 2a 2a 20 20 20 20  eases all.**    
28ef0 20 20 20 20 20 20 6d 65 6d 6f 72 79 20 61 6e 64        memory and
28f00 20 66 69 6c 65 20 72 65 73 6f 75 72 63 65 73 20   file resources 
28f10 68 65 6c 64 20 62 79 20 74 68 61 74 20 6f 62 6a  held by that obj
28f20 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 33  ect..**.** {F113
28f30 30 34 7d 20 49 66 20 74 68 65 20 6d 6f 73 74 20  04} If the most 
28f40 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b  recent call to [
28f50 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
28f60 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20   for the.**     
28f70 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73       [prepared s
28f80 74 61 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 75  tatement] S retu
28f90 72 6e 65 64 20 61 6e 20 65 72 72 6f 72 2c 0a 2a  rned an error,.*
28fa0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20  *          then 
28fb0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
28fc0 65 28 53 29 5d 20 72 65 74 75 72 6e 73 20 74 68  e(S)] returns th
28fd0 61 74 20 73 61 6d 65 20 65 72 72 6f 72 2e 0a 2a  at same error..*
28fe0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69  /.int sqlite3_fi
28ff0 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f 73  nalize(sqlite3_s
29000 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
29010 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
29020 73 65 74 20 41 20 50 72 65 70 61 72 65 64 20 53  set A Prepared S
29030 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 20  tatement Object 
29040 7b 46 31 33 33 33 30 7d 0a 2a 2a 0a 2a 2a 20 54  {F13330}.**.** T
29050 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74  he sqlite3_reset
29060 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63  () function is c
29070 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61  alled to reset a
29080 20 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73   .** [prepared s
29090 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74  tatement] object
290a0 2e 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 69 74 73  ..** back to its
290b0 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20   initial state, 
290c0 72 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65  ready to be re-e
290d0 78 65 63 75 74 65 64 2e 0a 2a 2a 20 41 6e 79 20  xecuted..** Any 
290e0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61  SQL statement va
290f0 72 69 61 62 6c 65 73 20 74 68 61 74 20 68 61 64  riables that had
29100 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f   values bound to
29110 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74   them using.** t
29120 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  he [sqlite3_bind
29130 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f  _blob | sqlite3_
29140 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65  bind_*() API] re
29150 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65  tain their value
29160 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74  s..** Use [sqlit
29170 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67  e3_clear_binding
29180 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68  s()] to reset th
29190 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a  e bindings..**.*
291a0 2a 20 7b 46 31 31 33 33 32 7d 20 54 68 65 20 5b  * {F11332} The [
291b0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
291c0 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 73 65  ] interface rese
291d0 74 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  ts the [prepared
291e0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a   statement] S.**
291f0 20 20 20 20 20 20 20 20 20 20 62 61 63 6b 20 74            back t
29200 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20  o the beginning 
29210 6f 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a  of its program..
29220 2a 2a 0a 2a 2a 20 7b 46 31 31 33 33 34 7d 20 49  **.** {F11334} I
29230 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
29240 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
29250 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20  e3_step(S)] for 
29260 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
29270 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
29280 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51  ] S returned [SQ
29290 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51  LITE_ROW] or [SQ
292a0 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 20  LITE_DONE],.**  
292b0 20 20 20 20 20 20 20 20 6f 72 20 69 66 20 5b 73          or if [s
292c0 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
292d0 68 61 73 20 6e 65 76 65 72 20 62 65 66 6f 72 65  has never before
292e0 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20   been called on 
292f0 53 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  S,.**          t
29300 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  hen [sqlite3_res
29310 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b  et(S)] returns [
29320 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a  SQLITE_OK]..**.*
29330 2a 20 7b 46 31 31 33 33 36 7d 20 49 66 20 74 68  * {F11336} If th
29340 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61  e most recent ca
29350 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
29360 74 65 70 28 53 29 5d 20 66 6f 72 0a 2a 2a 20 20  tep(S)] for.**  
29370 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65          [prepare
29380 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69  d statement] S i
29390 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72 72 6f  ndicated an erro
293a0 72 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20  r, then.**      
293b0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73      [sqlite3_res
293c0 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 61  et(S)] returns a
293d0 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65  n appropriate [e
293e0 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a  rror code]..**.*
293f0 2a 20 7b 46 31 31 33 33 38 7d 20 54 68 65 20 5b  * {F11338} The [
29400 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
29410 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73  ] interface does
29420 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20   not change the 
29430 76 61 6c 75 65 73 0a 2a 2a 20 20 20 20 20 20 20  values.**       
29440 20 20 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69 74     of any [sqlit
29450 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e  e3_bind_blob|bin
29460 64 69 6e 67 73 5d 20 6f 6e 20 5b 70 72 65 70 61  dings] on [prepa
29470 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
29480 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
29490 5f 72 65 73 65 74 28 73 71 6c 69 74 65 33 5f 73  _reset(sqlite3_s
294a0 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
294b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 72  .** CAPI3REF: Cr
294c0 65 61 74 65 20 4f 72 20 52 65 64 65 66 69 6e 65  eate Or Redefine
294d0 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73 20 7b   SQL Functions {
294e0 46 31 36 31 30 30 7d 0a 2a 2a 20 4b 45 59 57 4f  F16100}.** KEYWO
294f0 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63  RDS: {function c
29500 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  reation routines
29510 7d 20 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 74  } .**.** These t
29520 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f  wo functions (co
29530 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e  llectively known
29540 20 61 73 0a 2a 2a 20 22 66 75 6e 63 74 69 6f 6e   as.** "function
29550 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e   creation routin
29560 65 73 22 29 20 61 72 65 20 75 73 65 64 20 74 6f  es") are used to
29570 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f   add SQL functio
29580 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73  ns or aggregates
29590 0a 2a 2a 20 6f 72 20 74 6f 20 72 65 64 65 66 69  .** or to redefi
295a0 6e 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  ne the behavior 
295b0 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20  of existing SQL 
295c0 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67  functions or agg
295d0 72 65 67 61 74 65 73 2e 20 20 54 68 65 0a 2a 2a  regates.  The.**
295e0 20 64 69 66 66 65 72 65 6e 63 65 20 6f 6e 6c 79   difference only
295f0 20 62 65 74 77 65 65 6e 20 74 68 65 20 74 77 6f   between the two
29600 20 69 73 20 74 68 61 74 20 74 68 65 20 73 65 63   is that the sec
29610 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2c 20 74  ond parameter, t
29620 68 65 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20 74 68  he.** name of th
29630 65 20 28 73 63 61 6c 61 72 29 20 66 75 6e 63 74  e (scalar) funct
29640 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65  ion or aggregate
29650 2c 20 69 73 20 65 6e 63 6f 64 65 64 20 69 6e 20  , is encoded in 
29660 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c  UTF-8 for.** sql
29670 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
29680 74 69 6f 6e 28 29 20 61 6e 64 20 55 54 46 2d 31  tion() and UTF-1
29690 36 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72  6 for sqlite3_cr
296a0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
296b0 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  )..**.** The fir
296c0 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  st parameter is 
296d0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
296e0 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68 69  nnection] to whi
296f0 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75  ch the SQL.** fu
29700 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 20  nction is to be 
29710 61 64 64 65 64 2e 20 20 49 66 20 61 20 73 69 6e  added.  If a sin
29720 67 6c 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75  gle.** program u
29730 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  ses more than on
29740 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
29750 65 63 74 69 6f 6e 5d 20 69 6e 74 65 72 6e 61 6c  ection] internal
29760 6c 79 2c 20 74 68 65 6e 20 53 51 4c 0a 2a 2a 20  ly, then SQL.** 
29770 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20 62  functions must b
29780 65 20 61 64 64 65 64 20 69 6e 64 69 76 69 64 75  e added individu
29790 61 6c 6c 79 20 74 6f 20 65 61 63 68 20 5b 64 61  ally to each [da
297a0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
297b0 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  n]..**.** The se
297c0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
297d0 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
297e0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74  e SQL function t
297f0 6f 20 62 65 20 63 72 65 61 74 65 64 0a 2a 2a 20  o be created.** 
29800 6f 72 20 72 65 64 65 66 69 6e 65 64 2e 0a 2a 2a  or redefined..**
29810 20 54 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74   The length of t
29820 68 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74  he name is limit
29830 65 64 20 74 6f 20 32 35 35 20 62 79 74 65 73 2c  ed to 255 bytes,
29840 20 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68   exclusive of th
29850 65 20 0a 2a 2a 20 7a 65 72 6f 2d 74 65 72 6d 69  e .** zero-termi
29860 6e 61 74 6f 72 2e 20 20 4e 6f 74 65 20 74 68 61  nator.  Note tha
29870 74 20 74 68 65 20 6e 61 6d 65 20 6c 65 6e 67 74  t the name lengt
29880 68 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 62 79  h limit is in by
29890 74 65 73 2c 20 6e 6f 74 0a 2a 2a 20 63 68 61 72  tes, not.** char
298a0 61 63 74 65 72 73 2e 20 20 41 6e 79 20 61 74 74  acters.  Any att
298b0 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20 61  empt to create a
298c0 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61   function with a
298d0 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20   longer name.** 
298e0 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 61  will result in a
298f0 6e 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 65  n SQLITE_ERROR e
29900 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  rror..**.** The 
29910 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
29920 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
29930 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20   arguments that 
29940 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
29950 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65   or.** aggregate
29960 20 74 61 6b 65 73 2e 20 49 66 20 74 68 69 73 20   takes. If this 
29970 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 65 67  parameter is neg
29980 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20  ative, then the 
29990 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a  SQL function or.
299a0 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61 79  ** aggregate may
299b0 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72   take any number
299c0 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a   of arguments..*
299d0 2a 0a 2a 2a 20 54 68 65 20 66 6f 75 72 74 68 20  *.** The fourth 
299e0 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74  parameter, eText
299f0 52 65 70 2c 20 73 70 65 63 69 66 69 65 73 20 77  Rep, specifies w
29a00 68 61 74 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  hat .** [SQLITE_
29a10 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f  UTF8 | text enco
29a20 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66  ding] this SQL f
29a30 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20  unction prefers 
29a40 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d  for.** its param
29a50 65 74 65 72 73 2e 20 20 41 6e 79 20 53 51 4c 20  eters.  Any SQL 
29a60 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
29a70 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62  ntation should b
29a80 65 20 61 62 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a  e able to work.*
29a90 2a 20 77 6f 72 6b 20 77 69 74 68 20 55 54 46 2d  * work with UTF-
29aa0 38 2c 20 55 54 46 2d 31 36 6c 65 2c 20 6f 72 20  8, UTF-16le, or 
29ab0 55 54 46 2d 31 36 62 65 2e 20 20 42 75 74 20 73  UTF-16be.  But s
29ac0 6f 6d 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ome implementati
29ad0 6f 6e 73 20 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f  ons may be.** mo
29ae0 72 65 20 65 66 66 69 63 69 65 6e 74 20 77 69 74  re efficient wit
29af0 68 20 6f 6e 65 20 65 6e 63 6f 64 69 6e 67 20 74  h one encoding t
29b00 68 61 6e 20 61 6e 6f 74 68 65 72 2e 20 20 49 74  han another.  It
29b10 20 69 73 20 61 6c 6c 6f 77 65 64 20 74 6f 0a 2a   is allowed to.*
29b20 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  * invoke sqlite3
29b30 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
29b40 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 72  () or sqlite3_cr
29b50 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
29b60 29 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 69  ) multiple.** ti
29b70 6d 65 73 20 77 69 74 68 20 74 68 65 20 73 61 6d  mes with the sam
29b80 65 20 66 75 6e 63 74 69 6f 6e 20 62 75 74 20 77  e function but w
29b90 69 74 68 20 64 69 66 66 65 72 65 6e 74 20 76 61  ith different va
29ba0 6c 75 65 73 20 6f 66 20 65 54 65 78 74 52 65 70  lues of eTextRep
29bb0 2e 0a 2a 2a 20 57 68 65 6e 20 6d 75 6c 74 69 70  ..** When multip
29bc0 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
29bd0 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66  ns of the same f
29be0 75 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61 69  unction are avai
29bf0 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a  lable, SQLite.**
29c00 20 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f   will pick the o
29c10 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73  ne that involves
29c20 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e   the least amoun
29c30 74 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 72  t of data conver
29c40 73 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 72  sion..** If ther
29c50 65 20 69 73 20 6f 6e 6c 79 20 61 20 73 69 6e 67  e is only a sing
29c60 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
29c70 6e 20 77 68 69 63 68 20 64 6f 65 73 20 6e 6f 74  n which does not
29c80 20 63 61 72 65 20 77 68 61 74 0a 2a 2a 20 74 65   care what.** te
29c90 78 74 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75  xt encoding is u
29ca0 73 65 64 2c 20 74 68 65 6e 20 74 68 65 20 66 6f  sed, then the fo
29cb0 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 73 68  urth argument sh
29cc0 6f 75 6c 64 20 62 65 0a 2a 2a 20 5b 53 51 4c 49  ould be.** [SQLI
29cd0 54 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 54  TE_ANY]..**.** T
29ce0 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74  he fifth paramet
29cf0 65 72 20 69 73 20 61 6e 20 61 72 62 69 74 72 61  er is an arbitra
29d00 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65  ry pointer.  The
29d10 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a   implementation.
29d20 2a 2a 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69  ** of the functi
29d30 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63 65  on can gain acce
29d40 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e 74  ss to this point
29d50 65 72 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  er using.** [sql
29d60 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29  ite3_user_data()
29d70 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 76  ]..**.** The sev
29d80 65 6e 74 68 2c 20 65 69 67 68 74 68 20 61 6e 64  enth, eighth and
29d90 20 6e 69 6e 74 68 20 70 61 72 61 6d 65 74 65 72   ninth parameter
29da0 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20  s, xFunc, xStep 
29db0 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a  and xFinal, are.
29dc0 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43  ** pointers to C
29dd0 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69  -language functi
29de0 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  ons that impleme
29df0 6e 74 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75  nt the SQL.** fu
29e00 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67  nction or aggreg
29e10 61 74 65 2e 20 41 20 73 63 61 6c 61 72 20 53 51  ate. A scalar SQ
29e20 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69  L function requi
29e30 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74  res an implement
29e40 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 20  ation of.** the 
29e50 78 46 75 6e 63 20 63 61 6c 6c 62 61 63 6b 20 6f  xFunc callback o
29e60 6e 6c 79 2c 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  nly, NULL pointe
29e70 72 73 20 73 68 6f 75 6c 64 20 62 65 20 70 61 73  rs should be pas
29e80 73 65 64 20 61 73 20 74 68 65 20 78 53 74 65 70  sed as the xStep
29e90 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 70  .** and xFinal p
29ea0 61 72 61 6d 65 74 65 72 73 2e 20 41 6e 20 61 67  arameters. An ag
29eb0 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63  gregate SQL func
29ec0 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e  tion requires an
29ed0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a   implementation.
29ee0 2a 2a 20 6f 66 20 78 53 74 65 70 20 61 6e 64 20  ** of xStep and 
29ef0 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20  xFinal and NULL 
29f00 73 68 6f 75 6c 64 20 62 65 20 70 61 73 73 65 64  should be passed
29f10 20 66 6f 72 20 78 46 75 6e 63 2e 20 54 6f 20 64   for xFunc. To d
29f20 65 6c 65 74 65 20 61 6e 0a 2a 2a 20 65 78 69 73  elete an.** exis
29f30 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 6f  ting SQL functio
29f40 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20  n or aggregate, 
29f50 70 61 73 73 20 4e 55 4c 4c 20 66 6f 72 20 61 6c  pass NULL for al
29f60 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f 6e  l three function
29f70 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a  .** callbacks..*
29f80 2a 0a 2a 2a 20 49 74 20 69 73 20 70 65 72 6d 69  *.** It is permi
29f90 74 74 65 64 20 74 6f 20 72 65 67 69 73 74 65 72  tted to register
29fa0 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d   multiple implem
29fb0 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  entations of the
29fc0 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f   same.** functio
29fd0 6e 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65  ns with the same
29fe0 20 6e 61 6d 65 20 62 75 74 20 77 69 74 68 20 65   name but with e
29ff0 69 74 68 65 72 20 64 69 66 66 65 72 69 6e 67 20  ither differing 
2a000 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72  numbers of.** ar
2a010 67 75 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65  guments or diffe
2a020 72 69 6e 67 20 70 72 65 66 65 72 72 65 64 20 74  ring preferred t
2a030 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20  ext encodings.  
2a040 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a  SQLite will use.
2a050 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  ** the implement
2a060 61 74 69 6f 6e 20 6d 6f 73 74 20 63 6c 6f 73 65  ation most close
2a070 6c 79 20 6d 61 74 63 68 65 73 20 74 68 65 20 77  ly matches the w
2a080 61 79 20 69 6e 20 77 68 69 63 68 20 74 68 65 0a  ay in which the.
2a090 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ** SQL function 
2a0a0 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  is used..**.** I
2a0b0 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
2a0c0 20 7b 46 31 36 31 30 33 7d 20 54 68 65 20 5b 73   {F16103} The [s
2a0d0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2a0e0 6e 63 74 69 6f 6e 31 36 28 29 5d 20 69 6e 74 65  nction16()] inte
2a0f0 72 66 61 63 65 20 62 65 68 61 76 65 73 20 65 78  rface behaves ex
2a100 61 63 74 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20  actly.**        
2a110 20 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f    like [sqlite3_
2a120 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
2a130 29 5d 20 69 6e 20 65 76 65 72 79 20 77 61 79 20  )] in every way 
2a140 65 78 63 65 70 74 20 74 68 61 74 20 69 74 0a 2a  except that it.*
2a150 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 72  *          inter
2a160 70 72 65 74 73 20 74 68 65 20 7a 46 75 6e 63 74  prets the zFunct
2a170 69 6f 6e 4e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ionName argument
2a180 20 61 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   as.**          
2a190 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
2a1a0 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79  UTF-16 native by
2a1b0 74 65 20 6f 72 64 65 72 20 69 6e 73 74 65 61 64  te order instead
2a1c0 20 6f 66 20 61 73 20 61 0a 2a 2a 20 20 20 20 20   of as a.**     
2a1d0 20 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e       zero-termin
2a1e0 61 74 65 64 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a  ated UTF-8..**.*
2a1f0 2a 20 7b 46 31 36 31 30 36 7d 20 41 20 73 75 63  * {F16106} A suc
2a200 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69  cessful invocati
2a210 6f 6e 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20  on of.**        
2a220 20 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63    the [sqlite3_c
2a230 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44  reate_function(D
2a240 2c 58 2c 4e 2c 45 2c 2e 2e 2e 29 5d 20 69 6e 74  ,X,N,E,...)] int
2a250 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73  erface registers
2a260 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
2a270 72 65 70 6c 61 63 65 73 20 63 61 6c 6c 62 61 63  replaces callbac
2a280 6b 20 66 75 6e 63 74 69 6f 6e 73 20 69 6e 20 5b  k functions in [
2a290 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2a2a0 69 6f 6e 5d 20 44 0a 2a 2a 20 20 20 20 20 20 20  ion] D.**       
2a2b0 20 20 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65     used to imple
2a2c0 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e  ment the SQL fun
2a2d0 63 74 69 6f 6e 20 6e 61 6d 65 64 20 58 20 77 69  ction named X wi
2a2e0 74 68 20 4e 20 70 61 72 61 6d 65 74 65 72 73 0a  th N parameters.
2a2f0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64 20  **          and 
2a300 68 61 76 69 6e 67 20 61 20 70 72 65 66 65 72 72  having a preferr
2a310 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  ed text encoding
2a320 20 6f 66 20 45 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31   of E..**.** {F1
2a330 36 31 30 39 7d 20 41 20 73 75 63 63 65 73 73 66  6109} A successf
2a340 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ul call to [sqli
2a350 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2a360 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c  ion(D,X,N,E,P,F,
2a370 53 2c 4c 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  S,L)].**        
2a380 20 20 72 65 70 6c 61 63 65 73 20 74 68 65 20 50    replaces the P
2a390 2c 20 46 2c 20 53 2c 20 61 6e 64 20 4c 20 76 61  , F, S, and L va
2a3a0 6c 75 65 73 20 66 72 6f 6d 20 61 6e 79 20 70 72  lues from any pr
2a3b0 69 6f 72 20 63 61 6c 6c 73 20 77 69 74 68 0a 2a  ior calls with.*
2a3c0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 73  *          the s
2a3d0 61 6d 65 20 44 2c 20 58 2c 20 4e 2c 20 61 6e 64  ame D, X, N, and
2a3e0 20 45 20 76 61 6c 75 65 73 2e 0a 2a 2a 0a 2a 2a   E values..**.**
2a3f0 20 7b 46 31 36 31 31 32 7d 20 54 68 65 20 5b 73   {F16112} The [s
2a400 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2a410 6e 63 74 69 6f 6e 28 44 2c 58 2c 2e 2e 2e 29 5d  nction(D,X,...)]
2a420 20 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73   interface fails
2a430 20 77 69 74 68 0a 2a 2a 20 20 20 20 20 20 20 20   with.**        
2a440 20 20 61 20 72 65 74 75 72 6e 20 63 6f 64 65 20    a return code 
2a450 6f 66 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  of [SQLITE_ERROR
2a460 5d 20 69 66 20 74 68 65 20 53 51 4c 20 66 75 6e  ] if the SQL fun
2a470 63 74 69 6f 6e 20 6e 61 6d 65 20 58 20 69 73 0a  ction name X is.
2a480 2a 2a 20 20 20 20 20 20 20 20 20 20 6c 6f 6e 67  **          long
2a490 65 72 20 74 68 61 6e 20 32 35 35 20 62 79 74 65  er than 255 byte
2a4a0 73 20 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74  s exclusive of t
2a4b0 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  he zero terminat
2a4c0 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 31  or..**.** {F1611
2a4d0 38 7d 20 45 69 74 68 65 72 20 46 20 6d 75 73 74  8} Either F must
2a4e0 20 62 65 20 4e 55 4c 4c 20 61 6e 64 20 53 20 61   be NULL and S a
2a4f0 6e 64 20 4c 20 61 72 65 20 6e 6f 6e 2d 4e 55 4c  nd L are non-NUL
2a500 4c 20 6f 72 20 65 6c 73 65 20 46 0a 2a 2a 20 20  L or else F.**  
2a510 20 20 20 20 20 20 20 20 69 73 20 6e 6f 6e 2d 4e          is non-N
2a520 55 4c 4c 20 61 6e 64 20 53 20 61 6e 64 20 4c 20  ULL and S and L 
2a530 61 72 65 20 4e 55 4c 4c 2c 20 6f 74 68 65 72 77  are NULL, otherw
2a540 69 73 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ise.**          
2a550 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2a560 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45  function(D,X,N,E
2a570 2c 50 2c 46 2c 53 2c 4c 29 5d 20 72 65 74 75 72  ,P,F,S,L)] retur
2a580 6e 73 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ns [SQLITE_ERROR
2a590 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 32 31  ]..**.** {F16121
2a5a0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
2a5b0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44  reate_function(D
2a5c0 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65  ,...)] interface
2a5d0 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e 0a 2a   fails with an.*
2a5e0 2a 20 20 20 20 20 20 20 20 20 20 65 72 72 6f 72  *          error
2a5f0 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54 45   code of [SQLITE
2a600 5f 42 55 53 59 5d 20 69 66 20 74 68 65 72 65 20  _BUSY] if there 
2a610 65 78 69 73 74 20 5b 70 72 65 70 61 72 65 64 20  exist [prepared 
2a620 73 74 61 74 65 6d 65 6e 74 73 5d 0a 2a 2a 20 20  statements].**  
2a630 20 20 20 20 20 20 20 20 61 73 73 6f 63 69 61 74          associat
2a640 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 74  ed with the [dat
2a650 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2a660 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31  ] D..**.** {F161
2a670 32 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  24} The [sqlite3
2a680 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2a690 28 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d 20 69 6e 74  (D,X,N,...)] int
2a6a0 65 72 66 61 63 65 20 66 61 69 6c 73 20 77 69 74  erface fails wit
2a6b0 68 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  h an.**         
2a6c0 20 65 72 72 6f 72 20 63 6f 64 65 20 6f 66 20 5b   error code of [
2a6d0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66  SQLITE_ERROR] if
2a6e0 20 70 61 72 61 6d 65 74 65 72 20 4e 20 28 73 70   parameter N (sp
2a6f0 65 63 69 66 79 69 6e 67 20 74 68 65 20 6e 75 6d  ecifying the num
2a700 62 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ber.**          
2a710 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  of arguments to 
2a720 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
2a730 20 62 65 69 6e 67 20 72 65 67 69 73 74 65 72 65   being registere
2a740 64 29 20 69 73 20 6c 65 73 73 0a 2a 2a 20 20 20  d) is less.**   
2a750 20 20 20 20 20 20 20 74 68 61 6e 20 2d 31 20 6f         than -1 o
2a760 72 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 31  r greater than 1
2a770 32 37 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 32  27..**.** {F1612
2a780 37 7d 20 57 68 65 6e 20 4e 20 69 73 20 6e 6f 6e  7} When N is non
2a790 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 20 5b  -negative, the [
2a7a0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2a7b0 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e  unction(D,X,N,..
2a7c0 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  .)].**          
2a7d0 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73  interface causes
2a7e0 20 63 61 6c 6c 62 61 63 6b 73 20 74 6f 20 62 65   callbacks to be
2a7f0 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68 65   invoked for the
2a800 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a   SQL function.**
2a810 20 20 20 20 20 20 20 20 20 20 6e 61 6d 65 64 20            named 
2a820 58 20 77 68 65 6e 20 74 68 65 20 6e 75 6d 62 65  X when the numbe
2a830 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74  r of arguments t
2a840 6f 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  o the SQL functi
2a850 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20  on is.**        
2a860 20 20 65 78 61 63 74 6c 79 20 4e 2e 0a 2a 2a 0a    exactly N..**.
2a870 2a 2a 20 7b 46 31 36 31 33 30 7d 20 57 68 65 6e  ** {F16130} When
2a880 20 4e 20 69 73 20 2d 31 2c 20 74 68 65 20 5b 73   N is -1, the [s
2a890 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2a8a0 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e  nction(D,X,N,...
2a8b0 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  )].**          i
2a8c0 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20  nterface causes 
2a8d0 63 61 6c 6c 62 61 63 6b 73 20 74 6f 20 62 65 20  callbacks to be 
2a8e0 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68 65 20  invoked for the 
2a8f0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  SQL function.** 
2a900 20 20 20 20 20 20 20 20 20 6e 61 6d 65 64 20 58           named X
2a910 20 77 69 74 68 20 61 6e 79 20 6e 75 6d 62 65 72   with any number
2a920 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a   of arguments..*
2a930 2a 0a 2a 2a 20 7b 46 31 36 31 33 33 7d 20 57 68  *.** {F16133} Wh
2a940 65 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  en calls to [sql
2a950 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2a960 74 69 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d  tion(D,X,N,...)]
2a970 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 70 65  .**          spe
2a980 63 69 66 79 20 6d 75 6c 74 69 70 6c 65 20 69 6d  cify multiple im
2a990 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66  plementations of
2a9a0 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69   the same functi
2a9b0 6f 6e 20 58 0a 2a 2a 20 20 20 20 20 20 20 20 20  on X.**         
2a9c0 20 61 6e 64 20 77 68 65 6e 20 6f 6e 65 20 69 6d   and when one im
2a9d0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 68 61 73  plementation has
2a9e0 20 4e 3e 3d 30 20 61 6e 64 20 74 68 65 20 6f 74   N>=0 and the ot
2a9f0 68 65 72 20 68 61 73 20 4e 3d 28 2d 31 29 0a 2a  her has N=(-1).*
2aa00 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 69  *          the i
2aa10 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69  mplementation wi
2aa20 74 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 4e 20  th a non-zero N 
2aa30 69 73 20 70 72 65 66 65 72 72 65 64 2e 0a 2a 2a  is preferred..**
2aa40 0a 2a 2a 20 7b 46 31 36 31 33 36 7d 20 57 68 65  .** {F16136} Whe
2aa50 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  n calls to [sqli
2aa60 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2aa70 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 2e 2e 2e 29  ion(D,X,N,E,...)
2aa80 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 70  ].**          sp
2aa90 65 63 69 66 79 20 6d 75 6c 74 69 70 6c 65 20 69  ecify multiple i
2aaa0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f  mplementations o
2aab0 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74  f the same funct
2aac0 69 6f 6e 20 58 20 77 69 74 68 0a 2a 2a 20 20 20  ion X with.**   
2aad0 20 20 20 20 20 20 20 74 68 65 20 73 61 6d 65 20         the same 
2aae0 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65  number of argume
2aaf0 6e 74 73 20 4e 20 62 75 74 20 77 69 74 68 20 64  nts N but with d
2ab00 69 66 66 65 72 65 6e 74 0a 2a 2a 20 20 20 20 20  ifferent.**     
2ab10 20 20 20 20 20 65 6e 63 6f 64 69 6e 67 73 20 45       encodings E
2ab20 2c 20 74 68 65 6e 20 74 68 65 20 69 6d 70 6c 65  , then the imple
2ab30 6d 65 6e 74 61 74 69 6f 6e 20 77 68 65 72 65 20  mentation where 
2ab40 45 20 6d 61 74 63 68 65 73 20 74 68 65 0a 2a 2a  E matches the.**
2ab50 20 20 20 20 20 20 20 20 20 20 64 61 74 61 62 61            databa
2ab60 73 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 70  se encoding is p
2ab70 72 65 66 65 72 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  referred..**.** 
2ab80 7b 46 31 36 31 33 39 7d 20 46 6f 72 20 61 6e 20  {F16139} For an 
2ab90 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75  aggregate SQL fu
2aba0 6e 63 74 69 6f 6e 20 63 72 65 61 74 65 64 20 75  nction created u
2abb0 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20  sing.**         
2abc0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2abd0 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c  _function(D,X,N,
2abe0 45 2c 50 2c 30 2c 53 2c 4c 29 5d 20 74 68 65 20  E,P,0,S,L)] the 
2abf0 66 69 6e 69 61 6c 69 7a 65 72 0a 2a 2a 20 20 20  finializer.**   
2ac00 20 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 20         function 
2ac10 4c 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 62 65  L will always be
2ac20 20 69 6e 76 6f 6b 65 64 20 65 78 61 63 74 6c 79   invoked exactly
2ac30 20 6f 6e 63 65 20 69 66 20 74 68 65 0a 2a 2a 20   once if the.** 
2ac40 20 20 20 20 20 20 20 20 20 73 74 65 70 20 66 75           step fu
2ac50 6e 63 74 69 6f 6e 20 53 20 69 73 20 63 61 6c 6c  nction S is call
2ac60 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74  ed one or more t
2ac70 69 6d 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  imes..**.** {F16
2ac80 31 34 32 7d 20 57 68 65 6e 20 53 51 4c 69 74 65  142} When SQLite
2ac90 20 69 6e 76 6f 6b 65 73 20 65 69 74 68 65 72 20   invokes either 
2aca0 74 68 65 20 78 46 75 6e 63 20 6f 72 20 78 53 74  the xFunc or xSt
2acb0 65 70 20 66 75 6e 63 74 69 6f 6e 20 6f 66 0a 2a  ep function of.*
2acc0 2a 20 20 20 20 20 20 20 20 20 20 61 6e 20 61 70  *          an ap
2acd0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2ace0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  d SQL function o
2acf0 72 20 61 67 67 72 65 67 61 74 65 20 63 72 65 61  r aggregate crea
2ad00 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ted.**          
2ad10 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  by [sqlite3_crea
2ad20 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 6f  te_function()] o
2ad30 72 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  r [sqlite3_creat
2ad40 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 2c  e_function16()],
2ad50 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
2ad60 6e 20 74 68 65 20 61 72 72 61 79 20 6f 66 20 5b  n the array of [
2ad70 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2ad80 62 6a 65 63 74 73 20 70 61 73 73 65 64 20 61 73  bjects passed as
2ad90 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
2ada0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
2adb0 20 61 72 65 20 61 6c 77 61 79 73 20 5b 70 72 6f   are always [pro
2adc0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2add0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  alue] objects..*
2ade0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  /.int sqlite3_cr
2adf0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20  eate_function(. 
2ae00 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20   sqlite3 *db,.  
2ae10 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e  const char *zFun
2ae20 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74  ctionName,.  int
2ae30 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65   nArg,.  int eTe
2ae40 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70  xtRep,.  void *p
2ae50 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  App,.  void (*xF
2ae60 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  unc)(sqlite3_con
2ae70 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
2ae80 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
2ae90 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69  id (*xStep)(sqli
2aea0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
2aeb0 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
2aec0 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e  ),.  void (*xFin
2aed0 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  al)(sqlite3_cont
2aee0 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c  ext*).);.int sql
2aef0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2af00 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65  tion16(.  sqlite
2af10 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 76  3 *db,.  const v
2af20 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61  oid *zFunctionNa
2af30 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a  me,.  int nArg,.
2af40 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a    int eTextRep,.
2af50 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20    void *pApp,.  
2af60 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71  void (*xFunc)(sq
2af70 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
2af80 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
2af90 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53  **),.  void (*xS
2afa0 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  tep)(sqlite3_con
2afb0 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
2afc0 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
2afd0 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c  id (*xFinal)(sql
2afe0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29  ite3_context*).)
2aff0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2b000 46 3a 20 54 65 78 74 20 45 6e 63 6f 64 69 6e 67  F: Text Encoding
2b010 73 20 7b 46 31 30 32 36 37 7d 0a 2a 2a 0a 2a 2a  s {F10267}.**.**
2b020 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 20   These constant 
2b030 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63  define integer c
2b040 6f 64 65 73 20 74 68 61 74 20 72 65 70 72 65 73  odes that repres
2b050 65 6e 74 20 74 68 65 20 76 61 72 69 6f 75 73 0a  ent the various.
2b060 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  ** text encoding
2b070 73 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53  s supported by S
2b080 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e  QLite..*/.#defin
2b090 65 20 53 51 4c 49 54 45 5f 55 54 46 38 20 20 20  e SQLITE_UTF8   
2b0a0 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e          1.#defin
2b0b0 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45  e SQLITE_UTF16LE
2b0c0 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e          2.#defin
2b0d0 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45  e SQLITE_UTF16BE
2b0e0 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e          3.#defin
2b0f0 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 20 20  e SQLITE_UTF16  
2b100 20 20 20 20 20 20 20 20 34 20 20 20 20 2f 2a 20          4    /* 
2b110 55 73 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  Use native byte 
2b120 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65  order */.#define
2b130 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 20 20 20   SQLITE_ANY     
2b140 20 20 20 20 20 20 20 35 20 20 20 20 2f 2a 20 73         5    /* s
2b150 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2b160 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23  nction only */.#
2b170 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
2b180 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 20  F16_ALIGNED  8  
2b190 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65    /* sqlite3_cre
2b1a0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e  ate_collation on
2b1b0 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ly */../*.** CAP
2b1c0 49 33 52 45 46 3a 20 4f 62 73 6f 6c 65 74 65 20  I3REF: Obsolete 
2b1d0 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  Functions.**.** 
2b1e0 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
2b1f0 61 72 65 20 61 6c 6c 20 6e 6f 77 20 6f 62 73 6f  are all now obso
2b200 6c 65 74 65 2e 20 20 49 6e 20 6f 72 64 65 72 20  lete.  In order 
2b210 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62  to maintain.** b
2b220 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
2b230 62 69 6c 69 74 79 20 77 69 74 68 20 6f 6c 64 65  bility with olde
2b240 72 20 63 6f 64 65 2c 20 77 65 20 63 6f 6e 74 69  r code, we conti
2b250 6e 75 65 20 74 6f 20 73 75 70 70 6f 72 74 0a 2a  nue to support.*
2b260 2a 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  * these function
2b270 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 77  s.  However, new
2b280 20 64 65 76 65 6c 6f 70 6d 65 6e 74 20 70 72 6f   development pro
2b290 6a 65 63 74 73 20 73 68 6f 75 6c 64 20 61 76 6f  jects should avo
2b2a0 69 64 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66  id.** the use of
2b2b0 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
2b2c0 2e 20 20 54 6f 20 68 65 6c 70 20 65 6e 63 6f 75  .  To help encou
2b2d0 72 61 67 65 20 70 65 6f 70 6c 65 20 74 6f 20 61  rage people to a
2b2e0 76 6f 69 64 0a 2a 2a 20 75 73 69 6e 67 20 74 68  void.** using th
2b2f0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20 77  ese functions, w
2b300 65 20 61 72 65 20 6e 6f 74 20 67 6f 69 6e 67 20  e are not going 
2b310 74 6f 20 74 65 6c 6c 20 79 6f 75 20 77 61 6e 74  to tell you want
2b320 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 69 6e 74   they do..*/.int
2b330 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
2b340 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33  te_count(sqlite3
2b350 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 69 6e 74 20  _context*);.int 
2b360 73 71 6c 69 74 65 33 5f 65 78 70 69 72 65 64 28  sqlite3_expired(
2b370 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
2b380 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 72 61 6e  int sqlite3_tran
2b390 73 66 65 72 5f 62 69 6e 64 69 6e 67 73 28 73 71  sfer_bindings(sq
2b3a0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c  lite3_stmt*, sql
2b3b0 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 69 6e 74  ite3_stmt*);.int
2b3c0 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f   sqlite3_global_
2b3d0 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 76  recover(void);.v
2b3e0 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 68 72 65  oid sqlite3_thre
2b3f0 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 29  ad_cleanup(void)
2b400 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65  ;.int sqlite3_me
2b410 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28  mory_alarm(void(
2b420 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33  *)(void*,sqlite3
2b430 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 76 6f 69 64  _int64,int),void
2b440 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  *,sqlite3_int64)
2b450 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2b460 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c  F: Obtaining SQL
2b470 20 46 75 6e 63 74 69 6f 6e 20 50 61 72 61 6d 65   Function Parame
2b480 74 65 72 20 56 61 6c 75 65 73 20 7b 46 31 35 31  ter Values {F151
2b490 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d  00}.**.** The C-
2b4a0 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d 65  language impleme
2b4b0 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66  ntation of SQL f
2b4c0 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67  unctions and agg
2b4d0 72 65 67 61 74 65 73 20 75 73 65 73 0a 2a 2a 20  regates uses.** 
2b4e0 74 68 69 73 20 73 65 74 20 6f 66 20 69 6e 74 65  this set of inte
2b4f0 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20 74  rface routines t
2b500 6f 20 61 63 63 65 73 73 20 74 68 65 20 70 61 72  o access the par
2b510 61 6d 65 74 65 72 20 76 61 6c 75 65 73 20 6f 6e  ameter values on
2b520 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  .** the function
2b530 20 6f 72 20 61 67 67 72 65 67 61 74 65 2e 0a 2a   or aggregate..*
2b540 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 28  *.** The xFunc (
2b550 66 6f 72 20 73 63 61 6c 61 72 20 66 75 6e 63 74  for scalar funct
2b560 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 20 28  ions) or xStep (
2b570 66 6f 72 20 61 67 67 72 65 67 61 74 65 73 29 20  for aggregates) 
2b580 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f  parameters.** to
2b590 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2b5a0 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64  _function()] and
2b5b0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2b5c0 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a  _function16()].*
2b5d0 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 63  * define callbac
2b5e0 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ks that implemen
2b5f0 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  t the SQL functi
2b600 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74  ons and aggregat
2b610 65 73 2e 0a 2a 2a 20 54 68 65 20 34 74 68 20 70  es..** The 4th p
2b620 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 73  arameter to thes
2b630 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 61  e callbacks is a
2b640 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
2b650 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65  ers to.** [prote
2b660 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2b670 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 68  ue] objects.  Th
2b680 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69  ere is one [sqli
2b690 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
2b6a0 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61  t for.** each pa
2b6b0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 53  rameter to the S
2b6c0 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68  QL function.  Th
2b6d0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
2b6e0 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72   used to.** extr
2b6f0 61 63 74 20 76 61 6c 75 65 73 20 66 72 6f 6d 20  act values from 
2b700 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  the [sqlite3_val
2b710 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a  ue] objects..**.
2b720 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
2b730 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68  s work only with
2b740 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
2b750 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
2b760 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d  ts..** Any attem
2b770 70 74 20 74 6f 20 75 73 65 20 74 68 65 73 65 20  pt to use these 
2b780 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b  routines on an [
2b790 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
2b7a0 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62  te3_value].** ob
2b7b0 6a 65 63 74 20 72 65 73 75 6c 74 73 20 69 6e 20  ject results in 
2b7c0 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69  undefined behavi
2b7d0 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  or..**.** These 
2b7e0 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75  routines work ju
2b7f0 73 74 20 6c 69 6b 65 20 74 68 65 20 63 6f 72 72  st like the corr
2b800 65 73 70 6f 6e 64 69 6e 67 20 0a 2a 2a 20 5b 73  esponding .** [s
2b810 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
2b820 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ob | sqlite3_col
2b830 75 6d 6e 5f 2a 20 72 6f 75 74 69 6e 65 73 5d 20  umn_* routines] 
2b840 65 78 63 65 70 74 20 74 68 61 74 20 0a 2a 2a 20  except that .** 
2b850 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74  these routines t
2b860 61 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b 70 72  ake a single [pr
2b870 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2b880 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 70 6f  value] object po
2b890 69 6e 74 65 72 0a 2a 2a 20 69 6e 73 74 65 61 64  inter.** instead
2b8a0 20 6f 66 20 61 20 5b 73 71 6c 69 74 65 33 5f 73   of a [sqlite3_s
2b8b0 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e  tmt*] pointer an
2b8c0 64 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c  d an integer col
2b8d0 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a  umn number..**.*
2b8e0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61  * The sqlite3_va
2b8f0 6c 75 65 5f 74 65 78 74 31 36 28 29 20 69 6e 74  lue_text16() int
2b900 65 72 66 61 63 65 20 65 78 74 72 61 63 74 73 20  erface extracts 
2b910 61 20 55 54 46 31 36 20 73 74 72 69 6e 67 0a 2a  a UTF16 string.*
2b920 2a 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20  * in the native 
2b930 62 79 74 65 2d 6f 72 64 65 72 20 6f 66 20 74 68  byte-order of th
2b940 65 20 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20  e host machine. 
2b950 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   The.** sqlite3_
2b960 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29  value_text16be()
2b970 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 61 6c   and sqlite3_val
2b980 75 65 5f 74 65 78 74 31 36 6c 65 28 29 20 69 6e  ue_text16le() in
2b990 74 65 72 66 61 63 65 73 0a 2a 2a 20 65 78 74 72  terfaces.** extr
2b9a0 61 63 74 20 55 54 46 31 36 20 73 74 72 69 6e 67  act UTF16 string
2b9b0 73 20 61 73 20 62 69 67 2d 65 6e 64 69 61 6e 20  s as big-endian 
2b9c0 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61  and little-endia
2b9d0 6e 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a  n respectively..
2b9e0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
2b9f0 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f  3_value_numeric_
2ba00 74 79 70 65 28 29 20 69 6e 74 65 72 66 61 63 65  type() interface
2ba10 20 61 74 74 65 6d 70 74 73 20 74 6f 20 61 70 70   attempts to app
2ba20 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66  ly.** numeric af
2ba30 66 69 6e 69 74 79 20 74 6f 20 74 68 65 20 76 61  finity to the va
2ba40 6c 75 65 2e 20 20 54 68 69 73 20 6d 65 61 6e 73  lue.  This means
2ba50 20 74 68 61 74 20 61 6e 20 61 74 74 65 6d 70 74   that an attempt
2ba60 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63   is.** made to c
2ba70 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65  onvert the value
2ba80 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 6f   to an integer o
2ba90 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  r floating point
2baa0 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68 20 61 20  .  If.** such a 
2bab0 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 6f  conversion is po
2bac0 73 73 69 62 6c 65 20 77 69 74 68 6f 75 74 20 6c  ssible without l
2bad0 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69  oss of informati
2bae0 6f 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20  on (in other.** 
2baf0 77 6f 72 64 73 20 69 66 20 74 68 65 20 76 61 6c  words if the val
2bb00 75 65 20 69 73 20 61 20 73 74 72 69 6e 67 20 74  ue is a string t
2bb10 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61  hat looks like a
2bb20 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e   number).** then
2bb30 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20   the conversion 
2bb40 69 73 20 64 6f 6e 65 2e 20 20 4f 74 68 65 72 77  is done.  Otherw
2bb50 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f  ise no conversio
2bb60 6e 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20 0a  n occurs.  The .
2bb70 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47  ** [SQLITE_INTEG
2bb80 45 52 20 7c 20 64 61 74 61 74 79 70 65 5d 20 61  ER | datatype] a
2bb90 66 74 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20  fter conversion 
2bba0 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
2bbb0 2a 2a 20 50 6c 65 61 73 65 20 70 61 79 20 70 61  ** Please pay pa
2bbc0 72 74 69 63 75 6c 61 72 20 61 74 74 65 6e 74 69  rticular attenti
2bbd0 6f 6e 20 74 6f 20 74 68 65 20 66 61 63 74 20 74  on to the fact t
2bbe0 68 61 74 20 74 68 65 20 70 6f 69 6e 74 65 72 20  hat the pointer 
2bbf0 74 68 61 74 0a 2a 2a 20 69 73 20 72 65 74 75 72  that.** is retur
2bc00 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
2bc10 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c  3_value_blob()],
2bc20 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2bc30 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b  text()], or.** [
2bc40 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
2bc50 78 74 31 36 28 29 5d 20 63 61 6e 20 62 65 20 69  xt16()] can be i
2bc60 6e 76 61 6c 69 64 61 74 65 64 20 62 79 20 61 20  nvalidated by a 
2bc70 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20  subsequent call 
2bc80 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  to.** [sqlite3_v
2bc90 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b  alue_bytes()], [
2bca0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
2bcb0 74 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74  tes16()], [sqlit
2bcc0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d  e3_value_text()]
2bcd0 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ,.** or [sqlite3
2bce0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d  _value_text16()]
2bcf0 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  .  .**.** These 
2bd00 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65  routines must be
2bd10 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
2bd20 20 73 61 6d 65 20 74 68 72 65 61 64 20 61 73 0a   same thread as.
2bd30 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  ** the SQL funct
2bd40 69 6f 6e 20 74 68 61 74 20 73 75 70 70 6c 69 65  ion that supplie
2bd50 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  d the [sqlite3_v
2bd60 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74 65 72  alue*] parameter
2bd70 73 2e 0a 2a 2a 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  s..**.**.** INVA
2bd80 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  RIANTS:.**.** {F
2bd90 31 35 31 30 33 7d 20 54 68 65 20 5b 73 71 6c 69  15103} The [sqli
2bda0 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 56  te3_value_blob(V
2bdb0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e  )] interface con
2bdc0 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20  verts the.**    
2bdd0 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64        [protected
2bde0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
2bdf0 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20  object V into a 
2be00 62 6c 6f 62 20 61 6e 64 20 74 68 65 6e 20 72 65  blob and then re
2be10 74 75 72 6e 73 20 61 0a 2a 2a 20 20 20 20 20 20  turns a.**      
2be20 20 20 20 20 70 6f 69 6e 74 65 72 20 74 6f 20 74      pointer to t
2be30 68 65 20 63 6f 6e 76 65 72 74 65 64 20 76 61 6c  he converted val
2be40 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31 30  ue..**.** {F1510
2be50 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  6} The [sqlite3_
2be60 76 61 6c 75 65 5f 62 79 74 65 73 28 56 29 5d 20  value_bytes(V)] 
2be70 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2be80 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
2be90 20 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65    number of byte
2bea0 73 20 69 6e 20 74 68 65 20 62 6c 6f 62 20 6f 72  s in the blob or
2beb0 20 73 74 72 69 6e 67 20 28 65 78 63 6c 75 73 69   string (exclusi
2bec0 76 65 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20  ve of the.**    
2bed0 20 20 20 20 20 20 7a 65 72 6f 20 74 65 72 6d 69        zero termi
2bee0 6e 61 74 6f 72 20 6f 6e 20 74 68 65 20 73 74 72  nator on the str
2bef0 69 6e 67 29 20 74 68 61 74 20 77 61 73 20 72 65  ing) that was re
2bf00 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a  turned by the.**
2bf10 20 20 20 20 20 20 20 20 20 20 6d 6f 73 74 20 72            most r
2bf20 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73  ecent call to [s
2bf30 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f  qlite3_value_blo
2bf40 62 28 56 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20  b(V)] or.**     
2bf50 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 76 61       [sqlite3_va
2bf60 6c 75 65 5f 74 65 78 74 28 56 29 5d 2e 0a 2a 2a  lue_text(V)]..**
2bf70 0a 2a 2a 20 7b 46 31 35 31 30 39 7d 20 54 68 65  .** {F15109} The
2bf80 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2bf90 62 79 74 65 73 31 36 28 56 29 5d 20 69 6e 74 65  bytes16(V)] inte
2bfa0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
2bfb0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 75  e.**          nu
2bfc0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
2bfd0 20 74 68 65 20 73 74 72 69 6e 67 20 28 65 78 63   the string (exc
2bfe0 6c 75 73 69 76 65 20 6f 66 20 74 68 65 0a 2a 2a  lusive of the.**
2bff0 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 20 74            zero t
2c000 65 72 6d 69 6e 61 74 6f 72 20 6f 6e 20 74 68 65  erminator on the
2c010 20 73 74 72 69 6e 67 29 20 74 68 61 74 20 77 61   string) that wa
2c020 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  s returned by th
2c030 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 6f  e.**          mo
2c040 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74  st recent call t
2c050 6f 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  o [sqlite3_value
2c060 5f 74 65 78 74 31 36 28 56 29 5d 2c 0a 2a 2a 20  _text16(V)],.** 
2c070 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
2c080 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65  3_value_text16be
2c090 28 56 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65  (V)], or [sqlite
2c0a0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65  3_value_text16le
2c0b0 28 56 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35  (V)]..**.** {F15
2c0c0 31 31 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  112} The [sqlite
2c0d0 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 56  3_value_double(V
2c0e0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e  )] interface con
2c0f0 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20  verts the.**    
2c100 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64        [protected
2c110 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
2c120 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20  object V into a 
2c130 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76  floating point v
2c140 61 6c 75 65 20 61 6e 64 0a 2a 2a 20 20 20 20 20  alue and.**     
2c150 20 20 20 20 20 72 65 74 75 72 6e 73 20 61 20 63       returns a c
2c160 6f 70 79 20 6f 66 20 74 68 61 74 20 76 61 6c 75  opy of that valu
2c170 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31 31 35  e..**.** {F15115
2c180 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  } The [sqlite3_v
2c190 61 6c 75 65 5f 69 6e 74 28 56 29 5d 20 69 6e 74  alue_int(V)] int
2c1a0 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20  erface converts 
2c1b0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
2c1c0 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
2c1d0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
2c1e0 20 56 20 69 6e 74 6f 20 61 20 36 34 2d 62 69 74   V into a 64-bit
2c1f0 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20   signed integer 
2c200 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  and.**          
2c210 72 65 74 75 72 6e 73 20 74 68 65 20 6c 6f 77 65  returns the lowe
2c220 72 20 33 32 20 62 69 74 73 20 6f 66 20 74 68 61  r 32 bits of tha
2c230 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a  t integer..**.**
2c240 20 7b 46 31 35 31 31 38 7d 20 54 68 65 20 5b 73   {F15118} The [s
2c250 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74  qlite3_value_int
2c260 36 34 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65  64(V)] interface
2c270 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a   converts the.**
2c280 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65            [prote
2c290 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2c2a0 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74  ue] object V int
2c2b0 6f 20 61 20 36 34 2d 62 69 74 20 73 69 67 6e 65  o a 64-bit signe
2c2c0 64 20 69 6e 74 65 67 65 72 20 61 6e 64 0a 2a 2a  d integer and.**
2c2d0 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e            return
2c2e0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 61 74  s a copy of that
2c2f0 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20   integer..**.** 
2c300 7b 46 31 35 31 32 31 7d 20 54 68 65 20 5b 73 71  {F15121} The [sq
2c310 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
2c320 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  (V)] interface c
2c330 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20  onverts the.**  
2c340 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74          [protect
2c350 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2c360 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20  ] object V into 
2c370 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
2c380 64 20 55 54 46 2d 38 20 0a 2a 2a 20 20 20 20 20  d UTF-8 .**     
2c390 20 20 20 20 20 73 74 72 69 6e 67 20 61 6e 64 20       string and 
2c3a0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
2c3b0 72 20 74 6f 20 74 68 61 74 20 73 74 72 69 6e 67  r to that string
2c3c0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31 32 34 7d  ..**.** {F15124}
2c3d0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   The [sqlite3_va
2c3e0 6c 75 65 5f 74 65 78 74 31 36 28 56 29 5d 20 69  lue_text16(V)] i
2c3f0 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74  nterface convert
2c400 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
2c410 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c    [protected sql
2c420 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
2c430 63 74 20 56 20 69 6e 74 6f 20 61 20 7a 65 72 6f  ct V into a zero
2c440 2d 74 65 72 6d 69 6e 61 74 65 64 20 32 2d 62 79  -terminated 2-by
2c450 74 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  te.**          a
2c460 6c 69 67 6e 65 64 20 55 54 46 2d 31 36 20 6e 61  ligned UTF-16 na
2c470 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 0a  tive byte order.
2c480 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 72 69  **          stri
2c490 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61  ng and returns a
2c4a0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74   pointer to that
2c4b0 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b   string..**.** {
2c4c0 46 31 35 31 32 37 7d 20 54 68 65 20 5b 73 71 6c  F15127} The [sql
2c4d0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
2c4e0 36 62 65 28 56 29 5d 20 69 6e 74 65 72 66 61 63  6be(V)] interfac
2c4f0 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a  e converts the.*
2c500 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74  *          [prot
2c510 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2c520 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e  lue] object V in
2c530 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  to a zero-termin
2c540 61 74 65 64 20 32 2d 62 79 74 65 0a 2a 2a 20 20  ated 2-byte.**  
2c550 20 20 20 20 20 20 20 20 61 6c 69 67 6e 65 64 20          aligned 
2c560 55 54 46 2d 31 36 20 62 69 67 2d 65 6e 64 69 61  UTF-16 big-endia
2c570 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74  n.**          st
2c580 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73  ring and returns
2c590 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
2c5a0 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  at string..**.**
2c5b0 20 7b 46 31 35 31 33 30 7d 20 54 68 65 20 5b 73   {F15130} The [s
2c5c0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2c5d0 74 31 36 6c 65 28 56 29 5d 20 69 6e 74 65 72 66  t16le(V)] interf
2c5e0 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65  ace converts the
2c5f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
2c600 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2c610 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20  value] object V 
2c620 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d  into a zero-term
2c630 69 6e 61 74 65 64 20 32 2d 62 79 74 65 0a 2a 2a  inated 2-byte.**
2c640 20 20 20 20 20 20 20 20 20 20 61 6c 69 67 6e 65            aligne
2c650 64 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 2d  d UTF-16 little-
2c660 65 6e 64 69 61 6e 0a 2a 2a 20 20 20 20 20 20 20  endian.**       
2c670 20 20 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65     string and re
2c680 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
2c690 74 6f 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a  to that string..
2c6a0 2a 2a 0a 2a 2a 20 7b 46 31 35 31 33 33 7d 20 54  **.** {F15133} T
2c6b0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
2c6c0 65 5f 74 79 70 65 28 56 29 5d 20 69 6e 74 65 72  e_type(V)] inter
2c6d0 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20  face returns.** 
2c6e0 20 20 20 20 20 20 20 20 20 6f 6e 65 20 6f 66 20           one of 
2c6f0 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2c 20 5b  [SQLITE_NULL], [
2c700 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c  SQLITE_INTEGER],
2c710 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c   [SQLITE_FLOAT],
2c720 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51  .**          [SQ
2c730 4c 49 54 45 5f 54 45 58 54 5d 2c 20 6f 72 20 5b  LITE_TEXT], or [
2c740 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 20 61 73 20  SQLITE_BLOB] as 
2c750 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72 0a  appropriate for.
2c760 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
2c770 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
2c780 6f 62 6a 65 63 74 20 56 2e 0a 2a 2a 0a 2a 2a 20  object V..**.** 
2c790 7b 46 31 35 31 33 36 7d 20 54 68 65 20 5b 73 71  {F15136} The [sq
2c7a0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65  lite3_value_nume
2c7b0 72 69 63 5f 74 79 70 65 28 56 29 5d 20 69 6e 74  ric_type(V)] int
2c7c0 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 0a  erface converts.
2c7d0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
2c7e0 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
2c7f0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
2c800 20 56 20 69 6e 74 6f 20 65 69 74 68 65 72 20 61   V into either a
2c810 6e 20 69 6e 74 65 67 65 72 20 6f 72 0a 2a 2a 20  n integer or.** 
2c820 20 20 20 20 20 20 20 20 20 61 20 66 6c 6f 61 74           a float
2c830 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20  ing point value 
2c840 69 66 20 69 74 20 63 61 6e 20 64 6f 20 73 6f 20  if it can do so 
2c850 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 0a  without loss of.
2c860 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 66 6f  **          info
2c870 72 6d 61 74 69 6f 6e 2c 20 61 6e 64 20 72 65 74  rmation, and ret
2c880 75 72 6e 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c  urns one of [SQL
2c890 49 54 45 5f 4e 55 4c 4c 5d 2c 0a 2a 2a 20 20 20  ITE_NULL],.**   
2c8a0 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 49         [SQLITE_I
2c8b0 4e 54 45 47 45 52 5d 2c 20 5b 53 51 4c 49 54 45  NTEGER], [SQLITE
2c8c0 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45  _FLOAT], [SQLITE
2c8d0 5f 54 45 58 54 5d 2c 20 6f 72 0a 2a 2a 20 20 20  _TEXT], or.**   
2c8e0 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 42         [SQLITE_B
2c8f0 4c 4f 42 5d 20 61 73 20 61 70 70 72 6f 70 72 69  LOB] as appropri
2c900 61 74 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20  ate for.**      
2c910 20 20 20 20 74 68 65 20 5b 70 72 6f 74 65 63 74      the [protect
2c920 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2c930 5d 20 6f 62 6a 65 63 74 20 56 20 61 66 74 65 72  ] object V after
2c940 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20   the conversion 
2c950 61 74 74 65 6d 70 74 2e 0a 2a 2f 0a 63 6f 6e 73  attempt..*/.cons
2c960 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
2c970 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74  value_blob(sqlit
2c980 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
2c990 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
2c9a0 74 65 73 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  tes(sqlite3_valu
2c9b0 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
2c9c0 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 73  _value_bytes16(s
2c9d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
2c9e0 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 76  double sqlite3_v
2c9f0 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69  alue_double(sqli
2ca00 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
2ca10 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69   sqlite3_value_i
2ca20 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt(sqlite3_value
2ca30 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  *);.sqlite3_int6
2ca40 34 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  4 sqlite3_value_
2ca50 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 76 61  int64(sqlite3_va
2ca60 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e 73  lue*);.const uns
2ca70 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69  igned char *sqli
2ca80 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 73  te3_value_text(s
2ca90 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
2caa0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
2cab0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
2cac0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
2cad0 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
2cae0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
2caf0 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  16le(sqlite3_val
2cb00 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  ue*);.const void
2cb10 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
2cb20 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33  text16be(sqlite3
2cb30 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
2cb40 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65  lite3_value_type
2cb50 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
2cb60 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  ;.int sqlite3_va
2cb70 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65  lue_numeric_type
2cb80 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
2cb90 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2cba0 46 3a 20 4f 62 74 61 69 6e 20 41 67 67 72 65 67  F: Obtain Aggreg
2cbb0 61 74 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e  ate Function Con
2cbc0 74 65 78 74 20 7b 46 31 36 32 31 30 7d 0a 2a 2a  text {F16210}.**
2cbd0 0a 2a 2a 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e  .** The implemen
2cbe0 74 61 74 69 6f 6e 20 6f 66 20 61 67 67 72 65 67  tation of aggreg
2cbf0 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ate SQL function
2cc00 73 20 75 73 65 20 74 68 69 73 20 72 6f 75 74 69  s use this routi
2cc10 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 0a 2a  ne to allocate.*
2cc20 2a 20 61 20 73 74 72 75 63 74 75 72 65 20 66 6f  * a structure fo
2cc30 72 20 73 74 6f 72 69 6e 67 20 74 68 65 69 72 20  r storing their 
2cc40 73 74 61 74 65 2e 20 20 0a 2a 2a 20 54 68 65 20  state.  .** The 
2cc50 66 69 72 73 74 20 74 69 6d 65 20 74 68 65 20 73  first time the s
2cc60 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
2cc70 5f 63 6f 6e 74 65 78 74 28 29 20 72 6f 75 74 69  _context() routi
2cc80 6e 65 20 69 73 0a 2a 2a 20 69 73 20 63 61 6c 6c  ne is.** is call
2cc90 65 64 20 66 6f 72 20 61 20 70 61 72 74 69 63 75  ed for a particu
2cca0 6c 61 72 20 61 67 67 72 65 67 61 74 65 2c 20 53  lar aggregate, S
2ccb0 51 4c 69 74 65 20 61 6c 6c 6f 63 61 74 65 73 20  QLite allocates 
2ccc0 6e 42 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79  nBytes of memory
2ccd0 0a 2a 2a 20 7a 65 72 6f 73 20 74 68 61 74 20 6d  .** zeros that m
2cce0 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72  emory, and retur
2ccf0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
2cd00 69 74 2e 0a 2a 2a 20 4f 6e 20 73 65 63 6f 6e 64  it..** On second
2cd10 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20   and subsequent 
2cd20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
2cd30 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
2cd40 78 74 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20  xt().** for the 
2cd50 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 66  same aggregate f
2cd60 75 6e 63 74 69 6f 6e 20 69 6e 64 65 78 2c 20 74  unction index, t
2cd70 68 65 20 73 61 6d 65 20 62 75 66 66 65 72 20 69  he same buffer i
2cd80 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 54  s returned..** T
2cd90 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
2cda0 6e 0a 2a 2a 20 6f 66 20 74 68 65 20 61 67 67 72  n.** of the aggr
2cdb0 65 67 61 74 65 20 63 61 6e 20 75 73 65 20 74 68  egate can use th
2cdc0 65 20 72 65 74 75 72 6e 65 64 20 62 75 66 66 65  e returned buffe
2cdd0 72 20 74 6f 20 61 63 63 75 6d 75 6c 61 74 65 20  r to accumulate 
2cde0 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  data..**.** SQLi
2cdf0 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  te automatically
2ce00 20 66 72 65 65 73 20 74 68 65 20 61 6c 6c 6f 63   frees the alloc
2ce10 61 74 65 64 20 62 75 66 66 65 72 20 77 68 65 6e  ated buffer when
2ce20 20 74 68 65 20 61 67 67 72 65 67 61 74 65 0a 2a   the aggregate.*
2ce30 2a 20 71 75 65 72 79 20 63 6f 6e 63 6c 75 64 65  * query conclude
2ce40 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  s..**.** The fir
2ce50 73 74 20 70 61 72 61 6d 65 74 65 72 20 73 68 6f  st parameter sho
2ce60 75 6c 64 20 62 65 20 61 20 63 6f 70 79 20 6f 66  uld be a copy of
2ce70 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65   the .** [sqlite
2ce80 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20  3_context | SQL 
2ce90 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74  function context
2cea0 5d 20 74 68 61 74 20 69 73 20 74 68 65 20 66 69  ] that is the fi
2ceb0 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  rst.** parameter
2cec0 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
2ced0 20 72 6f 75 74 69 6e 65 20 74 68 61 74 20 69 6d   routine that im
2cee0 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 61 67 67  plements the agg
2cef0 72 65 67 61 74 65 0a 2a 2a 20 66 75 6e 63 74 69  regate.** functi
2cf00 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  on..**.** This r
2cf10 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63  outine must be c
2cf20 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73  alled from the s
2cf30 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68  ame thread in wh
2cf40 69 63 68 0a 2a 2a 20 74 68 65 20 61 67 67 72 65  ich.** the aggre
2cf50 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  gate SQL functio
2cf60 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a  n is running..**
2cf70 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
2cf80 2a 2a 0a 2a 2a 20 7b 46 31 36 32 31 31 7d 20 54  **.** {F16211} T
2cf90 68 65 20 66 69 72 73 74 20 69 6e 76 6f 63 61 74  he first invocat
2cfa0 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ion of [sqlite3_
2cfb0 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
2cfc0 74 28 43 2c 4e 29 5d 20 66 6f 72 0a 2a 2a 20 20  t(C,N)] for.**  
2cfd0 20 20 20 20 20 20 20 20 61 20 70 61 72 74 69 63          a partic
2cfe0 75 6c 61 72 20 69 6e 73 74 61 6e 63 65 20 6f 66  ular instance of
2cff0 20 61 6e 20 61 67 67 72 65 67 61 74 65 20 66 75   an aggregate fu
2d000 6e 63 74 69 6f 6e 20 28 66 6f 72 20 61 20 70 61  nction (for a pa
2d010 72 74 69 63 75 6c 61 72 0a 2a 2a 20 20 20 20 20  rticular.**     
2d020 20 20 20 20 20 63 6f 6e 74 65 78 74 20 43 29 20       context C) 
2d030 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f  causes SQLite to
2d040 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 4e 20 62 79   allocation N by
2d050 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2c 0a 2a  tes of memory,.*
2d060 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 20  *          zero 
2d070 74 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64  that memory, and
2d080 20 72 65 74 75 72 6e 20 61 20 70 6f 69 6e 74 65   return a pointe
2d090 72 20 74 6f 20 74 68 65 20 61 6c 6c 6f 63 61 74  r to the allocat
2d0a0 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d  ed.**          m
2d0b0 65 6d 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  emory..**.** {F1
2d0c0 36 32 31 33 7d 20 49 66 20 61 20 6d 65 6d 6f 72  6213} If a memor
2d0d0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72  y allocation err
2d0e0 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67  or occurs during
2d0f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
2d100 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
2d110 63 6f 6e 74 65 78 74 28 43 2c 4e 29 5d 20 74 68  context(C,N)] th
2d120 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  en the function 
2d130 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 0a 2a 2a  returns 0..**.**
2d140 20 7b 46 31 36 32 31 35 7d 20 53 65 63 6f 6e 64   {F16215} Second
2d150 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20   and subsequent 
2d160 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 0a 2a  invocations of.*
2d170 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
2d180 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
2d190 6e 74 65 78 74 28 43 2c 4e 29 5d 20 66 6f 72 20  ntext(C,N)] for 
2d1a0 74 68 65 20 73 61 6d 65 20 63 6f 6e 74 65 78 74  the same context
2d1b0 20 70 6f 69 6e 74 65 72 20 43 0a 2a 2a 20 20 20   pointer C.**   
2d1c0 20 20 20 20 20 20 20 69 67 6e 6f 72 65 20 74 68         ignore th
2d1d0 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 61 6e  e N parameter an
2d1e0 64 20 72 65 74 75 72 6e 20 61 20 70 6f 69 6e 74  d return a point
2d1f0 65 72 20 74 6f 20 74 68 65 20 73 61 6d 65 0a 2a  er to the same.*
2d200 2a 20 20 20 20 20 20 20 20 20 20 62 6c 6f 63 6b  *          block
2d210 20 6f 66 20 6d 65 6d 6f 72 79 20 72 65 74 75 72   of memory retur
2d220 6e 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  ned by the first
2d230 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a   invocation..**.
2d240 2a 2a 20 7b 46 31 36 32 31 37 7d 20 54 68 65 20  ** {F16217} The 
2d250 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 64  memory allocated
2d260 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 61 67 67   by [sqlite3_agg
2d270 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43  regate_context(C
2d280 2c 4e 29 5d 20 69 73 0a 2a 2a 20 20 20 20 20 20  ,N)] is.**      
2d290 20 20 20 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c      automaticall
2d2a0 79 20 66 72 65 65 64 20 6f 6e 20 74 68 65 20 6e  y freed on the n
2d2b0 65 78 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ext call to [sql
2d2c0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a  ite3_reset()].**
2d2d0 20 20 20 20 20 20 20 20 20 20 6f 72 20 5b 73 71            or [sq
2d2e0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
2d2f0 5d 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70 61  ] for the [prepa
2d300 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 63  red statement] c
2d310 6f 6e 74 61 69 6e 69 6e 67 0a 2a 2a 20 20 20 20  ontaining.**    
2d320 20 20 20 20 20 20 74 68 65 20 61 67 67 72 65 67        the aggreg
2d330 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 61 73 73  ate function ass
2d340 6f 63 69 61 74 65 64 20 77 69 74 68 20 63 6f 6e  ociated with con
2d350 74 65 78 74 20 43 2e 0a 2a 2f 0a 76 6f 69 64 20  text C..*/.void 
2d360 2a 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61  *sqlite3_aggrega
2d370 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69 74  te_context(sqlit
2d380 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
2d390 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a   nBytes);../*.**
2d3a0 20 43 41 50 49 33 52 45 46 3a 20 55 73 65 72 20   CAPI3REF: User 
2d3b0 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74 69 6f  Data For Functio
2d3c0 6e 73 20 7b 46 31 36 32 34 30 7d 0a 2a 2a 0a 2a  ns {F16240}.**.*
2d3d0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 73  * The sqlite3_us
2d3e0 65 72 5f 64 61 74 61 28 29 20 69 6e 74 65 72 66  er_data() interf
2d3f0 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f  ace returns a co
2d400 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69  py of.** the poi
2d410 6e 74 65 72 20 74 68 61 74 20 77 61 73 20 74 68  nter that was th
2d420 65 20 70 55 73 65 72 44 61 74 61 20 70 61 72 61  e pUserData para
2d430 6d 65 74 65 72 20 28 74 68 65 20 35 74 68 20 70  meter (the 5th p
2d440 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20  arameter).** of 
2d450 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  the [sqlite3_cre
2d460 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a  ate_function()].
2d470 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
2d480 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
2d490 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68  6()] routines th
2d4a0 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a  at originally.**
2d4b0 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20   registered the 
2d4c0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69  application defi
2d4d0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 7b 45  ned function. {E
2d4e0 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  ND}.**.** This r
2d4f0 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63  outine must be c
2d500 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73  alled from the s
2d510 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68  ame thread in wh
2d520 69 63 68 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69  ich.** the appli
2d530 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
2d540 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
2d550 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  ng..**.** INVARI
2d560 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  ANTS:.**.** {F16
2d570 32 34 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  243} The [sqlite
2d580 33 5f 75 73 65 72 5f 64 61 74 61 28 43 29 5d 20  3_user_data(C)] 
2d590 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2d5a0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a  s a copy of the.
2d5b0 2a 2a 20 20 20 20 20 20 20 20 20 20 50 20 70 6f  **          P po
2d5c0 69 6e 74 65 72 20 66 72 6f 6d 20 74 68 65 20 5b  inter from the [
2d5d0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2d5e0 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c  unction(D,X,N,E,
2d5f0 50 2c 46 2c 53 2c 4c 29 5d 0a 2a 2a 20 20 20 20  P,F,S,L)].**    
2d600 20 20 20 20 20 20 6f 72 20 5b 73 71 6c 69 74 65        or [sqlite
2d610 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2d620 6e 31 36 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c  n16(D,X,N,E,P,F,
2d630 53 2c 4c 29 5d 20 63 61 6c 6c 20 74 68 61 74 0a  S,L)] call that.
2d640 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 67 69  **          regi
2d650 73 74 65 72 65 64 20 74 68 65 20 53 51 4c 20 66  stered the SQL f
2d660 75 6e 63 74 69 6f 6e 20 61 73 73 6f 63 69 61 74  unction associat
2d670 65 64 20 77 69 74 68 20 0a 2a 2a 20 20 20 20 20  ed with .**     
2d680 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f       [sqlite3_co
2d690 6e 74 65 78 74 5d 20 43 2e 0a 2a 2f 0a 76 6f 69  ntext] C..*/.voi
2d6a0 64 20 2a 73 71 6c 69 74 65 33 5f 75 73 65 72 5f  d *sqlite3_user_
2d6b0 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e  data(sqlite3_con
2d6c0 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  text*);../*.** C
2d6d0 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73  API3REF: Databas
2d6e0 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72  e Connection For
2d6f0 20 46 75 6e 63 74 69 6f 6e 73 20 7b 46 31 36 32   Functions {F162
2d700 35 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  50}.**.** The sq
2d710 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62  lite3_context_db
2d720 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74 65 72 66  _handle() interf
2d730 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f  ace returns a co
2d740 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69  py of.** the poi
2d750 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 64 61 74  nter to the [dat
2d760 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2d770 5d 20 28 74 68 65 20 31 73 74 20 70 61 72 61 6d  ] (the 1st param
2d780 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20  eter).** of the 
2d790 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2d7a0 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61  function()].** a
2d7b0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
2d7c0 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
2d7d0 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f   routines that o
2d7e0 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67  riginally.** reg
2d7f0 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c  istered the appl
2d800 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20  ication defined 
2d810 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  function..**.** 
2d820 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
2d830 2a 20 7b 46 31 36 32 35 33 7d 20 54 68 65 20 5b  * {F16253} The [
2d840 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f  sqlite3_context_
2d850 64 62 5f 68 61 6e 64 6c 65 28 43 29 5d 20 69 6e  db_handle(C)] in
2d860 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2d870 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a  a copy of the.**
2d880 20 20 20 20 20 20 20 20 20 20 44 20 70 6f 69 6e            D poin
2d890 74 65 72 20 66 72 6f 6d 20 74 68 65 20 5b 73 71  ter from the [sq
2d8a0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2d8b0 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c  ction(D,X,N,E,P,
2d8c0 46 2c 53 2c 4c 29 5d 0a 2a 2a 20 20 20 20 20 20  F,S,L)].**      
2d8d0 20 20 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f      or [sqlite3_
2d8e0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
2d8f0 36 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c  6(D,X,N,E,P,F,S,
2d900 4c 29 5d 20 63 61 6c 6c 20 74 68 61 74 0a 2a 2a  L)] call that.**
2d910 20 20 20 20 20 20 20 20 20 20 72 65 67 69 73 74            regist
2d920 65 72 65 64 20 74 68 65 20 53 51 4c 20 66 75 6e  ered the SQL fun
2d930 63 74 69 6f 6e 20 61 73 73 6f 63 69 61 74 65 64  ction associated
2d940 20 77 69 74 68 20 0a 2a 2a 20 20 20 20 20 20 20   with .**       
2d950 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74     [sqlite3_cont
2d960 65 78 74 5d 20 43 2e 0a 2a 2f 0a 73 71 6c 69 74  ext] C..*/.sqlit
2d970 65 33 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6e 74  e3 *sqlite3_cont
2d980 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71  ext_db_handle(sq
2d990 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
2d9a0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2d9b0 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c  : Function Auxil
2d9c0 69 61 72 79 20 44 61 74 61 20 7b 46 31 36 32 37  iary Data {F1627
2d9d0 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c  0}.**.** The fol
2d9e0 6c 6f 77 69 6e 67 20 74 77 6f 20 66 75 6e 63 74  lowing two funct
2d9f0 69 6f 6e 73 20 6d 61 79 20 62 65 20 75 73 65 64  ions may be used
2da00 20 62 79 20 73 63 61 6c 61 72 20 53 51 4c 20 66   by scalar SQL f
2da10 75 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61  unctions to.** a
2da20 73 73 6f 63 69 61 74 65 20 6d 65 74 61 2d 64 61  ssociate meta-da
2da30 74 61 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74  ta with argument
2da40 20 76 61 6c 75 65 73 2e 20 49 66 20 74 68 65 20   values. If the 
2da50 73 61 6d 65 20 76 61 6c 75 65 20 69 73 20 70 61  same value is pa
2da60 73 73 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69  ssed to.** multi
2da70 70 6c 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20  ple invocations 
2da80 6f 66 20 74 68 65 20 73 61 6d 65 20 53 51 4c 20  of the same SQL 
2da90 66 75 6e 63 74 69 6f 6e 20 64 75 72 69 6e 67 20  function during 
2daa0 71 75 65 72 79 20 65 78 65 63 75 74 69 6f 6e 2c  query execution,
2dab0 20 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63   under.** some c
2dac0 69 72 63 75 6d 73 74 61 6e 63 65 73 20 74 68 65  ircumstances the
2dad0 20 61 73 73 6f 63 69 61 74 65 64 20 6d 65 74 61   associated meta
2dae0 2d 64 61 74 61 20 6d 61 79 20 62 65 20 70 72 65  -data may be pre
2daf0 73 65 72 76 65 64 2e 20 54 68 69 73 20 6d 61 79  served. This may
2db00 0a 2a 2a 20 62 65 20 75 73 65 64 2c 20 66 6f 72  .** be used, for
2db10 20 65 78 61 6d 70 6c 65 2c 20 74 6f 20 61 64 64   example, to add
2db20 20 61 20 72 65 67 75 6c 61 72 2d 65 78 70 72 65   a regular-expre
2db30 73 73 69 6f 6e 20 6d 61 74 63 68 69 6e 67 20 73  ssion matching s
2db40 63 61 6c 61 72 0a 2a 2a 20 66 75 6e 63 74 69 6f  calar.** functio
2db50 6e 2e 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20  n. The compiled 
2db60 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 72  version of the r
2db70 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f  egular expressio
2db80 6e 20 69 73 20 73 74 6f 72 65 64 20 61 73 0a 2a  n is stored as.*
2db90 2a 20 6d 65 74 61 2d 64 61 74 61 20 61 73 73 6f  * meta-data asso
2dba0 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
2dbb0 53 51 4c 20 76 61 6c 75 65 20 70 61 73 73 65 64  SQL value passed
2dbc0 20 61 73 20 74 68 65 20 72 65 67 75 6c 61 72 20   as the regular 
2dbd0 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 70 61  expression.** pa
2dbe0 74 74 65 72 6e 2e 20 20 54 68 65 20 63 6f 6d 70  ttern.  The comp
2dbf0 69 6c 65 64 20 72 65 67 75 6c 61 72 20 65 78 70  iled regular exp
2dc00 72 65 73 73 69 6f 6e 20 63 61 6e 20 62 65 20 72  ression can be r
2dc10 65 75 73 65 64 20 6f 6e 20 6d 75 6c 74 69 70 6c  eused on multipl
2dc20 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73  e.** invocations
2dc30 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e   of the same fun
2dc40 63 74 69 6f 6e 20 73 6f 20 74 68 61 74 20 74 68  ction so that th
2dc50 65 20 6f 72 69 67 69 6e 61 6c 20 70 61 74 74 65  e original patte
2dc60 72 6e 20 73 74 72 69 6e 67 0a 2a 2a 20 64 6f 65  rn string.** doe
2dc70 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65  s not need to be
2dc80 20 72 65 63 6f 6d 70 69 6c 65 64 20 6f 6e 20 65   recompiled on e
2dc90 61 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a  ach invocation..
2dca0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
2dcb0 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_get_auxdata() 
2dcc0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2dcd0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
2dce0 68 65 20 6d 65 74 61 2d 64 61 74 61 0a 2a 2a 20  he meta-data.** 
2dcf0 61 73 73 6f 63 69 61 74 65 64 20 62 79 20 74 68  associated by th
2dd00 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  e sqlite3_set_au
2dd10 78 64 61 74 61 28 29 20 66 75 6e 63 74 69 6f 6e  xdata() function
2dd20 20 77 69 74 68 20 74 68 65 20 4e 74 68 20 61 72   with the Nth ar
2dd30 67 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 20  gument.** value 
2dd40 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  to the applicati
2dd50 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
2dd60 69 6f 6e 2e 0a 2a 2a 20 49 66 20 6e 6f 20 6d 65  ion..** If no me
2dd70 74 61 2d 64 61 74 61 20 68 61 73 20 62 65 65 6e  ta-data has been
2dd80 20 65 76 65 72 20 62 65 65 6e 20 73 65 74 20 66   ever been set f
2dd90 6f 72 20 74 68 65 20 4e 74 68 0a 2a 2a 20 61 72  or the Nth.** ar
2dda0 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 66 75  gument of the fu
2ddb0 6e 63 74 69 6f 6e 2c 20 6f 72 20 69 66 20 74 68  nction, or if th
2ddc0 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
2ddd0 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74  function paramet
2dde0 65 72 0a 2a 2a 20 68 61 73 20 63 68 61 6e 67 65  er.** has change
2ddf0 64 20 73 69 6e 63 65 20 74 68 65 20 6d 65 74 61  d since the meta
2de00 2d 64 61 74 61 20 77 61 73 20 73 65 74 2c 20 74  -data was set, t
2de10 68 65 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  hen sqlite3_get_
2de20 61 75 78 64 61 74 61 28 29 0a 2a 2a 20 72 65 74  auxdata().** ret
2de30 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  urns a NULL poin
2de40 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ter..**.** The s
2de50 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
2de60 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  ta() interface s
2de70 61 76 65 73 20 74 68 65 20 6d 65 74 61 2d 64 61  aves the meta-da
2de80 74 61 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f  ta.** pointed to
2de90 20 62 79 20 69 74 73 20 33 72 64 20 70 61 72 61   by its 3rd para
2dea0 6d 65 74 65 72 20 61 73 20 74 68 65 20 6d 65 74  meter as the met
2deb0 61 2d 64 61 74 61 20 66 6f 72 20 74 68 65 20 4e  a-data for the N
2dec0 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  -th.** argument 
2ded0 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
2dee0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
2def0 69 6f 6e 2e 20 20 53 75 62 73 65 71 75 65 6e 74  ion.  Subsequent
2df00 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  .** calls to sql
2df10 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
2df20 28 29 20 6d 69 67 68 74 20 72 65 74 75 72 6e 20  () might return 
2df30 74 68 69 73 20 64 61 74 61 2c 20 69 66 20 69 74  this data, if it
2df40 20 68 61 73 0a 2a 2a 20 6e 6f 74 20 62 65 65 6e   has.** not been
2df50 20 64 65 73 74 72 6f 79 65 64 2e 20 0a 2a 2a 20   destroyed. .** 
2df60 49 66 20 69 74 20 69 73 20 6e 6f 74 20 4e 55 4c  If it is not NUL
2df70 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69  L, SQLite will i
2df80 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75  nvoke the destru
2df90 63 74 6f 72 20 0a 2a 2a 20 66 75 6e 63 74 69 6f  ctor .** functio
2dfa0 6e 20 67 69 76 65 6e 20 62 79 20 74 68 65 20 34  n given by the 4
2dfb0 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
2dfc0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
2dfd0 61 74 61 28 29 20 6f 6e 0a 2a 2a 20 74 68 65 20  ata() on.** the 
2dfe0 6d 65 74 61 2d 64 61 74 61 20 77 68 65 6e 20 74  meta-data when t
2dff0 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
2e000 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65   function parame
2e010 74 65 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f  ter changes.** o
2e020 72 20 77 68 65 6e 20 74 68 65 20 53 51 4c 20 73  r when the SQL s
2e030 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 6c 65 74  tatement complet
2e040 65 73 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f  es, whichever co
2e050 6d 65 73 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a  mes first..**.**
2e060 20 53 51 4c 69 74 65 20 69 73 20 66 72 65 65 20   SQLite is free 
2e070 74 6f 20 63 61 6c 6c 20 74 68 65 20 64 65 73 74  to call the dest
2e080 72 75 63 74 6f 72 20 61 6e 64 20 64 72 6f 70 20  ructor and drop 
2e090 6d 65 74 61 2d 64 61 74 61 20 6f 6e 0a 2a 2a 20  meta-data on.** 
2e0a0 61 6e 79 20 70 61 72 61 6d 65 74 65 72 20 6f 66  any parameter of
2e0b0 20 61 6e 79 20 66 75 6e 63 74 69 6f 6e 20 61 74   any function at
2e0c0 20 61 6e 79 20 74 69 6d 65 2e 20 20 54 68 65 20   any time.  The 
2e0d0 6f 6e 6c 79 20 67 75 61 72 61 6e 74 65 65 0a 2a  only guarantee.*
2e0e0 2a 20 69 73 20 74 68 61 74 20 74 68 65 20 64 65  * is that the de
2e0f0 73 74 72 75 63 74 6f 72 20 77 69 6c 6c 20 62 65  structor will be
2e100 20 63 61 6c 6c 65 64 20 62 65 66 6f 72 65 20 74   called before t
2e110 68 65 20 6d 65 74 61 64 61 74 61 20 69 73 0a 2a  he metadata is.*
2e120 2a 20 64 72 6f 70 70 65 64 2e 0a 2a 2a 0a 2a 2a  * dropped..**.**
2e130 20 49 6e 20 70 72 61 63 74 69 63 65 2c 20 6d 65   In practice, me
2e140 74 61 2d 64 61 74 61 20 69 73 20 70 72 65 73 65  ta-data is prese
2e150 72 76 65 64 20 62 65 74 77 65 65 6e 20 66 75 6e  rved between fun
2e160 63 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a  ction calls for.
2e170 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 73 20 74  ** expressions t
2e180 68 61 74 20 61 72 65 20 63 6f 6e 73 74 61 6e 74  hat are constant
2e190 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65   at compile time
2e1a0 2e 20 54 68 69 73 20 69 6e 63 6c 75 64 65 73 20  . This includes 
2e1b0 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65  literal.** value
2e1c0 73 20 61 6e 64 20 53 51 4c 20 76 61 72 69 61 62  s and SQL variab
2e1d0 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  les..**.** These
2e1e0 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62   routines must b
2e1f0 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
2e200 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e  e same thread in
2e210 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51   which.** the SQ
2e220 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  L function is ru
2e230 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  nning..**.** INV
2e240 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
2e250 46 31 36 32 37 32 7d 20 54 68 65 20 5b 73 71 6c  F16272} The [sql
2e260 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
2e270 28 43 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  (C,N)] interface
2e280 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
2e290 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  er.**          t
2e2a0 6f 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63  o metadata assoc
2e2b0 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 4e  iated with the N
2e2c0 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  th parameter of 
2e2d0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
2e2e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68 6f  .**          who
2e2f0 73 65 20 63 6f 6e 74 65 78 74 20 69 73 20 43 2c  se context is C,
2e300 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 72   or NULL if ther
2e310 65 20 69 73 20 6e 6f 20 6d 65 74 61 64 61 74 61  e is no metadata
2e320 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 20   associated.**  
2e330 20 20 20 20 20 20 20 20 77 69 74 68 20 74 68 61          with tha
2e340 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  t parameter..**.
2e350 2a 2a 20 7b 46 31 36 32 37 34 7d 20 54 68 65 20  ** {F16274} The 
2e360 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78  [sqlite3_set_aux
2e370 64 61 74 61 28 43 2c 4e 2c 50 2c 44 29 5d 20 69  data(C,N,P,D)] i
2e380 6e 74 65 72 66 61 63 65 20 61 73 73 69 67 6e 73  nterface assigns
2e390 20 61 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 20   a metadata.**  
2e3a0 20 20 20 20 20 20 20 20 70 6f 69 6e 74 65 72 20          pointer 
2e3b0 50 20 74 6f 20 74 68 65 20 4e 74 68 20 70 61 72  P to the Nth par
2e3c0 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20 53 51  ameter of the SQ
2e3d0 4c 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20  L function with 
2e3e0 63 6f 6e 74 65 78 74 0a 2a 2a 20 20 20 20 20 20  context.**      
2e3f0 20 20 20 20 43 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31      C..**.** {F1
2e400 36 32 37 36 7d 20 53 51 4c 69 74 65 20 77 69 6c  6276} SQLite wil
2e410 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73  l invoke the des
2e420 74 72 75 63 74 6f 72 20 44 20 77 69 74 68 20 61  tructor D with a
2e430 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
2e440 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68 69  .**          whi
2e450 63 68 20 69 73 20 74 68 65 20 6d 65 74 61 64 61  ch is the metada
2e460 74 61 20 70 6f 69 6e 74 65 72 20 50 20 66 6f 6c  ta pointer P fol
2e470 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f  lowing a call to
2e480 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
2e490 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
2e4a0 61 28 43 2c 4e 2c 50 2c 44 29 5d 20 77 68 65 6e  a(C,N,P,D)] when
2e4b0 20 53 51 4c 69 74 65 20 63 65 61 73 65 73 20 74   SQLite ceases t
2e4c0 6f 20 68 6f 6c 64 0a 2a 2a 20 20 20 20 20 20 20  o hold.**       
2e4d0 20 20 20 74 68 65 20 6d 65 74 61 64 61 74 61 2e     the metadata.
2e4e0 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32 37 37 7d 20  .**.** {F16277} 
2e4f0 53 51 4c 69 74 65 20 63 65 61 73 65 73 20 74 6f  SQLite ceases to
2e500 20 68 6f 6c 64 20 6d 65 74 61 64 61 74 61 20 66   hold metadata f
2e510 6f 72 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69  or an SQL functi
2e520 6f 6e 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  on parameter.** 
2e530 20 20 20 20 20 20 20 20 20 77 68 65 6e 20 74 68           when th
2e540 65 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20  e value of that 
2e550 70 61 72 61 6d 65 74 65 72 20 63 68 61 6e 67 65  parameter change
2e560 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32 37 38  s..**.** {F16278
2e570 7d 20 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f  } When [sqlite3_
2e580 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c  set_auxdata(C,N,
2e590 50 2c 44 29 5d 20 69 73 20 69 6e 76 6f 6b 65 64  P,D)] is invoked
2e5a0 2c 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  , the destructor
2e5b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20  .**          is 
2e5c0 63 61 6c 6c 65 64 20 66 6f 72 20 61 6e 79 20 70  called for any p
2e5d0 72 69 6f 72 20 6d 65 74 61 64 61 74 61 20 61 73  rior metadata as
2e5e0 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
2e5f0 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 0a  e same function.
2e600 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e 74  **          cont
2e610 65 78 74 20 43 20 61 6e 64 20 70 61 72 61 6d 65  ext C and parame
2e620 74 65 72 20 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  ter N..**.** {F1
2e630 36 32 37 39 7d 20 53 51 4c 69 74 65 20 77 69 6c  6279} SQLite wil
2e640 6c 20 63 61 6c 6c 20 64 65 73 74 72 75 63 74 6f  l call destructo
2e650 72 73 20 66 6f 72 20 61 6e 79 20 6d 65 74 61 64  rs for any metad
2e660 61 74 61 20 69 74 20 69 73 20 68 6f 6c 64 69 6e  ata it is holdin
2e670 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  g.**          in
2e680 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 5b 70   a particular [p
2e690 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2e6a0 74 5d 20 53 20 77 68 65 6e 20 65 69 74 68 65 72  t] S when either
2e6b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
2e6c0 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
2e6d0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
2e6e0 6c 69 7a 65 28 53 29 5d 20 69 73 20 63 61 6c 6c  lize(S)] is call
2e6f0 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c  ed..*/.void *sql
2e700 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
2e710 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2e720 2a 2c 20 69 6e 74 20 4e 29 3b 0a 76 6f 69 64 20  *, int N);.void 
2e730 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
2e740 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ata(sqlite3_cont
2e750 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f 69  ext*, int N, voi
2e760 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f 69  d*, void (*)(voi
2e770 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41  d*));.../*.** CA
2e780 50 49 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74  PI3REF: Constant
2e790 73 20 44 65 66 69 6e 69 6e 67 20 53 70 65 63 69  s Defining Speci
2e7a0 61 6c 20 44 65 73 74 72 75 63 74 6f 72 20 42 65  al Destructor Be
2e7b0 68 61 76 69 6f 72 20 7b 46 31 30 32 38 30 7d 0a  havior {F10280}.
2e7c0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20  **.** These are 
2e7d0 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20 66 6f  special value fo
2e7e0 72 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  r the destructor
2e7f0 20 74 68 61 74 20 69 73 20 70 61 73 73 65 64 20   that is passed 
2e800 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e  in as the.** fin
2e810 61 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 72  al argument to r
2e820 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71  outines like [sq
2e830 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
2e840 62 28 29 5d 2e 20 20 49 66 20 74 68 65 20 64 65  b()].  If the de
2e850 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75  structor.** argu
2e860 6d 65 6e 74 20 69 73 20 53 51 4c 49 54 45 5f 53  ment is SQLITE_S
2e870 54 41 54 49 43 2c 20 69 74 20 6d 65 61 6e 73 20  TATIC, it means 
2e880 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74  that the content
2e890 20 70 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e 73   pointer is cons
2e8a0 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c  tant.** and will
2e8b0 20 6e 65 76 65 72 20 63 68 61 6e 67 65 2e 20 20   never change.  
2e8c0 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  It does not need
2e8d0 20 74 6f 20 62 65 20 64 65 73 74 72 6f 79 65 64   to be destroyed
2e8e0 2e 20 20 54 68 65 20 0a 2a 2a 20 53 51 4c 49 54  .  The .** SQLIT
2e8f0 45 5f 54 52 41 4e 53 49 45 4e 54 20 76 61 6c 75  E_TRANSIENT valu
2e900 65 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  e means that the
2e910 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69   content will li
2e920 6b 65 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a  kely change in.*
2e930 2a 20 74 68 65 20 6e 65 61 72 20 66 75 74 75 72  * the near futur
2e940 65 20 61 6e 64 20 74 68 61 74 20 53 51 4c 69 74  e and that SQLit
2e950 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74  e should make it
2e960 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f  s own private co
2e970 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e  py of.** the con
2e980 74 65 6e 74 20 62 65 66 6f 72 65 20 72 65 74 75  tent before retu
2e990 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rning..**.** The
2e9a0 20 74 79 70 65 64 65 66 20 69 73 20 6e 65 63 65   typedef is nece
2e9b0 73 73 61 72 79 20 74 6f 20 77 6f 72 6b 20 61 72  ssary to work ar
2e9c0 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e  ound problems in
2e9d0 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20   certain.** C++ 
2e9e0 63 6f 6d 70 69 6c 65 72 73 2e 20 20 53 65 65 20  compilers.  See 
2e9f0 74 69 63 6b 65 74 20 23 32 31 39 31 2e 0a 2a 2f  ticket #2191..*/
2ea00 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a  .typedef void (*
2ea10 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74  sqlite3_destruct
2ea20 6f 72 5f 74 79 70 65 29 28 76 6f 69 64 2a 29 3b  or_type)(void*);
2ea30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2ea40 53 54 41 54 49 43 20 20 20 20 20 20 28 28 73 71  STATIC      ((sq
2ea50 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72  lite3_destructor
2ea60 5f 74 79 70 65 29 30 29 0a 23 64 65 66 69 6e 65  _type)0).#define
2ea70 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e   SQLITE_TRANSIEN
2ea80 54 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65  T   ((sqlite3_de
2ea90 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 2d 31  structor_type)-1
2eaa0 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  )../*.** CAPI3RE
2eab0 46 3a 20 53 65 74 74 69 6e 67 20 54 68 65 20 52  F: Setting The R
2eac0 65 73 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20  esult Of An SQL 
2ead0 46 75 6e 63 74 69 6f 6e 20 7b 46 31 36 34 30 30  Function {F16400
2eae0 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  }.**.** These ro
2eaf0 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20  utines are used 
2eb00 62 79 20 74 68 65 20 78 46 75 6e 63 20 6f 72 20  by the xFunc or 
2eb10 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73  xFinal callbacks
2eb20 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65   that.** impleme
2eb30 6e 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  nt SQL functions
2eb40 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e   and aggregates.
2eb50 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65    See.** [sqlite
2eb60 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2eb70 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  n()] and [sqlite
2eb80 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2eb90 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64  n16()].** for ad
2eba0 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
2ebb0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tion..**.** Thes
2ebc0 65 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b  e functions work
2ebd0 20 76 65 72 79 20 6d 75 63 68 20 6c 69 6b 65 20   very much like 
2ebe0 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  the .** [sqlite3
2ebf0 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c  _bind_blob | sql
2ec00 69 74 65 33 5f 62 69 6e 64 5f 2a 5d 20 66 61 6d  ite3_bind_*] fam
2ec10 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73  ily of functions
2ec20 20 75 73 65 64 0a 2a 2a 20 74 6f 20 62 69 6e 64   used.** to bind
2ec30 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73 74 20   values to host 
2ec40 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20 70 72  parameters in pr
2ec50 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2ec60 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 74  s..** Refer to t
2ec70 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  he.** [sqlite3_b
2ec80 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74  ind_blob | sqlit
2ec90 65 33 5f 62 69 6e 64 5f 2a 20 64 6f 63 75 6d 65  e3_bind_* docume
2eca0 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 0a 2a 2a 20  ntation] for.** 
2ecb0 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
2ecc0 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  mation..**.** Th
2ecd0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
2ece0 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63  _blob() interfac
2ecf0 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c  e sets the resul
2ed00 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70  t from.** an app
2ed10 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64  lication defined
2ed20 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
2ed30 74 68 65 20 42 4c 4f 42 20 77 68 6f 73 65 20 63  the BLOB whose c
2ed40 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69 6e 74 65  ontent is pointe
2ed50 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68 65 20 73  d.** to by the s
2ed60 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
2ed70 61 6e 64 20 77 68 69 63 68 20 69 73 20 4e 20 62  and which is N b
2ed80 79 74 65 73 20 6c 6f 6e 67 20 77 68 65 72 65 20  ytes long where 
2ed90 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74 68 69 72  N is the.** thir
2eda0 64 20 70 61 72 61 6d 65 74 65 72 2e 20 0a 2a 2a  d parameter. .**
2edb0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
2edc0 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 69  ult_zeroblob() i
2edd0 6e 74 65 72 66 61 63 65 73 20 73 65 74 20 74 68  nterfaces set th
2ede0 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74  e result of.** t
2edf0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
2ee00 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
2ee10 74 6f 20 62 65 20 61 20 42 4c 4f 42 20 63 6f 6e  to be a BLOB con
2ee20 74 61 69 6e 69 6e 67 20 61 6c 6c 20 7a 65 72 6f  taining all zero
2ee30 0a 2a 2a 20 62 79 74 65 73 20 61 6e 64 20 4e 20  .** bytes and N 
2ee40 62 79 74 65 73 20 69 6e 20 73 69 7a 65 2c 20 77  bytes in size, w
2ee50 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 76 61  here N is the va
2ee60 6c 75 65 20 6f 66 20 74 68 65 20 32 6e 64 20 70  lue of the 2nd p
2ee70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
2ee80 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
2ee90 6c 74 5f 64 6f 75 62 6c 65 28 29 20 69 6e 74 65  lt_double() inte
2eea0 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
2eeb0 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e  esult from.** an
2eec0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66   application def
2eed0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
2eee0 20 62 65 20 61 20 66 6c 6f 61 74 69 6e 67 20 70   be a floating p
2eef0 6f 69 6e 74 20 76 61 6c 75 65 20 73 70 65 63 69  oint value speci
2ef00 66 69 65 64 0a 2a 2a 20 62 79 20 69 74 73 20 32  fied.** by its 2
2ef10 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  nd argument..**.
2ef20 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
2ef30 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e  esult_error() an
2ef40 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
2ef50 5f 65 72 72 6f 72 31 36 28 29 20 66 75 6e 63 74  _error16() funct
2ef60 69 6f 6e 73 0a 2a 2a 20 63 61 75 73 65 20 74 68  ions.** cause th
2ef70 65 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51  e implemented SQ
2ef80 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68  L function to th
2ef90 72 6f 77 20 61 6e 20 65 78 63 65 70 74 69 6f 6e  row an exception
2efa0 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73  ..** SQLite uses
2efb0 20 74 68 65 20 73 74 72 69 6e 67 20 70 6f 69 6e   the string poin
2efc0 74 65 64 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a  ted to by the.**
2efd0 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f   2nd parameter o
2efe0 66 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  f sqlite3_result
2eff0 5f 65 72 72 6f 72 28 29 20 6f 72 20 73 71 6c 69  _error() or sqli
2f000 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
2f010 31 36 28 29 0a 2a 2a 20 61 73 20 74 68 65 20 74  16().** as the t
2f020 65 78 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20  ext of an error 
2f030 6d 65 73 73 61 67 65 2e 20 20 53 51 4c 69 74 65  message.  SQLite
2f040 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20   interprets the 
2f050 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65  error.** message
2f060 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c   string from sql
2f070 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
2f080 72 28 29 20 61 73 20 55 54 46 38 2e 20 53 51 4c  r() as UTF8. SQL
2f090 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74  ite.** interpret
2f0a0 73 20 74 68 65 20 73 74 72 69 6e 67 20 66 72 6f  s the string fro
2f0b0 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  m sqlite3_result
2f0c0 5f 65 72 72 6f 72 31 36 28 29 20 61 73 20 55 54  _error16() as UT
2f0d0 46 31 36 20 69 6e 20 6e 61 74 69 76 65 0a 2a 2a  F16 in native.**
2f0e0 20 62 79 74 65 20 6f 72 64 65 72 2e 20 20 49 66   byte order.  If
2f0f0 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
2f100 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
2f110 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a  result_error().*
2f120 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73  * or sqlite3_res
2f130 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73  ult_error16() is
2f140 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 53   negative then S
2f150 51 4c 69 74 65 20 74 61 6b 65 73 20 61 73 20 74  QLite takes as t
2f160 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73  he error.** mess
2f170 61 67 65 20 61 6c 6c 20 74 65 78 74 20 75 70 20  age all text up 
2f180 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 73  through the firs
2f190 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72  t zero character
2f1a0 2e 0a 2a 2a 20 49 66 20 74 68 65 20 74 68 69 72  ..** If the thir
2f1b0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
2f1c0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
2f1d0 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69  ror() or.** sqli
2f1e0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
2f1f0 31 36 28 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  16() is non-nega
2f200 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65  tive then SQLite
2f210 20 74 61 6b 65 73 20 74 68 61 74 20 6d 61 6e 79   takes that many
2f220 0a 2a 2a 20 62 79 74 65 73 20 28 6e 6f 74 20 63  .** bytes (not c
2f230 68 61 72 61 63 74 65 72 73 29 20 66 72 6f 6d 20  haracters) from 
2f240 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
2f250 72 20 61 73 20 74 68 65 20 65 72 72 6f 72 20 6d  r as the error m
2f260 65 73 73 61 67 65 2e 0a 2a 2a 20 54 68 65 20 73  essage..** The s
2f270 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
2f280 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ror() and sqlite
2f290 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
2f2a0 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 6d  ().** routines m
2f2b0 61 6b 65 20 61 20 63 6f 70 79 20 70 72 69 76 61  ake a copy priva
2f2c0 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 65  te copy of the e
2f2d0 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78  rror message tex
2f2e0 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 79  t before.** they
2f2f0 20 72 65 74 75 72 6e 2e 20 20 48 65 6e 63 65 2c   return.  Hence,
2f300 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e   the calling fun
2f310 63 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c 6f  ction can deallo
2f320 63 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66  cate or.** modif
2f330 79 20 74 68 65 20 74 65 78 74 20 61 66 74 65 72  y the text after
2f340 20 74 68 65 79 20 72 65 74 75 72 6e 20 77 69 74   they return wit
2f350 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 54 68  hout harm..** Th
2f360 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
2f370 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29 20 66 75  _error_code() fu
2f380 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65 73 20 74  nction changes t
2f390 68 65 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a  he error code.**
2f3a0 20 72 65 74 75 72 6e 65 64 20 62 79 20 53 51 4c   returned by SQL
2f3b0 69 74 65 20 61 73 20 61 20 72 65 73 75 6c 74 20  ite as a result 
2f3c0 6f 66 20 61 6e 20 65 72 72 6f 72 20 69 6e 20 61  of an error in a
2f3d0 20 66 75 6e 63 74 69 6f 6e 2e 20 20 42 79 20 64   function.  By d
2f3e0 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 20 65  efault,.** the e
2f3f0 72 72 6f 72 20 63 6f 64 65 20 69 73 20 53 51 4c  rror code is SQL
2f400 49 54 45 5f 45 52 52 4f 52 2e 20 20 41 20 73 75  ITE_ERROR.  A su
2f410 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f  bsequent call to
2f420 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2f430 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71  error().** or sq
2f440 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
2f450 6f 72 31 36 28 29 20 72 65 73 65 74 73 20 74 68  or16() resets th
2f460 65 20 65 72 72 6f 72 20 63 6f 64 65 20 74 6f 20  e error code to 
2f470 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a  SQLITE_ERROR..**
2f480 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
2f490 72 65 73 75 6c 74 5f 74 6f 6f 62 69 67 28 29 20  result_toobig() 
2f4a0 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73  interface causes
2f4b0 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 74 68   SQLite.** to th
2f4c0 72 6f 77 20 61 6e 20 65 72 72 6f 72 20 69 6e 64  row an error ind
2f4d0 69 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 73  icating that a s
2f4e0 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73  tring or BLOB is
2f4f0 20 74 6f 20 6c 6f 6e 67 0a 2a 2a 20 74 6f 20 72   to long.** to r
2f500 65 70 72 65 73 65 6e 74 2e 20 20 54 68 65 20 73  epresent.  The s
2f510 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 6f  qlite3_result_no
2f520 6d 65 6d 28 29 20 69 6e 74 65 72 66 61 63 65 0a  mem() interface.
2f530 2a 2a 20 63 61 75 73 65 73 20 53 51 4c 69 74 65  ** causes SQLite
2f540 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 78 63   to throw an exc
2f550 65 70 74 69 6f 6e 20 69 6e 64 69 63 61 74 69 6e  eption indicatin
2f560 67 20 74 68 61 74 20 74 68 65 20 61 0a 2a 2a 20  g that the a.** 
2f570 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
2f580 6e 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20  n failed..**.** 
2f590 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
2f5a0 6c 74 5f 69 6e 74 28 29 20 69 6e 74 65 72 66 61  lt_int() interfa
2f5b0 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75  ce sets the retu
2f5c0 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74  rn value.** of t
2f5d0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
2f5e0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
2f5f0 74 6f 20 62 65 20 74 68 65 20 33 32 2d 62 69 74  to be the 32-bit
2f600 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a   signed integer.
2f610 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69  ** value given i
2f620 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65  n the 2nd argume
2f630 6e 74 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  nt..** The sqlit
2f640 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28  e3_result_int64(
2f650 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
2f660 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
2f670 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c  e.** of the appl
2f680 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2f690 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74  function to be t
2f6a0 68 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  he 64-bit signed
2f6b0 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75   integer.** valu
2f6c0 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32  e given in the 2
2f6d0 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  nd argument..**.
2f6e0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
2f6f0 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e 74  esult_null() int
2f700 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
2f710 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20  return value.** 
2f720 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
2f730 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
2f740 69 6f 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a  ion to be NULL..
2f750 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
2f760 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 29 2c  3_result_text(),
2f770 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2f780 74 65 78 74 31 36 28 29 2c 20 0a 2a 2a 20 73 71  text16(), .** sq
2f790 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
2f7a0 74 31 36 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c  t16le(), and sql
2f7b0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
2f7c0 31 36 62 65 28 29 20 69 6e 74 65 72 66 61 63 65  16be() interface
2f7d0 73 0a 2a 2a 20 73 65 74 20 74 68 65 20 72 65 74  s.** set the ret
2f7e0 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65  urn value of the
2f7f0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
2f800 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
2f810 20 62 65 0a 2a 2a 20 61 20 74 65 78 74 20 73 74   be.** a text st
2f820 72 69 6e 67 20 77 68 69 63 68 20 69 73 20 72 65  ring which is re
2f830 70 72 65 73 65 6e 74 65 64 20 61 73 20 55 54 46  presented as UTF
2f840 2d 38 2c 20 55 54 46 2d 31 36 20 6e 61 74 69 76  -8, UTF-16 nativ
2f850 65 20 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a  e byte order,.**
2f860 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 20 65   UTF-16 little e
2f870 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36  ndian, or UTF-16
2f880 20 62 69 67 20 65 6e 64 69 61 6e 2c 20 72 65 73   big endian, res
2f890 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 53 51  pectively..** SQ
2f8a0 4c 69 74 65 20 74 61 6b 65 73 20 74 68 65 20 74  Lite takes the t
2f8b0 65 78 74 20 72 65 73 75 6c 74 20 66 72 6f 6d 20  ext result from 
2f8c0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
2f8d0 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20  from.** the 2nd 
2f8e0 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65  parameter of the
2f8f0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2f900 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
2f910 2e 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20  ..** If the 3rd 
2f920 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
2f930 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2f940 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
2f950 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c  .** is negative,
2f960 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b   then SQLite tak
2f970 65 73 20 72 65 73 75 6c 74 20 74 65 78 74 20 66  es result text f
2f980 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61  rom the 2nd para
2f990 6d 65 74 65 72 20 0a 2a 2a 20 74 68 72 6f 75 67  meter .** throug
2f9a0 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f  h the first zero
2f9b0 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49   character..** I
2f9c0 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65  f the 3rd parame
2f9d0 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
2f9e0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
2f9f0 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73  interfaces.** is
2fa00 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74   non-negative, t
2fa10 68 65 6e 20 61 73 20 6d 61 6e 79 20 62 79 74 65  hen as many byte
2fa20 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72  s (not character
2fa30 73 29 20 6f 66 20 74 68 65 20 74 65 78 74 0a 2a  s) of the text.*
2fa40 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20  * pointed to by 
2fa50 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
2fa60 72 20 61 72 65 20 74 61 6b 65 6e 20 61 73 20 74  r are taken as t
2fa70 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
2fa80 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 69  efined.** functi
2fa90 6f 6e 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 49 66  on result..** If
2faa0 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74   the 4th paramet
2fab0 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
2fac0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
2fad0 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20  nterfaces.** or 
2fae0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
2faf0 6c 6f 62 20 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c  lob is a non-NUL
2fb00 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20  L pointer, then 
2fb10 53 51 4c 69 74 65 20 63 61 6c 6c 73 20 74 68 61  SQLite calls tha
2fb20 74 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 61 73  t.** function as
2fb30 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
2fb40 6f 6e 20 74 68 65 20 74 65 78 74 20 6f 72 20 62  on the text or b
2fb50 6c 6f 62 20 72 65 73 75 6c 74 20 77 68 65 6e 20  lob result when 
2fb60 69 74 20 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68  it has.** finish
2fb70 65 64 20 75 73 69 6e 67 20 74 68 61 74 20 72 65  ed using that re
2fb80 73 75 6c 74 2e 0a 2a 2a 20 49 66 20 74 68 65 20  sult..** If the 
2fb90 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
2fba0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
2fbb0 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
2fbc0 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  aces.** or sqlit
2fbd0 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69  e3_result_blob i
2fbe0 73 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f  s the special co
2fbf0 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 53 54  nstant SQLITE_ST
2fc00 41 54 49 43 2c 20 74 68 65 6e 0a 2a 2a 20 53 51  ATIC, then.** SQ
2fc10 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 61  Lite assumes tha
2fc20 74 20 74 68 65 20 74 65 78 74 20 6f 72 20 62 6c  t the text or bl
2fc30 6f 62 20 72 65 73 75 6c 74 20 69 73 20 63 6f 6e  ob result is con
2fc40 73 74 61 6e 74 20 73 70 61 63 65 20 61 6e 64 0a  stant space and.
2fc50 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 63 6f 70 79  ** does not copy
2fc60 20 74 68 65 20 73 70 61 63 65 20 6f 72 20 63 61   the space or ca
2fc70 6c 6c 20 61 20 64 65 73 74 72 75 63 74 6f 72 20  ll a destructor 
2fc80 77 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20 66  when it has.** f
2fc90 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68  inished using th
2fca0 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 49 66  at result..** If
2fcb0 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74   the 4th paramet
2fcc0 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
2fcd0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
2fce0 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20  nterfaces.** or 
2fcf0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
2fd00 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65 63 69  lob is the speci
2fd10 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49  al constant SQLI
2fd20 54 45 5f 54 52 41 4e 53 49 45 4e 54 0a 2a 2a 20  TE_TRANSIENT.** 
2fd30 74 68 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65  then SQLite make
2fd40 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
2fd50 72 65 73 75 6c 74 20 69 6e 74 6f 20 73 70 61 63  result into spac
2fd60 65 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a  e obtained from.
2fd70 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ** from [sqlite3
2fd80 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 65 66 6f 72  _malloc()] befor
2fd90 65 20 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  e it returns..**
2fda0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
2fdb0 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69  result_value() i
2fdc0 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
2fdd0 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74  e result of.** t
2fde0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
2fdf0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
2fe00 74 6f 20 62 65 20 61 20 63 6f 70 79 20 74 68 65  to be a copy the
2fe10 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64  .** [unprotected
2fe20 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
2fe30 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 64  object specified
2fe40 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61   by the 2nd para
2fe50 6d 65 74 65 72 2e 20 20 54 68 65 0a 2a 2a 20 73  meter.  The.** s
2fe60 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
2fe70 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  lue() interface 
2fe80 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20  makes a copy of 
2fe90 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  the [sqlite3_val
2fea0 75 65 5d 0a 2a 2a 20 73 6f 20 74 68 61 74 20 5b  ue].** so that [
2feb0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 73  sqlite3_value] s
2fec0 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20  pecified in the 
2fed0 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 63 68  parameter may ch
2fee0 61 6e 67 65 20 6f 72 0a 2a 2a 20 62 65 20 64 65  ange or.** be de
2fef0 61 6c 6c 6f 63 61 74 65 64 20 61 66 74 65 72 20  allocated after 
2ff00 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
2ff10 61 6c 75 65 28 29 20 72 65 74 75 72 6e 73 20 77  alue() returns w
2ff20 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20  ithout harm..** 
2ff30 41 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  A [protected sql
2ff40 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
2ff50 63 74 20 6d 61 79 20 61 6c 77 61 79 73 20 62 65  ct may always be
2ff60 20 75 73 65 64 20 77 68 65 72 65 20 61 6e 0a 2a   used where an.*
2ff70 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  * [unprotected s
2ff80 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
2ff90 6a 65 63 74 20 69 73 20 72 65 71 75 69 72 65 64  ject is required
2ffa0 2c 20 73 6f 20 65 69 74 68 65 72 0a 2a 2a 20 6b  , so either.** k
2ffb0 69 6e 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ind of [sqlite3_
2ffc0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 63 61  value] object ca
2ffd0 6e 20 62 65 20 75 73 65 64 20 77 69 74 68 20 74  n be used with t
2ffe0 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  his interface..*
2fff0 2a 0a 2a 2a 20 49 66 20 74 68 65 73 65 20 72 6f  *.** If these ro
30000 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65  utines are calle
30010 64 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 74 68  d from within th
30020 65 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65  e different thre
30030 61 64 20 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20  ad .** than the 
30040 6f 6e 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  one containing t
30050 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
30060 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
30070 74 68 61 74 20 72 65 63 65 69 76 65 64 0a 2a 2a  that received.**
30080 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
30090 6e 74 65 78 74 5d 20 70 6f 69 6e 74 65 72 2c 20  ntext] pointer, 
300a0 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
300b0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
300c0 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
300d0 2a 2a 20 7b 46 31 36 34 30 33 7d 20 54 68 65 20  ** {F16403} The 
300e0 64 65 66 61 75 6c 74 20 72 65 74 75 72 6e 20 76  default return v
300f0 61 6c 75 65 20 66 72 6f 6d 20 61 6e 79 20 53 51  alue from any SQ
30100 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 4e 55  L function is NU
30110 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 30  LL..**.** {F1640
30120 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  6} The [sqlite3_
30130 72 65 73 75 6c 74 5f 62 6c 6f 62 28 43 2c 56 2c  result_blob(C,V,
30140 4e 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20  N,D)] interface 
30150 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20  changes the.**  
30160 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 76          return v
30170 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e  alue of function
30180 20 43 20 74 6f 20 62 65 20 61 20 62 6c 6f 62 20   C to be a blob 
30190 74 68 61 74 20 69 73 20 4e 20 62 79 74 65 73 0a  that is N bytes.
301a0 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 6c  **          in l
301b0 65 6e 67 74 68 20 61 6e 64 20 77 69 74 68 20 63  ength and with c
301c0 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65 64 20 74  ontent pointed t
301d0 6f 20 62 79 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 46  o by V..**.** {F
301e0 31 36 34 30 39 7d 20 54 68 65 20 5b 73 71 6c 69  16409} The [sqli
301f0 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c  te3_result_doubl
30200 65 28 43 2c 56 29 5d 20 69 6e 74 65 72 66 61 63  e(C,V)] interfac
30210 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a  e changes the.**
30220 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e            return
30230 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69   value of functi
30240 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65 20 66  on C to be the f
30250 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61  loating point va
30260 6c 75 65 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  lue V..**.** {F1
30270 36 34 31 32 7d 20 54 68 65 20 5b 73 71 6c 69 74  6412} The [sqlit
30280 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
30290 43 2c 56 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63  C,V,N)] interfac
302a0 65 20 63 68 61 6e 67 65 73 20 74 68 65 20 72 65  e changes the re
302b0 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  turn.**         
302c0 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69   value of functi
302d0 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e 20 65 78  on C to be an ex
302e0 63 65 70 74 69 6f 6e 20 77 69 74 68 20 65 72 72  ception with err
302f0 6f 72 20 63 6f 64 65 0a 2a 2a 20 20 20 20 20 20  or code.**      
30300 20 20 20 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f      [SQLITE_ERRO
30310 52 5d 20 61 6e 64 20 61 20 55 54 46 38 20 65 72  R] and a UTF8 er
30320 72 6f 72 20 6d 65 73 73 61 67 65 20 63 6f 70 69  ror message copi
30330 65 64 20 66 72 6f 6d 20 56 20 75 70 20 74 6f 20  ed from V up to 
30340 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
30350 66 69 72 73 74 20 7a 65 72 6f 20 62 79 74 65 20  first zero byte 
30360 6f 72 20 75 6e 74 69 6c 20 4e 20 62 79 74 65 73  or until N bytes
30370 20 61 72 65 20 72 65 61 64 20 69 66 20 4e 20 69   are read if N i
30380 73 20 70 6f 73 69 74 69 76 65 2e 0a 2a 2a 0a 2a  s positive..**.*
30390 2a 20 7b 46 31 36 34 31 35 7d 20 54 68 65 20 5b  * {F16415} The [
303a0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
303b0 72 72 6f 72 31 36 28 43 2c 56 2c 4e 29 5d 20 69  rror16(C,V,N)] i
303c0 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73  nterface changes
303d0 20 74 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 20   the return.**  
303e0 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 6f 66          value of
303f0 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62   function C to b
30400 65 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 77  e an exception w
30410 69 74 68 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a  ith error code.*
30420 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49  *          [SQLI
30430 54 45 5f 45 52 52 4f 52 5d 20 61 6e 64 20 61 20  TE_ERROR] and a 
30440 55 54 46 31 36 20 6e 61 74 69 76 65 20 62 79 74  UTF16 native byt
30450 65 20 6f 72 64 65 72 20 65 72 72 6f 72 20 6d 65  e order error me
30460 73 73 61 67 65 0a 2a 2a 20 20 20 20 20 20 20 20  ssage.**        
30470 20 20 63 6f 70 69 65 64 20 66 72 6f 6d 20 56 20    copied from V 
30480 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  up to the first 
30490 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20  zero terminator 
304a0 6f 72 20 75 6e 74 69 6c 20 4e 20 62 79 74 65 73  or until N bytes
304b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 72 65  .**          are
304c0 20 72 65 61 64 20 69 66 20 4e 20 69 73 20 70 6f   read if N is po
304d0 73 69 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46  sitive..**.** {F
304e0 31 36 34 31 38 7d 20 54 68 65 20 5b 73 71 6c 69  16418} The [sqli
304f0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
30500 5f 74 6f 6f 62 69 67 28 43 29 5d 20 69 6e 74 65  _toobig(C)] inte
30510 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68  rface changes th
30520 65 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20  e return.**     
30530 20 20 20 20 20 76 61 6c 75 65 20 6f 66 20 74 68       value of th
30540 65 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20  e function C to 
30550 62 65 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20  be an exception 
30560 77 69 74 68 20 65 72 72 6f 72 20 63 6f 64 65 0a  with error code.
30570 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c  **          [SQL
30580 49 54 45 5f 54 4f 4f 42 49 47 5d 20 61 6e 64 20  ITE_TOOBIG] and 
30590 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 65  an appropriate e
305a0 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a  rror message..**
305b0 0a 2a 2a 20 7b 46 31 36 34 32 31 7d 20 54 68 65  .** {F16421} The
305c0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
305d0 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 43 29 5d  _error_nomem(C)]
305e0 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67   interface chang
305f0 65 73 20 74 68 65 20 72 65 74 75 72 6e 0a 2a 2a  es the return.**
30600 20 20 20 20 20 20 20 20 20 20 76 61 6c 75 65 20            value 
30610 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  of the function 
30620 43 20 74 6f 20 62 65 20 61 6e 20 65 78 63 65 70  C to be an excep
30630 74 69 6f 6e 20 77 69 74 68 20 65 72 72 6f 72 20  tion with error 
30640 63 6f 64 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  code.**         
30650 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20   [SQLITE_NOMEM] 
30660 61 6e 64 20 61 6e 20 61 70 70 72 6f 70 72 69 61  and an appropria
30670 74 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  te error message
30680 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 32 34 7d  ..**.** {F16424}
30690 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   The [sqlite3_re
306a0 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28  sult_error_code(
306b0 43 2c 45 29 5d 20 69 6e 74 65 72 66 61 63 65 20  C,E)] interface 
306c0 63 68 61 6e 67 65 73 20 74 68 65 20 72 65 74 75  changes the retu
306d0 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76  rn.**          v
306e0 61 6c 75 65 20 6f 66 20 74 68 65 20 66 75 6e 63  alue of the func
306f0 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e 20  tion C to be an 
30700 65 78 63 65 70 74 69 6f 6e 20 77 69 74 68 20 65  exception with e
30710 72 72 6f 72 20 63 6f 64 65 20 45 2e 0a 2a 2a 20  rror code E..** 
30720 20 20 20 20 20 20 20 20 20 54 68 65 20 65 72 72           The err
30730 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78 74 20  or message text 
30740 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a  is unchanged..**
30750 0a 2a 2a 20 7b 46 31 36 34 32 37 7d 20 54 68 65  .** {F16427} The
30760 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
30770 5f 69 6e 74 28 43 2c 56 29 5d 20 69 6e 74 65 72  _int(C,V)] inter
30780 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65  face changes the
30790 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74  .**          ret
307a0 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e  urn value of fun
307b0 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68  ction C to be th
307c0 65 20 33 32 2d 62 69 74 20 69 6e 74 65 67 65 72  e 32-bit integer
307d0 20 76 61 6c 75 65 20 56 2e 0a 2a 2a 0a 2a 2a 20   value V..**.** 
307e0 7b 46 31 36 34 33 30 7d 20 54 68 65 20 5b 73 71  {F16430} The [sq
307f0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
30800 36 34 28 43 2c 56 29 5d 20 69 6e 74 65 72 66 61  64(C,V)] interfa
30810 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a  ce changes the.*
30820 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72  *          retur
30830 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74  n value of funct
30840 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65 20  ion C to be the 
30850 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 76  64-bit integer v
30860 61 6c 75 65 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 46  alue V..**.** {F
30870 31 36 34 33 33 7d 20 54 68 65 20 5b 73 71 6c 69  16433} The [sqli
30880 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28  te3_result_null(
30890 43 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68  C)] interface ch
308a0 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20  anges the.**    
308b0 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c        return val
308c0 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43  ue of function C
308d0 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a   to be NULL..**.
308e0 2a 2a 20 7b 46 31 36 34 33 36 7d 20 54 68 65 20  ** {F16436} The 
308f0 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
30900 74 65 78 74 28 43 2c 56 2c 4e 2c 44 29 5d 20 69  text(C,V,N,D)] i
30910 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73  nterface changes
30920 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
30930 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
30940 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62   function C to b
30950 65 20 74 68 65 20 55 54 46 38 20 73 74 72 69 6e  e the UTF8 strin
30960 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 56 20  g.**          V 
30970 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  up to the first 
30980 7a 65 72 6f 20 69 66 20 4e 20 69 73 20 6e 65 67  zero if N is neg
30990 61 74 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20  ative.**        
309a0 20 20 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e    or the first N
309b0 20 62 79 74 65 73 20 6f 66 20 56 20 69 66 20 4e   bytes of V if N
309c0 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
309d0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 33 39 7d  ..**.** {F16439}
309e0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   The [sqlite3_re
309f0 73 75 6c 74 5f 74 65 78 74 31 36 28 43 2c 56 2c  sult_text16(C,V,
30a00 4e 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20  N,D)] interface 
30a10 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20  changes the.**  
30a20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 76          return v
30a30 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e  alue of function
30a40 20 43 20 74 6f 20 62 65 20 74 68 65 20 55 54 46   C to be the UTF
30a50 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  16 native byte o
30a60 72 64 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  rder.**         
30a70 20 73 74 72 69 6e 67 20 56 20 75 70 20 74 6f 20   string V up to 
30a80 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 69  the first zero i
30a90 66 20 4e 20 69 73 0a 2a 2a 20 20 20 20 20 20 20  f N is.**       
30aa0 20 20 20 6e 65 67 61 74 69 76 65 20 6f 72 20 74     negative or t
30ab0 68 65 20 66 69 72 73 74 20 4e 20 62 79 74 65 73  he first N bytes
30ac0 20 6f 66 20 56 20 69 66 20 4e 20 69 73 20 6e 6f   of V if N is no
30ad0 6e 2d 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a  n-negative..**.*
30ae0 2a 20 7b 46 31 36 34 34 32 7d 20 54 68 65 20 5b  * {F16442} The [
30af0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
30b00 65 78 74 31 36 62 65 28 43 2c 56 2c 4e 2c 44 29  ext16be(C,V,N,D)
30b10 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e  ] interface chan
30b20 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  ges the.**      
30b30 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65      return value
30b40 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74   of function C t
30b50 6f 20 62 65 20 74 68 65 20 55 54 46 31 36 20 62  o be the UTF16 b
30b60 69 67 2d 65 6e 64 69 61 6e 0a 2a 2a 20 20 20 20  ig-endian.**    
30b70 20 20 20 20 20 20 73 74 72 69 6e 67 20 56 20 75        string V u
30b80 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a  p to the first z
30b90 65 72 6f 20 69 66 20 4e 20 69 73 0a 2a 2a 20 20  ero if N is.**  
30ba0 20 20 20 20 20 20 20 20 69 73 20 6e 65 67 61 74          is negat
30bb0 69 76 65 20 6f 72 20 74 68 65 20 66 69 72 73 74  ive or the first
30bc0 20 4e 20 62 79 74 65 73 20 6f 72 20 56 20 69 66   N bytes or V if
30bd0 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69   N is non-negati
30be0 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 34  ve..**.** {F1644
30bf0 35 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  5} The [sqlite3_
30c00 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28  result_text16le(
30c10 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74 65 72 66  C,V,N,D)] interf
30c20 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a  ace changes the.
30c30 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75  **          retu
30c40 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63  rn value of func
30c50 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65  tion C to be the
30c60 20 55 54 46 31 36 20 6c 69 74 74 6c 65 2d 65 6e   UTF16 little-en
30c70 64 69 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  dian.**         
30c80 20 73 74 72 69 6e 67 20 56 20 75 70 20 74 6f 20   string V up to 
30c90 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 69  the first zero i
30ca0 66 20 4e 20 69 73 0a 2a 2a 20 20 20 20 20 20 20  f N is.**       
30cb0 20 20 20 6e 65 67 61 74 69 76 65 20 6f 72 20 74     negative or t
30cc0 68 65 20 66 69 72 73 74 20 4e 20 62 79 74 65 73  he first N bytes
30cd0 20 6f 66 20 56 20 69 66 20 4e 20 69 73 20 6e 6f   of V if N is no
30ce0 6e 2d 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a  n-negative..**.*
30cf0 2a 20 7b 46 31 36 34 34 38 7d 20 54 68 65 20 5b  * {F16448} The [
30d00 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
30d10 61 6c 75 65 28 43 2c 56 29 5d 20 69 6e 74 65 72  alue(C,V)] inter
30d20 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65  face changes the
30d30 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74  .**          ret
30d40 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e  urn value of fun
30d50 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 5b 75  ction C to be [u
30d60 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
30d70 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 20 20 20  e3_value].**    
30d80 20 20 20 20 20 20 6f 62 6a 65 63 74 20 56 2e 0a        object V..
30d90 2a 2a 0a 2a 2a 20 7b 46 31 36 34 35 31 7d 20 54  **.** {F16451} T
30da0 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  he [sqlite3_resu
30db0 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 43 2c 4e 29  lt_zeroblob(C,N)
30dc0 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e  ] interface chan
30dd0 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  ges the.**      
30de0 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65      return value
30df0 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74   of function C t
30e00 6f 20 62 65 20 61 6e 20 4e 2d 62 79 74 65 20 62  o be an N-byte b
30e10 6c 6f 62 20 6f 66 20 61 6c 6c 20 7a 65 72 6f 73  lob of all zeros
30e20 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 35 34 7d  ..**.** {F16454}
30e30 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   The [sqlite3_re
30e40 73 75 6c 74 5f 65 72 72 6f 72 28 29 5d 20 61 6e  sult_error()] an
30e50 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  d [sqlite3_resul
30e60 74 5f 65 72 72 6f 72 31 36 28 29 5d 0a 2a 2a 20  t_error16()].** 
30e70 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 66 61           interfa
30e80 63 65 73 20 6d 61 6b 65 20 61 20 63 6f 70 79 20  ces make a copy 
30e90 6f 66 20 74 68 65 69 72 20 65 72 72 6f 72 20 6d  of their error m
30ea0 65 73 73 61 67 65 20 73 74 72 69 6e 67 73 20 62  essage strings b
30eb0 65 66 6f 72 65 0a 2a 2a 20 20 20 20 20 20 20 20  efore.**        
30ec0 20 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a    returning..**.
30ed0 2a 2a 20 7b 46 31 36 34 35 37 7d 20 49 66 20 74  ** {F16457} If t
30ee0 68 65 20 44 20 64 65 73 74 72 75 63 74 6f 72 20  he D destructor 
30ef0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
30f00 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
30f10 62 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20  b(C,V,N,D)],.** 
30f20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
30f30 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 43 2c  3_result_text(C,
30f40 56 2c 4e 2c 44 29 5d 2c 20 5b 73 71 6c 69 74 65  V,N,D)], [sqlite
30f50 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28  3_result_text16(
30f60 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20  C,V,N,D)],.**   
30f70 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
30f80 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28  result_text16be(
30f90 43 2c 56 2c 4e 2c 44 29 5d 2c 20 6f 72 0a 2a 2a  C,V,N,D)], or.**
30fa0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
30fb0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
30fc0 6c 65 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 73 20  le(C,V,N,D)] is 
30fd0 74 68 65 20 63 6f 6e 73 74 61 6e 74 20 5b 53 51  the constant [SQ
30fe0 4c 49 54 45 5f 53 54 41 54 49 43 5d 0a 2a 2a 20  LITE_STATIC].** 
30ff0 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 6e 6f           then no
31000 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 65   destructor is e
31010 76 65 72 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68  ver called on th
31020 65 20 70 6f 69 6e 74 65 72 20 56 20 61 6e 64 20  e pointer V and 
31030 53 51 4c 69 74 65 0a 2a 2a 20 20 20 20 20 20 20  SQLite.**       
31040 20 20 20 61 73 73 75 6d 65 73 20 74 68 61 74 20     assumes that 
31050 56 20 69 73 20 69 6d 6d 75 74 61 62 6c 65 2e 0a  V is immutable..
31060 2a 2a 0a 2a 2a 20 7b 46 31 36 34 36 30 7d 20 49  **.** {F16460} I
31070 66 20 74 68 65 20 44 20 64 65 73 74 72 75 63 74  f the D destruct
31080 6f 72 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  or parameter to 
31090 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
310a0 62 6c 6f 62 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a  blob(C,V,N,D)],.
310b0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
310c0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
310d0 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 5b 73 71 6c  (C,V,N,D)], [sql
310e0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
310f0 31 36 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a  16(C,V,N,D)],.**
31100 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
31110 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
31120 62 65 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 6f 72  be(C,V,N,D)], or
31130 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
31140 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
31150 74 31 36 6c 65 28 43 2c 56 2c 4e 2c 44 29 5d 20  t16le(C,V,N,D)] 
31160 69 73 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 0a  is the constant.
31170 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c  **          [SQL
31180 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 20 74  ITE_TRANSIENT] t
31190 68 65 6e 20 74 68 65 20 69 6e 74 65 72 66 61 63  hen the interfac
311a0 65 73 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20  es makes a copy 
311b0 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  of the.**       
311c0 20 20 20 63 6f 6e 74 65 6e 74 20 6f 66 20 56 20     content of V 
311d0 61 6e 64 20 72 65 74 61 69 6e 73 20 74 68 65 20  and retains the 
311e0 63 6f 70 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  copy..**.** {F16
311f0 34 36 33 7d 20 49 66 20 74 68 65 20 44 20 64 65  463} If the D de
31200 73 74 72 75 63 74 6f 72 20 70 61 72 61 6d 65 74  structor paramet
31210 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  er to [sqlite3_r
31220 65 73 75 6c 74 5f 62 6c 6f 62 28 43 2c 56 2c 4e  esult_blob(C,V,N
31230 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  ,D)],.**        
31240 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c    [sqlite3_resul
31250 74 5f 74 65 78 74 28 43 2c 56 2c 4e 2c 44 29 5d  t_text(C,V,N,D)]
31260 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  , [sqlite3_resul
31270 74 5f 74 65 78 74 31 36 28 43 2c 56 2c 4e 2c 44  t_text16(C,V,N,D
31280 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  )],.**          
31290 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
312a0 74 65 78 74 31 36 62 65 28 43 2c 56 2c 4e 2c 44  text16be(C,V,N,D
312b0 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20  )], or.**       
312c0 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75     [sqlite3_resu
312d0 6c 74 5f 74 65 78 74 31 36 6c 65 28 43 2c 56 2c  lt_text16le(C,V,
312e0 4e 2c 44 29 5d 20 69 73 20 73 6f 6d 65 20 76 61  N,D)] is some va
312f0 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e 0a 2a  lue other than.*
31300 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 63  *          the c
31310 6f 6e 73 74 61 6e 74 73 20 5b 53 51 4c 49 54 45  onstants [SQLITE
31320 5f 53 54 41 54 49 43 5d 20 61 6e 64 20 5b 53 51  _STATIC] and [SQ
31330 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 20  LITE_TRANSIENT] 
31340 74 68 65 6e 20 0a 2a 2a 20 20 20 20 20 20 20 20  then .**        
31350 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e    SQLite will in
31360 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75 63  voke the destruc
31370 74 6f 72 20 44 20 77 69 74 68 20 56 20 61 73 20  tor D with V as 
31380 69 74 73 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e  its only argumen
31390 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68  t.**          wh
313a0 65 6e 20 69 74 20 68 61 73 20 66 69 6e 69 73 68  en it has finish
313b0 65 64 20 77 69 74 68 20 74 68 65 20 56 20 76 61  ed with the V va
313c0 6c 75 65 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  lue..*/.void sql
313d0 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
313e0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
313f0 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
31400 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
31410 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  d*));.void sqlit
31420 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65  e3_result_double
31430 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
31440 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a 76 6f 69 64  *, double);.void
31450 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
31460 65 72 72 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f  error(sqlite3_co
31470 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68  ntext*, const ch
31480 61 72 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20  ar*, int);.void 
31490 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
314a0 72 72 6f 72 31 36 28 73 71 6c 69 74 65 33 5f 63  rror16(sqlite3_c
314b0 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
314c0 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64  oid*, int);.void
314d0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
314e0 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 73 71 6c  error_toobig(sql
314f0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
31500 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
31510 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28  ult_error_nomem(
31520 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
31530 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
31540 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64  result_error_cod
31550 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
31560 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73  t*, int);.void s
31570 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
31580 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t(sqlite3_contex
31590 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73  t*, int);.void s
315a0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
315b0 74 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  t64(sqlite3_cont
315c0 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ext*, sqlite3_in
315d0 74 36 34 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  t64);.void sqlit
315e0 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 73  e3_result_null(s
315f0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
31600 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
31610 65 73 75 6c 74 5f 74 65 78 74 28 73 71 6c 69 74  esult_text(sqlit
31620 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
31630 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 2c 20 76  st char*, int, v
31640 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
31650 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
31660 75 6c 74 5f 74 65 78 74 31 36 28 73 71 6c 69 74  ult_text16(sqlit
31670 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
31680 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76  st void*, int, v
31690 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
316a0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
316b0 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 73 71 6c  ult_text16le(sql
316c0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
316d0 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
316e0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
316f0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
31700 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 73 71  sult_text16be(sq
31710 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
31720 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
31730 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29  ,void(*)(void*))
31740 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
31750 65 73 75 6c 74 5f 76 61 6c 75 65 28 73 71 6c 69  esult_value(sqli
31760 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71  te3_context*, sq
31770 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 76  lite3_value*);.v
31780 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
31790 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69  lt_zeroblob(sqli
317a0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
317b0 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  t n);../*.** CAP
317c0 49 33 52 45 46 3a 20 44 65 66 69 6e 65 20 4e 65  I3REF: Define Ne
317d0 77 20 43 6f 6c 6c 61 74 69 6e 67 20 53 65 71 75  w Collating Sequ
317e0 65 6e 63 65 73 20 7b 46 31 36 36 30 30 7d 0a 2a  ences {F16600}.*
317f0 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74  *.** These funct
31800 69 6f 6e 73 20 61 72 65 20 75 73 65 64 20 74 6f  ions are used to
31810 20 61 64 64 20 6e 65 77 20 63 6f 6c 6c 61 74 69   add new collati
31820 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 74 6f 20  on sequences to 
31830 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 2a  the.** [sqlite3*
31840 5d 20 68 61 6e 64 6c 65 20 73 70 65 63 69 66 69  ] handle specifi
31850 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20  ed as the first 
31860 61 72 67 75 6d 65 6e 74 2e 20 0a 2a 2a 0a 2a 2a  argument. .**.**
31870 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   The name of the
31880 20 6e 65 77 20 63 6f 6c 6c 61 74 69 6f 6e 20 73   new collation s
31890 65 71 75 65 6e 63 65 20 69 73 20 73 70 65 63 69  equence is speci
318a0 66 69 65 64 20 61 73 20 61 20 55 54 46 2d 38 20  fied as a UTF-8 
318b0 73 74 72 69 6e 67 0a 2a 2a 20 66 6f 72 20 73 71  string.** for sq
318c0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
318d0 6c 61 74 69 6f 6e 28 29 20 61 6e 64 20 73 71 6c  lation() and sql
318e0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
318f0 61 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e  ation_v2().** an
31900 64 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e  d a UTF-16 strin
31910 67 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72  g for sqlite3_cr
31920 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36  eate_collation16
31930 28 29 2e 20 49 6e 20 61 6c 6c 20 63 61 73 65 73  (). In all cases
31940 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 69 73 20  .** the name is 
31950 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65  passed as the se
31960 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72  cond function ar
31970 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  gument..**.** Th
31980 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
31990 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66 20 74   may be one of t
319a0 68 65 20 63 6f 6e 73 74 61 6e 74 73 20 5b 53 51  he constants [SQ
319b0 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 5b  LITE_UTF8],.** [
319c0 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 20  SQLITE_UTF16LE] 
319d0 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  or [SQLITE_UTF16
319e0 42 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 20  BE], indicating 
319f0 74 68 61 74 20 74 68 65 20 75 73 65 72 2d 73 75  that the user-su
31a00 70 70 6c 69 65 64 0a 2a 2a 20 72 6f 75 74 69 6e  pplied.** routin
31a10 65 20 65 78 70 65 63 74 73 20 74 6f 20 62 65 20  e expects to be 
31a20 70 61 73 73 65 64 20 70 6f 69 6e 74 65 72 73 20  passed pointers 
31a30 74 6f 20 73 74 72 69 6e 67 73 20 65 6e 63 6f 64  to strings encod
31a40 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38 2c 0a  ed using UTF-8,.
31a50 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65  ** UTF-16 little
31a60 2d 65 6e 64 69 61 6e 20 6f 72 20 55 54 46 2d 31  -endian or UTF-1
31a70 36 20 62 69 67 2d 65 6e 64 69 61 6e 20 72 65 73  6 big-endian res
31a80 70 65 63 74 69 76 65 6c 79 2e 20 54 68 65 0a 2a  pectively. The.*
31a90 2a 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  * third argument
31aa0 20 6d 69 67 68 74 20 61 6c 73 6f 20 62 65 20 5b   might also be [
31ab0 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49  SQLITE_UTF16_ALI
31ac0 47 4e 45 44 5d 20 74 6f 20 69 6e 64 69 63 61 74  GNED] to indicat
31ad0 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 72 6f  e that.** the ro
31ae0 75 74 69 6e 65 20 65 78 70 65 63 74 73 20 70 6f  utine expects po
31af0 69 6e 74 65 72 73 20 74 6f 20 31 36 2d 62 69 74  inters to 16-bit
31b00 20 77 6f 72 64 20 61 6c 69 67 6e 65 64 20 73 74   word aligned st
31b10 72 69 6e 67 73 0a 2a 2a 20 6f 66 20 55 54 46 31  rings.** of UTF1
31b20 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20  6 in the native 
31b30 62 79 74 65 20 6f 72 64 65 72 20 6f 66 20 74 68  byte order of th
31b40 65 20 68 6f 73 74 20 63 6f 6d 70 75 74 65 72 2e  e host computer.
31b50 0a 2a 2a 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72  .**.** A pointer
31b60 20 74 6f 20 74 68 65 20 75 73 65 72 20 73 75 70   to the user sup
31b70 70 6c 69 65 64 20 72 6f 75 74 69 6e 65 20 6d 75  plied routine mu
31b80 73 74 20 62 65 20 70 61 73 73 65 64 20 61 73 20  st be passed as 
31b90 74 68 65 20 66 69 66 74 68 0a 2a 2a 20 61 72 67  the fifth.** arg
31ba0 75 6d 65 6e 74 2e 20 20 49 66 20 69 74 20 69 73  ument.  If it is
31bb0 20 4e 55 4c 4c 2c 20 74 68 69 73 20 69 73 20 74   NULL, this is t
31bc0 68 65 20 73 61 6d 65 20 61 73 20 64 65 6c 65 74  he same as delet
31bd0 69 6e 67 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f  ing the collatio
31be0 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 28 73  n.** sequence (s
31bf0 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61  o that SQLite ca
31c00 6e 6e 6f 74 20 63 61 6c 6c 20 69 74 20 61 6e 79  nnot call it any
31c10 6d 6f 72 65 29 2e 0a 2a 2a 20 45 61 63 68 20 74  more)..** Each t
31c20 69 6d 65 20 74 68 65 20 61 70 70 6c 69 63 61 74  ime the applicat
31c30 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20  ion.** supplied 
31c40 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f  function is invo
31c50 6b 65 64 2c 20 69 74 20 69 73 20 70 61 73 73 65  ked, it is passe
31c60 64 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  d a copy of the 
31c70 76 6f 69 64 2a 20 70 61 73 73 65 64 20 61 73 0a  void* passed as.
31c80 2a 2a 20 74 68 65 20 66 6f 75 72 74 68 20 61 72  ** the fourth ar
31c90 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
31ca0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
31cb0 6f 6e 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74  on() or.** sqlit
31cc0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
31cd0 69 6f 6e 31 36 28 29 20 61 73 20 69 74 73 20 66  ion16() as its f
31ce0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 0a  irst parameter..
31cf0 2a 2a 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e  **.** The remain
31d00 69 6e 67 20 61 72 67 75 6d 65 6e 74 73 20 74 6f  ing arguments to
31d10 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
31d20 2d 73 75 70 70 6c 69 65 64 20 72 6f 75 74 69 6e  -supplied routin
31d30 65 20 61 72 65 20 74 77 6f 20 73 74 72 69 6e 67  e are two string
31d40 73 2c 0a 2a 2a 20 65 61 63 68 20 72 65 70 72 65  s,.** each repre
31d50 73 65 6e 74 65 64 20 62 79 20 61 20 28 6c 65 6e  sented by a (len
31d60 67 74 68 2c 20 64 61 74 61 29 20 70 61 69 72 20  gth, data) pair 
31d70 61 6e 64 20 65 6e 63 6f 64 65 64 20 69 6e 20 74  and encoded in t
31d80 68 65 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 74  he encoding.** t
31d90 68 61 74 20 77 61 73 20 70 61 73 73 65 64 20 61  hat was passed a
31da0 73 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75  s the third argu
31db0 6d 65 6e 74 20 77 68 65 6e 20 74 68 65 20 63 6f  ment when the co
31dc0 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
31dd0 20 77 61 73 0a 2a 2a 20 72 65 67 69 73 74 65 72   was.** register
31de0 65 64 2e 20 7b 45 4e 44 7d 20 54 68 65 20 61 70  ed. {END} The ap
31df0 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65  plication define
31e00 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 72 6f 75 74  d collation rout
31e10 69 6e 65 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65  ine should.** re
31e20 74 75 72 6e 20 6e 65 67 61 74 69 76 65 2c 20 7a  turn negative, z
31e30 65 72 6f 20 6f 72 20 70 6f 73 69 74 69 76 65 20  ero or positive 
31e40 69 66 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20  if.** the first 
31e50 73 74 72 69 6e 67 20 69 73 20 6c 65 73 73 20 74  string is less t
31e60 68 61 6e 2c 20 65 71 75 61 6c 20 74 6f 2c 20 6f  han, equal to, o
31e70 72 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 74  r greater than t
31e80 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 73 74 72  he second.** str
31e90 69 6e 67 2e 20 69 2e 65 2e 20 28 53 54 52 49 4e  ing. i.e. (STRIN
31ea0 47 31 20 2d 20 53 54 52 49 4e 47 32 29 2e 0a 2a  G1 - STRING2)..*
31eb0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
31ec0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
31ed0 6e 5f 76 32 28 29 20 77 6f 72 6b 73 20 6c 69 6b  n_v2() works lik
31ee0 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  e sqlite3_create
31ef0 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20  _collation().** 
31f00 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20 74  except that it t
31f10 61 6b 65 73 20 61 6e 20 65 78 74 72 61 20 61 72  akes an extra ar
31f20 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
31f30 61 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72  a destructor for
31f40 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f  .** the collatio
31f50 6e 2e 20 20 54 68 65 20 64 65 73 74 72 75 63 74  n.  The destruct
31f60 6f 72 20 69 73 20 63 61 6c 6c 65 64 20 77 68 65  or is called whe
31f70 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20  n the collation 
31f80 69 73 0a 2a 2a 20 64 65 73 74 72 6f 79 65 64 20  is.** destroyed 
31f90 61 6e 64 20 69 73 20 70 61 73 73 65 64 20 61 20  and is passed a 
31fa0 63 6f 70 79 20 6f 66 20 74 68 65 20 66 6f 75 72  copy of the four
31fb0 74 68 20 70 61 72 61 6d 65 74 65 72 20 76 6f 69  th parameter voi
31fc0 64 2a 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 6f 66  d* pointer.** of
31fd0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65   the sqlite3_cre
31fe0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
31ff0 28 29 2e 0a 2a 2a 20 43 6f 6c 6c 61 74 69 6f 6e  ()..** Collation
32000 73 20 61 72 65 20 64 65 73 74 72 6f 79 65 64 20  s are destroyed 
32010 77 68 65 6e 0a 2a 2a 20 74 68 65 79 20 61 72 65  when.** they are
32020 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20 6c   overridden by l
32030 61 74 65 72 20 63 61 6c 6c 73 20 74 6f 20 74 68  ater calls to th
32040 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 72 65 61  e collation crea
32050 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 0a 2a  tion functions.*
32060 2a 20 6f 72 20 77 68 65 6e 20 74 68 65 20 5b 73  * or when the [s
32070 71 6c 69 74 65 33 2a 5d 20 64 61 74 61 62 61 73  qlite3*] databas
32080 65 20 68 61 6e 64 6c 65 20 69 73 20 63 6c 6f 73  e handle is clos
32090 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
320a0 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a  3_close()]..**.*
320b0 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
320c0 0a 2a 2a 20 7b 46 31 36 36 30 33 7d 20 41 20 73  .** {F16603} A s
320d0 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74  uccessful call t
320e0 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  o the.**        
320f0 20 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74    [sqlite3_creat
32100 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42  e_collation_v2(B
32110 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 20 69 6e 74  ,X,E,P,F,D)] int
32120 65 72 66 61 63 65 0a 2a 2a 20 20 20 20 20 20 20  erface.**       
32130 20 20 20 72 65 67 69 73 74 65 72 73 20 66 75 6e     registers fun
32140 63 74 69 6f 6e 20 46 20 61 73 20 74 68 65 20 63  ction F as the c
32150 6f 6d 70 61 72 69 73 6f 6e 20 66 75 6e 63 74 69  omparison functi
32160 6f 6e 20 75 73 65 64 20 74 6f 0a 2a 2a 20 20 20  on used to.**   
32170 20 20 20 20 20 20 20 69 6d 70 6c 65 6d 65 6e 74         implement
32180 20 63 6f 6c 6c 61 74 69 6f 6e 20 58 20 6f 6e 20   collation X on 
32190 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
321a0 74 69 6f 6e 5d 20 42 20 66 6f 72 0a 2a 2a 20 20  tion] B for.**  
321b0 20 20 20 20 20 20 20 20 64 61 74 61 62 61 73 65          database
321c0 73 20 68 61 76 69 6e 67 20 65 6e 63 6f 64 69 6e  s having encodin
321d0 67 20 45 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36  g E..**.** {F166
321e0 30 34 7d 20 53 51 4c 69 74 65 20 75 6e 64 65 72  04} SQLite under
321f0 73 74 61 6e 64 73 20 74 68 65 20 58 20 70 61 72  stands the X par
32200 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 20 20 20  ameter to.**    
32210 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63        [sqlite3_c
32220 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
32230 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d  v2(B,X,E,P,F,D)]
32240 20 61 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   as a zero-termi
32250 6e 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  nated.**        
32260 20 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 69    UTF-8 string i
32270 6e 20 77 68 69 63 68 20 63 61 73 65 20 69 73 20  n which case is 
32280 69 67 6e 6f 72 65 64 20 66 6f 72 20 41 53 43 49  ignored for ASCI
32290 49 20 63 68 61 72 61 63 74 65 72 73 20 61 6e 64  I characters and
322a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20  .**          is 
322b0 73 69 67 6e 69 66 69 63 61 6e 74 20 66 6f 72 20  significant for 
322c0 6e 6f 6e 2d 41 53 43 49 49 20 63 68 61 72 61 63  non-ASCII charac
322d0 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  ters..**.** {F16
322e0 36 30 36 7d 20 53 75 63 63 65 73 73 69 76 65 20  606} Successive 
322f0 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
32300 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
32310 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c  on_v2(B,X,E,P,F,
32320 44 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  D)].**          
32330 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 76 61  with the same va
32340 6c 75 65 73 20 66 6f 72 20 42 2c 20 58 2c 20 61  lues for B, X, a
32350 6e 64 20 45 2c 20 6f 76 65 72 72 69 64 65 20 70  nd E, override p
32360 72 69 6f 72 20 76 61 6c 75 65 73 0a 2a 2a 20 20  rior values.**  
32370 20 20 20 20 20 20 20 20 6f 66 20 50 2c 20 46 2c          of P, F,
32380 20 61 6e 64 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46   and D..**.** {F
32390 31 36 36 30 39 7d 20 54 68 65 20 64 65 73 74 72  16609} The destr
323a0 75 63 74 6f 72 20 44 20 69 6e 20 5b 73 71 6c 69  uctor D in [sqli
323b0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
323c0 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c  tion_v2(B,X,E,P,
323d0 46 2c 44 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  F,D)].**        
323e0 20 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68    is not NULL th
323f0 65 6e 20 69 74 20 69 73 20 63 61 6c 6c 65 64 20  en it is called 
32400 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 50 20  with argument P 
32410 77 68 65 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20  when the.**     
32420 20 20 20 20 20 63 6f 6c 6c 61 74 69 6e 67 20 66       collating f
32430 75 6e 63 74 69 6f 6e 20 69 73 20 64 72 6f 70 70  unction is dropp
32440 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2a  ed by SQLite..**
32450 0a 2a 2a 20 7b 46 31 36 36 31 32 7d 20 41 20 63  .** {F16612} A c
32460 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
32470 6e 20 69 73 20 64 72 6f 70 70 65 64 20 77 68 65  n is dropped whe
32480 6e 20 69 74 20 69 73 20 6f 76 65 72 6c 6f 61 64  n it is overload
32490 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36 31  ed..**.** {F1661
324a0 35 7d 20 41 20 63 6f 6c 6c 61 74 69 6e 67 20 66  5} A collating f
324b0 75 6e 63 74 69 6f 6e 20 69 73 20 64 72 6f 70 70  unction is dropp
324c0 65 64 20 77 68 65 6e 20 74 68 65 20 64 61 74 61  ed when the data
324d0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
324e0 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 63  **          is c
324f0 6c 6f 73 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  losed using [sql
32500 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a  ite3_close()]..*
32510 2a 0a 2a 2a 20 7b 46 31 36 36 31 38 7d 20 54 68  *.** {F16618} Th
32520 65 20 70 6f 69 6e 74 65 72 20 50 20 69 6e 20 5b  e pointer P in [
32530 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
32540 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c  ollation_v2(B,X,
32550 45 2c 50 2c 46 2c 44 29 5d 0a 2a 2a 20 20 20 20  E,P,F,D)].**    
32560 20 20 20 20 20 20 69 73 20 70 61 73 73 65 64 20        is passed 
32570 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 66  through as the f
32580 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
32590 6f 20 74 68 65 20 63 6f 6d 70 61 72 69 73 6f 6e  o the comparison
325a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 75 6e  .**          fun
325b0 63 74 69 6f 6e 20 46 20 66 6f 72 20 61 6c 6c 20  ction F for all 
325c0 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63  subsequent invoc
325d0 61 74 69 6f 6e 73 20 6f 66 20 46 2e 0a 2a 2a 0a  ations of F..**.
325e0 2a 2a 20 7b 46 31 36 36 32 31 7d 20 41 20 63 61  ** {F16621} A ca
325f0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
32600 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
32610 42 2c 58 2c 45 2c 50 2c 46 29 5d 20 69 73 20 65  B,X,E,P,F)] is e
32620 78 61 63 74 6c 79 0a 2a 2a 20 20 20 20 20 20 20  xactly.**       
32630 20 20 20 74 68 65 20 73 61 6d 65 20 61 73 20 61     the same as a
32640 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
32650 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
32660 6f 6e 5f 76 32 28 29 5d 20 77 69 74 68 0a 2a 2a  on_v2()] with.**
32670 20 20 20 20 20 20 20 20 20 20 74 68 65 20 73 61            the sa
32680 6d 65 20 70 61 72 61 6d 65 74 65 72 73 20 61 6e  me parameters an
32690 64 20 61 20 4e 55 4c 4c 20 64 65 73 74 72 75 63  d a NULL destruc
326a0 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36  tor..**.** {F166
326b0 32 34 7d 20 46 6f 6c 6c 6f 77 69 6e 67 20 61 20  24} Following a 
326c0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
326d0 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c 58  collation_v2(B,X
326e0 2c 45 2c 50 2c 46 2c 44 29 5d 2c 0a 2a 2a 20 20  ,E,P,F,D)],.**  
326f0 20 20 20 20 20 20 20 20 53 51 4c 69 74 65 20 75          SQLite u
32700 73 65 73 20 74 68 65 20 63 6f 6d 70 61 72 69 73  ses the comparis
32710 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 46 20 66 6f  on function F fo
32720 72 20 61 6c 6c 20 74 65 78 74 20 63 6f 6d 70 61  r all text compa
32730 72 69 73 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20  rison.**        
32740 20 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20    operations on 
32750 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
32760 74 69 6f 6e 5d 20 42 20 6f 6e 20 74 65 78 74 20  tion] B on text 
32770 76 61 6c 75 65 73 20 74 68 61 74 0a 2a 2a 20 20  values that.**  
32780 20 20 20 20 20 20 20 20 75 73 65 20 74 68 65 20          use the 
32790 63 6f 6c 6c 61 74 69 6e 67 20 73 65 71 75 65 6e  collating sequen
327a0 63 65 20 6e 61 6d 65 20 58 2e 0a 2a 2a 0a 2a 2a  ce name X..**.**
327b0 20 7b 46 31 36 36 32 37 7d 20 54 68 65 20 5b 73   {F16627} The [s
327c0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
327d0 6c 6c 61 74 69 6f 6e 31 36 28 42 2c 58 2c 45 2c  llation16(B,X,E,
327e0 50 2c 46 29 5d 20 77 6f 72 6b 73 20 74 68 65 20  P,F)] works the 
327f0 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  same.**         
32800 20 61 73 20 5b 73 71 6c 69 74 65 33 5f 63 72 65   as [sqlite3_cre
32810 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 42 2c  ate_collation(B,
32820 58 2c 45 2c 50 2c 46 29 5d 20 65 78 63 65 70 74  X,E,P,F)] except
32830 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 20 20 20   that the.**    
32840 20 20 20 20 20 20 63 6f 6c 6c 61 74 69 6f 6e 20        collation 
32850 6e 61 6d 65 20 58 20 69 73 20 75 6e 64 65 72 73  name X is unders
32860 74 6f 6f 64 20 61 73 20 55 54 46 2d 31 36 20 69  tood as UTF-16 i
32870 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  n native byte or
32880 64 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  der.**          
32890 69 6e 73 74 65 61 64 20 6f 66 20 55 54 46 2d 38  instead of UTF-8
328a0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36 33 30 7d  ..**.** {F16630}
328b0 20 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 63   When multiple c
328c0 6f 6d 70 61 72 69 73 6f 6e 20 66 75 6e 63 74 69  omparison functi
328d0 6f 6e 73 20 61 72 65 20 61 76 61 69 6c 61 62 6c  ons are availabl
328e0 65 20 66 6f 72 20 74 68 65 20 73 61 6d 65 0a 2a  e for the same.*
328f0 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6c 6c 61  *          colla
32900 74 69 6e 67 20 73 65 71 75 65 6e 63 65 2c 20 53  ting sequence, S
32910 51 4c 69 74 65 20 63 68 6f 6f 73 65 73 20 74 68  QLite chooses th
32920 65 20 6f 6e 65 20 77 68 6f 73 65 20 74 65 78 74  e one whose text
32930 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 20 20 20   encoding.**    
32940 20 20 20 20 20 20 72 65 71 75 69 72 65 73 20 74        requires t
32950 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20  he least amount 
32960 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72  of conversion fr
32970 6f 6d 20 74 68 65 20 64 65 66 61 75 6c 74 0a 2a  om the default.*
32980 2a 20 20 20 20 20 20 20 20 20 20 74 65 78 74 20  *          text 
32990 65 6e 63 6f 64 69 6e 67 20 6f 66 20 74 68 65 20  encoding of the 
329a0 64 61 74 61 62 61 73 65 2e 0a 2a 2f 0a 69 6e 74  database..*/.int
329b0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
329c0 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20 73 71 6c  collation(.  sql
329d0 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20  ite3*, .  const 
329e0 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20  char *zName, .  
329f0 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20  int eTextRep, . 
32a00 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78   void*,.  int(*x
32a10 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69  Compare)(void*,i
32a20 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69  nt,const void*,i
32a30 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a  nt,const void*).
32a40 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
32a50 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
32a60 76 32 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  v2(.  sqlite3*, 
32a70 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
32a80 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65  Name, .  int eTe
32a90 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c  xtRep, .  void*,
32aa0 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65  .  int(*xCompare
32ab0 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
32ac0 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  t void*,int,cons
32ad0 74 20 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64  t void*),.  void
32ae0 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64  (*xDestroy)(void
32af0 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  *).);.int sqlite
32b00 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
32b10 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a  on16(.  sqlite3*
32b20 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  , .  const char 
32b30 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65  *zName, .  int e
32b40 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64  TextRep, .  void
32b50 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61  *,.  int(*xCompa
32b60 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  re)(void*,int,co
32b70 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  nst void*,int,co
32b80 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f  nst void*).);../
32b90 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
32ba0 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65 64 65 64 20  ollation Needed 
32bb0 43 61 6c 6c 62 61 63 6b 73 20 7b 46 31 36 37 30  Callbacks {F1670
32bc0 30 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 61 76 6f 69  0}.**.** To avoi
32bd0 64 20 68 61 76 69 6e 67 20 74 6f 20 72 65 67 69  d having to regi
32be0 73 74 65 72 20 61 6c 6c 20 63 6f 6c 6c 61 74 69  ster all collati
32bf0 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 62 65 66  on sequences bef
32c00 6f 72 65 20 61 20 64 61 74 61 62 61 73 65 0a 2a  ore a database.*
32c10 2a 20 63 61 6e 20 62 65 20 75 73 65 64 2c 20 61  * can be used, a
32c20 20 73 69 6e 67 6c 65 20 63 61 6c 6c 62 61 63 6b   single callback
32c30 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65   function may be
32c40 20 72 65 67 69 73 74 65 72 65 64 20 77 69 74 68   registered with
32c50 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
32c60 20 68 61 6e 64 6c 65 20 74 6f 20 62 65 20 63 61   handle to be ca
32c70 6c 6c 65 64 20 77 68 65 6e 65 76 65 72 20 61 6e  lled whenever an
32c80 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61   undefined colla
32c90 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 69 73  tion sequence is
32ca0 0a 2a 2a 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a  .** required..**
32cb0 0a 2a 2a 20 49 66 20 74 68 65 20 66 75 6e 63 74  .** If the funct
32cc0 69 6f 6e 20 69 73 20 72 65 67 69 73 74 65 72 65  ion is registere
32cd0 64 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69  d using the sqli
32ce0 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
32cf0 65 64 65 64 28 29 20 41 50 49 2c 0a 2a 2a 20 74  eded() API,.** t
32d00 68 65 6e 20 69 74 20 69 73 20 70 61 73 73 65 64  hen it is passed
32d10 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 75 6e   the names of un
32d20 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f  defined collatio
32d30 6e 20 73 65 71 75 65 6e 63 65 73 20 61 73 20 73  n sequences as s
32d40 74 72 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64 65  trings.** encode
32d50 64 20 69 6e 20 55 54 46 2d 38 2e 20 7b 46 31 36  d in UTF-8. {F16
32d60 37 30 33 7d 20 49 66 20 73 71 6c 69 74 65 33 5f  703} If sqlite3_
32d70 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
32d80 31 36 28 29 20 69 73 20 75 73 65 64 2c 20 74 68  16() is used, th
32d90 65 20 6e 61 6d 65 73 0a 2a 2a 20 61 72 65 20 70  e names.** are p
32da0 61 73 73 65 64 20 61 73 20 55 54 46 2d 31 36 20  assed as UTF-16 
32db0 69 6e 20 6d 61 63 68 69 6e 65 20 6e 61 74 69 76  in machine nativ
32dc0 65 20 62 79 74 65 20 6f 72 64 65 72 2e 20 41 20  e byte order. A 
32dd0 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72 0a 2a  call to either.*
32de0 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 70 6c 61  * function repla
32df0 63 65 73 20 61 6e 79 20 65 78 69 73 74 69 6e 67  ces any existing
32e00 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a   callback..**.**
32e10 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61   When the callba
32e20 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74  ck is invoked, t
32e30 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
32e40 74 20 70 61 73 73 65 64 20 69 73 20 61 20 63 6f  t passed is a co
32e50 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 65 63  py.** of the sec
32e60 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
32e70 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
32e80 6e 5f 6e 65 65 64 65 64 28 29 20 6f 72 0a 2a 2a  n_needed() or.**
32e90 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
32ea0 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 2e 20 20  on_needed16().  
32eb0 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
32ec0 65 6e 74 20 69 73 20 74 68 65 20 64 61 74 61 62  ent is the datab
32ed0 61 73 65 0a 2a 2a 20 68 61 6e 64 6c 65 2e 20 20  ase.** handle.  
32ee0 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
32ef0 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51  nt is one of [SQ
32f00 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 5b  LITE_UTF8],.** [
32f10 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c  SQLITE_UTF16BE],
32f20 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31   or [SQLITE_UTF1
32f30 36 4c 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67  6LE], indicating
32f40 20 74 68 65 20 6d 6f 73 74 0a 2a 2a 20 64 65 73   the most.** des
32f50 69 72 61 62 6c 65 20 66 6f 72 6d 20 6f 66 20 74  irable form of t
32f60 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  he collation seq
32f70 75 65 6e 63 65 20 66 75 6e 63 74 69 6f 6e 20 72  uence function r
32f80 65 71 75 69 72 65 64 2e 0a 2a 2a 20 54 68 65 20  equired..** The 
32f90 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
32fa0 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
32fb0 74 68 65 0a 2a 2a 20 72 65 71 75 69 72 65 64 20  the.** required 
32fc0 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
32fd0 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61  ce..**.** The ca
32fe0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
32ff0 73 68 6f 75 6c 64 20 72 65 67 69 73 74 65 72 20  should register 
33000 74 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c 6c  the desired coll
33010 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b  ation using.** [
33020 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
33030 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b 73 71  ollation()], [sq
33040 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
33050 6c 61 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a  lation16()], or.
33060 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ** [sqlite3_crea
33070 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
33080 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  )]..**.** INVARI
33090 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  ANTS:.**.** {F16
330a0 37 30 32 7d 20 41 20 73 75 63 63 65 73 73 66 75  702} A successfu
330b0 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  l call to [sqlit
330c0 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
330d0 64 65 64 28 44 2c 50 2c 46 29 5d 0a 2a 2a 20 20  ded(D,P,F)].**  
330e0 20 20 20 20 20 20 20 20 6f 72 20 5b 73 71 6c 69          or [sqli
330f0 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
33100 65 64 65 64 31 36 28 44 2c 50 2c 46 29 5d 20 63  eded16(D,P,F)] c
33110 61 75 73 65 73 0a 2a 2a 20 20 20 20 20 20 20 20  auses.**        
33120 20 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20    the [database 
33130 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 74 6f  connection] D to
33140 20 69 6e 76 6f 6b 65 20 63 61 6c 6c 62 61 63 6b   invoke callback
33150 20 46 20 77 69 74 68 20 66 69 72 73 74 0a 2a 2a   F with first.**
33160 20 20 20 20 20 20 20 20 20 20 70 61 72 61 6d 65            parame
33170 74 65 72 20 50 20 77 68 65 6e 65 76 65 72 20 69  ter P whenever i
33180 74 20 6e 65 65 64 73 20 61 20 63 6f 6d 70 61 72  t needs a compar
33190 69 73 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 66 6f  ison function fo
331a0 72 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  r a.**          
331b0 63 6f 6c 6c 61 74 69 6e 67 20 73 65 71 75 65 6e  collating sequen
331c0 63 65 20 74 68 61 74 20 69 74 20 64 6f 65 73 20  ce that it does 
331d0 6e 6f 74 20 6b 6e 6f 77 20 61 62 6f 75 74 2e 0a  not know about..
331e0 2a 2a 0a 2a 2a 20 7b 46 31 36 37 30 34 7d 20 45  **.** {F16704} E
331f0 61 63 68 20 73 75 63 63 65 73 73 66 75 6c 20 63  ach successful c
33200 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
33210 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
33220 28 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20  ()] or.**       
33230 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c     [sqlite3_coll
33240 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29  ation_needed16()
33250 5d 20 6f 76 65 72 72 69 64 65 73 20 74 68 65 20  ] overrides the 
33260 63 61 6c 6c 62 61 63 6b 20 72 65 67 69 73 74 65  callback registe
33270 72 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  red.**          
33280 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74  on the same [dat
33290 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
332a0 5d 20 62 79 20 70 72 69 6f 72 20 63 61 6c 6c 73  ] by prior calls
332b0 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 20 20   to either.**   
332c0 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65         interface
332d0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 37 30 36 7d  ..**.** {F16706}
332e0 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   The name of the
332f0 20 72 65 71 75 65 73 74 65 64 20 63 6f 6c 6c 61   requested colla
33300 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70 61  ting function pa
33310 73 73 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 20  ssed in the.**  
33320 20 20 20 20 20 20 20 20 34 74 68 20 70 61 72 61          4th para
33330 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c  meter to the cal
33340 6c 62 61 63 6b 20 69 73 20 69 6e 20 55 54 46 2d  lback is in UTF-
33350 38 20 69 66 20 74 68 65 20 63 61 6c 6c 62 61 63  8 if the callbac
33360 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 61  k.**          wa
33370 73 20 72 65 67 69 73 74 65 72 65 64 20 75 73 69  s registered usi
33380 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  ng [sqlite3_coll
33390 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d 20  ation_needed()] 
333a0 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  and.**          
333b0 69 73 20 69 6e 20 55 54 46 2d 31 36 20 6e 61 74  is in UTF-16 nat
333c0 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 69  ive byte order i
333d0 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 77  f the callback w
333e0 61 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  as.**          r
333f0 65 67 69 73 74 65 72 65 64 20 75 73 69 6e 67 20  egistered using 
33400 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69  [sqlite3_collati
33410 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 5d 2e 0a  on_needed16()]..
33420 2a 2a 0a 2a 2a 20 0a 2a 2f 0a 69 6e 74 20 73 71  **.** .*/.int sq
33430 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
33440 6e 65 65 64 65 64 28 0a 20 20 73 71 6c 69 74 65  needed(.  sqlite
33450 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 20 0a 20  3*, .  void*, . 
33460 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73   void(*)(void*,s
33470 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78  qlite3*,int eTex
33480 74 52 65 70 2c 63 6f 6e 73 74 20 63 68 61 72 2a  tRep,const char*
33490 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ).);.int sqlite3
334a0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
334b0 64 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  d16(.  sqlite3*,
334c0 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f 69   .  void*,.  voi
334d0 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74  d(*)(void*,sqlit
334e0 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70  e3*,int eTextRep
334f0 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b  ,const void*).);
33500 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20  ../*.** Specify 
33510 74 68 65 20 6b 65 79 20 66 6f 72 20 61 6e 20 65  the key for an e
33520 6e 63 72 79 70 74 65 64 20 64 61 74 61 62 61 73  ncrypted databas
33530 65 2e 20 20 54 68 69 73 20 72 6f 75 74 69 6e 65  e.  This routine
33540 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 63 61   should be.** ca
33550 6c 6c 65 64 20 72 69 67 68 74 20 61 66 74 65 72  lled right after
33560 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 2e   sqlite3_open().
33570 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20  .**.** The code 
33580 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69  to implement thi
33590 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61  s API is not ava
335a0 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75  ilable in the pu
335b0 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20  blic release.** 
335c0 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e  of SQLite..*/.in
335d0 74 20 73 71 6c 69 74 65 33 5f 6b 65 79 28 0a 20  t sqlite3_key(. 
335e0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
335f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
33600 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62  /* Database to b
33610 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63  e rekeyed */.  c
33620 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c  onst void *pKey,
33630 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a   int nKey     /*
33640 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a   The key */.);..
33650 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65 20 74 68 65  /*.** Change the
33660 20 6b 65 79 20 6f 6e 20 61 6e 20 6f 70 65 6e 20   key on an open 
33670 64 61 74 61 62 61 73 65 2e 20 20 49 66 20 74 68  database.  If th
33680 65 20 63 75 72 72 65 6e 74 20 64 61 74 61 62 61  e current databa
33690 73 65 20 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63  se is not.** enc
336a0 72 79 70 74 65 64 2c 20 74 68 69 73 20 72 6f 75  rypted, this rou
336b0 74 69 6e 65 20 77 69 6c 6c 20 65 6e 63 72 79 70  tine will encryp
336c0 74 20 69 74 2e 20 20 49 66 20 70 4e 65 77 3d 3d  t it.  If pNew==
336d0 30 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20 74 68  0 or nNew==0, th
336e0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 69 73  e.** database is
336f0 20 64 65 63 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a   decrypted..**.*
33700 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d  * The code to im
33710 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49  plement this API
33720 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c   is not availabl
33730 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20  e in the public 
33740 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51  release.** of SQ
33750 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  Lite..*/.int sql
33760 69 74 65 33 5f 72 65 6b 65 79 28 0a 20 20 73 71  ite3_rekey(.  sq
33770 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
33780 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
33790 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72  Database to be r
337a0 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73  ekeyed */.  cons
337b0 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e  t void *pKey, in
337c0 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68  t nKey     /* Th
337d0 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a  e new key */.);.
337e0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
337f0 20 20 53 75 73 70 65 6e 64 20 45 78 65 63 75 74    Suspend Execut
33800 69 6f 6e 20 46 6f 72 20 41 20 53 68 6f 72 74 20  ion For A Short 
33810 54 69 6d 65 20 7b 46 31 30 35 33 30 7d 0a 2a 2a  Time {F10530}.**
33820 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
33830 73 6c 65 65 70 28 29 20 66 75 6e 63 74 69 6f 6e  sleep() function
33840 0a 2a 2a 20 63 61 75 73 65 73 20 74 68 65 20 63  .** causes the c
33850 75 72 72 65 6e 74 20 74 68 72 65 61 64 20 74 6f  urrent thread to
33860 20 73 75 73 70 65 6e 64 20 65 78 65 63 75 74 69   suspend executi
33870 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74 20 6c 65 61  on.** for at lea
33880 73 74 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 6d  st a number of m
33890 69 6c 6c 69 73 65 63 6f 6e 64 73 20 73 70 65 63  illiseconds spec
338a0 69 66 69 65 64 20 69 6e 20 69 74 73 20 70 61 72  ified in its par
338b0 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66  ameter..**.** If
338c0 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
338d0 79 73 74 65 6d 20 64 6f 65 73 20 6e 6f 74 20 73  ystem does not s
338e0 75 70 70 6f 72 74 20 73 6c 65 65 70 20 72 65 71  upport sleep req
338f0 75 65 73 74 73 20 77 69 74 68 20 0a 2a 2a 20 6d  uests with .** m
33900 69 6c 6c 69 73 65 63 6f 6e 64 20 74 69 6d 65 20  illisecond time 
33910 72 65 73 6f 6c 75 74 69 6f 6e 2c 20 74 68 65 6e  resolution, then
33920 20 74 68 65 20 74 69 6d 65 20 77 69 6c 6c 20 62   the time will b
33930 65 20 72 6f 75 6e 64 65 64 20 75 70 20 74 6f 20  e rounded up to 
33940 0a 2a 2a 20 74 68 65 20 6e 65 61 72 65 73 74 20  .** the nearest 
33950 73 65 63 6f 6e 64 2e 20 54 68 65 20 6e 75 6d 62  second. The numb
33960 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e  er of millisecon
33970 64 73 20 6f 66 20 73 6c 65 65 70 20 61 63 74 75  ds of sleep actu
33980 61 6c 6c 79 20 0a 2a 2a 20 72 65 71 75 65 73 74  ally .** request
33990 65 64 20 66 72 6f 6d 20 74 68 65 20 6f 70 65 72  ed from the oper
339a0 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 73 20  ating system is 
339b0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
339c0 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74  SQLite implement
339d0 73 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  s this interface
339e0 20 62 79 20 63 61 6c 6c 69 6e 67 20 74 68 65 20   by calling the 
339f0 78 53 6c 65 65 70 28 29 0a 2a 2a 20 6d 65 74 68  xSleep().** meth
33a00 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c  od of the defaul
33a10 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  t [sqlite3_vfs] 
33a20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 4e  object..**.** IN
33a30 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
33a40 7b 46 31 30 35 33 33 7d 20 54 68 65 20 5b 73 71  {F10533} The [sq
33a50 6c 69 74 65 33 5f 73 6c 65 65 70 28 4d 29 5d 20  lite3_sleep(M)] 
33a60 69 6e 74 65 72 66 61 63 65 20 69 6e 76 6f 6b 65  interface invoke
33a70 73 20 74 68 65 20 78 53 6c 65 65 70 0a 2a 2a 20  s the xSleep.** 
33a80 20 20 20 20 20 20 20 20 20 6d 65 74 68 6f 64 20           method 
33a90 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b  of the default [
33aa0 73 71 6c 69 74 65 33 5f 76 66 73 7c 56 46 53 5d  sqlite3_vfs|VFS]
33ab0 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20   in order to.** 
33ac0 20 20 20 20 20 20 20 20 20 73 75 73 70 65 6e 64           suspend
33ad0 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68   execution of th
33ae0 65 20 63 75 72 72 65 6e 74 20 74 68 72 65 61 64  e current thread
33af0 20 66 6f 72 20 61 74 20 6c 65 61 73 74 0a 2a 2a   for at least.**
33b00 20 20 20 20 20 20 20 20 20 20 4d 20 6d 69 6c 6c            M mill
33b10 69 73 65 63 6f 6e 64 73 2e 0a 2a 2a 0a 2a 2a 20  iseconds..**.** 
33b20 7b 46 31 30 35 33 36 7d 20 54 68 65 20 5b 73 71  {F10536} The [sq
33b30 6c 69 74 65 33 5f 73 6c 65 65 70 28 4d 29 5d 20  lite3_sleep(M)] 
33b40 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
33b50 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  s the number of.
33b60 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 69 6c 6c  **          mill
33b70 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65  iseconds of slee
33b80 70 20 61 63 74 75 61 6c 6c 79 20 72 65 71 75 65  p actually reque
33b90 73 74 65 64 20 6f 66 20 74 68 65 20 6f 70 65 72  sted of the oper
33ba0 61 74 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20  ating.**        
33bb0 20 20 73 79 73 74 65 6d 2c 20 77 68 69 63 68 20    system, which 
33bc0 6d 69 67 68 74 20 62 65 20 6c 61 72 67 65 72 20  might be larger 
33bd0 74 68 61 6e 20 74 68 65 20 70 61 72 61 6d 65 74  than the paramet
33be0 65 72 20 4d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  er M..*/.int sql
33bf0 69 74 65 33 5f 73 6c 65 65 70 28 69 6e 74 29 3b  ite3_sleep(int);
33c00 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
33c10 3a 20 20 4e 61 6d 65 20 4f 66 20 54 68 65 20 46  :  Name Of The F
33c20 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20 54 65  older Holding Te
33c30 6d 70 6f 72 61 72 79 20 46 69 6c 65 73 20 7b 46  mporary Files {F
33c40 31 30 33 31 30 7d 0a 2a 2a 0a 2a 2a 20 49 66 20  10310}.**.** If 
33c50 74 68 69 73 20 67 6c 6f 62 61 6c 20 76 61 72 69  this global vari
33c60 61 62 6c 65 20 69 73 20 6d 61 64 65 20 74 6f 20  able is made to 
33c70 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e  point to a strin
33c80 67 20 77 68 69 63 68 20 69 73 0a 2a 2a 20 74 68  g which is.** th
33c90 65 20 6e 61 6d 65 20 6f 66 20 61 20 66 6f 6c 64  e name of a fold
33ca0 65 72 20 28 61 2e 6b 2e 61 2e 20 64 69 72 65 63  er (a.k.a. direc
33cb0 74 6f 72 79 29 2c 20 74 68 65 6e 20 61 6c 6c 20  tory), then all 
33cc0 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 0a  temporary files.
33cd0 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 53 51  ** created by SQ
33ce0 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 70 6c 61  Lite will be pla
33cf0 63 65 64 20 69 6e 20 74 68 61 74 20 64 69 72 65  ced in that dire
33d00 63 74 6f 72 79 2e 20 20 49 66 20 74 68 69 73 20  ctory.  If this 
33d10 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 73 20 4e  variable.** is N
33d20 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65  ULL pointer, the
33d30 6e 20 53 51 4c 69 74 65 20 64 6f 65 73 20 61 20  n SQLite does a 
33d40 73 65 61 72 63 68 20 66 6f 72 20 61 6e 20 61 70  search for an ap
33d50 70 72 6f 70 72 69 61 74 65 20 74 65 6d 70 6f 72  propriate tempor
33d60 61 72 79 0a 2a 2a 20 66 69 6c 65 20 64 69 72 65  ary.** file dire
33d70 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20  ctory..**.** It 
33d80 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 6d  is not safe to m
33d90 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61  odify this varia
33da0 62 6c 65 20 6f 6e 63 65 20 61 20 64 61 74 61 62  ble once a datab
33db0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
33dc0 2a 20 68 61 73 20 62 65 65 6e 20 6f 70 65 6e 65  * has been opene
33dd0 64 2e 20 20 49 74 20 69 73 20 69 6e 74 65 6e 64  d.  It is intend
33de0 65 64 20 74 68 61 74 20 74 68 69 73 20 76 61 72  ed that this var
33df0 69 61 62 6c 65 20 62 65 20 73 65 74 20 6f 6e 63  iable be set onc
33e00 65 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20  e.** as part of 
33e10 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69  process initiali
33e20 7a 61 74 69 6f 6e 20 61 6e 64 20 62 65 66 6f 72  zation and befor
33e30 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74  e any SQLite int
33e40 65 72 66 61 63 65 0a 2a 2a 20 72 6f 75 74 69 6e  erface.** routin
33e50 65 73 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c  es have been cal
33e60 6c 20 61 6e 64 20 72 65 6d 61 69 6e 20 75 6e 63  l and remain unc
33e70 68 61 6e 67 65 64 20 74 68 65 72 65 61 66 74 65  hanged thereafte
33e80 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54  r..*/.SQLITE_EXT
33e90 45 52 4e 20 63 68 61 72 20 2a 73 71 6c 69 74 65  ERN char *sqlite
33ea0 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79  3_temp_directory
33eb0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
33ec0 46 3a 20 20 54 65 73 74 20 54 6f 20 53 65 65 20  F:  Test To See 
33ed0 49 66 20 54 68 65 20 44 61 74 61 62 61 73 65 20  If The Database 
33ee0 49 73 20 49 6e 20 41 75 74 6f 2d 43 6f 6d 6d 69  Is In Auto-Commi
33ef0 74 20 4d 6f 64 65 20 7b 46 31 32 39 33 30 7d 0a  t Mode {F12930}.
33f00 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
33f10 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74  3_get_autocommit
33f20 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
33f30 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72  urns non-zero or
33f40 0a 2a 2a 20 7a 65 72 6f 20 69 66 20 74 68 65 20  .** zero if the 
33f50 67 69 76 65 6e 20 64 61 74 61 62 61 73 65 20 63  given database c
33f60 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 72 20  onnection is or 
33f70 69 73 20 6e 6f 74 20 69 6e 20 61 75 74 6f 63 6f  is not in autoco
33f80 6d 6d 69 74 20 6d 6f 64 65 2c 0a 2a 2a 20 72 65  mmit mode,.** re
33f90 73 70 65 63 74 69 76 65 6c 79 2e 20 20 20 41 75  spectively.   Au
33fa0 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73  tocommit mode is
33fb0 20 6f 6e 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c   on.** by defaul
33fc0 74 2e 20 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d  t.  Autocommit m
33fd0 6f 64 65 20 69 73 20 64 69 73 61 62 6c 65 64 20  ode is disabled 
33fe0 62 79 20 61 20 5b 42 45 47 49 4e 5d 20 73 74 61  by a [BEGIN] sta
33ff0 74 65 6d 65 6e 74 2e 0a 2a 2a 20 41 75 74 6f 63  tement..** Autoc
34000 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 72 65  ommit mode is re
34010 2d 65 6e 61 62 6c 65 64 20 62 79 20 61 20 5b 43  -enabled by a [C
34020 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f 4c 4c 42  OMMIT] or [ROLLB
34030 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 63  ACK]..**.** If c
34040 65 72 74 61 69 6e 20 6b 69 6e 64 73 20 6f 66 20  ertain kinds of 
34050 65 72 72 6f 72 73 20 6f 63 63 75 72 20 6f 6e 20  errors occur on 
34060 61 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  a statement with
34070 69 6e 20 61 20 6d 75 6c 74 69 2d 73 74 61 74 65  in a multi-state
34080 6d 65 6e 74 0a 2a 2a 20 74 72 61 6e 73 61 63 74  ment.** transact
34090 69 6f 6e 73 20 28 65 72 72 6f 72 73 20 69 6e 63  ions (errors inc
340a0 6c 75 64 69 6e 67 20 5b 53 51 4c 49 54 45 5f 46  luding [SQLITE_F
340b0 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4f  ULL], [SQLITE_IO
340c0 45 52 52 5d 2c 20 0a 2a 2a 20 5b 53 51 4c 49 54  ERR], .** [SQLIT
340d0 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53 51 4c 49 54  E_NOMEM], [SQLIT
340e0 45 5f 42 55 53 59 5d 2c 20 61 6e 64 20 5b 53 51  E_BUSY], and [SQ
340f0 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 29  LITE_INTERRUPT])
34100 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 74 72 61   then the.** tra
34110 6e 73 61 63 74 69 6f 6e 20 6d 69 67 68 74 20 62  nsaction might b
34120 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75  e rolled back au
34130 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54 68  tomatically.  Th
34140 65 20 6f 6e 6c 79 20 77 61 79 20 74 6f 0a 2a 2a  e only way to.**
34150 20 66 69 6e 64 20 6f 75 74 20 69 66 20 53 51 4c   find out if SQL
34160 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ite automaticall
34170 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 74 68  y rolled back th
34180 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 61 66  e transaction af
34190 74 65 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20  ter.** an error 
341a0 69 73 20 74 6f 20 75 73 65 20 74 68 69 73 20 66  is to use this f
341b0 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49  unction..**.** I
341c0 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
341d0 20 7b 46 31 32 39 33 31 7d 20 54 68 65 20 5b 73   {F12931} The [s
341e0 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63  qlite3_get_autoc
341f0 6f 6d 6d 69 74 28 44 29 5d 20 69 6e 74 65 72 66  ommit(D)] interf
34200 61 63 65 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  ace returns non-
34210 7a 65 72 6f 20 6f 72 0a 2a 2a 20 20 20 20 20 20  zero or.**      
34220 20 20 20 20 7a 65 72 6f 20 69 66 20 74 68 65 20      zero if the 
34230 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
34240 74 69 6f 6e 5d 20 44 20 69 73 20 6f 72 20 69 73  tion] D is or is
34250 20 6e 6f 74 20 69 6e 20 61 75 74 6f 63 6f 6d 6d   not in autocomm
34260 69 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d  it.**          m
34270 6f 64 65 2c 20 72 65 73 70 65 63 74 69 76 65 6c  ode, respectivel
34280 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 33 32  y..**.** {F12932
34290 7d 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64  } Autocommit mod
342a0 65 20 69 73 20 6f 6e 20 62 79 20 64 65 66 61 75  e is on by defau
342b0 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 33  lt..**.** {F1293
342c0 33 7d 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f  3} Autocommit mo
342d0 64 65 20 69 73 20 64 69 73 61 62 6c 65 64 20 62  de is disabled b
342e0 79 20 61 20 73 75 63 63 65 73 73 66 75 6c 20 5b  y a successful [
342f0 42 45 47 49 4e 5d 20 73 74 61 74 65 6d 65 6e 74  BEGIN] statement
34300 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 33 34 7d  ..**.** {F12934}
34310 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65   Autocommit mode
34320 20 69 73 20 65 6e 61 62 6c 65 64 20 62 79 20 61   is enabled by a
34330 20 73 75 63 63 65 73 73 66 75 6c 20 5b 43 4f 4d   successful [COM
34340 4d 49 54 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41 43  MIT] or [ROLLBAC
34350 4b 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73  K].**          s
34360 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 0a 2a 2a  tatement..** .**
34370 0a 2a 2a 20 4c 49 4d 49 54 41 54 49 4f 4e 53 3a  .** LIMITATIONS:
34380 0a 2a 2a 2a 0a 2a 2a 20 7b 55 31 32 39 33 36 7d  .***.** {U12936}
34390 20 49 66 20 61 6e 6f 74 68 65 72 20 74 68 72 65   If another thre
343a0 61 64 20 63 68 61 6e 67 65 73 20 74 68 65 20 61  ad changes the a
343b0 75 74 6f 63 6f 6d 6d 69 74 20 73 74 61 74 75 73  utocommit status
343c0 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
343d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e  .**          con
343e0 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68  nection while th
343f0 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 72 75  is routine is ru
34400 6e 6e 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20  nning, then the 
34410 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20  return value.** 
34420 20 20 20 20 20 20 20 20 20 69 73 20 75 6e 64 65           is unde
34430 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71  fined..*/.int sq
34440 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f  lite3_get_autoco
34450 6d 6d 69 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a  mmit(sqlite3*);.
34460 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
34470 20 20 46 69 6e 64 20 54 68 65 20 44 61 74 61 62    Find The Datab
34480 61 73 65 20 48 61 6e 64 6c 65 20 4f 66 20 41 20  ase Handle Of A 
34490 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
344a0 6e 74 20 7b 46 31 33 31 32 30 7d 0a 2a 2a 0a 2a  nt {F13120}.**.*
344b0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62  * The sqlite3_db
344c0 5f 68 61 6e 64 6c 65 20 69 6e 74 65 72 66 61 63  _handle interfac
344d0 65 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74 68 65  e.** returns the
344e0 20 5b 73 71 6c 69 74 65 33 2a 5d 20 64 61 74 61   [sqlite3*] data
344f0 62 61 73 65 20 68 61 6e 64 6c 65 20 74 6f 20 77  base handle to w
34500 68 69 63 68 20 61 0a 2a 2a 20 5b 70 72 65 70 61  hich a.** [prepa
34510 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 62  red statement] b
34520 65 6c 6f 6e 67 73 2e 0a 2a 2a 20 54 68 65 20 64  elongs..** The d
34530 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 72  atabase handle r
34540 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
34550 65 33 5f 64 62 5f 68 61 6e 64 6c 65 0a 2a 2a 20  e3_db_handle.** 
34560 69 73 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  is the same data
34570 62 61 73 65 20 68 61 6e 64 6c 65 20 74 68 61 74  base handle that
34580 20 77 61 73 0a 2a 2a 20 74 68 65 20 66 69 72 73   was.** the firs
34590 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
345a0 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  e [sqlite3_prepa
345b0 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20  re_v2()] or its 
345c0 76 61 72 69 61 6e 74 73 0a 2a 2a 20 74 68 61 74  variants.** that
345d0 20 77 61 73 20 75 73 65 64 20 74 6f 20 63 72 65   was used to cre
345e0 61 74 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e  ate the statemen
345f0 74 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 70  t in the first p
34600 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  lace..**.** INVA
34610 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  RIANTS:.**.** {F
34620 31 33 31 32 33 7d 20 54 68 65 20 5b 73 71 6c 69  13123} The [sqli
34630 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 28 53 29  te3_db_handle(S)
34640 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
34650 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a  rns a pointer.**
34660 20 20 20 20 20 20 20 20 20 20 74 6f 20 74 68 65            to the
34670 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
34680 63 74 69 6f 6e 5d 20 61 73 73 6f 63 69 61 74 65  ction] associate
34690 64 20 77 69 74 68 0a 2a 2a 20 20 20 20 20 20 20  d with.**       
346a0 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61     [prepared sta
346b0 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 73 71  tement] S..*/.sq
346c0 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 64  lite3 *sqlite3_d
346d0 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33  b_handle(sqlite3
346e0 5f 73 74 6d 74 2a 29 3b 0a 0a 0a 2f 2a 0a 2a 2a  _stmt*);.../*.**
346f0 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 6d 69   CAPI3REF: Commi
34700 74 20 41 6e 64 20 52 6f 6c 6c 62 61 63 6b 20 4e  t And Rollback N
34710 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c  otification Call
34720 62 61 63 6b 73 20 7b 46 31 32 39 35 30 7d 0a 2a  backs {F12950}.*
34730 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
34740 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 20 69  _commit_hook() i
34750 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65  nterface registe
34760 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  rs a callback.**
34770 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
34780 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72  invoked whenever
34790 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69   a transaction i
347a0 73 20 63 6f 6d 6d 69 74 74 65 64 2e 0a 2a 2a 20  s committed..** 
347b0 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74  Any callback set
347c0 20 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 63   by a previous c
347d0 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  all to sqlite3_c
347e0 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20  ommit_hook().** 
347f0 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74  for the same dat
34800 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
34810 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a   is overridden..
34820 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
34830 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 20 69  ollback_hook() i
34840 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65  nterface registe
34850 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  rs a callback.**
34860 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
34870 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72  invoked whenever
34880 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69   a transaction i
34890 73 20 63 6f 6d 6d 69 74 74 65 64 2e 0a 2a 2a 20  s committed..** 
348a0 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74  Any callback set
348b0 20 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 63   by a previous c
348c0 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  all to sqlite3_c
348d0 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20  ommit_hook().** 
348e0 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74  for the same dat
348f0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
34900 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a   is overridden..
34910 2a 2a 20 54 68 65 20 70 41 72 67 20 61 72 67 75  ** The pArg argu
34920 6d 65 6e 74 20 69 73 20 70 61 73 73 65 64 20 74  ment is passed t
34930 68 72 6f 75 67 68 0a 2a 2a 20 74 6f 20 74 68 65  hrough.** to the
34940 20 63 61 6c 6c 62 61 63 6b 2e 20 20 49 66 20 74   callback.  If t
34950 68 65 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 20 61  he callback on a
34960 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 66 75 6e   commit hook fun
34970 63 74 69 6f 6e 20 0a 2a 2a 20 72 65 74 75 72 6e  ction .** return
34980 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e  s non-zero, then
34990 20 74 68 65 20 63 6f 6d 6d 69 74 20 69 73 20 63   the commit is c
349a0 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20  onverted into a 
349b0 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  rollback..**.** 
349c0 49 66 20 61 6e 6f 74 68 65 72 20 66 75 6e 63 74  If another funct
349d0 69 6f 6e 20 77 61 73 20 70 72 65 76 69 6f 75 73  ion was previous
349e0 6c 79 20 72 65 67 69 73 74 65 72 65 64 2c 20 69  ly registered, i
349f0 74 73 0a 2a 2a 20 70 41 72 67 20 76 61 6c 75 65  ts.** pArg value
34a00 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f   is returned.  O
34a10 74 68 65 72 77 69 73 65 20 4e 55 4c 4c 20 69 73  therwise NULL is
34a20 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
34a30 20 52 65 67 69 73 74 65 72 69 6e 67 20 61 20 4e   Registering a N
34a40 55 4c 4c 20 66 75 6e 63 74 69 6f 6e 20 64 69 73  ULL function dis
34a50 61 62 6c 65 73 20 74 68 65 20 63 61 6c 6c 62 61  ables the callba
34a60 63 6b 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 74 68  ck..**.** For th
34a70 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68  e purposes of th
34a80 69 73 20 41 50 49 2c 20 61 20 74 72 61 6e 73 61  is API, a transa
34a90 63 74 69 6f 6e 20 69 73 20 73 61 69 64 20 74 6f  ction is said to
34aa0 20 68 61 76 65 20 62 65 65 6e 20 0a 2a 2a 20 72   have been .** r
34ab0 6f 6c 6c 65 64 20 62 61 63 6b 20 69 66 20 61 6e  olled back if an
34ac0 20 65 78 70 6c 69 63 69 74 20 22 52 4f 4c 4c 42   explicit "ROLLB
34ad0 41 43 4b 22 20 73 74 61 74 65 6d 65 6e 74 20 69  ACK" statement i
34ae0 73 20 65 78 65 63 75 74 65 64 2c 20 6f 72 0a 2a  s executed, or.*
34af0 2a 20 61 6e 20 65 72 72 6f 72 20 6f 72 20 63 6f  * an error or co
34b00 6e 73 74 72 61 69 6e 74 20 63 61 75 73 65 73 20  nstraint causes 
34b10 61 6e 20 69 6d 70 6c 69 63 69 74 20 72 6f 6c 6c  an implicit roll
34b20 62 61 63 6b 20 74 6f 20 6f 63 63 75 72 2e 0a 2a  back to occur..*
34b30 2a 20 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 63  * The rollback c
34b40 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20 69  allback is not i
34b50 6e 76 6f 6b 65 64 20 69 66 20 61 20 74 72 61 6e  nvoked if a tran
34b60 73 61 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 61 75  saction is.** au
34b70 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c  tomatically roll
34b80 65 64 20 62 61 63 6b 20 62 65 63 61 75 73 65 20  ed back because 
34b90 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
34ba0 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65  nection is close
34bb0 64 2e 0a 2a 2a 20 54 68 65 20 72 6f 6c 6c 62 61  d..** The rollba
34bc0 63 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e  ck callback is n
34bd0 6f 74 20 69 6e 76 6f 6b 65 64 20 69 66 20 61 20  ot invoked if a 
34be0 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 0a 2a  transaction is.*
34bf0 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62 65  * rolled back be
34c00 63 61 75 73 65 20 61 20 63 6f 6d 6d 69 74 20 63  cause a commit c
34c10 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 65 64  allback returned
34c20 20 6e 6f 6e 2d 7a 65 72 6f 2e 0a 2a 2a 20 3c 74   non-zero..** <t
34c30 6f 64 6f 3e 20 43 68 65 63 6b 20 6f 6e 20 74 68  odo> Check on th
34c40 69 73 20 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a  is </todo>.**.**
34c50 20 54 68 65 73 65 20 61 72 65 20 65 78 70 65 72   These are exper
34c60 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66 61 63  imental interfac
34c70 65 73 20 61 6e 64 20 61 72 65 20 73 75 62 6a 65  es and are subje
34c80 63 74 20 74 6f 20 63 68 61 6e 67 65 2e 0a 2a 2a  ct to change..**
34c90 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
34ca0 2a 2a 0a 2a 2a 20 7b 46 31 32 39 35 31 7d 20 54  **.** {F12951} T
34cb0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 6d  he [sqlite3_comm
34cc0 69 74 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20  it_hook(D,F,P)] 
34cd0 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74  interface regist
34ce0 65 72 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  ers the.**      
34cf0 20 20 20 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e      callback fun
34d00 63 74 69 6f 6e 20 46 20 74 6f 20 62 65 20 69 6e  ction F to be in
34d10 76 6f 6b 65 64 20 77 69 74 68 20 61 72 67 75 6d  voked with argum
34d20 65 6e 74 20 50 20 77 68 65 6e 65 76 65 72 0a 2a  ent P whenever.*
34d30 2a 20 20 20 20 20 20 20 20 20 20 61 20 74 72 61  *          a tra
34d40 6e 73 61 63 74 69 6f 6e 20 63 6f 6d 6d 69 74 73  nsaction commits
34d50 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f   on [database co
34d60 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a  nnection] D..**.
34d70 2a 2a 20 7b 46 31 32 39 35 32 7d 20 54 68 65 20  ** {F12952} The 
34d80 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f  [sqlite3_commit_
34d90 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 6e 74  hook(D,F,P)] int
34da0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
34db0 68 65 20 50 0a 2a 2a 20 20 20 20 20 20 20 20 20  he P.**         
34dc0 20 61 72 67 75 6d 65 6e 74 20 66 72 6f 6d 20 74   argument from t
34dd0 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  he previous call
34de0 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 0a   with the same .
34df0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61 74  **          [dat
34e00 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
34e10 20 5d 20 44 20 2c 20 6f 72 20 4e 55 4c 4c 20 6f   ] D , or NULL o
34e20 6e 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c  n the first call
34e30 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 6f 72  .**          for
34e40 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 5b 64   a particular [d
34e50 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
34e60 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  on] D..**.** {F1
34e70 32 39 35 33 7d 20 45 61 63 68 20 63 61 6c 6c 20  2953} Each call 
34e80 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 6d  to [sqlite3_comm
34e90 69 74 5f 68 6f 6f 6b 28 29 5d 20 6f 76 65 72 77  it_hook()] overw
34ea0 72 69 74 65 73 20 74 68 65 20 63 61 6c 6c 62 61  rites the callba
34eb0 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  ck.**          r
34ec0 65 67 69 73 74 65 72 65 64 20 62 79 20 70 72 69  egistered by pri
34ed0 6f 72 20 63 61 6c 6c 73 2e 0a 2a 2a 0a 2a 2a 20  or calls..**.** 
34ee0 7b 46 31 32 39 35 34 7d 20 49 66 20 74 68 65 20  {F12954} If the 
34ef0 46 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73  F argument to [s
34f00 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f  qlite3_commit_ho
34f10 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 73 20 4e 55  ok(D,F,P)] is NU
34f20 4c 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  LL.**          t
34f30 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 68  hen the commit h
34f40 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ook callback is 
34f50 63 61 6e 63 65 6c 65 64 20 61 6e 64 20 6e 6f 20  canceled and no 
34f60 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20  callback.**     
34f70 20 20 20 20 20 69 73 20 69 6e 76 6f 6b 65 64 20       is invoked 
34f80 77 68 65 6e 20 61 20 74 72 61 6e 73 61 63 74 69  when a transacti
34f90 6f 6e 20 63 6f 6d 6d 69 74 73 2e 0a 2a 2a 0a 2a  on commits..**.*
34fa0 2a 20 7b 46 31 32 39 35 35 7d 20 49 66 20 74 68  * {F12955} If th
34fb0 65 20 63 6f 6d 6d 69 74 20 63 61 6c 6c 62 61 63  e commit callbac
34fc0 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  k returns non-ze
34fd0 72 6f 20 74 68 65 6e 20 74 68 65 20 63 6f 6d 6d  ro then the comm
34fe0 69 74 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20  it is.**        
34ff0 20 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f    converted into
35000 20 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a   a rollback..**.
35010 2a 2a 20 7b 46 31 32 39 36 31 7d 20 54 68 65 20  ** {F12961} The 
35020 5b 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63  [sqlite3_rollbac
35030 6b 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69  k_hook(D,F,P)] i
35040 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65  nterface registe
35050 72 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  rs the.**       
35060 20 20 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63     callback func
35070 74 69 6f 6e 20 46 20 74 6f 20 62 65 20 69 6e 76  tion F to be inv
35080 6f 6b 65 64 20 77 69 74 68 20 61 72 67 75 6d 65  oked with argume
35090 6e 74 20 50 20 77 68 65 6e 65 76 65 72 0a 2a 2a  nt P whenever.**
350a0 20 20 20 20 20 20 20 20 20 20 61 20 74 72 61 6e            a tran
350b0 73 61 63 74 69 6f 6e 20 72 6f 6c 6c 73 20 62 61  saction rolls ba
350c0 63 6b 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20  ck on [database 
350d0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a  connection] D..*
350e0 2a 0a 2a 2a 20 7b 46 31 32 39 36 32 7d 20 54 68  *.** {F12962} Th
350f0 65 20 5b 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62  e [sqlite3_rollb
35100 61 63 6b 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d  ack_hook(D,F,P)]
35110 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
35120 6e 73 20 74 68 65 20 50 0a 2a 2a 20 20 20 20 20  ns the P.**     
35130 20 20 20 20 20 61 72 67 75 6d 65 6e 74 20 66 72       argument fr
35140 6f 6d 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  om the previous 
35150 63 61 6c 6c 20 77 69 74 68 20 74 68 65 20 73 61  call with the sa
35160 6d 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  me .**          
35170 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
35180 74 69 6f 6e 20 5d 20 44 20 2c 20 6f 72 20 4e 55  tion ] D , or NU
35190 4c 4c 20 6f 6e 20 74 68 65 20 66 69 72 73 74 20  LL on the first 
351a0 63 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20  call.**         
351b0 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61   for a particula
351c0 72 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  r [database conn
351d0 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a  ection] D..**.**
351e0 20 7b 46 31 32 39 36 33 7d 20 45 61 63 68 20 63   {F12963} Each c
351f0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
35200 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 5d  rollback_hook()]
35210 20 6f 76 65 72 77 72 69 74 65 73 20 74 68 65 20   overwrites the 
35220 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20  callback.**     
35230 20 20 20 20 20 72 65 67 69 73 74 65 72 65 64 20       registered 
35240 62 79 20 70 72 69 6f 72 20 63 61 6c 6c 73 2e 0a  by prior calls..
35250 2a 2a 0a 2a 2a 20 7b 46 31 32 39 36 34 7d 20 49  **.** {F12964} I
35260 66 20 74 68 65 20 46 20 61 72 67 75 6d 65 6e 74  f the F argument
35270 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 6f 6c   to [sqlite3_rol
35280 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c 46 2c 50  lback_hook(D,F,P
35290 29 5d 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20 20 20  )] is NULL.**   
352a0 20 20 20 20 20 20 20 74 68 65 6e 20 74 68 65 20         then the 
352b0 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 63 61  rollback hook ca
352c0 6c 6c 62 61 63 6b 20 69 73 20 63 61 6e 63 65 6c  llback is cancel
352d0 65 64 20 61 6e 64 20 6e 6f 20 63 61 6c 6c 62 61  ed and no callba
352e0 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  ck.**          i
352f0 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 61  s invoked when a
35300 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 72 6f 6c   transaction rol
35310 6c 73 20 62 61 63 6b 2e 0a 2a 2f 0a 76 6f 69 64  ls back..*/.void
35320 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74   *sqlite3_commit
35330 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20  _hook(sqlite3*, 
35340 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76  int(*)(void*), v
35350 6f 69 64 2a 29 3b 0a 76 6f 69 64 20 2a 73 71 6c  oid*);.void *sql
35360 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f  ite3_rollback_ho
35370 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69  ok(sqlite3*, voi
35380 64 28 2a 29 28 76 6f 69 64 20 2a 29 2c 20 76 6f  d(*)(void *), vo
35390 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
353a0 49 33 52 45 46 3a 20 44 61 74 61 20 43 68 61 6e  I3REF: Data Chan
353b0 67 65 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20  ge Notification 
353c0 43 61 6c 6c 62 61 63 6b 73 20 7b 46 31 32 39 37  Callbacks {F1297
353d0 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  0}.**.** The sql
353e0 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b  ite3_update_hook
353f0 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  () interface.** 
35400 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c  registers a call
35410 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69  back function wi
35420 74 68 20 74 68 65 20 64 61 74 61 62 61 73 65 20  th the database 
35430 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 64 65 6e 74  connection ident
35440 69 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a  ified by the .**
35450 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
35460 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68  to be invoked wh
35470 65 6e 65 76 65 72 20 61 20 72 6f 77 20 69 73 20  enever a row is 
35480 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72 74 65  updated, inserte
35490 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a  d or deleted..**
354a0 20 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65   Any callback se
354b0 74 20 62 79 20 61 20 70 72 65 76 69 6f 75 73 20  t by a previous 
354c0 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 66 75 6e  call to this fun
354d0 63 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 73 61  ction for the sa
354e0 6d 65 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  me .** database 
354f0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76  connection is ov
35500 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 0a 2a 2a 20  erridden..**.** 
35510 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
35520 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ent is a pointer
35530 20 74 6f 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   to the function
35540 20 74 6f 20 69 6e 76 6f 6b 65 20 77 68 65 6e 20   to invoke when 
35550 61 20 0a 2a 2a 20 72 6f 77 20 69 73 20 75 70 64  a .** row is upd
35560 61 74 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f  ated, inserted o
35570 72 20 64 65 6c 65 74 65 64 2e 20 0a 2a 2a 20 54  r deleted. .** T
35580 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
35590 74 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  t to the callbac
355a0 6b 20 69 73 0a 2a 2a 20 61 20 63 6f 70 79 20 6f  k is.** a copy o
355b0 66 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75  f the third argu
355c0 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
355d0 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 2e 0a 2a  update_hook()..*
355e0 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 63 61 6c  * The second cal
355f0 6c 62 61 63 6b 20 0a 2a 2a 20 61 72 67 75 6d 65  lback .** argume
35600 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51  nt is one of [SQ
35610 4c 49 54 45 5f 49 4e 53 45 52 54 5d 2c 20 5b 53  LITE_INSERT], [S
35620 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 6f 72  QLITE_DELETE] or
35630 20 5b 53 51 4c 49 54 45 5f 55 50 44 41 54 45 5d   [SQLITE_UPDATE]
35640 2c 0a 2a 2a 20 64 65 70 65 6e 64 69 6e 67 20 6f  ,.** depending o
35650 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20  n the operation 
35660 74 68 61 74 20 63 61 75 73 65 64 20 74 68 65 20  that caused the 
35670 63 61 6c 6c 62 61 63 6b 20 74 6f 20 62 65 20 69  callback to be i
35680 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 54 68 65 20 74  nvoked..** The t
35690 68 69 72 64 20 61 6e 64 20 0a 2a 2a 20 66 6f 75  hird and .** fou
356a0 72 74 68 20 61 72 67 75 6d 65 6e 74 73 20 74 6f  rth arguments to
356b0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f   the callback co
356c0 6e 74 61 69 6e 20 70 6f 69 6e 74 65 72 73 20 74  ntain pointers t
356d0 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61  o the database a
356e0 6e 64 20 0a 2a 2a 20 74 61 62 6c 65 20 6e 61 6d  nd .** table nam
356f0 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  e containing the
35700 20 61 66 66 65 63 74 65 64 20 72 6f 77 2e 0a 2a   affected row..*
35710 2a 20 54 68 65 20 66 69 6e 61 6c 20 63 61 6c 6c  * The final call
35720 62 61 63 6b 20 70 61 72 61 6d 65 74 65 72 20 69  back parameter i
35730 73 20 0a 2a 2a 20 74 68 65 20 72 6f 77 69 64 20  s .** the rowid 
35740 6f 66 20 74 68 65 20 72 6f 77 2e 0a 2a 2a 20 49  of the row..** I
35750 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20 61 6e  n the case of an
35760 20 75 70 64 61 74 65 2c 20 74 68 69 73 20 69 73   update, this is
35770 20 74 68 65 20 72 6f 77 69 64 20 61 66 74 65 72   the rowid after
35780 20 0a 2a 2a 20 74 68 65 20 75 70 64 61 74 65 20   .** the update 
35790 74 61 6b 65 73 20 70 6c 61 63 65 2e 0a 2a 2a 0a  takes place..**.
357a0 2a 2a 20 54 68 65 20 75 70 64 61 74 65 20 68 6f  ** The update ho
357b0 6f 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65  ok is not invoke
357c0 64 20 77 68 65 6e 20 69 6e 74 65 72 6e 61 6c 20  d when internal 
357d0 73 79 73 74 65 6d 20 74 61 62 6c 65 73 20 61 72  system tables ar
357e0 65 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 20 28 69  e.** modified (i
357f0 2e 65 2e 20 73 71 6c 69 74 65 5f 6d 61 73 74 65  .e. sqlite_maste
35800 72 20 61 6e 64 20 73 71 6c 69 74 65 5f 73 65 71  r and sqlite_seq
35810 75 65 6e 63 65 29 2e 0a 2a 2a 0a 2a 2a 20 49 66  uence)..**.** If
35820 20 61 6e 6f 74 68 65 72 20 66 75 6e 63 74 69 6f   another functio
35830 6e 20 77 61 73 20 70 72 65 76 69 6f 75 73 6c 79  n was previously
35840 20 72 65 67 69 73 74 65 72 65 64 2c 20 69 74 73   registered, its
35850 20 70 41 72 67 20 76 61 6c 75 65 0a 2a 2a 20 69   pArg value.** i
35860 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68  s returned.  Oth
35870 65 72 77 69 73 65 20 4e 55 4c 4c 20 69 73 20 72  erwise NULL is r
35880 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  eturned..**.** I
35890 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
358a0 20 7b 46 31 32 39 37 31 7d 20 54 68 65 20 5b 73   {F12971} The [s
358b0 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f  qlite3_update_ho
358c0 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 6e 74 65 72  ok(D,F,P)] inter
358d0 66 61 63 65 20 63 61 75 73 65 73 20 63 61 6c 6c  face causes call
358e0 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20  back.**         
358f0 20 66 75 6e 63 74 69 6f 6e 20 46 20 74 6f 20 62   function F to b
35900 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 66  e invoked with f
35910 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 50  irst parameter P
35920 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 20 20 20   whenever.**    
35930 20 20 20 20 20 20 61 20 74 61 62 6c 65 20 72 6f        a table ro
35940 77 20 69 73 20 6d 6f 64 69 66 69 65 64 2c 20 69  w is modified, i
35950 6e 73 65 72 74 65 64 2c 20 6f 72 20 64 65 6c 65  nserted, or dele
35960 74 65 64 20 6f 6e 0a 2a 2a 20 20 20 20 20 20 20  ted on.**       
35970 20 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e     [database con
35980 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a  nection] D..**.*
35990 2a 20 7b 46 31 32 39 37 33 7d 20 54 68 65 20 5b  * {F12973} The [
359a0 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68  sqlite3_update_h
359b0 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 6e 74 65  ook(D,F,P)] inte
359c0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
359d0 65 20 76 61 6c 75 65 0a 2a 2a 20 20 20 20 20 20  e value.**      
359e0 20 20 20 20 6f 66 20 50 20 66 6f 72 20 74 68 65      of P for the
359f0 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 6f   previous call o
35a00 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61  n the same [data
35a10 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
35a20 20 44 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   D,.**          
35a30 6f 72 20 4e 55 4c 4c 20 66 6f 72 20 74 68 65 20  or NULL for the 
35a40 66 69 72 73 74 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a  first call..**.*
35a50 2a 20 7b 46 31 32 39 37 35 7d 20 49 66 20 74 68  * {F12975} If th
35a60 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 20 63 61  e update hook ca
35a70 6c 6c 62 61 63 6b 20 46 20 69 6e 20 5b 73 71 6c  llback F in [sql
35a80 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b  ite3_update_hook
35a90 28 44 2c 46 2c 50 29 5d 0a 2a 2a 20 20 20 20 20  (D,F,P)].**     
35aa0 20 20 20 20 20 69 73 20 4e 55 4c 4c 20 74 68 65       is NULL the
35ab0 6e 20 74 68 65 20 6e 6f 20 75 70 64 61 74 65 20  n the no update 
35ac0 63 61 6c 6c 62 61 63 6b 73 20 61 72 65 20 6d 61  callbacks are ma
35ad0 64 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 37  de..**.** {F1297
35ae0 37 7d 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20  7} Each call to 
35af0 5b 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f  [sqlite3_update_
35b00 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 6f 76 65  hook(D,F,P)] ove
35b10 72 72 69 64 65 73 20 70 72 69 6f 72 20 63 61 6c  rrides prior cal
35b20 6c 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  ls.**          t
35b30 6f 20 74 68 65 20 73 61 6d 65 20 69 6e 74 65 72  o the same inter
35b40 66 61 63 65 20 6f 6e 20 74 68 65 20 73 61 6d 65  face on the same
35b50 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
35b60 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20  ction] D..**.** 
35b70 7b 46 31 32 39 37 39 7d 20 54 68 65 20 75 70 64  {F12979} The upd
35b80 61 74 65 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63  ate hook callbac
35b90 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64  k is not invoked
35ba0 20 77 68 65 6e 20 69 6e 74 65 72 6e 61 6c 20 73   when internal s
35bb0 79 73 74 65 6d 0a 2a 2a 20 20 20 20 20 20 20 20  ystem.**        
35bc0 20 20 74 61 62 6c 65 73 20 73 75 63 68 20 61 73    tables such as
35bd0 20 73 71 6c 69 74 65 5f 6d 61 73 74 65 72 20 61   sqlite_master a
35be0 6e 64 20 73 71 6c 69 74 65 5f 73 65 71 75 65 6e  nd sqlite_sequen
35bf0 63 65 20 61 72 65 20 6d 6f 64 69 66 69 65 64 2e  ce are modified.
35c00 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 38 31 7d 20  .**.** {F12981} 
35c10 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
35c20 65 74 65 72 20 74 6f 20 74 68 65 20 75 70 64 61  eter to the upda
35c30 74 65 20 63 61 6c 6c 62 61 63 6b 20 0a 2a 2a 20  te callback .** 
35c40 20 20 20 20 20 20 20 20 20 69 73 20 6f 6e 65 20           is one 
35c50 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 53 45 52  of [SQLITE_INSER
35c60 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45  T], [SQLITE_DELE
35c70 54 45 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55  TE] or [SQLITE_U
35c80 50 44 41 54 45 5d 2c 0a 2a 2a 20 20 20 20 20 20  PDATE],.**      
35c90 20 20 20 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e      depending on
35ca0 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 74   the operation t
35cb0 68 61 74 20 63 61 75 73 65 64 20 74 68 65 20 63  hat caused the c
35cc0 61 6c 6c 62 61 63 6b 20 74 6f 20 62 65 20 69 6e  allback to be in
35cd0 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  voked..**.** {F1
35ce0 32 39 38 33 7d 20 54 68 65 20 74 68 69 72 64 20  2983} The third 
35cf0 61 6e 64 20 66 6f 75 72 74 68 20 61 72 67 75 6d  and fourth argum
35d00 65 6e 74 73 20 74 6f 20 74 68 65 20 63 61 6c 6c  ents to the call
35d10 62 61 63 6b 20 63 6f 6e 74 61 69 6e 20 70 6f 69  back contain poi
35d20 6e 74 65 72 73 0a 2a 2a 20 20 20 20 20 20 20 20  nters.**        
35d30 20 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e    to zero-termin
35d40 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e  ated UTF-8 strin
35d50 67 73 20 77 68 69 63 68 20 61 72 65 20 74 68 65  gs which are the
35d60 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a   names of the.**
35d70 20 20 20 20 20 20 20 20 20 20 64 61 74 61 62 61            databa
35d80 73 65 20 61 6e 64 20 74 61 62 6c 65 20 74 68 61  se and table tha
35d90 74 20 69 73 20 62 65 69 6e 67 20 75 70 64 61 74  t is being updat
35da0 65 64 2e 0a 0a 2a 2a 20 7b 46 31 32 39 38 35 7d  ed...** {F12985}
35db0 20 54 68 65 20 66 69 6e 61 6c 20 63 61 6c 6c 62   The final callb
35dc0 61 63 6b 20 70 61 72 61 6d 65 74 65 72 20 69 73  ack parameter is
35dd0 20 74 68 65 20 72 6f 77 69 64 20 6f 66 20 74 68   the rowid of th
35de0 65 20 72 6f 77 20 61 66 74 65 72 0a 2a 2a 20 20  e row after.**  
35df0 20 20 20 20 20 20 20 20 74 68 65 20 63 68 61 6e          the chan
35e00 67 65 20 6f 63 63 75 72 73 2e 0a 2a 2f 0a 76 6f  ge occurs..*/.vo
35e10 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 70 64 61  id *sqlite3_upda
35e20 74 65 5f 68 6f 6f 6b 28 0a 20 20 73 71 6c 69 74  te_hook(.  sqlit
35e30 65 33 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28  e3*, .  void(*)(
35e40 76 6f 69 64 20 2a 2c 69 6e 74 20 2c 63 68 61 72  void *,int ,char
35e50 20 63 6f 6e 73 74 20 2a 2c 63 68 61 72 20 63 6f   const *,char co
35e60 6e 73 74 20 2a 2c 73 71 6c 69 74 65 33 5f 69 6e  nst *,sqlite3_in
35e70 74 36 34 29 2c 0a 20 20 76 6f 69 64 2a 0a 29 3b  t64),.  void*.);
35e80 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
35e90 3a 20 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73  :  Enable Or Dis
35ea0 61 62 6c 65 20 53 68 61 72 65 64 20 50 61 67 65  able Shared Page
35eb0 72 20 43 61 63 68 65 20 7b 46 31 30 33 33 30 7d  r Cache {F10330}
35ec0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
35ed0 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64  ine enables or d
35ee0 69 73 61 62 6c 65 73 20 74 68 65 20 73 68 61 72  isables the shar
35ef0 69 6e 67 20 6f 66 20 74 68 65 20 64 61 74 61 62  ing of the datab
35f00 61 73 65 20 63 61 63 68 65 0a 2a 2a 20 61 6e 64  ase cache.** and
35f10 20 73 63 68 65 6d 61 20 64 61 74 61 20 73 74 72   schema data str
35f20 75 63 74 75 72 65 73 20 62 65 74 77 65 65 6e 20  uctures between 
35f30 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 74 6f 20 74  connections to t
35f40 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
35f50 2e 0a 2a 2a 20 53 68 61 72 69 6e 67 20 69 73 20  ..** Sharing is 
35f60 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20 61  enabled if the a
35f70 72 67 75 6d 65 6e 74 20 69 73 20 74 72 75 65 20  rgument is true 
35f80 61 6e 64 20 64 69 73 61 62 6c 65 64 20 69 66 20  and disabled if 
35f90 74 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  the argument.** 
35fa0 69 73 20 66 61 6c 73 65 2e 0a 2a 2a 0a 2a 2a 20  is false..**.** 
35fb0 43 61 63 68 65 20 73 68 61 72 69 6e 67 20 69 73  Cache sharing is
35fc0 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 64 69 73   enabled and dis
35fd0 61 62 6c 65 64 0a 2a 2a 20 66 6f 72 20 61 6e 20  abled.** for an 
35fe0 65 6e 74 69 72 65 20 70 72 6f 63 65 73 73 2e 20  entire process. 
35ff0 7b 45 4e 44 7d 20 54 68 69 73 20 69 73 20 61 20  {END} This is a 
36000 63 68 61 6e 67 65 20 61 73 20 6f 66 20 53 51 4c  change as of SQL
36010 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e  ite version 3.5.
36020 30 2e 0a 2a 2a 20 49 6e 20 70 72 69 6f 72 20 76  0..** In prior v
36030 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
36040 65 2c 20 73 68 61 72 69 6e 67 20 77 61 73 0a 2a  e, sharing was.*
36050 2a 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73  * enabled or dis
36060 61 62 6c 65 64 20 66 6f 72 20 65 61 63 68 20 74  abled for each t
36070 68 72 65 61 64 20 73 65 70 61 72 61 74 65 6c 79  hread separately
36080 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 63 68  ..**.** The cach
36090 65 20 73 68 61 72 69 6e 67 20 6d 6f 64 65 20 73  e sharing mode s
360a0 65 74 20 62 79 20 74 68 69 73 20 69 6e 74 65 72  et by this inter
360b0 66 61 63 65 20 65 66 66 65 63 74 73 20 61 6c 6c  face effects all
360c0 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63   subsequent.** c
360d0 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
360e0 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
360f0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61  e3_open_v2()], a
36100 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  nd [sqlite3_open
36110 31 36 28 29 5d 2e 0a 2a 2a 20 45 78 69 73 74 69  16()]..** Existi
36120 6e 67 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ng database conn
36130 65 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65  ections continue
36140 20 75 73 65 20 74 68 65 20 73 68 61 72 69 6e 67   use the sharing
36150 20 6d 6f 64 65 0a 2a 2a 20 74 68 61 74 20 77 61   mode.** that wa
36160 73 20 69 6e 20 65 66 66 65 63 74 20 61 74 20 74  s in effect at t
36170 68 65 20 74 69 6d 65 20 74 68 65 79 20 77 65 72  he time they wer
36180 65 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  e opened..**.** 
36190 56 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 63  Virtual tables c
361a0 61 6e 6e 6f 74 20 62 65 20 75 73 65 64 20 77 69  annot be used wi
361b0 74 68 20 61 20 73 68 61 72 65 64 20 63 61 63 68  th a shared cach
361c0 65 2e 20 20 20 57 68 65 6e 20 73 68 61 72 65 64  e.   When shared
361d0 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61  .** cache is ena
361e0 62 6c 65 64 2c 20 74 68 65 20 5b 73 71 6c 69 74  bled, the [sqlit
361f0 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65  e3_create_module
36200 28 29 5d 20 41 50 49 20 75 73 65 64 20 74 6f 20  ()] API used to 
36210 72 65 67 69 73 74 65 72 0a 2a 2a 20 76 69 72 74  register.** virt
36220 75 61 6c 20 74 61 62 6c 65 73 20 77 69 6c 6c 20  ual tables will 
36230 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20 61 6e  always return an
36240 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68   error..**.** Th
36250 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  is routine retur
36260 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69  ns [SQLITE_OK] i
36270 66 20 73 68 61 72 65 64 20 63 61 63 68 65 20 77  f shared cache w
36280 61 73 0a 2a 2a 20 65 6e 61 62 6c 65 64 20 6f 72  as.** enabled or
36290 20 64 69 73 61 62 6c 65 64 20 73 75 63 63 65 73   disabled succes
362a0 73 66 75 6c 6c 79 2e 20 20 41 6e 20 5b 65 72 72  sfully.  An [err
362b0 6f 72 20 63 6f 64 65 5d 0a 2a 2a 20 69 73 20 72  or code].** is r
362c0 65 74 75 72 6e 65 64 20 6f 74 68 65 72 77 69 73  eturned otherwis
362d0 65 2e 0a 2a 2a 0a 2a 2a 20 53 68 61 72 65 64 20  e..**.** Shared 
362e0 63 61 63 68 65 20 69 73 20 64 69 73 61 62 6c 65  cache is disable
362f0 64 20 62 79 20 64 65 66 61 75 6c 74 2e 20 42 75  d by default. Bu
36300 74 20 74 68 69 73 20 6d 69 67 68 74 20 63 68 61  t this might cha
36310 6e 67 65 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65  nge in.** future
36320 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
36330 69 74 65 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ite.  Applicatio
36340 6e 73 20 74 68 61 74 20 63 61 72 65 20 61 62 6f  ns that care abo
36350 75 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63  ut shared.** cac
36360 68 65 20 73 65 74 74 69 6e 67 20 73 68 6f 75 6c  he setting shoul
36370 64 20 73 65 74 20 69 74 20 65 78 70 6c 69 63 69  d set it explici
36380 74 6c 79 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  tly..**.** INVAR
36390 49 41 4e 54 53 3a 0a 2a 2a 20 0a 2a 2a 20 7b 46  IANTS:.** .** {F
363a0 31 30 33 33 31 7d 20 41 20 73 75 63 63 65 73 73  10331} A success
363b0 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  ful invocation o
363c0 66 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c  f [sqlite3_enabl
363d0 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28 42  e_shared_cache(B
363e0 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77  )].**          w
363f0 69 6c 6c 20 65 6e 61 62 6c 65 20 6f 72 20 64 69  ill enable or di
36400 73 61 62 6c 65 20 73 68 61 72 65 64 20 63 61 63  sable shared cac
36410 68 65 20 6d 6f 64 65 20 66 6f 72 20 61 6e 79 20  he mode for any 
36420 73 75 62 73 65 71 75 65 6e 74 6c 79 0a 2a 2a 20  subsequently.** 
36430 20 20 20 20 20 20 20 20 20 63 72 65 61 74 65 64           created
36440 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
36450 63 74 69 6f 6e 5d 20 69 6e 20 74 68 65 20 73 61  ction] in the sa
36460 6d 65 20 70 72 6f 63 65 73 73 2e 0a 2a 2a 0a 2a  me process..**.*
36470 2a 20 7b 46 31 30 33 33 36 7d 20 57 68 65 6e 20  * {F10336} When 
36480 73 68 61 72 65 64 20 63 61 63 68 65 20 69 73 20  shared cache is 
36490 65 6e 61 62 6c 65 64 2c 20 74 68 65 20 5b 73 71  enabled, the [sq
364a0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64  lite3_create_mod
364b0 75 6c 65 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ule()].**       
364c0 20 20 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c     interface wil
364d0 6c 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20  l always return 
364e0 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20  an error..**.** 
364f0 7b 46 31 30 33 33 37 7d 20 54 68 65 20 5b 73 71  {F10337} The [sq
36500 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61  lite3_enable_sha
36510 72 65 64 5f 63 61 63 68 65 28 42 29 5d 20 69 6e  red_cache(B)] in
36520 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a  terface returns.
36530 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c  **          [SQL
36540 49 54 45 5f 4f 4b 5d 20 69 66 20 73 68 61 72 65  ITE_OK] if share
36550 64 20 63 61 63 68 65 20 77 61 73 20 65 6e 61 62  d cache was enab
36560 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 20  led or disabled 
36570 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 0a 2a 2a  successfully..**
36580 0a 2a 2a 20 7b 46 31 30 33 33 39 7d 20 53 68 61  .** {F10339} Sha
36590 72 65 64 20 63 61 63 68 65 20 69 73 20 64 69 73  red cache is dis
365a0 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
365b0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
365c0 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63  _enable_shared_c
365d0 61 63 68 65 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  ache(int);../*.*
365e0 2a 20 43 41 50 49 33 52 45 46 3a 20 20 41 74 74  * CAPI3REF:  Att
365f0 65 6d 70 74 20 54 6f 20 46 72 65 65 20 48 65 61  empt To Free Hea
36600 70 20 4d 65 6d 6f 72 79 20 7b 46 31 37 33 34 30  p Memory {F17340
36610 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  }.**.** The sqli
36620 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f  te3_release_memo
36630 72 79 28 29 20 69 6e 74 65 72 66 61 63 65 20 61  ry() interface a
36640 74 74 65 6d 70 74 73 20 74 6f 0a 2a 2a 20 66 72  ttempts to.** fr
36650 65 65 20 4e 20 62 79 74 65 73 20 6f 66 20 68 65  ee N bytes of he
36660 61 70 20 6d 65 6d 6f 72 79 20 62 79 20 64 65 61  ap memory by dea
36670 6c 6c 6f 63 61 74 69 6e 67 20 6e 6f 6e 2d 65 73  llocating non-es
36680 73 65 6e 74 69 61 6c 20 6d 65 6d 6f 72 79 0a 2a  sential memory.*
36690 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 68 65  * allocations he
366a0 6c 64 20 62 79 20 74 68 65 20 64 61 74 61 62 61  ld by the databa
366b0 73 65 20 6c 69 62 72 61 72 79 2e 20 7b 45 4e 44  se library. {END
366c0 7d 20 20 4d 65 6d 6f 72 79 20 75 73 65 64 0a 2a  }  Memory used.*
366d0 2a 20 74 6f 20 63 61 63 68 65 20 64 61 74 61 62  * to cache datab
366e0 61 73 65 20 70 61 67 65 73 20 74 6f 20 69 6d 70  ase pages to imp
366f0 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e 63 65  rove performance
36700 20 69 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f   is an example o
36710 66 0a 2a 2a 20 6e 6f 6e 2d 65 73 73 65 6e 74 69  f.** non-essenti
36720 61 6c 20 6d 65 6d 6f 72 79 2e 20 20 53 71 6c 69  al memory.  Sqli
36730 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f  te3_release_memo
36740 72 79 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20  ry() returns.** 
36750 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
36760 74 65 73 20 61 63 74 75 61 6c 6c 79 20 66 72 65  tes actually fre
36770 65 64 2c 20 77 68 69 63 68 20 6d 69 67 68 74 20  ed, which might 
36780 62 65 20 6d 6f 72 65 20 6f 72 20 6c 65 73 73 0a  be more or less.
36790 2a 2a 20 74 68 61 6e 20 74 68 65 20 61 6d 6f 75  ** than the amou
367a0 6e 74 20 72 65 71 75 65 73 74 65 64 2e 0a 2a 2a  nt requested..**
367b0 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
367c0 2a 2a 0a 2a 2a 20 7b 46 31 37 33 34 31 7d 20 54  **.** {F17341} T
367d0 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65  he [sqlite3_rele
367e0 61 73 65 5f 6d 65 6d 6f 72 79 28 4e 29 5d 20 69  ase_memory(N)] i
367f0 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74  nterface attempt
36800 73 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20  s to.**         
36810 20 66 72 65 65 20 4e 20 62 79 74 65 73 20 6f 66   free N bytes of
36820 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 62 79 20   heap memory by 
36830 64 65 61 6c 6c 6f 63 61 74 69 6e 67 20 6e 6f 6e  deallocating non
36840 2d 65 73 73 65 6e 74 69 61 6c 0a 2a 2a 20 20 20  -essential.**   
36850 20 20 20 20 20 20 20 6d 65 6d 6f 72 79 20 61 6c         memory al
36860 6c 6f 63 61 74 69 6f 6e 73 20 68 65 6c 64 20 62  locations held b
36870 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6c  y the database l
36880 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46  ibrary..**.** {F
36890 31 36 33 34 32 7d 20 54 68 65 20 5b 73 71 6c 69  16342} The [sqli
368a0 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f  te3_release_memo
368b0 72 79 28 4e 29 5d 20 72 65 74 75 72 6e 73 20 74  ry(N)] returns t
368c0 68 65 20 6e 75 6d 62 65 72 0a 2a 2a 20 20 20 20  he number.**    
368d0 20 20 20 20 20 20 6f 66 20 62 79 74 65 73 20 61        of bytes a
368e0 63 74 75 61 6c 6c 79 20 66 72 65 65 64 2c 20 77  ctually freed, w
368f0 68 69 63 68 20 6d 69 67 68 74 20 62 65 20 6d 6f  hich might be mo
36900 72 65 20 6f 72 20 6c 65 73 73 0a 2a 2a 20 20 20  re or less.**   
36910 20 20 20 20 20 20 20 74 68 61 6e 20 74 68 65 20         than the 
36920 61 6d 6f 75 6e 74 20 72 65 71 75 65 73 74 65 64  amount requested
36930 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
36940 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28  _release_memory(
36950 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
36960 49 33 52 45 46 3a 20 20 49 6d 70 6f 73 65 20 41  I3REF:  Impose A
36970 20 4c 69 6d 69 74 20 4f 6e 20 48 65 61 70 20 53   Limit On Heap S
36980 69 7a 65 20 7b 46 31 37 33 35 30 7d 0a 2a 2a 0a  ize {F17350}.**.
36990 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73  ** The sqlite3_s
369a0 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 29  oft_heap_limit()
369b0 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 70 6c   interface.** pl
369c0 61 63 65 73 20 61 20 22 73 6f 66 74 22 20 6c 69  aces a "soft" li
369d0 6d 69 74 20 6f 6e 20 74 68 65 20 61 6d 6f 75 6e  mit on the amoun
369e0 74 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 79  t of heap memory
369f0 20 74 68 61 74 20 6d 61 79 20 62 65 20 61 6c 6c   that may be all
36a00 6f 63 61 74 65 64 0a 2a 2a 20 62 79 20 53 51 4c  ocated.** by SQL
36a10 69 74 65 2e 20 49 66 20 61 6e 20 69 6e 74 65 72  ite. If an inter
36a20 6e 61 6c 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69  nal allocation i
36a30 73 20 72 65 71 75 65 73 74 65 64 20 0a 2a 2a 20  s requested .** 
36a40 74 68 61 74 20 77 6f 75 6c 64 20 65 78 63 65 65  that would excee
36a50 64 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20  d the soft heap 
36a60 6c 69 6d 69 74 2c 20 5b 73 71 6c 69 74 65 33 5f  limit, [sqlite3_
36a70 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29  release_memory()
36a80 5d 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20  ] is.** invoked 
36a90 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  one or more time
36aa0 73 20 74 6f 20 66 72 65 65 20 75 70 20 73 6f 6d  s to free up som
36ab0 65 20 73 70 61 63 65 20 62 65 66 6f 72 65 20 74  e space before t
36ac0 68 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  he allocation.**
36ad0 20 69 73 20 6d 61 64 65 2e 0a 2a 2a 0a 2a 2a 20   is made..**.** 
36ae0 54 68 65 20 6c 69 6d 69 74 20 69 73 20 63 61 6c  The limit is cal
36af0 6c 65 64 20 22 73 6f 66 74 22 2c 20 62 65 63 61  led "soft", beca
36b00 75 73 65 20 69 66 0a 2a 2a 20 5b 73 71 6c 69 74  use if.** [sqlit
36b10 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72  e3_release_memor
36b20 79 28 29 5d 20 63 61 6e 6e 6f 74 0a 2a 2a 20 66  y()] cannot.** f
36b30 72 65 65 20 73 75 66 66 69 63 69 65 6e 74 20 6d  ree sufficient m
36b40 65 6d 6f 72 79 20 74 6f 20 70 72 65 76 65 6e 74  emory to prevent
36b50 20 74 68 65 20 6c 69 6d 69 74 20 66 72 6f 6d 20   the limit from 
36b60 62 65 69 6e 67 20 65 78 63 65 65 64 65 64 2c 0a  being exceeded,.
36b70 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 69 73  ** the memory is
36b80 20 61 6c 6c 6f 63 61 74 65 64 20 61 6e 79 77 61   allocated anywa
36b90 79 20 61 6e 64 20 74 68 65 20 63 75 72 72 65 6e  y and the curren
36ba0 74 20 6f 70 65 72 61 74 69 6f 6e 20 70 72 6f 63  t operation proc
36bb0 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 6e 65  eeds..**.** A ne
36bc0 67 61 74 69 76 65 20 6f 72 20 7a 65 72 6f 20 76  gative or zero v
36bd0 61 6c 75 65 20 66 6f 72 20 4e 20 6d 65 61 6e 73  alue for N means
36be0 20 74 68 61 74 20 74 68 65 72 65 20 69 73 20 6e   that there is n
36bf0 6f 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69  o soft heap limi
36c00 74 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  t and.** [sqlite
36c10 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79  3_release_memory
36c20 28 29 5d 20 77 69 6c 6c 20 6f 6e 6c 79 20 62 65  ()] will only be
36c30 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 6d 65 6d   called when mem
36c40 6f 72 79 20 69 73 20 65 78 68 61 75 73 74 65 64  ory is exhausted
36c50 2e 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74  ..** The default
36c60 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 73   value for the s
36c70 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69  oft heap limit i
36c80 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 51  s zero..**.** SQ
36c90 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 62 65 73  Lite makes a bes
36ca0 74 20 65 66 66 6f 72 74 20 74 6f 20 68 6f 6e 6f  t effort to hono
36cb0 72 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20  r the soft heap 
36cc0 6c 69 6d 69 74 2e 20 20 0a 2a 2a 20 42 75 74 20  limit.  .** But 
36cd0 69 66 20 74 68 65 20 73 6f 66 74 20 68 65 61 70  if the soft heap
36ce0 20 6c 69 6d 69 74 20 63 61 6e 6e 6f 74 20 62 65   limit cannot be
36cf0 20 68 6f 6e 6f 72 65 64 2c 20 65 78 65 63 75 74   honored, execut
36d00 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74  ion will.** cont
36d10 69 6e 75 65 20 77 69 74 68 6f 75 74 20 65 72 72  inue without err
36d20 6f 72 20 6f 72 20 6e 6f 74 69 66 69 63 61 74 69  or or notificati
36d30 6f 6e 2e 20 20 54 68 69 73 20 69 73 20 77 68 79  on.  This is why
36d40 20 74 68 65 20 6c 69 6d 69 74 20 69 73 20 0a 2a   the limit is .*
36d50 2a 20 63 61 6c 6c 65 64 20 61 20 22 73 6f 66 74  * called a "soft
36d60 22 20 6c 69 6d 69 74 2e 20 20 49 74 20 69 73 20  " limit.  It is 
36d70 61 64 76 69 73 6f 72 79 20 6f 6e 6c 79 2e 0a 2a  advisory only..*
36d80 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53 51  *.** Prior to SQ
36d90 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35  Lite version 3.5
36da0 2e 30 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65  .0, this routine
36db0 20 6f 6e 6c 79 20 63 6f 6e 73 74 72 61 69 6e 65   only constraine
36dc0 64 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20  d the memory.** 
36dd0 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 61 20 73  allocated by a s
36de0 69 6e 67 6c 65 20 74 68 72 65 61 64 20 2d 20 74  ingle thread - t
36df0 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69  he same thread i
36e00 6e 20 77 68 69 63 68 20 74 68 69 73 20 72 6f 75  n which this rou
36e10 74 69 6e 65 0a 2a 2a 20 72 75 6e 73 2e 20 20 42  tine.** runs.  B
36e20 65 67 69 6e 6e 69 6e 67 20 77 69 74 68 20 53 51  eginning with SQ
36e30 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35  Lite version 3.5
36e40 2e 30 2c 20 74 68 65 20 73 6f 66 74 20 68 65 61  .0, the soft hea
36e50 70 20 6c 69 6d 69 74 20 69 73 0a 2a 2a 20 61 70  p limit is.** ap
36e60 70 6c 69 65 64 20 74 6f 20 61 6c 6c 20 74 68 72  plied to all thr
36e70 65 61 64 73 2e 20 54 68 65 20 76 61 6c 75 65 20  eads. The value 
36e80 73 70 65 63 69 66 69 65 64 20 66 6f 72 20 74 68  specified for th
36e90 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69  e soft heap limi
36ea0 74 0a 2a 2a 20 69 73 20 61 6e 20 75 70 70 65 72  t.** is an upper
36eb0 20 62 6f 75 6e 64 20 6f 6e 20 74 68 65 20 74 6f   bound on the to
36ec0 74 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  tal memory alloc
36ed0 61 74 69 6f 6e 20 66 6f 72 20 61 6c 6c 20 74 68  ation for all th
36ee0 72 65 61 64 73 2e 20 49 6e 0a 2a 2a 20 76 65 72  reads. In.** ver
36ef0 73 69 6f 6e 20 33 2e 35 2e 30 20 74 68 65 72 65  sion 3.5.0 there
36f00 20 69 73 20 6e 6f 20 6d 65 63 68 61 6e 69 73 6d   is no mechanism
36f10 20 66 6f 72 20 6c 69 6d 69 74 69 6e 67 20 74 68   for limiting th
36f20 65 20 68 65 61 70 20 75 73 61 67 65 20 66 6f 72  e heap usage for
36f30 0a 2a 2a 20 69 6e 64 69 76 69 64 75 61 6c 20 74  .** individual t
36f40 68 72 65 61 64 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e  hreads..**.** IN
36f50 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
36f60 7b 46 31 36 33 35 31 7d 20 54 68 65 20 5b 73 71  {F16351} The [sq
36f70 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f  lite3_soft_heap_
36f80 6c 69 6d 69 74 28 4e 29 5d 20 69 6e 74 65 72 66  limit(N)] interf
36f90 61 63 65 20 70 6c 61 63 65 73 20 61 20 73 6f 66  ace places a sof
36fa0 74 20 6c 69 6d 69 74 0a 2a 2a 20 20 20 20 20 20  t limit.**      
36fb0 20 20 20 20 6f 66 20 4e 20 62 79 74 65 73 20 6f      of N bytes o
36fc0 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20  n the amount of 
36fd0 68 65 61 70 20 6d 65 6d 6f 72 79 20 74 68 61 74  heap memory that
36fe0 20 6d 61 79 20 62 65 20 61 6c 6c 6f 63 61 74 65   may be allocate
36ff0 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 75 73  d.**          us
37000 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  ing [sqlite3_mal
37010 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  loc()] or [sqlit
37020 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 61 74  e3_realloc()] at
37030 20 61 6e 79 20 70 6f 69 6e 74 0a 2a 2a 20 20 20   any point.**   
37040 20 20 20 20 20 20 20 69 6e 20 74 69 6d 65 2e 0a         in time..
37050 2a 2a 0a 2a 2a 20 7b 46 31 36 33 35 32 7d 20 49  **.** {F16352} I
37060 66 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  f a call to [sql
37070 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f  ite3_malloc()] o
37080 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  r [sqlite3_reall
37090 6f 63 28 29 5d 20 77 6f 75 6c 64 0a 2a 2a 20 20  oc()] would.**  
370a0 20 20 20 20 20 20 20 20 63 61 75 73 65 20 74 68          cause th
370b0 65 20 74 6f 74 61 6c 20 61 6d 6f 75 6e 74 20 6f  e total amount o
370c0 66 20 61 6c 6c 6f 63 61 74 65 64 20 6d 65 6d 6f  f allocated memo
370d0 72 79 20 74 6f 20 65 78 63 65 65 64 20 74 68 65  ry to exceed the
370e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 6f 66  .**          sof
370f0 74 20 68 65 61 70 20 6c 69 6d 69 74 2c 20 74 68  t heap limit, th
37100 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65  en [sqlite3_rele
37110 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 69 73  ase_memory()] is
37120 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 20 20 20 20   invoked.**     
37130 20 20 20 20 20 69 6e 20 61 6e 20 61 74 74 65 6d       in an attem
37140 70 74 20 74 6f 20 72 65 64 75 63 65 20 74 68 65  pt to reduce the
37150 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 20 70 72   memory usage pr
37160 69 6f 72 20 74 6f 20 70 72 6f 63 65 65 64 69 6e  ior to proceedin
37170 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69  g.**          wi
37180 74 68 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c  th the memory al
37190 6c 6f 63 61 74 69 6f 6e 20 61 74 74 65 6d 70 74  location attempt
371a0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 33 35 33 7d  ..**.** {F16353}
371b0 20 43 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   Calls to [sqlit
371c0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20  e3_malloc()] or 
371d0 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
371e0 28 29 5d 20 74 68 61 74 20 74 72 69 67 67 65 72  ()] that trigger
371f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 74 74  .**          att
37200 65 6d 70 74 73 20 74 6f 20 72 65 64 75 63 65 20  empts to reduce 
37210 6d 65 6d 6f 72 79 20 75 73 61 67 65 20 74 68 72  memory usage thr
37220 6f 75 67 68 20 74 68 65 20 73 6f 66 74 20 68 65  ough the soft he
37230 61 70 20 6c 69 6d 69 74 0a 2a 2a 20 20 20 20 20  ap limit.**     
37240 20 20 20 20 20 6d 65 63 68 61 6e 69 73 6d 20 63       mechanism c
37250 6f 6e 74 69 6e 75 65 20 65 76 65 6e 20 69 66 20  ontinue even if 
37260 74 68 65 20 61 74 74 65 6d 70 74 20 74 6f 20 72  the attempt to r
37270 65 64 75 63 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20  educe memory.** 
37280 20 20 20 20 20 20 20 20 20 75 73 61 67 65 20 69           usage i
37290 73 20 75 6e 73 75 63 63 65 73 73 66 75 6c 2e 0a  s unsuccessful..
372a0 2a 2a 0a 2a 2a 20 7b 46 31 36 33 35 34 7d 20 41  **.** {F16354} A
372b0 20 6e 65 67 61 74 69 76 65 20 6f 72 20 7a 65 72   negative or zer
372c0 6f 20 76 61 6c 75 65 20 66 6f 72 20 4e 20 69 6e  o value for N in
372d0 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 20 20   a call to.**   
372e0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
372f0 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28  soft_heap_limit(
37300 4e 29 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74  N)] means that t
37310 68 65 72 65 20 69 73 20 6e 6f 20 73 6f 66 74 0a  here is no soft.
37320 2a 2a 20 20 20 20 20 20 20 20 20 20 68 65 61 70  **          heap
37330 20 6c 69 6d 69 74 20 61 6e 64 20 5b 73 71 6c 69   limit and [sqli
37340 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f  te3_release_memo
37350 72 79 28 29 5d 20 77 69 6c 6c 20 6f 6e 6c 79 20  ry()] will only 
37360 62 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63  be.**          c
37370 61 6c 6c 65 64 20 77 68 65 6e 20 6d 65 6d 6f 72  alled when memor
37380 79 20 69 73 20 63 6f 6d 70 6c 65 74 65 6c 79 20  y is completely 
37390 65 78 68 61 75 73 74 65 64 2e 0a 2a 2a 0a 2a 2a  exhausted..**.**
373a0 20 7b 46 31 36 33 35 35 7d 20 54 68 65 20 64 65   {F16355} The de
373b0 66 61 75 6c 74 20 76 61 6c 75 65 20 66 6f 72 20  fault value for 
373c0 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69  the soft heap li
373d0 6d 69 74 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 0a  mit is zero..**.
373e0 2a 2a 20 7b 46 31 36 33 35 38 7d 20 45 61 63 68  ** {F16358} Each
373f0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
37400 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69  3_soft_heap_limi
37410 74 28 4e 29 5d 20 6f 76 65 72 72 69 64 65 73 20  t(N)] overrides 
37420 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
37430 76 61 6c 75 65 73 20 73 65 74 20 62 79 20 61 6c  values set by al
37440 6c 20 70 72 69 6f 72 20 63 61 6c 6c 73 2e 0a 2a  l prior calls..*
37450 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73  /.void sqlite3_s
37460 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 69  oft_heap_limit(i
37470 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
37480 33 52 45 46 3a 20 20 45 78 74 72 61 63 74 20 4d  3REF:  Extract M
37490 65 74 61 64 61 74 61 20 41 62 6f 75 74 20 41 20  etadata About A 
374a0 43 6f 6c 75 6d 6e 20 4f 66 20 41 20 54 61 62 6c  Column Of A Tabl
374b0 65 20 7b 46 31 32 38 35 30 7d 0a 2a 2a 0a 2a 2a  e {F12850}.**.**
374c0 20 54 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a   This routine.**
374d0 20 72 65 74 75 72 6e 73 20 6d 65 74 61 2d 64 61   returns meta-da
374e0 74 61 20 61 62 6f 75 74 20 61 20 73 70 65 63 69  ta about a speci
374f0 66 69 63 20 63 6f 6c 75 6d 6e 20 6f 66 20 61 20  fic column of a 
37500 73 70 65 63 69 66 69 63 20 64 61 74 61 62 61 73  specific databas
37510 65 0a 2a 2a 20 74 61 62 6c 65 20 61 63 63 65 73  e.** table acces
37520 73 69 62 6c 65 20 75 73 69 6e 67 20 74 68 65 20  sible using the 
37530 63 6f 6e 6e 65 63 74 69 6f 6e 20 68 61 6e 64 6c  connection handl
37540 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
37550 66 69 72 73 74 20 66 75 6e 63 74 69 6f 6e 20 0a  first function .
37560 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  ** argument..**.
37570 2a 2a 20 54 68 65 20 63 6f 6c 75 6d 6e 20 69 73  ** The column is
37580 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74   identified by t
37590 68 65 20 73 65 63 6f 6e 64 2c 20 74 68 69 72 64  he second, third
375a0 20 61 6e 64 20 66 6f 75 72 74 68 20 70 61 72 61   and fourth para
375b0 6d 65 74 65 72 73 20 74 6f 20 0a 2a 2a 20 74 68  meters to .** th
375c0 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65  is function. The
375d0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
375e0 72 20 69 73 20 65 69 74 68 65 72 20 74 68 65 20  r is either the 
375f0 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61  name of the data
37600 62 61 73 65 0a 2a 2a 20 28 69 2e 65 2e 20 22 6d  base.** (i.e. "m
37610 61 69 6e 22 2c 20 22 74 65 6d 70 22 20 6f 72 20  ain", "temp" or 
37620 61 6e 20 61 74 74 61 63 68 65 64 20 64 61 74 61  an attached data
37630 62 61 73 65 29 20 63 6f 6e 74 61 69 6e 69 6e 67  base) containing
37640 20 74 68 65 20 73 70 65 63 69 66 69 65 64 0a 2a   the specified.*
37650 2a 20 74 61 62 6c 65 20 6f 72 20 4e 55 4c 4c 2e  * table or NULL.
37660 20 49 66 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20   If it is NULL, 
37670 74 68 65 6e 20 61 6c 6c 20 61 74 74 61 63 68 65  then all attache
37680 64 20 64 61 74 61 62 61 73 65 73 20 61 72 65 20  d databases are 
37690 73 65 61 72 63 68 65 64 0a 2a 2a 20 66 6f 72 20  searched.** for 
376a0 74 68 65 20 74 61 62 6c 65 20 75 73 69 6e 67 20  the table using 
376b0 74 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74  the same algorit
376c0 68 6d 20 61 73 20 74 68 65 20 64 61 74 61 62 61  hm as the databa
376d0 73 65 20 65 6e 67 69 6e 65 20 75 73 65 73 20 74  se engine uses t
376e0 6f 20 0a 2a 2a 20 72 65 73 6f 6c 76 65 20 75 6e  o .** resolve un
376f0 71 75 61 6c 69 66 69 65 64 20 74 61 62 6c 65 20  qualified table 
37700 72 65 66 65 72 65 6e 63 65 73 2e 0a 2a 2a 0a 2a  references..**.*
37710 2a 20 54 68 65 20 74 68 69 72 64 20 61 6e 64 20  * The third and 
37720 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
37730 73 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69  s to this functi
37740 6f 6e 20 61 72 65 20 74 68 65 20 74 61 62 6c 65  on are the table
37750 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 0a 2a 2a 20   and column .** 
37760 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 65 73 69  name of the desi
37770 72 65 64 20 63 6f 6c 75 6d 6e 2c 20 72 65 73 70  red column, resp
37780 65 63 74 69 76 65 6c 79 2e 20 4e 65 69 74 68 65  ectively. Neithe
37790 72 20 6f 66 20 74 68 65 73 65 20 70 61 72 61 6d  r of these param
377a0 65 74 65 72 73 20 0a 2a 2a 20 6d 61 79 20 62 65  eters .** may be
377b0 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 4d 65 74   NULL..**.** Met
377c0 61 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  a information is
377d0 20 72 65 74 75 72 6e 65 64 20 62 79 20 77 72 69   returned by wri
377e0 74 69 6e 67 20 74 6f 20 74 68 65 20 6d 65 6d 6f  ting to the memo
377f0 72 79 20 6c 6f 63 61 74 69 6f 6e 73 20 70 61 73  ry locations pas
37800 73 65 64 20 61 73 0a 2a 2a 20 74 68 65 20 35 74  sed as.** the 5t
37810 68 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74  h and subsequent
37820 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74   parameters to t
37830 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20 41 6e  his function. An
37840 79 20 6f 66 20 74 68 65 73 65 20 0a 2a 2a 20 61  y of these .** a
37850 72 67 75 6d 65 6e 74 73 20 6d 61 79 20 62 65 20  rguments may be 
37860 4e 55 4c 4c 2c 20 69 6e 20 77 68 69 63 68 20 63  NULL, in which c
37870 61 73 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f  ase the correspo
37880 6e 64 69 6e 67 20 65 6c 65 6d 65 6e 74 20 6f 66  nding element of
37890 20 6d 65 74 61 20 0a 2a 2a 20 69 6e 66 6f 72 6d   meta .** inform
378a0 61 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64  ation is omitted
378b0 2e 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a  ..**.** <pre>.**
378c0 20 50 61 72 61 6d 65 74 65 72 20 20 20 20 20 4f   Parameter     O
378d0 75 74 70 75 74 20 54 79 70 65 20 20 20 20 20 20  utput Type      
378e0 44 65 73 63 72 69 70 74 69 6f 6e 0a 2a 2a 20 2d  Description.** -
378f0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
37900 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
37910 2d 2d 0a 2a 2a 0a 2a 2a 20 20 20 35 74 68 20 20  --.**.**   5th  
37920 20 20 20 20 20 20 20 63 6f 6e 73 74 20 63 68 61         const cha
37930 72 2a 20 20 20 20 20 20 44 61 74 61 20 74 79 70  r*      Data typ
37940 65 0a 2a 2a 20 20 20 36 74 68 20 20 20 20 20 20  e.**   6th      
37950 20 20 20 63 6f 6e 73 74 20 63 68 61 72 2a 20 20     const char*  
37960 20 20 20 20 4e 61 6d 65 20 6f 66 20 74 68 65 20      Name of the 
37970 64 65 66 61 75 6c 74 20 63 6f 6c 6c 61 74 69 6f  default collatio
37980 6e 20 73 65 71 75 65 6e 63 65 20 0a 2a 2a 20 20  n sequence .**  
37990 20 37 74 68 20 20 20 20 20 20 20 20 20 69 6e 74   7th         int
379a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 54 72                Tr
379b0 75 65 20 69 66 20 74 68 65 20 63 6f 6c 75 6d 6e  ue if the column
379c0 20 68 61 73 20 61 20 4e 4f 54 20 4e 55 4c 4c 20   has a NOT NULL 
379d0 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 20 20  constraint.**   
379e0 38 74 68 20 20 20 20 20 20 20 20 20 69 6e 74 20  8th         int 
379f0 20 20 20 20 20 20 20 20 20 20 20 20 20 54 72 75               Tru
37a00 65 20 69 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20  e if the column 
37a10 69 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 50  is part of the P
37a20 52 49 4d 41 52 59 20 4b 45 59 0a 2a 2a 20 20 20  RIMARY KEY.**   
37a30 39 74 68 20 20 20 20 20 20 20 20 20 69 6e 74 20  9th         int 
37a40 20 20 20 20 20 20 20 20 20 20 20 20 20 54 72 75               Tru
37a50 65 20 69 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20  e if the column 
37a60 69 73 20 41 55 54 4f 49 4e 43 52 45 4d 45 4e 54  is AUTOINCREMENT
37a70 0a 2a 2a 20 3c 2f 70 72 65 3e 0a 2a 2a 0a 2a 2a  .** </pre>.**.**
37a80 0a 2a 2a 20 54 68 65 20 6d 65 6d 6f 72 79 20 70  .** The memory p
37a90 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65  ointed to by the
37aa0 20 63 68 61 72 61 63 74 65 72 20 70 6f 69 6e 74   character point
37ab0 65 72 73 20 72 65 74 75 72 6e 65 64 20 66 6f 72  ers returned for
37ac0 20 74 68 65 20 0a 2a 2a 20 64 65 63 6c 61 72 61   the .** declara
37ad0 74 69 6f 6e 20 74 79 70 65 20 61 6e 64 20 63 6f  tion type and co
37ae0 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
37af0 20 69 73 20 76 61 6c 69 64 20 6f 6e 6c 79 20 75   is valid only u
37b00 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20 0a 2a  ntil the next .*
37b10 2a 20 63 61 6c 6c 20 74 6f 20 61 6e 79 20 73 71  * call to any sq
37b20 6c 69 74 65 20 41 50 49 20 66 75 6e 63 74 69 6f  lite API functio
37b30 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  n..**.** If the 
37b40 73 70 65 63 69 66 69 65 64 20 74 61 62 6c 65 20  specified table 
37b50 69 73 20 61 63 74 75 61 6c 6c 79 20 61 20 76 69  is actually a vi
37b60 65 77 2c 20 74 68 65 6e 20 61 6e 20 65 72 72 6f  ew, then an erro
37b70 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  r is returned..*
37b80 2a 0a 2a 2a 20 49 66 20 74 68 65 20 73 70 65 63  *.** If the spec
37b90 69 66 69 65 64 20 63 6f 6c 75 6d 6e 20 69 73 20  ified column is 
37ba0 22 72 6f 77 69 64 22 2c 20 22 6f 69 64 22 20 6f  "rowid", "oid" o
37bb0 72 20 22 5f 72 6f 77 69 64 5f 22 20 61 6e 64 20  r "_rowid_" and 
37bc0 61 6e 20 0a 2a 2a 20 49 4e 54 45 47 45 52 20 50  an .** INTEGER P
37bd0 52 49 4d 41 52 59 20 4b 45 59 20 63 6f 6c 75 6d  RIMARY KEY colum
37be0 6e 20 68 61 73 20 62 65 65 6e 20 65 78 70 6c 69  n has been expli
37bf0 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 2c 20  citly declared, 
37c00 74 68 65 6e 20 74 68 65 20 6f 75 74 70 75 74 20  then the output 
37c10 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 61  .** parameters a
37c20 72 65 20 73 65 74 20 66 6f 72 20 74 68 65 20 65  re set for the e
37c30 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72  xplicitly declar
37c40 65 64 20 63 6f 6c 75 6d 6e 2e 20 49 66 20 74 68  ed column. If th
37c50 65 72 65 20 69 73 20 6e 6f 0a 2a 2a 20 65 78 70  ere is no.** exp
37c60 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64  licitly declared
37c70 20 49 50 4b 20 63 6f 6c 75 6d 6e 2c 20 74 68 65   IPK column, the
37c80 6e 20 74 68 65 20 6f 75 74 70 75 74 20 70 61 72  n the output par
37c90 61 6d 65 74 65 72 73 20 61 72 65 20 73 65 74 20  ameters are set 
37ca0 61 73 20 0a 2a 2a 20 66 6f 6c 6c 6f 77 73 3a 0a  as .** follows:.
37cb0 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20  **.** <pre>.**  
37cc0 20 20 20 64 61 74 61 20 74 79 70 65 3a 20 22 49     data type: "I
37cd0 4e 54 45 47 45 52 22 0a 2a 2a 20 20 20 20 20 63  NTEGER".**     c
37ce0 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
37cf0 65 3a 20 22 42 49 4e 41 52 59 22 0a 2a 2a 20 20  e: "BINARY".**  
37d00 20 20 20 6e 6f 74 20 6e 75 6c 6c 3a 20 30 0a 2a     not null: 0.*
37d10 2a 20 20 20 20 20 70 72 69 6d 61 72 79 20 6b 65  *     primary ke
37d20 79 3a 20 31 0a 2a 2a 20 20 20 20 20 61 75 74 6f  y: 1.**     auto
37d30 20 69 6e 63 72 65 6d 65 6e 74 3a 20 30 0a 2a 2a   increment: 0.**
37d40 20 3c 2f 70 72 65 3e 0a 2a 2a 0a 2a 2a 20 54 68   </pre>.**.** Th
37d50 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20  is function may 
37d60 6c 6f 61 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  load one or more
37d70 20 73 63 68 65 6d 61 73 20 66 72 6f 6d 20 64 61   schemas from da
37d80 74 61 62 61 73 65 20 66 69 6c 65 73 2e 20 49 66  tabase files. If
37d90 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 6f 63 63   an.** error occ
37da0 75 72 73 20 64 75 72 69 6e 67 20 74 68 69 73 20  urs during this 
37db0 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 74  process, or if t
37dc0 68 65 20 72 65 71 75 65 73 74 65 64 20 74 61 62  he requested tab
37dd0 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  le or column.** 
37de0 63 61 6e 6e 6f 74 20 62 65 20 66 6f 75 6e 64 2c  cannot be found,
37df0 20 61 6e 20 53 51 4c 49 54 45 20 65 72 72 6f 72   an SQLITE error
37e00 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65   code is returne
37e10 64 20 61 6e 64 20 61 6e 20 65 72 72 6f 72 20 6d  d and an error m
37e20 65 73 73 61 67 65 0a 2a 2a 20 6c 65 66 74 20 69  essage.** left i
37e30 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 68  n the database h
37e40 61 6e 64 6c 65 20 28 74 6f 20 62 65 20 72 65 74  andle (to be ret
37e50 72 69 65 76 65 64 20 75 73 69 6e 67 20 73 71 6c  rieved using sql
37e60 69 74 65 33 5f 65 72 72 6d 73 67 28 29 29 2e 0a  ite3_errmsg())..
37e70 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49 20 69  **.** This API i
37e80 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65  s only available
37e90 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 20   if the library 
37ea0 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74  was compiled wit
37eb0 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f  h the.** SQLITE_
37ec0 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45  ENABLE_COLUMN_ME
37ed0 54 41 44 41 54 41 20 70 72 65 70 72 6f 63 65 73  TADATA preproces
37ee0 73 6f 72 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e  sor symbol defin
37ef0 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ed..*/.int sqlit
37f00 65 33 5f 74 61 62 6c 65 5f 63 6f 6c 75 6d 6e 5f  e3_table_column_
37f10 6d 65 74 61 64 61 74 61 28 0a 20 20 73 71 6c 69  metadata(.  sqli
37f20 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
37f30 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e 6e 65          /* Conne
37f40 63 74 69 6f 6e 20 68 61 6e 64 6c 65 20 2a 2f 0a  ction handle */.
37f50 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44    const char *zD
37f60 62 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 2f 2a  bName,        /*
37f70 20 44 61 74 61 62 61 73 65 20 6e 61 6d 65 20 6f   Database name o
37f80 72 20 4e 55 4c 4c 20 2a 2f 0a 20 20 63 6f 6e 73  r NULL */.  cons
37f90 74 20 63 68 61 72 20 2a 7a 54 61 62 6c 65 4e 61  t char *zTableNa
37fa0 6d 65 2c 20 20 20 20 20 2f 2a 20 54 61 62 6c 65  me,     /* Table
37fb0 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 6f 6e 73 74   name */.  const
37fc0 20 63 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e 4e 61   char *zColumnNa
37fd0 6d 65 2c 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e  me,    /* Column
37fe0 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 68 61 72 20   name */.  char 
37ff0 63 6f 6e 73 74 20 2a 2a 70 7a 44 61 74 61 54 79  const **pzDataTy
38000 70 65 2c 20 20 20 20 2f 2a 20 4f 55 54 50 55 54  pe,    /* OUTPUT
38010 3a 20 44 65 63 6c 61 72 65 64 20 64 61 74 61 20  : Declared data 
38020 74 79 70 65 20 2a 2f 0a 20 20 63 68 61 72 20 63  type */.  char c
38030 6f 6e 73 74 20 2a 2a 70 7a 43 6f 6c 6c 53 65 71  onst **pzCollSeq
38040 2c 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a  ,     /* OUTPUT:
38050 20 43 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   Collation seque
38060 6e 63 65 20 6e 61 6d 65 20 2a 2f 0a 20 20 69 6e  nce name */.  in
38070 74 20 2a 70 4e 6f 74 4e 75 6c 6c 2c 20 20 20 20  t *pNotNull,    
38080 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54            /* OUT
38090 50 55 54 3a 20 54 72 75 65 20 69 66 20 4e 4f 54  PUT: True if NOT
380a0 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69 6e 74   NULL constraint
380b0 20 65 78 69 73 74 73 20 2a 2f 0a 20 20 69 6e 74   exists */.  int
380c0 20 2a 70 50 72 69 6d 61 72 79 4b 65 79 2c 20 20   *pPrimaryKey,  
380d0 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50           /* OUTP
380e0 55 54 3a 20 54 72 75 65 20 69 66 20 63 6f 6c 75  UT: True if colu
380f0 6d 6e 20 70 61 72 74 20 6f 66 20 50 4b 20 2a 2f  mn part of PK */
38100 0a 20 20 69 6e 74 20 2a 70 41 75 74 6f 69 6e 63  .  int *pAutoinc
38110 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
38120 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65 20 69  * OUTPUT: True i
38130 66 20 63 6f 6c 75 6d 6e 20 69 73 20 61 75 74 6f  f column is auto
38140 2d 69 6e 63 72 65 6d 65 6e 74 20 2a 2f 0a 29 3b  -increment */.);
38150 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
38160 3a 20 4c 6f 61 64 20 41 6e 20 45 78 74 65 6e 73  : Load An Extens
38170 69 6f 6e 20 7b 46 31 32 36 30 30 7d 0a 2a 2a 0a  ion {F12600}.**.
38180 2a 2a 20 7b 46 31 32 36 30 31 7d 20 54 68 65 20  ** {F12601} The 
38190 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74  sqlite3_load_ext
381a0 65 6e 73 69 6f 6e 28 29 20 69 6e 74 65 72 66 61  ension() interfa
381b0 63 65 0a 2a 2a 20 61 74 74 65 6d 70 74 73 20 74  ce.** attempts t
381c0 6f 20 6c 6f 61 64 20 61 6e 20 53 51 4c 69 74 65  o load an SQLite
381d0 20 65 78 74 65 6e 73 69 6f 6e 20 6c 69 62 72 61   extension libra
381e0 72 79 20 63 6f 6e 74 61 69 6e 65 64 20 69 6e 20  ry contained in 
381f0 74 68 65 20 66 69 6c 65 0a 2a 2a 20 7a 46 69 6c  the file.** zFil
38200 65 2e 20 7b 46 31 32 36 30 32 7d 20 54 68 65 20  e. {F12602} The 
38210 65 6e 74 72 79 20 70 6f 69 6e 74 20 69 73 20 7a  entry point is z
38220 50 72 6f 63 2e 20 7b 46 31 32 36 30 33 7d 20 7a  Proc. {F12603} z
38230 50 72 6f 63 20 6d 61 79 20 62 65 20 30 0a 2a 2a  Proc may be 0.**
38240 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 74   in which case t
38250 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 65  he name of the e
38260 6e 74 72 79 20 70 6f 69 6e 74 20 64 65 66 61 75  ntry point defau
38270 6c 74 73 0a 2a 2a 20 74 6f 20 22 73 71 6c 69 74  lts.** to "sqlit
38280 65 33 5f 65 78 74 65 6e 73 69 6f 6e 5f 69 6e 69  e3_extension_ini
38290 74 22 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36 30  t"..**.** {F1260
382a0 34 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6c  4} The sqlite3_l
382b0 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20  oad_extension() 
382c0 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c 0a  interface shall.
382d0 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ** return [SQLIT
382e0 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73  E_OK] on success
382f0 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 45 52 52   and [SQLITE_ERR
38300 4f 52 5d 20 69 66 20 73 6f 6d 65 74 68 69 6e 67  OR] if something
38310 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 0a   goes wrong..**.
38320 2a 2a 20 7b 46 31 32 36 30 35 7d 0a 2a 2a 20 49  ** {F12605}.** I
38330 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  f an error occur
38340 73 20 61 6e 64 20 70 7a 45 72 72 4d 73 67 20 69  s and pzErrMsg i
38350 73 20 6e 6f 74 20 30 2c 20 74 68 65 6e 20 74 68  s not 0, then th
38360 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6c 6f 61  e.** sqlite3_loa
38370 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e  d_extension() in
38380 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20 61 74  terface shall at
38390 74 65 6d 70 74 20 74 6f 20 66 69 6c 6c 20 2a 70  tempt to fill *p
383a0 7a 45 72 72 4d 73 67 20 77 69 74 68 20 0a 2a 2a  zErrMsg with .**
383b0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74   error message t
383c0 65 78 74 20 73 74 6f 72 65 64 20 69 6e 20 6d 65  ext stored in me
383d0 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
383e0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
383f0 6f 63 28 29 5d 2e 0a 2a 2a 20 7b 45 4e 44 7d 20  oc()]..** {END} 
38400 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e   The calling fun
38410 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 66 72 65  ction should fre
38420 65 20 74 68 69 73 20 6d 65 6d 6f 72 79 0a 2a 2a  e this memory.**
38430 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c   by calling [sql
38440 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a  ite3_free()]..**
38450 0a 2a 2a 20 7b 46 31 32 36 30 36 7d 0a 2a 2a 20  .** {F12606}.** 
38460 45 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e  Extension loadin
38470 67 20 6d 75 73 74 20 62 65 20 65 6e 61 62 6c 65  g must be enable
38480 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
38490 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74  _enable_load_ext
384a0 65 6e 73 69 6f 6e 28 29 5d 0a 2a 2a 20 70 72 69  ension()].** pri
384b0 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20 74 68  or to calling th
384c0 69 73 20 41 50 49 20 6f 72 20 61 6e 20 65 72 72  is API or an err
384d0 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 74 75 72  or will be retur
384e0 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ned..*/.int sqli
384f0 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69  te3_load_extensi
38500 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  on(.  sqlite3 *d
38510 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4c  b,          /* L
38520 6f 61 64 20 74 68 65 20 65 78 74 65 6e 73 69 6f  oad the extensio
38530 6e 20 69 6e 74 6f 20 74 68 69 73 20 64 61 74 61  n into this data
38540 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
38550 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
38560 2a 7a 46 69 6c 65 2c 20 20 20 20 2f 2a 20 4e 61  *zFile,    /* Na
38570 6d 65 20 6f 66 20 74 68 65 20 73 68 61 72 65 64  me of the shared
38580 20 6c 69 62 72 61 72 79 20 63 6f 6e 74 61 69 6e   library contain
38590 69 6e 67 20 65 78 74 65 6e 73 69 6f 6e 20 2a 2f  ing extension */
385a0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
385b0 50 72 6f 63 2c 20 20 20 20 2f 2a 20 45 6e 74 72  Proc,    /* Entr
385c0 79 20 70 6f 69 6e 74 2e 20 20 44 65 72 69 76 65  y point.  Derive
385d0 64 20 66 72 6f 6d 20 7a 46 69 6c 65 20 69 66 20  d from zFile if 
385e0 30 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a  0 */.  char **pz
385f0 45 72 72 4d 73 67 20 20 20 20 20 20 20 2f 2a 20  ErrMsg       /* 
38600 50 75 74 20 65 72 72 6f 72 20 6d 65 73 73 61 67  Put error messag
38610 65 20 68 65 72 65 20 69 66 20 6e 6f 74 20 30 20  e here if not 0 
38620 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
38630 49 33 52 45 46 3a 20 20 45 6e 61 62 6c 65 20 4f  I3REF:  Enable O
38640 72 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e 73  r Disable Extens
38650 69 6f 6e 20 4c 6f 61 64 69 6e 67 20 7b 46 31 32  ion Loading {F12
38660 36 32 30 7d 0a 2a 2a 0a 2a 2a 20 53 6f 20 61 73  620}.**.** So as
38670 20 6e 6f 74 20 74 6f 20 6f 70 65 6e 20 73 65 63   not to open sec
38680 75 72 69 74 79 20 68 6f 6c 65 73 20 69 6e 20 6f  urity holes in o
38690 6c 64 65 72 20 61 70 70 6c 69 63 61 74 69 6f 6e  lder application
386a0 73 20 74 68 61 74 20 61 72 65 0a 2a 2a 20 75 6e  s that are.** un
386b0 70 72 65 70 61 72 65 64 20 74 6f 20 64 65 61 6c  prepared to deal
386c0 20 77 69 74 68 20 65 78 74 65 6e 73 69 6f 6e 20   with extension 
386d0 6c 6f 61 64 69 6e 67 2c 20 61 6e 64 20 61 73 20  loading, and as 
386e0 61 20 6d 65 61 6e 73 20 6f 66 20 64 69 73 61 62  a means of disab
386f0 6c 69 6e 67 0a 2a 2a 20 65 78 74 65 6e 73 69 6f  ling.** extensio
38700 6e 20 6c 6f 61 64 69 6e 67 20 77 68 69 6c 65 20  n loading while 
38710 65 76 61 6c 75 61 74 69 6e 67 20 75 73 65 72 2d  evaluating user-
38720 65 6e 74 65 72 65 64 20 53 51 4c 2c 20 74 68 65  entered SQL, the
38730 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 41 50   following.** AP
38740 49 20 69 73 20 70 72 6f 76 69 64 65 64 20 74 6f  I is provided to
38750 20 74 75 72 6e 20 74 68 65 20 5b 73 71 6c 69 74   turn the [sqlit
38760 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  e3_load_extensio
38770 6e 28 29 5d 20 6d 65 63 68 61 6e 69 73 6d 20 6f  n()] mechanism o
38780 6e 20 61 6e 64 0a 2a 2a 20 6f 66 66 2e 20 20 7b  n and.** off.  {
38790 46 31 32 36 32 32 7d 20 49 74 20 69 73 20 6f 66  F12622} It is of
387a0 66 20 62 79 20 64 65 66 61 75 6c 74 2e 20 7b 45  f by default. {E
387b0 4e 44 7d 20 53 65 65 20 74 69 63 6b 65 74 20 23  ND} See ticket #
387c0 31 38 36 33 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  1863..**.** {F12
387d0 36 32 31 7d 20 43 61 6c 6c 20 74 68 65 20 73 71  621} Call the sq
387e0 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61  lite3_enable_loa
387f0 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 72 6f  d_extension() ro
38800 75 74 69 6e 65 0a 2a 2a 20 77 69 74 68 20 6f 6e  utine.** with on
38810 6f 66 66 3d 3d 31 20 74 6f 20 74 75 72 6e 20 65  off==1 to turn e
38820 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67  xtension loading
38830 20 6f 6e 0a 2a 2a 20 61 6e 64 20 63 61 6c 6c 20   on.** and call 
38840 69 74 20 77 69 74 68 20 6f 6e 6f 66 66 3d 3d 30  it with onoff==0
38850 20 74 6f 20 74 75 72 6e 20 69 74 20 62 61 63 6b   to turn it back
38860 20 6f 66 66 20 61 67 61 69 6e 2e 20 7b 45 4e 44   off again. {END
38870 7d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  }.*/.int sqlite3
38880 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74  _enable_load_ext
38890 65 6e 73 69 6f 6e 28 73 71 6c 69 74 65 33 20 2a  ension(sqlite3 *
388a0 64 62 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a  db, int onoff);.
388b0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
388c0 20 4d 61 6b 65 20 41 72 72 61 6e 67 65 6d 65 6e   Make Arrangemen
388d0 74 73 20 54 6f 20 41 75 74 6f 6d 61 74 69 63 61  ts To Automatica
388e0 6c 6c 79 20 4c 6f 61 64 20 41 6e 20 45 78 74 65  lly Load An Exte
388f0 6e 73 69 6f 6e 20 7b 46 31 32 36 34 30 7d 0a 2a  nsion {F12640}.*
38900 2a 0a 2a 2a 20 7b 46 31 32 36 34 31 7d 20 54 68  *.** {F12641} Th
38910 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 72  is function.** r
38920 65 67 69 73 74 65 72 73 20 61 6e 20 65 78 74 65  egisters an exte
38930 6e 73 69 6f 6e 20 65 6e 74 72 79 20 70 6f 69 6e  nsion entry poin
38940 74 20 74 68 61 74 20 69 73 20 61 75 74 6f 6d 61  t that is automa
38950 74 69 63 61 6c 6c 79 20 69 6e 76 6f 6b 65 64 0a  tically invoked.
38960 2a 2a 20 77 68 65 6e 65 76 65 72 20 61 20 6e 65  ** whenever a ne
38970 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  w database conne
38980 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 20  ction is