/ Hex Artifact Content
Login

Artifact b8158aa606f0b39426d63132ae0530d91c021abb:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 20 0a 2a 2a 20 74 6f  e changes .** to
0390: 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e   experimental in
03a0: 74 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73  terfaces but res
03b0: 65 72 76 65 20 74 6f 20 6d 61 6b 65 20 6d 69 6e  erve to make min
03c0: 6f 72 20 63 68 61 6e 67 65 73 20 69 66 0a 2a 2a  or changes if.**
03d0: 20 65 78 70 65 72 69 65 6e 63 65 20 66 72 6f 6d   experience from
03e0: 20 75 73 65 20 22 69 6e 20 74 68 65 20 77 69 6c   use "in the wil
03f0: 64 22 20 73 75 67 67 65 73 74 20 73 75 63 68 20  d" suggest such 
0400: 63 68 61 6e 67 65 73 20 61 72 65 20 70 72 75 64  changes are prud
0410: 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f  ent..**.** The o
0420: 66 66 69 63 69 61 6c 20 43 2d 6c 61 6e 67 75 61  fficial C-langua
0430: 67 65 20 41 50 49 20 64 6f 63 75 6d 65 6e 74 61  ge API documenta
0440: 74 69 6f 6e 20 66 6f 72 20 53 51 4c 69 74 65 20  tion for SQLite 
0450: 69 73 20 64 65 72 69 76 65 64 0a 2a 2a 20 66 72  is derived.** fr
0460: 6f 6d 20 63 6f 6d 6d 65 6e 74 73 20 69 6e 20 74  om comments in t
0470: 68 69 73 20 66 69 6c 65 2e 20 20 54 68 69 73 20  his file.  This 
0480: 66 69 6c 65 20 69 73 20 74 68 65 20 61 75 74 68  file is the auth
0490: 6f 72 69 74 61 74 69 76 65 20 73 6f 75 72 63 65  oritative source
04a0: 0a 2a 2a 20 6f 6e 20 68 6f 77 20 53 51 4c 69 74  .** on how SQLit
04b0: 65 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  e interfaces are
04c0: 20 73 75 70 70 6f 73 65 20 74 6f 20 6f 70 65 72   suppose to oper
04d0: 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e  ate..**.** The n
04e0: 61 6d 65 20 6f 66 20 74 68 69 73 20 66 69 6c 65  ame of this file
04f0: 20 75 6e 64 65 72 20 63 6f 6e 66 69 67 75 72 61   under configura
0500: 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 20  tion management 
0510: 69 73 20 22 73 71 6c 69 74 65 2e 68 2e 69 6e 22  is "sqlite.h.in"
0520: 2e 0a 2a 2a 20 54 68 65 20 6d 61 6b 65 66 69 6c  ..** The makefil
0530: 65 20 6d 61 6b 65 73 20 73 6f 6d 65 20 6d 69 6e  e makes some min
0540: 6f 72 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  or changes to th
0550: 69 73 20 66 69 6c 65 20 28 73 75 63 68 20 61 73  is file (such as
0560: 20 69 6e 73 65 72 74 69 6e 67 0a 2a 2a 20 74 68   inserting.** th
0570: 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72  e version number
0580: 29 20 61 6e 64 20 63 68 61 6e 67 65 73 20 69 74  ) and changes it
0590: 73 20 6e 61 6d 65 20 74 6f 20 22 73 71 6c 69 74  s name to "sqlit
05a0: 65 33 2e 68 22 20 61 73 0a 2a 2a 20 70 61 72 74  e3.h" as.** part
05b0: 20 6f 66 20 74 68 65 20 62 75 69 6c 64 20 70 72   of the build pr
05c0: 6f 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 40 28 23  ocess..**.** @(#
05d0: 29 20 24 49 64 3a 20 73 71 6c 69 74 65 2e 68 2e  ) $Id: sqlite.h.
05e0: 69 6e 2c 76 20 31 2e 32 38 39 20 32 30 30 38 2f  in,v 1.289 2008/
05f0: 30 33 2f 30 33 20 31 38 3a 34 37 3a 32 38 20 64  03/03 18:47:28 d
0600: 72 68 20 45 78 70 20 24 0a 2a 2f 0a 23 69 66 6e  rh Exp $.*/.#ifn
0610: 64 65 66 20 5f 53 51 4c 49 54 45 33 5f 48 5f 0a  def _SQLITE3_H_.
0620: 23 64 65 66 69 6e 65 20 5f 53 51 4c 49 54 45 33  #define _SQLITE3
0630: 5f 48 5f 0a 23 69 6e 63 6c 75 64 65 20 3c 73 74  _H_.#include <st
0640: 64 61 72 67 2e 68 3e 20 20 20 20 20 2f 2a 20 4e  darg.h>     /* N
0650: 65 65 64 65 64 20 66 6f 72 20 74 68 65 20 64 65  eeded for the de
0660: 66 69 6e 69 74 69 6f 6e 20 6f 66 20 76 61 5f 6c  finition of va_l
0670: 69 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 4d 61  ist */../*.** Ma
0680: 6b 65 20 73 75 72 65 20 77 65 20 63 61 6e 20 63  ke sure we can c
0690: 61 6c 6c 20 74 68 69 73 20 73 74 75 66 66 20 66  all this stuff f
06a0: 72 6f 6d 20 43 2b 2b 2e 0a 2a 2f 0a 23 69 66 64  rom C++..*/.#ifd
06b0: 65 66 20 5f 5f 63 70 6c 75 73 70 6c 75 73 0a 65  ef __cplusplus.e
06c0: 78 74 65 72 6e 20 22 43 22 20 7b 0a 23 65 6e 64  xtern "C" {.#end
06d0: 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20 41 64 64 20 74  if.../*.** Add t
06e0: 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20 6f 76  he ability to ov
06f0: 65 72 72 69 64 65 20 27 65 78 74 65 72 6e 27 0a  erride 'extern'.
0700: 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54  */.#ifndef SQLIT
0710: 45 5f 45 58 54 45 52 4e 0a 23 20 64 65 66 69 6e  E_EXTERN.# defin
0720: 65 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20  e SQLITE_EXTERN 
0730: 65 78 74 65 72 6e 0a 23 65 6e 64 69 66 0a 0a 2f  extern.#endif../
0740: 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 74  *.** Make sure t
0750: 68 65 73 65 20 73 79 6d 62 6f 6c 73 20 77 68 65  hese symbols whe
0760: 72 65 20 6e 6f 74 20 64 65 66 69 6e 65 64 20 62  re not defined b
0770: 79 20 73 6f 6d 65 20 70 72 65 76 69 6f 75 73 20  y some previous 
0780: 68 65 61 64 65 72 0a 2a 2a 20 66 69 6c 65 2e 0a  header.** file..
0790: 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45  */.#ifdef SQLITE
07a0: 5f 56 45 52 53 49 4f 4e 0a 23 20 75 6e 64 65 66  _VERSION.# undef
07b0: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a   SQLITE_VERSION.
07c0: 23 65 6e 64 69 66 0a 23 69 66 64 65 66 20 53 51  #endif.#ifdef SQ
07d0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
07e0: 42 45 52 0a 23 20 75 6e 64 65 66 20 53 51 4c 49  BER.# undef SQLI
07f0: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45  TE_VERSION_NUMBE
0800: 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20  R.#endif../*.** 
0810: 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c  CAPI3REF: Compil
0820: 65 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20 56  e-Time Library V
0830: 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 20 7b  ersion Numbers {
0840: 46 31 30 30 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 68  F10010}.**.** Th
0850: 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  e SQLITE_VERSION
0860: 20 61 6e 64 20 53 51 4c 49 54 45 5f 56 45 52 53   and SQLITE_VERS
0870: 49 4f 4e 5f 4e 55 4d 42 45 52 20 23 64 65 66 69  ION_NUMBER #defi
0880: 6e 65 73 20 69 6e 0a 2a 2a 20 74 68 65 20 73 71  nes in.** the sq
0890: 6c 69 74 65 33 2e 68 20 66 69 6c 65 20 73 70 65  lite3.h file spe
08a0: 63 69 66 79 20 74 68 65 20 76 65 72 73 69 6f 6e  cify the version
08b0: 20 6f 66 20 53 51 4c 69 74 65 20 77 69 74 68 20   of SQLite with 
08c0: 77 68 69 63 68 0a 2a 2a 20 74 68 61 74 20 68 65  which.** that he
08d0: 61 64 65 72 20 66 69 6c 65 20 69 73 20 61 73 73  ader file is ass
08e0: 6f 63 69 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  ociated..**.** T
08f0: 68 65 20 22 76 65 72 73 69 6f 6e 22 20 6f 66 20  he "version" of 
0900: 53 51 4c 69 74 65 20 69 73 20 61 20 73 74 72 69  SQLite is a stri
0910: 6e 67 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22  ng of the form "
0920: 58 2e 59 2e 5a 22 2e 0a 2a 2a 20 54 68 65 20 70  X.Y.Z"..** The p
0930: 68 72 61 73 65 20 22 61 6c 70 68 61 22 20 6f 72  hrase "alpha" or
0940: 20 22 62 65 74 61 22 20 6d 69 67 68 74 20 62 65   "beta" might be
0950: 20 61 70 70 65 6e 64 65 64 20 61 66 74 65 72 20   appended after 
0960: 74 68 65 20 5a 2e 0a 2a 2a 20 54 68 65 20 58 20  the Z..** The X 
0970: 76 61 6c 75 65 20 69 73 20 6d 61 6a 6f 72 20 76  value is major v
0980: 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 61 6c  ersion number al
0990: 77 61 79 73 20 33 20 69 6e 20 53 51 4c 69 74 65  ways 3 in SQLite
09a0: 33 2e 0a 2a 2a 20 54 68 65 20 58 20 76 61 6c 75  3..** The X valu
09b0: 65 20 6f 6e 6c 79 20 63 68 61 6e 67 65 73 20 77  e only changes w
09c0: 68 65 6e 20 20 62 61 63 6b 77 61 72 64 73 20 63  hen  backwards c
09d0: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 69 73 0a  ompatibility is.
09e0: 2a 2a 20 62 72 6f 6b 65 6e 20 61 6e 64 20 77 65  ** broken and we
09f0: 20 69 6e 74 65 6e 64 20 74 6f 20 6e 65 76 65 72   intend to never
0a00: 20 62 72 65 61 6b 0a 2a 2a 20 62 61 63 6b 77 61   break.** backwa
0a10: 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
0a20: 79 2e 20 20 54 68 65 20 59 20 76 61 6c 75 65 20  y.  The Y value 
0a30: 69 73 20 74 68 65 20 6d 69 6e 6f 72 20 76 65 72  is the minor ver
0a40: 73 69 6f 6e 0a 2a 2a 20 6e 75 6d 62 65 72 20 61  sion.** number a
0a50: 6e 64 20 6f 6e 6c 79 20 63 68 61 6e 67 65 73 20  nd only changes 
0a60: 77 68 65 6e 0a 2a 2a 20 74 68 65 72 65 20 61 72  when.** there ar
0a70: 65 20 6d 61 6a 6f 72 20 66 65 61 74 75 72 65 20  e major feature 
0a80: 65 6e 68 61 6e 63 65 6d 65 6e 74 73 20 74 68 61  enhancements tha
0a90: 74 20 61 72 65 20 66 6f 72 77 61 72 64 73 20 63  t are forwards c
0aa0: 6f 6d 70 61 74 69 62 6c 65 0a 2a 2a 20 62 75 74  ompatible.** but
0ab0: 20 6e 6f 74 20 62 61 63 6b 77 61 72 64 73 20 63   not backwards c
0ac0: 6f 6d 70 61 74 69 62 6c 65 2e 20 20 54 68 65 20  ompatible.  The 
0ad0: 5a 20 76 61 6c 75 65 20 69 73 20 72 65 6c 65 61  Z value is relea
0ae0: 73 65 20 6e 75 6d 62 65 72 0a 2a 2a 20 61 6e 64  se number.** and
0af0: 20 69 73 20 69 6e 63 72 65 6d 65 6e 74 65 64 20   is incremented 
0b00: 77 69 74 68 0a 2a 2a 20 65 61 63 68 20 72 65 6c  with.** each rel
0b10: 65 61 73 65 20 62 75 74 20 72 65 73 65 74 73 20  ease but resets 
0b20: 62 61 63 6b 20 74 6f 20 30 20 77 68 65 6e 20 59  back to 0 when Y
0b30: 20 69 73 20 69 6e 63 72 65 6d 65 6e 74 65 64 2e   is incremented.
0b40: 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
0b50: 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72   [sqlite3_libver
0b60: 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  sion()] and [sql
0b70: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f  ite3_libversion_
0b80: 6e 75 6d 62 65 72 28 29 5d 2e 0a 2a 2a 0a 2a 2a  number()]..**.**
0b90: 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
0ba0: 2a 2a 20 7b 46 31 30 30 31 31 7d 20 54 68 65 20  ** {F10011} The 
0bb0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 23  SQLITE_VERSION #
0bc0: 64 65 66 69 6e 65 20 69 6e 20 74 68 65 20 73 71  define in the sq
0bd0: 6c 69 74 65 33 2e 68 20 68 65 61 64 65 72 20 66  lite3.h header f
0be0: 69 6c 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ile.**          
0bf0: 65 76 61 6c 75 61 74 65 73 20 74 6f 20 61 20 73  evaluates to a s
0c00: 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20 74 68  tring literal th
0c10: 61 74 20 69 73 20 74 68 65 20 53 51 4c 69 74 65  at is the SQLite
0c20: 20 76 65 72 73 69 6f 6e 0a 2a 2a 20 20 20 20 20   version.**     
0c30: 20 20 20 20 20 77 69 74 68 20 77 68 69 63 68 20       with which 
0c40: 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65 20  the header file 
0c50: 69 73 20 61 73 73 6f 63 69 61 74 65 64 2e 0a 2a  is associated..*
0c60: 2a 0a 2a 2a 20 7b 46 31 30 30 31 34 7d 20 54 68  *.** {F10014} Th
0c70: 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  e SQLITE_VERSION
0c80: 5f 4e 55 4d 42 45 52 20 23 64 65 66 69 6e 65 20  _NUMBER #define 
0c90: 72 65 73 6f 6c 76 65 73 20 74 6f 20 61 6e 20 69  resolves to an i
0ca0: 6e 74 65 67 65 72 0a 2a 2a 20 20 20 20 20 20 20  nteger.**       
0cb0: 20 20 20 77 69 74 68 20 74 68 65 20 76 61 6c 75     with the valu
0cc0: 65 20 20 28 58 2a 31 30 30 30 30 30 30 20 2b 20  e  (X*1000000 + 
0cd0: 59 2a 31 30 30 30 20 2b 20 5a 29 20 77 68 65 72  Y*1000 + Z) wher
0ce0: 65 20 58 2c 20 59 2c 20 61 6e 64 0a 2a 2a 20 20  e X, Y, and.**  
0cf0: 20 20 20 20 20 20 20 20 5a 20 61 72 65 20 74 68          Z are th
0d00: 65 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 2c  e major version,
0d10: 20 6d 69 6e 6f 72 20 76 65 72 73 69 6f 6e 2c 20   minor version, 
0d20: 61 6e 64 20 72 65 6c 65 61 73 65 20 6e 75 6d 62  and release numb
0d30: 65 72 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  er..*/.#define S
0d40: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 20 20  QLITE_VERSION   
0d50: 20 20 20 20 20 20 22 2d 2d 56 45 52 53 2d 2d 22        "--VERS--"
0d60: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
0d70: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 20  VERSION_NUMBER  
0d80: 2d 2d 56 45 52 53 49 4f 4e 2d 4e 55 4d 42 45 52  --VERSION-NUMBER
0d90: 2d 2d 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  --../*.** CAPI3R
0da0: 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62  EF: Run-Time Lib
0db0: 72 61 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d  rary Version Num
0dc0: 62 65 72 73 20 7b 46 31 30 30 32 30 7d 0a 2a 2a  bers {F10020}.**
0dd0: 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74   KEYWORDS: sqlit
0de0: 65 33 5f 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a  e3_version.**.**
0df0: 20 54 68 65 73 65 20 66 65 61 74 75 72 65 73 20   These features 
0e00: 70 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65  provide the same
0e10: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20   information as 
0e20: 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  the [SQLITE_VERS
0e30: 49 4f 4e 5d 0a 2a 2a 20 61 6e 64 20 5b 53 51 4c  ION].** and [SQL
0e40: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
0e50: 45 52 5d 20 23 64 65 66 69 6e 65 73 20 69 6e 20  ER] #defines in 
0e60: 74 68 65 20 68 65 61 64 65 72 2c 20 62 75 74 20  the header, but 
0e70: 61 72 65 20 61 73 73 6f 63 69 61 74 65 64 0a 2a  are associated.*
0e80: 2a 20 77 69 74 68 20 74 68 65 20 6c 69 62 72 61  * with the libra
0e90: 72 79 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68  ry instead of th
0ea0: 65 20 68 65 61 64 65 72 20 66 69 6c 65 2e 20 20  e header file.  
0eb0: 43 61 75 74 69 6f 75 73 20 70 72 6f 67 72 61 6d  Cautious program
0ec0: 6d 65 72 73 20 6d 69 67 68 74 0a 2a 2a 20 69 6e  mers might.** in
0ed0: 63 6c 75 64 65 20 61 20 63 68 65 63 6b 20 69 6e  clude a check in
0ee0: 20 74 68 65 69 72 20 61 70 70 6c 69 63 61 74 69   their applicati
0ef0: 6f 6e 20 74 6f 20 76 65 72 69 66 79 20 74 68 61  on to verify tha
0f00: 74 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6c 69  t .** sqlite3_li
0f10: 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28  bversion_number(
0f20: 29 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73  ) always returns
0f30: 20 74 68 65 20 76 61 6c 75 65 20 0a 2a 2a 20 5b   the value .** [
0f40: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
0f50: 55 4d 42 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  UMBER]..**.** Th
0f60: 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72  e sqlite3_libver
0f70: 73 69 6f 6e 28 29 20 66 75 6e 63 74 69 6f 6e 20  sion() function 
0f80: 72 65 74 75 72 6e 73 20 74 68 65 20 73 61 6d 65  returns the same
0f90: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20   information as 
0fa0: 69 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 71 6c  is.** in the sql
0fb0: 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73  ite3_version[] s
0fc0: 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 2e 20  tring constant. 
0fd0: 20 54 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73   The function is
0fe0: 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f 72   provided.** for
0ff0: 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69 6e   use in DLLs sin
1000: 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73 75  ce DLL users usu
1010: 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76 65  ally do not have
1020: 20 64 69 72 65 63 74 20 61 63 63 65 73 73 20 74   direct access t
1030: 6f 20 73 74 72 69 6e 67 0a 2a 2a 20 63 6f 6e 73  o string.** cons
1040: 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68 65  tants within the
1050: 20 44 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41   DLL..**.** INVA
1060: 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  RIANTS:.**.** {F
1070: 31 30 30 32 31 7d 20 54 68 65 20 5b 73 71 6c 69  10021} The [sqli
1080: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e  te3_libversion_n
1090: 75 6d 62 65 72 28 29 5d 20 69 6e 74 65 72 66 61  umber()] interfa
10a0: 63 65 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e  ce returns an in
10b0: 74 65 67 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  teger.**        
10c0: 20 20 65 71 75 61 6c 20 74 6f 20 5b 53 51 4c 49    equal to [SQLI
10d0: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45  TE_VERSION_NUMBE
10e0: 52 5d 2e 20 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 30  R]. .**.** {F100
10f0: 32 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  22} The [sqlite3
1100: 5f 76 65 72 73 69 6f 6e 5d 20 73 74 72 69 6e 67  _version] string
1110: 20 63 6f 6e 73 74 61 6e 74 20 63 6f 6e 74 61 69   constant contai
1120: 6e 73 20 74 68 65 20 74 65 78 74 20 6f 66 20 74  ns the text of t
1130: 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
1140: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20  SQLITE_VERSION] 
1150: 73 74 72 69 6e 67 2e 20 0a 2a 2a 0a 2a 2a 20 7b  string. .**.** {
1160: 46 31 30 30 32 33 7d 20 54 68 65 20 5b 73 71 6c  F10023} The [sql
1170: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
1180: 29 5d 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  )] function retu
1190: 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  rns.**          
11a0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
11b0: 20 5b 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f   [sqlite3_versio
11c0: 6e 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61  n] string consta
11d0: 6e 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58  nt..*/.SQLITE_EX
11e0: 54 45 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20  TERN const char 
11f0: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b  sqlite3_version[
1200: 5d 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  ];.const char *s
1210: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1220: 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c  n(void);.int sql
1230: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f  ite3_libversion_
1240: 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a 0a 2f  number(void);../
1250: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
1260: 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54 68  est To See If Th
1270: 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68 72  e Library Is Thr
1280: 65 61 64 73 61 66 65 20 7b 46 31 30 31 30 30 7d  eadsafe {F10100}
1290: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 61  .**.** SQLite ca
12a0: 6e 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 77 69  n be compiled wi
12b0: 74 68 20 6f 72 20 77 69 74 68 6f 75 74 20 6d 75  th or without mu
12c0: 74 65 78 65 73 2e 20 20 57 68 65 6e 0a 2a 2a 20  texes.  When.** 
12d0: 74 68 65 20 53 51 4c 49 54 45 5f 54 48 52 45 41  the SQLITE_THREA
12e0: 44 53 41 46 45 20 43 20 70 72 65 70 72 6f 63 65  DSAFE C preproce
12f0: 73 73 6f 72 20 6d 61 63 72 6f 20 69 73 20 74 72  ssor macro is tr
1300: 75 65 2c 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61  ue, mutexes.** a
1310: 72 65 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 53  re enabled and S
1320: 51 4c 69 74 65 20 69 73 20 74 68 72 65 61 64 73  QLite is threads
1330: 61 66 65 2e 20 20 57 68 65 6e 20 74 68 61 74 20  afe.  When that 
1340: 6d 61 63 72 6f 20 6f 73 20 66 61 6c 73 65 2c 0a  macro os false,.
1350: 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73 20 61  ** the mutexes a
1360: 72 65 20 6f 6d 69 74 74 65 64 2e 20 20 57 69 74  re omitted.  Wit
1370: 68 6f 75 74 20 74 68 65 20 6d 75 74 65 78 65 73  hout the mutexes
1380: 2c 20 69 74 20 69 73 20 6e 6f 74 20 73 61 66 65  , it is not safe
1390: 0a 2a 2a 20 74 6f 20 75 73 65 20 53 51 4c 69 74  .** to use SQLit
13a0: 65 20 66 72 6f 6d 20 6d 6f 72 65 20 74 68 61 6e  e from more than
13b0: 20 6f 6e 65 20 74 68 72 65 61 64 2e 0a 2a 2a 0a   one thread..**.
13c0: 2a 2a 20 54 68 65 72 65 20 69 73 20 61 20 6d 65  ** There is a me
13d0: 61 73 75 72 61 62 6c 65 20 70 65 72 66 6f 72 6d  asurable perform
13e0: 61 6e 63 65 20 70 65 6e 61 6c 74 79 20 66 6f 72  ance penalty for
13f0: 20 65 6e 61 62 6c 69 6e 67 20 6d 75 74 65 78 65   enabling mutexe
1400: 73 2e 0a 2a 2a 20 53 6f 20 69 66 20 73 70 65 65  s..** So if spee
1410: 64 20 69 73 20 6f 66 20 75 74 6d 6f 73 74 20 69  d is of utmost i
1420: 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74 20 6d 61  mportance, it ma
1430: 6b 65 73 20 73 65 6e 73 65 20 74 6f 20 64 69 73  kes sense to dis
1440: 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65  able.** the mute
1450: 78 65 73 2e 20 20 42 75 74 20 66 6f 72 20 6d 61  xes.  But for ma
1460: 78 69 6d 75 6d 20 73 61 66 65 74 79 2c 20 6d 75  ximum safety, mu
1470: 74 65 78 65 73 20 73 68 6f 75 6c 64 20 62 65 20  texes should be 
1480: 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 54 68 65 20  enabled..** The 
1490: 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72  default behavior
14a0: 20 69 73 20 66 6f 72 20 6d 75 74 65 78 65 73 20   is for mutexes 
14b0: 74 6f 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a  to be enabled..*
14c0: 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66  *.** This interf
14d0: 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ace can be used 
14e0: 62 79 20 61 20 70 72 6f 67 72 61 6d 20 74 6f 20  by a program to 
14f0: 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 20 74  make sure that t
1500: 68 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66  he.** version of
1510: 20 53 51 4c 69 74 65 20 74 68 61 74 20 69 74 20   SQLite that it 
1520: 69 73 20 6c 69 6e 6b 69 6e 67 20 61 67 61 69 6e  is linking again
1530: 73 74 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20  st was compiled 
1540: 77 69 74 68 0a 2a 2a 20 74 68 65 20 64 65 73 69  with.** the desi
1550: 72 65 64 20 73 65 74 74 69 6e 67 20 6f 66 20 74  red setting of t
1560: 68 65 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44  he SQLITE_THREAD
1570: 53 41 46 45 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a  SAFE macro..**.*
1580: 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
1590: 0a 2a 2a 20 7b 46 31 30 31 30 31 7d 20 54 68 65  .** {F10101} The
15a0: 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64   [sqlite3_thread
15b0: 73 61 66 65 28 29 5d 20 66 75 6e 63 74 69 6f 6e  safe()] function
15c0: 20 72 65 74 75 72 6e 73 20 6e 6f 6e 7a 65 72 6f   returns nonzero
15d0: 20 69 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   if.**          
15e0: 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70 69  SQLite was compi
15f0: 6c 65 64 20 77 69 74 68 20 69 74 73 20 6d 75 74  led with its mut
1600: 65 78 65 73 20 65 6e 61 62 6c 65 64 20 6f 72 20  exes enabled or 
1610: 7a 65 72 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20  zero.**         
1620: 20 69 66 20 53 51 4c 69 74 65 20 77 61 73 20 63   if SQLite was c
1630: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6d 75 74  ompiled with mut
1640: 65 78 65 73 20 64 69 73 61 62 6c 65 64 2e 0a 2a  exes disabled..*
1650: 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 68  /.int sqlite3_th
1660: 72 65 61 64 73 61 66 65 28 76 6f 69 64 29 3b 0a  readsafe(void);.
1670: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1680: 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
1690: 74 69 6f 6e 20 48 61 6e 64 6c 65 20 7b 46 31 32  tion Handle {F12
16a0: 30 30 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  000}.** KEYWORDS
16b0: 3a 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  : {database conn
16c0: 65 63 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 45 61  ection}.**.** Ea
16d0: 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20 64  ch open SQLite d
16e0: 61 74 61 62 61 73 65 20 69 73 20 72 65 70 72 65  atabase is repre
16f0: 73 65 6e 74 65 64 20 62 79 20 70 6f 69 6e 74 65  sented by pointe
1700: 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65  r to an instance
1710: 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 70 61 71 75   of the.** opaqu
1720: 65 20 73 74 72 75 63 74 75 72 65 20 6e 61 6d 65  e structure name
1730: 64 20 22 73 71 6c 69 74 65 33 22 2e 20 20 49 74  d "sqlite3".  It
1740: 20 69 73 20 75 73 65 66 75 6c 20 74 6f 20 74 68   is useful to th
1750: 69 6e 6b 20 6f 66 20 61 6e 20 73 71 6c 69 74 65  ink of an sqlite
1760: 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 61 73 20  3.** pointer as 
1770: 61 6e 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20  an object.  The 
1780: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
1790: 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  , [sqlite3_open1
17a0: 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  6()], and.** [sq
17b0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
17c0: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
17d0: 69 74 73 20 63 6f 6e 73 74 72 75 63 74 6f 72 73  its constructors
17e0: 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
17f0: 5f 63 6c 6f 73 65 28 29 5d 20 69 73 20 69 74 73  _close()] is its
1800: 20 64 65 73 74 72 75 63 74 6f 72 2e 20 20 54 68   destructor.  Th
1810: 65 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68  ere are many oth
1820: 65 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  er interfaces.**
1830: 20 28 73 75 63 68 20 61 73 20 5b 73 71 6c 69 74   (such as [sqlit
1840: 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1850: 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  , [sqlite3_creat
1860: 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61  e_function()], a
1870: 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nd.** [sqlite3_b
1880: 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74  usy_timeout()] t
1890: 6f 20 6e 61 6d 65 20 62 75 74 20 74 68 72 65 65  o name but three
18a0: 29 20 74 68 61 74 20 61 72 65 20 6d 65 74 68 6f  ) that are metho
18b0: 64 73 20 6f 6e 20 74 68 69 73 0a 2a 2a 20 6f 62  ds on this.** ob
18c0: 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  ject..*/.typedef
18d0: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 20   struct sqlite3 
18e0: 73 71 6c 69 74 65 33 3b 0a 0a 0a 2f 2a 0a 2a 2a  sqlite3;.../*.**
18f0: 20 43 41 50 49 33 52 45 46 3a 20 36 34 2d 42 69   CAPI3REF: 64-Bi
1900: 74 20 49 6e 74 65 67 65 72 20 54 79 70 65 73 20  t Integer Types 
1910: 7b 46 31 30 32 30 30 7d 0a 2a 2a 20 4b 45 59 57  {F10200}.** KEYW
1920: 4f 52 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74  ORDS: sqlite_int
1930: 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  64 sqlite_uint64
1940: 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74  .**.** Because t
1950: 68 65 72 65 20 69 73 20 6e 6f 20 63 72 6f 73 73  here is no cross
1960: 2d 70 6c 61 74 66 6f 72 6d 20 77 61 79 20 74 6f  -platform way to
1970: 20 73 70 65 63 69 66 79 20 36 34 2d 62 69 74 20   specify 64-bit 
1980: 69 6e 74 65 67 65 72 20 74 79 70 65 73 0a 2a 2a  integer types.**
1990: 20 53 51 4c 69 74 65 20 69 6e 63 6c 75 64 65 73   SQLite includes
19a0: 20 74 79 70 65 64 65 66 73 20 66 6f 72 20 36 34   typedefs for 64
19b0: 2d 62 69 74 20 73 69 67 6e 65 64 20 61 6e 64 20  -bit signed and 
19c0: 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  unsigned integer
19d0: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  s..**.** The sql
19e0: 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73  ite3_int64 and s
19f0: 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 61 72  qlite3_uint64 ar
1a00: 65 20 74 68 65 20 70 72 65 66 65 72 72 65 64 20  e the preferred 
1a10: 74 79 70 65 0a 2a 2a 20 64 65 66 69 6e 69 74 69  type.** definiti
1a20: 6f 6e 73 2e 20 20 54 68 65 20 73 71 6c 69 74 65  ons.  The sqlite
1a30: 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74  _int64 and sqlit
1a40: 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20 61  e_uint64 types a
1a50: 72 65 0a 2a 2a 20 73 75 70 70 6f 72 74 65 64 20  re.** supported 
1a60: 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f  for backwards co
1a70: 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79  mpatibility only
1a80: 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
1a90: 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 32 30  TS:.**.** {F1020
1aa0: 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 5f 69  1} The [sqlite_i
1ab0: 6e 74 36 34 5d 20 61 6e 64 20 5b 73 71 6c 69 74  nt64] and [sqlit
1ac0: 65 33 5f 69 6e 74 36 34 5d 20 74 79 70 65 73 20  e3_int64] types 
1ad0: 73 70 65 63 69 66 79 20 61 0a 2a 2a 20 20 20 20  specify a.**    
1ae0: 20 20 20 20 20 20 36 34 2d 62 69 74 20 73 69 67        64-bit sig
1af0: 6e 65 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a  ned integer..**.
1b00: 2a 2a 20 7b 46 31 30 32 30 32 7d 20 54 68 65 20  ** {F10202} The 
1b10: 5b 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 5d 20  [sqlite_uint64] 
1b20: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 75 69 6e  and [sqlite3_uin
1b30: 74 36 34 5d 20 74 79 70 65 73 20 73 70 65 63 69  t64] types speci
1b40: 66 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  fy.**          a
1b50: 20 36 34 2d 62 69 74 20 75 6e 73 69 67 6e 65 64   64-bit unsigned
1b60: 20 69 6e 74 65 67 65 72 2e 0a 2a 2f 0a 23 69 66   integer..*/.#if
1b70: 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34  def SQLITE_INT64
1b80: 5f 54 59 50 45 0a 20 20 74 79 70 65 64 65 66 20  _TYPE.  typedef 
1b90: 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50  SQLITE_INT64_TYP
1ba0: 45 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a  E sqlite_int64;.
1bb0: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e    typedef unsign
1bc0: 65 64 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f  ed SQLITE_INT64_
1bd0: 54 59 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74  TYPE sqlite_uint
1be0: 36 34 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e 65  64;.#elif define
1bf0: 64 28 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64  d(_MSC_VER) || d
1c00: 65 66 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44  efined(__BORLAND
1c10: 43 5f 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f  C__).  typedef _
1c20: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e  _int64 sqlite_in
1c30: 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75  t64;.  typedef u
1c40: 6e 73 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20  nsigned __int64 
1c50: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23  sqlite_uint64;.#
1c60: 65 6c 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c  else.  typedef l
1c70: 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c  ong long int sql
1c80: 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70  ite_int64;.  typ
1c90: 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f  edef unsigned lo
1ca0: 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69  ng long int sqli
1cb0: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69  te_uint64;.#endi
1cc0: 66 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65  f.typedef sqlite
1cd0: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69  _int64 sqlite3_i
1ce0: 6e 74 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71  nt64;.typedef sq
1cf0: 6c 69 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69  lite_uint64 sqli
1d00: 74 65 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a  te3_uint64;../*.
1d10: 2a 2a 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20  ** If compiling 
1d20: 66 6f 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20  for a processor 
1d30: 74 68 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74  that lacks float
1d40: 69 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72  ing point suppor
1d50: 74 2c 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65  t,.** substitute
1d60: 20 69 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f   integer for flo
1d70: 61 74 69 6e 67 2d 70 6f 69 6e 74 0a 2a 2f 0a 23  ating-point.*/.#
1d80: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49  ifdef SQLITE_OMI
1d90: 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54  T_FLOATING_POINT
1da0: 0a 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65  .# define double
1db0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23   sqlite3_int64.#
1dc0: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  endif../*.** CAP
1dd0: 49 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41  I3REF: Closing A
1de0: 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
1df0: 74 69 6f 6e 20 7b 46 31 32 30 31 30 7d 0a 2a 2a  tion {F12010}.**
1e00: 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
1e10: 20 69 73 20 74 68 65 20 64 65 73 74 72 75 63 74   is the destruct
1e20: 6f 72 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69  or for the [sqli
1e30: 74 65 33 5d 20 6f 62 6a 65 63 74 2e 20 20 0a 2a  te3] object.  .*
1e40: 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e  *.** Application
1e50: 73 20 73 68 6f 75 6c 64 20 5b 73 71 6c 69 74 65  s should [sqlite
1e60: 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e  3_finalize | fin
1e70: 61 6c 69 7a 65 5d 20 61 6c 6c 0a 2a 2a 20 5b 70  alize] all.** [p
1e80: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1e90: 74 73 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  ts] and.** [sqli
1ea0: 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c  te3_blob_close |
1eb0: 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 73 71 6c   close] all [sql
1ec0: 69 74 65 33 5f 62 6c 6f 62 20 7c 20 42 4c 4f 42  ite3_blob | BLOB
1ed0: 73 5d 20 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65  s] .** associate
1ee0: 64 20 77 69 74 68 20 74 68 65 20 5b 73 71 6c 69  d with the [sqli
1ef0: 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 72 69 6f  te3] object prio
1f00: 72 0a 2a 2a 20 74 6f 20 61 74 74 65 6d 70 74 69  r.** to attempti
1f10: 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65 20  ng to close the 
1f20: 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
1f30: 2e 0a 2a 2a 0a 2a 2a 20 3c 74 6f 64 6f 3e 57 68  ..**.** <todo>Wh
1f40: 61 74 20 68 61 70 70 65 6e 73 20 74 6f 20 70 65  at happens to pe
1f50: 6e 64 69 6e 67 20 74 72 61 6e 73 61 63 74 69 6f  nding transactio
1f60: 6e 73 3f 20 20 41 72 65 20 74 68 65 79 0a 2a 2a  ns?  Are they.**
1f70: 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2c 20 6f 72   rolled back, or
1f80: 20 61 62 61 6e 64 6f 6e 65 64 3f 3c 2f 74 6f 64   abandoned?</tod
1f90: 6f 3e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  o>.**.** INVARIA
1fa0: 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 30  NTS:.**.** {F120
1fb0: 31 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  11} The [sqlite3
1fc0: 5f 63 6c 6f 73 65 28 29 5d 20 69 6e 74 65 72 66  _close()] interf
1fd0: 61 63 65 20 64 65 73 74 72 6f 79 73 20 61 6e 20  ace destroys an 
1fe0: 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
1ff0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c 6c  .**          all
2000: 6f 63 61 74 65 64 20 62 79 20 61 20 70 72 69 6f  ocated by a prio
2010: 72 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  r call to [sqlit
2020: 65 33 5f 6f 70 65 6e 28 29 5d 2c 0a 2a 2a 20 20  e3_open()],.**  
2030: 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
2040: 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72 20 5b  _open16()], or [
2050: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
2060: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 30 31  )]..**.** {F1201
2070: 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  2} The [sqlite3_
2080: 63 6c 6f 73 65 28 29 5d 20 66 75 6e 63 74 69 6f  close()] functio
2090: 6e 20 72 65 6c 65 61 73 65 73 20 61 6c 6c 20 6d  n releases all m
20a0: 65 6d 6f 72 79 20 75 73 65 64 20 62 79 20 74 68  emory used by th
20b0: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f  e.**          co
20c0: 6e 6e 65 63 74 69 6f 6e 20 61 6e 64 20 63 6c 6f  nnection and clo
20d0: 73 65 73 20 61 6c 6c 20 6f 70 65 6e 20 66 69 6c  ses all open fil
20e0: 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 30 31  es..**.** {F1201
20f0: 33 7d 20 49 66 20 74 68 65 20 64 61 74 61 62 61  3} If the databa
2100: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6f  se connection co
2110: 6e 74 61 69 6e 73 0a 2a 2a 20 20 20 20 20 20 20  ntains.**       
2120: 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61     [prepared sta
2130: 74 65 6d 65 6e 74 73 5d 20 74 68 61 74 20 68 61  tements] that ha
2140: 76 65 20 6e 6f 74 20 62 65 65 6e 0a 2a 2a 20 20  ve not been.**  
2150: 20 20 20 20 20 20 20 20 66 69 6e 61 6c 69 7a 65          finalize
2160: 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 69  d by [sqlite3_fi
2170: 6e 61 6c 69 7a 65 28 29 5d 2c 20 74 68 65 6e 20  nalize()], then 
2180: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29  [sqlite3_close()
2190: 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  ].**          re
21a0: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55  turns [SQLITE_BU
21b0: 53 59 5d 20 61 6e 64 20 6c 65 61 76 65 73 20 74  SY] and leaves t
21c0: 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70  he connection op
21d0: 65 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 30 31  en..**.** {F1201
21e0: 34 7d 20 47 69 76 69 6e 67 20 73 71 6c 69 74 65  4} Giving sqlite
21f0: 33 5f 63 6c 6f 73 65 28 29 20 61 20 4e 55 4c 4c  3_close() a NULL
2200: 20 70 6f 69 6e 74 65 72 20 69 73 20 61 20 68 61   pointer is a ha
2210: 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a  rmless no-op..**
2220: 0a 2a 2a 20 4c 49 4d 49 54 41 54 49 4f 4e 53 3a  .** LIMITATIONS:
2230: 0a 2a 2a 0a 2a 2a 20 7b 55 31 32 30 31 35 7d 20  .**.** {U12015} 
2240: 54 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  The parameter to
2250: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
2260: 29 5d 20 6d 75 73 74 20 62 65 20 61 6e 20 5b 73  )] must be an [s
2270: 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 0a 2a  qlite3] object.*
2280: 2a 20 20 20 20 20 20 20 20 20 20 70 6f 69 6e 74  *          point
2290: 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62  er previously ob
22a0: 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
22b0: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 6f 72 20  ite3_open()] or 
22c0: 74 68 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  the .**         
22d0: 20 65 71 75 69 76 61 6c 65 6e 74 2c 20 6f 72 20   equivalent, or 
22e0: 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 55 31 32  NULL..**.** {U12
22f0: 30 31 36 7d 20 54 68 65 20 70 61 72 61 6d 65 74  016} The paramet
2300: 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  er to [sqlite3_c
2310: 6c 6f 73 65 28 29 5d 20 6d 75 73 74 20 6e 6f 74  lose()] must not
2320: 20 68 61 76 65 20 62 65 65 6e 20 70 72 65 76 69   have been previ
2330: 6f 75 73 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20  ously.**        
2340: 20 20 63 6c 6f 73 65 64 2e 0a 2a 2f 0a 69 6e 74    closed..*/.int
2350: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 73   sqlite3_close(s
2360: 71 6c 69 74 65 33 20 2a 29 3b 0a 0a 2f 2a 0a 2a  qlite3 *);../*.*
2370: 2a 20 54 68 65 20 74 79 70 65 20 66 6f 72 20 61  * The type for a
2380: 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
2390: 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 6c  on..** This is l
23a0: 65 67 61 63 79 20 61 6e 64 20 64 65 70 72 65 63  egacy and deprec
23b0: 61 74 65 64 2e 20 20 49 74 20 69 73 20 69 6e 63  ated.  It is inc
23c0: 6c 75 64 65 64 20 66 6f 72 20 68 69 73 74 6f 72  luded for histor
23d0: 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69 62  ical.** compatib
23e0: 69 6c 69 74 79 20 61 6e 64 20 69 73 20 6e 6f 74  ility and is not
23f0: 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a 2f 0a   documented..*/.
2400: 74 79 70 65 64 65 66 20 69 6e 74 20 28 2a 73 71  typedef int (*sq
2410: 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63 6b 29 28  lite3_callback)(
2420: 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a  void*,int,char**
2430: 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a 2a  , char**);../*.*
2440: 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 6e 65 2d  * CAPI3REF: One-
2450: 53 74 65 70 20 51 75 65 72 79 20 45 78 65 63 75  Step Query Execu
2460: 74 69 6f 6e 20 49 6e 74 65 72 66 61 63 65 20 7b  tion Interface {
2470: 46 31 32 31 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68  F12100}.**.** Th
2480: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
2490: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 61 20   interface is a 
24a0: 63 6f 6e 76 65 6e 69 65 6e 74 20 77 61 79 20 6f  convenient way o
24b0: 66 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 6f 6e 65  f running.** one
24c0: 20 6f 72 20 6d 6f 72 65 20 53 51 4c 20 73 74 61   or more SQL sta
24d0: 74 65 6d 65 6e 74 73 20 77 69 74 68 6f 75 74 20  tements without 
24e0: 61 20 6c 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e  a lot of C code.
24f0: 20 20 54 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61    The.** SQL sta
2500: 74 65 6d 65 6e 74 73 20 61 72 65 20 70 61 73 73  tements are pass
2510: 65 64 20 69 6e 20 61 73 20 74 68 65 20 73 65 63  ed in as the sec
2520: 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
2530: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
2540: 28 29 2e 20 20 54 68 65 20 73 74 61 74 65 6d 65  ().  The stateme
2550: 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65  nts are evaluate
2560: 64 20 6f 6e 65 20 62 79 20 6f 6e 65 0a 2a 2a 20  d one by one.** 
2570: 75 6e 74 69 6c 20 65 69 74 68 65 72 20 61 6e 20  until either an 
2580: 65 72 72 6f 72 20 6f 72 20 61 6e 20 69 6e 74 65  error or an inte
2590: 72 72 75 70 74 20 69 73 20 65 6e 63 6f 75 6e 74  rrupt is encount
25a0: 65 72 65 64 20 6f 72 0a 2a 2a 20 75 6e 74 69 6c  ered or.** until
25b0: 20 74 68 65 79 20 61 72 65 20 61 6c 6c 20 64 6f   they are all do
25c0: 6e 65 2e 20 20 54 68 65 20 33 72 64 20 70 61 72  ne.  The 3rd par
25d0: 61 6d 65 74 65 72 20 69 73 20 61 6e 20 6f 70 74  ameter is an opt
25e0: 69 6f 6e 61 6c 0a 2a 2a 20 63 61 6c 6c 62 61 63  ional.** callbac
25f0: 6b 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65  k that is invoke
2600: 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20  d once for each 
2610: 72 6f 77 20 6f 66 20 61 6e 79 20 71 75 65 72 79  row of any query
2620: 20 72 65 73 75 6c 74 73 0a 2a 2a 20 70 72 6f 64   results.** prod
2630: 75 63 65 64 20 62 79 20 74 68 65 20 53 51 4c 20  uced by the SQL 
2640: 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 54 68 65  statements.  The
2650: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
2660: 65 6c 6c 73 20 77 68 65 72 65 0a 2a 2a 20 74 6f  ells where.** to
2670: 20 77 72 69 74 65 20 61 6e 79 20 65 72 72 6f 72   write any error
2680: 20 6d 65 73 73 61 67 65 73 2e 0a 2a 2a 0a 2a 2a   messages..**.**
2690: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65   The sqlite3_exe
26a0: 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  c() interface is
26b0: 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 69 6e 20   implemented in 
26c0: 74 65 72 6d 73 20 6f 66 0a 2a 2a 20 5b 73 71 6c  terms of.** [sql
26d0: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
26e0: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  )], [sqlite3_ste
26f0: 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  p()], and [sqlit
2700: 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a  e3_finalize()]..
2710: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65  ** The sqlite3_e
2720: 78 65 63 28 29 20 72 6f 75 74 69 6e 65 20 64 6f  xec() routine do
2730: 65 73 20 6e 6f 74 68 69 6e 67 20 74 68 61 74 20  es nothing that 
2740: 63 61 6e 6e 6f 74 20 62 65 20 64 6f 6e 65 0a 2a  cannot be done.*
2750: 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72  * by [sqlite3_pr
2760: 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71  epare_v2()], [sq
2770: 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 61  lite3_step()], a
2780: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  nd [sqlite3_fina
2790: 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  lize()]..** The 
27a0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
27b0: 73 20 6a 75 73 74 20 61 20 63 6f 6e 76 65 6e 69  s just a conveni
27c0: 65 6e 74 20 77 72 61 70 70 65 72 2e 0a 2a 2a 0a  ent wrapper..**.
27d0: 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
27e0: 2a 20 0a 2a 2a 20 7b 46 31 32 31 30 31 7d 20 54  * .** {F12101} T
27f0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  he [sqlite3_exec
2800: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 65 76  ()] interface ev
2810: 61 6c 75 61 74 65 73 20 7a 65 72 6f 20 6f 72 20  aluates zero or 
2820: 6d 6f 72 65 20 55 54 46 2d 38 0a 2a 2a 20 20 20  more UTF-8.**   
2830: 20 20 20 20 20 20 20 65 6e 63 6f 64 65 64 2c 20         encoded, 
2840: 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61  semicolon-separa
2850: 74 65 64 2c 20 53 51 4c 20 73 74 61 74 65 6d 65  ted, SQL stateme
2860: 6e 74 73 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20  nts in the.**   
2870: 20 20 20 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d         zero-term
2880: 69 6e 61 74 65 64 20 73 74 72 69 6e 67 20 6f 66  inated string of
2890: 20 69 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74   its 2nd paramet
28a0: 65 72 20 77 69 74 68 69 6e 20 74 68 65 0a 2a 2a  er within the.**
28b0: 20 20 20 20 20 20 20 20 20 20 63 6f 6e 74 65 78            contex
28c0: 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  t of the [sqlite
28d0: 33 5d 20 6f 62 6a 65 63 74 20 67 69 76 65 6e 20  3] object given 
28e0: 69 6e 20 74 68 65 20 31 73 74 20 70 61 72 61 6d  in the 1st param
28f0: 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  eter..**.** {F12
2900: 31 30 34 7d 20 54 68 65 20 72 65 74 75 72 6e 20  104} The return 
2910: 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65  value of [sqlite
2920: 33 5f 65 78 65 63 28 29 5d 20 69 73 20 53 51 4c  3_exec()] is SQL
2930: 49 54 45 5f 4f 4b 20 69 66 20 61 6c 6c 0a 2a 2a  ITE_OK if all.**
2940: 20 20 20 20 20 20 20 20 20 20 53 51 4c 20 73 74            SQL st
2950: 61 74 65 6d 65 6e 74 73 20 72 75 6e 20 73 75 63  atements run suc
2960: 63 65 73 73 66 75 6c 6c 79 2e 0a 2a 2a 0a 2a 2a  cessfully..**.**
2970: 20 7b 46 31 32 31 30 35 7d 20 54 68 65 20 72 65   {F12105} The re
2980: 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 5b 73  turn value of [s
2990: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 69  qlite3_exec()] i
29a0: 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65  s an appropriate
29b0: 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 6f   .**          no
29c0: 6e 2d 7a 65 72 6f 20 65 72 72 6f 72 20 63 6f 64  n-zero error cod
29d0: 65 20 69 66 20 61 6e 79 20 53 51 4c 20 73 74 61  e if any SQL sta
29e0: 74 65 6d 65 6e 74 20 66 61 69 6c 73 2e 0a 2a 2a  tement fails..**
29f0: 0a 2a 2a 20 7b 46 31 32 31 30 37 7d 20 49 66 20  .** {F12107} If 
2a00: 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74  one or more of t
2a10: 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
2a20: 73 20 68 61 6e 64 65 64 20 74 6f 20 5b 73 71 6c  s handed to [sql
2a30: 69 74 65 33 5f 65 78 65 63 28 29 5d 0a 2a 2a 20  ite3_exec()].** 
2a40: 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20           return 
2a50: 72 65 73 75 6c 74 73 20 61 6e 64 20 74 68 65 20  results and the 
2a60: 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  3rd parameter is
2a70: 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 0a   not NULL, then.
2a80: 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
2a90: 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
2aa0: 6e 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  n specified by t
2ab0: 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
2ac0: 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   is.**          
2ad0: 69 6e 76 6f 6b 65 64 20 6f 6e 63 65 20 66 6f 72  invoked once for
2ae0: 20 65 61 63 68 20 72 6f 77 20 6f 66 20 72 65 73   each row of res
2af0: 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31  ult..**.** {F121
2b00: 31 30 7d 20 49 66 20 74 68 65 20 63 61 6c 6c 62  10} If the callb
2b10: 61 63 6b 20 72 65 74 75 72 6e 73 20 61 20 6e 6f  ack returns a no
2b20: 6e 2d 7a 65 72 6f 20 76 61 6c 75 65 20 74 68 65  n-zero value the
2b30: 6e 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  n [sqlite3_exec(
2b40: 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77  )].**          w
2b50: 69 6c 6c 20 61 62 6f 72 74 65 64 20 74 68 65 20  ill aborted the 
2b60: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 74  SQL statement it
2b70: 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 65 76   is currently ev
2b80: 61 6c 75 61 74 69 6e 67 2c 0a 2a 2a 20 20 20 20  aluating,.**    
2b90: 20 20 20 20 20 20 73 6b 69 70 20 61 6c 6c 20 73        skip all s
2ba0: 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20 73 74  ubsequent SQL st
2bb0: 61 74 65 6d 65 6e 74 73 2c 20 61 6e 64 20 72 65  atements, and re
2bc0: 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 41 42 4f  turn [SQLITE_ABO
2bd0: 52 54 5d 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20  RT]..**         
2be0: 20 3c 74 6f 64 6f 3e 57 68 61 74 20 68 61 70 70   <todo>What happ
2bf0: 65 6e 73 20 74 6f 20 2a 65 72 72 6d 73 67 20 68  ens to *errmsg h
2c00: 65 72 65 3f 20 20 44 6f 65 73 20 74 68 65 20 72  ere?  Does the r
2c10: 65 73 75 6c 74 20 63 6f 64 65 20 66 6f 72 0a 2a  esult code for.*
2c20: 2a 20 20 20 20 20 20 20 20 20 20 73 71 6c 69 74  *          sqlit
2c30: 65 33 5f 65 72 72 63 6f 64 65 28 29 20 67 65 74  e3_errcode() get
2c40: 20 73 65 74 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a   set?</todo>.**.
2c50: 2a 2a 20 7b 46 31 32 31 31 33 7d 20 54 68 65 20  ** {F12113} The 
2c60: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
2c70: 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 70 61   routine will pa
2c80: 73 73 20 69 74 73 20 34 74 68 20 70 61 72 61 6d  ss its 4th param
2c90: 65 74 65 72 20 74 68 72 6f 75 67 68 0a 2a 2a 20  eter through.** 
2ca0: 20 20 20 20 20 20 20 20 20 61 73 20 74 68 65 20           as the 
2cb0: 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 6f 66  1st parameter of
2cc0: 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a   the callback..*
2cd0: 2a 0a 2a 2a 20 7b 46 31 32 31 31 36 7d 20 54 68  *.** {F12116} Th
2ce0: 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  e [sqlite3_exec(
2cf0: 29 5d 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20  )] routine sets 
2d00: 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
2d10: 72 20 6f 66 20 69 74 73 0a 2a 2a 20 20 20 20 20  r of its.**     
2d20: 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 20 74 6f       callback to
2d30: 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   be the number o
2d40: 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65  f columns in the
2d50: 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 0a   current row of.
2d60: 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 73 75  **          resu
2d70: 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31 31  lt..**.** {F1211
2d80: 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  9} The [sqlite3_
2d90: 65 78 65 63 28 29 5d 20 72 6f 75 74 69 6e 65 20  exec()] routine 
2da0: 73 65 74 73 20 74 68 65 20 33 72 64 20 70 61 72  sets the 3rd par
2db0: 61 6d 65 74 65 72 20 6f 66 20 69 74 73 20 0a 2a  ameter of its .*
2dc0: 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c 62  *          callb
2dd0: 61 63 6b 20 74 6f 20 62 65 20 61 6e 20 61 72 72  ack to be an arr
2de0: 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74  ay of pointers t
2df0: 6f 20 73 74 72 69 6e 67 73 20 68 6f 6c 64 69 6e  o strings holdin
2e00: 67 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  g the.**        
2e10: 20 20 76 61 6c 75 65 73 20 66 6f 72 20 65 61 63    values for eac
2e20: 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20  h column in the 
2e30: 63 75 72 72 65 6e 74 20 72 65 73 75 6c 74 20 73  current result s
2e40: 65 74 20 72 6f 77 20 61 73 0a 2a 2a 20 20 20 20  et row as.**    
2e50: 20 20 20 20 20 20 6f 62 74 61 69 6e 65 64 20 66        obtained f
2e60: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  rom [sqlite3_col
2e70: 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a  umn_text()]..**.
2e80: 2a 2a 20 7b 46 31 32 31 32 32 7d 20 54 68 65 20  ** {F12122} The 
2e90: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
2ea0: 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 74 68   routine sets th
2eb0: 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
2ec0: 6f 66 20 69 74 73 0a 2a 2a 20 20 20 20 20 20 20  of its.**       
2ed0: 20 20 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 62     callback to b
2ee0: 65 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f  e an array of po
2ef0: 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67  inters to string
2f00: 73 20 68 6f 6c 64 69 6e 67 20 74 68 65 0a 2a 2a  s holding the.**
2f10: 20 20 20 20 20 20 20 20 20 20 6e 61 6d 65 73 20            names 
2f20: 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  of result column
2f30: 73 20 61 73 20 6f 62 74 61 69 6e 65 64 20 66 72  s as obtained fr
2f40: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  om [sqlite3_colu
2f50: 6d 6e 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a  mn_name()]..**.*
2f60: 2a 20 7b 46 31 32 31 32 35 7d 20 49 66 20 74 68  * {F12125} If th
2f70: 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
2f80: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  to [sqlite3_exec
2f90: 28 29 5d 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e  ()] is NULL then
2fa0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
2fb0: 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 6e 65  lite3_exec()] ne
2fc0: 76 65 72 20 69 6e 76 6f 6b 65 73 20 61 20 63 61  ver invokes a ca
2fd0: 6c 6c 62 61 63 6b 2e 20 20 41 6c 6c 20 71 75 65  llback.  All que
2fe0: 72 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  ry.**          r
2ff0: 65 73 75 6c 74 73 20 61 72 65 20 73 69 6c 65 6e  esults are silen
3000: 74 6c 79 20 64 69 73 63 61 72 64 65 64 2e 0a 2a  tly discarded..*
3010: 2a 0a 2a 2a 20 7b 46 31 32 31 32 38 7d 20 49 66  *.** {F12128} If
3020: 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
3030: 20 77 68 69 6c 65 20 70 61 72 73 69 6e 67 20 6f   while parsing o
3040: 72 20 65 76 61 6c 75 61 74 69 6e 67 20 61 6e 79  r evaluating any
3050: 20 6f 66 20 74 68 65 20 53 51 4c 0a 2a 2a 20 20   of the SQL.**  
3060: 20 20 20 20 20 20 20 20 73 74 61 74 65 6d 65 6e          statemen
3070: 74 73 20 68 61 6e 64 65 64 20 74 6f 20 5b 73 71  ts handed to [sq
3080: 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 74 68  lite3_exec()] th
3090: 65 6e 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  en [sqlite3_exec
30a0: 28 29 5d 20 77 69 6c 6c 0a 2a 2a 20 20 20 20 20  ()] will.**     
30b0: 20 20 20 20 20 72 65 74 75 72 6e 20 61 6e 20 5b       return an [
30c0: 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65  error code] othe
30d0: 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f  r than [SQLITE_O
30e0: 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31 33  K]..**.** {F1213
30f0: 31 7d 20 49 66 20 61 6e 20 65 72 72 6f 72 20 6f  1} If an error o
3100: 63 63 75 72 73 20 77 68 69 6c 65 20 70 61 72 73  ccurs while pars
3110: 69 6e 67 20 6f 72 20 65 76 61 6c 75 61 74 69 6e  ing or evaluatin
3120: 67 20 61 6e 79 20 6f 66 20 74 68 65 20 53 51 4c  g any of the SQL
3130: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 68 61 6e  .**          han
3140: 64 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ded to [sqlite3_
3150: 65 78 65 63 28 29 5d 20 61 6e 64 20 69 66 20 74  exec()] and if t
3160: 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
3170: 20 28 65 72 72 6d 73 67 29 0a 2a 2a 20 20 20 20   (errmsg).**    
3180: 20 20 20 20 20 20 74 6f 20 5b 73 71 6c 69 74 65        to [sqlite
3190: 33 5f 65 78 65 63 28 29 5d 20 69 73 20 6e 6f 74  3_exec()] is not
31a0: 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 61 6e 20 65   NULL, then an e
31b0: 72 72 6f 72 20 6d 65 73 73 61 67 65 20 69 73 0a  rror message is.
31c0: 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c 6c 6f  **          allo
31d0: 63 61 74 65 64 20 75 73 69 6e 67 20 74 68 65 20  cated using the 
31e0: 65 71 75 69 76 61 6c 65 6e 74 20 6f 66 20 5b 73  equivalent of [s
31f0: 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29  qlite3_mprintf()
3200: 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20  ] and.**        
3210: 20 20 2a 65 72 72 6d 73 67 20 69 73 20 6d 61 64    *errmsg is mad
3220: 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68  e to point to th
3230: 61 74 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a  at message..**.*
3240: 2a 20 7b 46 31 32 31 33 34 7d 20 54 68 65 20 5b  * {F12134} The [
3250: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20  sqlite3_exec()] 
3260: 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74  routine does not
3270: 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75   change the valu
3280: 65 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20  e of.**         
3290: 20 2a 65 72 72 6d 73 67 20 69 66 20 65 72 72 6d   *errmsg if errm
32a0: 73 67 20 69 73 20 4e 55 4c 4c 20 6f 72 20 69 66  sg is NULL or if
32b0: 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20 65 72   there are no er
32c0: 72 6f 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  rors..**.** {F12
32d0: 31 33 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  137} The [sqlite
32e0: 33 5f 65 78 65 63 28 29 5d 20 66 75 6e 63 74 69  3_exec()] functi
32f0: 6f 6e 20 73 65 74 73 20 74 68 65 20 65 72 72 6f  on sets the erro
3300: 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61  r code and messa
3310: 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  ge.**          a
3320: 63 63 65 73 73 69 62 6c 65 20 76 69 61 20 5b 73  ccessible via [s
3330: 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
3340: 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ], [sqlite3_errm
3350: 73 67 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 20 20  sg()], and.**   
3360: 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
3370: 65 72 72 6d 73 67 31 36 28 29 5d 2e 0a 2a 2a 0a  errmsg16()]..**.
3380: 2a 2a 20 4c 49 4d 49 54 41 54 49 4f 4e 53 3a 0a  ** LIMITATIONS:.
3390: 2a 2a 0a 2a 2a 20 7b 55 31 32 31 34 31 7d 20 54  **.** {U12141} T
33a0: 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
33b0: 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65  er to [sqlite3_e
33c0: 78 65 63 28 29 5d 20 6d 75 73 74 20 62 65 20 61  xec()] must be a
33d0: 6e 20 76 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e  n valid and open
33e0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61  .**          [da
33f0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
3400: 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 55 31 32 31 34  n]..**.** {U1214
3410: 32 7d 20 54 68 65 20 64 61 74 61 62 61 73 65 20  2} The database 
3420: 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20  connection must 
3430: 6e 6f 74 20 62 65 20 63 6c 6f 73 65 64 20 77 68  not be closed wh
3440: 69 6c 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ile.**          
3450: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
3460: 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20   is running..** 
3470: 0a 2a 2a 20 7b 55 31 32 31 34 33 7d 20 54 68 65  .** {U12143} The
3480: 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f   calling functio
3490: 6e 20 69 73 20 73 68 6f 75 6c 64 20 75 73 65 20  n is should use 
34a0: 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
34b0: 20 74 6f 20 66 72 65 65 0a 2a 2a 20 20 20 20 20   to free.**     
34c0: 20 20 20 20 20 74 68 65 20 6d 65 6d 6f 72 79 20       the memory 
34d0: 74 68 61 74 20 2a 65 72 72 6d 73 67 20 69 73 20  that *errmsg is 
34e0: 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 61 74  left pointing at
34f0: 20 6f 6e 63 65 20 74 68 65 20 65 72 72 6f 72 0a   once the error.
3500: 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 65 73 73  **          mess
3510: 61 67 65 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72  age is no longer
3520: 20 6e 65 65 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b   needed..**.** {
3530: 55 31 32 31 34 35 7d 20 54 68 65 20 53 51 4c 20  U12145} The SQL 
3540: 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 69  statement text i
3550: 6e 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  n the 2nd parame
3560: 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
3570: 65 78 65 63 28 29 5d 0a 2a 2a 20 20 20 20 20 20  exec()].**      
3580: 20 20 20 20 6d 75 73 74 20 72 65 6d 61 69 6e 20      must remain 
3590: 75 6e 63 68 61 6e 67 65 64 20 77 68 69 6c 65 20  unchanged while 
35a0: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
35b0: 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a   is running..*/.
35c0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63  int sqlite3_exec
35d0: 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20  (.  sqlite3*,   
35e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
35f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
3600: 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61  * An open databa
3610: 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  se */.  const ch
3620: 61 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20  ar *sql,        
3630: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3640: 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20     /* SQL to be 
3650: 65 76 61 6c 75 74 65 64 20 2a 2f 0a 20 20 69 6e  evaluted */.  in
3660: 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f  t (*callback)(vo
3670: 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63  id*,int,char**,c
3680: 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c  har**),  /* Call
3690: 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f  back function */
36a0: 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20  .  void *,      
36b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
36c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
36d0: 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f   1st argument to
36e0: 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63   callback */.  c
36f0: 68 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20  har **errmsg    
3700: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3710: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72            /* Err
3720: 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68  or msg written h
3730: 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  ere */.);../*.**
3740: 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c   CAPI3REF: Resul
3750: 74 20 43 6f 64 65 73 20 7b 46 31 30 32 31 30 7d  t Codes {F10210}
3760: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51  .** KEYWORDS: SQ
3770: 4c 49 54 45 5f 4f 4b 20 7b 65 72 72 6f 72 20 63  LITE_OK {error c
3780: 6f 64 65 7d 20 7b 65 72 72 6f 72 20 63 6f 64 65  ode} {error code
3790: 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51  s}.**.** Many SQ
37a0: 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20 72  Lite functions r
37b0: 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65 72  eturn an integer
37c0: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72 6f   result code fro
37d0: 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e 0a  m the set shown.
37e0: 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65 72  ** here in order
37f0: 20 74 6f 20 69 6e 64 69 63 61 74 65 73 20 73 75   to indicates su
3800: 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65  ccess or failure
3810: 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
3820: 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  : [SQLITE_IOERR_
3830: 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64 20  READ | extended 
3840: 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 0a 2a 2f  result codes].*/
3850: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3860: 4f 4b 20 20 20 20 20 20 20 20 20 20 20 30 20 20  OK           0  
3870: 20 2f 2a 20 53 75 63 63 65 73 73 66 75 6c 20 72   /* Successful r
3880: 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67 69  esult */./* begi
3890: 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d 63  nning-of-error-c
38a0: 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20  odes */.#define 
38b0: 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 20 20 20  SQLITE_ERROR    
38c0: 20 20 20 20 31 20 20 20 2f 2a 20 53 51 4c 20 65      1   /* SQL e
38d0: 72 72 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67 20  rror or missing 
38e0: 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66  database */.#def
38f0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52  ine SQLITE_INTER
3900: 4e 41 4c 20 20 20 20 20 32 20 20 20 2f 2a 20 49  NAL     2   /* I
3910: 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65 72  nternal logic er
3920: 72 6f 72 20 69 6e 20 53 51 4c 69 74 65 20 2a 2f  ror in SQLite */
3930: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3940: 50 45 52 4d 20 20 20 20 20 20 20 20 20 33 20 20  PERM         3  
3950: 20 2f 2a 20 41 63 63 65 73 73 20 70 65 72 6d 69   /* Access permi
3960: 73 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a  ssion denied */.
3970: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
3980: 42 4f 52 54 20 20 20 20 20 20 20 20 34 20 20 20  BORT        4   
3990: 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75 74  /* Callback rout
39a0: 69 6e 65 20 72 65 71 75 65 73 74 65 64 20 61 6e  ine requested an
39b0: 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69 6e   abort */.#defin
39c0: 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20  e SQLITE_BUSY   
39d0: 20 20 20 20 20 20 35 20 20 20 2f 2a 20 54 68 65        5   /* The
39e0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69   database file i
39f0: 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66  s locked */.#def
3a00: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45  ine SQLITE_LOCKE
3a10: 44 20 20 20 20 20 20 20 36 20 20 20 2f 2a 20 41  D       6   /* A
3a20: 20 74 61 62 6c 65 20 69 6e 20 74 68 65 20 64 61   table in the da
3a30: 74 61 62 61 73 65 20 69 73 20 6c 6f 63 6b 65 64  tabase is locked
3a40: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
3a50: 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20  TE_NOMEM        
3a60: 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63 28  7   /* A malloc(
3a70: 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65 66  ) failed */.#def
3a80: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f  ine SQLITE_READO
3a90: 4e 4c 59 20 20 20 20 20 38 20 20 20 2f 2a 20 41  NLY     8   /* A
3aa0: 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65 20  ttempt to write 
3ab0: 61 20 72 65 61 64 6f 6e 6c 79 20 64 61 74 61 62  a readonly datab
3ac0: 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ase */.#define S
3ad0: 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 20  QLITE_INTERRUPT 
3ae0: 20 20 20 39 20 20 20 2f 2a 20 4f 70 65 72 61 74     9   /* Operat
3af0: 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64 20 62  ion terminated b
3b00: 79 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  y sqlite3_interr
3b10: 75 70 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65 20  upt()*/.#define 
3b20: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 20 20 20  SQLITE_IOERR    
3b30: 20 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65 20     10   /* Some 
3b40: 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f 4f  kind of disk I/O
3b50: 20 65 72 72 6f 72 20 6f 63 63 75 72 72 65 64 20   error occurred 
3b60: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
3b70: 45 5f 43 4f 52 52 55 50 54 20 20 20 20 20 31 31  E_CORRUPT     11
3b80: 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61     /* The databa
3b90: 73 65 20 64 69 73 6b 20 69 6d 61 67 65 20 69 73  se disk image is
3ba0: 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23 64   malformed */.#d
3bb0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
3bc0: 46 4f 55 4e 44 20 20 20 20 31 32 20 20 20 2f 2a  FOUND    12   /*
3bd0: 20 4e 4f 54 20 55 53 45 44 2e 20 54 61 62 6c 65   NOT USED. Table
3be0: 20 6f 72 20 72 65 63 6f 72 64 20 6e 6f 74 20 66   or record not f
3bf0: 6f 75 6e 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ound */.#define 
3c00: 53 51 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20 20  SQLITE_FULL     
3c10: 20 20 20 31 33 20 20 20 2f 2a 20 49 6e 73 65 72     13   /* Inser
3c20: 74 69 6f 6e 20 66 61 69 6c 65 64 20 62 65 63 61  tion failed beca
3c30: 75 73 65 20 64 61 74 61 62 61 73 65 20 69 73 20  use database is 
3c40: 66 75 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20  full */.#define 
3c50: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20  SQLITE_CANTOPEN 
3c60: 20 20 20 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c     14   /* Unabl
3c70: 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61  e to open the da
3c80: 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23  tabase file */.#
3c90: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52  define SQLITE_PR
3ca0: 4f 54 4f 43 4f 4c 20 20 20 20 31 35 20 20 20 2f  OTOCOL    15   /
3cb0: 2a 20 4e 4f 54 20 55 53 45 44 2e 20 44 61 74 61  * NOT USED. Data
3cc0: 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f 63  base lock protoc
3cd0: 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66  ol error */.#def
3ce0: 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50 54 59  ine SQLITE_EMPTY
3cf0: 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 44         16   /* D
3d00: 61 74 61 62 61 73 65 20 69 73 20 65 6d 70 74 79  atabase is empty
3d10: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
3d20: 54 45 5f 53 43 48 45 4d 41 20 20 20 20 20 20 31  TE_SCHEMA      1
3d30: 37 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62  7   /* The datab
3d40: 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67  ase schema chang
3d50: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
3d60: 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 20 20 20  LITE_TOOBIG     
3d70: 20 31 38 20 20 20 2f 2a 20 53 74 72 69 6e 67 20   18   /* String 
3d80: 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 64 73 20  or BLOB exceeds 
3d90: 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23 64  size limit */.#d
3da0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
3db0: 53 54 52 41 49 4e 54 20 20 31 39 20 20 20 2f 2a  STRAINT  19   /*
3dc0: 20 41 62 6f 72 74 20 64 75 65 20 74 6f 20 63 6f   Abort due to co
3dd0: 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69  nstraint violati
3de0: 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  on */.#define SQ
3df0: 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 20 20 20  LITE_MISMATCH   
3e00: 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20 74 79   20   /* Data ty
3e10: 70 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a 23  pe mismatch */.#
3e20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49  define SQLITE_MI
3e30: 53 55 53 45 20 20 20 20 20 20 32 31 20 20 20 2f  SUSE      21   /
3e40: 2a 20 4c 69 62 72 61 72 79 20 75 73 65 64 20 69  * Library used i
3e50: 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23 64  ncorrectly */.#d
3e60: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4c  efine SQLITE_NOL
3e70: 46 53 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a  FS       22   /*
3e80: 20 55 73 65 73 20 4f 53 20 66 65 61 74 75 72 65   Uses OS feature
3e90: 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 64 20  s not supported 
3ea0: 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66 69  on host */.#defi
3eb0: 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48 20 20  ne SQLITE_AUTH  
3ec0: 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 41 75        23   /* Au
3ed0: 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e 69  thorization deni
3ee0: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
3ef0: 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 20 20 20  LITE_FORMAT     
3f00: 20 32 34 20 20 20 2f 2a 20 41 75 78 69 6c 69 61   24   /* Auxilia
3f10: 72 79 20 64 61 74 61 62 61 73 65 20 66 6f 72 6d  ry database form
3f20: 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66  at error */.#def
3f30: 69 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e 47 45  ine SQLITE_RANGE
3f40: 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 32         25   /* 2
3f50: 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
3f60: 73 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75 74  sqlite3_bind out
3f70: 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64 65   of range */.#de
3f80: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 41  fine SQLITE_NOTA
3f90: 44 42 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20  DB      26   /* 
3fa0: 46 69 6c 65 20 6f 70 65 6e 65 64 20 74 68 61 74  File opened that
3fb0: 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61   is not a databa
3fc0: 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69  se file */.#defi
3fd0: 6e 65 20 53 51 4c 49 54 45 5f 52 4f 57 20 20 20  ne SQLITE_ROW   
3fe0: 20 20 20 20 20 20 31 30 30 20 20 2f 2a 20 73 71        100  /* sq
3ff0: 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73  lite3_step() has
4000: 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 72 65 61   another row rea
4010: 64 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  dy */.#define SQ
4020: 4c 49 54 45 5f 44 4f 4e 45 20 20 20 20 20 20 20  LITE_DONE       
4030: 20 31 30 31 20 20 2f 2a 20 73 71 6c 69 74 65 33   101  /* sqlite3
4040: 5f 73 74 65 70 28 29 20 68 61 73 20 66 69 6e 69  _step() has fini
4050: 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 20 2a  shed executing *
4060: 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 6f  /./* end-of-erro
4070: 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a  r-codes */../*.*
4080: 2a 20 43 41 50 49 33 52 45 46 3a 20 45 78 74 65  * CAPI3REF: Exte
4090: 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65  nded Result Code
40a0: 73 20 7b 46 31 30 32 32 30 7d 0a 2a 2a 20 4b 45  s {F10220}.** KE
40b0: 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65  YWORDS: {extende
40c0: 64 20 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65  d error code} {e
40d0: 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f  xtended error co
40e0: 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  des}.** KEYWORDS
40f0: 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75  : {extended resu
4100: 6c 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20  lt codes}.**.** 
4110: 49 6e 20 69 74 73 20 64 65 66 61 75 6c 74 20 63  In its default c
4120: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 53 51  onfiguration, SQ
4130: 4c 69 74 65 20 41 50 49 20 72 6f 75 74 69 6e 65  Lite API routine
4140: 73 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20  s return one of 
4150: 32 36 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53  26 integer.** [S
4160: 51 4c 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c  QLITE_OK | resul
4170: 74 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76  t codes].  Howev
4180: 65 72 2c 20 65 78 70 65 72 69 65 6e 63 65 20 68  er, experience h
4190: 61 73 20 73 68 6f 77 6e 20 74 68 61 74 0a 2a 2a  as shown that.**
41a0: 20 6d 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72   many of these r
41b0: 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20  esult codes are 
41c0: 74 6f 6f 20 63 6f 75 72 73 65 2d 67 72 61 69 6e  too course-grain
41d0: 65 64 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f 74  ed.  They do not
41e0: 20 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d   provide as.** m
41f0: 75 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  uch information 
4200: 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20 61  about problems a
4210: 73 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69  s programmers mi
4220: 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e  ght like.  In an
4230: 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64   effort to.** ad
4240: 64 72 65 73 73 20 74 68 69 73 2c 20 6e 65 77 65  dress this, newe
4250: 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  r versions of SQ
4260: 4c 69 74 65 20 28 76 65 72 73 69 6f 6e 20 33 2e  Lite (version 3.
4270: 33 2e 38 20 61 6e 64 20 6c 61 74 65 72 29 20 69  3.8 and later) i
4280: 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72  nclude.** suppor
4290: 74 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  t for additional
42a0: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 74 68   result codes th
42b0: 61 74 20 70 72 6f 76 69 64 65 20 6d 6f 72 65 20  at provide more 
42c0: 64 65 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61  detailed informa
42d0: 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72  tion.** about er
42e0: 72 6f 72 73 2e 20 54 68 65 20 65 78 74 65 6e 64  rors. The extend
42f0: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ed result codes 
4300: 61 72 65 20 65 6e 61 62 6c 65 64 20 6f 72 20 64  are enabled or d
4310: 69 73 61 62 6c 65 64 0a 2a 2a 20 66 6f 72 20 65  isabled.** for e
4320: 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ach database con
4330: 6e 65 63 74 69 6f 6e 20 75 73 69 6e 67 20 74 68  nection using th
4340: 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  e [sqlite3_exten
4350: 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73  ded_result_codes
4360: 28 29 5d 0a 2a 2a 20 41 50 49 2e 0a 2a 2a 20 0a  ()].** API..** .
4370: 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68 65 20 61  ** Some of the a
4380: 76 61 69 6c 61 62 6c 65 20 65 78 74 65 6e 64 65  vailable extende
4390: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61  d result codes a
43a0: 72 65 20 6c 69 73 74 65 64 20 68 65 72 65 2e 0a  re listed here..
43b0: 2a 2a 20 4f 6e 65 20 6d 61 79 20 65 78 70 65 63  ** One may expec
43c0: 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
43d0: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
43e0: 63 6f 64 65 73 20 77 69 6c 6c 20 62 65 20 65 78  codes will be ex
43f0: 70 61 6e 64 0a 2a 2a 20 6f 76 65 72 20 74 69 6d  pand.** over tim
4400: 65 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61  e.  Software tha
4410: 74 20 75 73 65 73 20 65 78 74 65 6e 64 65 64 20  t uses extended 
4420: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 73 68 6f  result codes sho
4430: 75 6c 64 20 65 78 70 65 63 74 0a 2a 2a 20 74 6f  uld expect.** to
4440: 20 73 65 65 20 6e 65 77 20 72 65 73 75 6c 74 20   see new result 
4450: 63 6f 64 65 73 20 69 6e 20 66 75 74 75 72 65 20  codes in future 
4460: 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
4470: 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  te..**.** The SQ
4480: 4c 49 54 45 5f 4f 4b 20 72 65 73 75 6c 74 20 63  LITE_OK result c
4490: 6f 64 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 62  ode will never b
44a0: 65 20 65 78 74 65 6e 64 65 64 2e 20 20 49 74 20  e extended.  It 
44b0: 77 69 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a 20 62  will always.** b
44c0: 65 20 65 78 61 63 74 6c 79 20 7a 65 72 6f 2e 0a  e exactly zero..
44d0: 2a 2a 20 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  ** .** INVARIANT
44e0: 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 32 32 33  S:.**.** {F10223
44f0: 7d 20 54 68 65 20 73 79 6d 62 6f 6c 69 63 20 6e  } The symbolic n
4500: 61 6d 65 20 66 6f 72 20 61 6e 20 65 78 74 65 6e  ame for an exten
4510: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 20  ded result code 
4520: 61 6c 77 61 79 73 20 63 6f 6e 74 61 69 6e 73 0a  always contains.
4530: 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 72 65  **          a re
4540: 6c 61 74 65 64 20 70 72 69 6d 61 72 79 20 72 65  lated primary re
4550: 73 75 6c 74 20 63 6f 64 65 20 61 73 20 61 20 70  sult code as a p
4560: 72 65 66 69 78 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  refix..**.** {F1
4570: 30 32 32 34 7d 20 50 72 69 6d 61 72 79 20 72 65  0224} Primary re
4580: 73 75 6c 74 20 63 6f 64 65 20 6e 61 6d 65 73 20  sult code names 
4590: 63 6f 6e 74 61 69 6e 20 61 20 73 69 6e 67 6c 65  contain a single
45a0: 20 22 5f 22 20 63 68 61 72 61 63 74 65 72 2e 0a   "_" character..
45b0: 2a 2a 0a 2a 2a 20 7b 46 31 30 32 32 35 7d 20 45  **.** {F10225} E
45c0: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
45d0: 6f 64 65 20 6e 61 6d 65 73 20 63 6f 6e 74 61 69  ode names contai
45e0: 6e 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 22 5f  n two or more "_
45f0: 22 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a  " characters..**
4600: 0a 2a 2a 20 7b 46 31 30 32 32 36 7d 20 54 68 65  .** {F10226} The
4610: 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 6f   numeric value o
4620: 66 20 61 6e 20 65 78 74 65 6e 64 65 64 20 72 65  f an extended re
4630: 73 75 6c 74 20 63 6f 64 65 20 63 6f 6e 74 61 69  sult code contai
4640: 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ns the.**       
4650: 20 20 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65     numeric value
4660: 20 6f 66 20 69 74 73 20 63 6f 72 72 65 73 70 6f   of its correspo
4670: 6e 64 69 6e 67 20 70 72 69 6d 61 72 79 20 72 65  nding primary re
4680: 73 75 6c 74 20 63 6f 64 65 20 69 74 0a 2a 2a 20  sult code it.** 
4690: 20 20 20 20 20 20 20 20 20 69 74 73 20 6c 65 61           its lea
46a0: 73 74 20 73 69 67 6e 69 66 69 63 61 6e 74 20 38  st significant 8
46b0: 20 62 69 74 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e   bits..*/.#defin
46c0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52  e SQLITE_IOERR_R
46d0: 45 41 44 20 20 20 20 20 20 20 20 20 20 28 53 51  EAD          (SQ
46e0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c  LITE_IOERR | (1<
46f0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
4700: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f  ITE_IOERR_SHORT_
4710: 52 45 41 44 20 20 20 20 28 53 51 4c 49 54 45 5f  READ    (SQLITE_
4720: 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38 29 29 0a  IOERR | (2<<8)).
4730: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4740: 4f 45 52 52 5f 57 52 49 54 45 20 20 20 20 20 20  OERR_WRITE      
4750: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
4760: 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69   | (3<<8)).#defi
4770: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
4780: 46 53 59 4e 43 20 20 20 20 20 20 20 20 20 28 53  FSYNC         (S
4790: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 34  QLITE_IOERR | (4
47a0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
47b0: 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 46  LITE_IOERR_DIR_F
47c0: 53 59 4e 43 20 20 20 20 20 28 53 51 4c 49 54 45  SYNC     (SQLITE
47d0: 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29  _IOERR | (5<<8))
47e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
47f0: 49 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20  IOERR_TRUNCATE  
4800: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4810: 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 66  R | (6<<8)).#def
4820: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4830: 5f 46 53 54 41 54 20 20 20 20 20 20 20 20 20 28  _FSTAT         (
4840: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
4850: 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  7<<8)).#define S
4860: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f  QLITE_IOERR_UNLO
4870: 43 4b 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  CK        (SQLIT
4880: 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c 3c 38 29  E_IOERR | (8<<8)
4890: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
48a0: 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b 20 20 20  _IOERR_RDLOCK   
48b0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
48c0: 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65  RR | (9<<8)).#de
48d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
48e0: 52 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20  R_DELETE        
48f0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4900: 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (10<<8)).#define
4910: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c   SQLITE_IOERR_BL
4920: 4f 43 4b 45 44 20 20 20 20 20 20 20 28 53 51 4c  OCKED       (SQL
4930: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c  ITE_IOERR | (11<
4940: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
4950: 49 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20  ITE_IOERR_NOMEM 
4960: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
4970: 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c 38 29 29  IOERR | (12<<8))
4980: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
4990: 3a 20 46 6c 61 67 73 20 46 6f 72 20 46 69 6c 65  : Flags For File
49a0: 20 4f 70 65 6e 20 4f 70 65 72 61 74 69 6f 6e 73   Open Operations
49b0: 20 7b 46 31 30 32 33 30 7d 0a 2a 2a 0a 2a 2a 20   {F10230}.**.** 
49c0: 54 68 65 73 65 20 62 69 74 20 76 61 6c 75 65 73  These bit values
49d0: 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f   are intended fo
49e0: 72 20 75 73 65 20 69 6e 20 74 68 65 6e 0a 2a 2a  r use in then.**
49f0: 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
4a00: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f  o the [sqlite3_o
4a10: 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66  pen_v2()] interf
4a20: 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68  ace and.** in th
4a30: 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
4a40: 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74  to the xOpen met
4a50: 68 6f 64 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73  hod of the.** [s
4a60: 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
4a70: 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ct..*/.#define S
4a80: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
4a90: 4e 4c 59 20 20 20 20 20 20 20 20 20 30 78 30 30  NLY         0x00
4aa0: 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53  000001.#define S
4ab0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
4ac0: 52 49 54 45 20 20 20 20 20 20 20 20 30 78 30 30  RITE        0x00
4ad0: 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53  000002.#define S
4ae0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
4af0: 45 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30  E           0x00
4b00: 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53  000004.#define S
4b10: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
4b20: 45 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30  EONCLOSE    0x00
4b30: 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53  000008.#define S
4b40: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
4b50: 53 49 56 45 20 20 20 20 20 20 20 20 30 78 30 30  SIVE        0x00
4b60: 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53  000010.#define S
4b70: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
4b80: 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30  DB          0x00
4b90: 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53  000100.#define S
4ba0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
4bb0: 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30  DB          0x00
4bc0: 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53  000200.#define S
4bd0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53  QLITE_OPEN_TRANS
4be0: 49 45 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30  IENT_DB     0x00
4bf0: 30 30 30 34 30 30 0a 23 64 65 66 69 6e 65 20 53  000400.#define S
4c00: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
4c10: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30  JOURNAL     0x00
4c20: 30 30 30 38 30 30 0a 23 64 65 66 69 6e 65 20 53  000800.#define S
4c30: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
4c40: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30  JOURNAL     0x00
4c50: 30 30 31 30 30 30 0a 23 64 65 66 69 6e 65 20 53  001000.#define S
4c60: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f  QLITE_OPEN_SUBJO
4c70: 55 52 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30  URNAL       0x00
4c80: 30 30 32 30 30 30 0a 23 64 65 66 69 6e 65 20 53  002000.#define S
4c90: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45  QLITE_OPEN_MASTE
4ca0: 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30  R_JOURNAL   0x00
4cb0: 30 30 34 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41  004000../*.** CA
4cc0: 50 49 33 52 45 46 3a 20 44 65 76 69 63 65 20 43  PI3REF: Device C
4cd0: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20 7b  haracteristics {
4ce0: 46 31 30 32 34 30 7d 0a 2a 2a 0a 2a 2a 20 54 68  F10240}.**.** Th
4cf0: 65 20 78 44 65 76 69 63 65 43 61 70 61 62 69 6c  e xDeviceCapabil
4d00: 69 74 69 65 73 20 6d 65 74 68 6f 64 20 6f 66 20  ities method of 
4d10: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  the [sqlite3_io_
4d20: 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65  methods].** obje
4d30: 63 74 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e  ct returns an in
4d40: 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20 61  teger which is a
4d50: 20 76 65 63 74 6f 72 20 6f 66 20 74 68 65 20 74   vector of the t
4d60: 68 65 73 65 0a 2a 2a 20 62 69 74 20 76 61 6c 75  hese.** bit valu
4d70: 65 73 20 65 78 70 72 65 73 73 69 6e 67 20 49 2f  es expressing I/
4d80: 4f 20 63 68 61 72 61 63 74 65 72 69 73 74 69 63  O characteristic
4d90: 73 20 6f 66 20 74 68 65 20 6d 61 73 73 20 73 74  s of the mass st
4da0: 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69 63 65 20  orage.** device 
4db0: 74 68 61 74 20 68 6f 6c 64 73 20 74 68 65 20 66  that holds the f
4dc0: 69 6c 65 20 74 68 61 74 20 74 68 65 20 5b 73 71  ile that the [sq
4dd0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
4de0: 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74 6f 2e 0a  ].** refers to..
4df0: 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  **.** The SQLITE
4e00: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72  _IOCAP_ATOMIC pr
4e10: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
4e20: 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a  t all writes of.
4e30: 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20  ** any size are 
4e40: 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c  atomic.  The SQL
4e50: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
4e60: 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65  nnn values.** me
4e70: 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 6f  an that writes o
4e80: 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72  f blocks that ar
4e90: 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73  e nnn bytes in s
4ea0: 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61  ize and.** are a
4eb0: 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64  ligned to an add
4ec0: 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61 6e  ress which is an
4ed0: 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c   integer multipl
4ee0: 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20  e of.** nnn are 
4ef0: 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c  atomic.  The SQL
4f00: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41  ITE_IOCAP_SAFE_A
4f10: 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e  PPEND value mean
4f20: 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64  s.** that when d
4f30: 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 20  ata is appended 
4f40: 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64  to a file, the d
4f50: 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a  ata is appended.
4f60: 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 68  ** first then th
4f70: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69  e size of the fi
4f80: 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20  le is extended, 
4f90: 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a  never the other.
4fa0: 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20  ** way around.  
4fb0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
4fc0: 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70  _SEQUENTIAL prop
4fd0: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a  erty means that.
4fe0: 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  ** information i
4ff0: 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73  s written to dis
5000: 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72  k in the same or
5010: 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20  der as calls.** 
5020: 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2f 0a  to xWrite()..*/.
5030: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5040: 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20 20 20 20  OCAP_ATOMIC     
5050: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31 0a       0x00000001.
5060: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5070: 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 20 20  OCAP_ATOMIC512  
5080: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32 0a       0x00000002.
5090: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
50a0: 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20  OCAP_ATOMIC1K   
50b0: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34 0a       0x00000004.
50c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
50d0: 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20 20  OCAP_ATOMIC2K   
50e0: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 38 0a       0x00000008.
50f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5100: 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20 20  OCAP_ATOMIC4K   
5110: 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0a       0x00000010.
5120: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5130: 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20  OCAP_ATOMIC8K   
5140: 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30 0a       0x00000020.
5150: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5160: 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20  OCAP_ATOMIC16K  
5170: 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30 0a       0x00000040.
5180: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5190: 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20  OCAP_ATOMIC32K  
51a0: 20 20 20 20 20 30 78 30 30 30 30 30 30 38 30 0a       0x00000080.
51b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
51c0: 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20  OCAP_ATOMIC64K  
51d0: 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30 0a       0x00000100.
51e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
51f0: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44  OCAP_SAFE_APPEND
5200: 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30 0a       0x00000200.
5210: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5220: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20  OCAP_SEQUENTIAL 
5230: 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30 0a       0x00000400.
5240: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
5250: 20 46 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65   File Locking Le
5260: 76 65 6c 73 20 7b 46 31 30 32 35 30 7d 0a 2a 2a  vels {F10250}.**
5270: 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20  .** SQLite uses 
5280: 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74  one of these int
5290: 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74  eger values as t
52a0: 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67  he second.** arg
52b0: 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69  ument to calls i
52c0: 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78  t makes to the x
52d0: 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f  Lock() and xUnlo
52e0: 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20  ck() methods.** 
52f0: 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69  of an [sqlite3_i
5300: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
5310: 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t..*/.#define SQ
5320: 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20  LITE_LOCK_NONE  
5330: 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e          0.#defin
5340: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48  e SQLITE_LOCK_SH
5350: 41 52 45 44 20 20 20 20 20 20 20 20 31 0a 23 64  ARED        1.#d
5360: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
5370: 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20 20 20  K_RESERVED      
5380: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
5390: 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20  _LOCK_PENDING   
53a0: 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
53b0: 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53  LITE_LOCK_EXCLUS
53c0: 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a  IVE     4../*.**
53d0: 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68   CAPI3REF: Synch
53e0: 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20  ronization Type 
53f0: 46 6c 61 67 73 20 7b 46 31 30 32 36 30 7d 0a 2a  Flags {F10260}.*
5400: 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69 74 65  *.** When SQLite
5410: 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 78 53 79   invokes the xSy
5420: 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 61  nc() method of a
5430: 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f  n.** [sqlite3_io
5440: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
5450: 20 69 74 20 75 73 65 73 20 61 20 63 6f 6d 62 69   it uses a combi
5460: 6e 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a  nation of the.**
5470: 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76   these integer v
5480: 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63  alues as the sec
5490: 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  ond argument..**
54a0: 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c  .** When the SQL
54b0: 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c  ITE_SYNC_DATAONL
54c0: 59 20 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20  Y flag is used, 
54d0: 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  it means that th
54e0: 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74  e.** sync operat
54f0: 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74  ion only needs t
5500: 6f 20 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20  o flush data to 
5510: 6d 61 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49  mass storage.  I
5520: 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  node.** informat
5530: 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20  ion need not be 
5540: 66 6c 75 73 68 65 64 2e 20 54 68 65 20 53 51 4c  flushed. The SQL
5550: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20  ITE_SYNC_NORMAL 
5560: 6d 65 61 6e 73 20 0a 2a 2a 20 74 6f 20 75 73 65  means .** to use
5570: 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20   normal fsync() 
5580: 73 65 6d 61 6e 74 69 63 73 2e 20 54 68 65 20 53  semantics. The S
5590: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20  QLITE_SYNC_FULL 
55a0: 66 6c 61 67 20 6d 65 61 6e 73 20 0a 2a 2a 20 74  flag means .** t
55b0: 6f 20 75 73 65 20 4d 61 63 20 4f 53 2d 58 20 73  o use Mac OS-X s
55c0: 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69 6e  tyle fullsync in
55d0: 73 74 65 61 64 20 6f 66 20 66 73 79 6e 63 28 29  stead of fsync()
55e0: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
55f0: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20  ITE_SYNC_NORMAL 
5600: 20 20 20 20 20 20 20 30 78 30 30 30 30 32 0a 23         0x00002.#
5610: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59  define SQLITE_SY
5620: 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 20  NC_FULL         
5630: 20 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e 65   0x00003.#define
5640: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54   SQLITE_SYNC_DAT
5650: 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30 30  AONLY      0x000
5660: 31 30 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  10.../*.** CAPI3
5670: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63  REF: OS Interfac
5680: 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64  e Open File Hand
5690: 6c 65 20 7b 46 31 31 31 31 30 7d 0a 2a 2a 0a 2a  le {F11110}.**.*
56a0: 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69  * An [sqlite3_fi
56b0: 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72 65  le] object repre
56c0: 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66 69  sents an open fi
56d0: 6c 65 20 69 6e 20 74 68 65 20 4f 53 0a 2a 2a 20  le in the OS.** 
56e0: 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 2e  interface layer.
56f0: 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f 53 20    Individual OS 
5700: 69 6e 74 65 72 66 61 63 65 20 69 6d 70 6c 65 6d  interface implem
5710: 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a  entations will.*
5720: 2a 20 77 61 6e 74 20 74 6f 20 73 75 62 63 6c 61  * want to subcla
5730: 73 73 20 74 68 69 73 20 6f 62 6a 65 63 74 20 62  ss this object b
5740: 79 20 61 70 70 65 6e 64 69 6e 67 20 61 64 64 69  y appending addi
5750: 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a 2a  tional fields.**
5760: 20 66 6f 72 20 74 68 65 69 72 20 6f 77 6e 20 75   for their own u
5770: 73 65 2e 20 20 54 68 65 20 70 4d 65 74 68 6f 64  se.  The pMethod
5780: 73 20 65 6e 74 72 79 20 69 73 20 61 20 70 6f 69  s entry is a poi
5790: 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73  nter to an.** [s
57a0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
57b0: 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64  s] object that d
57c0: 65 66 69 6e 65 73 20 6d 65 74 68 6f 64 73 20 66  efines methods f
57d0: 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a  or performing.**
57e0: 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20   I/O operations 
57f0: 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65  on the open file
5800: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
5810: 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  uct sqlite3_file
5820: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b 0a 73   sqlite3_file;.s
5830: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69  truct sqlite3_fi
5840: 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73 74 72  le {.  const str
5850: 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  uct sqlite3_io_m
5860: 65 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f 64 73  ethods *pMethods
5870: 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f  ;  /* Methods fo
5880: 72 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 2a  r an open file *
5890: 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
58a0: 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61  3REF: OS Interfa
58b0: 63 65 20 46 69 6c 65 20 56 69 72 74 75 61 6c 20  ce File Virtual 
58c0: 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63 74 20 7b  Methods Object {
58d0: 46 31 31 31 32 30 7d 0a 2a 2a 0a 2a 2a 20 45 76  F11120}.**.** Ev
58e0: 65 72 79 20 66 69 6c 65 20 6f 70 65 6e 65 64 20  ery file opened 
58f0: 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  by the [sqlite3_
5900: 76 66 73 5d 20 78 4f 70 65 6e 20 6d 65 74 68 6f  vfs] xOpen metho
5910: 64 20 63 6f 6e 74 61 69 6e 73 20 61 20 70 6f 69  d contains a poi
5920: 6e 74 65 72 20 74 6f 0a 2a 2a 20 61 6e 20 69 6e  nter to.** an in
5930: 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 74 68  stance of the th
5940: 69 73 20 6f 62 6a 65 63 74 2e 20 20 54 68 69 73  is object.  This
5950: 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20   object defines 
5960: 74 68 65 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 75  the.** methods u
5970: 73 65 64 20 74 6f 20 70 65 72 66 6f 72 6d 20 76  sed to perform v
5980: 61 72 69 6f 75 73 20 6f 70 65 72 61 74 69 6f 6e  arious operation
5990: 73 20 61 67 61 69 6e 73 74 20 74 68 65 20 6f 70  s against the op
59a0: 65 6e 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54  en file..**.** T
59b0: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
59c0: 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79 20 62  t to xSync may b
59d0: 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45  e one of [SQLITE
59e0: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72  _SYNC_NORMAL] or
59f0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43  .** [SQLITE_SYNC
5a00: 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72  _FULL].  The fir
5a10: 73 74 20 63 68 6f 69 63 65 20 69 73 20 74 68 65  st choice is the
5a20: 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e   normal fsync().
5a30: 0a 2a 20 20 54 68 65 20 73 65 63 6f 6e 64 20 63  .*  The second c
5a40: 68 6f 69 63 65 20 69 73 20 61 6e 0a 2a 2a 20 4f  hoice is an.** O
5a50: 53 2d 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79  S-X style fullsy
5a60: 6e 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  nc.  The SQLITE_
5a70: 53 59 4e 43 5f 44 41 54 41 20 66 6c 61 67 20 6d  SYNC_DATA flag m
5a80: 61 79 20 62 65 20 4f 52 65 64 20 69 6e 20 74 6f  ay be ORed in to
5a90: 0a 2a 2a 20 69 6e 64 69 63 61 74 65 20 74 68 61  .** indicate tha
5aa0: 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 74 61 20  t only the data 
5ab0: 6f 66 20 74 68 65 20 66 69 6c 65 20 61 6e 64 20  of the file and 
5ac0: 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65 20 6e 65  not its inode ne
5ad0: 65 64 73 20 74 6f 20 62 65 0a 2a 2a 20 73 79 6e  eds to be.** syn
5ae0: 63 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 54 68 65 20  ced..** .** The 
5af0: 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 74  integer values t
5b00: 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55  o xLock() and xU
5b10: 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 20  nlock() are one 
5b20: 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  of.** <ul>.** <l
5b30: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
5b40: 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  NONE],.** <li> [
5b50: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52  SQLITE_LOCK_SHAR
5b60: 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  ED],.** <li> [SQ
5b70: 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56  LITE_LOCK_RESERV
5b80: 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  ED],.** <li> [SQ
5b90: 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e  LITE_LOCK_PENDIN
5ba0: 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b  G], or.** <li> [
5bb0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c  SQLITE_LOCK_EXCL
5bc0: 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e  USIVE]..** </ul>
5bd0: 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72  .** xLock() incr
5be0: 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20  eases the lock. 
5bf0: 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 61  xUnlock() decrea
5c00: 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20 20 0a  ses the lock.  .
5c10: 2a 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65 73  ** The xCheckRes
5c20: 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68  ervedLock() meth
5c30: 6f 64 20 6c 6f 6f 6b 73 0a 2a 2a 20 74 6f 20 73  od looks.** to s
5c40: 65 65 20 69 66 20 61 6e 79 20 64 61 74 61 62 61  ee if any databa
5c50: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 65  se connection, e
5c60: 69 74 68 65 72 20 69 6e 20 74 68 69 73 0a 2a 2a  ither in this.**
5c70: 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20 73   process or in s
5c80: 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65 73  ome other proces
5c90: 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 6e  s, is holding an
5ca0: 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45   RESERVED,.** PE
5cb0: 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53  NDING, or EXCLUS
5cc0: 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20  IVE lock on the 
5cd0: 66 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e  file.  It return
5ce0: 73 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63  s true.** if suc
5cf0: 68 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20  h a lock exists 
5d00: 61 6e 64 20 66 61 6c 73 65 20 69 66 20 6e 6f 74  and false if not
5d10: 2e 0a 2a 2a 20 0a 2a 2a 20 54 68 65 20 78 46 69  ..** .** The xFi
5d20: 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68  leControl() meth
5d30: 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69 63 20  od is a generic 
5d40: 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61  interface that a
5d50: 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20  llows custom.** 
5d60: 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
5d70: 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c 79 20  ons to directly 
5d80: 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20  control an open 
5d90: 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65 0a 2a  file using the.*
5da0: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  * [sqlite3_file_
5db0: 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72  control()] inter
5dc0: 66 61 63 65 2e 20 20 54 68 65 20 73 65 63 6f 6e  face.  The secon
5dd0: 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e 74 0a  d "op" argument.
5de0: 2a 2a 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ** is an integer
5df0: 20 6f 70 63 6f 64 65 2e 20 20 20 54 68 65 20 74   opcode.   The t
5e00: 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  hird.** argument
5e10: 20 69 73 20 61 20 67 65 6e 65 72 69 63 20 70 6f   is a generic po
5e20: 69 6e 74 65 72 20 77 68 69 63 68 20 69 73 20 69  inter which is i
5e30: 6e 74 65 6e 64 65 64 20 74 6f 20 62 65 20 61 20  ntended to be a 
5e40: 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 61 20  pointer.** to a 
5e50: 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20 6d  structure that m
5e60: 61 79 20 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d  ay contain argum
5e70: 65 6e 74 73 20 6f 72 20 73 70 61 63 65 20 69 6e  ents or space in
5e80: 20 77 68 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69   which to.** wri
5e90: 74 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 73  te return values
5ea0: 2e 20 20 50 6f 74 65 6e 74 69 61 6c 20 75 73 65  .  Potential use
5eb0: 73 20 66 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72  s for xFileContr
5ec0: 6f 6c 28 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a  ol() might be.**
5ed0: 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e   functions to en
5ee0: 61 62 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f  able blocking lo
5ef0: 63 6b 73 20 77 69 74 68 20 74 69 6d 65 6f 75 74  cks with timeout
5f00: 73 2c 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65  s, to change the
5f10: 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61  .** locking stra
5f20: 74 65 67 79 20 28 66 6f 72 20 65 78 61 6d 70 6c  tegy (for exampl
5f30: 65 20 74 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c  e to use dot-fil
5f40: 65 20 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71  e locks), to inq
5f50: 75 69 72 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68  uire.** about th
5f60: 65 20 73 74 61 74 75 73 20 6f 66 20 61 20 6c 6f  e status of a lo
5f70: 63 6b 2c 20 6f 72 20 74 6f 20 62 72 65 61 6b 20  ck, or to break 
5f80: 73 74 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68  stale locks.  Th
5f90: 65 20 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65  e SQLite.** core
5fa0: 20 72 65 73 65 72 76 65 73 20 6f 70 63 6f 64 65   reserves opcode
5fb0: 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20  s less than 100 
5fc0: 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73 65 2e  for its own use.
5fd0: 20 0a 2a 2a 20 41 20 5b 53 51 4c 49 54 45 5f 46   .** A [SQLITE_F
5fe0: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 7c  CNTL_LOCKSTATE |
5ff0: 20 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73   list of opcodes
6000: 5d 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20  ] less than 100 
6010: 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a  is available..**
6020: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   Applications th
6030: 61 74 20 64 65 66 69 6e 65 20 61 20 63 75 73 74  at define a cust
6040: 6f 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  om xFileControl 
6050: 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73  method should us
6060: 65 20 6f 70 63 6f 64 65 73 20 0a 2a 2a 20 67 72  e opcodes .** gr
6070: 65 61 74 65 72 20 74 68 61 6e 20 31 30 30 20 74  eater than 100 t
6080: 6f 20 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74  o avoid conflict
6090: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65  s..**.** The xSe
60a0: 63 74 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f  ctorSize() metho
60b0: 64 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 65  d returns the se
60c0: 63 74 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65  ctor size of the
60d0: 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20  .** device that 
60e0: 75 6e 64 65 72 6c 69 65 73 20 74 68 65 20 66 69  underlies the fi
60f0: 6c 65 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20  le.  The sector 
6100: 73 69 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d  size is the.** m
6110: 69 6e 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61  inimum write tha
6120: 74 20 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d  t can be perform
6130: 65 64 20 77 69 74 68 6f 75 74 20 64 69 73 74 75  ed without distu
6140: 72 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62  rbing.** other b
6150: 79 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65  ytes in the file
6160: 2e 20 20 54 68 65 20 78 44 65 76 69 63 65 43 68  .  The xDeviceCh
6170: 61 72 61 63 74 65 72 69 73 74 69 63 73 28 29 0a  aracteristics().
6180: 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e  ** method return
6190: 73 20 61 20 62 69 74 20 76 65 63 74 6f 72 20 64  s a bit vector d
61a0: 65 73 63 72 69 62 69 6e 67 20 62 65 68 61 76 69  escribing behavi
61b0: 6f 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e  ors of the.** un
61c0: 64 65 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a  derlying device:
61d0: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
61e0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
61f0: 50 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69  P_ATOMIC].** <li
6200: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6210: 41 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c  ATOMIC512].** <l
6220: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
6230: 5f 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c  _ATOMIC1K].** <l
6240: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
6250: 5f 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c  _ATOMIC2K].** <l
6260: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
6270: 5f 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c  _ATOMIC4K].** <l
6280: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
6290: 5f 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c  _ATOMIC8K].** <l
62a0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
62b0: 5f 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c  _ATOMIC16K].** <
62c0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
62d0: 50 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20  P_ATOMIC32K].** 
62e0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
62f0: 41 50 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a  AP_ATOMIC64K].**
6300: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
6310: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d  CAP_SAFE_APPEND]
6320: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
6330: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
6340: 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  L].** </ul>.**.*
6350: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43  * The SQLITE_IOC
6360: 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72  AP_ATOMIC proper
6370: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c  ty means that al
6380: 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61  l writes of.** a
6390: 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d  ny size are atom
63a0: 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  ic.  The SQLITE_
63b0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20  IOCAP_ATOMICnnn 
63c0: 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74  values.** mean t
63d0: 68 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c  hat writes of bl
63e0: 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e  ocks that are nn
63f0: 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20  n bytes in size 
6400: 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e  and.** are align
6410: 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73  ed to an address
6420: 20 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74   which is an int
6430: 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66  eger multiple of
6440: 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d  .** nnn are atom
6450: 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  ic.  The SQLITE_
6460: 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e  IOCAP_SAFE_APPEN
6470: 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a  D value means.**
6480: 20 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20   that when data 
6490: 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61  is appended to a
64a0: 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20   file, the data 
64b0: 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66  is appended.** f
64c0: 69 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69  irst then the si
64d0: 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69  ze of the file i
64e0: 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65  s extended, neve
64f0: 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77  r the other.** w
6500: 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20  ay around.  The 
6510: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51  SQLITE_IOCAP_SEQ
6520: 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79  UENTIAL property
6530: 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69   means that.** i
6540: 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72  nformation is wr
6550: 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e  itten to disk in
6560: 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20   the same order 
6570: 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78  as calls.** to x
6580: 57 72 69 74 65 28 29 2e 0a 2a 2f 0a 74 79 70 65  Write()..*/.type
6590: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
65a0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71  e3_io_methods sq
65b0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
65c0: 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  ;.struct sqlite3
65d0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20  _io_methods {.  
65e0: 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20  int iVersion;.  
65f0: 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71  int (*xClose)(sq
6600: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
6610: 69 6e 74 20 28 2a 78 52 65 61 64 29 28 73 71 6c  int (*xRead)(sql
6620: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64  ite3_file*, void
6630: 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c  *, int iAmt, sql
6640: 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74  ite3_int64 iOfst
6650: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72 69 74  );.  int (*xWrit
6660: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
6670: 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
6680: 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33  nt iAmt, sqlite3
6690: 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20  _int64 iOfst);. 
66a0: 20 69 6e 74 20 28 2a 78 54 72 75 6e 63 61 74 65   int (*xTruncate
66b0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
66c0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73   sqlite3_int64 s
66d0: 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  ize);.  int (*xS
66e0: 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ync)(sqlite3_fil
66f0: 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a  e*, int flags);.
6700: 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a    int (*xFileSiz
6710: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
6720: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
6730: 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28  *pSize);.  int (
6740: 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f  *xLock)(sqlite3_
6750: 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69  file*, int);.  i
6760: 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71  nt (*xUnlock)(sq
6770: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
6780: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68 65 63  );.  int (*xChec
6790: 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 29 28 73  kReservedLock)(s
67a0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20  qlite3_file*);. 
67b0: 20 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74   int (*xFileCont
67c0: 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  rol)(sqlite3_fil
67d0: 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64  e*, int op, void
67e0: 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28   *pArg);.  int (
67f0: 2a 78 53 65 63 74 6f 72 53 69 7a 65 29 28 73 71  *xSectorSize)(sq
6800: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
6810: 69 6e 74 20 28 2a 78 44 65 76 69 63 65 43 68 61  int (*xDeviceCha
6820: 72 61 63 74 65 72 69 73 74 69 63 73 29 28 73 71  racteristics)(sq
6830: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
6840: 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65  /* Additional me
6850: 74 68 6f 64 73 20 6d 61 79 20 62 65 20 61 64 64  thods may be add
6860: 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
6870: 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a  eases */.};../*.
6880: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74 61  ** CAPI3REF: Sta
6890: 6e 64 61 72 64 20 46 69 6c 65 20 43 6f 6e 74 72  ndard File Contr
68a0: 6f 6c 20 4f 70 63 6f 64 65 73 20 7b 46 31 31 33  ol Opcodes {F113
68b0: 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  10}.**.** These 
68c0: 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74  integer constant
68d0: 73 20 61 72 65 20 6f 70 63 6f 64 65 73 20 66 6f  s are opcodes fo
68e0: 72 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72  r the xFileContr
68f0: 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20  ol method.** of 
6900: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  the [sqlite3_io_
6910: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20  methods] object 
6920: 61 6e 64 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  and to the [sqli
6930: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
6940: 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ()].** interface
6950: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ..**.** The [SQL
6960: 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54  ITE_FCNTL_LOCKST
6970: 41 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  ATE] opcode is u
6980: 73 65 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e  sed for debuggin
6990: 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f  g.  This.** opco
69a0: 64 65 20 63 61 73 65 73 20 74 68 65 20 78 46 69  de cases the xFi
69b0: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
69c0: 20 74 6f 20 77 72 69 74 65 20 74 68 65 20 63 75   to write the cu
69d0: 72 72 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a  rrent state of.*
69e0: 2a 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20  * the lock (one 
69f0: 6f 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  of [SQLITE_LOCK_
6a00: 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c  NONE], [SQLITE_L
6a10: 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20  OCK_SHARED],.** 
6a20: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53  [SQLITE_LOCK_RES
6a30: 45 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f  ERVED], [SQLITE_
6a40: 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f  LOCK_PENDING], o
6a50: 72 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45  r [SQLITE_LOCK_E
6a60: 58 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e  XCLUSIVE]).** in
6a70: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68  to an integer th
6a80: 61 74 20 74 68 65 20 70 41 72 67 20 61 72 67 75  at the pArg argu
6a90: 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20  ment points to. 
6aa0: 54 68 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a  This capability.
6ab0: 2a 2a 20 69 73 20 75 73 65 64 20 64 75 72 69 6e  ** is used durin
6ac0: 67 20 74 65 73 74 69 6e 67 20 61 6e 64 20 6f 6e  g testing and on
6ad0: 6c 79 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73  ly needs to be s
6ae0: 75 70 70 6f 72 74 65 64 20 77 68 65 6e 20 53 51  upported when SQ
6af0: 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20 69 73 20  LITE_TEST.** is 
6b00: 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 23 64 65 66  defined..*/.#def
6b10: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
6b20: 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20 20 20 20  _LOCKSTATE      
6b30: 20 20 31 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33    1../*.** CAPI3
6b40: 52 45 46 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c  REF: Mutex Handl
6b50: 65 20 7b 46 31 37 31 31 30 7d 0a 2a 2a 0a 2a 2a  e {F17110}.**.**
6b60: 20 54 68 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c   The mutex modul
6b70: 65 20 77 69 74 68 69 6e 20 53 51 4c 69 74 65 20  e within SQLite 
6b80: 64 65 66 69 6e 65 73 20 5b 73 71 6c 69 74 65 33  defines [sqlite3
6b90: 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65 20 61 6e  _mutex] to be an
6ba0: 0a 2a 2a 20 61 62 73 74 72 61 63 74 20 74 79 70  .** abstract typ
6bb0: 65 20 66 6f 72 20 61 20 6d 75 74 65 78 20 6f 62  e for a mutex ob
6bc0: 6a 65 63 74 2e 20 20 54 68 65 20 53 51 4c 69 74  ject.  The SQLit
6bd0: 65 20 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f  e core never loo
6be0: 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e 74  ks.** at the int
6bf0: 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61  ernal representa
6c00: 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69  tion of an [sqli
6c10: 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20  te3_mutex].  It 
6c20: 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69  only.** deals wi
6c30: 74 68 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74  th pointers to t
6c40: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
6c50: 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a  x] object..**.**
6c60: 20 4d 75 74 65 78 65 73 20 61 72 65 20 63 72 65   Mutexes are cre
6c70: 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  ated using [sqli
6c80: 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28  te3_mutex_alloc(
6c90: 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  )]..*/.typedef s
6ca0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75  truct sqlite3_mu
6cb0: 74 65 78 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  tex sqlite3_mute
6cc0: 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  x;../*.** CAPI3R
6cd0: 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65  EF: OS Interface
6ce0: 20 4f 62 6a 65 63 74 20 7b 46 31 31 31 34 30 7d   Object {F11140}
6cf0: 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e  .**.** An instan
6d00: 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
6d10: 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e  t defines the in
6d20: 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 20  terface between 
6d30: 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f  the.** SQLite co
6d40: 72 65 20 61 6e 64 20 74 68 65 20 75 6e 64 65 72  re and the under
6d50: 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20  lying operating 
6d60: 73 79 73 74 65 6d 2e 20 20 54 68 65 20 22 76 66  system.  The "vf
6d70: 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d  s".** in the nam
6d80: 65 20 6f 66 20 74 68 65 20 6f 62 6a 65 63 74 20  e of the object 
6d90: 73 74 61 6e 64 73 20 66 6f 72 20 22 76 69 72 74  stands for "virt
6da0: 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 22  ual file system"
6db0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 56 65 72  ..**.** The iVer
6dc0: 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 20 69 6e  sion field is in
6dd0: 69 74 69 61 6c 6c 79 20 31 20 62 75 74 20 6d 61  itially 1 but ma
6de0: 79 20 62 65 20 6c 61 72 67 65 72 20 66 6f 72 20  y be larger for 
6df0: 66 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f  future.** versio
6e00: 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41  ns of SQLite.  A
6e10: 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73  dditional fields
6e20: 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64   may be appended
6e30: 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65   to this.** obje
6e40: 63 74 20 77 68 65 6e 20 74 68 65 20 69 56 65 72  ct when the iVer
6e50: 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 20 69 6e  sion value is in
6e60: 63 72 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  creased..**.** T
6e70: 68 65 20 73 7a 4f 73 46 69 6c 65 20 66 69 65 6c  he szOsFile fiel
6e80: 64 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66  d is the size of
6e90: 20 74 68 65 20 73 75 62 63 6c 61 73 73 65 64 20   the subclassed 
6ea0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 0a 2a  [sqlite3_file].*
6eb0: 2a 20 73 74 72 75 63 74 75 72 65 20 75 73 65 64  * structure used
6ec0: 20 62 79 20 74 68 69 73 20 56 46 53 2e 20 20 6d   by this VFS.  m
6ed0: 78 50 61 74 68 6e 61 6d 65 20 69 73 20 74 68 65  xPathname is the
6ee0: 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   maximum length 
6ef0: 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e 61 6d 65  of.** a pathname
6f00: 20 69 6e 20 74 68 69 73 20 56 46 53 2e 0a 2a 2a   in this VFS..**
6f10: 0a 2a 2a 20 52 65 67 69 73 74 65 72 65 64 20 73  .** Registered s
6f20: 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63  qlite3_vfs objec
6f30: 74 73 20 61 72 65 20 6b 65 70 74 20 6f 6e 20 61  ts are kept on a
6f40: 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20 66 6f 72   linked list for
6f50: 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 70 4e  med by.** the pN
6f60: 65 78 74 20 70 6f 69 6e 74 65 72 2e 20 20 54 68  ext pointer.  Th
6f70: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 72  e [sqlite3_vfs_r
6f80: 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a 20 61 6e  egister()].** an
6f90: 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 75  d [sqlite3_vfs_u
6fa0: 6e 72 65 67 69 73 74 65 72 28 29 5d 20 69 6e 74  nregister()] int
6fb0: 65 72 66 61 63 65 73 20 6d 61 6e 61 67 65 20 74  erfaces manage t
6fc0: 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69 6e 20 61  his list.** in a
6fd0: 20 74 68 72 65 61 64 2d 73 61 66 65 20 77 61 79   thread-safe way
6fe0: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
6ff0: 76 66 73 5f 66 69 6e 64 28 29 5d 20 69 6e 74 65  vfs_find()] inte
7000: 72 66 61 63 65 0a 2a 2a 20 73 65 61 72 63 68 65  rface.** searche
7010: 73 20 74 68 65 20 6c 69 73 74 2e 0a 2a 2a 0a 2a  s the list..**.*
7020: 2a 20 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c  * The pNext fiel
7030: 64 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69  d is the only fi
7040: 65 6c 64 73 20 69 6e 20 74 68 65 20 73 71 6c 69  elds in the sqli
7050: 74 65 33 5f 76 66 73 20 0a 2a 2a 20 73 74 72 75  te3_vfs .** stru
7060: 63 74 75 72 65 20 74 68 61 74 20 53 51 4c 69 74  cture that SQLit
7070: 65 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69  e will ever modi
7080: 66 79 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c  fy.  SQLite will
7090: 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20   only access.** 
70a0: 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 66  or modify this f
70b0: 69 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64 69  ield while holdi
70c0: 6e 67 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  ng a particular 
70d0: 73 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a  static mutex..**
70e0: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
70f0: 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f   should never mo
7100: 64 69 66 79 20 61 6e 79 74 68 69 6e 67 20 77 69  dify anything wi
7110: 74 68 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33  thin the sqlite3
7120: 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f  _vfs.** object o
7130: 6e 63 65 20 74 68 65 20 6f 62 6a 65 63 74 20 68  nce the object h
7140: 61 73 20 62 65 65 6e 20 72 65 67 69 73 74 65 72  as been register
7150: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e  ed..**.** The zN
7160: 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64 73 20  ame field holds 
7170: 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
7180: 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65  VFS module.  The
7190: 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65   name must.** be
71a0: 20 75 6e 69 71 75 65 20 61 63 72 6f 73 73 20 61   unique across a
71b0: 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a  ll VFS modules..
71c0: 2a 2a 0a 2a 2a 20 7b 46 31 31 31 34 31 7d 20 53  **.** {F11141} S
71d0: 51 4c 69 74 65 20 77 69 6c 6c 20 67 75 61 72 61  QLite will guara
71e0: 6e 74 65 65 20 74 68 61 74 20 74 68 65 20 7a 46  ntee that the zF
71f0: 69 6c 65 6e 61 6d 65 20 73 74 72 69 6e 67 20 70  ilename string p
7200: 61 73 73 65 64 20 74 6f 0a 2a 2a 20 78 4f 70 65  assed to.** xOpe
7210: 6e 28 29 20 69 73 20 61 20 66 75 6c 6c 20 70 61  n() is a full pa
7220: 74 68 6e 61 6d 65 20 61 73 20 67 65 6e 65 72 61  thname as genera
7230: 74 65 64 20 62 79 20 78 46 75 6c 6c 50 61 74 68  ted by xFullPath
7240: 6e 61 6d 65 28 29 20 61 6e 64 0a 2a 2a 20 74 68  name() and.** th
7250: 61 74 20 74 68 65 20 73 74 72 69 6e 67 20 77 69  at the string wi
7260: 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 6e 64 20  ll be valid and 
7270: 75 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 6c 20  unchanged until 
7280: 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63  xClose() is.** c
7290: 61 6c 6c 65 64 2e 20 20 7b 45 4e 44 7d 20 53 6f  alled.  {END} So
72a0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
72b0: 6c 65 5d 20 63 61 6e 20 73 74 6f 72 65 20 61 20  le] can store a 
72c0: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a  pointer to the.*
72d0: 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66 20 69 74  * filename if it
72e0: 20 6e 65 65 64 73 20 74 6f 20 72 65 6d 65 6d 62   needs to rememb
72f0: 65 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  er the filename 
7300: 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2e  for some reason.
7310: 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 31 34 32 7d 20  .**.** {F11142} 
7320: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
7330: 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e  nt to xOpen() in
7340: 63 6c 75 64 65 73 20 61 6c 6c 20 62 69 74 73 20  cludes all bits 
7350: 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c  set in.** the fl
7360: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ags argument to 
7370: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
7380: 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c  ()].  Or if [sql
7390: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20  ite3_open()].** 
73a0: 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  or [sqlite3_open
73b0: 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20 74  16()] is used, t
73c0: 68 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75 64  hen flags includ
73d0: 65 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b  es at least.** [
73e0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
73f0: 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45  WRITE] | [SQLITE
7400: 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20 7b  _OPEN_CREATE]. {
7410: 45 4e 44 7d 0a 2a 2a 20 49 66 20 78 4f 70 65 6e  END}.** If xOpen
7420: 28 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20  () opens a file 
7430: 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69  read-only then i
7440: 74 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67  t sets *pOutFlag
7450: 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20  s to.** include 
7460: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
7470: 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62  DONLY].  Other b
7480: 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67  its in *pOutFlag
7490: 73 20 6d 61 79 20 62 65 0a 2a 2a 20 73 65 74 2e  s may be.** set.
74a0: 0a 2a 2a 20 0a 2a 2a 20 7b 46 31 31 31 34 33 7d  .** .** {F11143}
74b0: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73   SQLite will als
74c0: 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65  o add one of the
74d0: 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73   following flags
74e0: 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 0a   to the xOpen().
74f0: 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69  ** call, dependi
7500: 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74  ng on the object
7510: 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a   being opened:.*
7520: 2a 20 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  * .** <ul>.** <l
7530: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
7540: 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69  _MAIN_DB].** <li
7550: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
7560: 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a  MAIN_JOURNAL].**
7570: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
7580: 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20  PEN_TEMP_DB].** 
7590: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
75a0: 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d  EN_TEMP_JOURNAL]
75b0: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
75c0: 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54  E_OPEN_TRANSIENT
75d0: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  _DB].** <li>  [S
75e0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f  QLITE_OPEN_SUBJO
75f0: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  URNAL].** <li>  
7600: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53  [SQLITE_OPEN_MAS
7610: 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  TER_JOURNAL].** 
7620: 3c 2f 75 6c 3e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a  </ul> {END}.**.*
7630: 2a 20 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 69  * The file I/O i
7640: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61  mplementation ca
7650: 6e 20 75 73 65 20 74 68 65 20 6f 62 6a 65 63 74  n use the object
7660: 20 74 79 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a   type flags to.*
7670: 2a 20 63 68 61 6e 67 65 73 20 74 68 65 20 77 61  * changes the wa
7680: 79 20 69 74 20 64 65 61 6c 73 20 77 69 74 68 20  y it deals with 
7690: 66 69 6c 65 73 2e 20 20 46 6f 72 20 65 78 61 6d  files.  For exam
76a0: 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74  ple, an applicat
76b0: 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73  ion.** that does
76c0: 20 6e 6f 74 20 63 61 72 65 20 61 62 6f 75 74 20   not care about 
76d0: 63 72 61 73 68 20 72 65 63 6f 76 65 72 79 20 6f  crash recovery o
76e0: 72 20 72 6f 6c 6c 62 61 63 6b 2c 20 6d 69 67 68  r rollback, migh
76f0: 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70  t make.** the op
7700: 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20  en of a journal 
7710: 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57  file a no-op.  W
7720: 72 69 74 65 73 20 74 6f 20 74 68 69 73 20 6a 6f  rites to this jo
7730: 75 72 6e 61 6c 20 61 72 65 0a 2a 2a 20 61 6c 73  urnal are.** als
7740: 6f 20 61 20 6e 6f 2d 6f 70 2e 20 20 41 6e 79 20  o a no-op.  Any 
7750: 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20  attempt to read 
7760: 74 68 65 20 6a 6f 75 72 6e 61 6c 20 72 65 74 75  the journal retu
7770: 72 6e 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e  rn SQLITE_IOERR.
7780: 0a 2a 2a 20 4f 72 20 74 68 65 20 69 6d 70 6c 65  .** Or the imple
7790: 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74 20  mentation might 
77a0: 72 65 63 6f 67 6e 69 7a 65 20 74 68 65 20 61 20  recognize the a 
77b0: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69  database file wi
77c0: 6c 6c 0a 2a 2a 20 62 65 20 64 6f 69 6e 67 20 70  ll.** be doing p
77d0: 61 67 65 2d 61 6c 69 67 6e 65 64 20 73 65 63 74  age-aligned sect
77e0: 6f 72 20 72 65 61 64 73 20 61 6e 64 20 77 72 69  or reads and wri
77f0: 74 65 73 20 69 6e 20 61 20 72 61 6e 64 6f 6d 20  tes in a random 
7800: 6f 72 64 65 72 0a 2a 2a 20 61 6e 64 20 73 65 74  order.** and set
7810: 20 75 70 20 69 74 73 20 49 2f 4f 20 73 75 62 73   up its I/O subs
7820: 79 73 74 65 6d 20 61 63 63 6f 72 64 69 6e 67 6c  ystem accordingl
7830: 79 2e 0a 2a 2a 20 0a 2a 2a 20 53 51 4c 69 74 65  y..** .** SQLite
7840: 20 6d 69 67 68 74 20 61 6c 73 6f 20 61 64 64 20   might also add 
7850: 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f  one of the follo
7860: 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68  wing flags to th
7870: 65 20 78 4f 70 65 6e 0a 2a 2a 20 6d 65 74 68 6f  e xOpen.** metho
7880: 64 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75 6c 3e 0a 2a  d:.** .** <ul>.*
7890: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f  * <li> [SQLITE_O
78a0: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
78b0: 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  E].** <li> [SQLI
78c0: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56  TE_OPEN_EXCLUSIV
78d0: 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 0a  E].** </ul>.** .
78e0: 2a 2a 20 7b 46 31 31 31 34 35 7d 20 54 68 65 20  ** {F11145} The 
78f0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c  [SQLITE_OPEN_DEL
7900: 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67  ETEONCLOSE] flag
7910: 20 6d 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20   means the file 
7920: 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c  should be.** del
7930: 65 74 65 64 20 77 68 65 6e 20 69 74 20 69 73 20  eted when it is 
7940: 63 6c 6f 73 65 64 2e 20 20 7b 46 31 31 31 34 36  closed.  {F11146
7950: 7d 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  } The [SQLITE_OP
7960: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
7970: 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65 74  ].** will be set
7980: 20 66 6f 72 20 54 45 4d 50 20 20 64 61 74 61 62   for TEMP  datab
7990: 61 73 65 73 2c 20 6a 6f 75 72 6e 61 6c 73 20 61  ases, journals a
79a0: 6e 64 20 66 6f 72 20 73 75 62 6a 6f 75 72 6e 61  nd for subjourna
79b0: 6c 73 2e 20 0a 2a 2a 20 7b 46 31 31 31 34 37 7d  ls. .** {F11147}
79c0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   The [SQLITE_OPE
79d0: 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20 66 6c 61  N_EXCLUSIVE] fla
79e0: 67 20 6d 65 61 6e 73 20 74 68 65 20 66 69 6c 65  g means the file
79f0: 20 73 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65   should be opene
7a00: 64 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73 69  d.** for exclusi
7a10: 76 65 20 61 63 63 65 73 73 2e 20 20 54 68 69 73  ve access.  This
7a20: 20 66 6c 61 67 20 69 73 20 73 65 74 20 66 6f 72   flag is set for
7a30: 20 61 6c 6c 20 66 69 6c 65 73 20 65 78 63 65 70   all files excep
7a40: 74 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d 61 69  t.** for the mai
7a50: 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e  n database file.
7a60: 20 7b 45 4e 44 7d 0a 2a 2a 20 0a 2a 2a 20 7b 46   {END}.** .** {F
7a70: 31 31 31 34 38 7d 20 41 74 20 6c 65 61 73 74 20  11148} At least 
7a80: 73 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20 6f  szOsFile bytes o
7a90: 66 20 6d 65 6d 6f 72 79 20 69 73 20 61 6c 6c 6f  f memory is allo
7aa0: 63 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 20  cated by SQLite 
7ab0: 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  .** to hold the 
7ac0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
7ad0: 73 74 72 75 63 74 75 72 65 20 70 61 73 73 65 64  structure passed
7ae0: 20 61 73 20 74 68 65 20 74 68 69 72 64 20 0a 2a   as the third .*
7af0: 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f  * argument to xO
7b00: 70 65 6e 2e 20 20 7b 45 4e 44 7d 20 20 54 68 65  pen.  {END}  The
7b10: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f   xOpen method do
7b20: 65 73 20 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a  es not have to.*
7b30: 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 20 73  * allocate the s
7b40: 74 72 75 63 74 75 72 65 3b 20 69 74 20 73 68 6f  tructure; it sho
7b50: 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20 69 74  uld just fill it
7b60: 20 69 6e 2e 0a 2a 2a 20 0a 2a 2a 20 7b 46 31 31   in..** .** {F11
7b70: 31 34 39 7d 20 54 68 65 20 66 6c 61 67 73 20 61  149} The flags a
7b80: 72 67 75 6d 65 6e 74 20 74 6f 20 78 41 63 63 65  rgument to xAcce
7b90: 73 73 28 29 20 6d 61 79 20 62 65 20 5b 53 51 4c  ss() may be [SQL
7ba0: 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54  ITE_ACCESS_EXIST
7bb0: 53 5d 20 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66  S] .** to test f
7bc0: 6f 72 20 74 68 65 20 65 78 69 73 74 61 6e 63 65  or the existance
7bd0: 20 6f 66 20 61 20 66 69 6c 65 2c 0a 2a 2a 20 6f   of a file,.** o
7be0: 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53  r [SQLITE_ACCESS
7bf0: 5f 52 45 41 44 57 52 49 54 45 5d 20 74 6f 20 74  _READWRITE] to t
7c00: 65 73 74 20 74 6f 20 73 65 65 0a 2a 2a 20 69 66  est to see.** if
7c10: 20 61 20 66 69 6c 65 20 69 73 20 72 65 61 64 61   a file is reada
7c20: 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65  ble and writable
7c30: 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43  , or [SQLITE_ACC
7c40: 45 53 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20  ESS_READ].** to 
7c50: 74 65 73 74 20 74 6f 20 73 65 65 20 69 66 20 61  test to see if a
7c60: 20 66 69 6c 65 20 69 73 20 61 74 20 6c 65 61 73   file is at leas
7c70: 74 20 72 65 61 64 61 62 6c 65 2e 20 20 7b 45 4e  t readable.  {EN
7c80: 44 7d 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20  D} The file can 
7c90: 62 65 20 61 20 0a 2a 2a 20 64 69 72 65 63 74 6f  be a .** directo
7ca0: 72 79 2e 0a 2a 2a 20 0a 2a 2a 20 7b 46 31 31 31  ry..** .** {F111
7cb0: 35 30 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  50} SQLite will 
7cc0: 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74 65 20  always allocate 
7cd0: 61 74 20 6c 65 61 73 74 20 6d 78 50 61 74 68 6e  at least mxPathn
7ce0: 61 6d 65 2b 31 20 62 79 74 65 20 66 6f 72 0a 2a  ame+1 byte for.*
7cf0: 2a 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66  * the output buf
7d00: 66 65 72 73 20 66 6f 72 20 78 47 65 74 54 65 6d  fers for xGetTem
7d10: 70 6e 61 6d 65 20 61 6e 64 20 78 46 75 6c 6c 50  pname and xFullP
7d20: 61 74 68 6e 61 6d 65 2e 20 7b 46 31 31 31 35 31  athname. {F11151
7d30: 7d 20 54 68 65 20 65 78 61 63 74 0a 2a 2a 20 73  } The exact.** s
7d40: 69 7a 65 20 6f 66 20 74 68 65 20 6f 75 74 70 75  ize of the outpu
7d50: 74 20 62 75 66 66 65 72 20 69 73 20 61 6c 73 6f  t buffer is also
7d60: 20 70 61 73 73 65 64 20 61 73 20 61 20 70 61 72   passed as a par
7d70: 61 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20 0a  ameter to both .
7d80: 2a 2a 20 6d 65 74 68 6f 64 73 2e 20 7b 45 4e 44  ** methods. {END
7d90: 7d 20 49 66 20 74 68 65 20 6f 75 74 70 75 74 20  } If the output 
7da0: 62 75 66 66 65 72 20 69 73 20 6e 6f 74 20 6c 61  buffer is not la
7db0: 72 67 65 20 65 6e 6f 75 67 68 2c 20 53 51 4c 49  rge enough, SQLI
7dc0: 54 45 5f 43 41 4e 54 4f 50 45 4e 0a 2a 2a 20 73  TE_CANTOPEN.** s
7dd0: 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65  hould be returne
7de0: 64 2e 20 41 73 20 74 68 69 73 20 69 73 20 68 61  d. As this is ha
7df0: 6e 64 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c  ndled as a fatal
7e00: 20 65 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65   error by SQLite
7e10: 2c 0a 2a 2a 20 76 66 73 20 69 6d 70 6c 65 6d 65  ,.** vfs impleme
7e20: 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ntations should 
7e30: 65 6e 64 65 61 76 6f 72 20 74 6f 20 70 72 65 76  endeavor to prev
7e40: 65 6e 74 20 74 68 69 73 20 62 79 20 73 65 74 74  ent this by sett
7e50: 69 6e 67 20 0a 2a 2a 20 6d 78 50 61 74 68 6e 61  ing .** mxPathna
7e60: 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63 69 65  me to a sufficie
7e70: 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c 75 65  ntly large value
7e80: 2e 0a 2a 2a 20 0a 2a 2a 20 54 68 65 20 78 52 61  ..** .** The xRa
7e90: 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65  ndomness(), xSle
7ea0: 65 70 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65  ep(), and xCurre
7eb0: 6e 74 54 69 6d 65 28 29 20 69 6e 74 65 72 66 61  ntTime() interfa
7ec0: 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 73  ces.** are not s
7ed0: 74 72 69 63 74 6c 79 20 61 20 70 61 72 74 20 6f  trictly a part o
7ee0: 66 20 74 68 65 20 66 69 6c 65 73 79 73 74 65 6d  f the filesystem
7ef0: 2c 20 62 75 74 20 74 68 65 79 20 61 72 65 0a 2a  , but they are.*
7f00: 2a 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68  * included in th
7f10: 65 20 56 46 53 20 73 74 72 75 63 74 75 72 65 20  e VFS structure 
7f20: 66 6f 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73  for completeness
7f30: 2e 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d  ..** The xRandom
7f40: 6e 65 73 73 28 29 20 66 75 6e 63 74 69 6f 6e 20  ness() function 
7f50: 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 74 75  attempts to retu
7f60: 72 6e 20 6e 42 79 74 65 73 20 62 79 74 65 73 0a  rn nBytes bytes.
7f70: 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69  ** of good-quali
7f80: 74 79 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e  ty randomness in
7f90: 74 6f 20 7a 4f 75 74 2e 20 20 54 68 65 20 72 65  to zOut.  The re
7fa0: 74 75 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a  turn value is.**
7fb0: 20 74 68 65 20 61 63 74 75 61 6c 20 6e 75 6d 62   the actual numb
7fc0: 65 72 20 6f 66 20 62 79 74 65 73 20 6f 66 20 72  er of bytes of r
7fd0: 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e  andomness obtain
7fe0: 65 64 2e 20 20 54 68 65 0a 2a 2a 20 78 53 6c 65  ed.  The.** xSle
7ff0: 65 70 28 29 20 6d 65 74 68 6f 64 20 63 61 75 73  ep() method caus
8000: 65 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68  e the calling th
8010: 72 65 61 64 20 74 6f 20 73 6c 65 65 70 20 66 6f  read to sleep fo
8020: 72 20 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68  r at.** least th
8030: 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63 72  e number of micr
8040: 6f 73 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20  oseconds given. 
8050: 20 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d   The xCurrentTim
8060: 65 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65  e().** method re
8070: 74 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44  turns a Julian D
8080: 61 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68  ay Number for th
8090: 65 20 63 75 72 72 65 6e 74 20 64 61 74 65 20 61  e current date a
80a0: 6e 64 0a 2a 2a 20 74 69 6d 65 2e 0a 2a 2f 0a 74  nd.** time..*/.t
80b0: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
80c0: 6c 69 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65  lite3_vfs sqlite
80d0: 33 5f 76 66 73 3b 0a 73 74 72 75 63 74 20 73 71  3_vfs;.struct sq
80e0: 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e  lite3_vfs {.  in
80f0: 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20 20  t iVersion;     
8100: 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63 74         /* Struct
8110: 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62  ure version numb
8120: 65 72 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73  er */.  int szOs
8130: 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20  File;           
8140: 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63   /* Size of subc
8150: 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66  lassed sqlite3_f
8160: 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50  ile */.  int mxP
8170: 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20  athname;        
8180: 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c    /* Maximum fil
8190: 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74  e pathname lengt
81a0: 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76  h */.  sqlite3_v
81b0: 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20  fs *pNext;      
81c0: 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65 72  /* Next register
81d0: 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73  ed VFS */.  cons
81e0: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20  t char *zName;  
81f0: 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20       /* Name of 
8200: 74 68 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c  this virtual fil
8210: 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f  e system */.  vo
8220: 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20  id *pAppData;   
8230: 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65         /* Pointe
8240: 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e  r to application
8250: 2d 73 70 65 63 69 66 69 63 20 64 61 74 61 20 2a  -specific data *
8260: 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29  /.  int (*xOpen)
8270: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
8280: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
8290: 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  , sqlite3_file*,
82a0: 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
82b0: 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a  int flags, int *
82c0: 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e  pOutFlags);.  in
82d0: 74 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c  t (*xDelete)(sql
82e0: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
82f0: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
8300: 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e  t syncDir);.  in
8310: 74 20 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c  t (*xAccess)(sql
8320: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
8330: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
8340: 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20  t flags);.  int 
8350: 28 2a 78 47 65 74 54 65 6d 70 6e 61 6d 65 29 28  (*xGetTempname)(
8360: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e  sqlite3_vfs*, in
8370: 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f  t nOut, char *zO
8380: 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 75  ut);.  int (*xFu
8390: 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71 6c 69  llPathname)(sqli
83a0: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
83b0: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74  char *zName, int
83c0: 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f 75   nOut, char *zOu
83d0: 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44  t);.  void *(*xD
83e0: 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76  lOpen)(sqlite3_v
83f0: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
8400: 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20 76  *zFilename);.  v
8410: 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72 29 28  oid (*xDlError)(
8420: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e  sqlite3_vfs*, in
8430: 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a  t nByte, char *z
8440: 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64 20  ErrMsg);.  void 
8450: 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c 69 74  *(*xDlSym)(sqlit
8460: 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c 20 63  e3_vfs*,void*, c
8470: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 79 6d 62  onst char *zSymb
8480: 6f 6c 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44  ol);.  void (*xD
8490: 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f  lClose)(sqlite3_
84a0: 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20  vfs*, void*);.  
84b0: 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73  int (*xRandomnes
84c0: 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  s)(sqlite3_vfs*,
84d0: 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72   int nByte, char
84e0: 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28   *zOut);.  int (
84f0: 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 74 65 33  *xSleep)(sqlite3
8500: 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f  _vfs*, int micro
8510: 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20  seconds);.  int 
8520: 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 29 28  (*xCurrentTime)(
8530: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f  sqlite3_vfs*, do
8540: 75 62 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4e 65 77  uble*);.  /* New
8550: 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61   fields may be a
8560: 70 70 65 6e 64 65 64 20 69 6e 20 66 69 67 75 72  ppended in figur
8570: 65 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65  e versions.  The
8580: 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76   iVersion.  ** v
8590: 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d  alue will increm
85a0: 65 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68 69  ent whenever thi
85b0: 73 20 68 61 70 70 65 6e 73 2e 20 2a 2f 0a 7d 3b  s happens. */.};
85c0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
85d0: 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20  : Flags for the 
85e0: 78 41 63 63 65 73 73 20 56 46 53 20 6d 65 74 68  xAccess VFS meth
85f0: 6f 64 20 7b 46 31 31 31 39 30 7d 0a 2a 2a 0a 2a  od {F11190}.**.*
8600: 2a 20 7b 46 31 31 31 39 31 7d 20 54 68 65 73 65  * {F11191} These
8610: 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e   integer constan
8620: 74 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 61  ts can be used a
8630: 73 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  s the third para
8640: 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20  meter to.** the 
8650: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 6f  xAccess method o
8660: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66  f an [sqlite3_vf
8670: 73 5d 20 6f 62 6a 65 63 74 2e 20 7b 45 4e 44 7d  s] object. {END}
8680: 20 20 54 68 65 79 20 64 65 74 65 72 6d 69 6e 65    They determine
8690: 0a 2a 2a 20 74 68 65 20 6b 69 6e 64 20 6f 66 20  .** the kind of 
86a0: 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72  what kind of per
86b0: 6d 69 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63  missions the xAc
86c0: 63 65 73 73 20 6d 65 74 68 6f 64 20 69 73 0a 2a  cess method is.*
86d0: 2a 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e 20 20  * looking for.  
86e0: 7b 46 31 31 31 39 32 7d 20 57 69 74 68 20 53 51  {F11192} With SQ
86f0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53  LITE_ACCESS_EXIS
8700: 54 53 2c 20 74 68 65 20 78 41 63 63 65 73 73 20  TS, the xAccess 
8710: 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79  method.** simply
8720: 20 63 68 65 63 6b 73 20 74 6f 20 73 65 65 20 69   checks to see i
8730: 66 20 74 68 65 20 66 69 6c 65 20 65 78 69 73 74  f the file exist
8740: 73 2e 20 7b 46 31 31 31 39 33 7d 20 57 69 74 68  s. {F11193} With
8750: 0a 2a 2a 20 53 51 4c 49 54 45 5f 41 43 43 45 53  .** SQLITE_ACCES
8760: 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68 65  S_READWRITE, the
8770: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20   xAccess method 
8780: 63 68 65 63 6b 73 20 74 6f 20 73 65 65 0a 2a 2a  checks to see.**
8790: 20 69 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   if the file is 
87a0: 62 6f 74 68 20 72 65 61 64 61 62 6c 65 20 61 6e  both readable an
87b0: 64 20 77 72 69 74 61 62 6c 65 2e 20 20 7b 46 31  d writable.  {F1
87c0: 31 31 39 34 7d 20 57 69 74 68 0a 2a 2a 20 53 51  1194} With.** SQ
87d0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
87e0: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
87f0: 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 74 6f  hod.** checks to
8800: 20 73 65 65 20 69 66 20 74 68 65 20 66 69 6c 65   see if the file
8810: 20 69 73 20 72 65 61 64 61 62 6c 65 2e 0a 2a 2f   is readable..*/
8820: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8830: 41 43 43 45 53 53 5f 45 58 49 53 54 53 20 20 20  ACCESS_EXISTS   
8840: 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   0.#define SQLIT
8850: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49  E_ACCESS_READWRI
8860: 54 45 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c  TE 1.#define SQL
8870: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20  ITE_ACCESS_READ 
8880: 20 20 20 20 20 32 0a 0a 2f 2a 0a 2a 2a 20 43 41       2../*.** CA
8890: 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f  PI3REF: Enable O
88a0: 72 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e 64  r Disable Extend
88b0: 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 20  ed Result Codes 
88c0: 7b 46 31 32 32 30 30 7d 0a 2a 2a 0a 2a 2a 20 54  {F12200}.**.** T
88d0: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  he sqlite3_exten
88e0: 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73  ded_result_codes
88f0: 28 29 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c  () routine enabl
8900: 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74  es or disables t
8910: 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f  he.** [SQLITE_IO
8920: 45 52 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e  ERR_READ | exten
8930: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
8940: 5d 20 66 65 61 74 75 72 65 20 6f 66 20 53 51 4c  ] feature of SQL
8950: 69 74 65 2e 0a 2a 2a 20 54 68 65 20 65 78 74 65  ite..** The exte
8960: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
8970: 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 62  s are disabled b
8980: 79 20 64 65 66 61 75 6c 74 20 66 6f 72 20 68 69  y default for hi
8990: 73 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70  storical.** comp
89a0: 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a  atibility..**.**
89b0: 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
89c0: 2a 2a 20 7b 46 31 32 32 30 31 7d 20 45 61 63 68  ** {F12201} Each
89d0: 20 6e 65 77 20 5b 64 61 74 61 62 61 73 65 20 63   new [database c
89e0: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 73 20 74  onnection] has t
89f0: 68 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  he .**          
8a00: 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
8a10: 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65 0a   codes] feature.
8a20: 2a 2a 20 20 20 20 20 20 20 20 20 20 64 69 73 61  **          disa
8a30: 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e  bled by default.
8a40: 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 30 32 7d 20  .**.** {F12202} 
8a50: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 74  The [sqlite3_ext
8a60: 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64  ended_result_cod
8a70: 65 73 28 44 2c 46 29 5d 20 69 6e 74 65 72 66 61  es(D,F)] interfa
8a80: 63 65 20 77 69 6c 6c 20 65 6e 61 62 6c 65 0a 2a  ce will enable.*
8a90: 2a 20 20 20 20 20 20 20 20 20 20 5b 65 78 74 65  *          [exte
8aa0: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
8ab0: 73 5d 20 66 6f 72 20 74 68 65 20 0a 2a 2a 20 20  s] for the .**  
8ac0: 20 20 20 20 20 20 20 20 5b 64 61 74 61 62 61 73          [databas
8ad0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20  e connection] D 
8ae0: 69 66 20 74 68 65 20 46 20 70 61 72 61 6d 65 74  if the F paramet
8af0: 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  er.**          i
8b00: 73 20 74 72 75 65 2c 20 6f 72 20 64 69 73 61 62  s true, or disab
8b10: 6c 65 20 74 68 65 6d 20 69 66 20 46 20 69 73 20  le them if F is 
8b20: 66 61 6c 73 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71  false..*/.int sq
8b30: 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72  lite3_extended_r
8b40: 65 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69  esult_codes(sqli
8b50: 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29  te3*, int onoff)
8b60: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
8b70: 46 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52  F: Last Insert R
8b80: 6f 77 69 64 20 7b 46 31 32 32 32 30 7d 0a 2a 2a  owid {F12220}.**
8b90: 0a 2a 2a 20 45 61 63 68 20 65 6e 74 72 79 20 69  .** Each entry i
8ba0: 6e 20 61 6e 20 53 51 4c 69 74 65 20 74 61 62 6c  n an SQLite tabl
8bb0: 65 20 68 61 73 20 61 20 75 6e 69 71 75 65 20 36  e has a unique 6
8bc0: 34 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20  4-bit signed.** 
8bd0: 69 6e 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c  integer key call
8be0: 65 64 20 74 68 65 20 22 72 6f 77 69 64 22 2e 20  ed the "rowid". 
8bf0: 54 68 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77  The rowid is alw
8c00: 61 79 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a  ays available.**
8c10: 20 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65   as an undeclare
8c20: 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52  d column named R
8c30: 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52  OWID, OID, or _R
8c40: 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73  OWID_ as long as
8c50: 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20   those.** names 
8c60: 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65  are not also use
8c70: 64 20 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20  d by explicitly 
8c80: 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73  declared columns
8c90: 2e 20 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c  . If.** the tabl
8ca0: 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f  e has a column o
8cb0: 66 20 74 79 70 65 20 49 4e 54 45 47 45 52 20 50  f type INTEGER P
8cc0: 52 49 4d 41 52 59 20 4b 45 59 20 74 68 65 6e 20  RIMARY KEY then 
8cd0: 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69  that column.** i
8ce0: 73 20 61 6e 6f 74 68 65 72 20 61 6e 20 61 6c 69  s another an ali
8cf0: 61 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69 64  as for the rowid
8d00: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  ..**.** This rou
8d10: 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
8d20: 20 72 6f 77 69 64 20 6f 66 20 74 68 65 20 6d 6f   rowid of the mo
8d30: 73 74 20 72 65 63 65 6e 74 0a 2a 2a 20 73 75 63  st recent.** suc
8d40: 63 65 73 73 66 75 6c 20 49 4e 53 45 52 54 20 69  cessful INSERT i
8d50: 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65  nto the database
8d60: 20 66 72 6f 6d 20 74 68 65 20 64 61 74 61 62 61   from the databa
8d70: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
8d80: 20 73 68 6f 77 6e 20 69 6e 20 74 68 65 20 66 69   shown in the fi
8d90: 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 20 20 49  rst argument.  I
8da0: 66 20 6e 6f 20 73 75 63 63 65 73 73 66 75 6c 20  f no successful 
8db0: 69 6e 73 65 72 74 73 0a 2a 2a 20 68 61 76 65 20  inserts.** have 
8dc0: 65 76 65 72 20 6f 63 63 75 72 72 65 64 20 6f 6e  ever occurred on
8dd0: 20 74 68 69 73 20 64 61 74 61 62 61 73 65 20 63   this database c
8de0: 6f 6e 6e 65 63 74 69 6f 6e 2c 20 7a 65 72 6f 20  onnection, zero 
8df0: 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
8e00: 2a 2a 20 49 66 20 61 6e 20 49 4e 53 45 52 54 20  ** If an INSERT 
8e10: 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 20  occurs within a 
8e20: 74 72 69 67 67 65 72 2c 20 74 68 65 6e 20 74 68  trigger, then th
8e30: 65 20 72 6f 77 69 64 20 6f 66 20 74 68 65 0a 2a  e rowid of the.*
8e40: 2a 20 69 6e 73 65 72 74 65 64 20 72 6f 77 20 69  * inserted row i
8e50: 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  s returned by th
8e60: 69 73 20 72 6f 75 74 69 6e 65 20 61 73 20 6c 6f  is routine as lo
8e70: 6e 67 20 61 73 20 74 68 65 20 74 72 69 67 67 65  ng as the trigge
8e80: 72 0a 2a 2a 20 69 73 20 72 75 6e 6e 69 6e 67 2e  r.** is running.
8e90: 20 20 42 75 74 20 6f 6e 63 65 20 74 68 65 20 74    But once the t
8ea0: 72 69 67 67 65 72 20 74 65 72 6d 69 6e 61 74 65  rigger terminate
8eb0: 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  s, the value ret
8ec0: 75 72 6e 65 64 0a 2a 2a 20 62 79 20 74 68 69 73  urned.** by this
8ed0: 20 72 6f 75 74 69 6e 65 20 72 65 76 65 72 74 73   routine reverts
8ee0: 20 74 6f 20 74 68 65 20 6c 61 73 74 20 76 61 6c   to the last val
8ef0: 75 65 20 69 6e 73 65 72 74 65 64 20 62 65 66 6f  ue inserted befo
8f00: 72 65 20 74 68 65 0a 2a 2a 20 74 72 69 67 67 65  re the.** trigge
8f10: 72 20 66 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 41  r fired..**.** A
8f20: 6e 20 49 4e 53 45 52 54 20 74 68 61 74 20 66 61  n INSERT that fa
8f30: 69 6c 73 20 64 75 65 20 74 6f 20 61 20 63 6f 6e  ils due to a con
8f40: 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f  straint violatio
8f50: 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75  n is not a.** su
8f60: 63 63 65 73 73 66 75 6c 20 69 6e 73 65 72 74 20  ccessful insert 
8f70: 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68 61  and does not cha
8f80: 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20 72 65  nge the value re
8f90: 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a 2a  turned by this.*
8fa0: 2a 20 72 6f 75 74 69 6e 65 2e 20 20 54 68 75 73  * routine.  Thus
8fb0: 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49 4c 2c   INSERT OR FAIL,
8fc0: 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f 52   INSERT OR IGNOR
8fd0: 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c  E, INSERT OR ROL
8fe0: 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e  LBACK,.** and IN
8ff0: 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20 6d 61  SERT OR ABORT ma
9000: 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f  ke no changes to
9010: 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
9020: 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75  e of this.** rou
9030: 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69 72 20  tine when their 
9040: 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e  insertion fails.
9050: 20 20 57 68 65 6e 20 49 4e 53 45 52 54 20 4f 52    When INSERT OR
9060: 20 52 45 50 4c 41 43 45 20 0a 2a 2a 20 65 6e 63   REPLACE .** enc
9070: 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 74 72  ounters a constr
9080: 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20  aint violation, 
9090: 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c  it does not fail
90a0: 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54  .  The.** INSERT
90b0: 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f   continues to co
90c0: 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 20 64  mpletion after d
90d0: 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 68 61  eleting rows tha
90e0: 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 65 20  t caused.** the 
90f0: 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f 62 6c  constraint probl
9100: 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f 52 20  em so INSERT OR 
9110: 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77  REPLACE will alw
9120: 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68  ays change.** th
9130: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
9140: 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  f this interface
9150: 2e 20 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 74 68 65  . .**.** For the
9160: 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69   purposes of thi
9170: 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 69 6e  s routine, an in
9180: 73 65 72 74 20 69 73 20 63 6f 6e 73 69 64 65 72  sert is consider
9190: 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63  ed to.** be succ
91a0: 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69  essful even if i
91b0: 74 20 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c  t is subsequentl
91c0: 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a  y rolled back..*
91d0: 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
91e0: 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 32 31 7d 20  .**.** {F12221} 
91f0: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73  The [sqlite3_las
9200: 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29  t_insert_rowid()
9210: 5d 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  ] function retur
9220: 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ns the.**       
9230: 20 20 20 72 6f 77 69 64 20 6f 66 20 74 68 65 20     rowid of the 
9240: 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 75 63 63  most recent succ
9250: 65 73 73 66 75 6c 20 69 6e 73 65 72 74 20 64 6f  essful insert do
9260: 6e 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  ne.**          o
9270: 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  n the same datab
9280: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 61  ase connection a
9290: 6e 64 20 77 69 74 68 69 6e 20 74 68 65 20 73 61  nd within the sa
92a0: 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  me.**          t
92b0: 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2c 20  rigger context, 
92c0: 6f 72 20 7a 65 72 6f 20 69 66 20 74 68 65 72 65  or zero if there
92d0: 20 68 61 76 65 0a 2a 2a 20 20 20 20 20 20 20 20   have.**        
92e0: 20 20 62 65 65 6e 20 6e 6f 20 71 75 61 6c 69 66    been no qualif
92f0: 79 69 6e 67 20 69 6e 73 65 72 74 73 20 6f 6e 20  ying inserts on 
9300: 74 68 61 74 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  that connection.
9310: 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 32 33 7d 20  .**.** {F12223} 
9320: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73  The [sqlite3_las
9330: 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29  t_insert_rowid()
9340: 5d 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  ] function retur
9350: 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73  ns.**          s
9360: 61 6d 65 20 76 61 6c 75 65 20 77 68 65 6e 20 63  ame value when c
9370: 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73  alled from the s
9380: 61 6d 65 20 74 72 69 67 67 65 72 20 63 6f 6e 74  ame trigger cont
9390: 65 78 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ext.**          
93a0: 69 6d 6d 65 64 69 61 74 65 6c 79 20 62 65 66 6f  immediately befo
93b0: 72 65 20 61 6e 64 20 61 66 74 65 72 20 61 20 52  re and after a R
93c0: 4f 4c 4c 42 41 43 4b 2e 0a 2a 2a 0a 2a 2a 20 4c  OLLBACK..**.** L
93d0: 49 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a  IMITATIONS:.**.*
93e0: 2a 20 7b 55 31 32 32 33 32 7d 20 49 66 20 73 65  * {U12232} If se
93f0: 70 61 72 61 74 65 20 74 68 72 65 61 64 20 64 6f  parate thread do
9400: 65 73 20 61 20 6e 65 77 20 69 6e 73 65 72 74 20  es a new insert 
9410: 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20  on the same.**  
9420: 20 20 20 20 20 20 20 20 64 61 74 61 62 61 73 65          database
9430: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c   connection whil
9440: 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c  e the [sqlite3_l
9450: 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
9460: 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ()].**          
9470: 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
9480: 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63 68 61  ing and thus cha
9490: 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20 69 6e  nges the last in
94a0: 73 65 72 74 20 72 6f 77 69 64 2c 0a 2a 2a 20 20  sert rowid,.**  
94b0: 20 20 20 20 20 20 20 20 74 68 65 6e 20 74 68 65          then the
94c0: 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
94d0: 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74  by [sqlite3_last
94e0: 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d  _insert_rowid()]
94f0: 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   is.**          
9500: 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e  unpredictable an
9510: 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71 75 61  d might not equa
9520: 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f 6c 64  l either the old
9530: 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20 20   or the new.**  
9540: 20 20 20 20 20 20 20 20 6c 61 73 74 20 69 6e 73          last ins
9550: 65 72 74 20 72 6f 77 69 64 2e 0a 2a 2f 0a 73 71  ert rowid..*/.sq
9560: 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
9570: 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
9580: 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 29 3b  rowid(sqlite3*);
9590: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
95a0: 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62  : Count The Numb
95b0: 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66  er Of Rows Modif
95c0: 69 65 64 20 7b 46 31 32 32 34 30 7d 0a 2a 2a 0a  ied {F12240}.**.
95d0: 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  ** This function
95e0: 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
95f0: 62 65 72 20 6f 66 20 64 61 74 61 62 61 73 65 20  ber of database 
9600: 72 6f 77 73 20 74 68 61 74 20 77 65 72 65 20 63  rows that were c
9610: 68 61 6e 67 65 64 0a 2a 2a 20 6f 72 20 69 6e 73  hanged.** or ins
9620: 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64  erted or deleted
9630: 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63   by the most rec
9640: 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20  ently completed 
9650: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  SQL statement.**
9660: 20 6f 6e 20 74 68 65 20 63 6f 6e 6e 65 63 74 69   on the connecti
9670: 6f 6e 20 73 70 65 63 69 66 69 65 64 20 62 79 20  on specified by 
9680: 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
9690: 74 65 72 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 63 68  ter.  Only.** ch
96a0: 61 6e 67 65 73 20 74 68 61 74 20 61 72 65 20 64  anges that are d
96b0: 69 72 65 63 74 6c 79 20 73 70 65 63 69 66 69 65  irectly specifie
96c0: 64 20 62 79 20 74 68 65 20 49 4e 53 45 52 54 2c  d by the INSERT,
96d0: 20 55 50 44 41 54 45 2c 20 6f 72 0a 2a 2a 20 44   UPDATE, or.** D
96e0: 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20  ELETE statement 
96f0: 61 72 65 20 63 6f 75 6e 74 65 64 2e 20 20 41 75  are counted.  Au
9700: 78 69 6c 69 61 72 79 20 63 68 61 6e 67 65 73 20  xiliary changes 
9710: 63 61 75 73 65 64 20 62 79 0a 2a 2a 20 74 72 69  caused by.** tri
9720: 67 67 65 72 73 20 61 72 65 20 6e 6f 74 20 63 6f  ggers are not co
9730: 75 6e 74 65 64 2e 20 55 73 65 20 74 68 65 20 5b  unted. Use the [
9740: 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
9750: 61 6e 67 65 73 28 29 5d 20 66 75 6e 63 74 69 6f  anges()] functio
9760: 6e 0a 2a 2a 20 74 6f 20 66 69 6e 64 20 74 68 65  n.** to find the
9770: 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66   total number of
9780: 20 63 68 61 6e 67 65 73 20 69 6e 63 6c 75 64 69   changes includi
9790: 6e 67 20 63 68 61 6e 67 65 73 20 63 61 75 73 65  ng changes cause
97a0: 64 20 62 79 20 74 72 69 67 67 65 72 73 2e 0a 2a  d by triggers..*
97b0: 2a 0a 2a 2a 20 41 20 22 72 6f 77 20 63 68 61 6e  *.** A "row chan
97c0: 67 65 73 22 20 69 73 20 61 20 63 68 61 6e 67 65  ges" is a change
97d0: 20 74 6f 20 61 20 73 69 6e 67 6c 65 20 72 6f 77   to a single row
97e0: 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 74 61 62   of a single tab
97f0: 6c 65 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20  le.** caused by 
9800: 61 6e 20 49 4e 53 45 52 54 2c 20 44 45 4c 45 54  an INSERT, DELET
9810: 45 2c 20 6f 72 20 55 50 44 41 54 45 20 73 74 61  E, or UPDATE sta
9820: 74 65 6d 65 6e 74 2e 20 20 52 6f 77 73 20 74 68  tement.  Rows th
9830: 61 74 0a 2a 2a 20 61 72 65 20 63 68 61 6e 67 65  at.** are change
9840: 64 20 61 73 20 73 69 64 65 20 65 66 66 65 63 74  d as side effect
9850: 73 20 6f 66 20 52 45 50 4c 41 43 45 20 63 6f 6e  s of REPLACE con
9860: 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69  straint resoluti
9870: 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c  on,.** rollback,
9880: 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e   ABORT processin
9890: 67 2c 20 44 52 4f 50 20 54 41 42 4c 45 2c 20 6f  g, DROP TABLE, o
98a0: 72 20 62 79 20 61 6e 79 20 6f 74 68 65 72 0a 2a  r by any other.*
98b0: 2a 20 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f 20  * mechanisms do 
98c0: 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 64 69 72  not count as dir
98d0: 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73 2e  ect row changes.
98e0: 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72 69 67 67 65  .**.** A "trigge
98f0: 72 20 63 6f 6e 74 65 78 74 22 20 69 73 20 61 20  r context" is a 
9900: 73 63 6f 70 65 20 6f 66 20 65 78 65 63 75 74 69  scope of executi
9910: 6f 6e 20 74 68 61 74 20 62 65 67 69 6e 73 20 61  on that begins a
9920: 6e 64 0a 2a 2a 20 65 6e 64 73 20 77 69 74 68 20  nd.** ends with 
9930: 74 68 65 20 73 63 72 69 70 74 20 6f 66 20 61 20  the script of a 
9940: 74 72 69 67 67 65 72 2e 20 20 4d 6f 73 74 20 53  trigger.  Most S
9950: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72  QL statements ar
9960: 65 0a 2a 2a 20 65 76 61 6c 75 61 74 65 64 20 6f  e.** evaluated o
9970: 75 74 73 69 64 65 20 6f 66 20 61 6e 79 20 74 72  utside of any tr
9980: 69 67 67 65 72 2e 20 20 54 68 69 73 20 69 73 20  igger.  This is 
9990: 74 68 65 20 22 74 6f 70 20 6c 65 76 65 6c 22 0a  the "top level".
99a0: 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65  ** trigger conte
99b0: 78 74 2e 20 20 49 66 20 61 20 74 72 69 67 67 65  xt.  If a trigge
99c0: 72 20 66 69 72 65 73 20 66 72 6f 6d 20 74 68 65  r fires from the
99d0: 20 74 6f 70 20 6c 65 76 65 6c 2c 20 61 0a 2a 2a   top level, a.**
99e0: 20 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e   new trigger con
99f0: 74 65 78 74 20 69 73 20 65 6e 74 65 72 65 64 20  text is entered 
9a00: 66 6f 72 20 74 68 65 20 64 75 72 61 74 69 6f 6e  for the duration
9a10: 20 6f 66 20 74 68 61 74 20 6f 6e 65 0a 2a 2a 20   of that one.** 
9a20: 74 72 69 67 67 65 72 2e 20 20 53 75 62 74 72 69  trigger.  Subtri
9a30: 67 67 65 72 73 20 63 72 65 61 74 65 20 73 75 62  ggers create sub
9a40: 63 6f 6e 74 65 78 74 73 20 66 6f 72 20 74 68 65  contexts for the
9a50: 69 72 20 64 75 72 61 74 69 6f 6e 2e 0a 2a 2a 0a  ir duration..**.
9a60: 2a 2a 20 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  ** Calling [sqli
9a70: 74 65 33 5f 65 78 65 63 28 29 5d 20 6f 72 20 5b  te3_exec()] or [
9a80: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
9a90: 72 65 63 75 72 73 69 76 65 6c 79 20 64 6f 65 73  recursively does
9aa0: 0a 2a 2a 20 6e 6f 74 20 63 72 65 61 74 65 20 61  .** not create a
9ab0: 20 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e   new trigger con
9ac0: 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  text..**.** This
9ad0: 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
9ae0: 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
9af0: 64 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67  direct row chang
9b00: 65 73 20 69 6e 20 74 68 65 0a 2a 2a 20 6d 6f 73  es in the.** mos
9b10: 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c  t recent INSERT,
9b20: 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45   UPDATE, or DELE
9b30: 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74  TE statement wit
9b40: 68 69 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20  hin the same.** 
9b50: 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e  trigger context.
9b60: 0a 2a 2a 0a 2a 2a 20 53 6f 20 77 68 65 6e 20 63  .**.** So when c
9b70: 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 74  alled from the t
9b80: 6f 70 20 6c 65 76 65 6c 2c 20 74 68 69 73 20 66  op level, this f
9b90: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
9ba0: 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
9bb0: 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20   changes in the 
9bc0: 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45  most recent INSE
9bd0: 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44  RT, UPDATE, or D
9be0: 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 61 6c  ELETE.** that al
9bf0: 73 6f 20 6f 63 63 75 72 72 65 64 20 61 74 20 74  so occurred at t
9c00: 68 65 20 74 6f 70 20 6c 65 76 65 6c 2e 0a 2a 2a  he top level..**
9c10: 20 57 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79   Within the body
9c20: 20 6f 66 20 61 20 74 72 69 67 67 65 72 2c 20 74   of a trigger, t
9c30: 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  he sqlite3_chang
9c40: 65 73 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a  es() interface.*
9c50: 2a 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20  * can be called 
9c60: 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62  to find the numb
9c70: 65 72 20 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 73  er of.** changes
9c80: 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63   in the most rec
9c90: 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20  ently completed 
9ca0: 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20  INSERT, UPDATE, 
9cb0: 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61  or DELETE.** sta
9cc0: 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68  tement within th
9cd0: 65 20 62 6f 64 79 20 6f 66 20 74 68 65 20 73 61  e body of the sa
9ce0: 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 20 48  me trigger..** H
9cf0: 6f 77 65 76 65 72 2c 20 74 68 65 20 6e 75 6d 62  owever, the numb
9d00: 65 72 20 72 65 74 75 72 6e 65 64 20 64 6f 65 73  er returned does
9d10: 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 69 6e 20   not include in 
9d20: 63 68 61 6e 67 65 73 0a 2a 2a 20 63 61 75 73 65  changes.** cause
9d30: 64 20 62 79 20 73 75 62 74 72 69 67 67 65 72 73  d by subtriggers
9d40: 20 73 69 6e 63 65 20 74 68 65 79 20 68 61 76 65   since they have
9d50: 20 74 68 65 69 72 20 6f 77 6e 20 63 6f 6e 74 65   their own conte
9d60: 78 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  xt..**.** SQLite
9d70: 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20   implements the 
9d80: 63 6f 6d 6d 61 6e 64 20 22 44 45 4c 45 54 45 20  command "DELETE 
9d90: 46 52 4f 4d 20 74 61 62 6c 65 22 20 77 69 74 68  FROM table" with
9da0: 6f 75 74 0a 2a 2a 20 61 20 57 48 45 52 45 20 63  out.** a WHERE c
9db0: 6c 61 75 73 65 20 62 79 20 64 72 6f 70 70 69 6e  lause by droppin
9dc0: 67 20 61 6e 64 20 72 65 63 72 65 61 74 69 6e 67  g and recreating
9dd0: 20 74 68 65 20 74 61 62 6c 65 2e 20 20 28 54 68   the table.  (Th
9de0: 69 73 20 69 73 20 6d 75 63 68 0a 2a 2a 20 66 61  is is much.** fa
9df0: 73 74 65 72 20 74 68 61 6e 20 67 6f 69 6e 67 20  ster than going 
9e00: 74 68 72 6f 75 67 68 20 61 6e 64 20 64 65 6c 65  through and dele
9e10: 74 69 6e 67 20 69 6e 64 69 76 69 64 75 61 6c 20  ting individual 
9e20: 65 6c 65 6d 65 6e 74 73 20 66 72 6f 6d 20 74 68  elements from th
9e30: 65 0a 2a 2a 20 74 61 62 6c 65 2e 29 20 20 42 65  e.** table.)  Be
9e40: 63 61 75 73 65 20 6f 66 20 74 68 69 73 20 6f 70  cause of this op
9e50: 74 69 6d 69 7a 61 74 69 6f 6e 2c 20 74 68 65 20  timization, the 
9e60: 64 65 6c 65 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20  deletions in.** 
9e70: 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62  "DELETE FROM tab
9e80: 6c 65 22 20 61 72 65 20 6e 6f 74 20 72 6f 77 20  le" are not row 
9e90: 63 68 61 6e 67 65 73 20 61 6e 64 20 77 69 6c 6c  changes and will
9ea0: 20 6e 6f 74 20 62 65 20 63 6f 75 6e 74 65 64 0a   not be counted.
9eb0: 2a 2a 20 62 79 20 74 68 65 20 73 71 6c 69 74 65  ** by the sqlite
9ec0: 33 5f 63 68 61 6e 67 65 73 28 29 20 6f 72 20 5b  3_changes() or [
9ed0: 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
9ee0: 61 6e 67 65 73 28 29 5d 20 66 75 6e 63 74 69 6f  anges()] functio
9ef0: 6e 73 2e 0a 2a 2a 20 54 6f 20 67 65 74 20 61 6e  ns..** To get an
9f00: 20 61 63 63 75 72 61 74 65 20 63 6f 75 6e 74 20   accurate count 
9f10: 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  of the number of
9f20: 20 72 6f 77 73 20 64 65 6c 65 74 65 64 2c 20 75   rows deleted, u
9f30: 73 65 0a 2a 2a 20 22 44 45 4c 45 54 45 20 46 52  se.** "DELETE FR
9f40: 4f 4d 20 74 61 62 6c 65 20 57 48 45 52 45 20 31  OM table WHERE 1
9f50: 22 20 69 6e 73 74 65 61 64 2e 0a 2a 2a 0a 2a 2a  " instead..**.**
9f60: 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
9f70: 2a 2a 20 7b 46 31 32 32 34 31 7d 20 54 68 65 20  ** {F12241} The 
9f80: 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73  [sqlite3_changes
9f90: 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  ()] function ret
9fa0: 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
9fb0: 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  of.**          r
9fc0: 6f 77 20 63 68 61 6e 67 65 73 20 63 61 75 73 65  ow changes cause
9fd0: 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65  d by the most re
9fe0: 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44  cent INSERT, UPD
9ff0: 41 54 45 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ATE,.**         
a000: 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65   or DELETE state
a010: 6d 65 6e 74 20 6f 6e 20 74 68 65 20 73 61 6d 65  ment on the same
a020: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
a030: 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 20 20 20 20  tion and.**     
a040: 20 20 20 20 20 77 69 74 68 69 6e 20 74 68 65 20       within the 
a050: 73 61 6d 65 20 74 72 69 67 67 65 72 20 63 6f 6e  same trigger con
a060: 74 65 78 74 2c 20 6f 72 20 7a 65 72 6f 20 69 66  text, or zero if
a070: 20 74 68 65 72 65 20 68 61 76 65 0a 2a 2a 20 20   there have.**  
a080: 20 20 20 20 20 20 20 20 6e 6f 74 20 62 65 65 6e          not been
a090: 20 61 6e 79 20 71 75 61 6c 69 66 79 69 6e 67 20   any qualifying 
a0a0: 72 6f 77 20 63 68 61 6e 67 65 73 2e 0a 2a 2a 0a  row changes..**.
a0b0: 2a 2a 20 4c 49 4d 49 54 41 54 49 4f 4e 53 3a 0a  ** LIMITATIONS:.
a0c0: 2a 2a 0a 2a 2a 20 7b 55 31 32 32 35 32 7d 20 49  **.** {U12252} I
a0d0: 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72  f a separate thr
a0e0: 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65  ead makes change
a0f0: 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61  s on the same da
a100: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
a110: 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68  n.**          wh
a120: 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61  ile [sqlite3_cha
a130: 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69  nges()] is runni
a140: 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75  ng then the valu
a150: 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 20 20  e returned.**   
a160: 20 20 20 20 20 20 20 69 73 20 75 6e 70 72 65 64         is unpred
a170: 69 63 74 61 62 6c 65 20 61 6e 64 20 75 6e 6d 65  ictable and unme
a180: 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74  aningful..*/.int
a190: 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
a1a0: 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
a1b0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74  ** CAPI3REF: Tot
a1c0: 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77  al Number Of Row
a1d0: 73 20 4d 6f 64 69 66 69 65 64 20 7b 46 31 32 32  s Modified {F122
a1e0: 36 30 7d 0a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20  60}.***.** This 
a1f0: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
a200: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72   the number of r
a210: 6f 77 20 63 68 61 6e 67 65 73 20 63 61 75 73 65  ow changes cause
a220: 64 0a 2a 2a 20 62 79 20 49 4e 53 45 52 54 2c 20  d.** by INSERT, 
a230: 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45  UPDATE or DELETE
a240: 20 73 74 61 74 65 6d 65 6e 74 73 20 73 69 6e 63   statements sinc
a250: 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 68  e the database h
a260: 61 6e 64 6c 65 0a 2a 2a 20 77 61 73 20 6f 70 65  andle.** was ope
a270: 6e 65 64 2e 20 20 54 68 65 20 63 6f 75 6e 74 20  ned.  The count 
a280: 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 63 68 61  includes all cha
a290: 6e 67 65 73 20 66 72 6f 6d 20 61 6c 6c 20 74 72  nges from all tr
a2a0: 69 67 67 65 72 0a 2a 2a 20 63 6f 6e 74 65 78 74  igger.** context
a2b0: 73 2e 20 20 42 75 74 20 74 68 65 20 63 6f 75 6e  s.  But the coun
a2c0: 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75  t does not inclu
a2d0: 64 65 20 63 68 61 6e 67 65 73 20 75 73 65 64 20  de changes used 
a2e0: 74 6f 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20  to.** implement 
a2f0: 52 45 50 4c 41 43 45 20 63 6f 6e 73 74 72 61 69  REPLACE constrai
a300: 6e 74 73 2c 20 64 6f 20 72 6f 6c 6c 62 61 63 6b  nts, do rollback
a310: 73 20 6f 72 20 41 42 4f 52 54 20 70 72 6f 63 65  s or ABORT proce
a320: 73 73 69 6e 67 2c 0a 2a 2a 20 6f 72 20 44 52 4f  ssing,.** or DRO
a330: 50 20 74 61 62 6c 65 20 70 72 6f 63 65 73 73 69  P table processi
a340: 6e 67 2e 0a 2a 2a 20 54 68 65 20 63 68 61 6e 67  ng..** The chang
a350: 65 73 0a 2a 2a 20 61 72 65 20 63 6f 75 6e 74 65  es.** are counte
a360: 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65  d as soon as the
a370: 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20   statement that 
a380: 6d 61 6b 65 73 20 74 68 65 6d 20 69 73 20 63 6f  makes them is co
a390: 6d 70 6c 65 74 65 64 20 0a 2a 2a 20 28 77 68 65  mpleted .** (whe
a3a0: 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  n the statement 
a3b0: 68 61 6e 64 6c 65 20 69 73 20 70 61 73 73 65 64  handle is passed
a3c0: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
a3d0: 65 74 28 29 5d 20 6f 72 20 0a 2a 2a 20 5b 73 71  et()] or .** [sq
a3e0: 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
a3f0: 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  ])..**.** SQLite
a400: 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20   implements the 
a410: 63 6f 6d 6d 61 6e 64 20 22 44 45 4c 45 54 45 20  command "DELETE 
a420: 46 52 4f 4d 20 74 61 62 6c 65 22 20 77 69 74 68  FROM table" with
a430: 6f 75 74 0a 2a 2a 20 61 20 57 48 45 52 45 20 63  out.** a WHERE c
a440: 6c 61 75 73 65 20 62 79 20 64 72 6f 70 70 69 6e  lause by droppin
a450: 67 20 61 6e 64 20 72 65 63 72 65 61 74 69 6e 67  g and recreating
a460: 20 74 68 65 20 74 61 62 6c 65 2e 20 20 28 54 68   the table.  (Th
a470: 69 73 20 69 73 20 6d 75 63 68 0a 2a 2a 20 66 61  is is much.** fa
a480: 73 74 65 72 20 74 68 61 6e 20 67 6f 69 6e 67 0a  ster than going.
a490: 2a 2a 20 74 68 72 6f 75 67 68 20 61 6e 64 20 64  ** through and d
a4a0: 65 6c 65 74 69 6e 67 20 69 6e 64 69 76 69 64 75  eleting individu
a4b0: 61 6c 20 65 6c 65 6d 65 6e 74 73 20 66 6f 72 6d  al elements form
a4c0: 20 74 68 65 20 74 61 62 6c 65 2e 29 20 20 42 65   the table.)  Be
a4d0: 63 61 75 73 65 20 6f 66 0a 2a 2a 20 74 68 69 73  cause of.** this
a4e0: 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 2c 20 74   optimization, t
a4f0: 68 65 20 63 68 61 6e 67 65 20 63 6f 75 6e 74 20  he change count 
a500: 66 6f 72 20 22 44 45 4c 45 54 45 20 46 52 4f 4d  for "DELETE FROM
a510: 20 74 61 62 6c 65 22 20 77 69 6c 6c 20 62 65 0a   table" will be.
a520: 2a 2a 20 7a 65 72 6f 20 72 65 67 61 72 64 6c 65  ** zero regardle
a530: 73 73 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72  ss of the number
a540: 20 6f 66 20 65 6c 65 6d 65 6e 74 73 20 74 68 61   of elements tha
a550: 74 20 77 65 72 65 20 6f 72 69 67 69 6e 61 6c 6c  t were originall
a560: 79 20 69 6e 20 74 68 65 0a 2a 2a 20 74 61 62 6c  y in the.** tabl
a570: 65 2e 20 54 6f 20 67 65 74 20 61 6e 20 61 63 63  e. To get an acc
a580: 75 72 61 74 65 20 63 6f 75 6e 74 20 6f 66 20 74  urate count of t
a590: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77  he number of row
a5a0: 73 20 64 65 6c 65 74 65 64 2c 20 75 73 65 0a 2a  s deleted, use.*
a5b0: 2a 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74  * "DELETE FROM t
a5c0: 61 62 6c 65 20 57 48 45 52 45 20 31 22 20 69 6e  able WHERE 1" in
a5d0: 73 74 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  stead..**.** See
a5e0: 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74   also the [sqlit
a5f0: 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e  e3_changes()] in
a600: 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49  terface..**.** I
a610: 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 20 0a 2a  NVARIANTS:.** .*
a620: 2a 20 7b 46 31 32 32 36 31 7d 20 54 68 65 20 5b  * {F12261} The [
a630: 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
a640: 61 6e 67 65 73 28 29 5d 20 72 65 74 75 72 6e 73  anges()] returns
a650: 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65   the total numbe
a660: 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66  r.**          of
a670: 20 72 6f 77 20 63 68 61 6e 67 65 73 20 63 61 75   row changes cau
a680: 73 65 64 20 62 79 20 49 4e 53 45 52 54 2c 20 55  sed by INSERT, U
a690: 50 44 41 54 45 2c 20 61 6e 64 2f 6f 72 20 44 45  PDATE, and/or DE
a6a0: 4c 45 54 45 0a 2a 2a 20 20 20 20 20 20 20 20 20  LETE.**         
a6b0: 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 74   statements on t
a6c0: 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73  he same [databas
a6d0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 69  e connection], i
a6e0: 6e 20 61 6e 79 0a 2a 2a 20 20 20 20 20 20 20 20  n any.**        
a6f0: 20 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78    trigger contex
a700: 74 2c 20 73 69 6e 63 65 20 74 68 65 20 64 61 74  t, since the dat
a710: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
a720: 20 77 61 73 0a 2a 2a 20 20 20 20 20 20 20 20 20   was.**         
a730: 20 63 72 65 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20   created..**.** 
a740: 4c 49 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a  LIMITATIONS:.**.
a750: 2a 2a 20 7b 55 31 32 32 36 34 7d 20 49 66 20 61  ** {U12264} If a
a760: 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64   separate thread
a770: 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f   makes changes o
a780: 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  n the same datab
a790: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
a7a0: 2a 20 20 20 20 20 20 20 20 20 20 77 68 69 6c 65  *          while
a7b0: 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f   [sqlite3_total_
a7c0: 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75  changes()] is ru
a7d0: 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76  nning then the v
a7e0: 61 6c 75 65 20 0a 2a 2a 20 20 20 20 20 20 20 20  alue .**        
a7f0: 20 20 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e    returned is un
a800: 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20  predictable and 
a810: 75 6e 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f  unmeaningful..*/
a820: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f 74  .int sqlite3_tot
a830: 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74  al_changes(sqlit
a840: 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
a850: 49 33 52 45 46 3a 20 49 6e 74 65 72 72 75 70 74  I3REF: Interrupt
a860: 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20   A Long-Running 
a870: 51 75 65 72 79 20 7b 46 31 32 32 37 30 7d 0a 2a  Query {F12270}.*
a880: 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69  *.** This functi
a890: 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70 65  on causes any pe
a8a0: 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f  nding database o
a8b0: 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72  peration to abor
a8c0: 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20  t and.** return 
a8d0: 61 74 20 69 74 73 20 65 61 72 6c 69 65 73 74 20  at its earliest 
a8e0: 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69  opportunity. Thi
a8f0: 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70  s routine is typ
a900: 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64  ically.** called
a910: 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20   in response to 
a920: 61 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75  a user action su
a930: 63 68 20 61 73 20 70 72 65 73 73 69 6e 67 20 22  ch as pressing "
a940: 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74  Cancel".** or Ct
a950: 72 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20 75  rl-C where the u
a960: 73 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67  ser wants a long
a970: 20 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e   query operation
a980: 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65   to halt.** imme
a990: 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 49  diately..**.** I
a9a0: 74 20 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c  t is safe to cal
a9b0: 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66  l this routine f
a9c0: 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69 66  rom a thread dif
a9d0: 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a  ferent from the.
a9e0: 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74 20 69  ** thread that i
a9f0: 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e  s currently runn
aa00: 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65  ing the database
aa10: 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74   operation.  But
aa20: 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61   it.** is not sa
aa30: 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20  fe to call this 
aa40: 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20 64  routine with a d
aa50: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
aa60: 6f 6e 20 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c  on that.** is cl
aa70: 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20 63 6c  osed or might cl
aa80: 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c 69 74  ose before sqlit
aa90: 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72  e3_interrupt() r
aaa0: 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66  eturns..**.** If
aab0: 20 61 6e 20 53 51 4c 20 69 73 20 76 65 72 79 20   an SQL is very 
aac0: 6e 65 61 72 6c 79 20 66 69 6e 69 73 68 65 64 20  nearly finished 
aad0: 61 74 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e  at the time when
aae0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
aaf0: 70 74 28 29 0a 2a 2a 20 69 73 20 63 61 6c 6c 65  pt().** is calle
ab00: 64 2c 20 74 68 65 6e 20 69 74 20 6d 69 67 68 74  d, then it might
ab10: 20 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f 70 70   not have an opp
ab20: 6f 72 74 75 6e 69 74 79 20 74 6f 20 62 65 20 69  ortunity to be i
ab30: 6e 74 65 72 72 75 70 74 65 64 2e 0a 2a 2a 20 49  nterrupted..** I
ab40: 74 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75 65  t might continue
ab50: 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a   to completion..
ab60: 2a 2a 20 41 6e 20 53 51 4c 20 6f 70 65 72 61 74  ** An SQL operat
ab70: 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74 65  ion that is inte
ab80: 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65 74  rrupted will ret
ab90: 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  urn.** [SQLITE_I
aba0: 4e 54 45 52 52 55 50 54 5d 2e 20 20 49 66 20 74  NTERRUPT].  If t
abb0: 68 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 53  he interrupted S
abc0: 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  QL operation is 
abd0: 61 6e 0a 2a 2a 20 49 4e 53 45 52 54 2c 20 55 50  an.** INSERT, UP
abe0: 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 20  DATE, or DELETE 
abf0: 74 68 61 74 20 69 73 20 69 6e 73 69 64 65 20 61  that is inside a
ac00: 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73  n explicit trans
ac10: 61 63 74 69 6f 6e 2c 20 0a 2a 2a 20 74 68 65 6e  action, .** then
ac20: 20 74 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e   the entire tran
ac30: 73 61 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20  saction will be 
ac40: 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f  rolled back auto
ac50: 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 20 41 20  matically..** A 
ac60: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
ac70: 69 6e 74 65 72 72 75 70 74 28 29 20 68 61 73 20  interrupt() has 
ac80: 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c  no effect on SQL
ac90: 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74   statements.** t
aca0: 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20  hat are started 
acb0: 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 69 6e  after sqlite3_in
acc0: 74 65 72 72 75 70 74 28 29 20 72 65 74 75 72 6e  terrupt() return
acd0: 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  s..**.** INVARIA
ace0: 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32  NTS:.**.** {F122
acf0: 37 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  71} The [sqlite3
ad00: 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 20 69 6e  _interrupt()] in
ad10: 74 65 72 66 61 63 65 20 77 69 6c 6c 20 66 6f 72  terface will for
ad20: 63 65 20 61 6c 6c 20 72 75 6e 6e 69 6e 67 0a 2a  ce all running.*
ad30: 2a 20 20 20 20 20 20 20 20 20 20 53 51 4c 20 73  *          SQL s
ad40: 74 61 74 65 6d 65 6e 74 73 20 61 73 73 6f 63 69  tatements associ
ad50: 61 74 65 64 20 77 69 74 68 20 74 68 65 20 73 61  ated with the sa
ad60: 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
ad70: 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20  ection.**       
ad80: 20 20 20 74 6f 20 68 61 6c 74 20 61 66 74 65 72     to halt after
ad90: 20 70 72 6f 63 65 73 73 69 6e 67 20 61 74 20 6d   processing at m
ada0: 6f 73 74 20 6f 6e 65 20 61 64 64 69 74 69 6f 6e  ost one addition
adb0: 61 6c 20 72 6f 77 20 6f 66 0a 2a 2a 20 20 20 20  al row of.**    
adc0: 20 20 20 20 20 20 64 61 74 61 2e 0a 2a 2a 0a 2a        data..**.*
add0: 2a 20 7b 46 31 32 32 37 32 7d 20 41 6e 79 20 53  * {F12272} Any S
ade0: 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61  QL statement tha
adf0: 74 20 69 73 20 69 6e 74 65 72 72 75 70 74 65 64  t is interrupted
ae00: 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74   by [sqlite3_int
ae10: 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 20 20 20  errupt()].**    
ae20: 20 20 20 20 20 20 77 69 6c 6c 20 72 65 74 75 72        will retur
ae30: 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  n [SQLITE_INTERR
ae40: 55 50 54 5d 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49  UPT]..**.** LIMI
ae50: 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b  TATIONS:.**.** {
ae60: 55 31 32 32 37 39 7d 20 49 66 20 74 68 65 20 64  U12279} If the d
ae70: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
ae80: 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c 65 20  on closes while 
ae90: 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75  [sqlite3_interru
aea0: 70 74 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  pt()].**        
aeb0: 20 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65    is running the
aec0: 6e 20 62 61 64 20 74 68 69 6e 67 73 20 77 69 6c  n bad things wil
aed0: 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e  l likely happen.
aee0: 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
aef0: 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69 74  _interrupt(sqlit
af00: 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
af10: 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65  I3REF: Determine
af20: 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65   If An SQL State
af30: 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 65  ment Is Complete
af40: 20 7b 46 31 30 35 31 30 7d 0a 2a 2a 0a 2a 2a 20   {F10510}.**.** 
af50: 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
af60: 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f  re useful for co
af70: 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74  mmand-line input
af80: 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 69 66   to determine if
af90: 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c   the.** currentl
afa0: 79 20 65 6e 74 65 72 65 64 20 74 65 78 74 20 73  y entered text s
afb0: 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20 63 6f 6d  eems to form com
afc0: 70 6c 65 74 65 20 61 20 53 51 4c 20 73 74 61 74  plete a SQL stat
afd0: 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61  ement or.** if a
afe0: 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20  dditional input 
aff0: 69 73 20 6e 65 65 64 65 64 20 62 65 66 6f 72 65  is needed before
b000: 20 73 65 6e 64 69 6e 67 20 74 68 65 20 74 65 78   sending the tex
b010: 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65  t into.** SQLite
b020: 20 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 20 54   for parsing.  T
b030: 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
b040: 74 75 72 6e 20 74 72 75 65 20 69 66 20 74 68 65  turn true if the
b050: 20 69 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a   input string.**
b060: 20 61 70 70 65 61 72 73 20 74 6f 20 62 65 20 61   appears to be a
b070: 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74   complete SQL st
b080: 61 74 65 6d 65 6e 74 2e 20 20 41 20 73 74 61 74  atement.  A stat
b090: 65 6d 65 6e 74 20 69 73 20 6a 75 64 67 65 64 20  ement is judged 
b0a0: 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74  to be.** complet
b0b0: 65 20 69 66 20 69 74 20 65 6e 64 73 20 77 69 74  e if it ends wit
b0c0: 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f  h a semicolon to
b0d0: 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20 61  ken and is not a
b0e0: 20 66 72 61 67 6d 65 6e 74 20 6f 66 20 61 0a 2a   fragment of a.*
b0f0: 2a 20 43 52 45 41 54 45 20 54 52 49 47 47 45 52  * CREATE TRIGGER
b100: 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 53 65 6d   statement.  Sem
b110: 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65  icolons that are
b120: 20 65 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e   embedded within
b130: 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72  .** string liter
b140: 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64  als or quoted id
b150: 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f  entifier names o
b160: 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e  r comments are n
b170: 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e  ot.** independen
b180: 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61  t tokens (they a
b190: 72 65 20 70 61 72 74 20 6f 66 20 74 68 65 20 74  re part of the t
b1a0: 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68  oken in which th
b1b0: 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64  ey are.** embedd
b1c0: 65 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20  ed) and thus do 
b1d0: 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73  not count as a s
b1e0: 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61  tatement termina
b1f0: 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  tor..**.** These
b200: 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74   routines do not
b210: 20 70 61 72 73 65 20 74 68 65 20 53 51 4c 20 61   parse the SQL a
b220: 6e 64 0a 2a 2a 20 73 6f 20 77 69 6c 6c 20 6e 6f  nd.** so will no
b230: 74 20 64 65 74 65 63 74 20 73 79 6e 74 61 63 74  t detect syntact
b240: 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63 74  ically incorrect
b250: 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41   SQL..**.** INVA
b260: 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  RIANTS:.**.** {F
b270: 31 30 35 31 31 7d 20 54 68 65 20 73 71 6c 69 74  10511} The sqlit
b280: 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 20 61 6e  e3_complete() an
b290: 64 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  d sqlite3_comple
b2a0: 74 65 31 36 28 29 20 66 75 6e 63 74 69 6f 6e 73  te16() functions
b2b0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74  .**          ret
b2c0: 75 72 6e 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65  urn true (non-ze
b2d0: 72 6f 29 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20  ro) if and only 
b2e0: 69 66 20 74 68 65 20 6c 61 73 74 0a 2a 2a 20 20  if the last.**  
b2f0: 20 20 20 20 20 20 20 20 6e 6f 6e 2d 77 68 69 74          non-whit
b300: 65 73 70 61 63 65 20 74 6f 6b 65 6e 20 69 6e 20  espace token in 
b310: 74 68 65 69 72 20 69 6e 70 75 74 20 69 73 20 61  their input is a
b320: 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 68 61 74 0a   semicolon that.
b330: 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 6e  **          is n
b340: 6f 74 20 69 6e 20 62 65 74 77 65 65 6e 20 74 68  ot in between th
b350: 65 20 42 45 47 49 4e 20 61 6e 64 20 45 4e 44 20  e BEGIN and END 
b360: 6f 66 20 61 20 43 52 45 41 54 45 20 54 52 49 47  of a CREATE TRIG
b370: 47 45 52 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  GER.**          
b380: 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a  statement..**.**
b390: 20 4c 49 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a   LIMITATIONS:.**
b3a0: 0a 2a 2a 20 7b 55 31 30 35 31 32 7d 20 54 68 65  .** {U10512} The
b3b0: 20 69 6e 70 75 74 20 74 6f 20 73 71 6c 69 74 65   input to sqlite
b3c0: 33 5f 63 6f 6d 70 6c 65 74 65 28 29 20 6d 75 73  3_complete() mus
b3d0: 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d  t be a zero-term
b3e0: 69 6e 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20  inated.**       
b3f0: 20 20 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e     UTF-8 string.
b400: 0a 2a 2a 0a 2a 2a 20 7b 55 31 30 35 31 33 7d 20  .**.** {U10513} 
b410: 54 68 65 20 69 6e 70 75 74 20 74 6f 20 73 71 6c  The input to sql
b420: 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
b430: 29 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f  ) must be a zero
b440: 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 20  -terminated.**  
b450: 20 20 20 20 20 20 20 20 55 54 46 2d 31 36 20 73          UTF-16 s
b460: 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20  tring in native 
b470: 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69  byte order..*/.i
b480: 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  nt sqlite3_compl
b490: 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a  ete(const char *
b4a0: 73 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  sql);.int sqlite
b4b0: 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e  3_complete16(con
b4c0: 73 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a  st void *sql);..
b4d0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
b4e0: 52 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62  Register A Callb
b4f0: 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51  ack To Handle SQ
b500: 4c 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73  LITE_BUSY Errors
b510: 20 7b 46 31 32 33 31 30 7d 0a 2a 2a 0a 2a 2a 20   {F12310}.**.** 
b520: 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 64 65  This routine ide
b530: 6e 74 69 66 69 65 73 20 61 20 63 61 6c 6c 62 61  ntifies a callba
b540: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74  ck function that
b550: 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 69 6e 76   might be.** inv
b560: 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 6e  oked whenever an
b570: 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65   attempt is made
b580: 20 74 6f 20 6f 70 65 6e 20 61 20 64 61 74 61 62   to open a datab
b590: 61 73 65 20 74 61 62 6c 65 20 0a 2a 2a 20 74 68  ase table .** th
b5a0: 61 74 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61  at another threa
b5b0: 64 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73  d or process has
b5c0: 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 20 49 66 20 74   locked..** If t
b5d0: 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  he busy callback
b5e0: 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b   is NULL, then [
b5f0: 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20  SQLITE_BUSY].** 
b600: 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  or [SQLITE_IOERR
b610: 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69 73 20  _BLOCKED].** is 
b620: 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61  returned immedia
b630: 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e  tely upon encoun
b640: 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e  tering the lock.
b650: 0a 2a 2a 20 49 66 20 74 68 65 20 62 75 73 79 20  .** If the busy 
b660: 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20  callback is not 
b670: 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 0a 2a  NULL, then the.*
b680: 2a 20 63 61 6c 6c 62 61 63 6b 20 77 69 6c 6c 20  * callback will 
b690: 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  be invoked with 
b6a0: 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 20 20  two arguments.  
b6b0: 54 68 65 0a 2a 2a 20 66 69 72 73 74 20 61 72 67  The.** first arg
b6c0: 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 68 61 6e  ument to the han
b6d0: 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f  dler is a copy o
b6e0: 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e  f the void* poin
b6f0: 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  ter which.** is 
b700: 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  the third argume
b710: 6e 74 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69  nt to this routi
b720: 6e 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ne.  The second 
b730: 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74  argument to.** t
b740: 68 65 20 68 61 6e 64 6c 65 72 20 69 73 20 74 68  he handler is th
b750: 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65  e number of time
b760: 73 20 74 68 61 74 20 74 68 65 20 62 75 73 79 20  s that the busy 
b770: 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62  handler has.** b
b780: 65 65 6e 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20  een invoked for 
b790: 74 68 69 73 20 6c 6f 63 6b 69 6e 67 20 65 76 65  this locking eve
b7a0: 6e 74 2e 20 20 20 49 66 20 74 68 65 0a 2a 2a 20  nt.   If the.** 
b7b0: 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 72 65  busy callback re
b7c0: 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f  turns 0, then no
b7d0: 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74 74 65   additional atte
b7e0: 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20 74 6f  mpts are made to
b7f0: 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65 20 64  .** access the d
b800: 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53 51 4c  atabase and [SQL
b810: 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51  ITE_BUSY] or [SQ
b820: 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
b830: 45 44 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ED] is returned.
b840: 0a 2a 2a 20 49 66 20 74 68 65 20 63 61 6c 6c 62  .** If the callb
b850: 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  ack returns non-
b860: 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68  zero, then anoth
b870: 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73  er attempt.** is
b880: 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 74 68   made to open th
b890: 65 20 64 61 74 61 62 61 73 65 20 66 6f 72 20 72  e database for r
b8a0: 65 61 64 69 6e 67 20 61 6e 64 20 74 68 65 20 63  eading and the c
b8b0: 79 63 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a  ycle repeats..**
b8c0: 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 6e 63 65  .** The presence
b8d0: 20 6f 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c   of a busy handl
b8e0: 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 75 61 72  er does not guar
b8f0: 61 6e 74 65 65 20 74 68 61 74 0a 2a 2a 20 69 74  antee that.** it
b900: 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64   will be invoked
b910: 20 77 68 65 6e 20 74 68 65 72 65 20 69 73 20 6c   when there is l
b920: 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 0a  ock contention..
b930: 2a 2a 20 49 66 20 53 51 4c 69 74 65 20 64 65 74  ** If SQLite det
b940: 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76  ermines that inv
b950: 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 20 68  oking the busy h
b960: 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72 65 73  andler could res
b970: 75 6c 74 20 69 6e 0a 2a 2a 20 61 20 64 65 61 64  ult in.** a dead
b980: 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f  lock, it will go
b990: 20 61 68 65 61 64 20 61 6e 64 20 72 65 74 75 72   ahead and retur
b9a0: 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  n [SQLITE_BUSY] 
b9b0: 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f  or.** [SQLITE_IO
b9c0: 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e 73  ERR_BLOCKED] ins
b9d0: 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67  tead of invoking
b9e0: 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 68 61 6e   the.** busy han
b9f0: 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65  dler..** Conside
ba00: 72 20 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65  r a scenario whe
ba10: 72 65 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69  re one process i
ba20: 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64  s holding a read
ba30: 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74   lock that.** it
ba40: 20 69 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72   is trying to pr
ba50: 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72  omote to a reser
ba60: 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20  ved lock and.** 
ba70: 61 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73  a second process
ba80: 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65   is holding a re
ba90: 73 65 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74  served lock that
baa0: 20 69 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a   it is trying.**
bab0: 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61   to promote to a
bac0: 6e 20 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b  n exclusive lock
bad0: 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 72 6f  .  The first pro
bae0: 63 65 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63  cess cannot proc
baf0: 65 65 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69  eed.** because i
bb00: 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20  t is blocked by 
bb10: 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74  the second and t
bb20: 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73  he second proces
bb30: 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63  s cannot.** proc
bb40: 65 65 64 20 62 65 63 61 75 73 65 20 69 74 20 69  eed because it i
bb50: 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65  s blocked by the
bb60: 20 66 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68   first.  If both
bb70: 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e   processes.** in
bb80: 76 6f 6b 65 20 74 68 65 20 62 75 73 79 20 68 61  voke the busy ha
bb90: 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20  ndlers, neither 
bba0: 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72  will make any pr
bbb0: 6f 67 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f  ogress.  Therefo
bbc0: 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65  re,.** SQLite re
bbd0: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55  turns [SQLITE_BU
bbe0: 53 59 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73  SY] for the firs
bbf0: 74 20 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e  t process, hopin
bc00: 67 20 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77  g that this.** w
bc10: 69 6c 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66  ill induce the f
bc20: 69 72 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20  irst process to 
bc30: 72 65 6c 65 61 73 65 20 69 74 73 20 72 65 61 64  release its read
bc40: 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a   lock and allow.
bc50: 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72  ** the second pr
bc60: 6f 63 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64  ocess to proceed
bc70: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61  ..**.** The defa
bc80: 75 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63  ult busy callbac
bc90: 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  k is NULL..**.**
bca0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 42 55 53   The [SQLITE_BUS
bcb0: 59 5d 20 65 72 72 6f 72 20 69 73 20 63 6f 6e 76  Y] error is conv
bcc0: 65 72 74 65 64 20 74 6f 20 5b 53 51 4c 49 54 45  erted to [SQLITE
bcd0: 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a  _IOERR_BLOCKED].
bce0: 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69  ** when SQLite i
bcf0: 73 20 69 6e 20 74 68 65 20 6d 69 64 64 6c 65 20  s in the middle 
bd00: 6f 66 20 61 20 6c 61 72 67 65 20 74 72 61 6e 73  of a large trans
bd10: 61 63 74 69 6f 6e 20 77 68 65 72 65 20 61 6c 6c  action where all
bd20: 20 74 68 65 0a 2a 2a 20 63 68 61 6e 67 65 73 20   the.** changes 
bd30: 77 69 6c 6c 20 6e 6f 74 20 66 69 74 20 69 6e 74  will not fit int
bd40: 6f 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 20  o the in-memory 
bd50: 63 61 63 68 65 2e 20 20 53 51 4c 69 74 65 20 77  cache.  SQLite w
bd60: 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64 79 20 68  ill.** already h
bd70: 6f 6c 64 20 61 20 52 45 53 45 52 56 45 44 20 6c  old a RESERVED l
bd80: 6f 63 6b 20 6f 6e 20 74 68 65 20 64 61 74 61 62  ock on the datab
bd90: 61 73 65 20 66 69 6c 65 2c 20 62 75 74 20 69 74  ase file, but it
bda0: 20 6e 65 65 64 73 0a 2a 2a 20 74 6f 20 70 72 6f   needs.** to pro
bdb0: 6d 6f 74 65 20 74 68 69 73 20 6c 6f 63 6b 20 74  mote this lock t
bdc0: 6f 20 45 58 43 4c 55 53 49 56 45 20 73 6f 20 74  o EXCLUSIVE so t
bdd0: 68 61 74 20 69 74 20 63 61 6e 20 73 70 69 6c 6c  hat it can spill
bde0: 20 63 61 63 68 65 0a 2a 2a 20 70 61 67 65 73 20   cache.** pages 
bdf0: 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  into the databas
be00: 65 20 66 69 6c 65 20 77 69 74 68 6f 75 74 20 68  e file without h
be10: 61 72 6d 20 74 6f 20 63 6f 6e 63 75 72 72 65 6e  arm to concurren
be20: 74 0a 2a 2a 20 72 65 61 64 65 72 73 2e 20 20 49  t.** readers.  I
be30: 66 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74  f it is unable t
be40: 6f 20 70 72 6f 6d 6f 74 65 20 74 68 65 20 6c 6f  o promote the lo
be50: 63 6b 2c 20 74 68 65 6e 20 74 68 65 20 69 6e 2d  ck, then the in-
be60: 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61 63 68 65 20  memory.** cache 
be70: 77 69 6c 6c 20 62 65 20 6c 65 66 74 20 69 6e 20  will be left in 
be80: 61 6e 20 69 6e 63 6f 6e 73 69 73 74 65 6e 74 20  an inconsistent 
be90: 73 74 61 74 65 20 61 6e 64 20 73 6f 20 74 68 65  state and so the
bea0: 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 69   error.** code i
beb0: 73 20 70 72 6f 6d 6f 74 65 64 20 66 72 6f 6d 20  s promoted from 
bec0: 74 68 65 20 72 65 6c 61 74 69 76 65 6c 79 20 62  the relatively b
bed0: 65 6e 69 67 6e 20 5b 53 51 4c 49 54 45 5f 42 55  enign [SQLITE_BU
bee0: 53 59 5d 20 74 6f 0a 2a 2a 20 74 68 65 20 6d 6f  SY] to.** the mo
bef0: 72 65 20 73 65 76 65 72 65 20 5b 53 51 4c 49 54  re severe [SQLIT
bf00: 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
bf10: 2e 20 20 54 68 69 73 20 65 72 72 6f 72 20 63 6f  .  This error co
bf20: 64 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20  de promotion.** 
bf30: 66 6f 72 63 65 73 20 61 6e 20 61 75 74 6f 6d 61  forces an automa
bf40: 74 69 63 20 72 6f 6c 6c 62 61 63 6b 20 6f 66 20  tic rollback of 
bf50: 74 68 65 20 63 68 61 6e 67 65 73 2e 20 20 53 65  the changes.  Se
bf60: 65 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66  e the.** <a href
bf70: 3d 22 68 74 74 70 3a 2f 2f 77 77 77 2e 73 71 6c  ="http://www.sql
bf80: 69 74 65 2e 6f 72 67 2f 63 76 73 74 72 61 63 2f  ite.org/cvstrac/
bf90: 77 69 6b 69 3f 70 3d 43 6f 72 72 75 70 74 69 6f  wiki?p=Corruptio
bfa0: 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72  nFollowingBusyEr
bfb0: 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72 75 70 74  ror">.** Corrupt
bfc0: 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79  ionFollowingBusy
bfd0: 45 72 72 6f 72 3c 2f 61 3e 20 77 69 6b 69 20 70  Error</a> wiki p
bfe0: 61 67 65 20 66 6f 72 20 61 20 64 69 73 63 75 73  age for a discus
bff0: 73 69 6f 6e 20 6f 66 20 77 68 79 0a 2a 2a 20 74  sion of why.** t
c000: 68 69 73 20 69 73 20 69 6d 70 6f 72 74 61 6e 74  his is important
c010: 2e 0a 2a 2a 09 0a 2a 2a 20 54 68 65 72 65 20 63  ..**..** There c
c020: 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e  an only be a sin
c030: 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  gle busy handler
c040: 20 64 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63   defined for eac
c050: 68 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  h database.** co
c060: 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65 74 74 69  nnection.  Setti
c070: 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20 68 61  ng a new busy ha
c080: 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79  ndler clears any
c090: 20 70 72 65 76 69 6f 75 73 20 6f 6e 65 2e 20 0a   previous one. .
c0a0: 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 63 61 6c  ** Note that cal
c0b0: 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75  ling [sqlite3_bu
c0c0: 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 77 69  sy_timeout()] wi
c0d0: 6c 6c 20 61 6c 73 6f 20 73 65 74 20 6f 72 20 63  ll also set or c
c0e0: 6c 65 61 72 0a 2a 2a 20 74 68 65 20 62 75 73 79  lear.** the busy
c0f0: 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20   handler..**.** 
c100: 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
c110: 2a 20 7b 46 31 32 33 31 31 7d 20 54 68 65 20 5b  * {F12311} The [
c120: 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
c130: 64 6c 65 72 28 29 5d 20 66 75 6e 63 74 69 6f 6e  dler()] function
c140: 20 72 65 70 6c 61 63 65 73 20 74 68 65 20 62 75   replaces the bu
c150: 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 20 20  sy handler.**   
c160: 20 20 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 20         callback 
c170: 69 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  in the database 
c180: 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 64 65 6e 74  connection ident
c190: 69 66 69 65 64 20 62 79 20 74 68 65 20 31 73 74  ified by the 1st
c1a0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 61 72  .**          par
c1b0: 61 6d 65 74 65 72 20 77 69 74 68 20 61 20 6e 65  ameter with a ne
c1c0: 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69  w busy handler i
c1d0: 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65  dentified by the
c1e0: 20 32 6e 64 20 61 6e 64 20 33 72 64 0a 2a 2a 20   2nd and 3rd.** 
c1f0: 20 20 20 20 20 20 20 20 20 70 61 72 61 6d 65 74           paramet
c200: 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33  ers..**.** {F123
c210: 31 32 7d 20 54 68 65 20 64 65 66 61 75 6c 74 20  12} The default 
c220: 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72  busy handler for
c230: 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f   new database co
c240: 6e 6e 65 63 74 69 6f 6e 73 20 69 73 20 4e 55 4c  nnections is NUL
c250: 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 31 34  L..**.** {F12314
c260: 7d 20 57 68 65 6e 20 74 77 6f 20 6f 72 20 6d 6f  } When two or mo
c270: 72 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  re database conn
c280: 65 63 74 69 6f 6e 20 73 68 61 72 65 20 61 20 63  ection share a c
c290: 6f 6d 6d 6f 6e 20 63 61 63 68 65 2c 0a 2a 2a 20  ommon cache,.** 
c2a0: 20 20 20 20 20 20 20 20 20 74 68 65 20 62 75 73           the bus
c2b0: 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 74 68  y handler for th
c2c0: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
c2d0: 63 74 69 6f 6e 20 63 75 72 72 65 6e 74 6c 79 20  ction currently 
c2e0: 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20  using.**        
c2f0: 20 20 74 68 65 20 63 61 63 68 65 20 69 73 20 69    the cache is i
c300: 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 20  nvoked when the 
c310: 63 61 63 68 65 20 65 6e 63 6f 75 6e 74 65 72 73  cache encounters
c320: 20 61 20 6c 6f 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b   a lock..**.** {
c330: 46 31 32 33 31 36 7d 20 49 66 20 61 20 62 75 73  F12316} If a bus
c340: 79 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61  y handler callba
c350: 63 6b 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c  ck returns zero,
c360: 20 74 68 65 6e 20 74 68 65 20 53 51 4c 69 74 65   then the SQLite
c370: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74  .**          int
c380: 65 72 66 61 63 65 20 74 68 61 74 20 70 72 6f 76  erface that prov
c390: 6f 6b 65 64 20 74 68 65 20 6c 6f 63 6b 69 6e 67  oked the locking
c3a0: 20 65 76 65 6e 74 20 77 69 6c 6c 20 72 65 74 75   event will retu
c3b0: 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  rn.**          [
c3c0: 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a  SQLITE_BUSY]..**
c3d0: 0a 2a 2a 20 7b 46 31 32 33 31 38 7d 20 53 51 4c  .** {F12318} SQL
c3e0: 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 73  ite will invokes
c3f0: 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
c400: 72 20 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d  r with two argum
c410: 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 20 20 20  ent which.**    
c420: 20 20 20 20 20 20 61 72 65 20 61 20 63 6f 70 79        are a copy
c430: 20 6f 66 20 74 68 65 20 70 6f 69 6e 74 65 72 20   of the pointer 
c440: 73 75 70 70 6c 69 65 64 20 62 79 20 74 68 65 20  supplied by the 
c450: 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
c460: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
c470: 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
c480: 65 72 28 29 5d 20 61 6e 64 20 61 20 63 6f 75 6e  er()] and a coun
c490: 74 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20  t of the number 
c4a0: 6f 66 20 70 72 69 6f 72 0a 2a 2a 20 20 20 20 20  of prior.**     
c4b0: 20 20 20 20 20 69 6e 76 6f 63 61 74 69 6f 6e 73       invocations
c4c0: 20 6f 66 20 74 68 65 20 62 75 73 79 20 68 61 6e   of the busy han
c4d0: 64 6c 65 72 20 66 6f 72 20 74 68 65 20 73 61 6d  dler for the sam
c4e0: 65 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e  e locking event.
c4f0: 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49 54 41 54 49 4f  .**.** LIMITATIO
c500: 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 55 31 32 33 31  NS:.**.** {U1231
c510: 39 7d 20 41 20 62 75 73 79 20 68 61 6e 64 6c 65  9} A busy handle
c520: 72 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c  r should not cal
c530: 6c 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61  l close the data
c540: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
c550: 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 70  **          or p
c560: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
c570: 74 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  t that invoked t
c580: 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e  he busy handler.
c590: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
c5a0: 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c  busy_handler(sql
c5b0: 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f  ite3*, int(*)(vo
c5c0: 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64 2a 29  id*,int), void*)
c5d0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
c5e0: 46 3a 20 53 65 74 20 41 20 42 75 73 79 20 54 69  F: Set A Busy Ti
c5f0: 6d 65 6f 75 74 20 7b 46 31 32 33 34 30 7d 0a 2a  meout {F12340}.*
c600: 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
c610: 65 20 73 65 74 73 20 61 20 5b 73 71 6c 69 74 65  e sets a [sqlite
c620: 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c  3_busy_handler |
c630: 20 62 75 73 79 20 68 61 6e 64 6c 65 72 5d 0a 2a   busy handler].*
c640: 2a 20 74 68 61 74 20 73 6c 65 65 70 73 20 66 6f  * that sleeps fo
c650: 72 20 61 20 77 68 69 6c 65 20 77 68 65 6e 20 61  r a while when a
c660: 0a 2a 2a 20 74 61 62 6c 65 20 69 73 20 6c 6f 63  .** table is loc
c670: 6b 65 64 2e 20 20 54 68 65 20 68 61 6e 64 6c 65  ked.  The handle
c680: 72 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c  r will sleep mul
c690: 74 69 70 6c 65 20 74 69 6d 65 73 20 75 6e 74 69  tiple times unti
c6a0: 6c 20 0a 2a 2a 20 61 74 20 6c 65 61 73 74 20 22  l .** at least "
c6b0: 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73  ms" milliseconds
c6c0: 20 6f 66 20 73 6c 65 65 70 69 6e 67 20 68 61 76   of sleeping hav
c6d0: 65 20 62 65 65 6e 20 64 6f 6e 65 2e 20 7b 46 31  e been done. {F1
c6e0: 32 33 34 33 7d 20 41 66 74 65 72 0a 2a 2a 20 22  2343} After.** "
c6f0: 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73  ms" milliseconds
c700: 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c 20 74 68   of sleeping, th
c710: 65 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e  e handler return
c720: 73 20 30 20 77 68 69 63 68 0a 2a 2a 20 63 61 75  s 0 which.** cau
c730: 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ses [sqlite3_ste
c740: 70 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 20 5b  p()] to return [
c750: 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20  SQLITE_BUSY] or 
c760: 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
c770: 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 43 61  OCKED]..**.** Ca
c780: 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69  lling this routi
c790: 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67 75 6d  ne with an argum
c7a0: 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 6f 72  ent less than or
c7b0: 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a   equal to zero.*
c7c0: 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20  * turns off all 
c7d0: 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a  busy handlers..*
c7e0: 2a 0a 2a 2a 20 54 68 65 72 65 20 63 61 6e 20 6f  *.** There can o
c7f0: 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20  nly be a single 
c800: 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72  busy handler for
c810: 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 64 61   a particular da
c820: 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
c830: 74 69 6f 6e 2e 20 20 49 66 20 61 6e 6f 74 68 65  tion.  If anothe
c840: 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 77  r busy handler w
c850: 61 73 20 64 65 66 69 6e 65 64 20 20 0a 2a 2a 20  as defined  .** 
c860: 28 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  (using [sqlite3_
c870: 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29  busy_handler()])
c880: 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e   prior to callin
c890: 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e  g.** this routin
c8a0: 65 2c 20 74 68 61 74 20 6f 74 68 65 72 20 62 75  e, that other bu
c8b0: 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c  sy handler is cl
c8c0: 65 61 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  eared..**.** INV
c8d0: 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
c8e0: 46 31 32 33 34 31 7d 20 54 68 65 20 5b 73 71 6c  F12341} The [sql
c8f0: 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
c900: 74 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 6f 76  t()] function ov
c910: 65 72 72 69 64 65 73 20 61 6e 79 20 70 72 69 6f  errides any prio
c920: 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  r.**          [s
c930: 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65  qlite3_busy_time
c940: 6f 75 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  out()] or [sqlit
c950: 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
c960: 29 5d 20 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20  )] setting.**   
c970: 20 20 20 20 20 20 20 6f 6e 20 74 68 65 20 73 61         on the sa
c980: 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
c990: 65 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46  ection..**.** {F
c9a0: 31 32 33 34 33 7d 20 49 66 20 74 68 65 20 32 6e  12343} If the 2n
c9b0: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  d parameter to [
c9c0: 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d  sqlite3_busy_tim
c9d0: 65 6f 75 74 28 29 5d 20 69 73 20 6c 65 73 73 20  eout()] is less 
c9e0: 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  than.**         
c9f0: 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72   or equal to zer
ca00: 6f 2c 20 74 68 65 6e 20 74 68 65 20 62 75 73 79  o, then the busy
ca10: 20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61   handler is clea
ca20: 72 65 64 20 73 6f 20 74 68 61 74 0a 2a 2a 20 20  red so that.**  
ca30: 20 20 20 20 20 20 20 20 61 6c 6c 20 73 75 62 73          all subs
ca40: 65 71 75 65 6e 74 20 6c 6f 63 6b 69 6e 67 20 65  equent locking e
ca50: 76 65 6e 74 73 20 69 6d 6d 65 64 69 61 74 65 6c  vents immediatel
ca60: 79 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  y return [SQLITE
ca70: 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46  _BUSY]..**.** {F
ca80: 31 32 33 34 34 7d 20 49 66 20 74 68 65 20 32 6e  12344} If the 2n
ca90: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  d parameter to [
caa0: 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d  sqlite3_busy_tim
cab0: 65 6f 75 74 28 29 5d 20 69 73 20 61 20 70 6f 73  eout()] is a pos
cac0: 69 74 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20  itive.**        
cad0: 20 20 6e 75 6d 62 65 72 20 4e 2c 20 74 68 65 6e    number N, then
cae0: 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20   a busy handler 
caf0: 69 73 20 73 65 74 20 74 68 61 74 20 72 65 70 65  is set that repe
cb00: 61 74 65 64 6c 79 20 63 61 6c 6c 73 0a 2a 2a 20  atedly calls.** 
cb10: 20 20 20 20 20 20 20 20 20 74 68 65 20 78 53 6c           the xSl
cb20: 65 65 70 28 29 20 6d 65 74 68 6f 64 20 69 6e 20  eep() method in 
cb30: 74 68 65 20 56 46 53 20 69 6e 74 65 72 66 61 63  the VFS interfac
cb40: 65 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74  e until either t
cb50: 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6c  he.**          l
cb60: 6f 63 6b 20 63 6c 65 61 72 73 20 6f 72 20 75 6e  ock clears or un
cb70: 74 69 6c 20 74 68 65 20 63 75 6d 75 6c 61 74 69  til the cumulati
cb80: 76 65 20 73 6c 65 65 70 20 74 69 6d 65 20 72 65  ve sleep time re
cb90: 70 6f 72 74 65 64 20 62 61 63 6b 0a 2a 2a 20 20  ported back.**  
cba0: 20 20 20 20 20 20 20 20 62 79 20 78 53 6c 65 65          by xSlee
cbb0: 70 28 29 20 65 78 63 65 65 64 73 20 4e 20 6d 69  p() exceeds N mi
cbc0: 6c 6c 69 73 65 63 6f 6e 64 73 2e 0a 2a 2f 0a 69  lliseconds..*/.i
cbd0: 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  nt sqlite3_busy_
cbe0: 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a  timeout(sqlite3*
cbf0: 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a  , int ms);../*.*
cc00: 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76  * CAPI3REF: Conv
cc10: 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73  enience Routines
cc20: 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65   For Running Que
cc30: 72 69 65 73 20 7b 46 31 32 33 37 30 7d 0a 2a 2a  ries {F12370}.**
cc40: 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20  .** Definition: 
cc50: 41 20 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c  A <b>result tabl
cc60: 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20  e</b> is memory 
cc70: 64 61 74 61 20 73 74 72 75 63 74 75 72 65 20 63  data structure c
cc80: 72 65 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a  reated by the.**
cc90: 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61   [sqlite3_get_ta
cca0: 62 6c 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ble()] interface
ccb0: 2e 20 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c  .  A result tabl
ccc0: 65 20 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a  e records the.**
ccd0: 20 63 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20   complete query 
cce0: 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65  results from one
ccf0: 20 6f 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73   or more queries
cd00: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c  ..**.** The tabl
cd10: 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68  e conceptually h
cd20: 61 73 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72  as a number of r
cd30: 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e  ows and columns.
cd40: 20 20 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e    But.** these n
cd50: 75 6d 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70  umbers are not p
cd60: 61 72 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c  art of the resul
cd70: 74 20 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20  t table itself. 
cd80: 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72   These.** number
cd90: 73 20 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73  s are obtained s
cda0: 65 70 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20  eparately.  Let 
cdb0: 4e 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20  N be the number 
cdc0: 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d  of rows.** and M
cdd0: 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   be the number o
cde0: 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a  f columns..**.**
cdf0: 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
ce00: 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
ce10: 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d  ointers to zero-
ce20: 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54  terminated.** UT
ce30: 46 2d 38 20 73 74 72 69 6e 67 73 2e 20 20 54 68  F-8 strings.  Th
ce40: 65 72 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20  ere are (N+1)*M 
ce50: 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20  elements in the 
ce60: 61 72 72 61 79 2e 20 20 0a 2a 2a 20 54 68 65 20  array.  .** The 
ce70: 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73  first M pointers
ce80: 20 70 6f 69 6e 74 20 74 6f 20 7a 65 72 6f 2d 74   point to zero-t
ce90: 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67  erminated string
cea0: 73 20 74 68 61 74 20 0a 2a 2a 20 63 6f 6e 74 61  s that .** conta
ceb0: 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20  in the names of 
cec0: 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20  the columns..** 
ced0: 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e  The remaining en
cee0: 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20  tries all point 
cef0: 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74 73  to query results
cf00: 2e 20 20 4e 55 4c 4c 0a 2a 2a 20 76 61 6c 75 65  .  NULL.** value
cf10: 73 20 61 72 65 20 67 69 76 65 20 61 20 4e 55 4c  s are give a NUL
cf20: 4c 20 70 6f 69 6e 74 65 72 2e 20 20 41 6c 6c 20  L pointer.  All 
cf30: 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61 72 65  other values are
cf40: 20 69 6e 0a 2a 2a 20 74 68 65 69 72 20 55 54 46   in.** their UTF
cf50: 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  -8 zero-terminat
cf60: 65 64 20 73 74 72 69 6e 67 20 72 65 70 72 65 73  ed string repres
cf70: 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75  entation as retu
cf80: 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  rned by.** [sqli
cf90: 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
cfa0: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75  )]..**.** A resu
cfb0: 6c 74 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63  lt table might c
cfc0: 6f 6e 73 69 73 74 73 20 6f 66 20 6f 6e 65 20 6f  onsists of one o
cfd0: 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c  r more memory al
cfe0: 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74  locations..** It
cff0: 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20   is not safe to 
d000: 70 61 73 73 20 61 20 72 65 73 75 6c 74 20 74 61  pass a result ta
d010: 62 6c 65 20 64 69 72 65 63 74 6c 79 20 74 6f 20  ble directly to 
d020: 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
d030: 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61  ..** A result ta
d040: 62 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 64 65  ble should be de
d050: 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 20  allocated using 
d060: 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61  [sqlite3_free_ta
d070: 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 73  ble()]..**.** As
d080: 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 74   an example of t
d090: 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
d0a0: 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 20  format, suppose 
d0b0: 61 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a  a query result.*
d0c0: 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  * is as follows:
d0d0: 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
d0e0: 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20  te><pre>.**     
d0f0: 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c     Name        |
d100: 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d   Age.**        -
d110: 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
d120: 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20  ------.**       
d130: 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34   Alice       | 4
d140: 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20  3.**        Bob 
d150: 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20          | 28.** 
d160: 20 20 20 20 20 20 20 43 69 6e 64 79 20 20 20 20         Cindy    
d170: 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65     | 21.** </pre
d180: 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
d190: 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74  *.** There are t
d1a0: 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29  wo column (M==2)
d1b0: 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73 20   and three rows 
d1c0: 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 68  (N==3).  Thus th
d1d0: 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 6c  e.** result tabl
d1e0: 65 20 68 61 73 20 38 20 65 6e 74 72 69 65 73 2e  e has 8 entries.
d1f0: 20 20 53 75 70 70 6f 73 65 20 74 68 65 20 72 65    Suppose the re
d200: 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73 74  sult table is st
d210: 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72  ored.** in an ar
d220: 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 75  ray names azResu
d230: 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 75  lt.  Then azResu
d240: 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63 6f  lt holds this co
d250: 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  ntent:.**.** <bl
d260: 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
d270: 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
d280: 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65  t&#91;0] = "Name
d290: 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
d2a0: 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22  esult&#91;1] = "
d2b0: 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  Age";.**        
d2c0: 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20  azResult&#91;2] 
d2d0: 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20  = "Alice";.**   
d2e0: 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
d2f0: 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20  1;3] = "43";.** 
d300: 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
d310: 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a  #91;4] = "Bob";.
d320: 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
d330: 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22  lt&#91;5] = "28"
d340: 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
d350: 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43  sult&#91;6] = "C
d360: 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20  indy";.**       
d370: 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d   azResult&#91;7]
d380: 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72   = "21";.** </pr
d390: 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
d3a0: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
d3b0: 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75  3_get_table() fu
d3c0: 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73  nction evaluates
d3d0: 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20   one or more.** 
d3e0: 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61  semicolon-separa
d3f0: 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ted SQL statemen
d400: 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74  ts in the zero-t
d410: 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a  erminated UTF-8.
d420: 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73  ** string of its
d430: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20   2nd parameter. 
d440: 20 49 74 20 72 65 74 75 72 6e 73 20 61 20 72 65   It returns a re
d450: 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68  sult table to th
d460: 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76  e.** pointer giv
d470: 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70 61  en in its 3rd pa
d480: 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41  rameter..**.** A
d490: 66 74 65 72 20 74 68 65 20 63 61 6c 6c 69 6e 67  fter the calling
d4a0: 20 66 75 6e 63 74 69 6f 6e 20 68 61 73 20 66 69   function has fi
d4b0: 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 65  nished using the
d4c0: 20 72 65 73 75 6c 74 2c 20 69 74 20 73 68 6f 75   result, it shou
d4d0: 6c 64 20 0a 2a 2a 20 70 61 73 73 20 74 68 65 20  ld .** pass the 
d4e0: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 72  pointer to the r
d4f0: 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 73  esult table to s
d500: 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
d510: 65 28 29 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  e() in order to 
d520: 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68 65 20  .** release the 
d530: 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61 73 20  memory that was 
d540: 6d 61 6c 6c 6f 63 2d 65 64 2e 20 20 42 65 63 61  malloc-ed.  Beca
d550: 75 73 65 20 6f 66 20 74 68 65 20 77 61 79 20 74  use of the way t
d560: 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  he .** [sqlite3_
d570: 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e  malloc()] happen
d580: 73 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33  s within sqlite3
d590: 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 68  _get_table(), th
d5a0: 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e  e calling.** fun
d5b0: 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74  ction must not t
d5c0: 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69  ry to call [sqli
d5d0: 74 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65  te3_free()] dire
d5e0: 63 74 6c 79 2e 20 20 4f 6e 6c 79 20 0a 2a 2a 20  ctly.  Only .** 
d5f0: 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61  [sqlite3_free_ta
d600: 62 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74  ble()] is able t
d610: 6f 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65  o release the me
d620: 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e  mory properly an
d630: 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  d safely..**.** 
d640: 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
d650: 74 61 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63  table() interfac
d660: 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64  e is implemented
d670: 20 61 73 20 61 20 77 72 61 70 70 65 72 20 61 72   as a wrapper ar
d680: 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ound.** [sqlite3
d690: 5f 65 78 65 63 28 29 5d 2e 20 20 54 68 65 20 73  _exec()].  The s
d6a0: 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
d6b0: 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20  () routine does 
d6c0: 6e 6f 74 20 68 61 76 65 20 61 63 63 65 73 73 0a  not have access.
d6d0: 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e  ** to any intern
d6e0: 61 6c 20 64 61 74 61 20 73 74 72 75 63 74 75 72  al data structur
d6f0: 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 49  es of SQLite.  I
d700: 74 20 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 20  t uses only the 
d710: 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66  public.** interf
d720: 61 63 65 20 64 65 66 69 6e 65 64 20 68 65 72 65  ace defined here
d730: 2e 20 20 41 73 20 61 20 63 6f 6e 73 65 71 75 65  .  As a conseque
d740: 6e 63 65 2c 20 65 72 72 6f 72 73 20 74 68 61 74  nce, errors that
d750: 20 6f 63 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a   occur in the.**
d760: 20 77 72 61 70 70 65 72 20 6c 61 79 65 72 20 6f   wrapper layer o
d770: 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 69 6e  utside of the in
d780: 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f  ternal [sqlite3_
d790: 65 78 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 65  exec()] call are
d7a0: 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65   not.** reflecte
d7b0: 64 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20  d in subsequent 
d7c0: 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
d7d0: 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a  3_errcode()] or.
d7e0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ** [sqlite3_errm
d7f0: 73 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  sg()]..**.** INV
d800: 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
d810: 46 31 32 33 37 31 7d 20 49 66 20 61 20 5b 73 71  F12371} If a [sq
d820: 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
d830: 29 5d 20 66 61 69 6c 73 20 61 20 6d 65 6d 6f 72  )] fails a memor
d840: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68  y allocation, th
d850: 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  en.**          i
d860: 74 20 66 72 65 65 73 20 74 68 65 20 72 65 73 75  t frees the resu
d870: 6c 74 20 74 61 62 6c 65 20 75 6e 64 65 72 20 63  lt table under c
d880: 6f 6e 73 74 72 75 63 74 69 6f 6e 2c 20 61 62 6f  onstruction, abo
d890: 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  rts the.**      
d8a0: 20 20 20 20 71 75 65 72 79 20 69 6e 20 70 72 6f      query in pro
d8b0: 63 65 73 73 2c 20 73 6b 69 70 73 20 61 6e 79 20  cess, skips any 
d8c0: 73 75 62 73 65 71 75 65 6e 74 20 71 75 65 72 69  subsequent queri
d8d0: 65 73 2c 20 73 65 74 73 20 74 68 65 0a 2a 2a 20  es, sets the.** 
d8e0: 20 20 20 20 20 20 20 20 20 2a 72 65 73 75 6c 74           *result
d8f0: 70 20 6f 75 74 70 75 74 20 70 6f 69 6e 74 65 72  p output pointer
d900: 20 74 6f 20 4e 55 4c 4c 20 61 6e 64 20 72 65 74   to NULL and ret
d910: 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d  urns [SQLITE_NOM
d920: 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33  EM]..**.** {F123
d930: 37 33 7d 20 49 66 20 74 68 65 20 6e 63 6f 6c 75  73} If the ncolu
d940: 6d 6e 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  mn parameter to 
d950: 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62  [sqlite3_get_tab
d960: 6c 65 28 29 5d 20 69 73 20 6e 6f 74 20 4e 55 4c  le()] is not NUL
d970: 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  L.**          th
d980: 65 6e 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  en [sqlite3_get_
d990: 74 61 62 6c 65 28 29 5d 20 77 72 69 74 65 20 74  table()] write t
d9a0: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
d9b0: 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20 20  umns in the.**  
d9c0: 20 20 20 20 20 20 20 20 72 65 73 75 6c 74 20 73          result s
d9d0: 65 74 20 6f 66 20 74 68 65 20 71 75 65 72 79 20  et of the query 
d9e0: 69 6e 74 6f 20 2a 6e 63 6f 6c 75 6d 6e 20 69 66  into *ncolumn if
d9f0: 20 74 68 65 20 71 75 65 72 79 20 69 73 0a 2a 2a   the query is.**
da00: 20 20 20 20 20 20 20 20 20 20 73 75 63 63 65 73            succes
da10: 73 66 75 6c 20 28 69 66 20 74 68 65 20 66 75 6e  sful (if the fun
da20: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 53 51  ction returns SQ
da30: 4c 49 54 45 5f 4f 4b 29 2e 0a 2a 2a 0a 2a 2a 20  LITE_OK)..**.** 
da40: 7b 46 31 32 33 37 34 7d 20 49 66 20 74 68 65 20  {F12374} If the 
da50: 6e 72 6f 77 20 70 61 72 61 6d 65 74 65 72 20 74  nrow parameter t
da60: 6f 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  o [sqlite3_get_t
da70: 61 62 6c 65 28 29 5d 20 69 73 20 6e 6f 74 20 4e  able()] is not N
da80: 55 4c 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ULL.**          
da90: 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 67 65  then [sqlite3_ge
daa0: 74 5f 74 61 62 6c 65 28 29 5d 20 77 72 69 74 65  t_table()] write
dab0: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72   the number of r
dac0: 6f 77 73 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20  ows in the.**   
dad0: 20 20 20 20 20 20 20 72 65 73 75 6c 74 20 73 65         result se
dae0: 74 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 69  t of the query i
daf0: 6e 74 6f 20 2a 6e 72 6f 77 20 69 66 20 74 68 65  nto *nrow if the
db00: 20 71 75 65 72 79 20 69 73 0a 2a 2a 20 20 20 20   query is.**    
db10: 20 20 20 20 20 20 73 75 63 63 65 73 73 66 75 6c        successful
db20: 20 28 69 66 20 74 68 65 20 66 75 6e 63 74 69 6f   (if the functio
db30: 6e 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45  n returns SQLITE
db40: 5f 4f 4b 29 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  _OK)..**.** {F12
db50: 33 37 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  376} The [sqlite
db60: 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 66  3_get_table()] f
db70: 75 6e 63 74 69 6f 6e 20 73 65 74 73 20 69 74 73  unction sets its
db80: 20 2a 6e 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 0a   *ncolumn value.
db90: 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 74  **          to t
dba0: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
dbb0: 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75  umns in the resu
dbc0: 6c 74 20 73 65 74 20 6f 66 20 74 68 65 20 71 75  lt set of the qu
dbd0: 65 72 79 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20  ery in the.**   
dbe0: 20 20 20 20 20 20 20 73 71 6c 20 70 61 72 61 6d         sql param
dbf0: 65 74 65 72 2c 20 6f 72 20 74 6f 20 7a 65 72 6f  eter, or to zero
dc00: 20 69 66 20 74 68 65 20 71 75 65 72 79 20 69 6e   if the query in
dc10: 20 73 71 6c 20 68 61 73 20 61 6e 20 65 6d 70 74   sql has an empt
dc20: 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  y.**          re
dc30: 73 75 6c 74 20 73 65 74 2e 0a 2a 2f 0a 69 6e 74  sult set..*/.int
dc40: 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
dc50: 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  le(.  sqlite3*, 
dc60: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41              /* A
dc70: 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20  n open database 
dc80: 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
dc90: 2a 73 71 6c 2c 20 20 20 20 20 20 2f 2a 20 53 51  *sql,      /* SQ
dca0: 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65  L to be evaluate
dcb0: 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70  d */.  char ***p
dcc0: 52 65 73 75 6c 74 2c 20 20 20 20 20 20 2f 2a 20  Result,      /* 
dcd0: 52 65 73 75 6c 74 73 20 6f 66 20 74 68 65 20 71  Results of the q
dce0: 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 6e  uery */.  int *n
dcf0: 72 6f 77 2c 20 20 20 20 20 20 20 20 20 20 20 20  row,            
dd00: 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73  /* Number of res
dd10: 75 6c 74 20 72 6f 77 73 20 77 72 69 74 74 65 6e  ult rows written
dd20: 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a   here */.  int *
dd30: 6e 63 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20  ncolumn,        
dd40: 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65   /* Number of re
dd50: 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69  sult columns wri
dd60: 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63  tten here */.  c
dd70: 68 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20  har **errmsg    
dd80: 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73       /* Error ms
dd90: 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a  g written here *
dda0: 2f 0a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  /.);.void sqlite
ddb0: 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 63 68 61  3_free_table(cha
ddc0: 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a  r **result);../*
ddd0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6f  .** CAPI3REF: Fo
dde0: 72 6d 61 74 74 65 64 20 53 74 72 69 6e 67 20 50  rmatted String P
ddf0: 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e  rinting Function
de00: 73 20 7b 46 31 37 34 30 30 7d 0a 2a 2a 0a 2a 2a  s {F17400}.**.**
de10: 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
de20: 61 72 65 20 77 6f 72 6b 61 6c 69 6b 65 73 20 6f  are workalikes o
de30: 66 20 74 68 65 20 22 70 72 69 6e 74 66 28 29 22  f the "printf()"
de40: 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74   family of funct
de50: 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65  ions.** from the
de60: 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
de70: 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ary..**.** The s
de80: 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29  qlite3_mprintf()
de90: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d 70   and sqlite3_vmp
dea0: 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 73  rintf() routines
deb0: 20 77 72 69 74 65 20 74 68 65 69 72 0a 2a 2a 20   write their.** 
dec0: 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d  results into mem
ded0: 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
dee0: 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
def0: 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72  c()]..** The str
df00: 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79  ings returned by
df10: 20 74 68 65 73 65 20 74 77 6f 20 72 6f 75 74 69   these two routi
df20: 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a  nes should be.**
df30: 20 72 65 6c 65 61 73 65 64 20 62 79 20 5b 73 71   released by [sq
df40: 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 20 20  lite3_free()].  
df50: 20 42 6f 74 68 20 72 6f 75 74 69 6e 65 73 20 72   Both routines r
df60: 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20  eturn a.** NULL 
df70: 70 6f 69 6e 74 65 72 20 69 66 20 5b 73 71 6c 69  pointer if [sqli
df80: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73  te3_malloc()] is
df90: 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
dfa0: 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65  ate enough.** me
dfb0: 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
dfc0: 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e   resulting strin
dfd0: 67 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 73 71 6c 69  g..**.** In sqli
dfe0: 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72  te3_snprintf() r
dff0: 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61  outine is simila
e000: 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29  r to "snprintf()
e010: 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74  " from.** the st
e020: 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
e030: 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 69 73  .  The result is
e040: 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68   written into th
e050: 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70  e.** buffer supp
e060: 6c 69 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  lied as the seco
e070: 6e 64 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f  nd parameter who
e080: 73 65 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e  se size is given
e090: 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74   by.** the first
e0a0: 20 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65   parameter. Note
e0b0: 20 74 68 61 74 20 74 68 65 20 6f 72 64 65 72 20   that the order 
e0c0: 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20  of the.** first 
e0d0: 74 77 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69  two parameters i
e0e0: 73 20 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20  s reversed from 
e0f0: 73 6e 70 72 69 6e 74 66 28 29 2e 20 20 54 68 69  snprintf().  Thi
e100: 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f  s is an.** histo
e110: 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74  rical accident t
e120: 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69  hat cannot be fi
e130: 78 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 61  xed without brea
e140: 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64  king.** backward
e150: 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  s compatibility.
e160: 20 20 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 74    Note also that
e170: 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
e180: 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61  f().** returns a
e190: 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 73 20   pointer to its 
e1a0: 62 75 66 66 65 72 20 69 6e 73 74 65 61 64 20 6f  buffer instead o
e1b0: 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  f the number of.
e1c0: 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 61 63  ** characters ac
e1d0: 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e 20 69  tually written i
e1e0: 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72 2e 20  nto the buffer. 
e1f0: 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 0a 2a   We admit that.*
e200: 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
e210: 63 68 61 72 61 63 74 65 72 73 20 77 72 69 74 74  characters writt
e220: 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f  en would be a mo
e230: 72 65 20 75 73 65 66 75 6c 20 72 65 74 75 72 6e  re useful return
e240: 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 20 77 65  .** value but we
e250: 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74   cannot change t
e260: 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
e270: 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70  n of sqlite3_snp
e280: 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77  rintf().** now w
e290: 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20  ithout breaking 
e2a0: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a  compatibility..*
e2b0: 2a 0a 2a 2a 20 41 73 20 6c 6f 6e 67 20 61 73 20  *.** As long as 
e2c0: 74 68 65 20 62 75 66 66 65 72 20 73 69 7a 65 20  the buffer size 
e2d0: 69 73 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  is greater than 
e2e0: 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e  zero, sqlite3_sn
e2f0: 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72  printf().** guar
e300: 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20  antees that the 
e310: 62 75 66 66 65 72 20 69 73 20 61 6c 77 61 79 73  buffer is always
e320: 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
e330: 2e 20 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20  .  The first.** 
e340: 70 61 72 61 6d 65 74 65 72 20 22 6e 22 20 69 73  parameter "n" is
e350: 20 74 68 65 20 74 6f 74 61 6c 20 73 69 7a 65 20   the total size 
e360: 6f 66 20 74 68 65 20 62 75 66 66 65 72 2c 20 69  of the buffer, i
e370: 6e 63 6c 75 64 69 6e 67 20 73 70 61 63 65 20 66  ncluding space f
e380: 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74  or.** the zero t
e390: 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74  erminator.  So t
e3a0: 68 65 20 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e  he longest strin
e3b0: 67 20 74 68 61 74 20 63 61 6e 20 62 65 20 63 6f  g that can be co
e3c0: 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74  mpletely.** writ
e3d0: 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20  ten will be n-1 
e3e0: 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a  characters..**.*
e3f0: 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
e400: 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73   all implement s
e410: 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 66  ome additional f
e420: 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74  ormatting.** opt
e430: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 75 73  ions that are us
e440: 65 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75  eful for constru
e450: 63 74 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d  cting SQL statem
e460: 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20  ents..** All of 
e470: 74 68 65 20 75 73 75 61 6c 20 70 72 69 6e 74 66  the usual printf
e480: 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69   formatting opti
e490: 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e 20 61  ons apply.  In a
e4a0: 64 64 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a  ddition, there.*
e4b0: 2a 20 69 73 20 61 72 65 20 22 25 71 22 2c 20 22  * is are "%q", "
e4c0: 25 51 22 2c 20 61 6e 64 20 22 25 7a 22 20 6f 70  %Q", and "%z" op
e4d0: 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tions..**.** The
e4e0: 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73   %q option works
e4f0: 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68 61 74   like %s in that
e500: 20 69 74 20 73 75 62 73 74 69 74 75 74 65 73 20   it substitutes 
e510: 61 20 6e 75 6c 6c 2d 74 65 72 6d 69 6e 61 74 65  a null-terminate
e520: 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d  d.** string from
e530: 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c 69   the argument li
e540: 73 74 2e 20 20 42 75 74 20 25 71 20 61 6c 73 6f  st.  But %q also
e550: 20 64 6f 75 62 6c 65 73 20 65 76 65 72 79 20 27   doubles every '
e560: 5c 27 27 20 63 68 61 72 61 63 74 65 72 2e 0a 2a  \'' character..*
e570: 2a 20 25 71 20 69 73 20 64 65 73 69 67 6e 65 64  * %q is designed
e580: 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20   for use inside 
e590: 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c  a string literal
e5a0: 2e 20 20 42 79 20 64 6f 75 62 6c 69 6e 67 20 65  .  By doubling e
e5b0: 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72  ach '\''.** char
e5c0: 61 63 74 65 72 20 69 74 20 65 73 63 61 70 65 73  acter it escapes
e5d0: 20 74 68 61 74 20 63 68 61 72 61 63 74 65 72 20   that character 
e5e0: 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f  and allows it to
e5f0: 20 62 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74   be inserted int
e600: 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 2e  o.** the string.
e610: 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70  .**.** For examp
e620: 6c 65 2c 20 73 6f 20 73 6f 6d 65 20 73 74 72 69  le, so some stri
e630: 6e 67 20 76 61 72 69 61 62 6c 65 20 63 6f 6e 74  ng variable cont
e640: 61 69 6e 73 20 74 65 78 74 20 61 73 20 66 6f 6c  ains text as fol
e650: 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
e660: 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
e670: 20 20 63 68 61 72 20 2a 7a 54 65 78 74 20 3d 20    char *zText = 
e680: 22 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61  "It's a happy da
e690: 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  y!";.** </pre></
e6a0: 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
e6b0: 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65 20 74 68  * One can use th
e6c0: 69 73 20 74 65 78 74 20 69 6e 20 61 6e 20 53 51  is text in an SQ
e6d0: 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20 66  L statement as f
e6e0: 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
e6f0: 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
e700: 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d  **  char *zSQL =
e710: 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
e720: 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61  ("INSERT INTO ta
e730: 62 6c 65 20 56 41 4c 55 45 53 28 27 25 71 27 29  ble VALUES('%q')
e740: 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73  ", zText);.**  s
e750: 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20  qlite3_exec(db, 
e760: 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a  zSQL, 0, 0, 0);.
e770: 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65  **  sqlite3_free
e780: 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65  (zSQL);.** </pre
e790: 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
e7a0: 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65  *.** Because the
e7b0: 20 25 71 20 66 6f 72 6d 61 74 20 73 74 72 69 6e   %q format strin
e7c0: 67 20 69 73 20 75 73 65 64 2c 20 74 68 65 20 27  g is used, the '
e7d0: 5c 27 27 20 63 68 61 72 61 63 74 65 72 20 69 6e  \'' character in
e7e0: 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65 73 63   zText.** is esc
e7f0: 61 70 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c  aped and the SQL
e800: 20 67 65 6e 65 72 61 74 65 64 20 69 73 20 61 73   generated is as
e810: 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
e820: 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
e830: 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54  >.**  INSERT INT
e840: 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28  O table1 VALUES(
e850: 27 49 74 27 27 73 20 61 20 68 61 70 70 79 20 64  'It''s a happy d
e860: 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  ay!').** </pre><
e870: 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
e880: 2a 2a 20 54 68 69 73 20 69 73 20 63 6f 72 72 65  ** This is corre
e890: 63 74 2e 20 20 48 61 64 20 77 65 20 75 73 65 64  ct.  Had we used
e8a0: 20 25 73 20 69 6e 73 74 65 61 64 20 6f 66 20 25   %s instead of %
e8b0: 71 2c 20 74 68 65 20 67 65 6e 65 72 61 74 65 64  q, the generated
e8c0: 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61   SQL.** would ha
e8d0: 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74  ve looked like t
e8e0: 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  his:.**.** <bloc
e8f0: 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
e900: 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62   INSERT INTO tab
e910: 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 73  le1 VALUES('It's
e920: 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29 3b   a happy day!');
e930: 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
e940: 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
e950: 69 73 20 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c  is second exampl
e960: 65 20 69 73 20 61 6e 20 53 51 4c 20 73 79 6e 74  e is an SQL synt
e970: 61 78 20 65 72 72 6f 72 2e 20 20 41 73 20 61 20  ax error.  As a 
e980: 67 65 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f 75  general rule you
e990: 0a 2a 2a 20 73 68 6f 75 6c 64 20 61 6c 77 61 79  .** should alway
e9a0: 73 20 75 73 65 20 25 71 20 69 6e 73 74 65 61 64  s use %q instead
e9b0: 20 6f 66 20 25 73 20 77 68 65 6e 20 69 6e 73 65   of %s when inse
e9c0: 72 74 69 6e 67 20 74 65 78 74 20 69 6e 74 6f 20  rting text into 
e9d0: 61 20 73 74 72 69 6e 67 20 0a 2a 2a 20 6c 69 74  a string .** lit
e9e0: 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  eral..**.** The 
e9f0: 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20  %Q option works 
ea00: 6c 69 6b 65 20 25 71 20 65 78 63 65 70 74 20 69  like %q except i
ea10: 74 20 61 6c 73 6f 20 61 64 64 73 20 73 69 6e 67  t also adds sing
ea20: 6c 65 20 71 75 6f 74 65 73 20 61 72 6f 75 6e 64  le quotes around
ea30: 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69 64 65 20  .** the outside 
ea40: 6f 66 20 74 68 65 20 74 6f 74 61 6c 20 73 74 72  of the total str
ea50: 69 6e 67 2e 20 20 4f 72 20 69 66 20 74 68 65 20  ing.  Or if the 
ea60: 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65  parameter in the
ea70: 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6c 69 73   argument.** lis
ea80: 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  t is a NULL poin
ea90: 74 65 72 2c 20 25 51 20 73 75 62 73 74 69 74 75  ter, %Q substitu
eaa0: 74 65 73 20 74 68 65 20 74 65 78 74 20 22 4e 55  tes the text "NU
eab0: 4c 4c 22 20 28 77 69 74 68 6f 75 74 20 73 69 6e  LL" (without sin
eac0: 67 6c 65 0a 2a 2a 20 71 75 6f 74 65 73 29 20 69  gle.** quotes) i
ead0: 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20 25  n place of the %
eae0: 51 20 6f 70 74 69 6f 6e 2e 20 7b 45 4e 44 7d 20  Q option. {END} 
eaf0: 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65   So, for example
eb00: 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a  , one could say:
eb10: 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
eb20: 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61  te><pre>.**  cha
eb30: 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65  r *zSQL = sqlite
eb40: 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52  3_mprintf("INSER
eb50: 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c  T INTO table VAL
eb60: 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78 74 29  UES(%Q)", zText)
eb70: 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78  ;.**  sqlite3_ex
eb80: 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20  ec(db, zSQL, 0, 
eb90: 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  0, 0);.**  sqlit
eba0: 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a  e3_free(zSQL);.*
ebb0: 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
ebc0: 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  uote>.**.** The 
ebd0: 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c 6c 20  code above will 
ebe0: 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65 63 74  render a correct
ebf0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69   SQL statement i
ec00: 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61  n the zSQL.** va
ec10: 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66 20 74  riable even if t
ec20: 68 65 20 7a 54 65 78 74 20 76 61 72 69 61 62 6c  he zText variabl
ec30: 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  e is a NULL poin
ec40: 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 22  ter..**.** The "
ec50: 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f  %z" formatting o
ec60: 70 74 69 6f 6e 20 77 6f 72 6b 73 20 65 78 61 63  ption works exac
ec70: 74 6c 79 20 6c 69 6b 65 20 22 25 73 22 20 77 69  tly like "%s" wi
ec80: 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69  th the.** additi
ec90: 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20 74 68  on that after th
eca0: 65 20 73 74 72 69 6e 67 20 68 61 73 20 62 65 65  e string has bee
ecb0: 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65  n read and copie
ecc0: 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65  d into.** the re
ecd0: 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66  sult, [sqlite3_f
ece0: 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64  ree()] is called
ecf0: 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74   on the input st
ed00: 72 69 6e 67 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a  ring. {END}.**.*
ed10: 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
ed20: 0a 2a 2a 20 7b 46 31 37 34 30 33 7d 20 20 54 68  .** {F17403}  Th
ed30: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e  e [sqlite3_mprin
ed40: 74 66 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  tf()] and [sqlit
ed50: 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 5d 20 69  e3_vmprintf()] i
ed60: 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 20 20 20  nterfaces.**    
ed70: 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 65 69         return ei
ed80: 74 68 65 72 20 70 6f 69 6e 74 65 72 73 20 74 6f  ther pointers to
ed90: 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
eda0: 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73 20 68   UTF-8 strings h
edb0: 65 6c 64 20 69 6e 0a 2a 2a 20 20 20 20 20 20 20  eld in.**       
edc0: 20 20 20 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69      memory obtai
edd0: 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
ede0: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 4e  3_malloc()] or N
edf0: 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 69 66 0a  ULL pointers if.
ee00: 2a 2a 20 20 20 20 20 20 20 20 20 20 20 61 20 63  **           a c
ee10: 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
ee20: 6d 61 6c 6c 6f 63 28 29 5d 20 66 61 69 6c 73 2e  malloc()] fails.
ee30: 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 34 30 36 7d 20  .**.** {F17406} 
ee40: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 6e   The [sqlite3_sn
ee50: 70 72 69 6e 74 66 28 29 5d 20 69 6e 74 65 72 66  printf()] interf
ee60: 61 63 65 20 77 72 69 74 65 73 20 61 20 7a 65 72  ace writes a zer
ee70: 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
ee80: 20 20 20 20 20 20 20 20 20 20 55 54 46 2d 38 20            UTF-8 
ee90: 73 74 72 69 6e 67 20 69 6e 74 6f 20 74 68 65 20  string into the 
eea0: 62 75 66 66 65 72 20 70 6f 69 6e 74 65 64 20 74  buffer pointed t
eeb0: 6f 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20  o by the second 
eec0: 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20  parameter.**    
eed0: 20 20 20 20 20 20 20 70 72 6f 76 69 64 65 64 20         provided 
eee0: 74 68 61 74 20 74 68 65 20 66 69 72 73 74 20 70  that the first p
eef0: 61 72 61 6d 65 74 65 72 20 69 73 20 67 72 65 61  arameter is grea
ef00: 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2e 0a 2a  ter than zero..*
ef10: 2a 0a 2a 2a 20 7b 46 31 37 34 30 37 7d 20 20 54  *.** {F17407}  T
ef20: 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72  he [sqlite3_snpr
ef30: 69 6e 74 66 28 29 5d 20 69 6e 74 65 72 66 61 63  intf()] interfac
ef40: 65 20 64 6f 65 73 20 6e 6f 74 20 77 72 69 74 65  e does not write
ef50: 73 20 73 6c 6f 74 73 20 6f 66 0a 2a 2a 20 20 20  s slots of.**   
ef60: 20 20 20 20 20 20 20 20 69 74 73 20 6f 75 74 70          its outp
ef70: 75 74 20 62 75 66 66 65 72 20 28 74 68 65 20 73  ut buffer (the s
ef80: 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 29  econd parameter)
ef90: 20 6f 75 74 73 69 64 65 20 74 68 65 20 72 61 6e   outside the ran
efa0: 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  ge.**           
efb0: 6f 66 20 30 20 74 68 72 6f 75 67 68 20 4e 2d 31  of 0 through N-1
efc0: 20 28 77 68 65 72 65 20 4e 20 69 73 20 74 68 65   (where N is the
efd0: 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
efe0: 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72  ).**           r
eff0: 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65  egardless of the
f000: 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73   length of the s
f010: 74 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20  tring.**        
f020: 20 20 20 72 65 71 75 65 73 74 65 64 20 62 79 20     requested by 
f030: 74 68 65 20 66 6f 72 6d 61 74 20 73 70 65 63 69  the format speci
f040: 66 69 63 61 74 69 6f 6e 2e 0a 2a 2a 20 20 20 0a  fication..**   .
f050: 2a 2f 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33  */.char *sqlite3
f060: 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63  _mprintf(const c
f070: 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20  har*,...);.char 
f080: 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74  *sqlite3_vmprint
f090: 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76  f(const char*, v
f0a0: 61 5f 6c 69 73 74 29 3b 0a 63 68 61 72 20 2a 73  a_list);.char *s
f0b0: 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
f0c0: 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20  int,char*,const 
f0d0: 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a  char*, ...);../*
f0e0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65  .** CAPI3REF: Me
f0f0: 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20  mory Allocation 
f100: 53 75 62 73 79 73 74 65 6d 20 7b 46 31 37 33 30  Subsystem {F1730
f110: 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  0}.**.** The SQL
f120: 69 74 65 20 63 6f 72 65 20 20 75 73 65 73 20 74  ite core  uses t
f130: 68 65 73 65 20 74 68 72 65 65 20 72 6f 75 74 69  hese three routi
f140: 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69  nes for all of i
f150: 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e  ts own.** intern
f160: 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  al memory alloca
f170: 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72  tion needs. "Cor
f180: 65 22 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f  e" in the previo
f190: 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64  us sentence.** d
f1a0: 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20  oes not include 
f1b0: 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d  operating-system
f1c0: 20 73 70 65 63 69 66 69 63 20 56 46 53 20 69 6d   specific VFS im
f1d0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54  plementation.  T
f1e0: 68 65 0a 2a 2a 20 77 69 6e 64 6f 77 73 20 56 46  he.** windows VF
f1f0: 53 20 75 73 65 73 20 6e 61 74 69 76 65 20 6d 61  S uses native ma
f200: 6c 6c 6f 63 20 61 6e 64 20 66 72 65 65 20 66 6f  lloc and free fo
f210: 72 20 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e  r some operation
f220: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  s..**.** The sql
f230: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f  ite3_malloc() ro
f240: 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20  utine returns a 
f250: 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f  pointer to a blo
f260: 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20  ck.** of memory 
f270: 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73  at least N bytes
f280: 20 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 72   in length, wher
f290: 65 20 4e 20 69 73 20 74 68 65 20 70 61 72 61 6d  e N is the param
f2a0: 65 74 65 72 2e 0a 2a 2a 20 49 66 20 73 71 6c 69  eter..** If sqli
f2b0: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20  te3_malloc() is 
f2c0: 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e  unable to obtain
f2d0: 20 73 75 66 66 69 63 69 65 6e 74 20 66 72 65 65   sufficient free
f2e0: 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72  .** memory, it r
f2f0: 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f  eturns a NULL po
f300: 69 6e 74 65 72 2e 20 20 49 66 20 74 68 65 20 70  inter.  If the p
f310: 61 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a  arameter N to.**
f320: 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
f330: 29 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67  ) is zero or neg
f340: 61 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74  ative then sqlit
f350: 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75  e3_malloc() retu
f360: 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f  rns.** a NULL po
f370: 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c  inter..**.** Cal
f380: 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65  ling sqlite3_fre
f390: 65 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74  e() with a point
f3a0: 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65  er previously re
f3b0: 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c  turned.** by sql
f3c0: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72  ite3_malloc() or
f3d0: 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
f3e0: 28 29 20 72 65 6c 65 61 73 65 73 20 74 68 61 74  () releases that
f3f0: 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68   memory so.** th
f400: 61 74 20 69 74 20 6d 69 67 68 74 20 62 65 20 72  at it might be r
f410: 65 75 73 65 64 2e 20 20 54 68 65 20 73 71 6c 69  eused.  The sqli
f420: 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69  te3_free() routi
f430: 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70  ne is.** a no-op
f440: 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69   if is called wi
f450: 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  th a NULL pointe
f460: 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55  r.  Passing a NU
f470: 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f  LL pointer.** to
f480: 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
f490: 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66  is harmless.  Af
f4a0: 74 65 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c  ter being freed,
f4b0: 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c   memory.** shoul
f4c0: 64 20 6e 65 69 74 68 65 72 20 62 65 20 72 65 61  d neither be rea
f4d0: 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20  d nor written.  
f4e0: 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65  Even reading pre
f4f0: 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a  viously freed.**
f500: 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65   memory might re
f510: 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e  sult in a segmen
f520: 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20  tation fault or 
f530: 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72  other severe err
f540: 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f  or..** Memory co
f550: 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d  rruption, a segm
f560: 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20  entation fault, 
f570: 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20  or other severe 
f580: 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72  error.** might r
f590: 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33  esult if sqlite3
f5a0: 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65  _free() is calle
f5b0: 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c  d with a non-NUL
f5c0: 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a  L pointer that.*
f5d0: 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e  * was not obtain
f5e0: 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ed from sqlite3_
f5f0: 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69  malloc() or sqli
f600: 74 65 33 5f 66 72 65 65 28 29 2e 0a 2a 2a 0a 2a  te3_free()..**.*
f610: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
f620: 61 6c 6c 6f 63 28 29 20 69 6e 74 65 72 66 61 63  alloc() interfac
f630: 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65  e attempts to re
f640: 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20  size a.** prior 
f650: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
f660: 6e 20 74 6f 20 62 65 20 61 74 20 6c 65 61 73 74  n to be at least
f670: 20 4e 20 62 79 74 65 73 2c 20 77 68 65 72 65 20   N bytes, where 
f680: 4e 20 69 73 20 74 68 65 0a 2a 2a 20 73 65 63 6f  N is the.** seco
f690: 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54  nd parameter.  T
f6a0: 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
f6b0: 74 69 6f 6e 20 74 6f 20 62 65 20 72 65 73 69 7a  tion to be resiz
f6c0: 65 64 20 69 73 20 74 68 65 20 66 69 72 73 74 0a  ed is the first.
f6d0: 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 20 49  ** parameter.  I
f6e0: 66 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  f the first para
f6f0: 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
f700: 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73  _realloc().** is
f710: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
f720: 74 68 65 6e 20 69 74 73 20 62 65 68 61 76 69 6f  then its behavio
f730: 72 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74  r is identical t
f740: 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c  o calling.** sql
f750: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 77  ite3_malloc(N) w
f760: 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65  here N is the se
f770: 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74  cond parameter t
f780: 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  o sqlite3_reallo
f790: 63 28 29 2e 0a 2a 2a 20 49 66 20 74 68 65 20 73  c()..** If the s
f7a0: 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
f7b0: 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  to sqlite3_reall
f7c0: 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a  oc() is zero or.
f7d0: 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e  ** negative then
f7e0: 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
f7f0: 20 65 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d   exactly the sam
f800: 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20  e as calling.** 
f810: 73 71 6c 69 74 65 33 5f 66 72 65 65 28 50 29 20  sqlite3_free(P) 
f820: 77 68 65 72 65 20 50 20 69 73 20 74 68 65 20 66  where P is the f
f830: 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
f840: 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  o sqlite3_reallo
f850: 63 28 29 2e 0a 2a 2a 20 53 71 6c 69 74 65 33 5f  c()..** Sqlite3_
f860: 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e  realloc() return
f870: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
f880: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
f890: 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73  on.** of at leas
f8a0: 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  t N bytes in siz
f8b0: 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 73 75 66  e or NULL if suf
f8c0: 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69  ficient memory i
f8d0: 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a  s unavailable..*
f8e0: 2a 20 49 66 20 4d 20 69 73 20 74 68 65 20 73 69  * If M is the si
f8f0: 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20  ze of the prior 
f900: 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e  allocation, then
f910: 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a   min(N,M) bytes.
f920: 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20  ** of the prior 
f930: 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20 63  allocation are c
f940: 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65 20 62  opied into the b
f950: 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66  eginning of buff
f960: 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62  er returned.** b
f970: 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  y sqlite3_reallo
f980: 63 28 29 20 61 6e 64 20 74 68 65 20 70 72 69 6f  c() and the prio
f990: 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20  r allocation is 
f9a0: 66 72 65 65 64 2e 0a 2a 2a 20 49 66 20 73 71 6c  freed..** If sql
f9b0: 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72  ite3_realloc() r
f9c0: 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74 68 65  eturns NULL, the
f9d0: 6e 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f  n the prior allo
f9e0: 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6e 6f 74  cation.** is not
f9f0: 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68   freed..**.** Th
fa00: 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65  e memory returne
fa10: 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c  d by sqlite3_mal
fa20: 6c 6f 63 28 29 20 61 6e 64 20 73 71 6c 69 74 65  loc() and sqlite
fa30: 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69  3_realloc().** i
fa40: 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e 65 64  s always aligned
fa50: 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61 6e 20   to at least an 
fa60: 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e  8 byte boundary.
fa70: 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65   {END}.**.** The
fa80: 20 64 65 66 61 75 6c 74 20 69 6d 70 6c 65 6d 65   default impleme
fa90: 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 74 68  ntation.** of th
faa0: 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
fab0: 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 75 73  ion subsystem us
fac0: 65 73 20 74 68 65 20 6d 61 6c 6c 6f 63 28 29 2c  es the malloc(),
fad0: 20 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 61 6e   realloc().** an
fae0: 64 20 66 72 65 65 28 29 20 70 72 6f 76 69 64 65  d free() provide
faf0: 64 20 62 79 20 74 68 65 20 73 74 61 6e 64 61 72  d by the standar
fb00: 64 20 43 20 6c 69 62 72 61 72 79 2e 20 7b 46 31  d C library. {F1
fb10: 37 33 38 32 7d 20 48 6f 77 65 76 65 72 2c 20 69  7382} However, i
fb20: 66 20 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73 20  f .** SQLite is 
fb30: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68  compiled with th
fb40: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 43 20 70 72  e following C pr
fb50: 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  eprocessor macro
fb60: 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
fb70: 74 65 3e 20 53 51 4c 49 54 45 5f 4d 45 4d 4f 52  te> SQLITE_MEMOR
fb80: 59 5f 53 49 5a 45 3d 3c 69 3e 4e 4e 4e 3c 2f 69  Y_SIZE=<i>NNN</i
fb90: 3e 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  > </blockquote>.
fba0: 2a 2a 0a 2a 2a 20 77 68 65 72 65 20 3c 69 3e 4e  **.** where <i>N
fbb0: 4e 4e 3c 2f 69 3e 20 69 73 20 61 6e 20 69 6e 74  NN</i> is an int
fbc0: 65 67 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74  eger, then SQLit
fbd0: 65 20 63 72 65 61 74 65 20 61 20 73 74 61 74 69  e create a stati
fbe0: 63 0a 2a 2a 20 61 72 72 61 79 20 6f 66 20 61 74  c.** array of at
fbf0: 20 6c 65 61 73 74 20 3c 69 3e 4e 4e 4e 3c 2f 69   least <i>NNN</i
fc00: 3e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20  > bytes in size 
fc10: 61 6e 64 20 75 73 65 20 74 68 61 74 20 61 72 72  and use that arr
fc20: 61 79 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f 66  ay.** for all of
fc30: 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d   its dynamic mem
fc40: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e  ory allocation n
fc50: 65 65 64 73 2e 20 7b 45 4e 44 7d 20 20 41 64 64  eeds. {END}  Add
fc60: 69 74 69 6f 6e 61 6c 0a 2a 2a 20 6d 65 6d 6f 72  itional.** memor
fc70: 79 20 61 6c 6c 6f 63 61 74 6f 72 20 6f 70 74 69  y allocator opti
fc80: 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ons may be added
fc90: 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
fca0: 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51  ses..**.** In SQ
fcb0: 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35  Lite version 3.5
fcc0: 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74  .0 and 3.5.1, it
fcd0: 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f   was possible to
fce0: 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53   define.** the S
fcf0: 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52  QLITE_OMIT_MEMOR
fd00: 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69  Y_ALLOCATION whi
fd10: 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74  ch would cause t
fd20: 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69  he built-in.** i
fd30: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
fd40: 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
fd50: 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20  to be omitted.  
fd60: 54 68 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a  That capability.
fd70: 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20  ** is no longer 
fd80: 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20  provided.  Only 
fd90: 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20  built-in memory 
fda0: 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62  allocators can b
fdb0: 65 0a 2a 2a 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a  e.** used..**.**
fdc0: 20 54 68 65 20 77 69 6e 64 6f 77 73 20 4f 53 20   The windows OS 
fdd0: 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 20  interface layer 
fde0: 63 61 6c 6c 73 0a 2a 2a 20 74 68 65 20 73 79 73  calls.** the sys
fdf0: 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64  tem malloc() and
fe00: 20 66 72 65 65 28 29 20 64 69 72 65 63 74 6c 79   free() directly
fe10: 20 77 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67   when converting
fe20: 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65  .** filenames be
fe30: 74 77 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20  tween the UTF-8 
fe40: 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79  encoding used by
fe50: 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77   SQLite.** and w
fe60: 68 61 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65  hatever filename
fe70: 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65   encoding is use
fe80: 64 20 62 79 20 74 68 65 20 70 61 72 74 69 63 75  d by the particu
fe90: 6c 61 72 20 77 69 6e 64 6f 77 73 0a 2a 2a 20 69  lar windows.** i
fea0: 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65  nstallation.  Me
feb0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
fec0: 65 72 72 6f 72 73 20 61 72 65 20 64 65 74 65 63  errors are detec
fed0: 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79  ted, but.** they
fee0: 20 61 72 65 20 72 65 70 6f 72 74 65 64 20 62 61   are reported ba
fef0: 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41  ck as [SQLITE_CA
ff00: 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53  NTOPEN] or.** [S
ff10: 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74  QLITE_IOERR] rat
ff20: 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
ff30: 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 49  _NOMEM]..**.** I
ff40: 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
ff50: 20 7b 46 31 37 33 30 33 7d 20 20 54 68 65 20 5b   {F17303}  The [
ff60: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e  sqlite3_malloc(N
ff70: 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
ff80: 75 72 6e 73 20 65 69 74 68 65 72 20 61 20 70 6f  urns either a po
ff90: 69 6e 74 65 72 20 74 6f 20 0a 2a 2a 20 20 20 20  inter to .**    
ffa0: 20 20 20 20 20 20 20 6e 65 77 6c 79 20 63 68 65         newly che
ffb0: 63 6b 65 64 2d 6f 75 74 20 62 6c 6f 63 6b 20 6f  cked-out block o
ffc0: 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74  f at least N byt
ffd0: 65 73 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20  es of memory.** 
ffe0: 20 20 20 20 20 20 20 20 20 20 74 68 61 74 20 69            that i
fff0: 73 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64  s 8-byte aligned
10000 2c 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  , .**           
10010 6f 72 20 69 74 20 72 65 74 75 72 6e 73 20 4e 55  or it returns NU
10020 4c 4c 20 69 66 20 69 74 20 69 73 20 75 6e 61 62  LL if it is unab
10030 6c 65 20 74 6f 20 66 75 6c 66 69 6c 6c 20 74 68  le to fulfill th
10040 65 20 72 65 71 75 65 73 74 2e 0a 2a 2a 0a 2a 2a  e request..**.**
10050 20 7b 46 31 37 33 30 34 7d 20 20 54 68 65 20 5b   {F17304}  The [
10060 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e  sqlite3_malloc(N
10070 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
10080 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  urns a NULL poin
10090 74 65 72 20 69 66 0a 2a 2a 20 20 20 20 20 20 20  ter if.**       
100a0 20 20 20 20 4e 20 69 73 20 6c 65 73 73 20 74 68      N is less th
100b0 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a  an or equal to z
100c0 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33  ero..**.** {F173
100d0 30 35 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65  05}  The [sqlite
100e0 33 5f 66 72 65 65 28 50 29 5d 20 69 6e 74 65 72  3_free(P)] inter
100f0 66 61 63 65 20 72 65 6c 65 61 73 65 73 20 6d 65  face releases me
10100 6d 6f 72 79 20 70 72 65 76 69 6f 75 73 6c 79 0a  mory previously.
10110 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72 65 74  **           ret
10120 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  urned from [sqli
10130 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72  te3_malloc()] or
10140 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
10150 63 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  c()],.**        
10160 20 20 20 6d 61 6b 69 6e 67 20 69 74 20 61 76 61     making it ava
10170 69 6c 61 62 6c 65 20 66 6f 72 20 72 65 75 73 65  ilable for reuse
10180 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 30 36 7d  ..**.** {F17306}
10190 20 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c    A call to [sql
101a0 69 74 65 33 5f 66 72 65 65 28 4e 55 4c 4c 29 5d  ite3_free(NULL)]
101b0 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e   is a harmless n
101c0 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37  o-op..**.** {F17
101d0 33 31 30 7d 20 20 41 20 63 61 6c 6c 20 74 6f 20  310}  A call to 
101e0 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
101f0 28 30 2c 4e 29 5d 20 69 73 20 65 71 75 69 76 61  (0,N)] is equiva
10200 6c 65 6e 74 20 74 6f 20 61 20 63 61 6c 6c 0a 2a  lent to a call.*
10210 2a 20 20 20 20 20 20 20 20 20 20 20 74 6f 20 5b  *           to [
10220 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e  sqlite3_malloc(N
10230 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 31  )]..**.** {F1731
10240 32 7d 20 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73  2}  A call to [s
10250 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 50  qlite3_realloc(P
10260 2c 30 29 5d 20 69 73 20 65 71 75 69 76 61 6c 65  ,0)] is equivale
10270 6e 74 20 74 6f 20 61 20 63 61 6c 6c 0a 2a 2a 20  nt to a call.** 
10280 20 20 20 20 20 20 20 20 20 20 74 6f 20 5b 73 71            to [sq
10290 6c 69 74 65 33 5f 66 72 65 65 28 50 29 5d 2e 0a  lite3_free(P)]..
102a0 2a 2a 0a 2a 2a 20 7b 46 31 37 33 31 35 7d 20 20  **.** {F17315}  
102b0 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  The SQLite core 
102c0 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 61  uses [sqlite3_ma
102d0 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65  lloc()], [sqlite
102e0 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a  3_realloc()],.**
102f0 20 20 20 20 20 20 20 20 20 20 20 61 6e 64 20 5b             and [
10300 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
10310 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6d  for all of its m
10320 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
10330 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20   and.**         
10340 20 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e    deallocation n
10350 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37  eeds..**.** {F17
10360 33 31 38 7d 20 20 54 68 65 20 5b 73 71 6c 69 74  318}  The [sqlit
10370 65 33 5f 72 65 61 6c 6c 6f 63 28 50 2c 4e 29 5d  e3_realloc(P,N)]
10380 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
10390 6e 73 20 65 69 74 68 65 72 20 61 20 70 6f 69 6e  ns either a poin
103a0 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ter.**          
103b0 20 74 6f 20 61 20 62 6c 6f 63 6b 20 6f 66 20 63   to a block of c
103c0 68 65 63 6b 65 64 2d 6f 75 74 20 6d 65 6d 6f 72  hecked-out memor
103d0 79 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20  y of at least N 
103e0 62 79 74 65 73 20 69 6e 20 73 69 7a 65 0a 2a 2a  bytes in size.**
103f0 20 20 20 20 20 20 20 20 20 20 20 74 68 61 74 20             that 
10400 69 73 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65  is 8-byte aligne
10410 64 2c 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69  d, or a NULL poi
10420 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37  nter..**.** {F17
10430 33 32 31 7d 20 20 57 68 65 6e 20 5b 73 71 6c 69  321}  When [sqli
10440 74 65 33 5f 72 65 61 6c 6c 6f 63 28 50 2c 4e 29  te3_realloc(P,N)
10450 5d 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d  ] returns a non-
10460 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 74  NULL pointer, it
10470 20 66 69 72 73 74 0a 2a 2a 20 20 20 20 20 20 20   first.**       
10480 20 20 20 20 63 6f 70 69 65 73 20 74 68 65 20 66      copies the f
10490 69 72 73 74 20 4b 20 62 79 74 65 73 20 6f 66 20  irst K bytes of 
104a0 63 6f 6e 74 65 6e 74 20 66 72 6f 6d 20 50 20 69  content from P i
104b0 6e 74 6f 20 74 68 65 20 6e 65 77 6c 79 20 61 6c  nto the newly al
104c0 6c 6f 63 61 74 65 64 0a 2a 2a 20 20 20 20 20 20  located.**      
104d0 20 20 20 20 20 77 68 65 72 65 20 4b 20 69 73 20       where K is 
104e0 74 68 65 20 6c 65 73 73 6f 72 20 6f 66 20 4e 20  the lessor of N 
104f0 61 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20  and the size of 
10500 74 68 65 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a  the buffer P..**
10510 0a 2a 2a 20 7b 46 31 37 33 32 32 7d 20 20 57 68  .** {F17322}  Wh
10520 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  en [sqlite3_real
10530 6c 6f 63 28 50 2c 4e 29 5d 20 72 65 74 75 72 6e  loc(P,N)] return
10540 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69  s a non-NULL poi
10550 6e 74 65 72 2c 20 69 74 20 66 69 72 73 74 0a 2a  nter, it first.*
10560 2a 20 20 20 20 20 20 20 20 20 20 20 72 65 6c 65  *           rele
10570 61 73 65 73 20 74 68 65 20 62 75 66 66 65 72 20  ases the buffer 
10580 50 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 32 33  P..**.** {F17323
10590 7d 20 20 57 68 65 6e 20 5b 73 71 6c 69 74 65 33  }  When [sqlite3
105a0 5f 72 65 61 6c 6c 6f 63 28 50 2c 4e 29 5d 20 72  _realloc(P,N)] r
105b0 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74 68 65  eturns NULL, the
105c0 20 62 75 66 66 65 72 20 50 20 69 73 0a 2a 2a 20   buffer P is.** 
105d0 20 20 20 20 20 20 20 20 20 20 6e 6f 74 20 6d 6f            not mo
105e0 64 69 66 69 65 64 20 6f 72 20 72 65 6c 65 61 73  dified or releas
105f0 65 64 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49 54 41  ed..**.** LIMITA
10600 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 55 31  TIONS:.**.** {U1
10610 37 33 35 30 7d 20 20 54 68 65 20 70 6f 69 6e 74  7350}  The point
10620 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  er arguments to 
10630 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
10640 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65   and [sqlite3_re
10650 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 20 20 20 20  alloc()].**     
10660 20 20 20 20 20 20 6d 75 73 74 20 62 65 20 65 69        must be ei
10670 74 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73  ther NULL or els
10680 65 20 61 20 70 6f 69 6e 74 65 72 20 6f 62 74 61  e a pointer obta
10690 69 6e 65 64 20 66 72 6f 6d 20 61 20 70 72 69 6f  ined from a prio
106a0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 69  r.**           i
106b0 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71  nvocation of [sq
106c0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
106d0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  or [sqlite3_real
106e0 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61 73 0a  loc()] that has.
106f0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6e 6f 74  **           not
10700 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a   been released..
10710 2a 2a 0a 2a 2a 20 7b 55 31 37 33 35 31 7d 20 20  **.** {U17351}  
10720 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
10730 6d 75 73 74 20 6e 6f 74 20 72 65 61 64 20 6f 72  must not read or
10740 20 77 72 69 74 65 20 61 6e 79 20 70 61 72 74 20   write any part 
10750 6f 66 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  of .**          
10760 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f   a block of memo
10770 72 79 20 61 66 74 65 72 20 69 74 20 68 61 73 20  ry after it has 
10780 62 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73  been released us
10790 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ing.**          
107a0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
107b0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
107c0 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 0a 2a 2f 0a  alloc()]..**.*/.
107d0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61  void *sqlite3_ma
107e0 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20  lloc(int);.void 
107f0 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  *sqlite3_realloc
10800 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f  (void*, int);.vo
10810 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  id sqlite3_free(
10820 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
10830 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20  API3REF: Memory 
10840 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74 69 73  Allocator Statis
10850 74 69 63 73 20 7b 46 31 37 33 37 30 7d 0a 2a 2a  tics {F17370}.**
10860 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 69  .** SQLite provi
10870 64 65 73 20 74 68 65 73 65 20 74 77 6f 20 69 6e  des these two in
10880 74 65 72 66 61 63 65 73 20 66 6f 72 20 72 65 70  terfaces for rep
10890 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 74  orting on the st
108a0 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  atus.** of the [
108b0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
108c0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ], [sqlite3_free
108d0 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ()], and [sqlite
108e0 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20  3_realloc()].** 
108f0 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
10900 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 20  ation subsystem 
10910 69 6e 63 6c 75 64 65 64 20 77 69 74 68 69 6e 20  included within 
10920 74 68 65 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a  the SQLite..**.*
10930 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
10940 0a 2a 2a 20 7b 46 31 37 33 37 31 7d 20 54 68 65  .** {F17371} The
10950 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
10960 5f 75 73 65 64 28 29 5d 20 72 6f 75 74 69 6e 65  _used()] routine
10970 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20   returns the.** 
10980 20 20 20 20 20 20 20 20 20 6e 75 6d 62 65 72 20           number 
10990 6f 66 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f  of bytes of memo
109a0 72 79 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 74  ry currently out
109b0 73 74 61 6e 64 69 6e 67 20 0a 2a 2a 20 20 20 20  standing .**    
109c0 20 20 20 20 20 20 28 6d 61 6c 6c 6f 63 65 64 20        (malloced 
109d0 62 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a  but not freed)..
109e0 2a 2a 0a 2a 2a 20 7b 46 31 37 33 37 33 7d 20 54  **.** {F17373} T
109f0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  he [sqlite3_memo
10a00 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20  ry_highwater()] 
10a10 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
10a20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 20  the maximum.**  
10a30 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 6f 66          value of
10a40 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
10a50 5f 75 73 65 64 28 29 5d 20 0a 2a 2a 20 20 20 20  _used()] .**    
10a60 20 20 20 20 20 20 73 69 6e 63 65 20 74 68 65 20        since the 
10a70 68 69 67 68 77 61 74 65 72 20 6d 61 72 6b 20 77  highwater mark w
10a80 61 73 20 6c 61 73 74 20 72 65 73 65 74 2e 0a 2a  as last reset..*
10a90 2a 0a 2a 2a 20 7b 46 31 37 33 37 34 7d 20 54 68  *.** {F17374} Th
10aa0 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65  e values returne
10ab0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65  d by [sqlite3_me
10ac0 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 61 6e 64  mory_used()] and
10ad0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
10ae0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
10af0 68 77 61 74 65 72 28 29 5d 20 69 6e 63 6c 75 64  hwater()] includ
10b00 65 20 61 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a  e any overhead.*
10b10 2a 20 20 20 20 20 20 20 20 20 20 61 64 64 65 64  *          added
10b20 20 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69 74   by SQLite in it
10b30 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  s implementation
10b40 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   of [sqlite3_mal
10b50 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20  loc()],.**      
10b60 20 20 20 20 62 75 74 20 6e 6f 74 20 6f 76 65 72      but not over
10b70 68 65 61 64 20 61 64 64 65 64 20 62 79 20 74 68  head added by th
10b80 65 20 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67  e any underlying
10b90 20 73 79 73 74 65 6d 20 6c 69 62 72 61 72 79 0a   system library.
10ba0 2a 2a 20 20 20 20 20 20 20 20 20 20 72 6f 75 74  **          rout
10bb0 69 6e 65 73 20 74 68 61 74 20 5b 73 71 6c 69 74  ines that [sqlit
10bc0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79  e3_malloc()] may
10bd0 20 63 61 6c 6c 2e 0a 2a 2a 20 0a 2a 2a 20 7b 46   call..** .** {F
10be0 31 37 33 37 35 7d 20 54 68 65 20 6d 65 6d 6f 72  17375} The memor
10bf0 79 20 68 69 67 68 77 61 74 65 72 20 6d 61 72 6b  y highwater mark
10c00 20 69 73 20 72 65 73 65 74 20 74 6f 20 74 68 65   is reset to the
10c10 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f   current value o
10c20 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  f.**          [s
10c30 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
10c40 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c  ed()] if and onl
10c50 79 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  y if the paramet
10c60 65 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20  er to.**        
10c70 20 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72    [sqlite3_memor
10c80 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 69  y_highwater()] i
10c90 73 20 74 72 75 65 2e 20 20 54 68 65 20 76 61 6c  s true.  The val
10ca0 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 20  ue returned.**  
10cb0 20 20 20 20 20 20 20 20 62 79 20 5b 73 71 6c 69          by [sqli
10cc0 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
10cd0 61 74 65 72 28 31 29 5d 20 69 73 20 74 68 65 20  ater(1)] is the 
10ce0 68 69 67 68 77 61 74 65 72 20 6d 61 72 6b 0a 2a  highwater mark.*
10cf0 2a 20 20 20 20 20 20 20 20 20 20 70 72 69 6f 72  *          prior
10d00 20 74 6f 20 74 68 65 20 72 65 73 65 74 2e 0a 2a   to the reset..*
10d10 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  /.sqlite3_int64 
10d20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
10d30 73 65 64 28 76 6f 69 64 29 3b 0a 73 71 6c 69 74  sed(void);.sqlit
10d40 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
10d50 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
10d60 72 28 69 6e 74 20 72 65 73 65 74 46 6c 61 67 29  r(int resetFlag)
10d70 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
10d80 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20  F: Compile-Time 
10d90 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61  Authorization Ca
10da0 6c 6c 62 61 63 6b 73 20 7b 46 31 32 35 30 30 7d  llbacks {F12500}
10db0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
10dc0 69 6e 65 20 72 65 67 69 73 74 65 72 73 20 61 20  ine registers a 
10dd0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
10de0 61 63 6b 20 77 69 74 68 20 61 20 70 61 72 74 69  ack with a parti
10df0 63 75 6c 61 72 0a 2a 2a 20 64 61 74 61 62 61 73  cular.** databas
10e00 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 73 75  e connection, su
10e10 70 70 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69  pplied in the fi
10e20 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  rst argument..**
10e30 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   The authorizer 
10e40 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
10e50 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61 74 65  ked as SQL state
10e60 6d 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20  ments are being 
10e70 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b  compiled.** by [
10e80 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
10e90 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e  )] or its varian
10ea0 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ts [sqlite3_prep
10eb0 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73  are_v2()],.** [s
10ec0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
10ed0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
10ee0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
10ef0 2e 20 20 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a  .  At various.**
10f00 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74   points during t
10f10 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70  he compilation p
10f20 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63  rocess, as logic
10f30 20 69 73 20 62 65 69 6e 67 20 63 72 65 61 74 65   is being create
10f40 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20  d.** to perform 
10f50 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c  various actions,
10f60 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
10f70 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
10f80 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66  ked to.** see if
10f90 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61   those actions a
10fa0 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 54 68 65  re allowed.  The
10fb0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
10fc0 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72  back should.** r
10fd0 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20  eturn SQLITE_OK 
10fe0 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74  to allow the act
10ff0 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e  ion, [SQLITE_IGN
11000 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77  ORE] to disallow
11010 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63   the.** specific
11020 20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f   action but allo
11030 77 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  w the SQL statem
11040 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20  ent to continue 
11050 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65  to be.** compile
11060 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45  d, or [SQLITE_DE
11070 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65  NY] to cause the
11080 20 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74   entire SQL stat
11090 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72  ement to be.** r
110a0 65 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e 20  ejected with an 
110b0 65 72 72 6f 72 2e 20 20 20 49 66 20 74 68 65 20  error.   If the 
110c0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
110d0 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61  ack returns.** a
110e0 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74  ny value other t
110f0 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  han [SQLITE_IGNO
11100 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  RE], [SQLITE_OK]
11110 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e  , or [SQLITE_DEN
11120 59 5d 0a 2a 2a 20 74 68 65 6e 20 5b 73 71 6c 69  Y].** then [sqli
11130 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
11140 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20  ] or equivalent 
11150 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65  call that trigge
11160 72 65 64 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f  red.** the autho
11170 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20  rizer will fail 
11180 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65  with an error me
11190 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65  ssage..**.** Whe
111a0 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  n the callback r
111b0 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
111c0 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74  K], that means t
111d0 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20  he operation.** 
111e0 72 65 71 75 65 73 74 65 64 20 69 73 20 6f 6b 2e  requested is ok.
111f0 20 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62    When the callb
11200 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ack returns [SQL
11210 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a  ITE_DENY], the.*
11220 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
11230 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69  re_v2()] or equi
11240 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74  valent call that
11250 20 74 72 69 67 67 65 72 65 64 20 74 68 65 0a 2a   triggered the.*
11260 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c  * authorizer wil
11270 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65  l fail with an e
11280 72 72 6f 72 20 6d 65 73 73 61 67 65 20 65 78 70  rror message exp
11290 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20  laining that.** 
112a0 61 63 63 65 73 73 20 69 73 20 64 65 6e 69 65 64  access is denied
112b0 2e 20 20 49 66 20 74 68 65 20 61 75 74 68 6f 72  .  If the author
112c0 69 7a 65 72 20 63 6f 64 65 20 69 73 20 5b 53 51  izer code is [SQ
112d0 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e  LITE_READ].** an
112e0 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  d the callback r
112f0 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49  eturns [SQLITE_I
11300 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 20  GNORE] then the 
11310 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74  prepared.** stat
11320 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75  ement is constru
11330 63 74 65 64 20 74 6f 20 69 6e 73 65 72 74 20 61  cted to insert a
11340 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70   NULL value in p
11350 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 74  lace of.** the t
11360 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74  able column that
11370 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62   would have.** b
11380 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51 4c  een read if [SQL
11390 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e  ITE_OK] had been
113a0 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20   returned.  The 
113b0 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a  [SQLITE_IGNORE].
113c0 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e 20 62 65  ** return can be
113d0 20 75 73 65 64 20 74 6f 20 64 65 6e 79 20 61 6e   used to deny an
113e0 20 75 6e 74 72 75 73 74 65 64 20 75 73 65 72 20   untrusted user 
113f0 61 63 63 65 73 73 20 74 6f 20 69 6e 64 69 76 69  access to indivi
11400 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20  dual.** columns 
11410 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 0a 2a  of a table..**.*
11420 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61  * The first para
11430 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74  meter to the aut
11440 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
11450 20 69 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a   is a copy of.**
11460 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
11470 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
11480 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
11490 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e 0a  er() interface..
114a0 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  ** The second pa
114b0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63  rameter to the c
114c0 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e  allback is an in
114d0 74 65 67 65 72 20 0a 2a 2a 20 5b 53 51 4c 49 54  teger .** [SQLIT
114e0 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20  E_COPY | action 
114f0 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63 69  code] that speci
11500 66 69 65 73 20 74 68 65 20 70 61 72 74 69 63 75  fies the particu
11510 6c 61 72 20 61 63 74 69 6f 6e 0a 2a 2a 20 74 6f  lar action.** to
11520 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 20   be authorized. 
11530 54 68 65 20 74 68 69 72 64 20 74 68 72 6f 75 67  The third throug
11540 68 20 73 69 78 74 68 0a 2a 2a 20 70 61 72 61 6d  h sixth.** param
11550 65 74 65 72 73 20 74 6f 20 74 68 65 20 63 61 6c  eters to the cal
11560 6c 62 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74  lback are zero-t
11570 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67  erminated string
11580 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 0a  s that contain .
11590 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 64 65  ** additional de
115a0 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20  tails about the 
115b0 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74  action to be aut
115c0 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 41  horized..**.** A
115d0 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20  n authorizer is 
115e0 75 73 65 64 20 77 68 65 6e 20 70 72 65 70 61 72  used when prepar
115f0 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ing SQL statemen
11600 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75  ts from an untru
11610 73 74 65 64 0a 2a 2a 20 73 6f 75 72 63 65 2c 20  sted.** source, 
11620 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20 74  to ensure that t
11630 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
11640 73 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20  s do not try to 
11650 61 63 63 65 73 73 20 64 61 74 61 0a 2a 2a 20 74  access data.** t
11660 68 61 74 20 74 68 65 79 20 61 72 65 20 6e 6f 74  hat they are not
11670 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c   allowed to see,
11680 20 6f 72 20 74 68 61 74 20 74 68 65 79 20 64 6f   or that they do
11690 20 6e 6f 74 20 74 72 79 20 74 6f 0a 2a 2a 20 65   not try to.** e
116a0 78 65 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 73  xecute malicious
116b0 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74   statements that
116c0 20 64 61 6d 61 67 65 20 74 68 65 20 64 61 74 61   damage the data
116d0 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78  base.  For.** ex
116e0 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63  ample, an applic
116f0 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20  ation may allow 
11700 61 20 75 73 65 72 20 74 6f 20 65 6e 74 65 72 20  a user to enter 
11710 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c  arbitrary.** SQL
11720 20 71 75 65 72 69 65 73 20 66 6f 72 20 65 76 61   queries for eva
11730 6c 75 61 74 69 6f 6e 20 62 79 20 61 20 64 61 74  luation by a dat
11740 61 62 61 73 65 2e 20 20 42 75 74 20 74 68 65 20  abase.  But the 
11750 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73  application does
11760 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 65  .** not want the
11770 20 75 73 65 72 20 74 6f 20 62 65 20 61 62 6c 65   user to be able
11780 20 74 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 61   to make arbitra
11790 72 79 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  ry changes to th
117a0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20  e.** database.  
117b0 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f  An authorizer co
117c0 75 6c 64 20 74 68 65 6e 20 62 65 20 70 75 74 20  uld then be put 
117d0 69 6e 20 70 6c 61 63 65 20 77 68 69 6c 65 20 74  in place while t
117e0 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72  he.** user-enter
117f0 65 64 20 53 51 4c 20 69 73 20 62 65 69 6e 67 20  ed SQL is being 
11800 70 72 65 70 61 72 65 64 20 74 68 61 74 20 64 69  prepared that di
11810 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69  sallows everythi
11820 6e 67 0a 2a 2a 20 65 78 63 65 70 74 20 53 45 4c  ng.** except SEL
11830 45 43 54 20 73 74 61 74 65 6d 65 6e 74 73 2e 20  ECT statements. 
11840 20 0a 2a 2a 0a 2a 2a 20 4f 6e 6c 79 20 61 20 73   .**.** Only a s
11850 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72  ingle authorizer
11860 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65   can be in place
11870 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 63   on a database c
11880 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20  onnection.** at 
11890 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61  a time.  Each ca
118a0 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65  ll to sqlite3_se
118b0 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65  t_authorizer ove
118c0 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72  rrides the.** pr
118d0 65 76 69 6f 75 73 20 63 61 6c 6c 2e 20 20 44 69  evious call.  Di
118e0 73 61 62 6c 65 20 74 68 65 20 61 75 74 68 6f 72  sable the author
118f0 69 7a 65 72 20 62 79 20 69 6e 73 74 61 6c 6c 69  izer by installi
11900 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61  ng a NULL callba
11910 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f  ck..** The autho
11920 72 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65  rizer is disable
11930 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a  d by default..**
11940 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68  .** Note that th
11950 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
11960 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
11970 20 6f 6e 6c 79 20 64 75 72 69 6e 67 20 0a 2a 2a   only during .**
11980 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
11990 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69  e()] or its vari
119a0 61 6e 74 73 2e 20 20 41 75 74 68 6f 72 69 7a 61  ants.  Authoriza
119b0 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70  tion is not.** p
119c0 65 72 66 6f 72 6d 65 64 20 64 75 72 69 6e 67 20  erformed during 
119d0 73 74 61 74 65 6d 65 6e 74 20 65 76 61 6c 75 61  statement evalua
119e0 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33  tion in [sqlite3
119f0 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _step()]..**.** 
11a00 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
11a10 2a 20 7b 46 31 32 35 30 31 7d 20 54 68 65 20 5b  * {F12501} The [
11a20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
11a30 6f 72 69 7a 65 72 28 44 2c 2e 2e 2e 29 5d 20 69  orizer(D,...)] i
11a40 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65  nterface registe
11a50 72 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20  rs a.**         
11a60 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
11a70 62 61 63 6b 20 77 69 74 68 20 64 61 74 61 62 61  back with databa
11a80 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e  se connection D.
11a90 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 30 32 7d 20  .**.** {F12502} 
11aa0 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  The authorizer c
11ab0 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
11ac0 65 64 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d  ed as SQL statem
11ad0 65 6e 74 73 20 61 72 65 0a 2a 2a 20 20 20 20 20  ents are.**     
11ae0 20 20 20 20 20 62 65 69 6e 67 20 63 6f 6d 70 69       being compi
11af0 6c 65 64 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 30  led.**.** {F1250
11b00 33 7d 20 49 66 20 74 68 65 20 61 75 74 68 6f 72  3} If the author
11b10 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65  izer callback re
11b20 74 75 72 6e 73 20 61 6e 79 20 76 61 6c 75 65 20  turns any value 
11b30 6f 74 68 65 72 20 74 68 61 6e 0a 2a 2a 20 20 20  other than.**   
11b40 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 49         [SQLITE_I
11b50 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f  GNORE], [SQLITE_
11b60 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OK], or [SQLITE_
11b70 44 45 4e 59 5d 20 74 68 65 6e 0a 2a 2a 20 20 20  DENY] then.**   
11b80 20 20 20 20 20 20 20 74 68 65 20 5b 73 71 6c 69         the [sqli
11b90 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
11ba0 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20  ] or equivalent 
11bb0 63 61 6c 6c 20 74 68 61 74 20 63 61 75 73 65 64  call that caused
11bc0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
11bd0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
11be0 62 61 63 6b 20 74 6f 20 72 75 6e 20 73 68 61 6c  back to run shal
11bf0 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 0a 2a  l fail with an.*
11c00 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49  *          [SQLI
11c10 54 45 5f 45 52 52 4f 52 5d 20 65 72 72 6f 72 20  TE_ERROR] error 
11c20 63 6f 64 65 20 61 6e 64 20 61 6e 20 61 70 70 72  code and an appr
11c30 6f 70 72 69 61 74 65 20 65 72 72 6f 72 20 6d 65  opriate error me
11c40 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  ssage..**.** {F1
11c50 32 35 30 34 7d 20 57 68 65 6e 20 74 68 65 20 61  2504} When the a
11c60 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
11c70 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ck returns [SQLI
11c80 54 45 5f 4f 4b 5d 2c 20 74 68 65 20 6f 70 65 72  TE_OK], the oper
11c90 61 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20  ation.**        
11ca0 20 20 64 65 73 63 72 69 62 65 64 20 69 73 20 63    described is c
11cb0 6f 64 65 64 20 6e 6f 72 6d 61 6c 6c 79 2e 0a 2a  oded normally..*
11cc0 2a 0a 2a 2a 20 7b 46 31 32 35 30 35 7d 20 57 68  *.** {F12505} Wh
11cd0 65 6e 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  en the authorize
11ce0 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  r callback retur
11cf0 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d  ns [SQLITE_DENY]
11d00 2c 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  , the.**        
11d10 20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61    [sqlite3_prepa
11d20 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69  re_v2()] or equi
11d30 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74  valent call that
11d40 20 63 61 75 73 65 64 20 74 68 65 0a 2a 2a 20 20   caused the.**  
11d50 20 20 20 20 20 20 20 20 61 75 74 68 6f 72 69 7a          authoriz
11d60 65 72 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 72  er callback to r
11d70 75 6e 20 73 68 61 6c 6c 20 66 61 69 6c 0a 2a 2a  un shall fail.**
11d80 20 20 20 20 20 20 20 20 20 20 77 69 74 68 20 61            with a
11d90 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  n [SQLITE_ERROR]
11da0 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20   error code and 
11db0 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
11dc0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 78 70  .**          exp
11dd0 6c 61 69 6e 69 6e 67 20 74 68 61 74 20 61 63 63  laining that acc
11de0 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e 0a 2a  ess is denied..*
11df0 2a 0a 2a 2a 20 7b 46 31 32 35 30 36 7d 20 49 66  *.** {F12506} If
11e00 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
11e10 63 6f 64 65 20 28 74 68 65 20 32 6e 64 20 70 61  code (the 2nd pa
11e20 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61  rameter to the a
11e30 75 74 68 6f 72 69 7a 65 72 0a 2a 2a 20 20 20 20  uthorizer.**    
11e40 20 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 29 20        callback) 
11e50 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d  is [SQLITE_READ]
11e60 20 61 6e 64 20 74 68 65 20 61 75 74 68 6f 72 69   and the authori
11e70 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  zer callback ret
11e80 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  urns.**         
11e90 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
11ea0 20 74 68 65 6e 20 74 68 65 20 70 72 65 70 61 72   then the prepar
11eb0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  ed statement is 
11ec0 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 0a 2a  constructed to.*
11ed0 2a 20 20 20 20 20 20 20 20 20 20 69 6e 73 65 72  *          inser
11ee0 74 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69  t a NULL value i
11ef0 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74  n place of the t
11f00 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74  able column that
11f10 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 20   would have.**  
11f20 20 20 20 20 20 20 20 20 62 65 65 6e 20 72 65 61          been rea
11f30 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  d if [SQLITE_OK]
11f40 20 68 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e   had been return
11f50 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 30  ed..**.** {F1250
11f60 37 7d 20 49 66 20 74 68 65 20 61 75 74 68 6f 72  7} If the author
11f70 69 7a 65 72 20 63 6f 64 65 20 28 74 68 65 20 32  izer code (the 2
11f80 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
11f90 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 0a 2a  the authorizer.*
11fa0 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c 62  *          callb
11fb0 61 63 6b 29 20 69 73 20 61 6e 79 74 68 69 6e 67  ack) is anything
11fc0 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
11fd0 49 54 45 5f 52 45 41 44 5d 2c 20 74 68 65 6e 0a  ITE_READ], then.
11fe0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 72 65  **          a re
11ff0 74 75 72 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f  turn of [SQLITE_
12000 49 47 4e 4f 52 45 5d 20 68 61 73 20 74 68 65 20  IGNORE] has the 
12010 73 61 6d 65 20 65 66 66 65 63 74 20 61 73 20 5b  same effect as [
12020 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2e 20 0a 2a  SQLITE_DENY]. .*
12030 2a 0a 2a 2a 20 7b 46 31 32 35 31 30 7d 20 54 68  *.** {F12510} Th
12040 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
12050 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69  r to the authori
12060 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
12070 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 20 20 20  a copy of.**    
12080 20 20 20 20 20 20 74 68 65 20 74 68 69 72 64 20        the third 
12090 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
120a0 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
120b0 74 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65  thorizer()] inte
120c0 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  rface..**.** {F1
120d0 32 35 31 31 7d 20 54 68 65 20 73 65 63 6f 6e 64  2511} The second
120e0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
120f0 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e  e callback is an
12100 20 69 6e 74 65 67 65 72 20 0a 2a 2a 20 20 20 20   integer .**    
12110 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 43 4f        [SQLITE_CO
12120 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65  PY | action code
12130 5d 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73  ] that specifies
12140 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20   the particular 
12150 61 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20  action.**       
12160 20 20 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69     to be authori
12170 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35  zed..**.** {F125
12180 31 32 7d 20 54 68 65 20 74 68 69 72 64 20 74 68  12} The third th
12190 72 6f 75 67 68 20 73 69 78 74 68 20 70 61 72 61  rough sixth para
121a0 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20 63 61  meters to the ca
121b0 6c 6c 62 61 63 6b 20 61 72 65 0a 2a 2a 20 20 20  llback are.**   
121c0 20 20 20 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d         zero-term
121d0 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74  inated strings t
121e0 68 61 74 20 63 6f 6e 74 61 69 6e 20 0a 2a 2a 20  hat contain .** 
121f0 20 20 20 20 20 20 20 20 20 61 64 64 69 74 69 6f           additio
12200 6e 61 6c 20 64 65 74 61 69 6c 73 20 61 62 6f 75  nal details abou
12210 74 20 74 68 65 20 61 63 74 69 6f 6e 20 74 6f 20  t the action to 
12220 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a  be authorized..*
12230 2a 0a 2a 2a 20 7b 46 31 32 35 32 30 7d 20 45 61  *.** {F12520} Ea
12240 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ch call to [sqli
12250 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
12260 65 72 28 29 5d 20 6f 76 65 72 72 69 64 65 73 20  er()] overrides 
12270 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
12280 61 6e 79 20 70 72 65 76 69 6f 75 73 6c 79 20 69  any previously i
12290 6e 73 74 61 6c 6c 65 64 20 61 75 74 68 6f 72 69  nstalled authori
122a0 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35  zer..**.** {F125
122b0 32 31 7d 20 41 20 4e 55 4c 4c 20 61 75 74 68 6f  21} A NULL autho
122c0 72 69 7a 65 72 20 6d 65 61 6e 73 20 74 68 61 74  rizer means that
122d0 20 6e 6f 20 61 75 74 68 6f 72 69 7a 61 74 69 6f   no authorizatio
122e0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61  n.**          ca
122f0 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
12300 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 32 32  d..**.** {F12522
12310 7d 20 54 68 65 20 64 65 66 61 75 6c 74 20 61 75  } The default au
12320 74 68 6f 72 69 7a 65 72 20 69 73 20 4e 55 4c 4c  thorizer is NULL
12330 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
12340 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
12350 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69  .  sqlite3*,.  i
12360 6e 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64  nt (*xAuth)(void
12370 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72  *,int,const char
12380 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f  *,const char*,co
12390 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20  nst char*,const 
123a0 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a  char*),.  void *
123b0 70 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a  pUserData.);../*
123c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75  .** CAPI3REF: Au
123d0 74 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20  thorizer Return 
123e0 43 6f 64 65 73 20 7b 46 31 32 35 39 30 7d 0a 2a  Codes {F12590}.*
123f0 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  *.** The [sqlite
12400 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
12410 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61   | authorizer ca
12420 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d  llback function]
12430 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20   must.** return 
12440 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f  either [SQLITE_O
12450 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65  K] or one of the
12460 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73  se two constants
12470 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20   in order.** to 
12480 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 68  signal SQLite wh
12490 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
124a0 20 61 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69   action is permi
124b0 74 74 65 64 2e 20 20 53 65 65 20 74 68 65 0a 2a  tted.  See the.*
124c0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  * [sqlite3_set_a
124d0 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68  uthorizer | auth
124e0 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61  orizer documenta
124f0 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 69  tion] for additi
12500 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  onal.** informat
12510 69 6f 6e 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ion..*/.#define 
12520 53 51 4c 49 54 45 5f 44 45 4e 59 20 20 20 31 20  SQLITE_DENY   1 
12530 20 20 2f 2a 20 41 62 6f 72 74 20 74 68 65 20 53    /* Abort the S
12540 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74  QL statement wit
12550 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64  h an error */.#d
12560 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e  efine SQLITE_IGN
12570 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74  ORE 2   /* Don't
12580 20 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20 62   allow access, b
12590 75 74 20 64 6f 6e 27 74 20 67 65 6e 65 72 61 74  ut don't generat
125a0 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f  e an error */../
125b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41  *.** CAPI3REF: A
125c0 75 74 68 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e  uthorizer Action
125d0 20 43 6f 64 65 73 20 7b 46 31 32 35 35 30 7d 0a   Codes {F12550}.
125e0 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  **.** The [sqlit
125f0 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
12600 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  r()] interface r
12610 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62  egisters a callb
12620 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ack function.** 
12630 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20  that is invoked 
12640 74 6f 20 61 75 74 68 6f 72 69 7a 65 72 20 63 65  to authorizer ce
12650 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d  rtain SQL statem
12660 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68  ent actions.  Th
12670 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61  e.** second para
12680 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c  meter to the cal
12690 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65  lback is an inte
126a0 67 65 72 20 63 6f 64 65 20 74 68 61 74 20 73 70  ger code that sp
126b0 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20  ecifies.** what 
126c0 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20  action is being 
126d0 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65  authorized.  The
126e0 73 65 20 61 72 65 20 74 68 65 20 69 6e 74 65 67  se are the integ
126f0 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20  er action codes 
12700 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68  that.** the auth
12710 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
12720 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a  may be passed..*
12730 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f  *.** These actio
12740 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69  n code values si
12750 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20  gnify what kind 
12760 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  of operation is 
12770 74 6f 20 62 65 20 0a 2a 2a 20 61 75 74 68 6f 72  to be .** author
12780 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20 61  ized.  The 3rd a
12790 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  nd 4th parameter
127a0 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69  s to the authori
127b0 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61  zation.** callba
127c0 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c  ck function will
127d0 20 62 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f   be parameters o
127e0 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67  r NULL depending
127f0 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68 65   on which of the
12800 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 75  se.** codes is u
12810 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  sed as the secon
12820 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68  d parameter.  Th
12830 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 5th parameter 
12840 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72  to the.** author
12850 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
12860 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
12870 20 64 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e   database ("main
12880 22 2c 20 22 74 65 6d 70 22 2c 20 0a 2a 2a 20 65  ", "temp", .** e
12890 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62  tc.) if applicab
128a0 6c 65 2e 20 20 54 68 65 20 36 74 68 20 70 61 72  le.  The 6th par
128b0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75  ameter to the au
128c0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
128d0 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65  k.** is the name
128e0 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f   of the inner-mo
128f0 73 74 20 74 72 69 67 67 65 72 20 6f 72 20 76 69  st trigger or vi
12900 65 77 20 74 68 61 74 20 69 73 20 72 65 73 70 6f  ew that is respo
12910 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68  nsible for.** th
12920 65 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74  e access attempt
12930 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73   or NULL if this
12940 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20   access attempt 
12950 69 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d  is directly from
12960 20 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53   .** top-level S
12970 51 4c 20 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 49  QL code..**.** I
12980 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
12990 20 7b 46 31 32 35 35 31 7d 20 54 68 65 20 73 65   {F12551} The se
129a0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74  cond parameter t
129b0 6f 20 61 6e 20 0a 2a 2a 20 20 20 20 20 20 20 20  o an .**        
129c0 20 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61    [sqlite3_set_a
129d0 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68  uthorizer | auth
129e0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
129f0 69 73 20 61 6c 77 61 79 73 20 61 6e 20 69 6e 74  is always an int
12a00 65 67 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  eger.**         
12a10 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20   [SQLITE_COPY | 
12a20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 64 65 5d  authorizer code]
12a30 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 20   that specifies 
12a40 77 68 61 74 20 61 63 74 69 6f 6e 0a 2a 2a 20 20  what action.**  
12a50 20 20 20 20 20 20 20 20 69 73 20 62 65 69 6e 67          is being
12a60 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a   authorized..**.
12a70 2a 2a 20 7b 46 31 32 35 35 32 7d 20 54 68 65 20  ** {F12552} The 
12a80 33 72 64 20 61 6e 64 20 34 74 68 20 70 61 72 61  3rd and 4th para
12a90 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20 0a 2a  meters to the .*
12aa0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
12ab0 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
12ac0 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 61 74 69  er | authorizati
12ad0 6f 6e 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  on callback func
12ae0 74 69 6f 6e 5d 0a 2a 2a 20 20 20 20 20 20 20 20  tion].**        
12af0 20 20 77 69 6c 6c 20 62 65 20 70 61 72 61 6d 65    will be parame
12b00 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70  ters or NULL dep
12b10 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63 68 20  ending on which 
12b20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51  .**          [SQ
12b30 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 75 74 68  LITE_COPY | auth
12b40 6f 72 69 7a 65 72 20 63 6f 64 65 5d 20 69 73 20  orizer code] is 
12b50 75 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  used as the seco
12b60 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  nd parameter..**
12b70 0a 2a 2a 20 7b 46 31 32 35 35 33 7d 20 54 68 65  .** {F12553} The
12b80 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
12b90 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  o the.**        
12ba0 20 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61    [sqlite3_set_a
12bb0 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68  uthorizer | auth
12bc0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 5d  orizer callback]
12bd0 20 69 73 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20   is the name.** 
12be0 20 20 20 20 20 20 20 20 20 6f 66 20 74 68 65 20           of the 
12bf0 64 61 74 61 62 61 73 65 20 28 65 78 61 6d 70 6c  database (exampl
12c00 65 3a 20 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70  e: "main", "temp
12c10 22 2c 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c  ", etc.) if appl
12c20 69 63 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46  icable..**.** {F
12c30 31 32 35 35 34 7d 20 54 68 65 20 36 74 68 20 70  12554} The 6th p
12c40 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a  arameter to the.
12c50 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
12c60 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
12c70 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72  zer | authorizer
12c80 20 63 61 6c 6c 62 61 63 6b 5d 20 69 73 20 74 68   callback] is th
12c90 65 20 6e 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20  e name.**       
12ca0 20 20 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d     of the inner-
12cb0 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72 20  most trigger or 
12cc0 76 69 65 77 20 74 68 61 74 20 69 73 20 72 65 73  view that is res
12cd0 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20  ponsible for.** 
12ce0 20 20 20 20 20 20 20 20 20 74 68 65 20 61 63 63           the acc
12cf0 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72 20 4e  ess attempt or N
12d00 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63 63 65  ULL if this acce
12d10 73 73 20 61 74 74 65 6d 70 74 20 69 73 20 64 69  ss attempt is di
12d20 72 65 63 74 6c 79 20 66 72 6f 6d 20 0a 2a 2a 20  rectly from .** 
12d30 20 20 20 20 20 20 20 20 20 74 6f 70 2d 6c 65 76           top-lev
12d40 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a  el SQL code..*/.
12d50 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  /***************
12d60 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
12d70 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64  ************ 3rd
12d80 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74   ************ 4t
12d90 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23  h ***********/.#
12da0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
12db0 45 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20  EATE_INDEX      
12dc0 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78      1   /* Index
12dd0 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
12de0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
12df0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
12e00 41 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20  ATE_TABLE       
12e10 20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20     2   /* Table 
12e20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
12e30 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
12e40 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
12e50 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20  TE_TEMP_INDEX   
12e60 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e    3   /* Index N
12e70 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
12e80 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
12e90 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
12ea0 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20  E_TEMP_TABLE    
12eb0 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61   4   /* Table Na
12ec0 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
12ed0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
12ee0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
12ef0 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20  _TEMP_TRIGGER   
12f00 35 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  5   /* Trigger N
12f10 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
12f20 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
12f30 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
12f40 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36  TEMP_VIEW      6
12f50 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
12f60 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
12f70 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
12f80 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
12f90 52 49 47 47 45 52 20 20 20 20 20 20 20 20 37 20  RIGGER        7 
12fa0 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
12fb0 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
12fc0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
12fd0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49  SQLITE_CREATE_VI
12fe0 45 57 20 20 20 20 20 20 20 20 20 20 20 38 20 20  EW           8  
12ff0 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
13000 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
13010 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
13020 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20  QLITE_DELETE    
13030 20 20 20 20 20 20 20 20 20 20 20 20 39 20 20 20              9   
13040 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
13050 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
13060 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
13070 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20  LITE_DROP_INDEX 
13080 20 20 20 20 20 20 20 20 20 20 31 30 20 20 20 2f            10   /
13090 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
130a0 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
130b0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
130c0 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20  ITE_DROP_TABLE  
130d0 20 20 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a           11   /*
130e0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
130f0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
13100 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
13110 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44  TE_DROP_TEMP_IND
13120 45 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20  EX      12   /* 
13130 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
13140 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
13150 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
13160 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c  E_DROP_TEMP_TABL
13170 45 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54  E      13   /* T
13180 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
13190 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
131a0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
131b0 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47  _DROP_TEMP_TRIGG
131c0 45 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72  ER    14   /* Tr
131d0 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
131e0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
131f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
13200 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20  DROP_TEMP_VIEW  
13210 20 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65       15   /* Vie
13220 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
13230 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
13240 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
13250 52 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20 20  ROP_TRIGGER     
13260 20 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67      16   /* Trig
13270 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
13280 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
13290 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
132a0 4f 50 5f 56 49 45 57 20 20 20 20 20 20 20 20 20  OP_VIEW         
132b0 20 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20     17   /* View 
132c0 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
132d0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
132e0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53  efine SQLITE_INS
132f0 45 52 54 20 20 20 20 20 20 20 20 20 20 20 20 20  ERT             
13300 20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20    18   /* Table 
13310 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
13320 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
13330 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47  fine SQLITE_PRAG
13340 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20  MA              
13350 20 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20   19   /* Pragma 
13360 4e 61 6d 65 20 20 20 20 20 31 73 74 20 61 72 67  Name     1st arg
13370 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66   or NULL */.#def
13380 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20  ine SQLITE_READ 
13390 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
133a0 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  20   /* Table Na
133b0 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e  me      Column N
133c0 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
133d0 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54  ne SQLITE_SELECT
133e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
133f0 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20  1   /* NULL     
13400 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
13410 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
13420 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43  e SQLITE_TRANSAC
13430 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32  TION          22
13440 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20     /* NULL      
13450 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
13460 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
13470 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20   SQLITE_UPDATE  
13480 20 20 20 20 20 20 20 20 20 20 20 20 20 32 33 20               23 
13490 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
134a0 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65       Column Name
134b0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
134c0 53 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20  SQLITE_ATTACH   
134d0 20 20 20 20 20 20 20 20 20 20 20 20 32 34 20 20              24  
134e0 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20   /* Filename    
134f0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
13500 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
13510 51 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20 20  QLITE_DETACH    
13520 20 20 20 20 20 20 20 20 20 20 20 32 35 20 20 20             25   
13530 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65  /* Database Name
13540 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
13550 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
13560 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45  LITE_ALTER_TABLE
13570 20 20 20 20 20 20 20 20 20 20 32 36 20 20 20 2f            26   /
13580 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20  * Database Name 
13590 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
135a0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
135b0 49 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20  ITE_REINDEX     
135c0 20 20 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a           27   /*
135d0 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
135e0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
135f0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
13600 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20  TE_ANALYZE      
13610 20 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20          28   /* 
13620 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
13630 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
13640 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
13650 45 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20  E_CREATE_VTABLE 
13660 20 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54         29   /* T
13670 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d  able Name      M
13680 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a  odule Name     *
13690 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
136a0 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20  _DROP_VTABLE    
136b0 20 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61        30   /* Ta
136c0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f  ble Name      Mo
136d0 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f  dule Name     */
136e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
136f0 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20  FUNCTION        
13700 20 20 20 20 20 33 31 20 20 20 2f 2a 20 46 75 6e       31   /* Fun
13710 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 4e 55 4c  ction Name   NUL
13720 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
13730 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
13740 4f 50 59 20 20 20 20 20 20 20 20 20 20 20 20 20  OPY             
13750 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c       0   /* No l
13760 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 0a 2f  onger used */../
13770 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
13780 72 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 69  racing And Profi
13790 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 20 7b  ling Functions {
137a0 46 31 32 32 38 30 7d 0a 2a 2a 0a 2a 2a 20 54 68  F12280}.**.** Th
137b0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67  ese routines reg
137c0 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66  ister callback f
137d0 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61  unctions that ca
137e0 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a  n be used for.**
137f0 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f   tracing and pro
13800 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75  filing the execu
13810 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74  tion of SQL stat
13820 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  ements..**.** Th
13830 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
13840 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62  ion registered b
13850 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  y sqlite3_trace(
13860 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a  ) is invoked at.
13870 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73  ** various times
13880 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61   when an SQL sta
13890 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20  tement is being 
138a0 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  run by [sqlite3_
138b0 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  step()]..** The 
138c0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
138d0 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69   a UTF-8 renderi
138e0 6e 67 20 6f 66 20 74 68 65 20 53 51 4c 20 73 74  ng of the SQL st
138f0 61 74 65 6d 65 6e 74 20 74 65 78 74 0a 2a 2a 20  atement text.** 
13900 61 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  as the statement
13910 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 65 78   first begins ex
13920 65 63 75 74 69 6e 67 2e 20 20 41 64 64 69 74 69  ecuting.  Additi
13930 6f 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 6f  onal callbacks o
13940 63 63 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 20  ccur.** as each 
13950 74 72 69 67 67 65 72 73 75 62 70 72 6f 67 72 61  triggersubprogra
13960 6d 20 69 73 20 65 6e 74 65 72 65 64 2e 20 20 54  m is entered.  T
13970 68 65 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72  he callbacks for
13980 20 74 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e   triggers.** con
13990 74 61 69 6e 20 61 20 55 54 46 2d 38 20 53 51 4c  tain a UTF-8 SQL
139a0 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69 64   comment that id
139b0 65 6e 74 69 66 69 65 73 20 74 68 65 20 74 72 69  entifies the tri
139c0 67 67 65 72 2e 0a 2a 2a 20 0a 2a 2a 20 54 68 65  gger..** .** The
139d0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
139e0 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79  on registered by
139f0 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65   sqlite3_profile
13a00 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a  () is invoked.**
13a10 20 61 73 20 65 61 63 68 20 53 51 4c 20 73 74 61   as each SQL sta
13a20 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e  tement finishes.
13a30 20 20 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61    The profile ca
13a40 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a  llback contains.
13a50 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  ** the original 
13a60 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61  statement text a
13a70 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f  nd an estimate o
13a80 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d  f wall-clock tim
13a90 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67  e.** of how long
13aa0 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20   that statement 
13ab0 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 0a 2a 2a 0a  took to run..**.
13ac0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70  ** The sqlite3_p
13ad0 72 6f 66 69 6c 65 28 29 20 41 50 49 20 69 73 20  rofile() API is 
13ae0 63 75 72 72 65 6e 74 6c 79 20 63 6f 6e 73 69 64  currently consid
13af0 65 72 65 64 20 65 78 70 65 72 69 6d 65 6e 74 61  ered experimenta
13b00 6c 20 61 6e 64 0a 2a 2a 20 69 73 20 73 75 62 6a  l and.** is subj
13b10 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 6f 72  ect to change or
13b20 20 72 65 6d 6f 76 61 6c 20 69 6e 20 61 20 66 75   removal in a fu
13b30 74 75 72 65 20 72 65 6c 65 61 73 65 2e 0a 2a 2a  ture release..**
13b40 0a 2a 2a 20 54 68 65 20 74 72 69 67 67 65 72 20  .** The trigger 
13b50 72 65 70 6f 72 74 69 6e 67 20 66 65 61 74 75 72  reporting featur
13b60 65 20 6f 66 20 74 68 65 20 74 72 61 63 65 20 63  e of the trace c
13b70 61 6c 6c 62 61 63 6b 20 69 73 20 63 6f 6e 73 69  allback is consi
13b80 64 65 72 65 64 0a 2a 2a 20 65 78 70 65 72 69 6d  dered.** experim
13b90 65 6e 74 61 6c 20 61 6e 64 20 69 73 20 73 75 62  ental and is sub
13ba0 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 6f  ject to change o
13bb0 72 20 72 65 6d 6f 76 61 6c 20 69 6e 20 66 75 74  r removal in fut
13bc0 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a  ure releases..**
13bd0 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   Future versions
13be0 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74   of SQLite might
13bf0 20 61 6c 73 6f 20 61 64 64 20 6e 65 77 20 74 72   also add new tr
13c00 61 63 65 20 63 61 6c 6c 62 61 63 6b 20 0a 2a 2a  ace callback .**
13c10 20 69 6e 76 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a   invocations..**
13c20 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
13c30 2a 2a 0a 2a 2a 20 7b 46 31 32 32 38 31 7d 20 54  **.** {F12281} T
13c40 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  he callback func
13c50 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20  tion registered 
13c60 62 79 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63  by [sqlite3_trac
13c70 65 28 29 5d 20 69 73 0a 2a 2a 20 20 20 20 20 20  e()] is.**      
13c80 20 20 20 20 77 68 65 6e 65 76 65 72 20 61 6e 20      whenever an 
13c90 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69  SQL statement fi
13ca0 72 73 74 20 62 65 67 69 6e 73 20 74 6f 20 65 78  rst begins to ex
13cb0 65 63 75 74 65 20 61 6e 64 0a 2a 2a 20 20 20 20  ecute and.**    
13cc0 20 20 20 20 20 20 77 68 65 6e 65 76 65 72 20 61        whenever a
13cd0 20 74 72 69 67 67 65 72 20 73 75 62 70 72 6f 67   trigger subprog
13ce0 72 61 6d 20 66 69 72 73 74 20 62 65 67 69 6e 73  ram first begins
13cf0 20 74 6f 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 7b   to run..**.** {
13d00 46 31 32 32 38 32 7d 20 45 61 63 68 20 63 61 6c  F12282} Each cal
13d10 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74 72  l to [sqlite3_tr
13d20 61 63 65 28 29 5d 20 6f 76 65 72 72 69 64 65 73  ace()] overrides
13d30 20 74 68 65 20 70 72 65 76 69 6f 75 73 6c 79 0a   the previously.
13d40 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 67 69  **          regi
13d50 73 74 65 72 65 64 20 74 72 61 63 65 20 63 61 6c  stered trace cal
13d60 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  lback..**.** {F1
13d70 32 32 38 33 7d 20 41 20 4e 55 4c 4c 20 74 72 61  2283} A NULL tra
13d80 63 65 20 63 61 6c 6c 62 61 63 6b 20 64 69 73 61  ce callback disa
13d90 62 6c 65 73 20 74 72 61 63 69 6e 67 2e 0a 2a 2a  bles tracing..**
13da0 0a 2a 2a 20 7b 46 31 32 32 38 34 7d 20 54 68 65  .** {F12284} The
13db0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
13dc0 74 6f 20 74 68 65 20 74 72 61 63 65 20 63 61 6c  to the trace cal
13dd0 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20  lback is a copy 
13de0 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  of.**          t
13df0 68 65 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68  he pointer which
13e00 20 77 61 73 20 74 68 65 20 33 72 64 20 61 72 67   was the 3rd arg
13e10 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65  ument to [sqlite
13e20 33 5f 74 72 61 63 65 28 29 5d 2e 0a 2a 2a 0a 2a  3_trace()]..**.*
13e30 2a 20 7b 46 31 32 32 38 35 7d 20 54 68 65 20 73  * {F12285} The s
13e40 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
13e50 6f 20 74 68 65 20 74 72 61 63 65 20 63 61 6c 6c  o the trace call
13e60 62 61 63 6b 20 69 73 20 61 0a 2a 2a 20 20 20 20  back is a.**    
13e70 20 20 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69        zero-termi
13e80 6e 61 74 65 64 20 55 54 46 38 20 73 74 72 69 6e  nated UTF8 strin
13e90 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  g containing the
13ea0 20 6f 72 69 67 69 6e 61 6c 20 74 65 78 74 0a 2a   original text.*
13eb0 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 74 68  *          of th
13ec0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
13ed0 61 73 20 69 74 20 77 61 73 20 70 61 73 73 65 64  as it was passed
13ee0 20 69 6e 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70   into [sqlite3_p
13ef0 72 65 70 61 72 65 5f 76 32 28 29 5d 0a 2a 2a 20  repare_v2()].** 
13f00 20 20 20 20 20 20 20 20 20 6f 72 20 74 68 65 20           or the 
13f10 65 71 75 69 76 61 6c 65 6e 74 2c 20 6f 72 20 61  equivalent, or a
13f20 6e 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 69 6e  n SQL comment in
13f30 64 69 63 61 74 69 6e 67 20 74 68 65 20 62 65 67  dicating the beg
13f40 69 6e 6e 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20  inning.**       
13f50 20 20 20 6f 66 20 61 20 74 72 69 67 67 65 72 20     of a trigger 
13f60 73 75 62 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a  subprogram..**.*
13f70 2a 20 7b 46 31 32 32 38 37 7d 20 54 68 65 20 63  * {F12287} The c
13f80 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
13f90 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20 5b   registered by [
13fa0 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28  sqlite3_profile(
13fb0 29 5d 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a  )] is invoked.**
13fc0 20 20 20 20 20 20 20 20 20 20 61 73 20 65 61 63            as eac
13fd0 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  h SQL statement 
13fe0 66 69 6e 69 73 68 65 73 2e 0a 2a 2a 0a 2a 2a 20  finishes..**.** 
13ff0 7b 46 31 32 32 38 38 7d 20 54 68 65 20 66 69 72  {F12288} The fir
14000 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
14010 74 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c  the profile call
14020 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f  back is a copy o
14030 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  f.**          th
14040 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
14050 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 66  to [sqlite3_prof
14060 69 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46  ile()]..**.** {F
14070 31 32 32 38 39 7d 20 54 68 65 20 73 65 63 6f 6e  12289} The secon
14080 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
14090 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62  he profile callb
140a0 61 63 6b 20 69 73 20 61 0a 2a 2a 20 20 20 20 20  ack is a.**     
140b0 20 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e       zero-termin
140c0 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e  ated UTF-8 strin
140d0 67 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 73 20  g that contains 
140e0 74 68 65 20 63 6f 6d 70 6c 65 74 65 20 74 65 78  the complete tex
140f0 74 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20  t of.**         
14100 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
14110 6e 74 20 61 73 20 69 74 20 77 61 73 20 70 72 6f  nt as it was pro
14120 63 65 73 73 65 64 20 62 79 20 5b 73 71 6c 69 74  cessed by [sqlit
14130 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
14140 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
14150 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74 2e 0a  the equivalent..
14160 2a 2a 0a 2a 2a 20 7b 46 31 32 32 39 30 7d 20 54  **.** {F12290} T
14170 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
14180 65 72 20 74 6f 20 74 68 65 20 70 72 6f 66 69 6c  er to the profil
14190 65 20 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  e  callback is a
141a0 6e 20 65 73 74 69 6d 61 74 65 0a 2a 2a 20 20 20  n estimate.**   
141b0 20 20 20 20 20 20 20 6f 66 20 74 68 65 20 6e 75         of the nu
141c0 6d 62 65 72 20 6f 66 20 6e 61 6e 6f 73 65 63 6f  mber of nanoseco
141d0 6e 64 73 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63  nds of wall-cloc
141e0 6b 20 74 69 6d 65 20 72 65 71 75 69 72 65 64 20  k time required 
141f0 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  to.**          r
14200 75 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  un the SQL state
14210 6d 65 6e 74 20 66 72 6f 6d 20 73 74 61 72 74 20  ment from start 
14220 74 6f 20 66 69 6e 69 73 68 2e 0a 2a 2f 0a 76 6f  to finish..*/.vo
14230 69 64 20 2a 73 71 6c 69 74 65 33 5f 74 72 61 63  id *sqlite3_trac
14240 65 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64  e(sqlite3*, void
14250 28 2a 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c  (*xTrace)(void*,
14260 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f  const char*), vo
14270 69 64 2a 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69  id*);.void *sqli
14280 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69  te3_profile(sqli
14290 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78  te3*,.   void(*x
142a0 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63  Profile)(void*,c
142b0 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74  onst char*,sqlit
142c0 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64  e3_uint64), void
142d0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
142e0 52 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72  REF: Query Progr
142f0 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 20 7b 46  ess Callbacks {F
14300 31 32 39 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69  12910}.**.** Thi
14310 73 20 72 6f 75 74 69 6e 65 20 63 6f 6e 66 69 67  s routine config
14320 75 72 65 73 20 61 20 63 61 6c 6c 62 61 63 6b 20  ures a callback 
14330 66 75 6e 63 74 69 6f 6e 20 2d 20 74 68 65 0a 2a  function - the.*
14340 2a 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62  * progress callb
14350 61 63 6b 20 2d 20 74 68 61 74 20 69 73 20 69 6e  ack - that is in
14360 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c  voked periodical
14370 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 0a 2a  ly during long.*
14380 2a 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20  * running calls 
14390 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  to [sqlite3_exec
143a0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74  ()], [sqlite3_st
143b0 65 70 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71  ep()] and.** [sq
143c0 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
143d0 29 5d 2e 20 20 20 41 6e 20 65 78 61 6d 70 6c 65  )].   An example
143e0 20 75 73 65 20 66 6f 72 20 74 68 69 73 20 0a 2a   use for this .*
143f0 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74  * interface is t
14400 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75 70 64  o keep a GUI upd
14410 61 74 65 64 20 64 75 72 69 6e 67 20 61 20 6c 61  ated during a la
14420 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a  rge query..**.**
14430 20 49 66 20 74 68 65 20 70 72 6f 67 72 65 73 73   If the progress
14440 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
14450 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20  s non-zero, the 
14460 6f 70 65 72 74 69 6f 6e 20 69 73 0a 2a 2a 20 69  opertion is.** i
14470 6e 74 65 72 72 75 70 74 65 64 2e 20 20 54 68 69  nterrupted.  Thi
14480 73 20 66 65 61 74 75 72 65 20 63 61 6e 20 62 65  s feature can be
14490 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65   used to impleme
144a0 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22  nt a.** "Cancel"
144b0 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49   button on a GUI
144c0 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a   dialog box..**.
144d0 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
144e0 2a 0a 2a 2a 20 7b 46 31 32 39 31 31 7d 20 54 68  *.** {F12911} Th
144f0 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
14500 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62  ion registered b
14510 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 67 72  y [sqlite3_progr
14520 65 73 73 5f 68 61 6e 64 6c 65 72 28 29 5d 0a 2a  ess_handler()].*
14530 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 69 6e  *          is in
14540 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c  voked periodical
14550 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72  ly during long r
14560 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 0a  unning calls to.
14570 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
14580 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a  ite3_step()]..**
14590 0a 2a 2a 20 7b 46 31 32 39 31 32 7d 20 54 68 65  .** {F12912} The
145a0 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61   progress callba
145b0 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e  ck is invoked on
145c0 63 65 20 66 6f 72 20 65 76 65 72 79 20 4e 20 76  ce for every N v
145d0 69 72 74 75 61 6c 0a 2a 2a 20 20 20 20 20 20 20  irtual.**       
145e0 20 20 20 6d 61 63 68 69 6e 65 20 6f 70 63 6f 64     machine opcod
145f0 65 73 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74  es, where N is t
14600 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
14610 6e 74 20 74 6f 20 0a 2a 2a 20 20 20 20 20 20 20  nt to .**       
14620 20 20 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f     the [sqlite3_
14630 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72  progress_handler
14640 28 29 5d 20 63 61 6c 6c 20 74 68 61 74 20 72 65  ()] call that re
14650 67 69 73 74 65 72 65 64 0a 2a 2a 20 20 20 20 20  gistered.**     
14660 20 20 20 20 20 74 68 65 20 63 61 6c 6c 62 61 63       the callbac
14670 6b 2e 20 20 3c 74 6f 64 6f 3e 57 68 61 74 20 69  k.  <todo>What i
14680 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e  f N is less than
14690 20 31 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a   1?</todo>.**.**
146a0 20 7b 46 31 32 39 31 33 7d 20 54 68 65 20 70 72   {F12913} The pr
146b0 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20  ogress callback 
146c0 69 74 73 65 6c 66 20 69 73 20 69 64 65 6e 74 69  itself is identi
146d0 66 69 65 64 20 62 79 20 74 68 65 20 74 68 69 72  fied by the thir
146e0 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 72  d.**          ar
146f0 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74  gument to [sqlit
14700 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64  e3_progress_hand
14710 6c 65 72 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46  ler()]..**.** {F
14720 31 32 39 31 34 7d 20 54 68 65 20 66 6f 75 72 74  12914} The fourt
14730 68 20 61 72 67 75 6d 65 6e 74 20 5b 73 71 6c 69  h argument [sqli
14740 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e  te3_progress_han
14750 64 6c 65 72 28 29 5d 20 69 73 20 61 0a 2a 2a 2a  dler()] is a.***
14760 20 20 20 20 20 20 20 20 20 76 6f 69 64 20 70 6f           void po
14770 69 6e 74 65 72 20 70 61 73 73 65 64 20 74 6f 20  inter passed to 
14780 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c  the progress cal
14790 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20  lback.**        
147a0 20 20 66 75 6e 63 74 69 6f 6e 20 65 61 63 68 20    function each 
147b0 74 69 6d 65 20 69 74 20 69 73 20 69 6e 76 6f 6b  time it is invok
147c0 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 31  ed..**.** {F1291
147d0 35 7d 20 49 66 20 61 20 63 61 6c 6c 20 74 6f 20  5} If a call to 
147e0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
147f0 20 72 65 73 75 6c 74 73 20 69 6e 20 66 65 77 65   results in fewe
14800 72 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20 20  r than.**       
14810 20 20 20 4e 20 6f 70 63 6f 64 65 73 20 62 65 69     N opcodes bei
14820 6e 67 20 65 78 65 63 75 74 65 64 2c 0a 2a 2a 20  ng executed,.** 
14830 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 74 68           then th
14840 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62  e progress callb
14850 61 63 6b 20 69 73 20 6e 65 76 65 72 20 69 6e 76  ack is never inv
14860 6f 6b 65 64 2e 20 7b 45 4e 44 7d 0a 2a 2a 20 0a  oked. {END}.** .
14870 2a 2a 20 7b 46 31 32 39 31 36 7d 20 45 76 65 72  ** {F12916} Ever
14880 79 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  y call to [sqlit
14890 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64  e3_progress_hand
148a0 6c 65 72 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ler()].**       
148b0 20 20 20 6f 76 65 72 77 72 69 74 65 73 20 61 6e     overwrites an
148c0 79 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 67  y previously reg
148d0 69 73 74 65 72 65 20 70 72 6f 67 72 65 73 73 20  istere progress 
148e0 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b  handler..**.** {
148f0 46 31 32 39 31 37 7d 20 49 66 20 74 68 65 20 70  F12917} If the p
14900 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20  rogress handler 
14910 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c  callback is NULL
14920 20 74 68 65 6e 20 6e 6f 20 70 72 6f 67 72 65 73   then no progres
14930 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 68 61  s.**          ha
14940 6e 64 6c 65 72 20 69 73 20 69 6e 76 6f 6b 65 64  ndler is invoked
14950 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 31 38 7d  ..**.** {F12918}
14960 20 49 66 20 74 68 65 20 70 72 6f 67 72 65 73 73   If the progress
14970 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
14980 73 20 61 20 72 65 73 75 6c 74 20 6f 74 68 65 72  s a result other
14990 20 74 68 61 6e 20 30 2c 20 74 68 65 6e 0a 2a 2a   than 0, then.**
149a0 20 20 20 20 20 20 20 20 20 20 74 68 65 20 62 65            the be
149b0 68 61 76 69 6f 72 20 69 73 20 61 20 69 66 20 5b  havior is a if [
149c0 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
149d0 74 28 29 5d 20 68 61 64 20 62 65 65 6e 20 63 61  t()] had been ca
149e0 6c 6c 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71  lled..*/.void sq
149f0 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68  lite3_progress_h
14a00 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c  andler(sqlite3*,
14a10 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69   int, int(*)(voi
14a20 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  d*), void*);../*
14a30 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70  .** CAPI3REF: Op
14a40 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61  ening A New Data
14a50 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20  base Connection 
14a60 7b 46 31 32 37 30 30 7d 0a 2a 2a 0a 2a 2a 20 54  {F12700}.**.** T
14a70 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 70  hese routines op
14a80 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74  en an SQLite dat
14a90 61 62 61 73 65 20 66 69 6c 65 20 77 68 6f 73 65  abase file whose
14aa0 20 6e 61 6d 65 0a 2a 2a 20 69 73 20 67 69 76 65   name.** is give
14ab0 6e 20 62 79 20 74 68 65 20 66 69 6c 65 6e 61 6d  n by the filenam
14ac0 65 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54  e argument..** T
14ad0 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  he filename argu
14ae0 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70 72 65  ment is interpre
14af0 74 65 64 20 61 73 20 55 54 46 2d 38 0a 2a 2a 20  ted as UTF-8.** 
14b00 66 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  for [sqlite3_ope
14b10 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  n()] and [sqlite
14b20 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 61 6e 64  3_open_v2()] and
14b30 20 61 73 20 55 54 46 2d 31 36 0a 2a 2a 20 69 6e   as UTF-16.** in
14b40 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
14b50 20 6f 72 64 65 72 20 66 6f 72 20 5b 73 71 6c 69   order for [sqli
14b60 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a  te3_open16()]..*
14b70 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 2a 5d 20  * An [sqlite3*] 
14b80 68 61 6e 64 6c 65 20 69 73 20 75 73 75 61 6c 6c  handle is usuall
14b90 79 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70  y returned in *p
14ba0 70 44 62 2c 20 65 76 65 6e 0a 2a 2a 20 69 66 20  pDb, even.** if 
14bb0 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e  an error occurs.
14bc0 20 20 54 68 65 20 6f 6e 6c 79 20 65 78 63 65 70    The only excep
14bd0 74 69 6f 6e 20 69 73 20 69 66 20 53 51 4c 69 74  tion is if SQLit
14be0 65 20 69 73 20 75 6e 61 62 6c 65 0a 2a 2a 20 74  e is unable.** t
14bf0 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72  o allocate memor
14c00 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73  y to hold the [s
14c10 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 20  qlite3] object, 
14c20 61 20 4e 55 4c 4c 20 77 69 6c 6c 0a 2a 2a 20 62  a NULL will.** b
14c30 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a  e written into *
14c40 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20  ppDb instead of 
14c50 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
14c60 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63   [sqlite3] objec
14c70 74 2e 0a 2a 2a 20 49 66 20 74 68 65 20 64 61 74  t..** If the dat
14c80 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
14c90 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 64 29  (and/or created)
14ca0 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79  .** successfully
14cb0 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 4f  , then [SQLITE_O
14cc0 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  K] is returned. 
14cd0 20 4f 74 68 65 72 77 69 73 65 20 61 6e 0a 2a 2a   Otherwise an.**
14ce0 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72   error code is r
14cf0 65 74 75 72 6e 65 64 2e 20 20 54 68 65 0a 2a 2a  eturned.  The.**
14d00 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
14d10 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
14d20 65 72 72 6d 73 67 31 36 28 29 5d 20 20 72 6f 75  errmsg16()]  rou
14d30 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75 73 65  tines can be use
14d40 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61  d to obtain.** a
14d50 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61  n English langua
14d60 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e 20 6f  ge description o
14d70 66 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 0a  f the error..**.
14d80 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20 65  ** The default e
14d90 6e 63 6f 64 69 6e 67 20 66 6f 72 20 74 68 65 20  ncoding for the 
14da0 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65  database will be
14db0 20 55 54 46 2d 38 20 69 66 0a 2a 2a 20 5b 73 71   UTF-8 if.** [sq
14dc0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 6f 72  lite3_open()] or
14dd0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
14de0 32 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 61  2()] is called a
14df0 6e 64 0a 2a 2a 20 55 54 46 2d 31 36 20 69 6e 20  nd.** UTF-16 in 
14e00 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  the native byte 
14e10 6f 72 64 65 72 20 69 66 20 5b 73 71 6c 69 74 65  order if [sqlite
14e20 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75  3_open16()] is u
14e30 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68  sed..**.** Wheth
14e40 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72  er or not an err
14e50 6f 72 20 6f 63 63 75 72 73 20 77 68 65 6e 20 69  or occurs when i
14e60 74 20 69 73 20 6f 70 65 6e 65 64 2c 20 72 65 73  t is opened, res
14e70 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69  ources.** associ
14e80 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 73  ated with the [s
14e90 71 6c 69 74 65 33 2a 5d 20 68 61 6e 64 6c 65 20  qlite3*] handle 
14ea0 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73  should be releas
14eb0 65 64 20 62 79 20 70 61 73 73 69 6e 67 20 69 74  ed by passing it
14ec0 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  .** to [sqlite3_
14ed0 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74  close()] when it
14ee0 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65   is no longer re
14ef0 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  quired..**.** Th
14f00 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  e [sqlite3_open_
14f10 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  v2()] interface 
14f20 77 6f 72 6b 73 20 6c 69 6b 65 20 5b 73 71 6c 69  works like [sqli
14f30 74 65 33 5f 6f 70 65 6e 28 29 5d 20 0a 2a 2a 20  te3_open()] .** 
14f40 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61  except that it a
14f50 63 63 63 65 70 74 73 20 74 77 6f 20 61 64 64 69  cccepts two addi
14f60 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72  tional parameter
14f70 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  s for additional
14f80 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72   control.** over
14f90 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73   the new databas
14fa0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54  e connection.  T
14fb0 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74  he flags paramet
14fc0 65 72 20 63 61 6e 20 62 65 0a 2a 2a 20 6f 6e 65  er can be.** one
14fd0 20 6f 66 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a   of:.**.** <ol>.
14fe0 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
14ff0 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 0a  _OPEN_READONLY].
15000 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
15010 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d  _OPEN_READWRITE]
15020 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
15030 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
15040 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ] | [SQLITE_OPEN
15050 5f 43 52 45 41 54 45 5d 0a 2a 2a 20 3c 2f 6f 6c  _CREATE].** </ol
15060 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  >.**.** The firs
15070 74 20 76 61 6c 75 65 20 6f 70 65 6e 73 20 74 68  t value opens th
15080 65 20 64 61 74 61 62 61 73 65 20 72 65 61 64 2d  e database read-
15090 6f 6e 6c 79 2e 20 0a 2a 2a 20 49 66 20 74 68 65  only. .** If the
150a0 20 64 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e   database does n
150b0 6f 74 20 70 72 65 76 69 6f 75 73 6c 79 20 65 78  ot previously ex
150c0 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73  ist, an error is
150d0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 54 68   returned..** Th
150e0 65 20 73 65 63 6f 6e 64 20 6f 70 74 69 6f 6e 20  e second option 
150f0 6f 70 65 6e 73 0a 2a 2a 20 74 68 65 20 64 61 74  opens.** the dat
15100 61 62 61 73 65 20 66 6f 72 20 72 65 61 64 69 6e  abase for readin
15110 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66  g and writing if
15120 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 65   possible, or re
15130 61 64 69 6e 67 20 6f 6e 6c 79 20 69 66 0a 2a 2a  ading only if.**
15140 20 69 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   if the file is 
15150 77 72 69 74 65 20 70 72 6f 74 65 63 74 65 64 2e  write protected.
15160 20 20 49 6e 20 65 69 74 68 65 72 20 63 61 73 65    In either case
15170 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
15180 20 6d 75 73 74 20 61 6c 72 65 61 64 79 20 65 78   must already ex
15190 69 73 74 20 6f 72 20 61 6e 20 65 72 72 6f 72 20  ist or an error 
151a0 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68  is returned.  Th
151b0 65 20 74 68 69 72 64 20 6f 70 74 69 6f 6e 0a 2a  e third option.*
151c0 2a 20 6f 70 65 6e 73 20 74 68 65 20 64 61 74 61  * opens the data
151d0 62 61 73 65 20 66 6f 72 20 72 65 61 64 69 6e 67  base for reading
151e0 20 61 6e 64 20 77 72 69 74 69 6e 67 20 61 6e 64   and writing and
151f0 20 63 72 65 61 74 65 73 20 69 74 20 69 66 20 69   creates it if i
15200 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 61 6c  t does.** not al
15210 72 65 61 64 79 20 65 78 69 73 74 2e 0a 2a 2a 20  ready exist..** 
15220 54 68 65 20 74 68 69 72 64 20 6f 70 74 69 6f 6e  The third option
15230 73 20 69 73 20 62 65 68 61 76 69 6f 72 20 74 68  s is behavior th
15240 61 74 20 69 73 20 61 6c 77 61 79 73 20 75 73 65  at is always use
15250 64 20 66 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f  d for [sqlite3_o
15260 70 65 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73  pen()].** and [s
15270 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
15280 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66  ..**.** If the f
15290 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d  ilename is ":mem
152a0 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 6e 20 70  ory:", then an p
152b0 72 69 76 61 74 65 0a 2a 2a 20 69 6e 2d 6d 65 6d  rivate.** in-mem
152c0 6f 72 79 20 64 61 74 61 62 61 73 65 20 69 73 20  ory database is 
152d0 63 72 65 61 74 65 64 20 66 6f 72 20 74 68 65 20  created for the 
152e0 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 69  connection.  Thi
152f0 73 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 64  s in-memory.** d
15300 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61 6e  atabase will van
15310 69 73 68 20 77 68 65 6e 20 74 68 65 20 64 61 74  ish when the dat
15320 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
15330 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 46 75 74   is closed.  Fut
15340 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f  ure.** version o
15350 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 6d  f SQLite might m
15360 61 6b 65 20 75 73 65 20 6f 66 20 61 64 64 69 74  ake use of addit
15370 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20 66 69  ional special fi
15380 6c 65 6e 61 6d 65 73 0a 2a 2a 20 74 68 61 74 20  lenames.** that 
15390 62 65 67 69 6e 20 77 69 74 68 20 74 68 65 20 22  begin with the "
153a0 3a 22 20 63 68 61 72 61 63 74 65 72 2e 20 20 49  :" character.  I
153b0 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  t is recommended
153c0 20 74 68 61 74 20 0a 2a 2a 20 77 68 65 6e 20 61   that .** when a
153d0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   database filena
153e0 6d 65 20 72 65 61 6c 6c 79 20 64 6f 65 73 20 62  me really does b
153f0 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 22 3a 22  egin with.** ":"
15400 20 74 68 61 74 20 79 6f 75 20 70 72 65 66 69 78   that you prefix
15410 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69   the filename wi
15420 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20 6c 69  th a pathname li
15430 6b 65 20 22 2e 2f 22 20 74 6f 0a 2a 2a 20 61 76  ke "./" to.** av
15440 6f 69 64 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a  oid ambiguity..*
15450 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 6c 65  *.** If the file
15460 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d 70 74 79  name is an empty
15470 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 20   string, then a 
15480 70 72 69 76 61 74 65 20 74 65 6d 70 6f 72 61 72  private temporar
15490 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74  y.** on-disk dat
154a0 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72  abase will be cr
154b0 65 61 74 65 64 2e 20 20 54 68 69 73 20 70 72 69  eated.  This pri
154c0 76 61 74 65 20 64 61 74 61 62 61 73 65 20 77 69  vate database wi
154d0 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74  ll be.** automat
154e0 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 61  ically deleted a
154f0 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 64 61  s soon as the da
15500 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
15510 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a  n is closed..**.
15520 2a 2a 20 54 68 65 20 66 6f 75 72 74 68 20 70 61  ** The fourth pa
15530 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
15540 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20  e3_open_v2() is 
15550 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a  the name of the.
15560 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  ** [sqlite3_vfs]
15570 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66   object that def
15580 69 6e 65 73 20 74 68 65 20 6f 70 65 72 61 74 69  ines the operati
15590 6e 67 20 73 79 73 74 65 6d 20 0a 2a 2a 20 69 6e  ng system .** in
155a0 74 65 72 66 61 63 65 20 74 68 61 74 20 74 68 65  terface that the
155b0 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f   new database co
155c0 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20  nnection should 
155d0 75 73 65 2e 20 20 49 66 20 74 68 65 0a 2a 2a 20  use.  If the.** 
155e0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
155f0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
15600 65 72 20 74 68 65 6e 20 74 68 65 20 64 65 66 61  er then the defa
15610 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  ult [sqlite3_vfs
15620 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 69 73 20 75  ].** object is u
15630 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f  sed..**.** <b>No
15640 74 65 20 74 6f 20 77 69 6e 64 6f 77 73 20 75 73  te to windows us
15650 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e  ers:</b>  The en
15660 63 6f 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20  coding used for 
15670 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  the filename arg
15680 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 5b 73 71 6c  ument.** of [sql
15690 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 61 6e 64  ite3_open()] and
156a0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
156b0 32 28 29 5d 20 6d 75 73 74 20 62 65 20 55 54 46  2()] must be UTF
156c0 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72  -8, not whatever
156d0 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20  .** codepage is 
156e0 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65  currently define
156f0 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f  d.  Filenames co
15700 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61  ntaining interna
15710 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63  tional.** charac
15720 74 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e  ters must be con
15730 76 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20  verted to UTF-8 
15740 70 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67  prior to passing
15750 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 5b 73   them into.** [s
15760 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 6f  qlite3_open()] o
15770 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  r [sqlite3_open_
15780 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  v2()]..**.** INV
15790 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
157a0 46 31 32 37 30 31 7d 20 54 68 65 20 5b 73 71 6c  F12701} The [sql
157b0 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
157c0 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
157d0 2c 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20  , and.**        
157e0 20 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f    [sqlite3_open_
157f0 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73  v2()] interfaces
15800 20 63 72 65 61 74 65 20 61 20 6e 65 77 0a 2a 2a   create a new.**
15810 20 20 20 20 20 20 20 20 20 20 5b 64 61 74 61 62            [datab
15820 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
15830 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 0a  associated with.
15840 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
15850 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 67 69  database file gi
15860 76 65 6e 20 69 6e 20 74 68 65 69 72 20 66 69 72  ven in their fir
15870 73 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  st parameter..**
15880 0a 2a 2a 20 7b 46 31 32 37 30 32 7d 20 54 68 65  .** {F12702} The
15890 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65   filename argume
158a0 6e 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65  nt is interprete
158b0 64 20 61 73 20 55 54 46 2d 38 0a 2a 2a 20 20 20  d as UTF-8.**   
158c0 20 20 20 20 20 20 20 66 6f 72 20 5b 73 71 6c 69         for [sqli
158d0 74 65 33 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20  te3_open()] and 
158e0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
158f0 28 29 5d 20 61 6e 64 20 61 73 20 55 54 46 2d 31  ()] and as UTF-1
15900 36 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  6.**          in
15910 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
15920 20 6f 72 64 65 72 20 66 6f 72 20 5b 73 71 6c 69   order for [sqli
15930 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a  te3_open16()]..*
15940 2a 0a 2a 2a 20 7b 46 31 32 37 30 33 7d 20 41 20  *.** {F12703} A 
15950 73 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63  successful invoc
15960 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65  ation of [sqlite
15970 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
15980 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 0a  te3_open16()], .
15990 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 5b  **          or [
159a0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
159b0 29 5d 20 77 72 69 74 65 73 20 61 20 70 6f 69 6e  )] writes a poin
159c0 74 65 72 20 74 6f 20 61 20 6e 65 77 0a 2a 2a 20  ter to a new.** 
159d0 20 20 20 20 20 20 20 20 20 5b 64 61 74 61 62 61           [databa
159e0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69  se connection] i
159f0 6e 74 6f 20 2a 70 70 44 62 2e 0a 2a 2a 0a 2a 2a  nto *ppDb..**.**
15a00 20 7b 46 31 32 37 30 34 7d 20 54 68 65 20 5b 73   {F12704} The [s
15a10 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
15a20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
15a30 29 5d 2c 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20  )], and.**      
15a40 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65      [sqlite3_ope
15a50 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63  n_v2()] interfac
15a60 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  es return [SQLIT
15a70 45 5f 4f 4b 5d 20 75 70 6f 6e 20 73 75 63 63 65  E_OK] upon succe
15a80 73 73 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ss,.**          
15a90 6f 72 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74  or an appropriat
15aa0 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f  e [error code] o
15ab0 6e 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a  n failure..**.**
15ac0 20 7b 46 31 32 37 30 36 7d 20 54 68 65 20 64 65   {F12706} The de
15ad0 66 61 75 6c 74 20 74 65 78 74 20 65 6e 63 6f 64  fault text encod
15ae0 69 6e 67 20 66 6f 72 20 61 20 6e 65 77 20 64 61  ing for a new da
15af0 74 61 62 61 73 65 20 63 72 65 61 74 65 64 20 75  tabase created u
15b00 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20  sing.**         
15b10 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
15b20 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ] or [sqlite3_op
15b30 65 6e 5f 76 32 28 29 5d 20 77 69 6c 6c 20 62 65  en_v2()] will be
15b40 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b 46   UTF-8..**.** {F
15b50 31 32 37 30 37 7d 20 54 68 65 20 64 65 66 61 75  12707} The defau
15b60 6c 74 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  lt text encoding
15b70 20 66 6f 72 20 61 20 6e 65 77 20 64 61 74 61 62   for a new datab
15b80 61 73 65 20 63 72 65 61 74 65 64 20 75 73 69 6e  ase created usin
15b90 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  g.**          [s
15ba0 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
15bb0 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 31 36 2e   will be UTF-16.
15bc0 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 30 39 7d 20  .**.** {F12709} 
15bd0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  The [sqlite3_ope
15be0 6e 28 46 2c 44 29 5d 20 69 6e 74 65 72 66 61 63  n(F,D)] interfac
15bf0 65 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20  e is equivalent 
15c00 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  to.**          [
15c10 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
15c20 46 2c 44 2c 47 2c 30 29 5d 20 77 68 65 72 65 20  F,D,G,0)] where 
15c30 74 68 65 20 47 20 70 61 72 61 6d 65 74 65 72 20  the G parameter 
15c40 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  is.**          [
15c50 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
15c60 57 52 49 54 45 5d 7c 5b 53 51 4c 49 54 45 5f 4f  WRITE]|[SQLITE_O
15c70 50 45 4e 5f 43 52 45 41 54 45 5d 2e 0a 2a 2a 0a  PEN_CREATE]..**.
15c80 2a 2a 20 7b 46 31 32 37 31 31 7d 20 49 66 20 74  ** {F12711} If t
15c90 68 65 20 47 20 70 61 72 61 6d 65 74 65 72 20 74  he G parameter t
15ca0 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  o [sqlite3_open_
15cb0 76 32 28 46 2c 44 2c 47 2c 56 29 5d 20 63 6f 6e  v2(F,D,G,V)] con
15cc0 74 61 69 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20  tains the.**    
15cd0 20 20 20 20 20 20 62 69 74 20 76 61 6c 75 65 20        bit value 
15ce0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
15cf0 44 4f 4e 4c 59 5d 20 74 68 65 6e 20 74 68 65 20  DONLY] then the 
15d00 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
15d10 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  ed.**          f
15d20 6f 72 20 72 65 61 64 69 6e 67 20 6f 6e 6c 79 2e  or reading only.
15d30 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 31 32 7d 20  .**.** {F12712} 
15d40 49 66 20 74 68 65 20 47 20 70 61 72 61 6d 65 74  If the G paramet
15d50 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f  er to [sqlite3_o
15d60 70 65 6e 5f 76 32 28 46 2c 44 2c 47 2c 56 29 5d  pen_v2(F,D,G,V)]
15d70 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 0a 2a 2a   contains the.**
15d80 20 20 20 20 20 20 20 20 20 20 62 69 74 20 76 61            bit va
15d90 6c 75 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  lue [SQLITE_OPEN
15da0 5f 52 45 41 44 57 52 49 54 45 5d 20 74 68 65 6e  _READWRITE] then
15db0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
15dc0 20 6f 70 65 6e 65 64 0a 2a 2a 20 20 20 20 20 20   opened.**      
15dd0 20 20 20 20 72 65 61 64 69 6e 67 20 61 6e 64 20      reading and 
15de0 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69  writing if possi
15df0 62 6c 65 2c 20 6f 72 20 66 6f 72 20 72 65 61 64  ble, or for read
15e00 69 6e 67 20 6f 6e 6c 79 20 69 66 20 74 68 65 0a  ing only if the.
15e10 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65  **          file
15e20 20 69 73 20 77 72 69 74 65 20 70 72 6f 74 65 63   is write protec
15e30 74 65 64 20 62 79 20 74 68 65 20 6f 70 65 72 61  ted by the opera
15e40 74 69 6e 67 20 73 79 73 74 65 6d 2e 0a 2a 2a 0a  ting system..**.
15e50 2a 2a 20 7b 46 31 32 37 31 33 7d 20 49 66 20 74  ** {F12713} If t
15e60 68 65 20 47 20 70 61 72 61 6d 65 74 65 72 20 74  he G parameter t
15e70 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  o [sqlite3_open(
15e80 76 32 28 46 2c 44 2c 47 2c 56 29 5d 20 6f 6d 69  v2(F,D,G,V)] omi
15e90 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ts the.**       
15ea0 20 20 20 62 69 74 20 76 61 6c 75 65 20 5b 53 51     bit value [SQ
15eb0 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
15ec0 5d 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61  ] and the databa
15ed0 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 20  se does not.**  
15ee0 20 20 20 20 20 20 20 20 70 72 65 76 69 6f 75 73          previous
15ef0 6c 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72  ly exist, an err
15f00 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  or is returned..
15f10 2a 2a 0a 2a 2a 20 7b 46 31 32 37 31 34 7d 20 49  **.** {F12714} I
15f20 66 20 74 68 65 20 47 20 70 61 72 61 6d 65 74 65  f the G paramete
15f30 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  r to [sqlite3_op
15f40 65 6e 28 76 32 28 46 2c 44 2c 47 2c 56 29 5d 20  en(v2(F,D,G,V)] 
15f50 63 6f 6e 74 61 69 6e 73 20 74 68 65 0a 2a 2a 20  contains the.** 
15f60 20 20 20 20 20 20 20 20 20 62 69 74 20 76 61 6c           bit val
15f70 75 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ue [SQLITE_OPEN_
15f80 43 52 45 41 54 45 5d 20 61 6e 64 20 74 68 65 20  CREATE] and the 
15f90 64 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f  database does no
15fa0 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 72  t.**          pr
15fb0 65 76 69 6f 75 73 6c 79 20 65 78 69 73 74 2c 20  eviously exist, 
15fc0 74 68 65 6e 20 61 6e 20 61 74 74 65 6d 70 74 20  then an attempt 
15fd0 69 73 20 6d 61 64 65 20 74 6f 20 63 72 65 61 74  is made to creat
15fe0 65 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20  e and.**        
15ff0 20 20 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65    initialize the
16000 20 64 61 74 61 62 61 73 65 2e 0a 2a 2a 0a 2a 2a   database..**.**
16010 20 7b 46 31 32 37 31 37 7d 20 49 66 20 74 68 65   {F12717} If the
16020 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65   filename argume
16030 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f  nt to [sqlite3_o
16040 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  pen()], [sqlite3
16050 5f 6f 70 65 6e 31 36 28 29 5d 2c 0a 2a 2a 20 20  _open16()],.**  
16060 20 20 20 20 20 20 20 20 6f 72 20 5b 73 71 6c 69          or [sqli
16070 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69  te3_open_v2()] i
16080 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68  s ":memory:", th
16090 65 6e 20 61 6e 20 70 72 69 76 61 74 65 2c 0a 2a  en an private,.*
160a0 2a 20 20 20 20 20 20 20 20 20 20 65 70 68 65 6d  *          ephem
160b0 65 72 61 6c 2c 20 69 6e 2d 6d 65 6d 6f 72 79 20  eral, in-memory 
160c0 64 61 74 61 62 61 73 65 20 69 73 20 63 72 65 61  database is crea
160d0 74 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e  ted for the conn
160e0 65 63 74 69 6f 6e 2e 0a 2a 2a 20 20 20 20 20 20  ection..**      
160f0 20 20 20 20 3c 74 6f 64 6f 3e 49 73 20 53 51 4c      <todo>Is SQL
16100 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 7c  ITE_OPEN_CREATE|
16110 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
16120 57 52 49 54 45 20 72 65 71 75 69 72 65 64 0a 2a  WRITE required.*
16130 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 73 71  *          in sq
16140 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 3f  lite3_open_v2()?
16150 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 7b 46  </todo>.**.** {F
16160 31 32 37 31 39 7d 20 49 66 20 74 68 65 20 66 69  12719} If the fi
16170 6c 65 6e 61 6d 65 20 69 73 20 4e 55 4c 4c 20 6f  lename is NULL o
16180 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  r an empty strin
16190 67 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74  g, then a privat
161a0 65 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65  e,.**          e
161b0 70 68 65 72 6d 65 72 61 6c 20 6f 6e 2d 64 69 73  phermeral on-dis
161c0 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  k database will 
161d0 62 65 20 63 72 65 61 74 65 64 2e 0a 2a 2a 20 20  be created..**  
161e0 20 20 20 20 20 20 20 20 3c 74 6f 64 6f 3e 49 73          <todo>Is
161f0 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45   SQLITE_OPEN_CRE
16200 41 54 45 7c 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ATE|SQLITE_OPEN_
16210 52 45 41 44 57 52 49 54 45 20 72 65 71 75 69 72  READWRITE requir
16220 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  ed.**          i
16230 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  n sqlite3_open_v
16240 32 28 29 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a  2()?</todo>.**.*
16250 2a 20 7b 46 31 32 37 32 31 7d 20 54 68 65 20 5b  * {F12721} The [
16260 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
16270 69 6f 6e 5d 20 63 72 65 61 74 65 64 20 62 79 20  ion] created by 
16280 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
16290 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 46 2c  lite3_open_v2(F,
162a0 44 2c 47 2c 56 29 5d 20 77 69 6c 6c 20 75 73 65  D,G,V)] will use
162b0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
162c0 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
162d0 62 6a 65 63 74 20 69 64 65 6e 74 69 66 69 65 64  bject identified
162e0 20 62 79 20 74 68 65 20 56 20 70 61 72 61 6d 65   by the V parame
162f0 74 65 72 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20  ter, or.**      
16300 20 20 20 20 74 68 65 20 64 65 66 61 75 6c 74 20      the default 
16310 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
16320 6a 65 63 74 20 69 73 20 56 20 69 73 20 61 20 4e  ject is V is a N
16330 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a  ULL pointer..*/.
16340 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  int sqlite3_open
16350 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  (.  const char *
16360 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
16370 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
16380 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71   (UTF-8) */.  sq
16390 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20  lite3 **ppDb    
163a0 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
163b0 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
163c0 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
163d0 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74  _open16(.  const
163e0 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c   void *filename,
163f0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66     /* Database f
16400 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29  ilename (UTF-16)
16410 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a   */.  sqlite3 **
16420 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a  ppDb          /*
16430 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20   OUT: SQLite db 
16440 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74  handle */.);.int
16450 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
16460 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  (.  const char *
16470 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
16480 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
16490 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71   (UTF-8) */.  sq
164a0 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20  lite3 **ppDb,   
164b0 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
164c0 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
164d0 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20  /.  int flags,  
164e0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46              /* F
164f0 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  lags */.  const 
16500 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20  char *zVfs      
16510 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53    /* Name of VFS
16520 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a   module to use *
16530 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.);../*.** CAPI
16540 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65  3REF: Error Code
16550 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73 20 7b  s And Messages {
16560 46 31 32 38 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68  F12800}.**.** Th
16570 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64  e sqlite3_errcod
16580 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  e() interface re
16590 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69  turns the numeri
165a0 63 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 20  c.** [SQLITE_OK 
165b0 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f  | result code] o
165c0 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  r [SQLITE_IOERR_
165d0 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64 20  READ | extended 
165e0 72 65 73 75 6c 74 20 63 6f 64 65 5d 0a 2a 2a 20  result code].** 
165f0 66 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 65 63  for the most rec
16600 65 6e 74 20 66 61 69 6c 65 64 20 73 71 6c 69 74  ent failed sqlit
16610 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 20 61 73  e3_* API call as
16620 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68  sociated.** with
16630 20 5b 73 71 6c 69 74 65 33 5d 20 68 61 6e 64 6c   [sqlite3] handl
16640 65 20 27 64 62 27 2e 20 49 66 20 61 20 70 72 69  e 'db'. If a pri
16650 6f 72 20 41 50 49 20 63 61 6c 6c 20 66 61 69 6c  or API call fail
16660 65 64 20 62 75 74 20 74 68 65 0a 2a 2a 20 6d 6f  ed but the.** mo
16670 73 74 20 72 65 63 65 6e 74 20 41 50 49 20 63 61  st recent API ca
16680 6c 6c 20 73 75 63 63 65 65 64 65 64 2c 20 74 68  ll succeeded, th
16690 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
166a0 72 6f 6d 20 73 71 6c 69 74 65 33 5f 65 72 72 63  rom sqlite3_errc
166b0 6f 64 65 28 29 0a 2a 2a 20 69 73 20 75 6e 64 65  ode().** is unde
166c0 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  fined..**.** The
166d0 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28   sqlite3_errmsg(
166e0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72  ) and sqlite3_er
166f0 72 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e 20  rmsg16() return 
16700 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65  English-language
16710 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64 65  .** text that de
16720 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f  scribes the erro
16730 72 2c 20 61 73 20 65 69 74 68 65 72 20 55 54 46  r, as either UTF
16740 38 20 6f 72 20 55 54 46 31 36 20 72 65 73 70 65  8 or UTF16 respe
16750 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 4d 65 6d 6f  ctively..** Memo
16760 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65  ry to hold the e
16770 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72  rror message str
16780 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69  ing is managed i
16790 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68  nternally..** Th
167a0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f  e application do
167b0 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77  es not need to w
167c0 6f 72 72 79 20 77 69 74 68 20 66 72 65 65 69 6e  orry with freein
167d0 67 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a  g the result..**
167e0 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 65 72   However, the er
167f0 72 6f 72 20 73 74 72 69 6e 67 20 6d 69 67 68 74  ror string might
16800 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20   be overwritten 
16810 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 62  or deallocated b
16820 79 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20  y.** subsequent 
16830 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20 53  calls to other S
16840 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 20  QLite interface 
16850 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  functions..**.**
16860 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
16870 2a 2a 20 7b 46 31 32 38 30 31 7d 20 54 68 65 20  ** {F12801} The 
16880 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65  [sqlite3_errcode
16890 28 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  (D)] interface r
168a0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72  eturns the numer
168b0 69 63 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ic.**          [
168c0 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75  SQLITE_OK | resu
168d0 6c 74 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 20  lt code] or.**  
168e0 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f          [SQLITE_
168f0 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 65 78 74  IOERR_READ | ext
16900 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
16910 65 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  e].**          f
16920 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  or the most rece
16930 6e 74 6c 79 20 66 61 69 6c 65 64 20 69 6e 74 65  ntly failed inte
16940 72 66 61 63 65 20 63 61 6c 6c 20 61 73 73 6f 63  rface call assoc
16950 69 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  iated.**        
16960 20 20 77 69 74 68 20 5b 64 61 74 61 62 61 73 65    with [database
16970 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a   connection] D..
16980 2a 2a 0a 2a 2a 20 7b 46 31 32 38 30 33 7d 20 54  **.** {F12803} T
16990 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  he [sqlite3_errm
169a0 73 67 28 44 29 5d 20 61 6e 64 20 5b 73 71 6c 69  sg(D)] and [sqli
169b0 74 65 33 5f 65 72 72 6d 73 67 31 36 28 44 29 5d  te3_errmsg16(D)]
169c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74  .**          int
169d0 65 72 66 61 63 65 73 20 72 65 74 75 72 6e 20 45  erfaces return E
169e0 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 20  nglish-language 
169f0 74 65 78 74 20 74 68 61 74 20 64 65 73 63 72 69  text that descri
16a00 62 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  bes.**          
16a10 74 68 65 20 65 72 72 6f 72 20 69 6e 20 74 68 65  the error in the
16a20 20 6d 6f 73 74 6c 79 20 72 65 63 65 6e 74 6c 79   mostly recently
16a30 20 66 61 69 6c 65 64 20 69 6e 74 65 72 66 61 63   failed interfac
16a40 65 20 63 61 6c 6c 2c 0a 2a 2a 20 20 20 20 20 20  e call,.**      
16a50 20 20 20 20 65 6e 63 6f 64 65 64 20 61 73 20 65      encoded as e
16a60 69 74 68 65 72 20 55 54 46 38 20 6f 72 20 55 54  ither UTF8 or UT
16a70 46 31 36 20 72 65 73 70 65 63 74 69 76 65 6c 79  F16 respectively
16a80 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 38 30 37 7d  ..**.** {F12807}
16a90 20 54 68 65 20 73 74 72 69 6e 67 73 20 72 65 74   The strings ret
16aa0 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
16ab0 33 5f 65 72 72 6d 73 67 28 29 5d 20 61 6e 64 20  3_errmsg()] and 
16ac0 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31  [sqlite3_errmsg1
16ad0 36 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  6()].**         
16ae0 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c   are valid until
16af0 20 74 68 65 20 6e 65 78 74 20 53 51 4c 69 74 65   the next SQLite
16b00 20 69 6e 74 65 72 66 61 63 65 20 63 61 6c 6c 2e   interface call.
16b10 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 38 30 38 7d 20  .**.** {F12808} 
16b20 43 61 6c 6c 73 20 74 6f 20 41 50 49 20 72 6f 75  Calls to API rou
16b30 74 69 6e 65 73 20 74 68 61 74 20 64 6f 20 6e 6f  tines that do no
16b40 74 20 72 65 74 75 72 6e 20 61 6e 20 65 72 72 6f  t return an erro
16b50 72 20 63 6f 64 65 0a 2a 2a 20 20 20 20 20 20 20  r code.**       
16b60 20 20 20 28 65 78 61 6d 70 6c 65 3a 20 5b 73 71     (example: [sq
16b70 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
16b80 28 29 5d 29 20 64 6f 20 6e 6f 74 0a 2a 2a 20 20  ()]) do not.**  
16b90 20 20 20 20 20 20 20 20 63 68 61 6e 67 65 20 74          change t
16ba0 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 6f 72  he error code or
16bb0 20 6d 65 73 73 61 67 65 20 72 65 74 75 72 6e 65   message returne
16bc0 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20  d by.**         
16bd0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64   [sqlite3_errcod
16be0 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 65  e()], [sqlite3_e
16bf0 72 72 6d 73 67 28 29 5d 2c 20 6f 72 20 5b 73 71  rrmsg()], or [sq
16c00 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29  lite3_errmsg16()
16c10 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 38 30 39  ]..**.** {F12809
16c20 7d 20 49 6e 74 65 72 66 61 63 65 73 20 74 68 61  } Interfaces tha
16c30 74 20 61 72 65 20 6e 6f 74 20 61 73 73 6f 63 69  t are not associ
16c40 61 74 65 64 20 77 69 74 68 20 61 20 73 70 65 63  ated with a spec
16c50 69 66 69 63 0a 2a 2a 20 20 20 20 20 20 20 20 20  ific.**         
16c60 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
16c70 63 74 69 6f 6e 5d 20 28 65 78 61 6d 70 6c 65 73  ction] (examples
16c80 3a 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  :.**          [s
16c90 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29  qlite3_mprintf()
16ca0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 6e  ] or [sqlite3_en
16cb0 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68  able_shared_cach
16cc0 65 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  e()].**         
16cd0 20 64 6f 20 6e 6f 74 20 63 68 61 6e 67 65 20 74   do not change t
16ce0 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e  he values return
16cf0 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20  ed by.**        
16d00 20 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f    [sqlite3_errco
16d10 64 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  de()], [sqlite3_
16d20 65 72 72 6d 73 67 28 29 5d 2c 20 6f 72 20 5b 73  errmsg()], or [s
16d30 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
16d40 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
16d50 65 33 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74  e3_errcode(sqlit
16d60 65 33 20 2a 64 62 29 3b 0a 63 6f 6e 73 74 20 63  e3 *db);.const c
16d70 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72  har *sqlite3_err
16d80 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63  msg(sqlite3*);.c
16d90 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
16da0 65 33 5f 65 72 72 6d 73 67 31 36 28 73 71 6c 69  e3_errmsg16(sqli
16db0 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
16dc0 50 49 33 52 45 46 3a 20 53 51 4c 20 53 74 61 74  PI3REF: SQL Stat
16dd0 65 6d 65 6e 74 20 4f 62 6a 65 63 74 20 7b 46 31  ement Object {F1
16de0 33 30 30 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  3000}.** KEYWORD
16df0 53 3a 20 7b 70 72 65 70 61 72 65 64 20 73 74 61  S: {prepared sta
16e00 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65  tement} {prepare
16e10 64 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a  d statements}.**
16e20 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20  .** An instance 
16e30 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72  of this object r
16e40 65 70 72 65 73 65 6e 74 20 73 69 6e 67 6c 65 20  epresent single 
16e50 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20  SQL statements. 
16e60 20 54 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20   This.** object 
16e70 69 73 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f  is variously kno
16e80 77 6e 20 61 73 20 61 20 22 70 72 65 70 61 72 65  wn as a "prepare
16e90 64 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20  d statement" or 
16ea0 61 20 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20  a .** "compiled 
16eb0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 22 20 6f  SQL statement" o
16ec0 72 20 73 69 6d 70 6c 79 20 61 73 20 61 20 22 73  r simply as a "s
16ed0 74 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a 20 0a 2a  tatement"..** .*
16ee0 2a 20 54 68 65 20 6c 69 66 65 20 6f 66 20 61 20  * The life of a 
16ef0 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74  statement object
16f00 20 67 6f 65 73 20 73 6f 6d 65 74 68 69 6e 67 20   goes something 
16f10 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a  like this:.**.**
16f20 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72   <ol>.** <li> Cr
16f30 65 61 74 65 20 74 68 65 20 6f 62 6a 65 63 74 20  eate the object 
16f40 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70  using [sqlite3_p
16f50 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
16f60 61 20 72 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20  a related.**    
16f70 20 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c    function..** <
16f80 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20  li> Bind values 
16f90 74 6f 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65  to host paramete
16fa0 72 73 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20  rs using.**     
16fb0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
16fc0 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69  lob | sqlite3_bi
16fd0 6e 64 5f 2a 20 69 6e 74 65 72 66 61 63 65 73 5d  nd_* interfaces]
16fe0 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68  ..** <li> Run th
16ff0 65 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67  e SQL by calling
17000 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
17010 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69  ] one or more ti
17020 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73  mes..** <li> Res
17030 65 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  et the statement
17040 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
17050 72 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f  reset()] then go
17060 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f   back.**      to
17070 20 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69   step 2.  Do thi
17080 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74  s zero or more t
17090 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65  imes..** <li> De
170a0 73 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74  stroy the object
170b0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
170c0 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20  finalize()]..** 
170d0 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65  </ol>.**.** Refe
170e0 72 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69  r to documentati
170f0 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c  on on individual
17100 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 66   methods above f
17110 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  or additional.**
17120 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f   information..*/
17130 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
17140 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c  sqlite3_stmt sql
17150 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a  ite3_stmt;../*.*
17160 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70  * CAPI3REF: Comp
17170 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53 74 61  iling An SQL Sta
17180 74 65 6d 65 6e 74 20 7b 46 31 33 30 31 30 7d 0a  tement {F13010}.
17190 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65  **.** To execute
171a0 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 69   an SQL query, i
171b0 74 20 6d 75 73 74 20 66 69 72 73 74 20 62 65 20  t must first be 
171c0 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20  compiled into a 
171d0 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f  byte-code.** pro
171e0 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f  gram using one o
171f0 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
17200 2e 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  . .**.** The fir
17210 73 74 20 61 72 67 75 6d 65 6e 74 20 22 64 62 22  st argument "db"
17220 20 69 73 20 61 6e 20 5b 64 61 74 61 62 61 73 65   is an [database
17230 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 0a 2a 2a   connection] .**
17240 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61   obtained from a
17250 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 5b   prior call to [
17260 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
17270 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
17280 32 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  2()].** or [sqli
17290 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 0a  te3_open16()]. .
172a0 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72  ** The second ar
172b0 67 75 6d 65 6e 74 20 22 7a 53 71 6c 22 20 69 73  gument "zSql" is
172c0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74   the statement t
172d0 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65  o be compiled, e
172e0 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69 74  ncoded.** as eit
172f0 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46  her UTF-8 or UTF
17300 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69 74 65  -16.  The sqlite
17310 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e 64 20  3_prepare() and 
17320 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
17330 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  v2().** interfac
17340 65 73 20 75 73 65 73 20 55 54 46 2d 38 20 61 6e  es uses UTF-8 an
17350 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
17360 65 31 36 28 29 20 61 6e 64 20 73 71 6c 69 74 65  e16() and sqlite
17370 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
17380 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 36 2e 20  .** use UTF-16. 
17390 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 49 66 20 74  {END}.**.** If t
173a0 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e  he nByte argumen
173b0 74 20 69 73 20 6c 65 73 73 0a 2a 2a 20 74 68 61  t is less.** tha
173c0 6e 20 7a 65 72 6f 2c 20 74 68 65 6e 20 7a 53 71  n zero, then zSq
173d0 6c 20 69 73 20 72 65 61 64 20 75 70 20 74 6f 20  l is read up to 
173e0 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74  the first zero t
173f0 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66  erminator..** If
17400 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65   nByte is non-ne
17410 67 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20  gative, then it 
17420 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e  is the maximum n
17430 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 62 79 74  umber of .** byt
17440 65 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71  es read from zSq
17450 6c 2e 20 20 57 68 65 6e 20 6e 42 79 74 65 20 69  l.  When nByte i
17460 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20  s non-negative, 
17470 74 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69  the.** zSql stri
17480 6e 67 20 65 6e 64 73 20 61 74 20 65 69 74 68 65  ng ends at eithe
17490 72 20 74 68 65 20 66 69 72 73 74 20 27 5c 30 30  r the first '\00
174a0 30 27 20 6f 72 20 27 5c 75 30 30 30 30 27 20 63  0' or '\u0000' c
174b0 68 61 72 61 63 74 65 72 20 6f 72 20 0a 2a 2a 20  haracter or .** 
174c0 75 6e 74 69 6c 20 74 68 65 20 6e 42 79 74 65 2d  until the nByte-
174d0 74 68 20 62 79 74 65 2c 20 77 68 69 63 68 65 76  th byte, whichev
174e0 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 20  er comes first. 
174f0 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 2a 70 7a 54  {END}.**.** *pzT
17500 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70  ail is made to p
17510 6f 69 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73  oint to the firs
17520 74 20 62 79 74 65 20 70 61 73 74 20 74 68 65 20  t byte past the 
17530 65 6e 64 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69  end of the.** fi
17540 72 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  rst SQL statemen
17550 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73  t in zSql.  Thes
17560 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 20  e routines only 
17570 63 6f 6d 70 69 6c 65 73 20 74 68 65 20 66 69 72  compiles the fir
17580 73 74 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  st.** statement 
17590 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54  in zSql, so *pzT
175a0 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f 69 6e  ail is left poin
175b0 74 69 6e 67 20 74 6f 20 77 68 61 74 20 72 65 6d  ting to what rem
175c0 61 69 6e 73 0a 2a 2a 20 75 6e 63 6f 6d 70 69 6c  ains.** uncompil
175d0 65 64 2e 0a 2a 2a 0a 2a 2a 20 2a 70 70 53 74 6d  ed..**.** *ppStm
175e0 74 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69  t is left pointi
175f0 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64  ng to a compiled
17600 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
17610 6d 65 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 62  ment] that can b
17620 65 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73  e.** executed us
17630 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ing [sqlite3_ste
17640 70 28 29 5d 2e 20 20 4f 72 20 69 66 20 74 68 65  p()].  Or if the
17650 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c 20  re is an error, 
17660 2a 70 70 53 74 6d 74 20 69 73 0a 2a 2a 20 73 65  *ppStmt is.** se
17670 74 20 74 6f 20 4e 55 4c 4c 2e 20 20 49 66 20 74  t to NULL.  If t
17680 68 65 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f  he input text co
17690 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69  ntains no SQL (i
176a0 66 20 74 68 65 20 69 6e 70 75 74 0a 2a 2a 20 69  f the input.** i
176b0 73 20 61 6e 64 20 65 6d 70 74 79 20 73 74 72 69  s and empty stri
176c0 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29  ng or a comment)
176d0 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 69 73   then *ppStmt is
176e0 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a   set to NULL..**
176f0 20 7b 55 31 33 30 31 38 7d 20 54 68 65 20 63 61   {U13018} The ca
17700 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65 20  lling procedure 
17710 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
17720 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65 0a  or deleting the.
17730 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20  ** compiled SQL 
17740 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 75 73 69  statement.** usi
17750 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ng [sqlite3_fina
17760 6c 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74  lize()] after it
17770 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69   has finished wi
17780 74 68 20 69 74 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20  th it..**.** On 
17790 73 75 63 63 65 73 73 2c 20 5b 53 51 4c 49 54 45  success, [SQLITE
177a0 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64  _OK] is returned
177b0 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20  .  Otherwise an 
177c0 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  .** [error code]
177d0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
177e0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
177f0 70 72 65 70 61 72 65 5f 76 32 28 29 20 61 6e 64  prepare_v2() and
17800 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
17810 31 36 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63  16_v2() interfac
17820 65 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d  es are.** recomm
17830 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65  ended for all ne
17840 77 20 70 72 6f 67 72 61 6d 73 2e 20 54 68 65 20  w programs. The 
17850 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72 66  two older interf
17860 61 63 65 73 20 61 72 65 20 72 65 74 61 69 6e 65  aces are retaine
17870 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61 72  d.** for backwar
17880 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
17890 2c 20 62 75 74 20 74 68 65 69 72 20 75 73 65 20  , but their use 
178a0 69 73 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a  is discouraged..
178b0 2a 2a 20 49 6e 20 74 68 65 20 22 76 32 22 20 69  ** In the "v2" i
178c0 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 70  nterfaces, the p
178d0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
178e0 74 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74  t.** that is ret
178f0 75 72 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69  urned (the [sqli
17900 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74  te3_stmt] object
17910 29 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70  ) contains a cop
17920 79 20 6f 66 20 74 68 65 20 0a 2a 2a 20 6f 72 69  y of the .** ori
17930 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20  ginal SQL text. 
17940 7b 45 4e 44 7d 20 54 68 69 73 20 63 61 75 73 65  {END} This cause
17950 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  s the [sqlite3_s
17960 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65  tep()] interface
17970 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20 61 20   to.** behave a 
17980 64 69 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74  differently in t
17990 77 6f 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c  wo ways:.**.** <
179a0 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 49  ol>.** <li>.** I
179b0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73  f the database s
179c0 63 68 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 69  chema changes, i
179d0 6e 73 74 65 61 64 20 6f 66 20 72 65 74 75 72 6e  nstead of return
179e0 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 45  ing [SQLITE_SCHE
179f0 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77  MA] as it.** alw
17a00 61 79 73 20 75 73 65 64 20 74 6f 20 64 6f 2c 20  ays used to do, 
17a10 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
17a20 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61   will automatica
17a30 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 68  lly recompile th
17a40 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65  e SQL.** stateme
17a50 6e 74 20 61 6e 64 20 74 72 79 20 74 6f 20 72 75  nt and try to ru
17a60 6e 20 69 74 20 61 67 61 69 6e 2e 20 20 49 66 20  n it again.  If 
17a70 74 68 65 20 73 63 68 65 6d 61 20 68 61 73 20 63  the schema has c
17a80 68 61 6e 67 65 64 20 69 6e 0a 2a 2a 20 61 20 77  hanged in.** a w
17a90 61 79 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68  ay that makes th
17aa0 65 20 73 74 61 74 65 6d 65 6e 74 20 6e 6f 20 6c  e statement no l
17ab0 6f 6e 67 65 72 20 76 61 6c 69 64 2c 20 5b 73 71  onger valid, [sq
17ac0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69  lite3_step()] wi
17ad0 6c 6c 20 73 74 69 6c 6c 0a 2a 2a 20 72 65 74 75  ll still.** retu
17ae0 72 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d  rn [SQLITE_SCHEM
17af0 41 5d 2e 20 20 42 75 74 20 75 6e 6c 69 6b 65 20  A].  But unlike 
17b00 74 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76  the legacy behav
17b10 69 6f 72 2c 20 0a 2a 2a 20 5b 53 51 4c 49 54 45  ior, .** [SQLITE
17b20 5f 53 43 48 45 4d 41 5d 20 69 73 20 6e 6f 77 20  _SCHEMA] is now 
17b30 61 20 66 61 74 61 6c 20 65 72 72 6f 72 2e 20 20  a fatal error.  
17b40 43 61 6c 6c 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  Calling.** [sqli
17b50 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
17b60 5d 20 61 67 61 69 6e 20 77 69 6c 6c 20 6e 6f 74  ] again will not
17b70 20 6d 61 6b 65 20 74 68 65 0a 2a 2a 20 65 72 72   make the.** err
17b80 6f 72 20 67 6f 20 61 77 61 79 2e 20 20 4e 6f 74  or go away.  Not
17b90 65 3a 20 75 73 65 20 5b 73 71 6c 69 74 65 33 5f  e: use [sqlite3_
17ba0 65 72 72 6d 73 67 28 29 5d 20 74 6f 20 66 69 6e  errmsg()] to fin
17bb0 64 20 74 68 65 20 74 65 78 74 0a 2a 2a 20 6f 66  d the text.** of
17bc0 20 74 68 65 20 70 61 72 73 69 6e 67 20 65 72 72   the parsing err
17bd0 6f 72 20 74 68 61 74 20 72 65 73 75 6c 74 73 20  or that results 
17be0 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 53 43  in an [SQLITE_SC
17bf0 48 45 4d 41 5d 20 72 65 74 75 72 6e 2e 20 7b 45  HEMA] return. {E
17c00 4e 44 7d 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a  ND}.** </li>.**.
17c10 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 57 68 65 6e 20  ** <li>.** When 
17c20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c  an error occurs,
17c30 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74   .** [sqlite3_st
17c40 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  ep()] will retur
17c50 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74  n one of the det
17c60 61 69 6c 65 64 20 0a 2a 2a 20 5b 65 72 72 6f 72  ailed .** [error
17c70 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 65   codes] or [exte
17c80 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73  nded error codes
17c90 5d 2e 20 0a 2a 2a 20 54 68 65 20 6c 65 67 61 63  ]. .** The legac
17ca0 79 20 62 65 68 61 76 69 6f 72 20 77 61 73 20 74  y behavior was t
17cb0 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  hat [sqlite3_ste
17cc0 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20  p()] would only 
17cd0 72 65 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63  return a generic
17ce0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  .** [SQLITE_ERRO
17cf0 52 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 20 61  R] result code a
17d00 6e 64 20 79 6f 75 20 77 6f 75 6c 64 20 68 61 76  nd you would hav
17d10 65 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f  e to make a seco
17d20 6e 64 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73  nd call to.** [s
17d30 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
17d40 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64  in order to find
17d50 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20   the underlying 
17d60 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f  cause of the pro
17d70 62 6c 65 6d 2e 0a 2a 2a 20 57 69 74 68 20 74 68  blem..** With th
17d80 65 20 22 76 32 22 20 70 72 65 70 61 72 65 20 69  e "v2" prepare i
17d90 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 75  nterfaces, the u
17da0 6e 64 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e  nderlying reason
17db0 20 66 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69   for the error i
17dc0 73 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6d  s.** returned im
17dd0 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f  mediately..** </
17de0 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a  li>.** </ol>.**.
17df0 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
17e00 2a 0a 2a 2a 20 7b 46 31 33 30 31 31 7d 20 54 68  *.** {F13011} Th
17e10 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  e [sqlite3_prepa
17e20 72 65 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d  re(db,zSql,...)]
17e30 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20   and.**         
17e40 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
17e50 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e  e_v2(db,zSql,...
17e60 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 69 6e  )] interfaces in
17e70 74 65 72 70 72 65 74 20 74 68 65 0a 2a 2a 20 20  terpret the.**  
17e80 20 20 20 20 20 20 20 20 74 65 78 74 20 69 6e 20          text in 
17e90 74 68 65 69 72 20 7a 53 71 6c 20 70 61 72 61 6d  their zSql param
17ea0 65 74 65 72 20 61 73 20 55 54 46 2d 38 2e 0a 2a  eter as UTF-8..*
17eb0 2a 0a 2a 2a 20 7b 46 31 33 30 31 32 7d 20 54 68  *.** {F13012} Th
17ec0 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  e [sqlite3_prepa
17ed0 72 65 31 36 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e  re16(db,zSql,...
17ee0 29 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20  )] and.**       
17ef0 20 20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70     [sqlite3_prep
17f00 61 72 65 31 36 5f 76 32 28 64 62 2c 7a 53 71 6c  are16_v2(db,zSql
17f10 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65  ,...)] interface
17f20 73 20 69 6e 74 65 72 70 72 65 74 20 74 68 65 0a  s interpret the.
17f30 2a 2a 20 20 20 20 20 20 20 20 20 20 74 65 78 74  **          text
17f40 20 69 6e 20 74 68 65 69 72 20 7a 53 71 6c 20 70   in their zSql p
17f50 61 72 61 6d 65 74 65 72 20 61 73 20 55 54 46 2d  arameter as UTF-
17f60 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  16 in the native
17f70 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a   byte order..**.
17f80 2a 2a 20 7b 46 31 33 30 31 33 7d 20 49 66 20 74  ** {F13013} If t
17f90 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e  he nByte argumen
17fa0 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72  t to [sqlite3_pr
17fb0 65 70 61 72 65 5f 76 32 28 64 62 2c 7a 53 71 6c  epare_v2(db,zSql
17fc0 2c 6e 42 79 74 65 2c 2e 2e 2e 29 5d 0a 2a 2a 20  ,nByte,...)].** 
17fd0 20 20 20 20 20 20 20 20 20 61 6e 64 20 69 74 73           and its
17fe0 20 76 61 72 69 61 6e 74 73 20 69 73 20 6c 65 73   variants is les
17ff0 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65  s than zero, the
18000 6e 20 53 51 4c 20 74 65 78 74 20 69 73 0a 2a 2a  n SQL text is.**
18010 20 20 20 20 20 20 20 20 20 20 72 65 61 64 20 66            read f
18020 72 6f 6d 20 7a 53 71 6c 20 69 73 20 72 65 61 64  rom zSql is read
18030 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74   up to the first
18040 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
18050 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 30 31 34 7d  ..**.** {F13014}
18060 20 49 66 20 74 68 65 20 6e 42 79 74 65 20 61 72   If the nByte ar
18070 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74  gument to [sqlit
18080 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 64 62  e3_prepare_v2(db
18090 2c 7a 53 71 6c 2c 6e 42 79 74 65 2c 2e 2e 2e 29  ,zSql,nByte,...)
180a0 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e  ].**          an
180b0 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 69  d its variants i
180c0 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20  s non-negative, 
180d0 74 68 65 6e 20 6e 42 79 74 65 73 20 62 79 74 65  then nBytes byte
180e0 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53 51  s.**          SQ
180f0 4c 20 74 65 78 74 20 69 73 20 72 65 61 64 20 66  L text is read f
18100 72 6f 6d 20 7a 53 71 6c 2e 0a 2a 2a 0a 2a 2a 20  rom zSql..**.** 
18110 7b 46 31 33 30 31 35 7d 20 49 6e 20 5b 73 71 6c  {F13015} In [sql
18120 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
18130 64 62 2c 7a 53 71 6c 2c 4e 2c 50 2c 70 7a 54 61  db,zSql,N,P,pzTa
18140 69 6c 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72  il)] and its var
18150 69 61 6e 74 73 0a 2a 2a 20 20 20 20 20 20 20 20  iants.**        
18160 20 20 69 66 20 74 68 65 20 7a 53 71 6c 20 69 6e    if the zSql in
18170 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e  put text contain
18180 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20  s more than one 
18190 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  SQL statement.**
181a0 20 20 20 20 20 20 20 20 20 20 61 6e 64 20 70 7a            and pz
181b0 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  Tail is not NULL
181c0 2c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69  , then *pzTail i
181d0 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20  s made to point 
181e0 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  to the.**       
181f0 20 20 20 66 69 72 73 74 20 62 79 74 65 20 70 61     first byte pa
18200 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68  st the end of th
18210 65 20 66 69 72 73 74 20 53 51 4c 20 73 74 61 74  e first SQL stat
18220 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 0a 2a  ement in zSql..*
18230 2a 20 20 20 20 20 20 20 20 20 20 3c 74 6f 64 6f  *          <todo
18240 3e 57 68 61 74 20 64 6f 65 73 20 2a 70 7a 54 61  >What does *pzTa
18250 69 6c 20 70 6f 69 6e 74 20 74 6f 20 69 66 20 74  il point to if t
18260 68 65 72 65 20 69 73 20 6f 6e 65 20 73 74 61 74  here is one stat
18270 65 6d 65 6e 74 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a  ement?</todo>.**
18280 0a 2a 2a 20 7b 46 31 33 30 31 36 7d 20 41 20 73  .** {F13016} A s
18290 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74  uccessful call t
182a0 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  o [sqlite3_prepa
182b0 72 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 4e 2c  re_v2(db,zSql,N,
182c0 70 70 53 74 6d 74 2c 2e 2e 2e 29 5d 0a 2a 2a 20  ppStmt,...)].** 
182d0 20 20 20 20 20 20 20 20 20 6f 72 20 6f 6e 65 20           or one 
182e0 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74 73 20  of its variants 
182f0 77 72 69 74 65 73 20 69 6e 74 6f 20 2a 70 70 53  writes into *ppS
18300 74 6d 74 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  tmt a pointer to
18310 20 61 20 6e 65 77 0a 2a 2a 20 20 20 20 20 20 20   a new.**       
18320 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61     [prepared sta
18330 74 65 6d 65 6e 74 5d 20 6f 72 20 61 20 70 6f 69  tement] or a poi
18340 6e 74 65 72 20 74 6f 20 4e 55 4c 4c 0a 2a 2a 20  nter to NULL.** 
18350 20 20 20 20 20 20 20 20 20 69 66 20 7a 53 71 6c           if zSql
18360 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 74 68 69 6e   contains nothin
18370 67 20 6f 74 68 65 72 20 74 68 61 6e 20 77 68 69  g other than whi
18380 74 65 73 70 61 63 65 20 6f 72 20 63 6f 6d 6d 65  tespace or comme
18390 6e 74 73 2e 20 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  nts. .**.** {F13
183a0 30 31 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  019} The [sqlite
183b0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
183c0 69 6e 74 65 72 66 61 63 65 20 61 6e 64 20 69 74  interface and it
183d0 73 20 76 61 72 69 61 6e 74 73 20 72 65 74 75 72  s variants retur
183e0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53  n.**          [S
183f0 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 61 6e 20  QLITE_OK] or an 
18400 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72  appropriate [err
18410 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 20 66 61  or code] upon fa
18420 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  ilure..**.** {F1
18430 33 30 32 31 7d 20 42 65 66 6f 72 65 20 5b 73 71  3021} Before [sq
18440 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 64 62  lite3_prepare(db
18450 2c 7a 53 71 6c 2c 6e 42 79 74 65 2c 70 70 53 74  ,zSql,nByte,ppSt
18460 6d 74 2c 70 7a 54 61 69 6c 29 5d 20 6f 72 20 69  mt,pzTail)] or i
18470 74 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76  ts.**          v
18480 61 72 69 61 6e 74 73 20 72 65 74 75 72 6e 73 20  ariants returns 
18490 61 6e 20 65 72 72 6f 72 20 28 61 6e 79 20 76 61  an error (any va
184a0 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  lue other than [
184b0 53 51 4c 49 54 45 5f 4f 4b 5d 29 0a 2a 2a 20 20  SQLITE_OK]).**  
184c0 20 20 20 20 20 20 20 20 69 74 20 66 69 72 73 74          it first
184d0 20 73 65 74 73 20 2a 70 70 53 74 6d 74 20 74 6f   sets *ppStmt to
184e0 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71   NULL..*/.int sq
184f0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 0a 20  lite3_prepare(. 
18500 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
18510 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
18520 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
18530 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71   const char *zSq
18540 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
18550 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38  statement, UTF-8
18560 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
18570 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
18580 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
18590 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
185a0 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
185b0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
185c0 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
185d0 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
185e0 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
185f0 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
18600 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
18610 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
18620 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74  f zSql */.);.int
18630 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
18640 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v2(.  sqlite3 *
18650 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
18660 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
18670 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
18680 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  r *zSql,       /
18690 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
186a0 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a   UTF-8 encoded *
186b0 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
186c0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
186d0 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
186e0 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
186f0 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
18700 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
18710 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
18720 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
18730 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20   char **pzTail  
18740 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
18750 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
18760 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
18770 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  );.int sqlite3_p
18780 72 65 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69  repare16(.  sqli
18790 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
187a0 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
187b0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
187c0 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20  t void *zSql,   
187d0 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
187e0 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63  ment, UTF-16 enc
187f0 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
18800 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
18810 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
18820 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
18830 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
18840 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
18850 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
18860 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
18870 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a   const void **pz
18880 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
18890 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
188a0 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
188b0 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  ql */.);.int sql
188c0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
188d0 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  2(.  sqlite3 *db
188e0 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
188f0 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
18900 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
18910 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
18920 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
18930 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f  TF-16 encoded */
18940 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
18950 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
18960 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
18970 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
18980 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
18990 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
189a0 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
189b0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
189c0 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20  void **pzTail   
189d0 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
189e0 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
189f0 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
18a00 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 52 45 46  ;../*.** CAPIREF
18a10 3a 20 52 65 74 72 69 65 76 69 6e 67 20 53 74 61  : Retrieving Sta
18a20 74 65 6d 65 6e 74 20 53 51 4c 20 7b 46 31 33 31  tement SQL {F131
18a30 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  00}.**.** This i
18a40 6e 74 65 72 65 66 61 63 65 20 63 61 6e 20 62 65  ntereface can be
18a50 20 75 73 65 64 20 74 6f 20 72 65 74 72 69 65 76   used to retriev
18a60 65 20 61 20 73 61 76 65 64 20 63 6f 70 79 20 6f  e a saved copy o
18a70 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a  f the original.*
18a80 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65 64 20  * SQL text used 
18a90 74 6f 20 63 72 65 61 74 65 20 61 20 5b 70 72 65  to create a [pre
18aa0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
18ab0 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
18ac0 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 31 30  TS:.**.** {F1310
18ad0 31 7d 20 49 66 20 74 68 65 20 5b 70 72 65 70 61  1} If the [prepa
18ae0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 70  red statement] p
18af0 61 73 73 65 64 20 61 73 20 0a 2a 2a 20 20 20 20  assed as .**    
18b00 20 20 20 20 20 20 74 68 65 20 61 6e 20 61 72 67        the an arg
18b10 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65  ument to [sqlite
18b20 33 5f 73 71 6c 28 29 5d 20 77 61 73 20 63 6f 6d  3_sql()] was com
18b30 70 69 6c 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  piled.**        
18b40 20 20 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67    compiled using
18b50 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33   either [sqlite3
18b60 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
18b70 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  r.**          [s
18b80 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
18b90 5f 76 32 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20  _v2()],.**      
18ba0 20 20 20 20 74 68 65 6e 20 5b 73 71 6c 69 74 65      then [sqlite
18bb0 33 5f 73 71 6c 28 29 5d 20 66 75 6e 63 74 69 6f  3_sql()] functio
18bc0 6e 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  n returns a poin
18bd0 74 65 72 20 74 6f 20 61 0a 2a 2a 20 20 20 20 20  ter to a.**     
18be0 20 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e       zero-termin
18bf0 61 74 65 64 20 73 74 72 69 6e 67 20 63 6f 6e 74  ated string cont
18c00 61 69 6e 69 6e 67 20 61 20 55 54 46 2d 38 20 72  aining a UTF-8 r
18c10 65 6e 64 65 72 69 6e 67 0a 2a 2a 20 20 20 20 20  endering.**     
18c20 20 20 20 20 20 6f 66 20 74 68 65 20 6f 72 69 67       of the orig
18c30 69 6e 61 6c 20 53 51 4c 20 73 74 61 74 65 6d 65  inal SQL stateme
18c40 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 31 30  nt..**.** {F1310
18c50 32 7d 20 49 66 20 74 68 65 20 5b 70 72 65 70 61  2} If the [prepa
18c60 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 70  red statement] p
18c70 61 73 73 65 64 20 61 73 20 0a 2a 2a 20 20 20 20  assed as .**    
18c80 20 20 20 20 20 20 74 68 65 20 61 6e 20 61 72 67        the an arg
18c90 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65  ument to [sqlite
18ca0 33 5f 73 71 6c 28 29 5d 20 77 61 73 20 63 6f 6d  3_sql()] was com
18cb0 70 69 6c 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  piled.**        
18cc0 20 20 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67    compiled using
18cd0 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33   either [sqlite3
18ce0 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 0a 2a  _prepare()] or.*
18cf0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
18d00 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
18d10 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  ,.**          th
18d20 65 6e 20 5b 73 71 6c 69 74 65 33 5f 73 71 6c 28  en [sqlite3_sql(
18d30 29 5d 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  )] function retu
18d40 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
18d50 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 31 30  er..**.** {F1310
18d60 33 7d 20 54 68 65 20 73 74 72 69 6e 67 20 72 65  3} The string re
18d70 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
18d80 65 33 5f 73 71 6c 28 53 29 5d 20 69 73 20 76 61  e3_sql(S)] is va
18d90 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 0a 2a 2a  lid until the.**
18da0 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61            [prepa
18db0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
18dc0 20 69 73 20 64 65 6c 65 74 65 64 20 75 73 69 6e   is deleted usin
18dd0 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  g [sqlite3_final
18de0 69 7a 65 28 53 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73  ize(S)]..*/.cons
18df0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
18e00 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  sql(sqlite3_stmt
18e10 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
18e20 20 43 41 50 49 33 52 45 46 3a 20 20 44 79 6e 61   CAPI3REF:  Dyna
18e30 6d 69 63 61 6c 6c 79 20 54 79 70 65 64 20 56 61  mically Typed Va
18e40 6c 75 65 20 4f 62 6a 65 63 74 20 20 7b 46 31 35  lue Object  {F15
18e50 30 30 30 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  000}.**.** SQLit
18e60 65 20 75 73 65 73 20 74 68 65 20 73 71 6c 69 74  e uses the sqlit
18e70 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
18e80 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c  to represent all
18e90 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20   values.** that 
18ea0 61 72 65 20 6f 72 20 63 61 6e 20 62 65 20 73 74  are or can be st
18eb0 6f 72 65 64 20 69 6e 20 61 20 64 61 74 61 62 61  ored in a databa
18ec0 73 65 20 74 61 62 6c 65 2e 0a 2a 2a 20 53 51 4c  se table..** SQL
18ed0 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63  ite uses dynamic
18ee0 20 74 79 70 69 6e 67 20 66 6f 72 20 74 68 65 20   typing for the 
18ef0 76 61 6c 75 65 73 20 69 74 20 73 74 6f 72 65 73  values it stores
18f00 2e 20 20 0a 2a 2a 20 56 61 6c 75 65 73 20 73 74  .  .** Values st
18f10 6f 72 65 64 20 69 6e 20 73 71 6c 69 74 65 33 5f  ored in sqlite3_
18f20 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 63 61  value objects ca
18f30 6e 20 62 65 0a 2a 2a 20 62 65 20 69 6e 74 65 67  n be.** be integ
18f40 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f  ers, floating po
18f50 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 72 69  int values, stri
18f60 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e  ngs, BLOBs, or N
18f70 55 4c 4c 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ULL..*/.typedef 
18f80 73 74 72 75 63 74 20 4d 65 6d 20 73 71 6c 69 74  struct Mem sqlit
18f90 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a  e3_value;../*.**
18fa0 20 43 41 50 49 33 52 45 46 3a 20 20 53 51 4c 20   CAPI3REF:  SQL 
18fb0 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74  Function Context
18fc0 20 4f 62 6a 65 63 74 20 7b 46 31 36 30 30 31 7d   Object {F16001}
18fd0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65  .**.** The conte
18fe0 78 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20 53  xt in which an S
18ff0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 63  QL function exec
19000 75 74 65 73 20 69 73 20 73 74 6f 72 65 64 20 69  utes is stored i
19010 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  n an.** sqlite3_
19020 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e 20  context object. 
19030 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   A pointer to an
19040 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
19050 0a 2a 2a 20 6f 62 6a 65 63 74 20 69 73 20 61 6c  .** object is al
19060 77 61 79 73 20 66 69 72 73 74 20 70 61 72 61 6d  ways first param
19070 65 74 65 72 20 74 6f 20 61 70 70 6c 69 63 61 74  eter to applicat
19080 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
19090 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2f 0a 74 79  functions..*/.ty
190a0 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
190b0 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c  ite3_context sql
190c0 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f  ite3_context;../
190d0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20  *.** CAPI3REF:  
190e0 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 20 54  Binding Values T
190f0 6f 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  o Prepared State
19100 6d 65 6e 74 73 20 7b 46 31 33 35 30 30 7d 0a 2a  ments {F13500}.*
19110 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 53 51 4c 20  *.** In the SQL 
19120 73 74 72 69 6e 67 73 20 69 6e 70 75 74 20 74 6f  strings input to
19130 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
19140 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 74 73 0a  e_v2()] and its.
19150 2a 2a 20 76 61 72 69 61 6e 74 73 2c 20 6c 69 74  ** variants, lit
19160 65 72 61 6c 73 20 6d 61 79 20 62 65 20 72 65 70  erals may be rep
19170 6c 61 63 65 20 62 79 20 61 20 70 61 72 61 6d 65  lace by a parame
19180 74 65 72 20 69 6e 20 6f 6e 65 0a 2a 2a 20 6f 66  ter in one.** of
19190 20 74 68 65 73 65 20 66 6f 72 6d 73 3a 0a 2a 2a   these forms:.**
191a0 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
191b0 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e    ?.** <li>  ?NN
191c0 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a  N.** <li>  :VVV.
191d0 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a  ** <li>  @VVV.**
191e0 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c   <li>  $VVV.** <
191f0 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68  /ul>.**.** In th
19200 65 20 70 61 72 61 6d 65 74 65 72 20 66 6f 72 6d  e parameter form
19210 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 4e 4e  s shown above NN
19220 4e 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  N is an integer 
19230 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 56 56 56 20  literal,.** VVV 
19240 61 6c 70 68 61 2d 6e 75 6d 65 72 69 63 20 70 61  alpha-numeric pa
19250 72 61 6d 65 74 65 72 20 6e 61 6d 65 2e 0a 2a 2a  rameter name..**
19260 20 54 68 65 20 76 61 6c 75 65 73 20 6f 66 20 74   The values of t
19270 68 65 73 65 20 70 61 72 61 6d 65 74 65 72 73 20  hese parameters 
19280 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f  (also called "ho
19290 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d  st parameter nam
192a0 65 73 22 0a 2a 2a 20 6f 72 20 22 53 51 4c 20 70  es".** or "SQL p
192b0 61 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63  arameters").** c
192c0 61 6e 20 62 65 20 73 65 74 20 75 73 69 6e 67 20  an be set using 
192d0 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
192e0 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 64 65  _*() routines de
192f0 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a  fined here..**.*
19300 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
19310 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69  ment to the sqli
19320 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
19330 74 69 6e 65 73 20 61 6c 77 61 79 73 0a 2a 2a 20  tines always.** 
19340 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
19350 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  the [sqlite3_stm
19360 74 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  t] object return
19370 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69  ed from.** [sqli
19380 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
19390 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74  ] or its variant
193a0 73 2e 20 54 68 65 20 73 65 63 6f 6e 64 0a 2a 2a  s. The second.**
193b0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
193c0 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 70 61   index of the pa
193d0 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20 73 65  rameter to be se
193e0 74 2e 20 54 68 65 0a 2a 2a 20 66 69 72 73 74 20  t. The.** first 
193f0 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e  parameter has an
19400 20 69 6e 64 65 78 20 6f 66 20 31 2e 20 20 57 68   index of 1.  Wh
19410 65 6e 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  en the same name
19420 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69  d.** parameter i
19430 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e  s used more than
19440 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e   once, second an
19450 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20  d subsequent.** 
19460 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61 76 65  occurrences have
19470 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20   the same index 
19480 61 73 20 74 68 65 20 66 69 72 73 74 20 6f 63 63  as the first occ
19490 75 72 72 65 6e 63 65 2e 20 0a 2a 2a 20 54 68 65  urrence. .** The
194a0 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64   index for named
194b0 20 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20   parameters can 
194c0 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69  be looked up usi
194d0 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ng the.** [sqlit
194e0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
194f0 72 5f 6e 61 6d 65 28 29 5d 20 41 50 49 20 69 66  r_name()] API if
19500 20 64 65 73 69 72 65 64 2e 20 20 54 68 65 20 69   desired.  The i
19510 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e  ndex.** for "?NN
19520 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20 69 73  N" parameters is
19530 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e   the value of NN
19540 4e 2e 0a 2a 2a 20 54 68 65 20 4e 4e 4e 20 76 61  N..** The NNN va
19550 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65 74 77  lue must be betw
19560 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20 63 6f  een 1 and the co
19570 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 70 61  mpile-time.** pa
19580 72 61 6d 65 74 65 72 20 53 51 4c 49 54 45 5f 4d  rameter SQLITE_M
19590 41 58 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42  AX_VARIABLE_NUMB
195a0 45 52 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75  ER (default valu
195b0 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 54  e: 999)..**.** T
195c0 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
195d0 74 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 74  t is the value t
195e0 6f 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70 61  o bind to the pa
195f0 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49  rameter..**.** I
19600 6e 20 74 68 6f 73 65 0a 2a 2a 20 72 6f 75 74 69  n those.** routi
19610 6e 65 73 20 74 68 61 74 20 68 61 76 65 20 61 20  nes that have a 
19620 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c  fourth argument,
19630 20 69 74 73 20 76 61 6c 75 65 20 69 73 20 74 68   its value is th
19640 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
19650 73 0a 2a 2a 20 69 6e 20 74 68 65 20 70 61 72 61  s.** in the para
19660 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 20 63 6c  meter.  To be cl
19670 65 61 72 3a 20 74 68 65 20 76 61 6c 75 65 20 69  ear: the value i
19680 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
19690 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 0a 2a 2a 20  <u>bytes</u>.** 
196a0 69 6e 20 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f  in the value, no
196b0 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
196c0 63 68 61 72 61 63 74 65 72 73 2e 20 20 20 54 68  characters.   Th
196d0 65 20 6e 75 6d 62 65 72 0a 2a 2a 20 6f 66 20 62  e number.** of b
196e0 79 74 65 73 20 64 6f 65 73 20 6e 6f 74 20 69 6e  ytes does not in
196f0 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 2d 74  clude the zero-t
19700 65 72 6d 69 6e 61 74 6f 72 20 61 74 20 74 68 65  erminator at the
19710 20 65 6e 64 20 6f 66 20 73 74 72 69 6e 67 73 2e   end of strings.
19720 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f 75 72 74  .** If the fourt
19730 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e  h parameter is n
19740 65 67 61 74 69 76 65 2c 20 74 68 65 20 6c 65 6e  egative, the len
19750 67 74 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e  gth of the strin
19760 67 20 69 73 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f  g is.** number o
19770 66 20 62 79 74 65 73 20 75 70 20 74 6f 20 74 68  f bytes up to th
19780 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72  e first zero ter
19790 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54  minator..**.** T
197a0 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e  he fifth argumen
197b0 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  t to sqlite3_bin
197c0 64 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65  d_blob(), sqlite
197d0 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c 20 61  3_bind_text(), a
197e0 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69  nd.** sqlite3_bi
197f0 6e 64 5f 74 65 78 74 31 36 28 29 20 69 73 20 61  nd_text16() is a
19800 20 64 65 73 74 72 75 63 74 6f 72 20 75 73 65 64   destructor used
19810 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74   to dispose of t
19820 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74  he BLOB or.** st
19830 72 69 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74  ring after SQLit
19840 65 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77  e has finished w
19850 69 74 68 20 69 74 2e 20 49 66 20 74 68 65 20 66  ith it. If the f
19860 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69 73  ifth argument is
19870 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c 20  .** the special 
19880 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 54  value [SQLITE_ST
19890 41 54 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69  ATIC], then SQLi
198a0 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  te assumes that 
198b0 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  the.** informati
198c0 6f 6e 20 69 73 20 69 6e 20 73 74 61 74 69 63 2c  on is in static,
198d0 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65   unmanaged space
198e0 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65   and does not ne
198f0 65 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e 0a  ed to be freed..
19900 2a 2a 20 49 66 20 74 68 65 20 66 69 66 74 68 20  ** If the fifth 
19910 61 72 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65  argument has the
19920 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54   value [SQLITE_T
19930 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a  RANSIENT], then.
19940 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20  ** SQLite makes 
19950 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20  its own private 
19960 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61 74 61  copy of the data
19970 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65   immediately, be
19980 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69  fore.** the sqli
19990 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
199a0 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  tine returns..**
199b0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
199c0 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20  bind_zeroblob() 
199d0 72 6f 75 74 69 6e 65 20 62 69 6e 64 73 20 61 20  routine binds a 
199e0 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e  BLOB of length N
199f0 20 74 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c   that.** is fill
19a00 65 64 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20  ed with zeros.  
19a10 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73 20  A zeroblob uses 
19a20 61 20 66 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f  a fixed amount o
19a30 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73  f memory.** (jus
19a40 74 20 61 6e 20 69 6e 74 65 67 65 72 20 74 6f 20  t an integer to 
19a50 68 6f 6c 64 20 69 74 20 73 69 7a 65 29 20 77 68  hold it size) wh
19a60 69 6c 65 20 69 74 20 69 73 20 62 65 69 6e 67 20  ile it is being 
19a70 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65  processed..** Ze
19a80 72 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 65  roblobs are inte
19a90 6e 64 65 64 20 74 6f 20 73 65 72 76 65 20 61 73  nded to serve as
19aa0 20 70 6c 61 63 65 2d 68 6f 6c 64 65 72 73 20 66   place-holders f
19ab0 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a  or BLOBs whose.*
19ac0 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74  * content is lat
19ad0 65 72 20 77 72 69 74 74 65 6e 20 75 73 69 6e 67  er written using
19ae0 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c   .** [sqlite3_bl
19af0 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d  ob_open | increm
19b00 65 6e 74 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f  ent BLOB I/O] ro
19b10 75 74 69 6e 65 73 2e 20 41 20 6e 65 67 61 74 69  utines. A negati
19b20 76 65 0a 2a 2a 20 76 61 6c 75 65 20 66 6f 72 20  ve.** value for 
19b30 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73  the zeroblob res
19b40 75 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c  ults in a zero-l
19b50 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a  ength BLOB..**.*
19b60 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69  * The sqlite3_bi
19b70 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
19b80 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 61  must be called a
19b90 66 74 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  fter.** [sqlite3
19ba0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 28  _prepare_v2()] (
19bb0 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73  and its variants
19bc0 29 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ) or [sqlite3_re
19bd0 73 65 74 28 29 5d 20 61 6e 64 0a 2a 2a 20 62 65  set()] and.** be
19be0 66 6f 72 65 20 5b 73 71 6c 69 74 65 33 5f 73 74  fore [sqlite3_st
19bf0 65 70 28 29 5d 2e 0a 2a 2a 20 42 69 6e 64 69 6e  ep()]..** Bindin
19c00 67 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 61 72  gs are not clear
19c10 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74  ed by the [sqlit
19c20 65 33 5f 72 65 73 65 74 28 29 5d 20 72 6f 75 74  e3_reset()] rout
19c30 69 6e 65 2e 0a 2a 2a 20 55 6e 62 6f 75 6e 64 20  ine..** Unbound 
19c40 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 69  parameters are i
19c50 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 4e 55  nterpreted as NU
19c60 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  LL..**.** These 
19c70 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
19c80 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73  [SQLITE_OK] on s
19c90 75 63 63 65 73 73 20 6f 72 20 61 6e 20 65 72 72  uccess or an err
19ca0 6f 72 20 63 6f 64 65 20 69 66 0a 2a 2a 20 61 6e  or code if.** an
19cb0 79 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e  ything goes wron
19cc0 67 2e 20 20 5b 53 51 4c 49 54 45 5f 52 41 4e 47  g.  [SQLITE_RANG
19cd0 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  E] is returned i
19ce0 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a  f the parameter.
19cf0 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20  ** index is out 
19d00 6f 66 20 72 61 6e 67 65 2e 20 20 5b 53 51 4c 49  of range.  [SQLI
19d10 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74  TE_NOMEM] is ret
19d20 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 20  urned if malloc 
19d30 66 61 69 6c 73 2e 0a 2a 2a 20 5b 53 51 4c 49 54  fails..** [SQLIT
19d40 45 5f 4d 49 53 55 53 45 5d 20 6d 69 67 68 74 20  E_MISUSE] might 
19d50 62 65 20 72 65 74 75 72 6e 65 64 20 69 66 20 74  be returned if t
19d60 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
19d70 65 20 63 61 6c 6c 65 64 20 6f 6e 20 61 0a 2a 2a  e called on a.**
19d80 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65   virtual machine
19d90 20 74 68 61 74 20 69 73 20 74 68 65 20 77 72 6f   that is the wro
19da0 6e 67 20 73 74 61 74 65 20 6f 72 20 77 68 69 63  ng state or whic
19db0 68 20 68 61 73 20 61 6c 72 65 61 64 79 20 62 65  h has already be
19dc0 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 0a 2a 2a  en finalized..**
19dd0 20 44 65 74 65 63 74 69 6f 6e 20 6f 66 20 6d 69   Detection of mi
19de0 73 75 73 65 20 69 73 20 75 6e 72 65 6c 69 61 62  suse is unreliab
19df0 6c 65 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  le.  Application
19e00 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20 64 65 70  s should not dep
19e10 65 6e 64 0a 2a 2a 20 6f 6e 20 53 51 4c 49 54 45  end.** on SQLITE
19e20 5f 4d 49 53 55 53 45 20 72 65 74 75 72 6e 73 2e  _MISUSE returns.
19e30 20 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20    SQLITE_MISUSE 
19e40 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 69  is intended to i
19e50 6e 64 69 63 61 74 65 20 61 0a 2a 2a 20 61 20 6c  ndicate a.** a l
19e60 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 74 68  ogic error in th
19e70 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20  e application.  
19e80 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  Future versions 
19e90 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a  of SQLite might.
19ea0 2a 2a 20 70 61 6e 69 63 20 72 61 74 68 65 72 20  ** panic rather 
19eb0 74 68 61 6e 20 72 65 74 75 72 6e 20 53 51 4c 49  than return SQLI
19ec0 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 0a 2a 2a  TE_MISUSE..**.**
19ed0 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
19ee0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
19ef0 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20  er_count()],.** 
19f00 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
19f10 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c  rameter_name()],
19f20 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
19f30 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
19f40 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  index()]..**.** 
19f50 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
19f60 2a 20 7b 46 31 33 35 30 36 7d 20 54 68 65 20 5b  * {F13506} The [
19f70 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20  sqlite3_prepare 
19f80 7c 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  | SQL statement 
19f90 63 6f 6d 70 69 6c 65 72 5d 20 72 65 63 6f 67 6e  compiler] recogn
19fa0 69 7a 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  izes.**         
19fb0 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 20 66   tokens of the f
19fc0 6f 72 6d 73 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22  orms "?", "?NNN"
19fd0 2c 20 22 24 56 56 56 22 2c 20 22 3a 56 56 56 22  , "$VVV", ":VVV"
19fe0 2c 20 61 6e 64 20 22 40 56 56 56 22 0a 2a 2a 20  , and "@VVV".** 
19ff0 20 20 20 20 20 20 20 20 20 61 73 20 53 51 4c 20           as SQL 
1a000 70 61 72 61 6d 65 74 65 72 73 2c 20 77 68 65 72  parameters, wher
1a010 65 20 4e 4e 4e 20 69 73 20 61 6e 79 20 73 65 71  e NNN is any seq
1a020 75 65 6e 63 65 20 6f 66 20 6f 6e 65 20 6f 72 20  uence of one or 
1a030 6d 6f 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  more.**         
1a040 20 64 69 67 69 74 73 20 61 6e 64 20 77 68 65 72   digits and wher
1a050 65 20 56 56 56 20 69 73 20 61 6e 79 20 73 65 71  e VVV is any seq
1a060 75 65 6e 63 65 20 6f 66 20 6f 6e 65 20 6f 72 20  uence of one or 
1a070 6d 6f 72 65 20 0a 2a 2a 20 20 20 20 20 20 20 20  more .**        
1a080 20 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 63    alphanumeric c
1a090 68 61 72 61 63 74 65 72 73 20 6f 72 20 22 3a 3a  haracters or "::
1a0a0 22 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 66 6f 6c  " optionally fol
1a0b0 6c 6f 77 65 64 20 62 79 0a 2a 2a 20 20 20 20 20  lowed by.**     
1a0c0 20 20 20 20 20 61 20 73 74 72 69 6e 67 20 63 6f       a string co
1a0d0 6e 74 61 69 6e 69 6e 67 20 6e 6f 20 73 70 61 63  ntaining no spac
1a0e0 65 73 20 61 6e 64 20 63 6f 6e 74 61 69 6e 65 64  es and contained
1a0f0 20 77 69 74 68 69 6e 20 70 61 72 65 6e 74 68 65   within parenthe
1a100 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35  ses..**.** {F135
1a110 30 39 7d 20 54 68 65 20 69 6e 69 74 69 61 6c 20  09} The initial 
1a120 76 61 6c 75 65 20 6f 66 20 61 6e 20 53 51 4c 20  value of an SQL 
1a130 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c  parameter is NUL
1a140 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 31 32  L..**.** {F13512
1a150 7d 20 54 68 65 20 69 6e 64 65 78 20 6f 66 20 61  } The index of a
1a160 6e 20 22 3f 22 20 53 51 4c 20 70 61 72 61 6d 65  n "?" SQL parame
1a170 74 65 72 20 69 73 20 6f 6e 65 20 6c 61 72 67 65  ter is one large
1a180 72 20 74 68 61 6e 20 74 68 65 0a 2a 2a 20 20 20  r than the.**   
1a190 20 20 20 20 20 20 20 6c 61 72 67 65 73 74 20 69         largest i
1a1a0 6e 64 65 78 20 6f 66 20 53 51 4c 20 70 61 72 61  ndex of SQL para
1a1b0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 6c 65 66  meter to the lef
1a1c0 74 2c 20 6f 72 20 31 20 69 66 0a 2a 2a 20 20 20  t, or 1 if.**   
1a1d0 20 20 20 20 20 20 20 74 68 65 20 22 3f 22 20 69         the "?" i
1a1e0 73 20 74 68 65 20 6c 65 66 74 6d 6f 73 74 20 53  s the leftmost S
1a1f0 51 4c 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  QL parameter..**
1a200 0a 2a 2a 20 7b 46 31 33 35 31 35 7d 20 54 68 65  .** {F13515} The
1a210 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 22 3f 4e   index of an "?N
1a220 4e 4e 22 20 53 51 4c 20 70 61 72 61 6d 65 74 65  NN" SQL paramete
1a230 72 20 69 73 20 74 68 65 20 69 6e 74 65 67 65 72  r is the integer
1a240 20 4e 4e 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33   NNN..**.** {F13
1a250 35 31 38 7d 20 54 68 65 20 69 6e 64 65 78 20 6f  518} The index o
1a260 66 20 61 6e 20 22 3a 56 56 56 22 2c 20 22 24 56  f an ":VVV", "$V
1a270 56 56 22 2c 20 6f 72 20 22 40 56 56 56 22 20 53  VV", or "@VVV" S
1a280 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a  QL parameter is.
1a290 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
1a2a0 73 61 6d 65 20 61 73 20 74 68 65 20 69 6e 64 65  same as the inde
1a2b0 78 20 6f 66 20 6c 65 66 74 6d 6f 73 74 20 6f 63  x of leftmost oc
1a2c0 63 75 72 61 6e 63 65 73 20 6f 66 20 74 68 65 20  curances of the 
1a2d0 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  same.**         
1a2e0 20 70 61 72 61 6d 65 74 65 72 2c 20 6f 72 20 6f   parameter, or o
1a2f0 6e 65 20 6d 6f 72 65 20 74 68 61 6e 20 74 68 65  ne more than the
1a300 20 6c 61 72 67 65 73 74 20 69 6e 64 65 78 20 6f   largest index o
1a310 76 65 72 20 61 6c 6c 0a 2a 2a 20 20 20 20 20 20  ver all.**      
1a320 20 20 20 20 70 61 72 61 6d 65 74 65 72 73 20 74      parameters t
1a330 6f 20 74 68 65 20 6c 65 66 74 20 69 66 20 74 68  o the left if th
1a340 69 73 20 69 73 20 74 68 65 20 66 69 72 73 74 20  is is the first 
1a350 6f 63 63 75 72 72 61 6e 63 65 0a 2a 2a 20 20 20  occurrance.**   
1a360 20 20 20 20 20 20 20 6f 66 20 74 68 69 73 20 70         of this p
1a370 61 72 61 6d 65 74 65 72 2c 20 6f 72 20 31 20 69  arameter, or 1 i
1a380 66 20 74 68 69 73 20 69 73 20 74 68 65 20 6c 65  f this is the le
1a390 66 74 6d 6f 73 74 20 70 61 72 61 6d 65 74 65 72  ftmost parameter
1a3a0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 32 31 7d  ..**.** {F13521}
1a3b0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72   The [sqlite3_pr
1a3c0 65 70 61 72 65 20 7c 20 53 51 4c 20 73 74 61 74  epare | SQL stat
1a3d0 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 5d 20  ement compiler] 
1a3e0 66 61 69 6c 20 77 69 74 68 0a 2a 2a 20 20 20 20  fail with.**    
1a3f0 20 20 20 20 20 20 61 6e 20 5b 53 51 4c 49 54 45        an [SQLITE
1a400 5f 52 41 4e 47 45 5d 20 65 72 72 6f 72 20 69 66  _RANGE] error if
1a410 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e   the index of an
1a420 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 0a 2a   SQL parameter.*
1a430 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 6c 65  *          is le
1a440 73 73 20 74 68 61 6e 20 31 20 6f 72 20 67 72 65  ss than 1 or gre
1a450 61 74 65 72 20 74 68 61 6e 20 53 51 4c 49 54 45  ater than SQLITE
1a460 5f 4d 41 58 5f 56 41 52 49 41 42 4c 45 5f 4e 55  _MAX_VARIABLE_NU
1a470 4d 42 45 52 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  MBER..**.** {F13
1a480 35 32 34 7d 20 43 61 6c 6c 73 20 74 6f 20 5b 73  524} Calls to [s
1a490 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
1a4a0 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 28   | sqlite3_bind(
1a4b0 53 2c 4e 2c 56 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20  S,N,V,...)].**  
1a4c0 20 20 20 20 20 20 20 20 61 73 73 6f 63 69 61 74          associat
1a4d0 65 20 74 68 65 20 76 61 6c 75 65 20 56 20 77 69  e the value V wi
1a4e0 74 68 20 61 6c 6c 20 53 51 4c 20 70 61 72 61 6d  th all SQL param
1a4f0 65 74 65 72 73 20 68 61 76 69 6e 67 20 61 6e 0a  eters having an.
1a500 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 64 65  **          inde
1a510 78 20 6f 66 20 4e 20 69 6e 20 74 68 65 20 5b 70  x of N in the [p
1a520 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1a530 74 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  t] S..**.** {F13
1a540 35 32 37 7d 20 43 61 6c 6c 73 20 74 6f 20 5b 73  527} Calls to [s
1a550 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
1a560 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 28   | sqlite3_bind(
1a570 53 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20  S,N,...)].**    
1a580 20 20 20 20 20 20 6f 76 65 72 72 69 64 65 20 70        override p
1a590 72 69 6f 72 20 63 61 6c 6c 73 20 77 69 74 68 20  rior calls with 
1a5a0 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65 73 20  the same values 
1a5b0 6f 66 20 53 20 61 6e 64 20 4e 2e 0a 2a 2a 0a 2a  of S and N..**.*
1a5c0 2a 20 7b 46 31 33 35 33 30 7d 20 42 69 6e 64 69  * {F13530} Bindi
1a5d0 6e 67 73 20 65 73 74 61 62 6c 69 73 68 65 64 20  ngs established 
1a5e0 62 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  by [sqlite3_bind
1a5f0 5f 74 65 78 74 20 7c 20 73 71 6c 69 74 65 33 5f  _text | sqlite3_
1a600 62 69 6e 64 28 53 2c 2e 2e 2e 29 5d 0a 2a 2a 20  bind(S,...)].** 
1a610 20 20 20 20 20 20 20 20 20 70 65 72 73 69 73 74           persist
1a620 20 61 63 72 6f 73 73 20 63 61 6c 6c 73 20 74 6f   across calls to
1a630 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
1a640 53 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35  S)]..**.** {F135
1a650 33 33 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20  33} In calls to 
1a660 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
1a670 6f 62 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a  ob(S,N,V,L,D)],.
1a680 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
1a690 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 53  ite3_bind_text(S
1a6a0 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 20 6f 72 0a 2a  ,N,V,L,D)], or.*
1a6b0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
1a6c0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
1a6d0 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 53 51 4c 69  S,N,V,L,D)] SQLi
1a6e0 74 65 20 62 69 6e 64 73 20 74 68 65 20 66 69 72  te binds the fir
1a6f0 73 74 20 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20  st L.**         
1a700 20 62 79 74 65 73 20 6f 66 20 74 68 65 20 62 6c   bytes of the bl
1a710 6f 62 20 6f 72 20 73 74 72 69 6e 67 20 70 6f 69  ob or string poi
1a720 6e 74 65 64 20 74 6f 20 62 79 20 56 2c 20 77 68  nted to by V, wh
1a730 65 6e 20 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20  en L.**         
1a740 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
1a750 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 33 36 7d  ..**.** {F13536}
1a760 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71   In calls to [sq
1a770 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
1a780 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 6f 72 0a 2a  S,N,V,L,D)] or.*
1a790 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
1a7a0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
1a7b0 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 53 51 4c 69  S,N,V,L,D)] SQLi
1a7c0 74 65 20 62 69 6e 64 73 20 63 68 61 72 61 63 74  te binds charact
1a7d0 65 72 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ers.**          
1a7e0 66 72 6f 6d 20 56 20 74 68 72 6f 75 67 68 20 74  from V through t
1a7f0 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68  he first zero ch
1a800 61 72 61 63 74 65 72 20 77 68 65 6e 20 4c 20 69  aracter when L i
1a810 73 20 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a  s negative..**.*
1a820 2a 20 7b 46 31 33 35 33 39 7d 20 49 6e 20 63 61  * {F13539} In ca
1a830 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
1a840 62 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56 2c  bind_blob(S,N,V,
1a850 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  L,D)],.**       
1a860 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64     [sqlite3_bind
1a870 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29  _text(S,N,V,L,D)
1a880 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  ], or.**        
1a890 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f    [sqlite3_bind_
1a8a0 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44  text16(S,N,V,L,D
1a8b0 29 5d 20 77 68 65 6e 20 44 20 69 73 20 74 68 65  )] when D is the
1a8c0 20 73 70 65 63 69 61 6c 0a 2a 2a 20 20 20 20 20   special.**     
1a8d0 20 20 20 20 20 63 6f 6e 73 74 61 6e 74 20 5b 53       constant [S
1a8e0 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 53  QLITE_STATIC], S
1a8f0 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68  QLite assumes th
1a900 61 74 20 74 68 65 20 76 61 6c 75 65 20 56 0a 2a  at the value V.*
1a910 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 68 65  *          is he
1a920 6c 64 20 69 6e 20 73 74 61 74 69 63 20 75 6e 6d  ld in static unm
1a930 61 6e 61 67 65 64 20 73 70 61 63 65 20 74 68 61  anaged space tha
1a940 74 20 77 69 6c 6c 20 6e 6f 74 20 63 68 61 6e 67  t will not chang
1a950 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 75  e.**          du
1a960 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d  ring the lifetim
1a970 65 20 6f 66 20 74 68 65 20 62 69 6e 64 69 6e 67  e of the binding
1a980 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 34 32 7d  ..**.** {F13542}
1a990 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71   In calls to [sq
1a9a0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
1a9b0 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20  S,N,V,L,D)],.** 
1a9c0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
1a9d0 33 5f 62 69 6e 64 5f 74 65 78 74 28 53 2c 4e 2c  3_bind_text(S,N,
1a9e0 56 2c 4c 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20  V,L,D)], or.**  
1a9f0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
1aa00 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e  _bind_text16(S,N
1aa10 2c 56 2c 4c 2c 44 29 5d 20 77 68 65 6e 20 44 20  ,V,L,D)] when D 
1aa20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 0a 2a  is the special.*
1aa30 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e 73 74  *          const
1aa40 61 6e 74 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e  ant [SQLITE_TRAN
1aa50 53 49 45 4e 54 5d 2c 20 74 68 65 20 72 6f 75 74  SIENT], the rout
1aa60 69 6e 65 20 6d 61 6b 65 73 20 61 20 0a 2a 2a 20  ine makes a .** 
1aa70 20 20 20 20 20 20 20 20 20 70 72 69 76 61 74 65           private
1aa80 20 63 6f 70 79 20 6f 66 20 56 20 76 61 6c 75 65   copy of V value
1aa90 20 62 65 66 6f 72 65 20 69 74 20 72 65 74 75 72   before it retur
1aaa0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 34  ns..**.** {F1354
1aab0 35 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b  5} In calls to [
1aac0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
1aad0 62 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a  b(S,N,V,L,D)],.*
1aae0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
1aaf0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 53 2c  te3_bind_text(S,
1ab00 4e 2c 56 2c 4c 2c 44 29 5d 2c 20 6f 72 0a 2a 2a  N,V,L,D)], or.**
1ab10 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
1ab20 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 53  e3_bind_text16(S
1ab30 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 77 68 65 6e 20  ,N,V,L,D)] when 
1ab40 44 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  D is a pointer t
1ab50 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20  o.**          a 
1ab60 66 75 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65  function, SQLite
1ab70 20 69 6e 76 6f 6b 65 73 20 74 68 61 74 20 66 75   invokes that fu
1ab80 6e 63 74 69 6f 6e 20 74 6f 20 64 65 73 74 72 6f  nction to destro
1ab90 79 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  y the.**        
1aba0 20 20 56 20 76 61 6c 75 65 20 61 66 74 65 72 20    V value after 
1abb0 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  it has finished 
1abc0 75 73 69 6e 67 20 74 68 65 20 56 20 76 61 6c 75  using the V valu
1abd0 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 34 38  e..**.** {F13548
1abe0 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73  } In calls to [s
1abf0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f  qlite3_bind_zero
1ac00 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 29 5d 20 74  blob(S,N,V,L)] t
1ac10 68 65 20 76 61 6c 75 65 20 62 6f 75 6e 64 0a 2a  he value bound.*
1ac20 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 61 20  *          is a 
1ac30 62 6c 6f 62 20 6f 66 20 4c 20 62 79 74 65 73 2c  blob of L bytes,
1ac40 20 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74   or a zero-lengt
1ac50 68 20 62 6c 6f 62 20 69 66 20 4c 20 69 73 20 6e  h blob if L is n
1ac60 65 67 61 74 69 76 65 2e 0a 2a 2f 0a 69 6e 74 20  egative..*/.int 
1ac70 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
1ac80 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  b(sqlite3_stmt*,
1ac90 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64   int, const void
1aca0 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a  *, int n, void(*
1acb0 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73  )(void*));.int s
1acc0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62  qlite3_bind_doub
1acd0 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  le(sqlite3_stmt*
1ace0 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a  , int, double);.
1acf0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
1ad00 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  _int(sqlite3_stm
1ad10 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 69  t*, int, int);.i
1ad20 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
1ad30 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74  int64(sqlite3_st
1ad40 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65  mt*, int, sqlite
1ad50 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73 71  3_int64);.int sq
1ad60 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28  lite3_bind_null(
1ad70 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
1ad80 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  nt);.int sqlite3
1ad90 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74  _bind_text(sqlit
1ada0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
1adb0 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 20  onst char*, int 
1adc0 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  n, void(*)(void*
1add0 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  ));.int sqlite3_
1ade0 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69  bind_text16(sqli
1adf0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
1ae00 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
1ae10 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
1ae20 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
1ae30 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 65  ind_value(sqlite
1ae40 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
1ae50 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  nst sqlite3_valu
1ae60 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
1ae70 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73  _bind_zeroblob(s
1ae80 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
1ae90 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a  t, int n);../*.*
1aea0 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62  * CAPI3REF: Numb
1aeb0 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61 6d 65  er Of SQL Parame
1aec0 74 65 72 73 20 7b 46 31 33 36 30 30 7d 0a 2a 2a  ters {F13600}.**
1aed0 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
1aee0 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
1aef0 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20  find the number 
1af00 6f 66 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  of SQL parameter
1af10 73 0a 2a 2a 20 69 6e 20 61 20 70 72 65 70 61 72  s.** in a prepar
1af20 65 64 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 53  ed statement.  S
1af30 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 61 72  QL parameters ar
1af40 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a  e tokens of the.
1af50 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e  ** form "?", "?N
1af60 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41  NN", ":AAA", "$A
1af70 41 41 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74  AA", or "@AAA" t
1af80 68 61 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20  hat serve as.** 
1af90 70 6c 61 63 65 2d 68 6f 6c 64 65 72 73 20 66 6f  place-holders fo
1afa0 72 20 76 61 6c 75 65 73 20 74 68 61 74 20 61 72  r values that ar
1afb0 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
1afc0 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a  blob | bound].**
1afd0 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65   to the paramete
1afe0 72 73 20 61 74 20 61 20 6c 61 74 65 72 20 74 69  rs at a later ti
1aff0 6d 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  me..**.** This r
1b000 6f 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20  outine actually 
1b010 72 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65  returns the inde
1b020 78 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74  x of the largest
1b030 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 46   parameter..** F
1b040 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63  or all forms exc
1b050 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77  ept ?NNN, this w
1b060 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20 74  ill correspond t
1b070 6f 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  o the number of.
1b080 2a 2a 20 75 6e 69 71 75 65 20 70 61 72 61 6d 65  ** unique parame
1b090 74 65 72 73 2e 20 20 49 66 20 70 61 72 61 6d 65  ters.  If parame
1b0a0 74 65 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e  ters of the ?NNN
1b0b0 20 61 72 65 20 75 73 65 64 2c 20 74 68 65 72 65   are used, there
1b0c0 20 6d 61 79 0a 2a 2a 20 62 65 20 67 61 70 73 20   may.** be gaps 
1b0d0 69 6e 20 74 68 65 20 6c 69 73 74 2e 0a 2a 2a 0a  in the list..**.
1b0e0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
1b0f0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
1b100 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c  sqlite3_bind()],
1b110 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
1b120 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
1b130 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
1b140 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
1b150 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a  ter_index()]..**
1b160 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
1b170 2a 2a 0a 2a 2a 20 7b 46 31 33 36 30 31 7d 20 54  **.** {F13601} T
1b180 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  he [sqlite3_bind
1b190 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
1b1a0 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  (S)] interface r
1b1b0 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20  eturns.**       
1b1c0 20 20 20 74 68 65 20 6c 61 72 67 65 73 74 20 69     the largest i
1b1d0 6e 64 65 78 20 6f 66 20 61 6c 6c 20 53 51 4c 20  ndex of all SQL 
1b1e0 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20 74 68  parameters in th
1b1f0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  e.**          [p
1b200 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1b210 74 5d 20 53 2c 20 6f 72 20 30 20 69 66 20 53 0a  t] S, or 0 if S.
1b220 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e 74  **          cont
1b230 61 69 6e 73 20 6e 6f 20 53 51 4c 20 70 61 72 61  ains no SQL para
1b240 6d 65 74 65 72 73 2e 0a 2a 2f 0a 69 6e 74 20 73  meters..*/.int s
1b250 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
1b260 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69  meter_count(sqli
1b270 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
1b280 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d  ** CAPI3REF: Nam
1b290 65 20 4f 66 20 41 20 48 6f 73 74 20 50 61 72 61  e Of A Host Para
1b2a0 6d 65 74 65 72 20 7b 46 31 33 36 32 30 7d 0a 2a  meter {F13620}.*
1b2b0 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
1b2c0 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
1b2d0 74 65 72 20 74 6f 20 74 68 65 20 6e 61 6d 65 20  ter to the name 
1b2e0 6f 66 20 74 68 65 20 6e 2d 74 68 0a 2a 2a 20 53  of the n-th.** S
1b2f0 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20  QL parameter in 
1b300 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
1b310 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 53 51 4c 20 70  ement]..** SQL p
1b320 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
1b330 20 66 6f 72 6d 20 22 3a 41 41 41 22 20 6f 72 20   form ":AAA" or 
1b340 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22  "@AAA" or "$AAA"
1b350 20 68 61 76 65 20 61 20 6e 61 6d 65 0a 2a 2a 20   have a name.** 
1b360 77 68 69 63 68 20 69 73 20 74 68 65 20 73 74 72  which is the str
1b370 69 6e 67 20 22 3a 41 41 41 22 20 6f 72 20 22 40  ing ":AAA" or "@
1b380 41 41 41 22 20 6f 72 20 22 24 56 56 56 22 2e 20  AAA" or "$VVV". 
1b390 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  .** In other wor
1b3a0 64 73 2c 20 74 68 65 20 69 6e 69 74 69 61 6c 20  ds, the initial 
1b3b0 22 3a 22 20 6f 72 20 22 24 22 20 6f 72 20 22 40  ":" or "$" or "@
1b3c0 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 64  ".** is included
1b3d0 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 20   as part of the 
1b3e0 6e 61 6d 65 2e 0a 2a 2a 20 50 61 72 61 6d 65 74  name..** Paramet
1b3f0 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20  ers of the form 
1b400 22 3f 22 20 6f 72 20 22 3f 4e 4e 4e 22 20 68 61  "?" or "?NNN" ha
1b410 76 65 20 6e 6f 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a  ve no name..**.*
1b420 2a 20 54 68 65 20 66 69 72 73 74 20 68 6f 73 74  * The first host
1b430 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61   parameter has a
1b440 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f  n index of 1, no
1b450 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  t 0..**.** If th
1b460 65 20 76 61 6c 75 65 20 6e 20 69 73 20 6f 75 74  e value n is out
1b470 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 69 66 20   of range or if 
1b480 74 68 65 20 6e 2d 74 68 20 70 61 72 61 6d 65 74  the n-th paramet
1b490 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73  er is.** nameles
1b4a0 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20  s, then NULL is 
1b4b0 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 72  returned.  The r
1b4c0 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69  eturned string i
1b4d0 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 74  s.** always in t
1b4e0 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e  he UTF-8 encodin
1b4f0 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61  g even if the na
1b500 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20 77 61  med parameter wa
1b510 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20  s.** originally 
1b520 73 70 65 63 69 66 69 65 64 20 61 73 20 55 54 46  specified as UTF
1b530 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f  -16 in [sqlite3_
1b540 70 72 65 70 61 72 65 31 36 28 29 5d 20 6f 72 0a  prepare16()] or.
1b550 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
1b560 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a  are16_v2()]..**.
1b570 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
1b580 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
1b590 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c  sqlite3_bind()],
1b5a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
1b5b0 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
1b5c0 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  t()], and.** [sq
1b5d0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
1b5e0 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a  eter_index()]..*
1b5f0 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
1b600 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 36 32 31 7d 20  .**.** {F13621} 
1b610 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  The [sqlite3_bin
1b620 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
1b630 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  (S,N)] interface
1b640 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20   returns.**     
1b650 20 20 20 20 20 61 20 55 54 46 2d 38 20 72 65 6e       a UTF-8 ren
1b660 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 6e 61  dering of the na
1b670 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20 70 61  me of the SQL pa
1b680 72 61 6d 65 74 65 72 20 69 6e 0a 2a 2a 20 20 20  rameter in.**   
1b690 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64         [prepared
1b6a0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 68 61   statement] S ha
1b6b0 76 69 6e 67 20 69 6e 64 65 78 20 4e 2c 20 6f 72  ving index N, or
1b6c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 55 4c  .**          NUL
1b6d0 4c 20 69 66 20 74 68 65 72 65 20 69 73 20 6e 6f  L if there is no
1b6e0 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 77   SQL parameter w
1b6f0 69 74 68 20 69 6e 64 65 78 20 4e 20 6f 72 20 69  ith index N or i
1b700 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  f the.**        
1b710 20 20 70 61 72 61 6d 65 74 65 72 20 77 69 74 68    parameter with
1b720 20 69 6e 64 65 78 20 4e 20 69 73 20 61 6e 20 61   index N is an a
1b730 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 74  nonymous paramet
1b740 65 72 20 22 3f 22 20 6f 72 0a 2a 2a 20 20 20 20  er "?" or.**    
1b750 20 20 20 20 20 20 61 20 6e 75 6d 62 65 72 65 64        a numbered
1b760 20 70 61 72 61 6d 65 74 65 72 20 22 3f 4e 4e 4e   parameter "?NNN
1b770 22 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  "..*/.const char
1b780 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   *sqlite3_bind_p
1b790 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71  arameter_name(sq
1b7a0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
1b7b0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1b7c0 45 46 3a 20 49 6e 64 65 78 20 4f 66 20 41 20 50  EF: Index Of A P
1b7d0 61 72 61 6d 65 74 65 72 20 57 69 74 68 20 41 20  arameter With A 
1b7e0 47 69 76 65 6e 20 4e 61 6d 65 20 7b 46 31 33 36  Given Name {F136
1b7f0 34 30 7d 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e  40}.**.** Return
1b800 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e   the index of an
1b810 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67   SQL parameter g
1b820 69 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20  iven its name.  
1b830 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c  The.** index val
1b840 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 73  ue returned is s
1b850 75 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20  uitable for use 
1b860 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a  as the second.**
1b870 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
1b880 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
1b890 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
1b8a0 2e 20 20 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20  .  A zero.** is 
1b8b0 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d  returned if no m
1b8c0 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65  atching paramete
1b8d0 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 54 68 65  r is found.  The
1b8e0 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61   parameter.** na
1b8f0 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e  me must be given
1b900 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69   in UTF-8 even i
1b910 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73  f the original s
1b920 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20  tatement.** was 
1b930 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54  prepared from UT
1b940 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67 20  F-16 text using 
1b950 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1b960 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  16_v2()]..**.** 
1b970 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
1b980 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c  e3_bind_blob|sql
1b990 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a  ite3_bind()],.**
1b9a0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
1b9b0 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29  arameter_count()
1b9c0 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
1b9d0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
1b9e0 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a  r_index()]..**.*
1b9f0 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
1ba00 0a 2a 2a 20 7b 46 31 33 36 34 31 7d 20 54 68 65  .** {F13641} The
1ba10 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
1ba20 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 53  arameter_index(S
1ba30 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  ,N)] interface r
1ba40 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20  eturns.**       
1ba50 20 20 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20     the index of 
1ba60 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 6e  SQL parameter in
1ba70 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1ba80 6d 65 6e 74 5d 0a 2a 2a 20 20 20 20 20 20 20 20  ment].**        
1ba90 20 20 53 20 77 68 6f 73 65 20 6e 61 6d 65 20 6d    S whose name m
1baa0 61 74 63 68 65 73 20 74 68 65 20 55 54 46 2d 38  atches the UTF-8
1bab0 20 73 74 72 69 6e 67 20 4e 2c 20 6f 72 20 30 20   string N, or 0 
1bac0 69 66 20 74 68 65 72 65 20 69 73 0a 2a 2a 20 20  if there is.**  
1bad0 20 20 20 20 20 20 20 20 6e 6f 20 6d 61 74 63 68          no match
1bae0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
1baf0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
1bb00 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f 73 74  index(sqlite3_st
1bb10 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  mt*, const char 
1bb20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *zName);../*.** 
1bb30 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20  CAPI3REF: Reset 
1bb40 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20  All Bindings On 
1bb50 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
1bb60 6d 65 6e 74 20 7b 46 31 33 36 36 30 7d 0a 2a 2a  ment {F13660}.**
1bb70 0a 2a 2a 20 43 6f 6e 74 72 61 72 79 20 74 6f 20  .** Contrary to 
1bb80 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66  the intuition of
1bb90 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f   many, [sqlite3_
1bba0 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f  reset()] does no
1bbb0 74 0a 2a 2a 20 72 65 73 65 74 20 74 68 65 20 5b  t.** reset the [
1bbc0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
1bbd0 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e  b | bindings] on
1bbe0 20 61 20 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64   a .** [prepared
1bbf0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 55 73   statement].  Us
1bc00 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74  e this routine t
1bc10 6f 0a 2a 2a 20 72 65 73 65 74 20 61 6c 6c 20 68  o.** reset all h
1bc20 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 74  ost parameters t
1bc30 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 49 4e  o NULL..**.** IN
1bc40 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
1bc50 7b 46 31 33 36 36 31 7d 20 54 68 65 20 5b 73 71  {F13661} The [sq
1bc60 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64  lite3_clear_bind
1bc70 69 6e 67 73 28 53 29 5d 20 69 6e 74 65 72 66 61  ings(S)] interfa
1bc80 63 65 20 72 65 73 65 74 73 20 61 6c 6c 0a 2a 2a  ce resets all.**
1bc90 20 20 20 20 20 20 20 20 20 20 53 51 4c 20 70 61            SQL pa
1bca0 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 73  rameter bindings
1bcb0 20 69 6e 20 5b 70 72 65 70 61 72 65 64 20 73 74   in [prepared st
1bcc0 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 20 20  atement] S.**   
1bcd0 20 20 20 20 20 20 20 62 61 63 6b 20 74 6f 20 4e         back to N
1bce0 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ULL..*/.int sqli
1bcf0 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e  te3_clear_bindin
1bd00 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  gs(sqlite3_stmt*
1bd10 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1bd20 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f  EF: Number Of Co
1bd30 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 6c  lumns In A Resul
1bd40 74 20 53 65 74 20 7b 46 31 33 37 31 30 7d 0a 2a  t Set {F13710}.*
1bd50 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 74 68 65 20  *.** Return the 
1bd60 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
1bd70 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20  s in the result 
1bd80 73 65 74 20 72 65 74 75 72 6e 65 64 20 62 79 20  set returned by 
1bd90 74 68 65 20 0a 2a 2a 20 5b 70 72 65 70 61 72 65  the .** [prepare
1bda0 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 54 68  d statement]. Th
1bdb0 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  is routine retur
1bdc0 6e 73 20 30 0a 2a 2a 20 69 66 20 70 53 74 6d 74  ns 0.** if pStmt
1bdd0 20 69 73 20 61 6e 20 53 51 4c 20 73 74 61 74 65   is an SQL state
1bde0 6d 65 6e 74 20 74 68 61 74 20 64 6f 65 73 20 6e  ment that does n
1bdf0 6f 74 20 72 65 74 75 72 6e 20 64 61 74 61 20 28  ot return data (
1be00 66 6f 72 20 0a 2a 2a 20 65 78 61 6d 70 6c 65 20  for .** example 
1be10 61 6e 20 55 50 44 41 54 45 29 2e 0a 2a 2a 0a 2a  an UPDATE)..**.*
1be20 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
1be30 0a 2a 2a 20 7b 46 31 33 37 31 31 7d 20 54 68 65  .** {F13711} The
1be40 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
1be50 5f 63 6f 75 6e 74 28 53 29 5d 20 69 6e 74 65 72  _count(S)] inter
1be60 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
1be70 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 20 20   number of.**   
1be80 20 20 20 20 20 20 20 63 6f 6c 75 6d 6e 73 20 69         columns i
1be90 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  n the result set
1bea0 20 67 65 6e 65 72 61 74 65 64 20 62 79 20 74 68   generated by th
1beb0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  e.**          [p
1bec0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1bed0 74 5d 20 53 2c 20 6f 72 20 30 20 69 66 20 53 20  t] S, or 0 if S 
1bee0 64 6f 65 73 20 6e 6f 74 20 67 65 6e 65 72 61 74  does not generat
1bef0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20  e.**          a 
1bf00 72 65 73 75 6c 74 20 73 65 74 2e 0a 2a 2f 0a 69  result set..*/.i
1bf10 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
1bf20 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  n_count(sqlite3_
1bf30 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
1bf40 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
1bf50 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41  olumn Names In A
1bf60 20 52 65 73 75 6c 74 20 53 65 74 20 7b 46 31 33   Result Set {F13
1bf70 37 32 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  720}.**.** These
1bf80 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
1bf90 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e   the name assign
1bfa0 65 64 20 74 6f 20 61 20 70 61 72 74 69 63 75 6c  ed to a particul
1bfb0 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20  ar column.** in 
1bfc0 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f  the result set o
1bfd0 66 20 61 20 53 45 4c 45 43 54 20 73 74 61 74 65  f a SELECT state
1bfe0 6d 65 6e 74 2e 20 20 54 68 65 20 73 71 6c 69 74  ment.  The sqlit
1bff0 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29  e3_column_name()
1c000 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65  .** interface re
1c010 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
1c020 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  to a zero-termin
1c030 61 74 65 64 20 55 54 46 38 20 73 74 72 69 6e 67  ated UTF8 string
1c040 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  .** and sqlite3_
1c050 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20  column_name16() 
1c060 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
1c070 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d  r to a zero-term
1c080 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 31 36 20  inated.** UTF16 
1c090 73 74 72 69 6e 67 2e 20 20 54 68 65 20 66 69 72  string.  The fir
1c0a0 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  st parameter is 
1c0b0 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
1c0c0 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
1c0d0 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20   implements the 
1c0e0 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74  SELECT statement
1c0f0 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
1c100 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
1c110 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20   column number. 
1c120 20 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63   The left-most c
1c130 6f 6c 75 6d 6e 20 69 73 0a 2a 2a 20 6e 75 6d 62  olumn is.** numb
1c140 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  er 0..**.** The 
1c150 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
1c160 70 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64  pointer is valid
1c170 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68   until either th
1c180 65 20 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  e .** [prepared 
1c190 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65  statement] is de
1c1a0 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69  stroyed by [sqli
1c1b0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a  te3_finalize()].
1c1c0 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  ** or until the 
1c1d0 6e 65 78 74 20 63 61 6c 6c 20 73 71 6c 69 74 65  next call sqlite
1c1e0 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20  3_column_name() 
1c1f0 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  or sqlite3_colum
1c200 6e 5f 6e 61 6d 65 31 36 28 29 0a 2a 2a 20 6f 6e  n_name16().** on
1c210 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e   the same column
1c220 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 73 71 6c 69 74  ..**.** If sqlit
1c230 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c  e3_malloc() fail
1c240 73 20 64 75 72 69 6e 67 20 74 68 65 20 70 72 6f  s during the pro
1c250 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68 65  cessing of eithe
1c260 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f  r routine.** (fo
1c270 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e 67  r example during
1c280 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72   a conversion fr
1c290 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46 2d  om UTF-8 to UTF-
1c2a0 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55  16) then a.** NU
1c2b0 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65  LL pointer is re
1c2c0 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  turned..**.** Th
1c2d0 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65 73 75  e name of a resu
1c2e0 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65  lt column is the
1c2f0 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 22 41   value of the "A
1c300 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a  S" clause for.**
1c310 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66   that column, if
1c320 20 74 68 65 72 65 20 69 73 20 61 6e 20 41 53 20   there is an AS 
1c330 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68 65 72  clause.  If ther
1c340 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61 75 73  e is no AS claus
1c350 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e 61  e.** then the na
1c360 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  me of the column
1c370 20 69 73 20 75 6e 73 70 65 63 69 66 69 65 64 20   is unspecified 
1c380 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 20 66  and may change f
1c390 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61  rom.** one relea
1c3a0 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74 6f 20  se of SQLite to 
1c3b0 74 68 65 20 6e 65 78 74 2e 0a 2a 2a 0a 2a 2a 20  the next..**.** 
1c3c0 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
1c3d0 2a 20 7b 46 31 33 37 32 31 7d 20 41 20 73 75 63  * {F13721} A suc
1c3e0 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69  cessful invocati
1c3f0 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  on of the [sqlit
1c400 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 53  e3_column_name(S
1c410 2c 4e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ,N)].**         
1c420 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
1c430 6e 73 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 20  ns the name.**  
1c440 20 20 20 20 20 20 20 20 6f 66 20 74 68 65 20 4e          of the N
1c450 74 68 20 63 6f 6c 75 6d 6e 20 28 77 68 65 72 65  th column (where
1c460 20 30 20 69 73 20 74 68 65 20 6c 65 66 74 2d 6d   0 is the left-m
1c470 6f 73 74 20 63 6f 6c 75 6d 6e 29 20 66 6f 72 20  ost column) for 
1c480 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
1c490 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 5b 70  result set of [p
1c4a0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1c4b0 74 5d 20 53 20 61 73 20 61 0a 2a 2a 20 20 20 20  t] S as a.**    
1c4c0 20 20 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69        zero-termi
1c4d0 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69  nated UTF-8 stri
1c4e0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 32  ng..**.** {F1372
1c4f0 33 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20  3} A successful 
1c500 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68  invocation of th
1c510 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
1c520 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 0a 2a  n_name16(S,N)].*
1c530 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 72  *          inter
1c540 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
1c550 20 6e 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20   name.**        
1c560 20 20 6f 66 20 74 68 65 20 4e 74 68 20 63 6f 6c    of the Nth col
1c570 75 6d 6e 20 28 77 68 65 72 65 20 30 20 69 73 20  umn (where 0 is 
1c580 74 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f  the left-most co
1c590 6c 75 6d 6e 29 20 66 6f 72 20 74 68 65 0a 2a 2a  lumn) for the.**
1c5a0 20 20 20 20 20 20 20 20 20 20 72 65 73 75 6c 74            result
1c5b0 20 73 65 74 20 6f 66 20 5b 70 72 65 70 61 72 65   set of [prepare
1c5c0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 61  d statement] S a
1c5d0 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  s a.**          
1c5e0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
1c5f0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e  UTF-16 string in
1c600 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
1c610 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46   order..**.** {F
1c620 31 33 37 32 34 7d 20 54 68 65 20 5b 73 71 6c 69  13724} The [sqli
1c630 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
1c640 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
1c650 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 5d  column_name16()]
1c660 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74  .**          int
1c670 65 72 66 61 63 65 73 20 72 65 74 75 72 6e 20 61  erfaces return a
1c680 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66   NULL pointer if
1c690 20 74 68 65 79 20 61 72 65 20 75 6e 61 62 6c 65   they are unable
1c6a0 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   to.**          
1c6b0 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20  allocate memory 
1c6c0 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  memory to hold t
1c6d0 68 65 72 65 20 6e 6f 72 6d 61 6c 20 72 65 74 75  here normal retu
1c6e0 72 6e 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 0a 2a  rn strings..**.*
1c6f0 2a 20 7b 46 31 33 37 32 35 7d 20 49 66 20 74 68  * {F13725} If th
1c700 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 74 6f  e N parameter to
1c710 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
1c720 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 6f 72 0a 2a  _name(S,N)] or.*
1c730 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
1c740 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
1c750 36 28 53 2c 4e 29 5d 20 69 73 20 6f 75 74 20 6f  6(S,N)] is out o
1c760 66 20 72 61 6e 67 65 2c 20 74 68 65 6e 20 74 68  f range, then th
1c770 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  e.**          in
1c780 74 65 72 66 61 63 65 73 20 72 65 74 75 72 6e 73  terfaces returns
1c790 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
1c7a0 0a 2a 2a 20 0a 2a 2a 20 7b 46 31 33 37 32 36 7d  .** .** {F13726}
1c7b0 20 54 68 65 20 73 74 72 69 6e 67 73 20 72 65 74   The strings ret
1c7c0 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
1c7d0 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 53 2c  3_column_name(S,
1c7e0 4e 29 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20  N)] and.**      
1c7f0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c      [sqlite3_col
1c800 75 6d 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d  umn_name16(S,N)]
1c810 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c   are valid until
1c820 20 74 68 65 20 6e 65 78 74 0a 2a 2a 20 20 20 20   the next.**    
1c830 20 20 20 20 20 20 63 61 6c 6c 20 74 6f 20 65 69        call to ei
1c840 74 68 65 72 20 72 6f 75 74 69 6e 65 20 77 69 74  ther routine wit
1c850 68 20 74 68 65 20 73 61 6d 65 20 53 20 61 6e 64  h the same S and
1c860 20 4e 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a   N parameters.**
1c870 20 20 20 20 20 20 20 20 20 20 6f 72 20 75 6e 74            or unt
1c880 69 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  il [sqlite3_fina
1c890 6c 69 7a 65 28 53 29 5d 20 69 73 20 63 61 6c 6c  lize(S)] is call
1c8a0 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 32  ed..**.** {F1372
1c8b0 37 7d 20 57 68 65 6e 20 61 20 72 65 73 75 6c 74  7} When a result
1c8c0 20 63 6f 6c 75 6d 6e 20 6f 66 20 61 20 5b 53 45   column of a [SE
1c8d0 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20  LECT] statement 
1c8e0 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 20 20 20 20  contains.**     
1c8f0 20 20 20 20 20 61 6e 20 41 53 20 63 6c 61 75 73       an AS claus
1c900 65 2c 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  e, the name of t
1c910 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68  hat column is th
1c920 65 20 69 6e 64 65 6e 74 69 66 69 65 72 0a 2a 2a  e indentifier.**
1c930 20 20 20 20 20 20 20 20 20 20 74 6f 20 74 68 65            to the
1c940 20 72 69 67 68 74 20 6f 66 20 74 68 65 20 41 53   right of the AS
1c950 20 6b 65 79 77 6f 72 64 2e 0a 2a 2f 0a 63 6f 6e   keyword..*/.con
1c960 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
1c970 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c  _column_name(sql
1c980 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
1c990 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  N);.const void *
1c9a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
1c9b0 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
1c9c0 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a  mt*, int N);../*
1c9d0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 6f  .** CAPI3REF: So
1c9e0 75 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e 20  urce Of Data In 
1c9f0 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 20 7b  A Query Result {
1ca00 46 31 33 37 34 30 7d 0a 2a 2a 0a 2a 2a 20 54 68  F13740}.**.** Th
1ca10 65 73 65 20 72 6f 75 74 69 6e 65 73 20 70 72 6f  ese routines pro
1ca20 76 69 64 65 20 61 20 6d 65 61 6e 73 20 74 6f 20  vide a means to 
1ca30 64 65 74 65 72 6d 69 6e 65 20 77 68 61 74 20 63  determine what c
1ca40 6f 6c 75 6d 6e 20 6f 66 20 77 68 61 74 0a 2a 2a  olumn of what.**
1ca50 20 74 61 62 6c 65 20 69 6e 20 77 68 69 63 68 20   table in which 
1ca60 64 61 74 61 62 61 73 65 20 61 20 72 65 73 75 6c  database a resul
1ca70 74 20 6f 66 20 61 20 53 45 4c 45 43 54 20 73 74  t of a SELECT st
1ca80 61 74 65 6d 65 6e 74 20 63 6f 6d 65 73 20 66 72  atement comes fr
1ca90 6f 6d 2e 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20  om..** The name 
1caa0 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
1cab0 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75  or table or colu
1cac0 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 75 72 6e  mn can be return
1cad0 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 20  ed as.** either 
1cae0 61 20 55 54 46 38 20 6f 72 20 55 54 46 31 36 20  a UTF8 or UTF16 
1caf0 73 74 72 69 6e 67 2e 20 20 54 68 65 20 5f 64 61  string.  The _da
1cb00 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73  tabase_ routines
1cb10 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64   return.** the d
1cb20 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68  atabase name, th
1cb30 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e  e _table_ routin
1cb40 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 74 61  es return the ta
1cb50 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a  ble name, and.**
1cb60 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75   the origin_ rou
1cb70 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65  tines return the
1cb80 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a   column name..**
1cb90 20 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74   The returned st
1cba0 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75 6e  ring is valid un
1cbb0 74 69 6c 0a 2a 2a 20 74 68 65 20 5b 70 72 65 70  til.** the [prep
1cbc0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
1cbd0 69 73 20 64 65 73 74 72 6f 79 65 64 20 75 73 69  is destroyed usi
1cbe0 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  ng.** [sqlite3_f
1cbf0 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e  inalize()] or un
1cc00 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69 6e 66  til the same inf
1cc10 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 71 75  ormation is requ
1cc20 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69  ested.** again i
1cc30 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20 65 6e  n a different en
1cc40 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68  coding..**.** Th
1cc50 65 20 6e 61 6d 65 73 20 72 65 74 75 72 6e 65 64  e names returned
1cc60 20 61 72 65 20 74 68 65 20 6f 72 69 67 69 6e 61   are the origina
1cc70 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d  l un-aliased nam
1cc80 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74  es of the.** dat
1cc90 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e  abase, table, an
1cca0 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20  d column..**.** 
1ccb0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
1ccc0 6e 74 20 74 6f 20 74 68 65 20 66 6f 6c 6c 6f 77  nt to the follow
1ccd0 69 6e 67 20 63 61 6c 6c 73 20 69 73 20 61 20 5b  ing calls is a [
1cce0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1ccf0 6e 74 5d 2e 0a 2a 2a 20 54 68 65 73 65 20 66 75  nt]..** These fu
1cd00 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 69  nctions return i
1cd10 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74  nformation about
1cd20 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
1cd30 72 65 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20  returned by .** 
1cd40 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 77  the statement, w
1cd50 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65  here N is the se
1cd60 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72  cond function ar
1cd70 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 49 66  gument..**.** If
1cd80 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
1cd90 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20  returned by the 
1cda0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 6e 20  statement is an 
1cdb0 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 6f 72  expression.** or
1cdc0 20 73 75 62 71 75 65 72 79 20 61 6e 64 20 69 73   subquery and is
1cdd0 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61   not a column va
1cde0 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66  lue, then all of
1cdf0 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
1ce00 0a 2a 2a 20 72 65 74 75 72 6e 20 4e 55 4c 4c 2e  .** return NULL.
1ce10 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 20    These routine 
1ce20 6d 69 67 68 74 20 61 6c 73 6f 20 72 65 74 75 72  might also retur
1ce30 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f  n NULL if a memo
1ce40 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e  ry.** allocation
1ce50 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20   error occurs.  
1ce60 4f 74 68 65 72 77 69 73 65 2c 20 74 68 65 79 20  Otherwise, they 
1ce70 72 65 74 75 72 6e 20 74 68 65 20 0a 2a 2a 20 6e  return the .** n
1ce80 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74 61 63  ame of the attac
1ce90 68 65 64 20 64 61 74 61 62 61 73 65 2c 20 74 61  hed database, ta
1cea0 62 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 74  ble and column t
1ceb0 68 61 74 20 71 75 65 72 79 20 72 65 73 75 6c 74  hat query result
1cec0 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65  .** column was e
1ced0 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a  xtracted from..*
1cee0 2a 0a 2a 2a 20 41 73 20 77 69 74 68 20 61 6c 6c  *.** As with all
1cef0 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 41 50   other SQLite AP
1cf00 49 73 2c 20 74 68 6f 73 65 20 70 6f 73 74 66 69  Is, those postfi
1cf10 78 65 64 20 77 69 74 68 20 22 31 36 22 20 72 65  xed with "16" re
1cf20 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65  turn.** UTF-16 e
1cf30 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 73 2c 20  ncoded strings, 
1cf40 74 68 65 20 6f 74 68 65 72 20 66 75 6e 63 74 69  the other functi
1cf50 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 46 2d 38  ons return UTF-8
1cf60 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68  . {END}.**.** Th
1cf70 65 73 65 20 41 50 49 73 20 61 72 65 20 6f 6e 6c  ese APIs are onl
1cf80 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74  y available if t
1cf90 68 65 20 6c 69 62 72 61 72 79 20 77 61 73 20 63  he library was c
1cfa0 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65  ompiled with the
1cfb0 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 45 4e 41 42   .** SQLITE_ENAB
1cfc0 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41  LE_COLUMN_METADA
1cfd0 54 41 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20  TA preprocessor 
1cfe0 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a  symbol defined..
1cff0 2a 2a 0a 2a 2a 20 7b 55 31 33 37 35 31 7d 0a 2a  **.** {U13751}.*
1d000 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65  * If two or more
1d010 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e   threads call on
1d020 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65  e or more of the
1d030 73 65 20 72 6f 75 74 69 6e 65 73 20 61 67 61 69  se routines agai
1d040 6e 73 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20  nst the same.** 
1d050 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1d060 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74  nt and column at
1d070 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74   the same time t
1d080 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20  hen the results 
1d090 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64  are.** undefined
1d0a0 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
1d0b0 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 34  TS:.**.** {F1374
1d0c0 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
1d0d0 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
1d0e0 6e 61 6d 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72  name(S,N)] inter
1d0f0 66 61 63 65 20 72 65 74 75 72 6e 73 20 65 69 74  face returns eit
1d100 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  her.**          
1d110 74 68 65 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74  the UTF-8 zero-t
1d120 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f  erminated name o
1d130 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  f the database f
1d140 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20 0a 2a  rom which the .*
1d150 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 72  *          Nth r
1d160 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20  esult column of 
1d170 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
1d180 65 6e 74 5d 20 53 20 0a 2a 2a 20 20 20 20 20 20  ent] S .**      
1d190 20 20 20 20 69 73 20 65 78 74 72 61 63 74 65 64      is extracted
1d1a0 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65  , or NULL if the
1d1b0 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
1d1c0 6f 66 20 53 20 69 73 20 61 0a 2a 2a 20 20 20 20  of S is a.**    
1d1d0 20 20 20 20 20 20 67 65 6e 65 72 61 6c 20 65 78        general ex
1d1e0 70 72 65 73 73 69 6f 6e 20 6f 72 20 69 66 20 75  pression or if u
1d1f0 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74  nable to allocat
1d200 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20 20 20  e memory.**     
1d210 20 20 20 20 20 74 6f 20 73 74 6f 72 65 20 74 68       to store th
1d220 65 20 6e 61 6d 65 2e 0a 2a 2a 20 20 20 20 20 20  e name..**      
1d230 20 20 20 20 0a 2a 2a 20 7b 46 31 33 37 34 32 7d      .** {F13742}
1d240 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
1d250 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61  lumn_database_na
1d260 6d 65 31 36 28 53 2c 4e 29 5d 20 69 6e 74 65 72  me16(S,N)] inter
1d270 66 61 63 65 20 72 65 74 75 72 6e 73 20 65 69 74  face returns eit
1d280 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  her.**          
1d290 74 68 65 20 55 54 46 2d 31 36 20 6e 61 74 69 76  the UTF-16 nativ
1d2a0 65 20 62 79 74 65 20 6f 72 64 65 72 0a 2a 2a 20  e byte order.** 
1d2b0 20 20 20 20 20 20 20 20 20 7a 65 72 6f 2d 74 65           zero-te
1d2c0 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66  rminated name of
1d2d0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 72   the database fr
1d2e0 6f 6d 20 77 68 69 63 68 20 74 68 65 20 0a 2a 2a  om which the .**
1d2f0 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 72 65            Nth re
1d300 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 5b  sult column of [
1d310 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1d320 6e 74 5d 20 53 20 0a 2a 2a 20 20 20 20 20 20 20  nt] S .**       
1d330 20 20 20 69 73 20 65 78 74 72 61 63 74 65 64 2c     is extracted,
1d340 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20   or NULL if the 
1d350 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f  the Nth column o
1d360 66 20 53 20 69 73 20 61 0a 2a 2a 20 20 20 20 20  f S is a.**     
1d370 20 20 20 20 20 67 65 6e 65 72 61 6c 20 65 78 70       general exp
1d380 72 65 73 73 69 6f 6e 20 6f 72 20 69 66 20 75 6e  ression or if un
1d390 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  able to allocate
1d3a0 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20 20 20 20   memory.**      
1d3b0 20 20 20 20 74 6f 20 73 74 6f 72 65 20 74 68 65      to store the
1d3c0 20 6e 61 6d 65 2e 0a 2a 2a 20 20 20 20 20 20 20   name..**       
1d3d0 20 20 20 0a 2a 2a 20 7b 46 31 33 37 34 33 7d 20     .** {F13743} 
1d3e0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  The [sqlite3_col
1d3f0 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 53  umn_table_name(S
1d400 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  ,N)] interface r
1d410 65 74 75 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a  eturns either.**
1d420 20 20 20 20 20 20 20 20 20 20 74 68 65 20 55 54            the UT
1d430 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  F-8 zero-termina
1d440 74 65 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  ted name of the 
1d450 74 61 62 6c 65 20 66 72 6f 6d 20 77 68 69 63 68  table from which
1d460 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 20 20 20   the .**        
1d470 20 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c    Nth result col
1d480 75 6d 6e 20 6f 66 20 5b 70 72 65 70 61 72 65 64  umn of [prepared
1d490 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 0a 2a   statement] S .*
1d4a0 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 65 78  *          is ex
1d4b0 74 72 61 63 74 65 64 2c 20 6f 72 20 4e 55 4c 4c  tracted, or NULL
1d4c0 20 69 66 20 74 68 65 20 74 68 65 20 4e 74 68 20   if the the Nth 
1d4d0 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20 61  column of S is a
1d4e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 67 65 6e  .**          gen
1d4f0 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e 20  eral expression 
1d500 6f 72 20 69 66 20 75 6e 61 62 6c 65 20 74 6f 20  or if unable to 
1d510 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 0a  allocate memory.
1d520 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 73  **          to s
1d530 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a  tore the name..*
1d540 2a 20 20 20 20 20 20 20 20 20 20 0a 2a 2a 20 7b  *          .** {
1d550 46 31 33 37 34 34 7d 20 54 68 65 20 5b 73 71 6c  F13744} The [sql
1d560 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c  ite3_column_tabl
1d570 65 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20 69  e_name16(S,N)] i
1d580 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
1d590 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20   either.**      
1d5a0 20 20 20 20 74 68 65 20 55 54 46 2d 31 36 20 6e      the UTF-16 n
1d5b0 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
1d5c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72  .**          zer
1d5d0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d  o-terminated nam
1d5e0 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 66  e of the table f
1d5f0 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20 0a 2a  rom which the .*
1d600 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 72  *          Nth r
1d610 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20  esult column of 
1d620 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
1d630 65 6e 74 5d 20 53 20 0a 2a 2a 20 20 20 20 20 20  ent] S .**      
1d640 20 20 20 20 69 73 20 65 78 74 72 61 63 74 65 64      is extracted
1d650 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65  , or NULL if the
1d660 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
1d670 6f 66 20 53 20 69 73 20 61 0a 2a 2a 20 20 20 20  of S is a.**    
1d680 20 20 20 20 20 20 67 65 6e 65 72 61 6c 20 65 78        general ex
1d690 70 72 65 73 73 69 6f 6e 20 6f 72 20 69 66 20 75  pression or if u
1d6a0 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74  nable to allocat
1d6b0 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20 20 20  e memory.**     
1d6c0 20 20 20 20 20 74 6f 20 73 74 6f 72 65 20 74 68       to store th
1d6d0 65 20 6e 61 6d 65 2e 0a 2a 2a 20 20 20 20 20 20  e name..**      
1d6e0 20 20 20 20 0a 2a 2a 20 7b 46 31 33 37 34 35 7d      .** {F13745}
1d6f0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
1d700 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65  lumn_origin_name
1d710 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  (S,N)] interface
1d720 20 72 65 74 75 72 6e 73 20 65 69 74 68 65 72 0a   returns either.
1d730 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
1d740 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69  UTF-8 zero-termi
1d750 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66 20 74 68  nated name of th
1d760 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 66  e table column f
1d770 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20 0a 2a  rom which the .*
1d780 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 72  *          Nth r
1d790 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20  esult column of 
1d7a0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
1d7b0 65 6e 74 5d 20 53 20 0a 2a 2a 20 20 20 20 20 20  ent] S .**      
1d7c0 20 20 20 20 69 73 20 65 78 74 72 61 63 74 65 64      is extracted
1d7d0 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65  , or NULL if the
1d7e0 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
1d7f0 6f 66 20 53 20 69 73 20 61 0a 2a 2a 20 20 20 20  of S is a.**    
1d800 20 20 20 20 20 20 67 65 6e 65 72 61 6c 20 65 78        general ex
1d810 70 72 65 73 73 69 6f 6e 20 6f 72 20 69 66 20 75  pression or if u
1d820 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74  nable to allocat
1d830 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20 20 20  e memory.**     
1d840 20 20 20 20 20 74 6f 20 73 74 6f 72 65 20 74 68       to store th
1d850 65 20 6e 61 6d 65 2e 0a 2a 2a 20 20 20 20 20 20  e name..**      
1d860 20 20 20 20 0a 2a 2a 20 7b 46 31 33 37 34 36 7d      .** {F13746}
1d870 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
1d880 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65  lumn_origin_name
1d890 31 36 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61  16(S,N)] interfa
1d8a0 63 65 20 72 65 74 75 72 6e 73 20 65 69 74 68 65  ce returns eithe
1d8b0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  r.**          th
1d8c0 65 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20  e UTF-16 native 
1d8d0 62 79 74 65 20 6f 72 64 65 72 0a 2a 2a 20 20 20  byte order.**   
1d8e0 20 20 20 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d         zero-term
1d8f0 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66 20 74  inated name of t
1d900 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20  he table column 
1d910 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20 0a  from which the .
1d920 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20  **          Nth 
1d930 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66  result column of
1d940 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1d950 6d 65 6e 74 5d 20 53 20 0a 2a 2a 20 20 20 20 20  ment] S .**     
1d960 20 20 20 20 20 69 73 20 65 78 74 72 61 63 74 65       is extracte
1d970 64 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68  d, or NULL if th
1d980 65 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  e the Nth column
1d990 20 6f 66 20 53 20 69 73 20 61 0a 2a 2a 20 20 20   of S is a.**   
1d9a0 20 20 20 20 20 20 20 67 65 6e 65 72 61 6c 20 65         general e
1d9b0 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 69 66 20  xpression or if 
1d9c0 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61  unable to alloca
1d9d0 74 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20 20  te memory.**    
1d9e0 20 20 20 20 20 20 74 6f 20 73 74 6f 72 65 20 74        to store t
1d9f0 68 65 20 6e 61 6d 65 2e 0a 2a 2a 20 20 20 20 20  he name..**     
1da00 20 20 20 20 20 0a 2a 2a 20 7b 46 31 33 37 34 38       .** {F13748
1da10 7d 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c  } The return val
1da20 75 65 73 20 66 72 6f 6d 0a 2a 2a 20 20 20 20 20  ues from.**     
1da30 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f       [sqlite3_co
1da40 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61  lumn_database_na
1da50 6d 65 7c 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61  me|column metada
1da60 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a  ta interfaces].*
1da70 2a 20 20 20 20 20 20 20 20 20 20 61 72 65 20 76  *          are v
1da80 61 6c 69 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  alid.**         
1da90 20 66 6f 72 20 74 68 65 20 6c 69 66 65 74 69 6d   for the lifetim
1daa0 65 20 6f 66 20 74 68 65 20 5b 70 72 65 70 61 72  e of the [prepar
1dab0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a  ed statement].**
1dac0 20 20 20 20 20 20 20 20 20 20 6f 72 20 75 6e 74            or unt
1dad0 69 6c 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  il the encoding 
1dae0 69 73 20 63 68 61 6e 67 65 64 20 62 79 20 61 6e  is changed by an
1daf0 6f 74 68 65 72 20 6d 65 74 61 64 61 74 61 0a 2a  other metadata.*
1db00 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 72  *          inter
1db10 66 61 63 65 20 63 61 6c 6c 20 66 6f 72 20 74 68  face call for th
1db20 65 20 73 61 6d 65 20 70 72 65 70 61 72 65 64 20  e same prepared 
1db30 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f  statement and co
1db40 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49  lumn..**.** LIMI
1db50 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b  TATIONS:.**.** {
1db60 55 31 33 37 35 31 7d 20 49 66 20 74 77 6f 20 6f  U13751} If two o
1db70 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63  r more threads c
1db80 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a  all one or more.
1db90 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
1dba0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61  ite3_column_data
1dbb0 62 61 73 65 5f 6e 61 6d 65 7c 63 6f 6c 75 6d 6e  base_name|column
1dbc0 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72 66   metadata interf
1dbd0 61 63 65 73 5d 0a 2a 2a 20 20 20 20 20 20 20 20  aces].**        
1dbe0 20 20 74 68 65 20 73 61 6d 65 20 5b 70 72 65 70    the same [prep
1dbf0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
1dc00 61 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  and result colum
1dc10 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 74  n.**          at
1dc20 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74   the same time t
1dc30 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20  hen the results 
1dc40 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
1dc50 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
1dc60 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74  lite3_column_dat
1dc70 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74  abase_name(sqlit
1dc80 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
1dc90 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
1dca0 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61  e3_column_databa
1dcb0 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  se_name16(sqlite
1dcc0 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
1dcd0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
1dce0 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e  3_column_table_n
1dcf0 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
1dd00 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f  *,int);.const vo
1dd10 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
1dd20 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28  mn_table_name16(
1dd30 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
1dd40 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  t);.const char *
1dd50 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f  sqlite3_column_o
1dd60 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74  rigin_name(sqlit
1dd70 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
1dd80 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
1dd90 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e  e3_column_origin
1dda0 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
1ddb0 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a  stmt*,int);../*.
1ddc0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 63  ** CAPI3REF: Dec
1ddd0 6c 61 72 65 64 20 44 61 74 61 74 79 70 65 20 4f  lared Datatype O
1dde0 66 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74  f A Query Result
1ddf0 20 7b 46 31 33 37 36 30 7d 0a 2a 2a 0a 2a 2a 20   {F13760}.**.** 
1de00 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
1de10 74 65 72 20 69 73 20 61 20 5b 70 72 65 70 61 72  ter is a [prepar
1de20 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 0a  ed statement]. .
1de30 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61 74 65  ** If this state
1de40 6d 65 6e 74 20 69 73 20 61 20 53 45 4c 45 43 54  ment is a SELECT
1de50 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74   statement and t
1de60 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66  he Nth column of
1de70 20 74 68 65 20 0a 2a 2a 20 72 65 74 75 72 6e 65   the .** returne
1de80 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  d result set of 
1de90 74 68 61 74 20 53 45 4c 45 43 54 20 69 73 20 61  that SELECT is a
1dea0 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e   table column (n
1deb0 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73  ot an.** express
1dec0 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 29  ion or subquery)
1ded0 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61 72   then the declar
1dee0 65 64 20 74 79 70 65 20 6f 66 20 74 68 65 20 74  ed type of the t
1def0 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69  able.** column i
1df00 73 20 72 65 74 75 72 6e 65 64 2e 20 20 49 66 20  s returned.  If 
1df10 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f  the Nth column o
1df20 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
1df30 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73   is an.** expres
1df40 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79  sion or subquery
1df50 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f  , then a NULL po
1df60 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65  inter is returne
1df70 64 2e 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 6e  d..** The return
1df80 65 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c 77  ed string is alw
1df90 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  ays UTF-8 encode
1dfa0 64 2e 20 20 7b 45 4e 44 7d 20 0a 2a 2a 20 46 6f  d.  {END} .** Fo
1dfb0 72 20 65 78 61 6d 70 6c 65 2c 20 69 6e 20 74 68  r example, in th
1dfc0 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d  e database schem
1dfd0 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20  a:.**.** CREATE 
1dfe0 54 41 42 4c 45 20 74 31 28 63 31 20 56 41 52 49  TABLE t1(c1 VARI
1dff0 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 41 6e 64 20  ANT);.**.** And 
1e000 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74  the following st
1e010 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 64  atement compiled
1e020 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63  :.**.** SELECT c
1e030 31 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74  1 + 1, c1 FROM t
1e040 31 3b 0a 2a 2a 0a 2a 2a 20 54 68 65 6e 20 74 68  1;.**.** Then th
1e050 69 73 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64  is routine would
1e060 20 72 65 74 75 72 6e 20 74 68 65 20 73 74 72 69   return the stri
1e070 6e 67 20 22 56 41 52 49 41 4e 54 22 20 66 6f 72  ng "VARIANT" for
1e080 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 72   the second.** r
1e090 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d  esult column (i=
1e0a0 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20  =1), and a NULL 
1e0b0 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65 20  pointer for the 
1e0c0 66 69 72 73 74 20 72 65 73 75 6c 74 20 63 6f 6c  first result col
1e0d0 75 6d 6e 0a 2a 2a 20 28 69 3d 3d 30 29 2e 0a 2a  umn.** (i==0)..*
1e0e0 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73  *.** SQLite uses
1e0f0 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d   dynamic run-tim
1e100 65 20 74 79 70 69 6e 67 2e 20 20 53 6f 20 6a 75  e typing.  So ju
1e110 73 74 20 62 65 63 61 75 73 65 20 61 20 63 6f 6c  st because a col
1e120 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72  umn.** is declar
1e130 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20  ed to contain a 
1e140 70 61 72 74 69 63 75 6c 61 72 20 74 79 70 65 20  particular type 
1e150 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68  does not mean th
1e160 61 74 20 74 68 65 0a 2a 2a 20 64 61 74 61 20 73  at the.** data s
1e170 74 6f 72 65 64 20 69 6e 20 74 68 61 74 20 63 6f  tored in that co
1e180 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68 65 20 64  lumn is of the d
1e190 65 63 6c 61 72 65 64 20 74 79 70 65 2e 20 20 53  eclared type.  S
1e1a0 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f  QLite is.** stro
1e1b0 6e 67 6c 79 20 74 79 70 65 64 2c 20 62 75 74 20  ngly typed, but 
1e1c0 74 68 65 20 74 79 70 69 6e 67 20 69 73 20 64 79  the typing is dy
1e1d0 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61 74 69 63  namic not static
1e1e0 2e 20 20 54 79 70 65 0a 2a 2a 20 69 73 20 61 73  .  Type.** is as
1e1f0 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 69 6e  sociated with in
1e200 64 69 76 69 64 75 61 6c 20 76 61 6c 75 65 73 2c  dividual values,
1e210 20 6e 6f 74 20 77 69 74 68 20 74 68 65 20 63 6f   not with the co
1e220 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64  ntainers.** used
1e230 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20 76   to hold those v
1e240 61 6c 75 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  alues..**.** INV
1e250 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
1e260 46 31 33 37 36 31 7d 20 20 41 20 73 75 63 63 65  F13761}  A succe
1e270 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73  ssful call to [s
1e280 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65  qlite3_column_de
1e290 63 6c 74 79 70 65 28 53 2c 4e 29 5d 0a 2a 2a 20  cltype(S,N)].** 
1e2a0 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e            return
1e2b0 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  s a zero-termina
1e2c0 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67  ted UTF-8 string
1e2d0 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 0a   containing the.
1e2e0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 68 65  **           the
1e2f0 20 64 65 63 6c 61 72 65 64 20 64 61 74 61 74 79   declared dataty
1e300 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20  pe of the table 
1e310 63 6f 6c 75 6d 6e 20 74 68 61 74 20 61 70 70 65  column that appe
1e320 61 72 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ars.**          
1e330 20 61 73 20 74 68 65 20 4e 74 68 20 63 6f 6c 75   as the Nth colu
1e340 6d 6e 20 28 6e 75 6d 62 65 72 65 64 20 66 72 6f  mn (numbered fro
1e350 6d 20 30 29 20 6f 66 20 74 68 65 20 72 65 73 75  m 0) of the resu
1e360 6c 74 20 73 65 74 20 74 6f 20 74 68 65 0a 2a 2a  lt set to the.**
1e370 20 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70             [prep
1e380 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
1e390 53 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 36 32  S..**.** {F13762
1e3a0 7d 20 20 41 20 73 75 63 63 65 73 73 66 75 6c 20  }  A successful 
1e3b0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
1e3c0 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65  _column_decltype
1e3d0 31 36 28 53 2c 4e 29 5d 0a 2a 2a 20 20 20 20 20  16(S,N)].**     
1e3e0 20 20 20 20 20 20 72 65 74 75 72 6e 73 20 61 20        returns a 
1e3f0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
1e400 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79  UTF-16 native by
1e410 74 65 20 6f 72 64 65 72 20 73 74 72 69 6e 67 0a  te order string.
1e420 2a 2a 20 20 20 20 20 20 20 20 20 20 20 63 6f 6e  **           con
1e430 74 61 69 6e 69 6e 67 20 74 68 65 20 64 65 63 6c  taining the decl
1e440 61 72 65 64 20 64 61 74 61 74 79 70 65 20 6f 66  ared datatype of
1e450 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d   the table colum
1e460 6e 20 74 68 61 74 20 61 70 70 65 61 72 73 0a 2a  n that appears.*
1e470 2a 20 20 20 20 20 20 20 20 20 20 20 61 73 20 74  *           as t
1e480 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 28 6e  he Nth column (n
1e490 75 6d 62 65 72 65 64 20 66 72 6f 6d 20 30 29 20  umbered from 0) 
1e4a0 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
1e4b0 74 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20  t to the.**     
1e4c0 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20        [prepared 
1e4d0 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2a  statement] S..**
1e4e0 0a 2a 2a 20 7b 46 31 33 37 36 33 7d 20 20 49 66  .** {F13763}  If
1e4f0 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20   N is less than 
1e500 30 20 6f 72 20 4e 20 69 73 20 67 72 65 61 74 65  0 or N is greate
1e510 72 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20  r than or equal 
1e520 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  to.**           
1e530 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  the number of co
1e540 6c 75 6d 6e 73 20 69 6e 20 5b 70 72 65 70 61 72  lumns in [prepar
1e550 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a  ed statement] S.
1e560 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6f 72 20  **           or 
1e570 69 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  if the Nth colum
1e580 6e 20 6f 66 20 53 20 69 73 20 61 6e 20 65 78 70  n of S is an exp
1e590 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75  ression or subqu
1e5a0 65 72 79 20 72 61 74 68 65 72 0a 2a 2a 20 20 20  ery rather.**   
1e5b0 20 20 20 20 20 20 20 20 74 68 61 6e 20 61 20 74          than a t
1e5c0 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 6f 72 20 69  able column or i
1e5d0 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  f a memory alloc
1e5e0 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 0a 2a 2a  ation failure.**
1e5f0 20 20 20 20 20 20 20 20 20 20 20 6f 63 63 75 72             occur
1e600 73 20 64 75 72 69 6e 67 20 65 6e 63 6f 64 69 6e  s during encodin
1e610 67 20 63 6f 6e 76 65 72 73 69 6f 6e 73 2c 20 74  g conversions, t
1e620 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  hen.**          
1e630 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
1e640 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79  e3_column_declty
1e650 70 65 28 53 2c 4e 29 5d 20 6f 72 0a 2a 2a 20 20  pe(S,N)] or.**  
1e660 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
1e670 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70  3_column_decltyp
1e680 65 31 36 28 53 2c 4e 29 5d 20 72 65 74 75 72 6e  e16(S,N)] return
1e690 20 4e 55 4c 4c 2e 0a 2a 2f 0a 63 6f 6e 73 74 20   NULL..*/.const 
1e6a0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
1e6b0 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71  lumn_decltype(sq
1e6c0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
1e6d0 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
1e6e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63  lite3_column_dec
1e6f0 6c 74 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f  ltype16(sqlite3_
1e700 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 20  stmt*,int);../* 
1e710 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 45  .** CAPI3REF:  E
1e720 76 61 6c 75 61 74 65 20 41 6e 20 53 51 4c 20 53  valuate An SQL S
1e730 74 61 74 65 6d 65 6e 74 20 7b 46 31 33 32 30 30  tatement {F13200
1e740 7d 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 6e  }.**.** After an
1e750 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1e760 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70  ment] has been p
1e770 72 65 70 61 72 65 64 20 77 69 74 68 20 61 20 63  repared with a c
1e780 61 6c 6c 0a 2a 2a 20 74 6f 20 65 69 74 68 65 72  all.** to either
1e790 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1e7a0 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69  e_v2()] or [sqli
1e7b0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
1e7c0 28 29 5d 20 6f 72 20 74 6f 20 6f 6e 65 20 6f 66  ()] or to one of
1e7d0 0a 2a 2a 20 74 68 65 20 6c 65 67 61 63 79 20 69  .** the legacy i
1e7e0 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74  nterfaces [sqlit
1e7f0 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72  e3_prepare()] or
1e800 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1e810 65 31 36 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20  e16()],.** then 
1e820 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d 75  this function mu
1e830 73 74 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65  st be called one
1e840 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74   or more times t
1e850 6f 20 65 76 61 6c 75 61 74 65 20 74 68 65 20 0a  o evaluate the .
1e860 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a  ** statement..**
1e870 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20  .** The details 
1e880 6f 66 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  of the behavior 
1e890 6f 66 20 74 68 69 73 20 73 71 6c 69 74 65 33 5f  of this sqlite3_
1e8a0 73 74 65 70 28 29 20 69 6e 74 65 72 66 61 63 65  step() interface
1e8b0 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68   depend.** on wh
1e8c0 65 74 68 65 72 20 74 68 65 20 73 74 61 74 65 6d  ether the statem
1e8d0 65 6e 74 20 77 61 73 20 70 72 65 70 61 72 65 64  ent was prepared
1e8e0 20 75 73 69 6e 67 20 74 68 65 20 6e 65 77 65 72   using the newer
1e8f0 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 0a   "v2" interface.
1e900 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
1e910 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73  are_v2()] and [s
1e920 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
1e930 5f 76 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c  _v2()] or the ol
1e940 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e  der legacy.** in
1e950 74 65 72 66 61 63 65 20 5b 73 71 6c 69 74 65 33  terface [sqlite3
1e960 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20  _prepare()] and 
1e970 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1e980 31 36 28 29 5d 2e 20 20 54 68 65 20 75 73 65 20  16()].  The use 
1e990 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76  of the.** new "v
1e9a0 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  2" interface is 
1e9b0 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20  recommended for 
1e9c0 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  new applications
1e9d0 20 62 75 74 20 74 68 65 20 6c 65 67 61 63 79 0a   but the legacy.
1e9e0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c  ** interface wil
1e9f0 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65  l continue to be
1ea00 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a   supported..**.*
1ea10 2a 20 49 6e 20 74 68 65 20 6c 61 67 61 63 79 20  * In the lagacy 
1ea20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 72  interface, the r
1ea30 65 74 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c  eturn value will
1ea40 20 62 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49   be either [SQLI
1ea50 54 45 5f 42 55 53 59 5d 2c 20 0a 2a 2a 20 5b 53  TE_BUSY], .** [S
1ea60 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51  QLITE_DONE], [SQ
1ea70 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49  LITE_ROW], [SQLI
1ea80 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53  TE_ERROR], or [S
1ea90 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a  QLITE_MISUSE]..*
1eaa0 2a 20 57 69 74 68 20 74 68 65 20 22 76 32 22 20  * With the "v2" 
1eab0 69 6e 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f  interface, any o
1eac0 66 20 74 68 65 20 6f 74 68 65 72 20 5b 53 51 4c  f the other [SQL
1ead0 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20  ITE_OK | result 
1eae0 63 6f 64 65 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c  code].** or [SQL
1eaf0 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c  ITE_IOERR_READ |
1eb00 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
1eb10 20 63 6f 64 65 5d 20 6d 69 67 68 74 20 62 65 20   code] might be 
1eb20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 77  returned as.** w
1eb30 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49  ell..**.** [SQLI
1eb40 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74  TE_BUSY] means t
1eb50 68 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65  hat the database
1eb60 20 65 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62   engine was unab
1eb70 6c 65 20 74 6f 20 61 63 71 75 69 72 65 20 74 68  le to acquire th
1eb80 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f  e.** database lo
1eb90 63 6b 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20  cks it needs to 
1eba0 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20 49 66 20  do its job.  If 
1ebb0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
1ebc0 20 61 20 43 4f 4d 4d 49 54 0a 2a 2a 20 6f 72 20   a COMMIT.** or 
1ebd0 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f  occurs outside o
1ebe0 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72  f an explicit tr
1ebf0 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20  ansaction, then 
1ec00 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20 74 68  you can retry th
1ec10 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20  e.** statement. 
1ec20 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   If the statemen
1ec30 74 20 69 73 20 6e 6f 74 20 61 20 43 4f 4d 4d 49  t is not a COMMI
1ec40 54 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74  T and occurs wit
1ec50 68 69 6e 20 61 0a 2a 2a 20 65 78 70 6c 69 63 69  hin a.** explici
1ec60 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68  t transaction th
1ec70 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f  en you should ro
1ec80 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73  llback the trans
1ec90 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a  action before.**
1eca0 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a   continuing..**.
1ecb0 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  ** [SQLITE_DONE]
1ecc0 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
1ecd0 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69  statement has fi
1ece0 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67  nished executing
1ecf0 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79  .** successfully
1ed00 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  .  sqlite3_step(
1ed10 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  ) should not be 
1ed20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20  called again on 
1ed30 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20  this virtual.** 
1ed40 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20  machine without 
1ed50 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73  first calling [s
1ed60 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
1ed70 74 6f 20 72 65 73 65 74 20 74 68 65 20 76 69 72  to reset the vir
1ed80 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20  tual.** machine 
1ed90 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74  back to its init
1eda0 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a  ial state..**.**
1edb0 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74   If the SQL stat
1edc0 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63  ement being exec
1edd0 75 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79  uted returns any
1ede0 20 64 61 74 61 2c 20 74 68 65 6e 20 0a 2a 2a 20   data, then .** 
1edf0 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 69 73 20  [SQLITE_ROW] is 
1ee00 72 65 74 75 72 6e 65 64 20 65 61 63 68 20 74 69  returned each ti
1ee10 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20  me a new row of 
1ee20 64 61 74 61 20 69 73 20 72 65 61 64 79 0a 2a 2a  data is ready.**
1ee30 20 66 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20   for processing 
1ee40 62 79 20 74 68 65 20 63 61 6c 6c 65 72 2e 20 54  by the caller. T
1ee50 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65  he values may be
1ee60 20 61 63 63 65 73 73 65 64 20 75 73 69 6e 67 0a   accessed using.
1ee70 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
1ee80 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 63 6f 6c  column_int | col
1ee90 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74  umn access funct
1eea0 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65  ions]..** sqlite
1eeb0 33 5f 73 74 65 70 28 29 20 69 73 20 63 61 6c 6c  3_step() is call
1eec0 65 64 20 61 67 61 69 6e 20 74 6f 20 72 65 74 72  ed again to retr
1eed0 69 65 76 65 20 74 68 65 20 6e 65 78 74 20 72 6f  ieve the next ro
1eee0 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 20 0a 2a  w of data..** .*
1eef0 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  * [SQLITE_ERROR]
1ef00 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20 72 75   means that a ru
1ef10 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 28 73 75  n-time error (su
1ef20 63 68 20 61 73 20 61 20 63 6f 6e 73 74 72 61 69  ch as a constrai
1ef30 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29  nt.** violation)
1ef40 20 68 61 73 20 6f 63 63 75 72 72 65 64 2e 20 20   has occurred.  
1ef50 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73  sqlite3_step() s
1ef60 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c  hould not be cal
1ef70 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20  led again on.** 
1ef80 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66  the VM. More inf
1ef90 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65 20  ormation may be 
1efa0 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67  found by calling
1efb0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
1efc0 28 29 5d 2e 0a 2a 2a 20 57 69 74 68 20 74 68 65  ()]..** With the
1efd0 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
1efe0 65 2c 20 61 20 6d 6f 72 65 20 73 70 65 63 69 66  e, a more specif
1eff0 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 28 65  ic error code (e
1f000 78 61 6d 70 6c 65 3a 0a 2a 2a 20 5b 53 51 4c 49  xample:.** [SQLI
1f010 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b  TE_INTERRUPT], [
1f020 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20  SQLITE_SCHEMA], 
1f030 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d  [SQLITE_CORRUPT]
1f040 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a  , and so forth).
1f050 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e  ** can be obtain
1f060 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73  ed by calling [s
1f070 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
1f080 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  on the.** [prepa
1f090 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20  red statement]. 
1f0a0 20 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74   In the "v2" int
1f0b0 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d  erface,.** the m
1f0c0 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72  ore specific err
1f0d0 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 72  or code is retur
1f0e0 6e 65 64 20 64 69 72 65 63 74 6c 79 20 62 79 20  ned directly by 
1f0f0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a  sqlite3_step()..
1f100 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49  **.** [SQLITE_MI
1f110 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74  SUSE] means that
1f120 20 74 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e   the this routin
1f130 65 20 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61  e was called ina
1f140 70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a  ppropriately..**
1f150 20 50 65 72 68 61 70 73 20 69 74 20 77 61 73 20   Perhaps it was 
1f160 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65  called on a [pre
1f170 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
1f180 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72   that has.** alr
1f190 65 61 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74  eady been [sqlit
1f1a0 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69  e3_finalize | fi
1f1b0 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f  nalized] or on o
1f1c0 6e 65 20 74 68 61 74 20 68 61 64 20 0a 2a 2a 20  ne that had .** 
1f1d0 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72  previously retur
1f1e0 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  ned [SQLITE_ERRO
1f1f0 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f  R] or [SQLITE_DO
1f200 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c  NE].  Or it coul
1f210 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 61 73 65  d.** be the case
1f220 20 74 68 61 74 20 74 68 65 20 73 61 6d 65 20 64   that the same d
1f230 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1f240 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 73 65 64  on is being used
1f250 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f   by two or.** mo
1f260 72 65 20 74 68 72 65 61 64 73 20 61 74 20 74 68  re threads at th
1f270 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e  e same moment in
1f280 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e   time..**.** <b>
1f290 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 65 20  Goofy Interface 
1f2a0 41 6c 65 72 74 3a 3c 2f 62 3e 0a 2a 2a 20 49 6e  Alert:</b>.** In
1f2b0 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65   the legacy inte
1f2c0 72 66 61 63 65 2c 20 0a 2a 2a 20 74 68 65 20 73  rface, .** the s
1f2d0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 41 50  qlite3_step() AP
1f2e0 49 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73  I always returns
1f2f0 20 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72   a generic error
1f300 20 63 6f 64 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54   code,.** [SQLIT
1f310 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77  E_ERROR], follow
1f320 69 6e 67 20 61 6e 79 20 65 72 72 6f 72 20 6f 74  ing any error ot
1f330 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
1f340 5f 42 55 53 59 5d 0a 2a 2a 20 61 6e 64 20 5b 53  _BUSY].** and [S
1f350 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20  QLITE_MISUSE].  
1f360 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 20 5b 73  You must call [s
1f370 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
1f380 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  or.** [sqlite3_f
1f390 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72  inalize()] in or
1f3a0 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20  der to find one 
1f3b0 6f 66 20 74 68 65 20 73 70 65 63 69 66 69 63 0a  of the specific.
1f3c0 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d  ** [error codes]
1f3d0 20 74 68 61 74 20 62 65 74 74 65 72 20 64 65 73   that better des
1f3e0 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72  cribes the error
1f3f0 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68  ..** We admit th
1f400 61 74 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f  at this is a goo
1f410 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20  fy design.  The 
1f420 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e  problem has been
1f430 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74   fixed.** with t
1f440 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
1f450 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70 61  e.  If you prepa
1f460 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53  re all of your S
1f470 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
1f480 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73   using either [s
1f490 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1f4a0 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  2()] or [sqlite3
1f4b0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
1f4c0 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74   instead.** of t
1f4d0 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74  he legacy [sqlit
1f4e0 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e  e3_prepare()] an
1f4f0 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
1f500 72 65 31 36 28 29 5d 2c 20 74 68 65 6e 20 74 68  re16()], then th
1f510 65 20 0a 2a 2a 20 6d 6f 72 65 20 73 70 65 63 69  e .** more speci
1f520 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73  fic [error codes
1f530 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64 20 64  ] are returned d
1f540 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71  irectly.** by sq
1f550 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 54  lite3_step().  T
1f560 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 22 76  he use of the "v
1f570 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  2" interface is 
1f580 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a  recommended..**.
1f590 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
1f5a0 2a 0a 2a 2a 20 7b 46 31 33 32 30 32 7d 20 20 49  *.** {F13202}  I
1f5b0 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  f [prepared stat
1f5c0 65 6d 65 6e 74 5d 20 53 20 69 73 20 72 65 61 64  ement] S is read
1f5d0 79 20 74 6f 20 62 65 0a 2a 2a 20 20 20 20 20 20  y to be.**      
1f5e0 20 20 20 20 20 72 75 6e 2c 20 74 68 65 6e 20 5b       run, then [
1f5f0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
1f600 20 61 64 76 61 6e 63 65 73 20 74 68 61 74 20 70   advances that p
1f610 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1f620 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 75  t.**           u
1f630 6e 74 69 6c 20 74 6f 20 63 6f 6d 70 6c 65 74 69  ntil to completi
1f640 6f 6e 20 6f 72 20 75 6e 74 69 6c 20 69 74 20 69  on or until it i
1f650 73 20 72 65 61 64 79 20 74 6f 20 72 65 74 75 72  s ready to retur
1f660 6e 20 61 6e 6f 74 68 65 72 0a 2a 2a 20 20 20 20  n another.**    
1f670 20 20 20 20 20 20 20 72 6f 77 20 6f 66 20 74 68         row of th
1f680 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 72 20  e result set or 
1f690 61 6e 20 69 6e 74 65 72 72 75 70 74 20 6f 72 20  an interrupt or 
1f6a0 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 6f  run-time error o
1f6b0 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  ccurs..**.** {F1
1f6c0 35 33 30 34 7d 20 20 57 68 65 6e 20 61 20 63 61  5304}  When a ca
1f6d0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
1f6e0 74 65 70 28 53 29 5d 20 63 61 75 73 65 73 20 74  tep(S)] causes t
1f6f0 68 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  he .**          
1f700 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1f710 6d 65 6e 74 5d 20 53 20 74 6f 20 72 75 6e 20 74  ment] S to run t
1f720 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2c 0a 2a 2a  o completion,.**
1f730 20 20 20 20 20 20 20 20 20 20 20 74 68 65 20 66             the f
1f740 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
1f750 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 0a 2a  [SQLITE_DONE]..*
1f760 2a 0a 2a 2a 20 7b 46 31 35 33 30 36 7d 20 20 57  *.** {F15306}  W
1f770 68 65 6e 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73  hen a call to [s
1f780 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
1f790 73 74 6f 70 73 20 62 65 63 61 75 73 65 20 69 74  stops because it
1f7a0 20 69 73 20 72 65 61 64 79 0a 2a 2a 20 20 20 20   is ready.**    
1f7b0 20 20 20 20 20 20 20 74 6f 20 72 65 74 75 72 6e         to return
1f7c0 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 6f 66 20   another row of 
1f7d0 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 2c 20  the result set, 
1f7e0 69 74 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20  it returns.**   
1f7f0 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f          [SQLITE_
1f800 52 4f 57 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35  ROW]..**.** {F15
1f810 33 30 38 7d 20 20 49 66 20 61 20 63 61 6c 6c 20  308}  If a call 
1f820 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
1f830 28 53 29 5d 20 65 6e 63 6f 75 6e 74 65 72 73 20  (S)] encounters 
1f840 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  an.**           
1f850 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75  [sqlite3_interru
1f860 70 74 7c 69 6e 74 65 72 72 75 70 74 5d 20 6f 72  pt|interrupt] or
1f870 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f   a run-time erro
1f880 72 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  r,.**           
1f890 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70  it returns an ap
1f8a0 70 72 6f 70 72 61 69 74 65 20 65 72 72 6f 72 20  propraite error 
1f8b0 63 6f 64 65 20 74 68 61 74 20 69 73 20 6e 6f 74  code that is not
1f8c0 20 6f 6e 65 20 6f 66 0a 2a 2a 20 20 20 20 20 20   one of.**      
1f8d0 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d       [SQLITE_OK]
1f8e0 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20  , [SQLITE_ROW], 
1f8f0 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  or [SQLITE_DONE]
1f900 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 33 31 30 7d  ..**.** {F15310}
1f910 20 20 49 66 20 61 6e 20 5b 73 71 6c 69 74 65 33    If an [sqlite3
1f920 5f 69 6e 74 65 72 72 75 70 74 7c 69 6e 74 65 72  _interrupt|inter
1f930 72 75 70 74 5d 20 6f 72 20 72 75 6e 2d 74 69 6d  rupt] or run-tim
1f940 65 20 65 72 72 6f 72 0a 2a 2a 20 20 20 20 20 20  e error.**      
1f950 20 20 20 20 20 6f 63 63 75 72 73 20 64 75 72 69       occurs duri
1f960 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71  ng a call to [sq
1f970 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 0a 2a  lite3_step(S)].*
1f980 2a 20 20 20 20 20 20 20 20 20 20 20 66 6f 72 20  *           for 
1f990 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
1f9a0 65 6d 65 6e 74 5d 20 53 20 63 72 65 61 74 65 64  ement] S created
1f9b0 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20   using.**       
1f9c0 20 20 20 20 6c 65 67 61 63 79 20 69 6e 74 65 72      legacy inter
1f9d0 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70  faces [sqlite3_p
1f9e0 72 65 70 61 72 65 28 29 5d 20 6f 72 0a 2a 2a 20  repare()] or.** 
1f9f0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
1fa00 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20  e3_prepare16()] 
1fa10 74 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f  then the functio
1fa20 6e 20 72 65 74 75 72 6e 73 20 65 69 74 68 65 72  n returns either
1fa30 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 53  .**           [S
1fa40 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 5b 53  QLITE_ERROR], [S
1fa50 51 4c 49 54 45 5f 42 55 53 59 5d 2c 20 6f 72 20  QLITE_BUSY], or 
1fa60 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e  [SQLITE_MISUSE].
1fa70 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1fa80 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d  step(sqlite3_stm
1fa90 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
1faa0 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20  3REF: Number of 
1fab0 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 73  columns in a res
1fac0 75 6c 74 20 73 65 74 20 7b 46 31 33 37 37 30 7d  ult set {F13770}
1fad0 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 74 68  .**.** Return th
1fae0 65 20 6e 75 6d 62 65 72 20 6f 66 20 76 61 6c 75  e number of valu
1faf0 65 73 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e  es in the curren
1fb00 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73  t row of the res
1fb10 75 6c 74 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 49  ult set..**.** I
1fb20 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
1fb30 20 7b 46 31 33 37 37 31 7d 20 20 41 66 74 65 72   {F13771}  After
1fb40 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69   a call to [sqli
1fb50 74 65 33 5f 73 74 65 70 28 53 29 5d 20 74 68 61  te3_step(S)] tha
1fb60 74 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20  t returns.**    
1fb70 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 52         [SQLITE_R
1fb80 4f 57 5d 2c 20 74 68 65 20 5b 73 71 6c 69 74 65  OW], the [sqlite
1fb90 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 53 29 5d  3_data_count(S)]
1fba0 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 20 20 20 20   routine.**     
1fbb0 20 20 20 20 20 20 77 69 6c 6c 20 72 65 74 75 72        will retur
1fbc0 6e 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65  n the same value
1fbd0 20 61 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   as the.**      
1fbe0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f       [sqlite3_co
1fbf0 6c 75 6d 6e 5f 63 6f 75 6e 74 28 53 29 5d 20 66  lumn_count(S)] f
1fc00 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b  unction..**.** {
1fc10 46 31 33 37 37 32 7d 20 20 41 66 74 65 72 20 5b  F13772}  After [
1fc20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
1fc30 20 68 61 73 20 72 65 74 75 72 6e 65 64 20 61 6e   has returned an
1fc40 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68  y value other th
1fc50 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  an.**           
1fc60 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20  [SQLITE_ROW] or 
1fc70 62 65 66 6f 72 65 20 5b 73 71 6c 69 74 65 33 5f  before [sqlite3_
1fc80 73 74 65 70 28 53 29 5d 20 68 61 73 20 62 65 65  step(S)] has bee
1fc90 6e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  n .**           
1fca0 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 5b 70  called on the [p
1fcb0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1fcc0 74 5d 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20  t] for.**       
1fcd0 20 20 20 20 74 68 65 20 66 69 72 73 74 20 74 69      the first ti
1fce0 6d 65 20 73 69 6e 63 65 20 69 74 20 77 61 73 20  me since it was 
1fcf0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1fd00 7c 70 72 65 70 61 72 65 64 5d 0a 2a 2a 20 20 20  |prepared].**   
1fd10 20 20 20 20 20 20 20 20 6f 72 20 5b 73 71 6c 69          or [sqli
1fd20 74 65 33 5f 72 65 73 65 74 7c 72 65 73 65 74 5d  te3_reset|reset]
1fd30 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64  , the [sqlite3_d
1fd40 61 74 61 5f 63 6f 75 6e 74 28 53 29 5d 0a 2a 2a  ata_count(S)].**
1fd50 20 20 20 20 20 20 20 20 20 20 20 72 6f 75 74 69             routi
1fd60 6e 65 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e  ne returns zero.
1fd70 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1fd80 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74  data_count(sqlit
1fd90 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
1fda0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1fdb0 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61  : Fundamental Da
1fdc0 74 61 74 79 70 65 73 20 7b 46 31 30 32 36 35 7d  tatypes {F10265}
1fdd0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51  .** KEYWORDS: SQ
1fde0 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20  LITE_TEXT.**.** 
1fdf0 7b 46 31 30 32 36 36 7d 45 76 65 72 79 20 76 61  {F10266}Every va
1fe00 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20 68 61  lue in SQLite ha
1fe10 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 75  s one of five fu
1fe20 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 79  ndamental dataty
1fe30 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  pes:.**.** <ul>.
1fe40 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73  ** <li> 64-bit s
1fe50 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a  igned integer.**
1fe60 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 45   <li> 64-bit IEE
1fe70 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  E floating point
1fe80 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20   number.** <li> 
1fe90 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42  string.** <li> B
1fea0 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c  LOB.** <li> NULL
1feb0 0a 2a 2a 20 3c 2f 75 6c 3e 20 7b 45 4e 44 7d 0a  .** </ul> {END}.
1fec0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
1fed0 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65 73 20  tants are codes 
1fee0 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68 6f 73  for each of thos
1fef0 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e  e types..**.** N
1ff00 6f 74 65 20 74 68 61 74 20 74 68 65 20 53 51 4c  ote that the SQL
1ff10 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e  ITE_TEXT constan
1ff20 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65 64 20  t was also used 
1ff30 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  in SQLite versio
1ff40 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d  n 2.** for a com
1ff50 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72 65 6e  pletely differen
1ff60 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74  t meaning.  Soft
1ff70 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 20  ware that links 
1ff80 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20  against both.** 
1ff90 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32  SQLite version 2
1ffa0 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73   and SQLite vers
1ffb0 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 65  ion 3 should use
1ffc0 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20 6e 6f   SQLITE3_TEXT no
1ffd0 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 54  t.** SQLITE_TEXT
1ffe0 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
1fff0 49 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a 23  ITE_INTEGER  1.#
20000 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c  define SQLITE_FL
20010 4f 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e 65  OAT    2.#define
20020 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20   SQLITE_BLOB    
20030 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   4.#define SQLIT
20040 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 66  E_NULL     5.#if
20050 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a  def SQLITE_TEXT.
20060 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 54  # undef SQLITE_T
20070 45 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 69  EXT.#else.# defi
20080 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 20  ne SQLITE_TEXT  
20090 20 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 66     3.#endif.#def
200a0 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54  ine SQLITE3_TEXT
200b0 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41       3../*.** CA
200c0 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 73 20  PI3REF: Results 
200d0 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 75  Values From A Qu
200e0 65 72 79 20 7b 46 31 33 38 30 30 7d 0a 2a 2a 0a  ery {F13800}.**.
200f0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
20100 73 20 66 6f 72 6d 20 74 68 65 20 22 72 65 73 75  s form the "resu
20110 6c 74 20 73 65 74 20 71 75 65 72 79 22 20 69 6e  lt set query" in
20120 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54  terface..**.** T
20130 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
20140 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  turn information
20150 20 61 62 6f 75 74 0a 2a 2a 20 61 20 73 69 6e 67   about.** a sing
20160 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  le column of the
20170 20 63 75 72 72 65 6e 74 20 72 65 73 75 6c 74 20   current result 
20180 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e 20  row of a query. 
20190 20 49 6e 20 65 76 65 72 79 0a 2a 2a 20 63 61 73   In every.** cas
201a0 65 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  e the first argu
201b0 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
201c0 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20 5b 70 72  r to the .** [pr
201d0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
201e0 5d 20 74 68 61 74 20 69 73 20 62 65 69 6e 67 0a  ] that is being.
201f0 2a 2a 20 65 76 61 6c 75 61 74 65 64 20 28 74 68  ** evaluated (th
20200 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  e [sqlite3_stmt*
20210 5d 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72  ] that was retur
20220 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71  ned from .** [sq
20230 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
20240 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74  ()] or one of it
20250 73 20 76 61 72 69 61 6e 74 73 29 20 61 6e 64 0a  s variants) and.
20260 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  ** the second ar
20270 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e  gument is the in
20280 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d  dex of the colum
20290 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f  n for which info
202a0 72 6d 61 74 69 6f 6e 20 0a 2a 2a 20 73 68 6f 75  rmation .** shou
202b0 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20  ld be returned. 
202c0 20 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63   The left-most c
202d0 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73  olumn of the res
202e0 75 6c 74 20 73 65 74 0a 2a 2a 20 68 61 73 20 61  ult set.** has a
202f0 6e 20 69 6e 64 65 78 20 6f 66 20 30 2e 0a 2a 2a  n index of 0..**
20300 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73  .** If the SQL s
20310 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20  tatement is not 
20320 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20  currently point 
20330 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20  to a valid row, 
20340 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 74 68 65  or if the.** the
20350 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73   column index is
20360 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74   out of range, t
20370 68 65 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64  he result is und
20380 65 66 69 6e 65 64 2e 20 0a 2a 2a 20 54 68 65 73  efined. .** Thes
20390 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f  e routines may o
203a0 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68  nly be called wh
203b0 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  en the most rece
203c0 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73  nt call to.** [s
203d0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68  qlite3_step()] h
203e0 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c  as returned [SQL
203f0 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69  ITE_ROW] and nei
20400 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ther.** [sqlite3
20410 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73  _reset()] nor [s
20420 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
20430 29 5d 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c  )] has been call
20440 20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a   subsequently..*
20450 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73  * If any of thes
20460 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63  e routines are c
20470 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c  alled after [sql
20480 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
20490 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  .** [sqlite3_fin
204a0 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65  alize()] or afte
204b0 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  r [sqlite3_step(
204c0 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a  )] has returned.
204d0 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68  ** something oth
204e0 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
204f0 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74  ROW], the result
20500 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
20510 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f  .** If [sqlite3_
20520 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69  step()] or [sqli
20530 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20  te3_reset()] or 
20540 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
20550 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c  e()].** are call
20560 65 64 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72  ed from a differ
20570 65 6e 74 20 74 68 72 65 61 64 20 77 68 69 6c 65  ent thread while
20580 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f   any of these ro
20590 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65  utines.** are pe
205a0 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20  nding, then the 
205b0 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
205c0 66 69 6e 65 64 2e 20 20 0a 2a 2a 0a 2a 2a 20 54  fined.  .**.** T
205d0 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
205e0 6e 5f 74 79 70 65 28 29 20 72 6f 75 74 69 6e 65  n_type() routine
205f0 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51   returns .** [SQ
20600 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64  LITE_INTEGER | d
20610 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f  atatype code] fo
20620 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61  r the initial da
20630 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68  ta type.** of th
20640 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e  e result column.
20650 20 20 54 68 65 20 72 65 74 75 72 6e 65 64 20 76    The returned v
20660 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b  alue is one of [
20670 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c  SQLITE_INTEGER],
20680 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41  .** [SQLITE_FLOA
20690 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54  T], [SQLITE_TEXT
206a0 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d  ], [SQLITE_BLOB]
206b0 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c  , or [SQLITE_NUL
206c0 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 0a 2a  L].  The value.*
206d0 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  * returned by sq
206e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
206f0 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e  e() is only mean
20700 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74 79 70  ingful if no typ
20710 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73  e.** conversions
20720 20 68 61 76 65 20 6f 63 63 75 72 72 65 64 20 61   have occurred a
20730 73 20 64 65 73 63 72 69 62 65 64 20 62 65 6c 6f  s described belo
20740 77 2e 20 20 41 66 74 65 72 20 61 20 74 79 70 65  w.  After a type
20750 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20   conversion,.** 
20760 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
20770 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
20780 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 75  lumn_type() is u
20790 6e 64 65 66 69 6e 65 64 2e 20 20 46 75 74 75 72  ndefined.  Futur
207a0 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66  e.** versions of
207b0 20 53 51 4c 69 74 65 20 6d 61 79 20 63 68 61 6e   SQLite may chan
207c0 67 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  ge the behavior 
207d0 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  of sqlite3_colum
207e0 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c  n_type().** foll
207f0 6f 77 69 6e 67 20 61 20 74 79 70 65 20 63 6f 6e  owing a type con
20800 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49  version..**.** I
20810 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
20820 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20  a BLOB or UTF-8 
20830 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20  string then the 
20840 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
20850 79 74 65 73 28 29 20 0a 2a 2a 20 72 6f 75 74 69  ytes() .** routi
20860 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ne returns the n
20870 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
20880 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73  n that BLOB or s
20890 74 72 69 6e 67 2e 0a 2a 2a 20 49 66 20 74 68 65  tring..** If the
208a0 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46   result is a UTF
208b0 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68 65 6e  -16 string, then
208c0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
208d0 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72 74 73  bytes() converts
208e0 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74  .** the string t
208f0 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68 65 6e  o UTF-8 and then
20900 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
20910 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a  ber of bytes..**
20920 20 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69   If the result i
20930 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75  s a numeric valu
20940 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  e then sqlite3_c
20950 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 73  olumn_bytes() us
20960 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  es.** [sqlite3_s
20970 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f  nprintf()] to co
20980 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65  nvert that value
20990 20 74 6f 20 61 20 55 54 46 2d 38 20 73 74 72 69   to a UTF-8 stri
209a0 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a  ng and returns.*
209b0 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
209c0 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74  bytes in that st
209d0 72 69 6e 67 2e 0a 2a 2a 20 54 68 65 20 76 61 6c  ring..** The val
209e0 75 65 20 72 65 74 75 72 6e 65 64 20 64 6f 65 73  ue returned does
209f0 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 65   not include the
20a00 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
20a10 20 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f   at the end.** o
20a20 66 20 74 68 65 20 73 74 72 69 6e 67 2e 20 20 46  f the string.  F
20a30 6f 72 20 63 6c 61 72 69 74 79 3a 20 74 68 65 20  or clarity: the 
20a40 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69  value returned i
20a50 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  s the number of.
20a60 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  ** bytes in the 
20a70 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20  string, not the 
20a80 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63  number of charac
20a90 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 53 74 72 69  ters..**.** Stri
20aa0 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ngs returned by 
20ab0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
20ac0 65 78 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ext() and sqlite
20ad0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
20ae0 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79  ),.** even empty
20af0 20 73 74 72 69 6e 67 73 2c 20 61 72 65 20 61 6c   strings, are al
20b00 77 61 79 73 20 7a 65 72 6f 20 74 65 72 6d 69 6e  ways zero termin
20b10 61 74 65 64 2e 20 20 54 68 65 20 72 65 74 75 72  ated.  The retur
20b20 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20  n.** value from 
20b30 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
20b40 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a 65 72 6f  lob() for a zero
20b50 2d 6c 65 6e 67 74 68 20 62 6c 6f 62 20 69 73 20  -length blob is 
20b60 61 6e 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20  an arbitrary.** 
20b70 70 6f 69 6e 74 65 72 2c 20 70 6f 73 73 69 62 6c  pointer, possibl
20b80 79 20 65 76 65 6e 20 61 20 4e 55 4c 4c 20 70 6f  y even a NULL po
20b90 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  inter..**.** The
20ba0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
20bb0 62 79 74 65 73 31 36 28 29 20 72 6f 75 74 69 6e  bytes16() routin
20bc0 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20  e is similar to 
20bd0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
20be0 79 74 65 73 28 29 0a 2a 2a 20 62 75 74 20 6c 65  ytes().** but le
20bf0 61 76 65 73 20 74 68 65 20 72 65 73 75 6c 74 20  aves the result 
20c00 69 6e 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74  in UTF-16 in nat
20c10 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 69  ive byte order i
20c20 6e 73 74 65 61 64 20 6f 66 20 55 54 46 2d 38 2e  nstead of UTF-8.
20c30 20 20 0a 2a 2a 20 54 68 65 20 7a 65 72 6f 20 74    .** The zero t
20c40 65 72 6d 69 6e 61 74 6f 72 20 69 73 20 6e 6f 74  erminator is not
20c50 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 69   included in thi
20c60 73 20 63 6f 75 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54  s count..**.** T
20c70 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 74  hese routines at
20c80 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 74  tempt to convert
20c90 20 74 68 65 20 76 61 6c 75 65 20 77 68 65 72 65   the value where
20ca0 20 61 70 70 72 6f 70 72 69 61 74 65 2e 20 20 46   appropriate.  F
20cb0 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69  or.** example, i
20cc0 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72  f the internal r
20cd0 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73  epresentation is
20ce0 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78   FLOAT and a tex
20cf0 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72  t result.** is r
20d00 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74  equested, [sqlit
20d10 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69  e3_snprintf()] i
20d20 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c  s used internall
20d30 79 20 74 6f 20 64 6f 20 74 68 65 20 63 6f 6e 76  y to do the conv
20d40 65 72 73 69 6f 6e 0a 2a 2a 20 61 75 74 6f 6d 61  ersion.** automa
20d50 74 69 63 61 6c 6c 79 2e 20 20 54 68 65 20 66 6f  tically.  The fo
20d60 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 65  llowing table de
20d70 74 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 72  tails the conver
20d80 73 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 61 72  sions that.** ar
20d90 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a  e applied:.**.**
20da0 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a   <blockquote>.**
20db0 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22   <table border="
20dc0 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20  1">.** <tr><th> 
20dd0 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65  Internal<br>Type
20de0 20 3c 74 68 3e 20 52 65 71 75 65 73 74 65 64 3c   <th> Requested<
20df0 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 43 6f  br>Type <th>  Co
20e00 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c  nversion.**.** <
20e10 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20  tr><td>  NULL   
20e20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
20e30 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30  <td> Result is 0
20e40 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
20e50 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41  LL    <td>  FLOA
20e60 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  T    <td> Result
20e70 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c   is 0.0.** <tr><
20e80 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
20e90 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
20ea0 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20   Result is NULL 
20eb0 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c  pointer.** <tr><
20ec0 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
20ed0 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  >   BLOB    <td>
20ee0 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20   Result is NULL 
20ef0 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c  pointer.** <tr><
20f00 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64  td> INTEGER  <td
20f10 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
20f20 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e   Convert from in
20f30 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a  teger to float.*
20f40 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47  * <tr><td> INTEG
20f50 45 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20  ER  <td>   TEXT 
20f60 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65     <td> ASCII re
20f70 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69  ndering of the i
20f80 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  nteger.** <tr><t
20f90 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e  d> INTEGER  <td>
20fa0 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
20fb0 53 61 6d 65 20 61 73 20 66 6f 72 20 49 4e 54 45  Same as for INTE
20fc0 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72  GER->TEXT.** <tr
20fd0 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c  ><td>  FLOAT   <
20fe0 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
20ff0 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20  d> Convert from 
21000 66 6c 6f 61 74 20 74 6f 20 69 6e 74 65 67 65 72  float to integer
21010 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c  .** <tr><td>  FL
21020 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58  OAT   <td>   TEX
21030 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20  T    <td> ASCII 
21040 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65  rendering of the
21050 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74   float.** <tr><t
21060 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e  d>  FLOAT   <td>
21070 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
21080 53 61 6d 65 20 61 73 20 46 4c 4f 41 54 2d 3e 54  Same as FLOAT->T
21090 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  EXT.** <tr><td> 
210a0 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 49 4e   TEXT    <td> IN
210b0 54 45 47 45 52 20 20 20 3c 74 64 3e 20 55 73 65  TEGER   <td> Use
210c0 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c   atoi().** <tr><
210d0 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64  td>  TEXT    <td
210e0 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
210f0 20 55 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c   Use atof().** <
21100 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20  tr><td>  TEXT   
21110 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20   <td>   BLOB    
21120 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a  <td> No change.*
21130 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42  * <tr><td>  BLOB
21140 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52      <td> INTEGER
21150 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20     <td> Convert 
21160 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73 65  to TEXT then use
21170 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c   atoi().** <tr><
21180 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  td>  BLOB    <td
21190 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
211a0 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54   Convert to TEXT
211b0 20 74 68 65 6e 20 75 73 65 20 61 74 6f 66 28 29   then use atof()
211c0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c  .** <tr><td>  BL
211d0 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58  OB    <td>   TEX
211e0 54 20 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20  T    <td> Add a 
211f0 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20  zero terminator 
21200 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74  if needed.** </t
21210 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b  able>.** </block
21220 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  quote>.**.** The
21230 20 74 61 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b   table above mak
21240 65 73 20 72 65 66 65 72 65 6e 63 65 20 74 6f 20  es reference to 
21250 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
21260 72 79 20 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f  ry functions ato
21270 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28  i().** and atof(
21280 29 2e 20 20 53 51 4c 69 74 65 20 64 6f 65 73 20  ).  SQLite does 
21290 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73 65 20 74  not really use t
212a0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20  hese functions. 
212b0 20 49 74 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f   It has its.** o
212c0 6e 20 65 71 75 61 76 61 6c 65 6e 74 20 69 6e 74  n equavalent int
212d0 65 72 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e 20  ernal routines. 
212e0 20 54 68 65 20 61 74 6f 69 28 29 20 61 6e 64 20   The atoi() and 
212f0 61 74 6f 66 28 29 20 6e 61 6d 65 73 20 61 72 65  atof() names are
21300 0a 2a 2a 20 75 73 65 64 20 69 6e 20 74 68 65 20  .** used in the 
21310 74 61 62 6c 65 20 66 6f 72 20 62 72 65 76 69 74  table for brevit
21320 79 20 61 6e 64 20 62 65 63 61 75 73 65 20 74 68  y and because th
21330 65 79 20 61 72 65 20 66 61 6d 69 6c 69 61 72 20  ey are familiar 
21340 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 6f  to most.** C pro
21350 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  grammers..**.** 
21360 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20 74  Note that when t
21370 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20  ype conversions 
21380 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 20  occur, pointers 
21390 72 65 74 75 72 6e 65 64 20 62 79 20 70 72 69 6f  returned by prio
213a0 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71  r.** calls to sq
213b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
213c0 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  b(), sqlite3_col
213d0 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f  umn_text(), and/
213e0 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  or.** sqlite3_co
213f0 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d 61  lumn_text16() ma
21400 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64  y be invalidated
21410 2e 20 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65  . .** Type conve
21420 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74  rsions and point
21430 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73  er invalidations
21440 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20   might occur.** 
21450 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  in the following
21460 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75   cases:.**.** <u
21470 6c 3e 0a 2a 2a 20 3c 6c 69 3e 3c 70 3e 20 20 54  l>.** <li><p>  T
21480 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65  he initial conte
21490 6e 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64  nt is a BLOB and
214a0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
214b0 74 65 78 74 28 29 20 0a 2a 2a 20 20 20 20 20 20  text() .**      
214c0 20 20 20 20 6f 72 20 73 71 6c 69 74 65 33 5f 63      or sqlite3_c
214d0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69  olumn_text16() i
214e0 73 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72  s called.  A zer
214f0 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67  o-terminator mig
21500 68 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e  ht.**          n
21510 65 65 64 20 74 6f 20 62 65 20 61 64 64 65 64 20  eed to be added 
21520 74 6f 20 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f  to the string.</
21530 70 3e 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c  p></li>.**.** <l
21540 69 3e 3c 70 3e 20 20 54 68 65 20 69 6e 69 74 69  i><p>  The initi
21550 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54  al content is UT
21560 46 2d 38 20 74 65 78 74 20 61 6e 64 20 73 71 6c  F-8 text and sql
21570 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
21580 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20  s16() or.**     
21590 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c       sqlite3_col
215a0 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20  umn_text16() is 
215b0 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e  called.  The con
215c0 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e  tent must be con
215d0 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 20  verted.**       
215e0 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 70     to UTF-16.</p
215f0 3e 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  ></li>.**.** <li
21600 3e 3c 70 3e 20 20 54 68 65 20 69 6e 69 74 69 61  ><p>  The initia
21610 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46  l content is UTF
21620 2d 31 36 20 74 65 78 74 20 61 6e 64 20 73 71 6c  -16 text and sql
21630 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
21640 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20  s() or.**       
21650 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d     sqlite3_colum
21660 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c 6c  n_text() is call
21670 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74  ed.  The content
21680 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74   must be convert
21690 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  ed.**          t
216a0 6f 20 55 54 46 2d 38 2e 3c 2f 70 3e 3c 2f 6c 69  o UTF-8.</p></li
216b0 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  >.** </ul>.**.**
216c0 20 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65 74   Conversions bet
216d0 77 65 65 6e 20 55 54 46 2d 31 36 62 65 20 61 6e  ween UTF-16be an
216e0 64 20 55 54 46 2d 31 36 6c 65 20 61 72 65 20 61  d UTF-16le are a
216f0 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c  lways done in pl
21700 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f  ace and do.** no
21710 74 20 69 6e 76 61 6c 69 64 61 74 65 20 61 20 70  t invalidate a p
21720 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74 68  rior pointer, th
21730 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74  ough of course t
21740 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
21750 65 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74  e buffer.** that
21760 20 74 68 65 20 70 72 69 6f 72 20 70 6f 69 6e 74   the prior point
21770 65 72 20 70 6f 69 6e 74 73 20 74 6f 20 77 69 6c  er points to wil
21780 6c 20 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69  l have been modi
21790 66 69 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e  fied.  Other kin
217a0 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73  ds.** of convers
217b0 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20  ion are done in 
217c0 70 6c 61 63 65 20 77 68 65 6e 20 69 74 20 69 73  place when it is
217d0 20 70 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73   possible, but s
217e0 6f 6d 65 74 69 6d 65 20 69 74 20 69 73 0a 2a 2a  ometime it is.**
217f0 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e   not possible an
21800 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73  d in those cases
21810 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20   prior pointers 
21820 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e  are invalidated.
21830 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66    .**.** The saf
21840 65 73 74 20 61 6e 64 20 65 61 73 69 65 73 74 20  est and easiest 
21850 74 6f 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69  to remember poli
21860 63 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20  cy is to invoke 
21870 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a  these routines.*
21880 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20  * in one of the 
21890 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a  following ways:.
218a0 2a 2a 0a 2a 2a 20 20 3c 75 6c 3e 0a 2a 2a 20 20  **.**  <ul>.**  
218b0 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  <li>sqlite3_colu
218c0 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77  mn_text() follow
218d0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
218e0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69  lumn_bytes()</li
218f0 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65  >.**  <li>sqlite
21900 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20  3_column_blob() 
21910 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69  followed by sqli
21920 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
21930 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e  ()</li>.**  <li>
21940 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
21950 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64  ext16() followed
21960 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
21970 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c 69  mn_bytes16()</li
21980 3e 0a 2a 2a 20 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  >.**  </ul>.**.*
21990 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  * In other words
219a0 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c  , you should cal
219b0 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  l sqlite3_column
219c0 5f 74 65 78 74 28 29 2c 20 73 71 6c 69 74 65 33  _text(), sqlite3
219d0 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 0a  _column_blob(),.
219e0 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f  ** or sqlite3_co
219f0 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 69  lumn_text16() fi
21a00 72 73 74 20 74 6f 20 66 6f 72 63 65 20 74 68 65  rst to force the
21a10 20 72 65 73 75 6c 74 20 69 6e 74 6f 20 74 68 65   result into the
21a20 20 64 65 73 69 72 65 64 0a 2a 2a 20 66 6f 72 6d   desired.** form
21a30 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20  at, then invoke 
21a40 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
21a50 79 74 65 73 28 29 20 6f 72 20 73 71 6c 69 74 65  ytes() or sqlite
21a60 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
21a70 28 29 20 74 6f 0a 2a 2a 20 66 69 6e 64 20 74 68  () to.** find th
21a80 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 72 65  e size of the re
21a90 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69  sult.  Do not mi
21aa0 78 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  x call to sqlite
21ab0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
21ac0 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  or.** sqlite3_co
21ad0 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68  lumn_blob() with
21ae0 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
21af0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
21b00 28 29 2e 20 20 41 6e 64 20 64 6f 20 6e 6f 74 0a  ().  And do not.
21b10 2a 2a 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20  ** mix calls to 
21b20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
21b30 65 78 74 31 36 28 29 20 77 69 74 68 20 63 61 6c  ext16() with cal
21b40 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ls to sqlite3_co
21b50 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a  lumn_bytes()..**
21b60 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 73  .** The pointers
21b70 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 76 61   returned are va
21b80 6c 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65  lid until a type
21b90 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75   conversion occu
21ba0 72 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62  rs as.** describ
21bb0 65 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74  ed above, or unt
21bc0 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  il [sqlite3_step
21bd0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
21be0 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b  reset()] or.** [
21bf0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
21c00 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  ()] is called.  
21c10 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65  The memory space
21c20 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 74   used to hold st
21c30 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 62 6c 6f  rings.** and blo
21c40 62 73 20 69 73 20 66 72 65 65 64 20 61 75 74 6f  bs is freed auto
21c50 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c  matically.  Do <
21c60 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 73 20 74  b>not</b> pass t
21c70 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75  he pointers retu
21c80 72 6e 65 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  rned.** [sqlite3
21c90 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c  _column_blob()],
21ca0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
21cb0 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69  _text()], etc. i
21cc0 6e 74 6f 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  nto .** [sqlite3
21cd0 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _free()]..**.** 
21ce0 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  If a memory allo
21cf0 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63  cation error occ
21d00 75 72 73 20 64 75 72 69 6e 67 20 74 68 65 20 65  urs during the e
21d10 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79  valuation of any
21d20 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 72 6f 75  .** of these rou
21d30 74 69 6e 65 73 2c 20 61 20 64 65 66 61 75 6c 74  tines, a default
21d40 20 76 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e   value is return
21d50 65 64 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74  ed.  The default
21d60 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74   value.** is eit
21d70 68 65 72 20 74 68 65 20 69 6e 74 65 67 65 72 20  her the integer 
21d80 30 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20  0, the floating 
21d90 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30  point number 0.0
21da0 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70  , or a NULL.** p
21db0 6f 69 6e 74 65 72 2e 20 20 53 75 62 73 65 71 75  ointer.  Subsequ
21dc0 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  ent calls to [sq
21dd0 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d  lite3_errcode()]
21de0 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20   will return.** 
21df0 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a  [SQLITE_NOMEM]..
21e00 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
21e10 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 30 33 7d  :.**.** {F13803}
21e20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
21e30 6c 75 6d 6e 5f 62 6c 6f 62 28 53 2c 4e 29 5d 20  lumn_blob(S,N)] 
21e40 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72  interface conver
21e50 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ts the.**       
21e60 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e     Nth column in
21e70 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77   the current row
21e80 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
21e90 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20  et for.**       
21ea0 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61     [prepared sta
21eb0 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61  tement] S into a
21ec0 20 62 6c 6f 62 20 61 6e 64 20 74 68 65 6e 20 72   blob and then r
21ed0 65 74 75 72 6e 73 20 61 0a 2a 2a 20 20 20 20 20  eturns a.**     
21ee0 20 20 20 20 20 70 6f 69 6e 74 65 72 20 74 6f 20       pointer to 
21ef0 74 68 65 20 63 6f 6e 76 65 72 74 65 64 20 76 61  the converted va
21f00 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38  lue..**.** {F138
21f10 30 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  06} The [sqlite3
21f20 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 53 2c  _column_bytes(S,
21f30 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  N)] interface re
21f40 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20  turns the.**    
21f50 20 20 20 20 20 20 6e 75 6d 62 65 72 20 6f 66 20        number of 
21f60 62 79 74 65 73 20 69 6e 20 74 68 65 20 62 6c 6f  bytes in the blo
21f70 62 20 6f 72 20 73 74 72 69 6e 67 20 28 65 78 63  b or string (exc
21f80 6c 75 73 69 76 65 20 6f 66 20 74 68 65 0a 2a 2a  lusive of the.**
21f90 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 20 74            zero t
21fa0 65 72 6d 69 6e 61 74 6f 72 20 6f 6e 20 74 68 65  erminator on the
21fb0 20 73 74 72 69 6e 67 29 20 74 68 61 74 20 77 61   string) that wa
21fc0 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  s returned by th
21fd0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 6f  e.**          mo
21fe0 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74  st recent call t
21ff0 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  o [sqlite3_colum
22000 6e 5f 62 6c 6f 62 28 53 2c 4e 29 5d 20 6f 72 0a  n_blob(S,N)] or.
22010 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
22020 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
22030 28 53 2c 4e 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46  (S,N)]..**.** {F
22040 31 33 38 30 39 7d 20 54 68 65 20 5b 73 71 6c 69  13809} The [sqli
22050 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
22060 31 36 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61  16(S,N)] interfa
22070 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a  ce returns the.*
22080 2a 20 20 20 20 20 20 20 20 20 20 6e 75 6d 62 65  *          numbe
22090 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
220a0 65 20 73 74 72 69 6e 67 20 28 65 78 63 6c 75 73  e string (exclus
220b0 69 76 65 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20  ive of the.**   
220c0 20 20 20 20 20 20 20 7a 65 72 6f 20 74 65 72 6d         zero term
220d0 69 6e 61 74 6f 72 20 6f 6e 20 74 68 65 20 73 74  inator on the st
220e0 72 69 6e 67 29 20 74 68 61 74 20 77 61 73 20 72  ring) that was r
220f0 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a  eturned by the.*
22100 2a 20 20 20 20 20 20 20 20 20 20 6d 6f 73 74 20  *          most 
22110 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b  recent call to [
22120 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
22130 65 78 74 31 36 28 53 2c 4e 29 5d 2e 0a 2a 2a 0a  ext16(S,N)]..**.
22140 2a 2a 20 7b 46 31 33 38 31 32 7d 20 54 68 65 20  ** {F13812} The 
22150 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
22160 64 6f 75 62 6c 65 28 53 2c 4e 29 5d 20 69 6e 74  double(S,N)] int
22170 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20  erface converts 
22180 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
22190 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68  Nth column in th
221a0 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66  e current row of
221b0 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
221c0 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  for.**          
221d0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
221e0 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20 66 6c  ent] S into a fl
221f0 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
22200 75 65 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20  ue and.**       
22210 20 20 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70     returns a cop
22220 79 20 6f 66 20 74 68 61 74 20 76 61 6c 75 65 2e  y of that value.
22230 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 31 35 7d 20  .**.** {F13815} 
22240 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  The [sqlite3_col
22250 75 6d 6e 5f 69 6e 74 28 53 2c 4e 29 5d 20 69 6e  umn_int(S,N)] in
22260 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73  terface converts
22270 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
22280 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74   Nth column in t
22290 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f  he current row o
222a0 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
222b0 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20   for.**         
222c0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
222d0 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20 36  ment] S into a 6
222e0 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  4-bit signed int
222f0 65 67 65 72 20 61 6e 64 0a 2a 2a 20 20 20 20 20  eger and.**     
22300 20 20 20 20 20 72 65 74 75 72 6e 73 20 74 68 65       returns the
22310 20 6c 6f 77 65 72 20 33 32 20 62 69 74 73 20 6f   lower 32 bits o
22320 66 20 74 68 61 74 20 69 6e 74 65 67 65 72 2e 0a  f that integer..
22330 2a 2a 0a 2a 2a 20 7b 46 31 33 38 31 38 7d 20 54  **.** {F13818} T
22340 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
22350 6d 6e 5f 69 6e 74 36 34 28 53 2c 4e 29 5d 20 69  mn_int64(S,N)] i
22360 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74  nterface convert
22370 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
22380 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20    Nth column in 
22390 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20  the current row 
223a0 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
223b0 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  t for.**        
223c0 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74    [prepared stat
223d0 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20  ement] S into a 
223e0 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  64-bit signed in
223f0 74 65 67 65 72 20 61 6e 64 0a 2a 2a 20 20 20 20  teger and.**    
22400 20 20 20 20 20 20 72 65 74 75 72 6e 73 20 61 20        returns a 
22410 63 6f 70 79 20 6f 66 20 74 68 61 74 20 69 6e 74  copy of that int
22420 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  eger..**.** {F13
22430 38 32 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  821} The [sqlite
22440 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 53 2c  3_column_text(S,
22450 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f  N)] interface co
22460 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20  nverts the.**   
22470 20 20 20 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d         Nth colum
22480 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74  n in the current
22490 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75   row of the resu
224a0 6c 74 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20 20  lt set for.**   
224b0 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64         [prepared
224c0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e   statement] S in
224d0 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  to a zero-termin
224e0 61 74 65 64 20 55 54 46 2d 38 20 0a 2a 2a 20 20  ated UTF-8 .**  
224f0 20 20 20 20 20 20 20 20 73 74 72 69 6e 67 20 61          string a
22500 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  nd returns a poi
22510 6e 74 65 72 20 74 6f 20 74 68 61 74 20 73 74 72  nter to that str
22520 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38  ing..**.** {F138
22530 32 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  24} The [sqlite3
22540 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 53  _column_text16(S
22550 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  ,N)] interface c
22560 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20  onverts the.**  
22570 20 20 20 20 20 20 20 20 4e 74 68 20 63 6f 6c 75          Nth colu
22580 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e  mn in the curren
22590 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73  t row of the res
225a0 75 6c 74 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20  ult set for.**  
225b0 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65          [prepare
225c0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69  d statement] S i
225d0 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69  nto a zero-termi
225e0 6e 61 74 65 64 20 32 2d 62 79 74 65 0a 2a 2a 20  nated 2-byte.** 
225f0 20 20 20 20 20 20 20 20 20 61 6c 69 67 6e 65 64           aligned
22600 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62   UTF-16 native b
22610 79 74 65 20 6f 72 64 65 72 0a 2a 2a 20 20 20 20  yte order.**    
22620 20 20 20 20 20 20 73 74 72 69 6e 67 20 61 6e 64        string and
22630 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
22640 65 72 20 74 6f 20 74 68 61 74 20 73 74 72 69 6e  er to that strin
22650 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 32 37  g..**.** {F13827
22660 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
22670 6f 6c 75 6d 6e 5f 74 79 70 65 28 53 2c 4e 29 5d  olumn_type(S,N)]
22680 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
22690 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  ns.**          o
226a0 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4e 55  ne of [SQLITE_NU
226b0 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4e 54  LL], [SQLITE_INT
226c0 45 47 45 52 5d 2c 20 5b 53 51 4c 49 54 45 5f 46  EGER], [SQLITE_F
226d0 4c 4f 41 54 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  LOAT],.**       
226e0 20 20 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d     [SQLITE_TEXT]
226f0 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 42 4c 4f  , or [SQLITE_BLO
22700 42 5d 20 61 73 20 61 70 70 72 6f 70 72 69 61 74  B] as appropriat
22710 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  e for.**        
22720 20 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e    the Nth column
22730 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20   in the current 
22740 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c  row of the resul
22750 74 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20  t set for.**    
22760 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20        [prepared 
22770 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2a  statement] S..**
22780 0a 2a 2a 20 7b 46 31 33 38 33 30 7d 20 54 68 65  .** {F13830} The
22790 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
227a0 5f 76 61 6c 75 65 28 53 2c 4e 29 5d 20 69 6e 74  _value(S,N)] int
227b0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
227c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 6f 69  .**          poi
227d0 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c  nter to the [sql
227e0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
227f0 63 74 20 74 68 61 74 20 66 6f 72 20 74 68 65 0a  ct that for the.
22800 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20  **          Nth 
22810 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75  column in the cu
22820 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65  rrent row of the
22830 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72 0a   result set for.
22840 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65  **          [pre
22850 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
22860 20 53 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69   S..*/.const voi
22870 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
22880 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73  n_blob(sqlite3_s
22890 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
228a0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
228b0 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65  umn_bytes(sqlite
228c0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
228d0 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
228e0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 73  column_bytes16(s
228f0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
22900 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20  t iCol);.double 
22910 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
22920 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74  ouble(sqlite3_st
22930 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
22940 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
22950 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73  mn_int(sqlite3_s
22960 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
22970 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
22980 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e  qlite3_column_in
22990 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t64(sqlite3_stmt
229a0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f  *, int iCol);.co
229b0 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61  nst unsigned cha
229c0 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
229d0 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73  n_text(sqlite3_s
229e0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
229f0 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
22a00 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
22a10 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
22a20 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74  , int iCol);.int
22a30 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
22a40 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  type(sqlite3_stm
22a50 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73  t*, int iCol);.s
22a60 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71  qlite3_value *sq
22a70 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
22a80 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ue(sqlite3_stmt*
22a90 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a  , int iCol);../*
22aa0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
22ab0 73 74 72 6f 79 20 41 20 50 72 65 70 61 72 65 64  stroy A Prepared
22ac0 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63   Statement Objec
22ad0 74 20 7b 46 31 33 33 30 30 7d 0a 2a 2a 0a 2a 2a  t {F13300}.**.**
22ae0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e   The sqlite3_fin
22af0 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e  alize() function
22b00 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 64 65   is called to de
22b10 6c 65 74 65 20 61 20 0a 2a 2a 20 5b 70 72 65 70  lete a .** [prep
22b20 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
22b30 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   If the statemen
22b40 74 20 77 61 73 0a 2a 2a 20 65 78 65 63 75 74 65  t was.** execute
22b50 64 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20  d successfully, 
22b60 6f 72 20 6e 6f 74 20 65 78 65 63 75 74 65 64 20  or not executed 
22b70 61 74 20 61 6c 6c 2c 20 74 68 65 6e 20 53 51 4c  at all, then SQL
22b80 49 54 45 5f 4f 4b 20 69 73 20 72 65 74 75 72 6e  ITE_OK is return
22b90 65 64 2e 0a 2a 2a 20 49 66 20 65 78 65 63 75 74  ed..** If execut
22ba0 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 74 65  ion of the state
22bb0 6d 65 6e 74 20 66 61 69 6c 65 64 20 74 68 65 6e  ment failed then
22bc0 20 61 6e 20 0a 2a 2a 20 5b 65 72 72 6f 72 20 63   an .** [error c
22bd0 6f 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65  ode] or [extende
22be0 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 0a 2a 2a  d error code].**
22bf0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 0a 2a   is returned. .*
22c00 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
22c10 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20  e can be called 
22c20 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 75 72  at any point dur
22c30 69 6e 67 20 74 68 65 20 65 78 65 63 75 74 69 6f  ing the executio
22c40 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65  n of the.** [pre
22c50 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
22c60 2e 20 20 49 66 20 74 68 65 20 76 69 72 74 75 61  .  If the virtua
22c70 6c 20 6d 61 63 68 69 6e 65 20 68 61 73 20 6e 6f  l machine has no
22c80 74 20 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20  t .** completed 
22c90 65 78 65 63 75 74 69 6f 6e 20 77 68 65 6e 20 74  execution when t
22ca0 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 63  his routine is c
22cb0 61 6c 6c 65 64 2c 20 74 68 61 74 20 69 73 20 6c  alled, that is l
22cc0 69 6b 65 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72  ike.** encounter
22cd0 69 6e 67 20 61 6e 20 65 72 72 6f 72 20 6f 72 20  ing an error or 
22ce0 61 6e 20 69 6e 74 65 72 72 75 70 74 2e 20 20 28  an interrupt.  (
22cf0 53 65 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74  See [sqlite3_int
22d00 65 72 72 75 70 74 28 29 5d 2e 29 20 0a 2a 2a 20  errupt()].) .** 
22d10 49 6e 63 6f 6d 70 6c 65 74 65 20 75 70 64 61 74  Incomplete updat
22d20 65 73 20 6d 61 79 20 62 65 20 72 6f 6c 6c 65 64  es may be rolled
22d30 20 62 61 63 6b 20 61 6e 64 20 74 72 61 6e 73 61   back and transa
22d40 63 74 69 6f 6e 73 20 63 61 6e 63 65 6c 6c 65 64  ctions cancelled
22d50 2c 20 20 0a 2a 2a 20 64 65 70 65 6e 64 69 6e 67  ,  .** depending
22d60 20 6f 6e 20 74 68 65 20 63 69 72 63 75 6d 73 74   on the circumst
22d70 61 6e 63 65 73 2c 20 61 6e 64 20 74 68 65 20 0a  ances, and the .
22d80 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  ** [error code] 
22d90 72 65 74 75 72 6e 65 64 20 77 69 6c 6c 20 62 65  returned will be
22da0 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e   [SQLITE_ABORT].
22db0 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
22dc0 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 33 30 32  S:.**.** {F11302
22dd0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  } The [sqlite3_f
22de0 69 6e 61 6c 69 7a 65 28 53 29 5d 20 69 6e 74 65  inalize(S)] inte
22df0 72 66 61 63 65 20 64 65 73 74 72 6f 79 73 20 74  rface destroys t
22e00 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
22e10 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
22e20 6e 74 5d 20 53 20 61 6e 64 20 72 65 6c 65 61 73  nt] S and releas
22e30 65 73 20 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20  es all.**       
22e40 20 20 20 6d 65 6d 6f 72 79 20 61 6e 64 20 66 69     memory and fi
22e50 6c 65 20 72 65 73 6f 75 72 63 65 73 20 68 65 6c  le resources hel
22e60 64 20 62 79 20 74 68 61 74 20 6f 62 6a 65 63 74  d by that object
22e70 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 33 30 34 7d  ..**.** {F11304}
22e80 20 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63   If the most rec
22e90 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ent call to [sql
22ea0 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f  ite3_step(S)] fo
22eb0 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  r the.**        
22ec0 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74    [prepared stat
22ed0 65 6d 65 6e 74 5d 20 53 20 72 65 74 75 72 6e 65  ement] S returne
22ee0 64 20 61 6e 20 65 72 72 6f 72 2c 0a 2a 2a 20 20  d an error,.**  
22ef0 20 20 20 20 20 20 20 20 74 68 65 6e 20 5b 73 71          then [sq
22f00 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53  lite3_finalize(S
22f10 29 5d 20 72 65 74 75 72 6e 73 20 74 68 61 74 20  )] returns that 
22f20 73 61 6d 65 20 65 72 72 6f 72 2e 0a 2a 2f 0a 69  same error..*/.i
22f30 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  nt sqlite3_final
22f40 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ize(sqlite3_stmt
22f50 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
22f60 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74   CAPI3REF: Reset
22f70 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74   A Prepared Stat
22f80 65 6d 65 6e 74 20 4f 62 6a 65 63 74 20 7b 46 31  ement Object {F1
22f90 33 33 33 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20  3330}.**.** The 
22fa0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 20  sqlite3_reset() 
22fb0 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c  function is call
22fc0 65 64 20 74 6f 20 72 65 73 65 74 20 61 20 0a 2a  ed to reset a .*
22fd0 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
22fe0 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 2e 0a 2a  ement] object..*
22ff0 2a 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e  * back to its in
23000 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65 61  itial state, rea
23010 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65 63  dy to be re-exec
23020 75 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 53 51 4c  uted..** Any SQL
23030 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69 61   statement varia
23040 62 6c 65 73 20 74 68 61 74 20 68 61 64 20 76 61  bles that had va
23050 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74 68  lues bound to th
23060 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20  em using.** the 
23070 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
23080 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e  ob | sqlite3_bin
23090 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61 69  d_*() API] retai
230a0 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e 0a  n their values..
230b0 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33 5f  ** Use [sqlite3_
230c0 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 29  clear_bindings()
230d0 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 62  ] to reset the b
230e0 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 7b  indings..**.** {
230f0 46 31 31 33 33 32 7d 20 54 68 65 20 5b 73 71 6c  F11332} The [sql
23100 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69  ite3_reset(S)] i
23110 6e 74 65 72 66 61 63 65 20 72 65 73 65 74 73 20  nterface resets 
23120 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
23130 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 20 20  atement] S.**   
23140 20 20 20 20 20 20 20 62 61 63 6b 20 74 6f 20 74         back to t
23150 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20  he beginning of 
23160 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a  its program..**.
23170 2a 2a 20 7b 46 31 31 33 33 34 7d 20 49 66 20 74  ** {F11334} If t
23180 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63  he most recent c
23190 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
231a0 73 74 65 70 28 53 29 5d 20 66 6f 72 20 0a 2a 2a  step(S)] for .**
231b0 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61            [prepa
231c0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
231d0 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54   returned [SQLIT
231e0 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54  E_ROW] or [SQLIT
231f0 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 20 20 20 20  E_DONE],.**     
23200 20 20 20 20 20 6f 72 20 69 66 20 5b 73 71 6c 69       or if [sqli
23210 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73  te3_step(S)] has
23220 20 6e 65 76 65 72 20 62 65 66 6f 72 65 20 62 65   never before be
23230 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a  en called on S,.
23240 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e  **          then
23250 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
23260 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  S)] returns [SQL
23270 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  ITE_OK]..**.** {
23280 46 31 31 33 33 36 7d 20 49 66 20 74 68 65 20 6d  F11336} If the m
23290 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
232a0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
232b0 28 53 29 5d 20 66 6f 72 0a 2a 2a 20 20 20 20 20  (S)] for.**     
232c0 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73       [prepared s
232d0 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69  tatement] S indi
232e0 63 61 74 65 64 20 61 6e 20 65 72 72 6f 72 2c 20  cated an error, 
232f0 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  then.**         
23300 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
23310 53 29 5d 20 72 65 74 75 72 6e 73 20 61 6e 20 61  S)] returns an a
23320 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f  ppropriate [erro
23330 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  r code]..**.** {
23340 46 31 31 33 33 38 7d 20 54 68 65 20 5b 73 71 6c  F11338} The [sql
23350 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69  ite3_reset(S)] i
23360 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f  nterface does no
23370 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c  t change the val
23380 75 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ues.**          
23390 6f 66 20 61 6e 79 20 5b 73 71 6c 69 74 65 33 5f  of any [sqlite3_
233a0 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e  bind_blob|bindin
233b0 67 73 5d 20 6f 6e 20 5b 70 72 65 70 61 72 65 64  gs] on [prepared
233c0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a   statement] S..*
233d0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65  /.int sqlite3_re
233e0 73 65 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  set(sqlite3_stmt
233f0 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
23400 20 43 41 50 49 33 52 45 46 3a 20 43 72 65 61 74   CAPI3REF: Creat
23410 65 20 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51  e Or Redefine SQ
23420 4c 20 46 75 6e 63 74 69 6f 6e 73 20 7b 46 31 36  L Functions {F16
23430 31 30 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  100}.** KEYWORDS
23440 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65 61  : {function crea
23450 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 20 0a  tion routines} .
23460 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 74 77 6f 20  **.** These two 
23470 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65  functions (colle
23480 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73  ctively known as
23490 0a 2a 2a 20 22 66 75 6e 63 74 69 6f 6e 20 63 72  .** "function cr
234a0 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22  eation routines"
234b0 29 20 61 72 65 20 75 73 65 64 20 74 6f 20 61 64  ) are used to ad
234c0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  d SQL functions 
234d0 6f 72 20 61 67 67 72 65 67 61 74 65 73 0a 2a 2a  or aggregates.**
234e0 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65 20   or to redefine 
234f0 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20  the behavior of 
23500 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e  existing SQL fun
23510 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67  ctions or aggreg
23520 61 74 65 73 2e 20 20 54 68 65 0a 2a 2a 20 64 69  ates.  The.** di
23530 66 66 65 72 65 6e 63 65 20 6f 6e 6c 79 20 62 65  fference only be
23540 74 77 65 65 6e 20 74 68 65 20 74 77 6f 20 69 73  tween the two is
23550 20 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e 64   that the second
23560 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 0a   parameter, the.
23570 2a 2a 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 28  ** name of the (
23580 73 63 61 6c 61 72 29 20 66 75 6e 63 74 69 6f 6e  scalar) function
23590 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20 69   or aggregate, i
235a0 73 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54 46  s encoded in UTF
235b0 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  -8 for.** sqlite
235c0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
235d0 6e 28 29 20 61 6e 64 20 55 54 46 2d 31 36 20 66  n() and UTF-16 f
235e0 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  or sqlite3_creat
235f0 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 2e 0a  e_function16()..
23600 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
23610 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
23620 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
23630 74 69 6f 6e 5d 20 74 68 61 74 20 68 6f 6c 64 73  tion] that holds
23640 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63   the.** SQL func
23650 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74  tion or aggregat
23660 65 20 69 73 20 74 6f 20 62 65 20 61 64 64 65 64  e is to be added
23670 20 6f 72 20 72 65 64 65 66 69 6e 65 64 2e 20 49   or redefined. I
23680 66 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 70 72  f a single.** pr
23690 6f 67 72 61 6d 20 75 73 65 73 20 6d 6f 72 65 20  ogram uses more 
236a0 74 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73  than one databas
236b0 65 20 68 61 6e 64 6c 65 20 69 6e 74 65 72 6e 61  e handle interna
236c0 6c 6c 79 2c 20 74 68 65 6e 20 53 51 4c 0a 2a 2a  lly, then SQL.**
236d0 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67   functions or ag
236e0 67 72 65 67 61 74 65 73 20 6d 75 73 74 20 62 65  gregates must be
236f0 20 61 64 64 65 64 20 69 6e 64 69 76 69 64 75 61   added individua
23700 6c 6c 79 20 74 6f 20 65 61 63 68 20 64 61 74 61  lly to each data
23710 62 61 73 65 0a 2a 2a 20 68 61 6e 64 6c 65 20 77  base.** handle w
23720 69 74 68 20 77 68 69 63 68 20 74 68 65 79 20 77  ith which they w
23730 69 6c 6c 20 62 65 20 75 73 65 64 2e 0a 2a 2a 0a  ill be used..**.
23740 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  ** The second pa
23750 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e  rameter is the n
23760 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66  ame of the SQL f
23770 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72  unction to be cr
23780 65 61 74 65 64 0a 2a 2a 20 6f 72 20 72 65 64 65  eated.** or rede
23790 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6c 65  fined..** The le
237a0 6e 67 74 68 20 6f 66 20 74 68 65 20 6e 61 6d 65  ngth of the name
237b0 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 32   is limited to 2
237c0 35 35 20 62 79 74 65 73 2c 20 65 78 63 6c 75 73  55 bytes, exclus
237d0 69 76 65 20 6f 66 20 74 68 65 20 0a 2a 2a 20 7a  ive of the .** z
237e0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20  ero-terminator. 
237f0 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6e   Note that the n
23800 61 6d 65 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74  ame length limit
23810 20 69 73 20 69 6e 20 62 79 74 65 73 2c 20 6e 6f   is in bytes, no
23820 74 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 2e  t.** characters.
23830 20 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f    Any attempt to
23840 20 63 72 65 61 74 65 20 61 20 66 75 6e 63 74 69   create a functi
23850 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67 65 72  on with a longer
23860 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65   name.** will re
23870 73 75 6c 74 20 69 6e 20 61 6e 20 53 51 4c 49 54  sult in an SQLIT
23880 45 5f 45 52 52 4f 52 20 65 72 72 6f 72 2e 0a 2a  E_ERROR error..*
23890 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20 70  *.** The third p
238a0 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
238b0 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65  number of argume
238c0 6e 74 73 20 74 68 61 74 20 74 68 65 20 53 51 4c  nts that the SQL
238d0 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20   function or.** 
238e0 61 67 67 72 65 67 61 74 65 20 74 61 6b 65 73 2e  aggregate takes.
238f0 20 49 66 20 74 68 69 73 20 70 61 72 61 6d 65 74   If this paramet
23900 65 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  er is negative, 
23910 74 68 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e  then the SQL fun
23920 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72  ction or.** aggr
23930 65 67 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61  egate may take a
23940 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67  ny number of arg
23950 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  uments..**.** Th
23960 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
23970 65 72 2c 20 65 54 65 78 74 52 65 70 2c 20 73 70  er, eTextRep, sp
23980 65 63 69 66 69 65 73 20 77 68 61 74 20 0a 2a 2a  ecifies what .**
23990 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20   [SQLITE_UTF8 | 
239a0 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74  text encoding] t
239b0 68 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  his SQL function
239c0 20 70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20   prefers for.** 
239d0 69 74 73 20 70 61 72 61 6d 65 74 65 72 73 2e 20  its parameters. 
239e0 20 41 6e 79 20 53 51 4c 20 66 75 6e 63 74 69 6f   Any SQL functio
239f0 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
23a00 20 73 68 6f 75 6c 64 20 62 65 20 61 62 6c 65 20   should be able 
23a10 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 6f 72 6b 20  to work.** work 
23a20 77 69 74 68 20 55 54 46 2d 38 2c 20 55 54 46 2d  with UTF-8, UTF-
23a30 31 36 6c 65 2c 20 6f 72 20 55 54 46 2d 31 36 62  16le, or UTF-16b
23a40 65 2e 20 20 42 75 74 20 73 6f 6d 65 20 69 6d 70  e.  But some imp
23a50 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61 79  lementations may
23a60 20 62 65 0a 2a 2a 20 6d 6f 72 65 20 65 66 66 69   be.** more effi
23a70 63 69 65 6e 74 20 77 69 74 68 20 6f 6e 65 20 65  cient with one e
23a80 6e 63 6f 64 69 6e 67 20 74 68 61 6e 20 61 6e 6f  ncoding than ano
23a90 74 68 65 72 2e 20 20 49 74 20 69 73 20 61 6c 6c  ther.  It is all
23aa0 6f 77 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b  owed to.** invok
23ab0 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  e sqlite3_create
23ac0 5f 66 75 6e 63 74 69 6f 6e 28 29 20 6f 72 20 73  _function() or s
23ad0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
23ae0 6e 63 74 69 6f 6e 31 36 28 29 20 6d 75 6c 74 69  nction16() multi
23af0 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 20 77 69 74  ple.** times wit
23b00 68 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74  h the same funct
23b10 69 6f 6e 20 62 75 74 20 77 69 74 68 20 64 69 66  ion but with dif
23b20 66 65 72 65 6e 74 20 76 61 6c 75 65 73 20 6f 66  ferent values of
23b30 20 65 54 65 78 74 52 65 70 2e 0a 2a 2a 20 57 68   eTextRep..** Wh
23b40 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c  en multiple impl
23b50 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74  ementations of t
23b60 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e  he same function
23b70 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c 20   are available, 
23b80 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70  SQLite.** will p
23b90 69 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 74  ick the one that
23ba0 20 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c 65   involves the le
23bb0 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61  ast amount of da
23bc0 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a  ta conversion..*
23bd0 2a 20 49 66 20 74 68 65 72 65 20 69 73 20 6f 6e  * If there is on
23be0 6c 79 20 61 20 73 69 6e 67 6c 65 20 69 6d 70 6c  ly a single impl
23bf0 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 69 63 68  ementation which
23c00 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 77   does not care w
23c10 68 61 74 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f  hat.** text enco
23c20 64 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68  ding is used, th
23c30 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61 72  en the fourth ar
23c40 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65  gument should be
23c50 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 41 4e 59 5d  .** [SQLITE_ANY]
23c60 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 66 74  ..**.** The fift
23c70 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  h parameter is a
23c80 6e 20 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e  n arbitrary poin
23c90 74 65 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d  ter.  The implem
23ca0 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 74  entation.** of t
23cb0 68 65 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20  he function can 
23cc0 67 61 69 6e 20 61 63 63 65 73 73 20 74 6f 20 74  gain access to t
23cd0 68 69 73 20 70 6f 69 6e 74 65 72 20 75 73 69 6e  his pointer usin
23ce0 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 75 73  g.** [sqlite3_us
23cf0 65 72 5f 64 61 74 61 28 29 5d 2e 0a 2a 2a 0a 2a  er_data()]..**.*
23d00 2a 20 54 68 65 20 73 65 76 65 6e 74 68 2c 20 65  * The seventh, e
23d10 69 67 68 74 68 20 61 6e 64 20 6e 69 6e 74 68 20  ighth and ninth 
23d20 70 61 72 61 6d 65 74 65 72 73 2c 20 78 46 75 6e  parameters, xFun
23d30 63 2c 20 78 53 74 65 70 20 61 6e 64 20 78 46 69  c, xStep and xFi
23d40 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e  nal, are.** poin
23d50 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61  ters to C-langua
23d60 67 65 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61  ge functions tha
23d70 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20  t implement the 
23d80 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  SQL.** function 
23d90 6f 72 20 61 67 67 72 65 67 61 74 65 2e 20 41 20  or aggregate. A 
23da0 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74  scalar SQL funct
23db0 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20  ion requires an 
23dc0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
23dd0 66 0a 2a 2a 20 74 68 65 20 78 46 75 6e 63 20 63  f.** the xFunc c
23de0 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 2c 20 4e 55  allback only, NU
23df0 4c 4c 20 70 6f 69 6e 74 65 72 73 20 73 68 6f 75  LL pointers shou
23e00 6c 64 20 62 65 20 70 61 73 73 65 64 20 61 73 20  ld be passed as 
23e10 74 68 65 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64  the xStep.** and
23e20 20 78 46 69 6e 61 6c 20 70 61 72 61 6d 65 74 65   xFinal paramete
23e30 72 73 2e 20 41 6e 20 61 67 67 72 65 67 61 74 65  rs. An aggregate
23e40 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65   SQL function re
23e50 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d  quires an implem
23e60 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 78  entation.** of x
23e70 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 20  Step and xFinal 
23e80 61 6e 64 20 4e 55 4c 4c 20 73 68 6f 75 6c 64 20  and NULL should 
23e90 62 65 20 70 61 73 73 65 64 20 66 6f 72 20 78 46  be passed for xF
23ea0 75 6e 63 2e 20 54 6f 20 64 65 6c 65 74 65 20 61  unc. To delete a
23eb0 6e 0a 2a 2a 20 65 78 69 73 74 69 6e 67 20 53 51  n.** existing SQ
23ec0 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67  L function or ag
23ed0 67 72 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55  gregate, pass NU
23ee0 4c 4c 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 65  LL for all three
23ef0 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c   function.** cal
23f00 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49 74 20  lback..**.** It 
23f10 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20  is permitted to 
23f20 72 65 67 69 73 74 65 72 20 6d 75 6c 74 69 70 6c  register multipl
23f30 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
23f40 73 20 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a  s of the same.**
23f50 20 66 75 6e 63 74 69 6f 6e 73 20 77 69 74 68 20   functions with 
23f60 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75  the same name bu
23f70 74 20 77 69 74 68 20 65 69 74 68 65 72 20 64 69  t with either di
23f80 66 66 65 72 69 6e 67 20 6e 75 6d 62 65 72 73 20  ffering numbers 
23f90 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20  of.** arguments 
23fa0 6f 72 20 64 69 66 66 65 72 69 6e 67 20 70 65 72  or differing per
23fb0 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f  ferred text enco
23fc0 64 69 6e 67 73 2e 20 20 53 51 4c 69 74 65 20 77  dings.  SQLite w
23fd0 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20 69  ill use.** the i
23fe0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 6f  mplementation mo
23ff0 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68  st closely match
24000 65 73 20 74 68 65 20 77 61 79 20 69 6e 20 77 68  es the way in wh
24010 69 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66  ich the.** SQL f
24020 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64 2e  unction is used.
24030 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
24040 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 30 33  S:.**.** {F16103
24050 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
24060 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
24070 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 62 65  ()] interface be
24080 68 61 76 65 73 20 65 78 61 63 74 6c 79 0a 2a 2a  haves exactly.**
24090 20 20 20 20 20 20 20 20 20 20 6c 69 6b 65 20 5b            like [
240a0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
240b0 75 6e 63 74 69 6f 6e 28 29 5d 20 69 6e 20 65 76  unction()] in ev
240c0 65 72 79 20 77 61 79 20 65 78 63 65 70 74 20 74  ery way except t
240d0 68 61 74 20 69 74 0a 2a 2a 20 20 20 20 20 20 20  hat it.**       
240e0 20 20 20 69 6e 74 65 72 70 72 65 74 73 20 74 68     interprets th
240f0 65 20 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 20  e zFunctionName 
24100 61 72 67 75 6d 65 6e 74 20 61 73 0a 2a 2a 20 20  argument as.**  
24110 20 20 20 20 20 20 20 20 7a 65 72 6f 2d 74 65 72          zero-ter
24120 6d 69 6e 61 74 65 64 20 55 54 46 2d 31 36 20 6e  minated UTF-16 n
24130 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
24140 20 69 6e 73 74 65 61 64 20 6f 66 20 61 73 20 61   instead of as a
24150 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72  .**          zer
24160 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
24170 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 30  -8..**.** {F1610
24180 36 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20  6} A successful 
24190 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a  invocation of.**
241a0 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 73            the [s
241b0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
241c0 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 2e  nction(D,X,N,E,.
241d0 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  ..)] interface r
241e0 65 67 69 73 74 65 72 73 0a 2a 2a 20 20 20 20 20  egisters.**     
241f0 20 20 20 20 20 6f 72 20 72 65 70 6c 61 63 65 73       or replaces
24200 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
24210 6f 6e 73 20 69 6e 20 5b 64 61 74 61 62 61 73 65  ons in [database
24220 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a   connection] D.*
24230 2a 20 20 20 20 20 20 20 20 20 20 75 73 65 64 20  *          used 
24240 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65  to implement the
24250 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6e 61   SQL function na
24260 6d 65 64 20 58 20 77 69 74 68 20 4e 20 70 61 72  med X with N par
24270 61 6d 65 74 65 72 73 0a 2a 2a 20 20 20 20 20 20  ameters.**      
24280 20 20 20 20 61 6e 64 20 68 61 76 69 6e 67 20 61      and having a
24290 20 70 65 72 66 65 72 72 65 64 20 74 65 78 74 20   perferred text 
242a0 65 6e 63 6f 64 69 6e 67 20 6f 66 20 45 2e 0a 2a  encoding of E..*
242b0 2a 0a 2a 2a 20 7b 46 31 36 31 30 39 7d 20 41 20  *.** {F16109} A 
242c0 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20  successful call 
242d0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  to [sqlite3_crea
242e0 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c  te_function(D,X,
242f0 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 0a 2a 2a  N,E,P,F,S,L)].**
24300 20 20 20 20 20 20 20 20 20 20 72 65 70 6c 61 63            replac
24310 65 73 20 74 68 65 20 50 2c 20 46 2c 20 53 2c 20  es the P, F, S, 
24320 61 6e 64 20 4c 20 76 61 6c 75 65 73 20 66 72 6f  and L values fro
24330 6d 20 61 6e 79 20 70 72 69 6f 72 20 63 61 6c 6c  m any prior call
24340 73 20 77 69 74 68 0a 2a 2a 20 20 20 20 20 20 20  s with.**       
24350 20 20 20 74 68 65 20 73 61 6d 65 20 44 2c 20 58     the same D, X
24360 2c 20 4e 2c 20 61 6e 64 20 45 20 76 61 6c 75 65  , N, and E value
24370 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 31 32  s..**.** {F16112
24380 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
24390 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44  reate_function(D
243a0 2c 58 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61  ,X,...)] interfa
243b0 63 65 20 66 61 69 6c 73 20 77 69 74 68 0a 2a 2a  ce fails with.**
243c0 20 20 20 20 20 20 20 20 20 20 61 20 72 65 74 75            a retu
243d0 72 6e 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49  rn code of [SQLI
243e0 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 74 68 65  TE_ERROR] if the
243f0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6e 61   SQL function na
24400 6d 65 20 58 20 69 73 0a 2a 2a 20 20 20 20 20 20  me X is.**      
24410 20 20 20 20 6c 6f 6e 67 65 72 20 74 68 61 6e 20      longer than 
24420 32 35 35 20 62 79 74 65 73 20 65 78 63 6c 75 73  255 bytes exclus
24430 69 76 65 20 6f 66 20 74 68 65 20 7a 65 72 6f 20  ive of the zero 
24440 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a  terminator..**.*
24450 2a 20 7b 46 31 36 31 31 38 7d 20 45 69 74 68 65  * {F16118} Eithe
24460 72 20 46 20 6d 75 73 74 20 62 65 20 4e 55 4c 4c  r F must be NULL
24470 20 61 6e 64 20 53 20 61 6e 64 20 4c 20 61 72 65   and S and L are
24480 20 6e 6f 6e 2d 4e 55 4c 4c 20 6f 72 20 65 6c 73   non-NULL or els
24490 65 20 46 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  e F.**          
244a0 69 73 20 6e 6f 6e 2d 4e 55 4c 4c 20 61 6e 64 20  is non-NULL and 
244b0 53 20 61 6e 64 20 4c 20 61 72 65 20 4e 55 4c 4c  S and L are NULL
244c0 2c 20 6f 74 68 65 72 77 69 73 65 0a 2a 2a 20 20  , otherwise.**  
244d0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
244e0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
244f0 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c  (D,X,N,E,P,F,S,L
24500 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  )] returns [SQLI
24510 54 45 5f 45 52 52 4f 52 5d 2e 0a 2a 2a 0a 2a 2a  TE_ERROR]..**.**
24520 20 7b 46 31 36 31 32 31 7d 20 54 68 65 20 5b 73   {F16121} The [s
24530 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
24540 6e 63 74 69 6f 6e 28 44 2c 2e 2e 2e 29 5d 20 69  nction(D,...)] i
24550 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73 20 77  nterface fails w
24560 69 74 68 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20  ith an.**       
24570 20 20 20 65 72 72 6f 72 20 63 6f 64 65 20 6f 66     error code of
24580 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 69   [SQLITE_BUSY] i
24590 66 20 74 68 65 72 65 20 65 78 69 73 74 20 5b 70  f there exist [p
245a0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
245b0 74 73 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ts].**          
245c0 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
245d0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
245e0 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a  nnection] D..**.
245f0 2a 2a 20 7b 46 31 36 31 32 34 7d 20 54 68 65 20  ** {F16124} The 
24600 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
24610 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 2e  function(D,X,N,.
24620 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 66  ..)] interface f
24630 61 69 6c 73 20 77 69 74 68 20 61 6e 0a 2a 2a 20  ails with an.** 
24640 20 20 20 20 20 20 20 20 20 65 72 72 6f 72 20 63           error c
24650 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 45  ode of [SQLITE_E
24660 52 52 4f 52 5d 20 69 66 20 70 61 72 61 6d 65 74  RROR] if paramet
24670 65 72 20 4e 20 28 73 70 65 63 69 66 79 69 6e 67  er N (specifying
24680 20 74 68 65 20 6e 75 6d 62 65 72 0a 2a 2a 20 20   the number.**  
24690 20 20 20 20 20 20 20 20 6f 66 20 61 72 67 75 6d          of argum
246a0 65 6e 74 73 20 74 6f 20 74 68 65 20 53 51 4c 20  ents to the SQL 
246b0 66 75 6e 63 74 69 6f 6e 20 62 65 69 6e 67 20 72  function being r
246c0 65 67 69 73 74 65 72 65 64 29 20 69 73 20 6c 65  egistered) is le
246d0 73 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  ss.**          t
246e0 68 61 6e 20 2d 31 20 6f 72 20 67 72 65 61 74 65  han -1 or greate
246f0 72 20 74 68 61 6e 20 31 32 37 2e 0a 2a 2a 0a 2a  r than 127..**.*
24700 2a 20 7b 46 31 36 31 32 37 7d 20 57 68 65 6e 20  * {F16127} When 
24710 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  N is non-negativ
24720 65 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  e, the [sqlite3_
24730 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
24740 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20  D,X,N,...)].**  
24750 20 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 63          interfac
24760 65 20 63 61 75 73 65 73 20 63 61 6c 6c 62 61 63  e causes callbac
24770 6b 73 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64  ks to be invoked
24780 20 66 6f 72 20 74 68 65 20 53 51 4c 20 66 75 6e   for the SQL fun
24790 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20  ction.**        
247a0 20 20 6e 61 6d 65 64 20 58 20 77 68 65 6e 20 74    named X when t
247b0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67  he number of arg
247c0 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 53 51  uments to the SQ
247d0 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a  L function is.**
247e0 20 20 20 20 20 20 20 20 20 20 65 78 61 63 74 6c            exactl
247f0 79 20 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31  y N..**.** {F161
24800 33 30 7d 20 57 68 65 6e 20 4e 20 69 73 20 2d 31  30} When N is -1
24810 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  , the [sqlite3_c
24820 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44  reate_function(D
24830 2c 58 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20  ,X,N,...)].**   
24840 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65         interface
24850 20 63 61 75 73 65 73 20 63 61 6c 6c 62 61 63 6b   causes callback
24860 73 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20  s to be invoked 
24870 66 6f 72 20 74 68 65 20 53 51 4c 20 66 75 6e 63  for the SQL func
24880 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  tion.**         
24890 20 6e 61 6d 65 64 20 58 20 77 69 74 68 20 61 6e   named X with an
248a0 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75  y number of argu
248b0 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  ments..**.** {F1
248c0 36 31 33 33 7d 20 57 68 65 6e 20 63 61 6c 6c 73  6133} When calls
248d0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65   to [sqlite3_cre
248e0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58  ate_function(D,X
248f0 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20  ,N,...)].**     
24900 20 20 20 20 20 73 70 65 63 69 66 79 20 6d 75 6c       specify mul
24910 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  tiple implementa
24920 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d  tions of the sam
24930 65 20 66 75 6e 63 74 69 6f 6e 20 58 0a 2a 2a 20  e function X.** 
24940 20 20 20 20 20 20 20 20 20 61 6e 64 20 77 68 65           and whe
24950 6e 20 6f 6e 65 20 69 6d 70 6c 65 6d 65 6e 74 61  n one implementa
24960 74 69 6f 6e 20 68 61 73 20 4e 3e 3d 30 20 61 6e  tion has N>=0 an
24970 64 20 74 68 65 20 6f 74 68 65 72 20 68 61 73 20  d the other has 
24980 4e 3d 28 2d 31 29 0a 2a 2a 20 20 20 20 20 20 20  N=(-1).**       
24990 20 20 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74     the implement
249a0 61 74 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e  ation with a non
249b0 2d 7a 65 72 6f 20 4e 20 69 73 20 70 72 65 66 65  -zero N is prefe
249c0 72 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  rred..**.** {F16
249d0 31 33 36 7d 20 57 68 65 6e 20 63 61 6c 6c 73 20  136} When calls 
249e0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  to [sqlite3_crea
249f0 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c  te_function(D,X,
24a00 4e 2c 45 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20  N,E,...)].**    
24a10 20 20 20 20 20 20 73 70 65 63 69 66 79 20 6d 75        specify mu
24a20 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  ltiple implement
24a30 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
24a40 6d 65 20 66 75 6e 63 74 69 6f 6e 20 58 20 77 69  me function X wi
24a50 74 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  th.**          t
24a60 68 65 20 73 61 6d 65 20 6e 75 6d 62 65 72 20 6f  he same number o
24a70 66 20 61 72 67 75 6d 65 6e 74 73 20 4e 20 62 75  f arguments N bu
24a80 74 20 77 69 74 68 20 64 69 66 66 65 72 65 6e 74  t with different
24a90 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 6e 63  .**          enc
24aa0 6f 64 69 6e 67 73 20 45 2c 20 74 68 65 6e 20 74  odings E, then t
24ab0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
24ac0 6e 20 77 68 65 72 65 20 45 20 6d 61 74 63 68 65  n where E matche
24ad0 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
24ae0 20 20 64 61 74 61 62 61 73 65 20 65 6e 63 6f 64    database encod
24af0 69 6e 67 20 69 73 20 70 72 65 66 65 72 72 65 64  ing is preferred
24b00 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 33 39 7d  ..**.** {F16139}
24b10 20 46 6f 72 20 61 6e 20 61 67 67 72 65 67 61 74   For an aggregat
24b20 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63  e SQL function c
24b30 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20  reated using.** 
24b40 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
24b50 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
24b60 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c 30 2c 53 2c  n(D,X,N,E,P,0,S,
24b70 4c 29 5d 20 74 68 65 20 66 69 6e 69 61 6c 69 7a  L)] the finializ
24b80 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  er.**          f
24b90 75 6e 63 74 69 6f 6e 20 4c 20 77 69 6c 6c 20 61  unction L will a
24ba0 6c 77 61 79 73 20 62 65 20 69 6e 76 6f 6b 65 64  lways be invoked
24bb0 20 65 78 61 63 74 6c 79 20 6f 6e 63 65 20 69 66   exactly once if
24bc0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
24bd0 20 73 74 65 70 20 66 75 6e 63 74 69 6f 6e 20 53   step function S
24be0 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f   is called one o
24bf0 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2f  r more times..*/
24c00 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65  .int sqlite3_cre
24c10 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20  ate_function(.  
24c20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63  sqlite3 *db,.  c
24c30 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63  onst char *zFunc
24c40 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20  tionName,.  int 
24c50 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78  nArg,.  int eTex
24c60 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41  tRep,.  void *pA
24c70 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75  pp,.  void (*xFu
24c80 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  nc)(sqlite3_cont
24c90 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
24ca0 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
24cb0 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74  d (*xStep)(sqlit
24cc0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
24cd0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
24ce0 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61  ,.  void (*xFina
24cf0 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  l)(sqlite3_conte
24d00 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  xt*).);.int sqli
24d10 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
24d20 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33  ion16(.  sqlite3
24d30 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 76 6f   *db,.  const vo
24d40 69 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d  id *zFunctionNam
24d50 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20  e,.  int nArg,. 
24d60 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20   int eTextRep,. 
24d70 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76   void *pApp,.  v
24d80 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c  oid (*xFunc)(sql
24d90 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
24da0 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
24db0 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74  *),.  void (*xSt
24dc0 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ep)(sqlite3_cont
24dd0 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
24de0 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
24df0 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69  d (*xFinal)(sqli
24e00 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b  te3_context*).);
24e10 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
24e20 3a 20 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 73  : Text Encodings
24e30 20 7b 46 31 30 32 36 37 7d 0a 2a 2a 0a 2a 2a 20   {F10267}.**.** 
24e40 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 20 64  These constant d
24e50 65 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63 6f  efine integer co
24e60 64 65 73 20 74 68 61 74 20 72 65 70 72 65 73 65  des that represe
24e70 6e 74 20 74 68 65 20 76 61 72 69 6f 75 73 0a 2a  nt the various.*
24e80 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73  * text encodings
24e90 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51   supported by SQ
24ea0 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  Lite..*/.#define
24eb0 20 53 51 4c 49 54 45 5f 55 54 46 38 20 20 20 20   SQLITE_UTF8    
24ec0 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
24ed0 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 20   SQLITE_UTF16LE 
24ee0 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65         2.#define
24ef0 20 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20   SQLITE_UTF16BE 
24f00 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65         3.#define
24f10 20 53 51 4c 49 54 45 5f 55 54 46 31 36 20 20 20   SQLITE_UTF16   
24f20 20 20 20 20 20 20 20 34 20 20 20 20 2f 2a 20 55         4    /* U
24f30 73 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  se native byte o
24f40 72 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rder */.#define 
24f50 53 51 4c 49 54 45 5f 41 4e 59 20 20 20 20 20 20  SQLITE_ANY      
24f60 20 20 20 20 20 20 35 20 20 20 20 2f 2a 20 73 71        5    /* sq
24f70 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
24f80 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64  ction only */.#d
24f90 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46  efine SQLITE_UTF
24fa0 31 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 20 20  16_ALIGNED  8   
24fb0 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61   /* sqlite3_crea
24fc0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c  te_collation onl
24fd0 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  y */../*.** CAPI
24fe0 33 52 45 46 3a 20 4f 62 73 6f 6c 65 74 65 20 46  3REF: Obsolete F
24ff0 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54  unctions.**.** T
25000 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61  hese functions a
25010 72 65 20 61 6c 6c 20 6e 6f 77 20 6f 62 73 6f 6c  re all now obsol
25020 65 74 65 2e 20 20 49 6e 20 6f 72 64 65 72 20 74  ete.  In order t
25030 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61  o maintain.** ba
25040 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
25050 69 6c 69 74 79 20 77 69 74 68 20 6f 6c 64 65 72  ility with older
25060 20 63 6f 64 65 2c 20 77 65 20 63 6f 6e 74 69 6e   code, we contin
25070 75 65 20 74 6f 20 73 75 70 70 6f 72 74 0a 2a 2a  ue to support.**
25080 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
25090 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 20  .  However, new 
250a0 64 65 76 65 6c 6f 70 6d 65 6e 74 20 70 72 6f 6a  development proj
250b0 65 63 74 73 20 73 68 6f 75 6c 64 20 61 76 6f 69  ects should avoi
250c0 64 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20  d.** the use of 
250d0 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e  these functions.
250e0 20 20 54 6f 20 68 65 6c 70 20 65 6e 63 6f 75 72    To help encour
250f0 61 67 65 20 70 65 6f 70 6c 65 20 74 6f 20 61 76  age people to av
25100 6f 69 64 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65  oid.** using the
25110 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20 77 65  se functions, we
25120 20 61 72 65 20 6e 6f 74 20 67 6f 69 6e 67 20 74   are not going t
25130 6f 20 74 65 6c 6c 20 79 6f 75 20 77 61 6e 74 20  o tell you want 
25140 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 69 6e 74 20  they do..*/.int 
25150 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
25160 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  e_count(sqlite3_
25170 63 6f 6e 74 65 78 74 2a 29 3b 0a 69 6e 74 20 73  context*);.int s
25180 71 6c 69 74 65 33 5f 65 78 70 69 72 65 64 28 73  qlite3_expired(s
25190 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 69  qlite3_stmt*);.i
251a0 6e 74 20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73  nt sqlite3_trans
251b0 66 65 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c  fer_bindings(sql
251c0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69  ite3_stmt*, sqli
251d0 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 69 6e 74 20  te3_stmt*);.int 
251e0 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72  sqlite3_global_r
251f0 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 76 6f  ecover(void);.vo
25200 69 64 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61  id sqlite3_threa
25210 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b  d_cleanup(void);
25220 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d  .int sqlite3_mem
25230 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a  ory_alarm(void(*
25240 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f  )(void*,sqlite3_
25250 69 6e 74 36 34 2c 69 6e 74 29 2c 76 6f 69 64 2a  int64,int),void*
25260 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b  ,sqlite3_int64);
25270 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
25280 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c 20  : Obtaining SQL 
25290 46 75 6e 63 74 69 6f 6e 20 50 61 72 61 6d 65 74  Function Paramet
252a0 65 72 20 56 61 6c 75 65 73 20 7b 46 31 35 31 30  er Values {F1510
252b0 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c  0}.**.** The C-l
252c0 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e  anguage implemen
252d0 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75  tation of SQL fu
252e0 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72  nctions and aggr
252f0 65 67 61 74 65 73 20 75 73 65 73 0a 2a 2a 20 74  egates uses.** t
25300 68 69 73 20 73 65 74 20 6f 66 20 69 6e 74 65 72  his set of inter
25310 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20 74 6f  face routines to
25320 20 61 63 63 65 73 73 20 74 68 65 20 70 61 72 61   access the para
25330 6d 65 74 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a  meter values on.
25340 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  ** the function 
25350 6f 72 20 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a  or aggregate..**
25360 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 28 66  .** The xFunc (f
25370 6f 72 20 73 63 61 6c 61 72 20 66 75 6e 63 74 69  or scalar functi
25380 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 20 28 66  ons) or xStep (f
25390 6f 72 20 61 67 67 72 65 67 61 74 65 73 29 20 70  or aggregates) p
253a0 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20  arameters.** to 
253b0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
253c0 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20  function()] and 
253d0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
253e0 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a  function16()].**
253f0 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b   define callback
25400 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  s that implement
25410 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
25420 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65  ns and aggregate
25430 73 2e 0a 2a 2a 20 54 68 65 20 34 74 68 20 70 61  s..** The 4th pa
25440 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 73 65  rameter to these
25450 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e   callbacks is an
25460 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65   array of pointe
25470 72 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  rs to.** [sqlite
25480 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73  3_value] objects
25490 2e 20 20 54 68 65 72 65 20 69 73 20 6f 6e 65 20  .  There is one 
254a0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
254b0 6f 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61  object for.** ea
254c0 63 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  ch parameter to 
254d0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
254e0 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  .  These routine
254f0 73 20 61 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a  s are used to.**
25500 20 65 78 74 72 61 63 74 20 76 61 6c 75 65 73 20   extract values 
25510 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65  from the [sqlite
25520 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73  3_value] objects
25530 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
25540 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74  utines work just
25550 20 6c 69 6b 65 20 74 68 65 20 63 6f 72 72 65 73   like the corres
25560 70 6f 6e 64 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c  ponding .** [sql
25570 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
25580 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d   | sqlite3_colum
25590 6e 5f 2a 20 72 6f 75 74 69 6e 65 73 5d 20 65 78  n_* routines] ex
255a0 63 65 70 74 20 74 68 61 74 20 0a 2a 2a 20 74 68  cept that .** th
255b0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 61 6b  ese routines tak
255c0 65 20 61 20 73 69 6e 67 6c 65 20 5b 73 71 6c 69  e a single [sqli
255d0 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70 6f 69 6e  te3_value*] poin
255e0 74 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f  ter instead.** o
255f0 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74  f an [sqlite3_st
25600 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64  mt*] pointer and
25610 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c 75   an integer colu
25620 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a  mn number..**.**
25630 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c   The sqlite3_val
25640 75 65 5f 74 65 78 74 31 36 28 29 20 69 6e 74 65  ue_text16() inte
25650 72 66 61 63 65 20 65 78 74 72 61 63 74 73 20 61  rface extracts a
25660 20 55 54 46 31 36 20 73 74 72 69 6e 67 0a 2a 2a   UTF16 string.**
25670 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
25680 79 74 65 2d 6f 72 64 65 72 20 6f 66 20 74 68 65  yte-order of the
25690 20 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20 20   host machine.  
256a0 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  The.** sqlite3_v
256b0 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29 20  alue_text16be() 
256c0 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  and sqlite3_valu
256d0 65 5f 74 65 78 74 31 36 6c 65 28 29 20 69 6e 74  e_text16le() int
256e0 65 72 66 61 63 65 73 0a 2a 2a 20 65 78 74 72 61  erfaces.** extra
256f0 63 74 20 55 54 46 31 36 20 73 74 72 69 6e 67 73  ct UTF16 strings
25700 20 61 73 20 62 69 67 2d 65 6e 64 69 61 6e 20 61   as big-endian a
25710 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e  nd little-endian
25720 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a   respectively..*
25730 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
25740 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74  _value_numeric_t
25750 79 70 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ype() interface 
25760 61 74 74 65 6d 70 74 73 20 74 6f 20 61 70 70 6c  attempts to appl
25770 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66 66  y.** numeric aff
25780 69 6e 69 74 79 20 74 6f 20 74 68 65 20 76 61 6c  inity to the val
25790 75 65 2e 20 20 54 68 69 73 20 6d 65 61 6e 73 20  ue.  This means 
257a0 74 68 61 74 20 61 6e 20 61 74 74 65 6d 70 74 20  that an attempt 
257b0 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f  is.** made to co
257c0 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20  nvert the value 
257d0 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72  to an integer or
257e0 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e   floating point.
257f0 20 20 49 66 0a 2a 2a 20 73 75 63 68 20 61 20 63    If.** such a c
25800 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 6f 73  onversion is pos
25810 73 69 62 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f  sible without lo
25820 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f  ss of informatio
25830 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77  n (in other.** w
25840 6f 72 64 73 20 69 66 20 74 68 65 20 76 61 6c 75  ords if the valu
25850 65 20 69 73 20 61 20 73 74 72 69 6e 67 20 74 68  e is a string th
25860 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20  at looks like a 
25870 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20  number).** then 
25880 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69  the conversion i
25890 73 20 64 6f 6e 65 2e 20 20 4f 74 68 65 72 77 69  s done.  Otherwi
258a0 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e  se no conversion
258b0 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20 0a 2a   occurs.  The .*
258c0 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  * [SQLITE_INTEGE
258d0 52 20 7c 20 64 61 74 61 74 79 70 65 5d 20 61 66  R | datatype] af
258e0 74 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69  ter conversion i
258f0 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
25900 2a 20 50 6c 65 61 73 65 20 70 61 79 20 70 61 72  * Please pay par
25910 74 69 63 75 6c 61 72 20 61 74 74 65 6e 74 69 6f  ticular attentio
25920 6e 20 74 6f 20 74 68 65 20 66 61 63 74 20 74 68  n to the fact th
25930 61 74 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74  at the pointer t
25940 68 61 74 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e  hat.** is return
25950 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
25960 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20  _value_blob()], 
25970 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
25980 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73  ext()], or.** [s
25990 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
259a0 74 31 36 28 29 5d 20 63 61 6e 20 62 65 20 69 6e  t16()] can be in
259b0 76 61 6c 69 64 61 74 65 64 20 62 79 20 61 20 73  validated by a s
259c0 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74  ubsequent call t
259d0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61  o.** [sqlite3_va
259e0 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73  lue_bytes()], [s
259f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
25a00 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65  es16()], [sqlite
25a10 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c  3_value_text()],
25a20 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
25a30 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 2e  value_text16()].
25a40 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72    .**.** These r
25a50 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20  outines must be 
25a60 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
25a70 73 61 6d 65 20 74 68 72 65 61 64 20 61 73 0a 2a  same thread as.*
25a80 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  * the SQL functi
25a90 6f 6e 20 74 68 61 74 20 73 75 70 70 6c 69 65 64  on that supplied
25aa0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c   the sqlite3_val
25ab0 75 65 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 0a  ue* parameters..
25ac0 2a 2a 20 4f 72 2c 20 69 66 20 74 68 65 20 73 71  ** Or, if the sq
25ad0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 20 61 72 67  lite3_value* arg
25ae0 75 6d 65 6e 74 20 63 6f 6d 65 73 20 66 72 6f 6d  ument comes from
25af0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
25b00 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 0a 2a 2a  lumn_value()].**
25b10 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 6e   interface, then
25b20 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
25b30 73 68 6f 75 6c 64 20 62 65 20 63 61 6c 6c 65 64  should be called
25b40 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74   from the same t
25b50 68 72 65 61 64 0a 2a 2a 20 74 68 61 74 20 72 61  hread.** that ra
25b60 6e 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  n [sqlite3_colum
25b70 6e 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 0a 2a  n_value()]..**.*
25b80 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
25b90 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31 30 33 7d 20  .**.** {F15103} 
25ba0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  The [sqlite3_val
25bb0 75 65 5f 62 6c 6f 62 28 56 29 5d 20 69 6e 74 65  ue_blob(V)] inte
25bc0 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74  rface converts t
25bd0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
25be0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
25bf0 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20 62  bject V into a b
25c00 6c 6f 62 20 61 6e 64 20 74 68 65 6e 20 72 65 74  lob and then ret
25c10 75 72 6e 73 20 61 0a 2a 2a 20 20 20 20 20 20 20  urns a.**       
25c20 20 20 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68     pointer to th
25c30 65 20 63 6f 6e 76 65 72 74 65 64 20 76 61 6c 75  e converted valu
25c40 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31 30 36  e..**.** {F15106
25c50 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  } The [sqlite3_v
25c60 61 6c 75 65 5f 62 79 74 65 73 28 56 29 5d 20 69  alue_bytes(V)] i
25c70 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
25c80 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
25c90 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
25ca0 20 69 6e 20 74 68 65 20 62 6c 6f 62 20 6f 72 20   in the blob or 
25cb0 73 74 72 69 6e 67 20 28 65 78 63 6c 75 73 69 76  string (exclusiv
25cc0 65 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20  e of the.**     
25cd0 20 20 20 20 20 7a 65 72 6f 20 74 65 72 6d 69 6e       zero termin
25ce0 61 74 6f 72 20 6f 6e 20 74 68 65 20 73 74 72 69  ator on the stri
25cf0 6e 67 29 20 74 68 61 74 20 77 61 73 20 72 65 74  ng) that was ret
25d00 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20  urned by the.** 
25d10 20 20 20 20 20 20 20 20 20 6d 6f 73 74 20 72 65           most re
25d20 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  cent call to [sq
25d30 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62  lite3_value_blob
25d40 28 56 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20  (V)] or.**      
25d50 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c      [sqlite3_val
25d60 75 65 5f 74 65 78 74 28 56 29 5d 2e 0a 2a 2a 0a  ue_text(V)]..**.
25d70 2a 2a 20 7b 46 31 35 31 30 39 7d 20 54 68 65 20  ** {F15109} The 
25d80 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
25d90 79 74 65 73 31 36 28 56 29 5d 20 69 6e 74 65 72  ytes16(V)] inter
25da0 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
25db0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 75 6d  .**          num
25dc0 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
25dd0 74 68 65 20 73 74 72 69 6e 67 20 28 65 78 63 6c  the string (excl
25de0 75 73 69 76 65 20 6f 66 20 74 68 65 0a 2a 2a 20  usive of the.** 
25df0 20 20 20 20 20 20 20 20 20 7a 65 72 6f 20 74 65           zero te
25e00 72 6d 69 6e 61 74 6f 72 20 6f 6e 20 74 68 65 20  rminator on the 
25e10 73 74 72 69 6e 67 29 20 74 68 61 74 20 77 61 73  string) that was
25e20 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
25e30 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 6f 73  .**          mos
25e40 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f  t recent call to
25e50 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
25e60 74 65 78 74 31 36 28 56 29 5d 2c 0a 2a 2a 20 20  text16(V)],.**  
25e70 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
25e80 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28  _value_text16be(
25e90 56 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33  V)], or [sqlite3
25ea0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28  _value_text16le(
25eb0 56 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31  V)]..**.** {F151
25ec0 31 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  12} The [sqlite3
25ed0 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 56 29  _value_double(V)
25ee0 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76  ] interface conv
25ef0 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  erts the.**     
25f00 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 76 61       [sqlite3_va
25f10 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e  lue] object V in
25f20 74 6f 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f  to a floating po
25f30 69 6e 74 20 76 61 6c 75 65 20 61 6e 64 0a 2a 2a  int value and.**
25f40 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e            return
25f50 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 61 74  s a copy of that
25f60 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46   value..**.** {F
25f70 31 35 31 31 35 7d 20 54 68 65 20 5b 73 71 6c 69  15115} The [sqli
25f80 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 56 29  te3_value_int(V)
25f90 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76  ] interface conv
25fa0 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  erts the.**     
25fb0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 76 61       [sqlite3_va
25fc0 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e  lue] object V in
25fd0 74 6f 20 61 20 36 34 2d 62 69 74 20 73 69 67 6e  to a 64-bit sign
25fe0 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 0a 2a  ed integer and.*
25ff0 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72  *          retur
26000 6e 73 20 74 68 65 20 6c 6f 77 65 72 20 33 32 20  ns the lower 32 
26010 62 69 74 73 20 6f 66 20 74 68 61 74 20 69 6e 74  bits of that int
26020 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35  eger..**.** {F15
26030 31 31 38 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  118} The [sqlite
26040 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28 56 29  3_value_int64(V)
26050 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76  ] interface conv
26060 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  erts the.**     
26070 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 76 61       [sqlite3_va
26080 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e  lue] object V in
26090 74 6f 20 61 20 36 34 2d 62 69 74 20 73 69 67 6e  to a 64-bit sign
260a0 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 0a 2a  ed integer and.*
260b0 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72  *          retur
260c0 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 61  ns a copy of tha
260d0 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a  t integer..**.**
260e0 20 7b 46 31 35 31 32 31 7d 20 54 68 65 20 5b 73   {F15121} The [s
260f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
26100 74 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20  t(V)] interface 
26110 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20  converts the.** 
26120 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
26130 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
26140 56 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65  V into a zero-te
26150 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 0a  rminated UTF-8 .
26160 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 72 69  **          stri
26170 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61  ng and returns a
26180 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74   pointer to that
26190 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b   string..**.** {
261a0 46 31 35 31 32 34 7d 20 54 68 65 20 5b 73 71 6c  F15124} The [sql
261b0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
261c0 36 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20  6(V)] interface 
261d0 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20  converts the.** 
261e0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
261f0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
26200 56 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65  V into a zero-te
26210 72 6d 69 6e 61 74 65 64 20 32 2d 62 79 74 65 0a  rminated 2-byte.
26220 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c 69 67  **          alig
26230 6e 65 64 20 55 54 46 2d 31 36 20 6e 61 74 69 76  ned UTF-16 nativ
26240 65 20 62 79 74 65 20 6f 72 64 65 72 0a 2a 2a 20  e byte order.** 
26250 20 20 20 20 20 20 20 20 20 73 74 72 69 6e 67 20           string 
26260 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f  and returns a po
26270 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20 73 74  inter to that st
26280 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35  ring..**.** {F15
26290 31 32 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  127} The [sqlite
262a0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65  3_value_text16be
262b0 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  (V)] interface c
262c0 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20  onverts the.**  
262d0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
262e0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56  _value] object V
262f0 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72   into a zero-ter
26300 6d 69 6e 61 74 65 64 20 32 2d 62 79 74 65 0a 2a  minated 2-byte.*
26310 2a 20 20 20 20 20 20 20 20 20 20 61 6c 69 67 6e  *          align
26320 65 64 20 55 54 46 2d 31 36 20 62 69 67 2d 65 6e  ed UTF-16 big-en
26330 64 69 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  dian.**         
26340 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75   string and retu
26350 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
26360 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a   that string..**
26370 0a 2a 2a 20 7b 46 31 35 31 33 30 7d 20 54 68 65  .** {F15130} The
26380 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
26390 74 65 78 74 31 36 6c 65 28 56 29 5d 20 69 6e 74  text16le(V)] int
263a0 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20  erface converts 
263b0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
263c0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
263d0 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20  object V into a 
263e0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
263f0 32 2d 62 79 74 65 0a 2a 2a 20 20 20 20 20 20 20  2-byte.**       
26400 20 20 20 61 6c 69 67 6e 65 64 20 55 54 46 2d 31     aligned UTF-1
26410 36 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 0a  6 little-endian.
26420 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 72 69  **          stri
26430 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61  ng and returns a
26440 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74   pointer to that
26450 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b   string..**.** {
26460 46 31 35 31 33 33 7d 20 54 68 65 20 5b 73 71 6c  F15133} The [sql
26470 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28  ite3_value_type(
26480 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  V)] interface re
26490 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20  turns.**        
264a0 20 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45    one of [SQLITE
264b0 5f 4e 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f  _NULL], [SQLITE_
264c0 49 4e 54 45 47 45 52 5d 2c 20 5b 53 51 4c 49 54  INTEGER], [SQLIT
264d0 45 5f 46 4c 4f 41 54 5d 2c 0a 2a 2a 20 20 20 20  E_FLOAT],.**    
264e0 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 54 45        [SQLITE_TE
264f0 58 54 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  XT], or [SQLITE_
26500 42 4c 4f 42 5d 20 61 73 20 61 70 70 72 6f 70 72  BLOB] as appropr
26510 69 61 74 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20  iate for.**     
26520 20 20 20 20 20 74 68 65 20 5b 73 71 6c 69 74 65       the [sqlite
26530 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
26540 56 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31 33 36  V..**.** {F15136
26550 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  } The [sqlite3_v
26560 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70  alue_numeric_typ
26570 65 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20  e(V)] interface 
26580 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 20 20 20 20  converts.**     
26590 20 20 20 20 20 74 68 65 20 5b 73 71 6c 69 74 65       the [sqlite
265a0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
265b0 56 20 69 6e 74 6f 20 65 69 74 68 65 72 20 61 6e  V into either an
265c0 20 69 6e 74 65 67 65 72 20 6f 72 0a 2a 2a 20 20   integer or.**  
265d0 20 20 20 20 20 20 20 20 61 20 66 6c 6f 61 74 69          a floati
265e0 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 69  ng point value i
265f0 66 20 69 74 20 63 61 6e 20 64 6f 20 73 6f 20 77  f it can do so w
26600 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 0a 2a  ithout loss of.*
26610 2a 20 20 20 20 20 20 20 20 20 20 69 6e 66 6f 72  *          infor
26620 6d 61 74 69 6f 6e 2c 20 61 6e 64 20 72 65 74 75  mation, and retu
26630 72 6e 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49  rns one of [SQLI
26640 54 45 5f 4e 55 4c 4c 5d 2c 0a 2a 2a 20 20 20 20  TE_NULL],.**    
26650 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 49 4e        [SQLITE_IN
26660 54 45 47 45 52 5d 2c 20 5b 53 51 4c 49 54 45 5f  TEGER], [SQLITE_
26670 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f  FLOAT], [SQLITE_
26680 54 45 58 54 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20  TEXT], or.**    
26690 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 42 4c        [SQLITE_BL
266a0 4f 42 5d 20 61 73 20 61 70 70 72 6f 70 72 69 61  OB] as appropria
266b0 74 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20  te for.**       
266c0 20 20 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f     the [sqlite3_
266d0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20  value] object V 
266e0 61 66 74 65 72 20 74 68 65 20 63 6f 6e 76 65 72  after the conver
266f0 73 69 6f 6e 20 61 74 74 65 6d 70 74 2e 0a 2a 2f  sion attempt..*/
26700 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
26710 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28  ite3_value_blob(
26720 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
26730 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  .int sqlite3_val
26740 75 65 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33  ue_bytes(sqlite3
26750 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
26760 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
26770 73 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  s16(sqlite3_valu
26780 65 2a 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69  e*);.double sqli
26790 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65  te3_value_double
267a0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
267b0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  ;.int sqlite3_va
267c0 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  lue_int(sqlite3_
267d0 76 61 6c 75 65 2a 29 3b 0a 73 71 6c 69 74 65 33  value*);.sqlite3
267e0 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 76  _int64 sqlite3_v
267f0 61 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c 69 74  alue_int64(sqlit
26800 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73  e3_value*);.cons
26810 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20  t unsigned char 
26820 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  *sqlite3_value_t
26830 65 78 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ext(sqlite3_valu
26840 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  e*);.const void 
26850 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  *sqlite3_value_t
26860 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 76 61  ext16(sqlite3_va
26870 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  lue*);.const voi
26880 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  d *sqlite3_value
26890 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65  _text16le(sqlite
268a0 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74  3_value*);.const
268b0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76   void *sqlite3_v
268c0 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 73 71  alue_text16be(sq
268d0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
268e0 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
268f0 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61  _type(sqlite3_va
26900 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
26910 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63  e3_value_numeric
26920 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61  _type(sqlite3_va
26930 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  lue*);../*.** CA
26940 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41  PI3REF: Obtain A
26950 67 67 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f  ggregate Functio
26960 6e 20 43 6f 6e 74 65 78 74 20 7b 46 31 36 32 31  n Context {F1621
26970 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6d 70  0}.**.** The imp
26980 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61  lementation of a
26990 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e  ggregate SQL fun
269a0 63 74 69 6f 6e 73 20 75 73 65 20 74 68 69 73 20  ctions use this 
269b0 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63  routine to alloc
269c0 61 74 65 0a 2a 2a 20 61 20 73 74 72 75 63 74 75  ate.** a structu
269d0 72 65 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 74  re for storing t
269e0 68 65 69 72 20 73 74 61 74 65 2e 20 20 0a 2a 2a  heir state.  .**
269f0 20 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20   The first time 
26a00 74 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72  the sqlite3_aggr
26a10 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20  egate_context() 
26a20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20 69 73  routine is.** is
26a30 20 63 61 6c 6c 65 64 20 66 6f 72 20 61 20 70 61   called for a pa
26a40 72 74 69 63 75 6c 61 72 20 61 67 67 72 65 67 61  rticular aggrega
26a50 74 65 2c 20 53 51 4c 69 74 65 20 61 6c 6c 6f 63  te, SQLite alloc
26a60 61 74 65 73 20 6e 42 79 74 65 73 20 6f 66 20 6d  ates nBytes of m
26a70 65 6d 6f 72 79 0a 2a 2a 20 7a 65 72 6f 73 20 74  emory.** zeros t
26a80 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20  hat memory, and 
26a90 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
26aa0 72 20 74 6f 20 69 74 2e 0a 2a 2a 20 4f 6e 20 73  r to it..** On s
26ab0 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71  econd and subseq
26ac0 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 73 71  uent calls to sq
26ad0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
26ae0 63 6f 6e 74 65 78 74 28 29 0a 2a 2a 20 66 6f 72  context().** for
26af0 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67   the same aggreg
26b00 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 64  ate function ind
26b10 65 78 2c 20 74 68 65 20 73 61 6d 65 20 62 75 66  ex, the same buf
26b20 66 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  fer is returned.
26b30 0a 2a 2a 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e  .** The implemen
26b40 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 74 68 65  tation.** of the
26b50 20 61 67 67 72 65 67 61 74 65 20 63 61 6e 20 75   aggregate can u
26b60 73 65 20 74 68 65 20 72 65 74 75 72 6e 65 64 20  se the returned 
26b70 62 75 66 66 65 72 20 74 6f 20 61 63 63 75 6d 75  buffer to accumu
26b80 6c 61 74 65 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a  late data..**.**
26b90 20 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69   SQLite automati
26ba0 63 61 6c 6c 79 20 66 72 65 65 73 20 74 68 65 20  cally frees the 
26bb0 61 6c 6c 6f 63 61 74 65 64 20 62 75 66 66 65 72  allocated buffer
26bc0 20 77 68 65 6e 20 74 68 65 20 61 67 67 72 65 67   when the aggreg
26bd0 61 74 65 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6e  ate.** query con
26be0 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  cludes..**.** Th
26bf0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
26c00 72 20 73 68 6f 75 6c 64 20 62 65 20 61 20 63 6f  r should be a co
26c10 70 79 20 6f 66 20 74 68 65 20 0a 2a 2a 20 5b 73  py of the .** [s
26c20 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c  qlite3_context |
26c30 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f   SQL function co
26c40 6e 74 65 78 74 5d 20 74 68 61 74 20 69 73 20 74  ntext] that is t
26c50 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61  he first.** para
26c60 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c  meter to the cal
26c70 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74 68  lback routine th
26c80 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68  at implements th
26c90 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 66  e aggregate.** f
26ca0 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  unction..**.** T
26cb0 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74  his routine must
26cc0 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
26cd0 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
26ce0 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20  in which.** the 
26cf0 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75  aggregate SQL fu
26d00 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
26d10 67 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  g..**.** INVARIA
26d20 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32  NTS:.**.** {F162
26d30 31 31 7d 20 54 68 65 20 66 69 72 73 74 20 69 6e  11} The first in
26d40 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c  vocation of [sql
26d50 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
26d60 6f 6e 74 65 78 74 28 43 2c 4e 29 5d 20 66 6f 72  ontext(C,N)] for
26d70 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 70  .**          a p
26d80 61 72 74 69 63 75 6c 61 72 20 69 6e 73 74 61 6e  articular instan
26d90 63 65 20 6f 66 20 61 6e 20 61 67 67 72 65 67 61  ce of an aggrega
26da0 74 65 20 66 75 6e 63 74 69 6f 6e 20 28 66 6f 72  te function (for
26db0 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a   a particular.**
26dc0 20 20 20 20 20 20 20 20 20 20 63 6f 6e 74 65 78            contex
26dd0 74 20 43 29 20 63 61 75 73 65 73 20 53 51 4c 69  t C) causes SQLi
26de0 74 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e  te to allocation
26df0 20 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f   N bytes of memo
26e00 72 79 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ry,.**          
26e10 7a 65 72 6f 20 74 68 61 74 20 6d 65 6d 6f 72 79  zero that memory
26e20 2c 20 61 6e 64 20 72 65 74 75 72 6e 20 61 20 70  , and return a p
26e30 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 61 6c  ointer to the al
26e40 6c 6f 63 61 74 69 6f 6e 65 64 0a 2a 2a 20 20 20  locationed.**   
26e50 20 20 20 20 20 20 20 6d 65 6d 6f 72 79 2e 0a 2a         memory..*
26e60 2a 0a 2a 2a 20 7b 46 31 36 32 31 33 7d 20 49 66  *.** {F16213} If
26e70 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
26e80 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  tion error occur
26e90 73 20 64 75 72 69 6e 67 0a 2a 2a 20 20 20 20 20  s during.**     
26ea0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 61 67       [sqlite3_ag
26eb0 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
26ec0 43 2c 4e 29 5d 20 74 68 65 6e 20 74 68 65 20 66  C,N)] then the f
26ed0 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
26ee0 30 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32 31 35  0..**.** {F16215
26ef0 7d 20 53 65 63 6f 6e 64 20 61 6e 64 20 73 75 62  } Second and sub
26f00 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69  sequent invocati
26f10 6f 6e 73 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20  ons of.**       
26f20 20 20 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72     [sqlite3_aggr
26f30 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c  egate_context(C,
26f40 4e 29 5d 20 66 6f 72 20 74 68 65 20 73 61 6d 65  N)] for the same
26f50 20 63 6f 6e 74 65 78 74 20 70 6f 69 6e 74 65 72   context pointer
26f60 20 43 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69   C.**          i
26f70 67 6e 6f 72 65 20 74 68 65 20 4e 20 70 61 72 61  gnore the N para
26f80 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e  meter and return
26f90 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
26fa0 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20  e same.**       
26fb0 20 20 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f     block of memo
26fc0 72 79 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  ry returned by t
26fd0 68 65 20 66 69 72 73 74 20 69 6e 76 6f 63 61 74  he first invocat
26fe0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32  ion..**.** {F162
26ff0 31 37 7d 20 54 68 65 20 6d 65 6d 6f 72 79 20 61  17} The memory a
27000 6c 6c 6f 63 61 74 65 64 20 62 79 20 5b 73 71 6c  llocated by [sql
27010 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
27020 6f 6e 74 65 78 74 28 43 2c 4e 29 5d 20 69 73 0a  ontext(C,N)] is.
27030 2a 2a 20 20 20 20 20 20 20 20 20 20 61 75 74 6f  **          auto
27040 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65 64 20  matically freed 
27050 6f 6e 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c  on the next call
27060 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
27070 65 74 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  et()].**        
27080 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69    or [sqlite3_fi
27090 6e 61 6c 69 7a 65 28 29 5d 20 66 6f 72 20 74 68  nalize()] for th
270a0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
270b0 65 6d 65 6e 74 5d 20 63 6f 6e 74 61 69 6e 69 6e  ement] containin
270c0 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  g.**          th
270d0 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  e aggregate func
270e0 74 69 6f 6e 20 61 73 73 6f 63 69 61 74 65 64 20  tion associated 
270f0 77 69 74 68 20 63 6f 6e 74 65 78 74 20 43 2e 0a  with context C..
27100 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
27110 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
27120 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  xt(sqlite3_conte
27130 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73 29  xt*, int nBytes)
27140 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
27150 46 3a 20 55 73 65 72 20 44 61 74 61 20 46 6f 72  F: User Data For
27160 20 46 75 6e 63 74 69 6f 6e 73 20 7b 46 31 36 32   Functions {F162
27170 34 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  40}.**.** The sq
27180 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
27190 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
271a0 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a  rns a copy of.**
271b0 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 68 61   the pointer tha
271c0 74 20 77 61 73 20 74 68 65 20 70 55 73 65 72 44  t was the pUserD
271d0 61 74 61 20 70 61 72 61 6d 65 74 65 72 20 28 74  ata parameter (t
271e0 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
271f0 29 0a 2a 2a 20 6f 66 20 74 68 65 20 74 68 65 20  ).** of the the 
27200 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
27210 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61  function()].** a
27220 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
27230 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
27240 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f   routines that o
27250 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67  riginally.** reg
27260 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c  istered the appl
27270 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20  ication defined 
27280 66 75 6e 63 74 69 6f 6e 2e 20 7b 45 4e 44 7d 0a  function. {END}.
27290 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
272a0 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  ne must be calle
272b0 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
272c0 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a  thread in which.
272d0 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
272e0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
272f0 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ion is running..
27300 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
27310 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32 34 33 7d  :.**.** {F16243}
27320 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 75 73   The [sqlite3_us
27330 65 72 5f 64 61 74 61 28 43 29 5d 20 69 6e 74 65  er_data(C)] inte
27340 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
27350 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 20  copy of the.**  
27360 20 20 20 20 20 20 20 20 50 20 70 6f 69 6e 74 65          P pointe
27370 72 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69  r from the [sqli
27380 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
27390 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c  ion(D,X,N,E,P,F,
273a0 53 2c 4c 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  S,L)].**        
273b0 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63 72    or [sqlite3_cr
273c0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
273d0 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29  D,X,N,E,P,F,S,L)
273e0 5d 20 63 61 6c 6c 20 74 68 61 74 0a 2a 2a 20 20  ] call that.**  
273f0 20 20 20 20 20 20 20 20 72 65 67 69 73 74 65 72          register
27400 65 64 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  ed the SQL funct
27410 69 6f 6e 20 61 73 73 6f 63 69 61 74 65 64 20 77  ion associated w
27420 69 74 68 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  ith .**         
27430 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   [sqlite3_contex
27440 74 5d 20 43 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73  t] C..*/.void *s
27450 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61  qlite3_user_data
27460 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
27470 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
27480 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75  REF: Function Au
27490 78 69 6c 69 61 72 79 20 44 61 74 61 20 7b 46 31  xiliary Data {F1
274a0 36 32 37 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20  6270}.**.** The 
274b0 66 6f 6c 6c 6f 77 69 6e 67 20 74 77 6f 20 66 75  following two fu
274c0 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 75  nctions may be u
274d0 73 65 64 20 62 79 20 73 63 61 6c 61 72 20 53 51  sed by scalar SQ
274e0 4c 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a  L functions to.*
274f0 2a 20 61 73 73 6f 63 69 61 74 65 20 6d 65 74 61  * associate meta
27500 2d 64 61 74 61 20 77 69 74 68 20 61 72 67 75 6d  -data with argum
27510 65 6e 74 20 76 61 6c 75 65 73 2e 20 49 66 20 74  ent values. If t
27520 68 65 20 73 61 6d 65 20 76 61 6c 75 65 20 69 73  he same value is
27530 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 6d 75   passed to.** mu
27540 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61 74 69 6f  ltiple invocatio
27550 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 53  ns of the same S
27560 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64 75 72 69  QL function duri
27570 6e 67 20 71 75 65 72 79 20 65 78 65 63 75 74 69  ng query executi
27580 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d  on, under.** som
27590 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20  e circumstances 
275a0 74 68 65 20 61 73 73 6f 63 69 61 74 65 64 20 6d  the associated m
275b0 65 74 61 2d 64 61 74 61 20 6d 61 79 20 62 65 20  eta-data may be 
275c0 70 72 65 73 65 72 76 65 64 2e 20 54 68 69 73 20  preserved. This 
275d0 6d 61 79 0a 2a 2a 20 62 65 20 75 73 65 64 2c 20  may.** be used, 
275e0 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74 6f 20  for example, to 
275f0 61 64 64 20 61 20 72 65 67 75 6c 61 72 2d 65 78  add a regular-ex
27600 70 72 65 73 73 69 6f 6e 20 6d 61 74 63 68 69 6e  pression matchin
27610 67 20 73 63 61 6c 61 72 0a 2a 2a 20 66 75 6e 63  g scalar.** func
27620 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70 69 6c  tion. The compil
27630 65 64 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68  ed version of th
27640 65 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73  e regular expres
27650 73 69 6f 6e 20 69 73 20 73 74 6f 72 65 64 20 61  sion is stored a
27660 73 0a 2a 2a 20 6d 65 74 61 2d 64 61 74 61 20 61  s.** meta-data a
27670 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
27680 68 65 20 53 51 4c 20 76 61 6c 75 65 20 70 61 73  he SQL value pas
27690 73 65 64 20 61 73 20 74 68 65 20 72 65 67 75 6c  sed as the regul
276a0 61 72 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a  ar expression.**
276b0 20 70 61 74 74 65 72 6e 2e 20 20 54 68 65 20 63   pattern.  The c
276c0 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c 61 72 20  ompiled regular 
276d0 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20 62  expression can b
276e0 65 20 72 65 75 73 65 64 20 6f 6e 20 6d 75 6c 74  e reused on mult
276f0 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69  iple.** invocati
27700 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ons of the same 
27710 66 75 6e 63 74 69 6f 6e 20 73 6f 20 74 68 61 74  function so that
27720 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 70 61   the original pa
27730 74 74 65 72 6e 20 73 74 72 69 6e 67 0a 2a 2a 20  ttern string.** 
27740 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
27750 20 62 65 20 72 65 63 6f 6d 70 69 6c 65 64 20 6f   be recompiled o
27760 6e 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f  n each invocatio
27770 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  n..**.** The sql
27780 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
27790 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
277a0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
277b0 6f 20 74 68 65 20 6d 65 74 61 2d 64 61 74 61 0a  o the meta-data.
277c0 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 62 79  ** associated by
277d0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74   the sqlite3_set
277e0 5f 61 75 78 64 61 74 61 28 29 20 66 75 6e 63 74  _auxdata() funct
277f0 69 6f 6e 20 77 69 74 68 20 74 68 65 20 4e 74 68  ion with the Nth
27800 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c   argument.** val
27810 75 65 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63  ue to the applic
27820 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
27830 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 49 66 20 6e 6f  nction..** If no
27840 20 6d 65 74 61 2d 64 61 74 61 20 68 61 73 20 62   meta-data has b
27850 65 65 6e 20 65 76 65 72 20 62 65 65 6e 20 73 65  een ever been se
27860 74 20 66 6f 72 20 74 68 65 20 4e 74 68 0a 2a 2a  t for the Nth.**
27870 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65   argument of the
27880 20 66 75 6e 63 74 69 6f 6e 2c 20 6f 72 20 69 66   function, or if
27890 20 74 68 65 20 63 6f 6f 72 65 73 70 6f 6e 64 69   the coorespondi
278a0 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61  ng function para
278b0 6d 65 74 65 72 0a 2a 2a 20 68 61 73 20 63 68 61  meter.** has cha
278c0 6e 67 65 64 20 73 69 6e 63 65 20 74 68 65 20 6d  nged since the m
278d0 65 74 61 2d 64 61 74 61 20 77 61 73 20 73 65 74  eta-data was set
278e0 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 67  , then sqlite3_g
278f0 65 74 5f 61 75 78 64 61 74 61 28 29 0a 2a 2a 20  et_auxdata().** 
27900 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70  returns a NULL p
27910 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  ointer..**.** Th
27920 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  e sqlite3_set_au
27930 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63  xdata() interfac
27940 65 20 73 61 76 65 73 20 74 68 65 20 6d 65 74 61  e saves the meta
27950 2d 64 61 74 61 0a 2a 2a 20 70 6f 69 6e 74 65 64  -data.** pointed
27960 20 74 6f 20 62 79 20 69 74 73 20 33 72 64 20 70   to by its 3rd p
27970 61 72 61 6d 65 74 65 72 20 61 73 20 74 68 65 20  arameter as the 
27980 6d 65 74 61 2d 64 61 74 61 20 66 6f 72 20 74 68  meta-data for th
27990 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65  e N-th.** argume
279a0 6e 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  nt of the applic
279b0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
279c0 6e 63 74 69 6f 6e 2e 20 20 53 75 62 73 65 71 75  nction.  Subsequ
279d0 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20  ent.** calls to 
279e0 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
279f0 61 74 61 28 29 20 6d 69 67 68 74 20 72 65 74 75  ata() might retu
27a00 72 6e 20 74 68 69 73 20 64 61 74 61 2c 20 69 66  rn this data, if
27a10 20 69 74 20 68 61 73 0a 2a 2a 20 6e 6f 74 20 62   it has.** not b
27a20 65 65 6e 20 64 65 73 74 72 6f 79 65 64 2e 20 0a  een destroyed. .
27a30 2a 2a 20 49 66 20 69 74 20 69 73 20 6e 6f 74 20  ** If it is not 
27a40 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c  NULL, SQLite wil
27a50 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73  l invoke the des
27a60 74 72 75 63 74 6f 72 20 0a 2a 2a 20 66 75 6e 63  tructor .** func
27a70 74 69 6f 6e 20 67 69 76 65 6e 20 62 79 20 74 68  tion given by th
27a80 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
27a90 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  to sqlite3_set_a
27aa0 75 78 64 61 74 61 28 29 20 6f 6e 0a 2a 2a 20 74  uxdata() on.** t
27ab0 68 65 20 6d 65 74 61 2d 64 61 74 61 20 77 68 65  he meta-data whe
27ac0 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  n the correspond
27ad0 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70 61 72  ing function par
27ae0 61 6d 65 74 65 72 20 63 68 61 6e 67 65 73 0a 2a  ameter changes.*
27af0 2a 20 6f 72 20 77 68 65 6e 20 74 68 65 20 53 51  * or when the SQ
27b00 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70  L statement comp
27b10 6c 65 74 65 73 2c 20 77 68 69 63 68 65 76 65 72  letes, whichever
27b20 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 0a 2a 2a   comes first..**
27b30 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73 20 66 72  .** SQLite is fr
27b40 65 65 20 74 6f 20 63 61 6c 6c 20 74 68 65 20 64  ee to call the d
27b50 65 73 74 72 75 63 74 6f 72 20 61 6e 64 20 64 72  estructor and dr
27b60 6f 70 20 6d 65 74 61 2d 64 61 74 61 20 6f 6e 0a  op meta-data on.
27b70 2a 2a 20 61 6e 79 20 70 61 72 61 6d 65 74 65 72  ** any parameter
27b80 20 6f 66 20 61 6e 79 20 66 75 6e 63 74 69 6f 6e   of any function
27b90 20 61 74 20 61 6e 79 20 74 69 6d 65 2e 20 20 54   at any time.  T
27ba0 68 65 20 6f 6e 6c 79 20 67 75 61 72 61 6e 74 65  he only guarante
27bb0 65 0a 2a 2a 20 69 73 20 74 68 61 74 20 74 68 65  e.** is that the
27bc0 20 64 65 73 74 72 75 63 74 6f 72 20 77 69 6c 6c   destructor will
27bd0 20 62 65 20 63 61 6c 6c 65 64 20 62 65 66 6f 72   be called befor
27be0 65 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 69  e the metadata i
27bf0 73 0a 2a 2a 20 64 72 6f 70 70 65 64 2e 0a 2a 2a  s.** dropped..**
27c00 0a 2a 2a 20 49 6e 20 70 72 61 63 74 69 63 65 2c  .** In practice,
27c10 20 6d 65 74 61 2d 64 61 74 61 20 69 73 20 70 72   meta-data is pr
27c20 65 73 65 72 76 65 64 20 62 65 74 77 65 65 6e 20  eserved between 
27c30 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20 66  function calls f
27c40 6f 72 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e  or.** expression
27c50 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 73 74  s that are const
27c60 61 6e 74 20 61 74 20 63 6f 6d 70 69 6c 65 20 74  ant at compile t
27c70 69 6d 65 2e 20 54 68 69 73 20 69 6e 63 6c 75 64  ime. This includ
27c80 65 73 20 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 61  es literal.** va
27c90 6c 75 65 73 20 61 6e 64 20 53 51 4c 20 76 61 72  lues and SQL var
27ca0 69 61 62 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  iables..**.** Th
27cb0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73  ese routines mus
27cc0 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
27cd0 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
27ce0 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65   in which.** the
27cf0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73   SQL function is
27d00 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20   running..**.** 
27d10 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
27d20 2a 20 7b 46 31 36 32 37 32 7d 20 54 68 65 20 5b  * {F16272} The [
27d30 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
27d40 61 74 61 28 43 2c 4e 29 5d 20 69 6e 74 65 72 66  ata(C,N)] interf
27d50 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
27d60 69 6e 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  inter.**        
27d70 20 20 74 6f 20 6d 65 74 61 64 61 74 61 20 61 73    to metadata as
27d80 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
27d90 65 20 4e 74 68 20 70 61 72 61 6d 65 74 65 72 20  e Nth parameter 
27da0 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  of the SQL funct
27db0 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ion.**          
27dc0 77 68 6f 73 65 20 63 6f 6e 74 65 78 74 20 69 73  whose context is
27dd0 20 43 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74   C, or NULL if t
27de0 68 65 72 65 20 69 73 20 6e 6f 20 6d 65 74 61 64  here is no metad
27df0 61 74 61 20 61 73 73 6f 63 69 61 74 65 64 0a 2a  ata associated.*
27e00 2a 20 20 20 20 20 20 20 20 20 20 77 69 74 68 20  *          with 
27e10 74 68 61 74 20 70 61 72 61 6d 65 74 65 72 2e 0a  that parameter..
27e20 2a 2a 0a 2a 2a 20 7b 46 31 36 32 37 34 7d 20 54  **.** {F16274} T
27e30 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  he [sqlite3_set_
27e40 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 44 29  auxdata(C,N,P,D)
27e50 5d 20 69 6e 74 65 72 66 61 63 65 20 61 73 73 69  ] interface assi
27e60 67 6e 73 20 61 20 6d 65 74 61 64 61 74 61 0a 2a  gns a metadata.*
27e70 2a 20 20 20 20 20 20 20 20 20 20 70 6f 69 6e 74  *          point
27e80 65 72 20 50 20 74 6f 20 74 68 65 20 4e 74 68 20  er P to the Nth 
27e90 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65  parameter of the
27ea0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 77 69   SQL function wi
27eb0 74 68 20 63 6f 6e 74 65 78 74 0a 2a 2a 20 20 20  th context.**   
27ec0 20 20 20 20 20 20 20 43 2e 0a 2a 2a 0a 2a 2a 20         C..**.** 
27ed0 7b 46 31 36 32 37 36 7d 20 53 51 4c 69 74 65 20  {F16276} SQLite 
27ee0 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20  will invoke the 
27ef0 64 65 73 74 72 75 63 74 6f 72 20 44 20 77 69 74  destructor D wit
27f00 68 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  h a single argum
27f10 65 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ent.**          
27f20 77 68 69 63 68 20 69 73 20 74 68 65 20 6d 65 74  which is the met
27f30 61 64 61 74 61 20 70 6f 69 6e 74 65 72 20 50 20  adata pointer P 
27f40 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c  following a call
27f50 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   to.**          
27f60 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78  [sqlite3_set_aux
27f70 64 61 74 61 28 43 2c 4e 2c 50 2c 44 29 5d 20 77  data(C,N,P,D)] w
27f80 68 65 6e 20 53 51 4c 69 74 65 20 63 65 61 73 65  hen SQLite cease
27f90 73 20 74 6f 20 68 6f 6c 64 0a 2a 2a 20 20 20 20  s to hold.**    
27fa0 20 20 20 20 20 20 74 68 65 20 6d 65 74 61 64 61        the metada
27fb0 74 61 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32 37  ta..**.** {F1627
27fc0 37 7d 20 53 51 4c 69 74 65 20 63 65 61 73 65 73  7} SQLite ceases
27fd0 20 74 6f 20 68 6f 6c 64 20 6d 65 74 61 64 61 74   to hold metadat
27fe0 61 20 66 6f 72 20 61 6e 20 53 51 4c 20 66 75 6e  a for an SQL fun
27ff0 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 0a  ction parameter.
28000 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68 65 6e  **          when
28010 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
28020 61 74 20 70 61 72 61 6d 65 74 65 72 20 63 68 61  at parameter cha
28030 6e 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  nges..**.** {F16
28040 32 37 38 7d 20 57 68 65 6e 20 5b 73 71 6c 69 74  278} When [sqlit
28050 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43  e3_set_auxdata(C
28060 2c 4e 2c 50 2c 44 29 5d 20 69 73 20 69 6e 76 6f  ,N,P,D)] is invo
28070 6b 65 64 2c 20 74 68 65 20 64 65 73 74 72 75 63  ked, the destruc
28080 74 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  tor.**          
28090 69 73 20 63 61 6c 6c 65 64 20 66 6f 72 20 61 6e  is called for an
280a0 79 20 70 72 69 6f 72 20 6d 65 74 61 64 61 74 61  y prior metadata
280b0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
280c0 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69   the same functi
280d0 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63  on.**          c
280e0 6f 6e 74 65 78 74 20 43 20 61 6e 64 20 70 61 72  ontext C and par
280f0 61 6d 65 74 65 72 20 4e 2e 0a 2a 2a 0a 2a 2a 20  ameter N..**.** 
28100 7b 46 31 36 32 37 39 7d 20 53 51 4c 69 74 65 20  {F16279} SQLite 
28110 77 69 6c 6c 20 63 61 6c 6c 20 64 65 73 74 72 75  will call destru
28120 63 74 6f 72 73 20 66 6f 72 20 61 6e 79 20 6d 65  ctors for any me
28130 74 61 64 61 74 61 20 69 74 20 69 73 20 68 6f 6c  tadata it is hol
28140 64 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20  ding.**         
28150 20 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72   in a particular
28160 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
28170 6d 65 6e 74 5d 20 53 20 77 68 65 6e 20 65 69 74  ment] S when eit
28180 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  her.**          
28190 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
281a0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  )] or [sqlite3_f
281b0 69 6e 61 6c 69 7a 65 28 53 29 5d 20 69 73 20 63  inalize(S)] is c
281c0 61 6c 6c 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  alled..*/.void *
281d0 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
281e0 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ata(sqlite3_cont
281f0 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 76 6f  ext*, int N);.vo
28200 69 64 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  id sqlite3_set_a
28210 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63  uxdata(sqlite3_c
28220 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20  ontext*, int N, 
28230 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28  void*, void (*)(
28240 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a  void*));.../*.**
28250 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 73 74   CAPI3REF: Const
28260 61 6e 74 73 20 44 65 66 69 6e 69 6e 67 20 53 70  ants Defining Sp
28270 65 63 69 61 6c 20 44 65 73 74 72 75 63 74 6f 72  ecial Destructor
28280 20 42 65 68 61 76 69 6f 72 20 7b 46 31 30 32 38   Behavior {F1028
28290 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61  0}.**.** These a
282a0 72 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65  re special value
282b0 20 66 6f 72 20 74 68 65 20 64 65 73 74 72 75 63   for the destruc
282c0 74 6f 72 20 74 68 61 74 20 69 73 20 70 61 73 73  tor that is pass
282d0 65 64 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20  ed in as the.** 
282e0 66 69 6e 61 6c 20 61 72 67 75 6d 65 6e 74 20 74  final argument t
282f0 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20  o routines like 
28300 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
28310 62 6c 6f 62 28 29 5d 2e 20 20 49 66 20 74 68 65  blob()].  If the
28320 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61   destructor.** a
28330 72 67 75 6d 65 6e 74 20 69 73 20 53 51 4c 49 54  rgument is SQLIT
28340 45 5f 53 54 41 54 49 43 2c 20 69 74 20 6d 65 61  E_STATIC, it mea
28350 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74  ns that the cont
28360 65 6e 74 20 70 6f 69 6e 74 65 72 20 69 73 20 63  ent pointer is c
28370 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77  onstant.** and w
28380 69 6c 6c 20 6e 65 76 65 72 20 63 68 61 6e 67 65  ill never change
28390 2e 20 20 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e  .  It does not n
283a0 65 65 64 20 74 6f 20 62 65 20 64 65 73 74 72 6f  eed to be destro
283b0 79 65 64 2e 20 20 54 68 65 20 0a 2a 2a 20 53 51  yed.  The .** SQ
283c0 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 76  LITE_TRANSIENT v
283d0 61 6c 75 65 20 6d 65 61 6e 73 20 74 68 61 74 20  alue means that 
283e0 74 68 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c  the content will
283f0 20 6c 69 6b 65 6c 79 20 63 68 61 6e 67 65 20 69   likely change i
28400 6e 0a 2a 2a 20 74 68 65 20 6e 65 61 72 20 66 75  n.** the near fu
28410 74 75 72 65 20 61 6e 64 20 74 68 61 74 20 53 51  ture and that SQ
28420 4c 69 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65  Lite should make
28430 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65   its own private
28440 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20   copy of.** the 
28450 63 6f 6e 74 65 6e 74 20 62 65 66 6f 72 65 20 72  content before r
28460 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  eturning..**.** 
28470 54 68 65 20 74 79 70 65 64 65 66 20 69 73 20 6e  The typedef is n
28480 65 63 65 73 73 61 72 79 20 74 6f 20 77 6f 72 6b  ecessary to work
28490 20 61 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73   around problems
284a0 20 69 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43   in certain.** C
284b0 2b 2b 20 63 6f 6d 70 69 6c 65 72 73 2e 20 20 53  ++ compilers.  S
284c0 65 65 20 74 69 63 6b 65 74 20 23 32 31 39 31 2e  ee ticket #2191.
284d0 0a 2a 2f 0a 74 79 70 65 64 65 66 20 76 6f 69 64  .*/.typedef void
284e0 20 28 2a 73 71 6c 69 74 65 33 5f 64 65 73 74 72   (*sqlite3_destr
284f0 75 63 74 6f 72 5f 74 79 70 65 29 28 76 6f 69 64  uctor_type)(void
28500 2a 29 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  *);.#define SQLI
28510 54 45 5f 53 54 41 54 49 43 20 20 20 20 20 20 28  TE_STATIC      (
28520 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63  (sqlite3_destruc
28530 74 6f 72 5f 74 79 70 65 29 30 29 0a 23 64 65 66  tor_type)0).#def
28540 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53  ine SQLITE_TRANS
28550 49 45 4e 54 20 20 20 28 28 73 71 6c 69 74 65 33  IENT   ((sqlite3
28560 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65  _destructor_type
28570 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  )-1)../*.** CAPI
28580 33 52 45 46 3a 20 53 65 74 74 69 6e 67 20 54 68  3REF: Setting Th
28590 65 20 52 65 73 75 6c 74 20 4f 66 20 41 6e 20 53  e Result Of An S
285a0 51 4c 20 46 75 6e 63 74 69 6f 6e 20 7b 46 31 36  QL Function {F16
285b0 34 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  400}.**.** These
285c0 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73   routines are us
285d0 65 64 20 62 79 20 74 68 65 20 78 46 75 6e 63 20  ed by the xFunc 
285e0 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61  or xFinal callba
285f0 63 6b 73 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c  cks that.** impl
28600 65 6d 65 6e 74 20 53 51 4c 20 66 75 6e 63 74 69  ement SQL functi
28610 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74  ons and aggregat
28620 65 73 2e 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c  es.  See.** [sql
28630 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
28640 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  tion()] and [sql
28650 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
28660 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72  tion16()].** for
28670 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   additional info
28680 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  rmation..**.** T
28690 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 77  hese functions w
286a0 6f 72 6b 20 76 65 72 79 20 6d 75 63 68 20 6c 69  ork very much li
286b0 6b 65 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69  ke the .** [sqli
286c0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20  te3_bind_blob | 
286d0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 5d 20  sqlite3_bind_*] 
286e0 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69  family of functi
286f0 6f 6e 73 20 75 73 65 64 0a 2a 2a 20 74 6f 20 62  ons used.** to b
28700 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f  ind values to ho
28710 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e  st parameters in
28720 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
28730 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74  ents..** Refer t
28740 6f 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  o the.** [sqlite
28750 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71  3_bind_blob | sq
28760 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 64 6f 63  lite3_bind_* doc
28770 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 0a  umentation] for.
28780 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  ** additional in
28790 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
287a0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
287b0 75 6c 74 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72  ult_blob() inter
287c0 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
287d0 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20  sult from.** an 
287e0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69  application defi
287f0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
28800 62 65 20 74 68 65 20 42 4c 4f 42 20 77 68 6f 73  be the BLOB whos
28810 65 20 63 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69  e content is poi
28820 6e 74 65 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68  nted.** to by th
28830 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
28840 65 72 20 61 6e 64 20 77 68 69 63 68 20 69 73 20  er and which is 
28850 4e 20 62 79 74 65 73 20 6c 6f 6e 67 20 77 68 65  N bytes long whe
28860 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74  re N is the.** t
28870 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e 20  hird parameter. 
28880 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
28890 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28  result_zeroblob(
288a0 29 20 69 6e 65 72 66 61 63 65 73 20 73 65 74 20  ) inerfaces set 
288b0 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a  the result of.**
288c0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
288d0 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f   defined functio
288e0 6e 20 74 6f 20 62 65 20 61 20 42 4c 4f 42 20 63  n to be a BLOB c
288f0 6f 6e 74 61 69 6e 69 6e 67 20 61 6c 6c 20 7a 65  ontaining all ze
28900 72 6f 0a 2a 2a 20 62 79 74 65 73 20 61 6e 64 20  ro.** bytes and 
28910 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 2c  N bytes in size,
28920 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20   where N is the 
28930 76 61 6c 75 65 20 6f 66 20 74 68 65 20 32 6e 64  value of the 2nd
28940 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
28950 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
28960 73 75 6c 74 5f 64 6f 75 62 6c 65 28 29 20 69 6e  sult_double() in
28970 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
28980 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20   result from.** 
28990 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  an application d
289a0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
289b0 74 6f 20 62 65 20 61 20 66 6c 6f 61 74 69 6e 67  to be a floating
289c0 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 73 70 65   point value spe
289d0 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 69 74 73  cified.** by its
289e0 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a   2nd argument..*
289f0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
28a00 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20  _result_error() 
28a10 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  and sqlite3_resu
28a20 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 66 75 6e  lt_error16() fun
28a30 63 74 69 6f 6e 73 0a 2a 2a 20 63 61 75 73 65 20  ctions.** cause 
28a40 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20  the implemented 
28a50 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  SQL function to 
28a60 74 68 72 6f 77 20 61 6e 20 65 78 63 65 70 74 69  throw an excepti
28a70 6f 6e 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73  on..** SQLite us
28a80 65 73 20 74 68 65 20 73 74 72 69 6e 67 20 70 6f  es the string po
28a90 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 0a  inted to by the.
28aa0 2a 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  ** 2nd parameter
28ab0 20 6f 66 20 73 71 6c 69 74 65 33 5f 72 65 73 75   of sqlite3_resu
28ac0 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 20 73 71  lt_error() or sq
28ad0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
28ae0 6f 72 31 36 28 29 0a 2a 2a 20 61 73 20 74 68 65  or16().** as the
28af0 20 74 65 78 74 20 6f 66 20 61 6e 20 65 72 72 6f   text of an erro
28b00 72 20 6d 65 73 73 61 67 65 2e 20 20 53 51 4c 69  r message.  SQLi
28b10 74 65 20 69 6e 74 65 72 70 72 65 74 73 20 74 68  te interprets th
28b20 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61  e error.** messa
28b30 67 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73  ge string from s
28b40 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
28b50 72 6f 72 28 29 20 61 73 20 55 54 46 38 2e 20 53  ror() as UTF8. S
28b60 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72  QLite.** interpr
28b70 65 74 73 20 74 68 65 20 73 74 72 69 6e 67 20 66  ets the string f
28b80 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75  rom sqlite3_resu
28b90 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 61 73 20  lt_error16() as 
28ba0 55 54 46 31 36 20 69 6e 20 6e 61 74 69 76 65 0a  UTF16 in native.
28bb0 2a 2a 20 62 79 74 65 20 6f 72 64 65 72 2e 20 20  ** byte order.  
28bc0 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72  If the third par
28bd0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
28be0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
28bf0 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  .** or sqlite3_r
28c00 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20  esult_error16() 
28c10 69 73 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e  is negative then
28c20 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 61 73   SQLite takes as
28c30 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65   the error.** me
28c40 73 73 61 67 65 20 61 6c 6c 20 74 65 78 74 20 75  ssage all text u
28c50 70 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69  p through the fi
28c60 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74  rst zero charact
28c70 65 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 74 68  er..** If the th
28c80 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
28c90 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
28ca0 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 73 71  error() or.** sq
28cb0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
28cc0 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d 6e 65  or16() is non-ne
28cd0 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69  gative then SQLi
28ce0 74 65 20 74 61 6b 65 73 20 74 68 61 74 20 6d 61  te takes that ma
28cf0 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e 6f 74  ny.** bytes (not
28d00 20 63 68 61 72 61 63 74 65 72 73 29 20 66 72 6f   characters) fro
28d10 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  m the 2nd parame
28d20 74 65 72 20 61 73 20 74 68 65 20 65 72 72 6f 72  ter as the error
28d30 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 54 68 65   message..** The
28d40 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
28d50 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69  error() and sqli
28d60 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
28d70 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  16().** routines
28d80 20 6d 61 6b 65 20 61 20 63 6f 70 79 20 70 72 69   make a copy pri
28d90 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65  vate copy of the
28da0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74   error message t
28db0 65 78 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68  ext before.** th
28dc0 65 79 20 72 65 74 75 72 6e 2e 20 20 48 65 6e 63  ey return.  Henc
28dd0 65 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66  e, the calling f
28de0 75 6e 63 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c  unction can deal
28df0 6c 6f 63 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64  locate or.** mod
28e00 69 66 79 20 74 68 65 20 74 65 78 74 20 61 66 74  ify the text aft
28e10 65 72 20 74 68 65 79 20 72 65 74 75 72 6e 20 77  er they return w
28e20 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20  ithout harm..** 
28e30 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
28e40 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29 20  lt_error_code() 
28e50 66 75 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65 73  function changes
28e60 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 0a   the error code.
28e70 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 53  ** returned by S
28e80 51 4c 69 74 65 20 61 73 20 61 20 72 65 73 75 6c  QLite as a resul
28e90 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 69 6e  t of an error in
28ea0 20 61 20 66 75 6e 63 74 69 6f 6e 2e 20 20 42 79   a function.  By
28eb0 20 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 65   default,.** the
28ec0 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 53   error code is S
28ed0 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 0a 2a 2a  QLITE_ERROR. .**
28ee0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
28ef0 72 65 73 75 6c 74 5f 74 6f 6f 62 69 67 28 29 20  result_toobig() 
28f00 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73  interface causes
28f10 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 74 68   SQLite.** to th
28f20 72 6f 77 20 61 6e 20 65 72 72 6f 72 20 69 6e 64  row an error ind
28f30 69 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 73  icating that a s
28f40 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73  tring or BLOB is
28f50 20 74 6f 20 6c 6f 6e 67 0a 2a 2a 20 74 6f 20 72   to long.** to r
28f60 65 70 72 65 73 65 6e 74 2e 20 20 54 68 65 20 73  epresent.  The s
28f70 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 6f  qlite3_result_no
28f80 6d 65 6d 28 29 20 69 6e 74 65 72 66 61 63 65 0a  mem() interface.
28f90 2a 2a 20 63 61 75 73 65 73 20 53 51 4c 69 74 65  ** causes SQLite
28fa0 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 78 63   to throw an exc
28fb0 65 70 74 69 6f 6e 20 69 6e 64 69 63 61 74 69 6e  eption indicatin
28fc0 67 20 74 68 61 74 20 74 68 65 20 61 0a 2a 2a 20  g that the a.** 
28fd0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
28fe0 6e 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20  n failed..**.** 
28ff0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
29000 6c 74 5f 69 6e 74 28 29 20 69 6e 74 65 72 66 61  lt_int() interfa
29010 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75  ce sets the retu
29020 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74  rn value.** of t
29030 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
29040 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
29050 74 6f 20 62 65 20 74 68 65 20 33 32 2d 62 69 74  to be the 32-bit
29060 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a   signed integer.
29070 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69  ** value given i
29080 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65  n the 2nd argume
29090 6e 74 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  nt..** The sqlit
290a0 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28  e3_result_int64(
290b0 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
290c0 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
290d0 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c  e.** of the appl
290e0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
290f0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74  function to be t
29100 68 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  he 64-bit signed
29110 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75   integer.** valu
29120 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32  e given in the 2
29130 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  nd argument..**.
29140 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
29150 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e 74  esult_null() int
29160 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
29170 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20  return value.** 
29180 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
29190 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
291a0 69 6f 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a  ion to be NULL..
291b0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
291c0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 29 2c  3_result_text(),
291d0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
291e0 74 65 78 74 31 36 28 29 2c 20 0a 2a 2a 20 73 71  text16(), .** sq
291f0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
29200 74 31 36 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c  t16le(), and sql
29210 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
29220 31 36 62 65 28 29 20 69 6e 74 65 72 66 61 63 65  16be() interface
29230 73 0a 2a 2a 20 73 65 74 20 74 68 65 20 72 65 74  s.** set the ret
29240 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65  urn value of the
29250 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
29260 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
29270 20 62 65 0a 2a 2a 20 61 20 74 65 78 74 20 73 74   be.** a text st
29280 72 69 6e 67 20 77 68 69 63 68 20 69 73 20 72 65  ring which is re
29290 70 72 65 73 65 6e 74 65 64 20 61 73 20 55 54 46  presented as UTF
292a0 2d 38 2c 20 55 54 46 2d 31 36 20 6e 61 74 69 76  -8, UTF-16 nativ
292b0 65 20 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a  e byte order,.**
292c0 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 20 65   UTF-16 little e
292d0 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36  ndian, or UTF-16
292e0 20 62 69 67 20 65 6e 64 69 61 6e 2c 20 72 65 73   big endian, res
292f0 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 53 51  pectively..** SQ
29300 4c 69 74 65 20 74 61 6b 65 73 20 74 68 65 20 74  Lite takes the t
29310 65 78 74 20 72 65 73 75 6c 74 20 66 72 6f 6d 20  ext result from 
29320 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
29330 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20  from.** the 2nd 
29340 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65  parameter of the
29350 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
29360 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
29370 2e 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20  ..** If the 3rd 
29380 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
29390 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
293a0 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
293b0 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c  .** is negative,
293c0 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b   then SQLite tak
293d0 65 73 20 72 65 73 75 6c 74 20 74 65 78 74 20 66  es result text f
293e0 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61  rom the 2nd para
293f0 6d 65 74 65 72 20 0a 2a 2a 20 74 68 72 6f 75 67  meter .** throug
29400 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f  h the first zero
29410 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49   character..** I
29420 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65  f the 3rd parame
29430 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
29440 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
29450 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73  interfaces.** is
29460 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74   non-negative, t
29470 68 65 6e 20 61 73 20 6d 61 6e 79 20 62 79 74 65  hen as many byte
29480 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72  s (not character
29490 73 29 20 6f 66 20 74 68 65 20 74 65 78 74 0a 2a  s) of the text.*
294a0 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20  * pointed to by 
294b0 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
294c0 72 20 61 72 65 20 74 61 6b 65 6e 20 61 73 20 74  r are taken as t
294d0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
294e0 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 69  efined.** functi
294f0 6f 6e 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 49 66  on result..** If
29500 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74   the 4th paramet
29510 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
29520 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
29530 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20  nterfaces.** or 
29540 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
29550 6c 6f 62 20 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c  lob is a non-NUL
29560 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20  L pointer, then 
29570 53 51 4c 69 74 65 20 63 61 6c 6c 73 20 74 68 61  SQLite calls tha
29580 74 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 61 73  t.** function as
29590 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
295a0 6f 6e 20 74 68 65 20 74 65 78 74 20 6f 72 20 62  on the text or b
295b0 6c 6f 62 20 72 65 73 75 6c 74 20 77 68 65 6e 20  lob result when 
295c0 69 74 20 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68  it has.** finish
295d0 65 64 20 75 73 69 6e 67 20 74 68 61 74 20 72 65  ed using that re
295e0 73 75 6c 74 2e 0a 2a 2a 20 49 66 20 74 68 65 20  sult..** If the 
295f0 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
29600 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
29610 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
29620 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  aces.** or sqlit
29630 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69  e3_result_blob i
29640 73 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f  s the special co
29650 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 53 54  nstant SQLITE_ST
29660 41 54 49 43 2c 20 74 68 65 6e 0a 2a 2a 20 53 51  ATIC, then.** SQ
29670 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 61  Lite assumes tha
29680 74 20 74 68 65 20 74 65 78 74 20 6f 72 20 62 6c  t the text or bl
29690 6f 62 20 72 65 73 75 6c 74 20 69 73 20 63 6f 6e  ob result is con
296a0 73 74 61 6e 74 20 73 70 61 63 65 20 61 6e 64 0a  stant space and.
296b0 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 63 6f 70 79  ** does not copy
296c0 20 74 68 65 20 73 70 61 63 65 20 6f 72 20 63 61   the space or ca
296d0 6c 6c 20 61 20 64 65 73 74 72 75 63 74 6f 72 20  ll a destructor 
296e0 77 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20 66  when it has.** f
296f0 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68  inished using th
29700 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 49 66  at result..** If
29710 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74   the 4th paramet
29720 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
29730 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
29740 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20  nterfaces.** or 
29750 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
29760 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65 63 69  lob is the speci
29770 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49  al constant SQLI
29780 54 45 5f 54 52 41 4e 53 49 45 4e 54 0a 2a 2a 20  TE_TRANSIENT.** 
29790 74 68 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65  then SQLite make
297a0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
297b0 72 65 73 75 6c 74 20 69 6e 74 6f 20 73 70 61 63  result into spac
297c0 65 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a  e obtained from.
297d0 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ** from [sqlite3
297e0 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 65 66 6f 72  _malloc()] befor
297f0 65 20 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  e it returns..**
29800 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
29810 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69  result_value() i
29820 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
29830 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74  e result of.** t
29840 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
29850 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
29860 74 6f 20 62 65 20 61 20 63 6f 70 79 20 74 68 65  to be a copy the
29870 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
29880 0a 2a 2a 20 6f 62 6a 65 63 74 20 73 70 65 63 69  .** object speci
29890 66 69 65 64 20 62 79 20 74 68 65 20 32 6e 64 20  fied by the 2nd 
298a0 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65 0a  parameter.  The.
298b0 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  ** sqlite3_resul
298c0 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66  t_value() interf
298d0 61 63 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79  ace makes a copy
298e0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
298f0 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74 68  _value].** so th
29900 61 74 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  at [sqlite3_valu
29910 65 5d 20 73 70 65 63 69 66 69 65 64 20 69 6e 20  e] specified in 
29920 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61  the parameter ma
29930 79 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 62  y change or.** b
29940 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 61 66  e deallocated af
29950 74 65 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75  ter sqlite3_resu
29960 6c 74 5f 76 61 6c 75 65 28 29 20 72 65 74 75 72  lt_value() retur
29970 6e 73 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e  ns without harm.
29980 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 73 65 20  .**.** If these 
29990 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c  routines are cal
299a0 6c 65 64 20 66 72 6f 6d 20 77 69 74 68 69 6e 20  led from within 
299b0 74 68 65 20 64 69 66 66 65 72 65 6e 74 20 74 68  the different th
299c0 72 65 61 64 20 0a 2a 2a 20 74 68 61 6e 20 74 68  read .** than th
299d0 65 20 6f 6e 65 20 63 6f 6e 74 61 69 6e 69 6e 67  e one containing
299e0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
299f0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
29a00 6e 20 74 68 61 74 20 72 65 63 69 65 76 65 64 0a  n that recieved.
29a10 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
29a20 63 6f 6e 74 65 78 74 5d 20 70 6f 69 6e 74 65 72  context] pointer
29a30 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  , the results ar
29a40 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  e undefined..**.
29a50 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
29a60 2a 0a 2a 2a 20 7b 46 31 36 34 30 33 7d 20 54 68  *.** {F16403} Th
29a70 65 20 64 65 66 61 75 6c 74 20 72 65 74 75 72 6e  e default return
29a80 20 76 61 6c 75 65 20 66 72 6f 6d 20 61 6e 79 20   value from any 
29a90 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  SQL function is 
29aa0 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  NULL..**.** {F16
29ab0 34 30 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  406} The [sqlite
29ac0 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 43 2c  3_result_blob(C,
29ad0 56 2c 4e 2c 44 29 5d 20 69 6e 74 65 72 66 61 63  V,N,D)] interfac
29ae0 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a  e changes the.**
29af0 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e            return
29b00 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69   value of functi
29b10 6f 6e 20 43 20 74 6f 20 62 65 20 61 20 62 6c 6f  on C to be a blo
29b20 62 20 74 68 61 74 20 69 73 20 4e 20 62 79 74 65  b that is N byte
29b30 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  s.**          in
29b40 20 6c 65 6e 67 74 68 20 61 6e 64 20 77 69 74 68   length and with
29b50 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65 64   content pointed
29b60 20 74 6f 20 62 79 20 56 2e 0a 2a 2a 0a 2a 2a 20   to by V..**.** 
29b70 7b 46 31 36 34 30 39 7d 20 54 68 65 20 5b 73 71  {F16409} The [sq
29b80 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75  lite3_result_dou
29b90 62 6c 65 28 43 2c 56 29 5d 20 69 6e 74 65 72 66  ble(C,V)] interf
29ba0 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a  ace changes the.
29bb0 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75  **          retu
29bc0 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63  rn value of func
29bd0 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65  tion C to be the
29be0 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
29bf0 76 61 6c 75 65 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b  value V..**.** {
29c00 46 31 36 34 31 32 7d 20 54 68 65 20 5b 73 71 6c  F16412} The [sql
29c10 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
29c20 72 28 43 2c 56 2c 4e 29 5d 20 69 6e 74 65 72 66  r(C,V,N)] interf
29c30 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 20  ace changes the 
29c40 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20  return.**       
29c50 20 20 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63     value of func
29c60 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e 20  tion C to be an 
29c70 65 78 63 65 70 74 69 6f 6e 20 77 69 74 68 20 65  exception with e
29c80 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 20 20 20  rror code.**    
29c90 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 45 52        [SQLITE_ER
29ca0 52 4f 52 5d 20 61 6e 64 20 61 20 55 54 46 38 20  ROR] and a UTF8 
29cb0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 63 6f  error message co
29cc0 70 69 65 64 20 66 72 6f 6d 20 56 20 75 70 20 74  pied from V up t
29cd0 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  o the.**        
29ce0 20 20 66 69 72 73 74 20 7a 65 72 6f 20 62 79 74    first zero byt
29cf0 65 20 6f 72 20 75 6e 74 69 6c 20 4e 20 62 79 74  e or until N byt
29d00 65 73 20 61 72 65 20 72 65 61 64 20 69 66 20 4e  es are read if N
29d10 20 69 73 20 70 6f 73 69 74 69 76 65 2e 0a 2a 2a   is positive..**
29d20 0a 2a 2a 20 7b 46 31 36 34 31 35 7d 20 54 68 65  .** {F16415} The
29d30 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
29d40 5f 65 72 72 6f 72 31 36 28 43 2c 56 2c 4e 29 5d  _error16(C,V,N)]
29d50 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67   interface chang
29d60 65 73 20 74 68 65 20 72 65 74 75 72 6e 0a 2a 2a  es the return.**
29d70 20 20 20 20 20 20 20 20 20 20 76 61 6c 75 65 20            value 
29d80 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f  of function C to
29d90 20 62 65 20 61 6e 20 65 78 63 65 70 74 69 6f 6e   be an exception
29da0 20 77 69 74 68 20 65 72 72 6f 72 20 63 6f 64 65   with error code
29db0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51  .**          [SQ
29dc0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 61 6e 64 20  LITE_ERROR] and 
29dd0 61 20 55 54 46 31 36 20 6e 61 74 69 76 65 20 62  a UTF16 native b
29de0 79 74 65 20 6f 72 64 65 72 20 65 72 72 6f 72 20  yte order error 
29df0 6d 65 73 73 61 67 65 0a 2a 2a 20 20 20 20 20 20  message.**      
29e00 20 20 20 20 63 6f 70 69 65 64 20 66 72 6f 6d 20      copied from 
29e10 56 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73  V up to the firs
29e20 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  t zero terminato
29e30 72 20 6f 72 20 75 6e 74 69 6c 20 4e 20 62 79 74  r or until N byt
29e40 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  es.**          a
29e50 72 65 20 72 65 61 64 20 69 66 20 4e 20 69 73 20  re read if N is 
29e60 70 6f 73 69 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20  positive..**.** 
29e70 7b 46 31 36 34 31 38 7d 20 54 68 65 20 5b 73 71  {F16418} The [sq
29e80 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
29e90 6f 72 5f 74 6f 6f 62 69 67 28 43 29 5d 20 69 6e  or_toobig(C)] in
29ea0 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20  terface changes 
29eb0 74 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20  the return.**   
29ec0 20 20 20 20 20 20 20 76 61 6c 75 65 20 6f 66 20         value of 
29ed0 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 43 20 74  the function C t
29ee0 6f 20 62 65 20 61 6e 20 65 78 63 65 70 74 69 6f  o be an exceptio
29ef0 6e 20 77 69 74 68 20 65 72 72 6f 72 20 63 6f 64  n with error cod
29f00 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53  e.**          [S
29f10 51 4c 49 54 45 5f 54 4f 4f 42 49 47 5d 20 61 6e  QLITE_TOOBIG] an
29f20 64 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65  d an appropriate
29f30 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a   error message..
29f40 2a 2a 0a 2a 2a 20 7b 46 31 36 34 32 31 7d 20 54  **.** {F16421} T
29f50 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  he [sqlite3_resu
29f60 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 43  lt_error_nomem(C
29f70 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61  )] interface cha
29f80 6e 67 65 73 20 74 68 65 20 72 65 74 75 72 6e 0a  nges the return.
29f90 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c 75  **          valu
29fa0 65 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f  e of the functio
29fb0 6e 20 43 20 74 6f 20 62 65 20 61 6e 20 65 78 63  n C to be an exc
29fc0 65 70 74 69 6f 6e 20 77 69 74 68 20 65 72 72 6f  eption with erro
29fd0 72 20 63 6f 64 65 0a 2a 2a 20 20 20 20 20 20 20  r code.**       
29fe0 20 20 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d     [SQLITE_NOMEM
29ff0 5d 20 61 6e 64 20 61 6e 20 61 70 70 72 6f 70 72  ] and an appropr
2a000 69 61 74 65 20 65 72 72 6f 72 20 6d 65 73 73 61  iate error messa
2a010 67 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 32  ge..**.** {F1642
2a020 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  4} The [sqlite3_
2a030 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64  result_error_cod
2a040 65 28 43 2c 45 29 5d 20 69 6e 74 65 72 66 61 63  e(C,E)] interfac
2a050 65 20 63 68 61 6e 67 65 73 20 74 68 65 20 72 65  e changes the re
2a060 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  turn.**         
2a070 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 66 75   value of the fu
2a080 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 61  nction C to be a
2a090 6e 20 65 78 63 65 70 74 69 6f 6e 20 77 69 74 68  n exception with
2a0a0 20 65 72 72 6f 72 20 63 6f 64 65 20 45 2e 0a 2a   error code E..*
2a0b0 2a 20 20 20 20 20 20 20 20 20 20 54 68 65 20 65  *          The e
2a0c0 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78  rror message tex
2a0d0 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a  t is unchanged..
2a0e0 2a 2a 0a 2a 2a 20 7b 46 31 36 34 32 37 7d 20 54  **.** {F16427} T
2a0f0 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  he [sqlite3_resu
2a100 6c 74 5f 69 6e 74 28 43 2c 56 29 5d 20 69 6e 74  lt_int(C,V)] int
2a110 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74  erface changes t
2a120 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  he.**          r
2a130 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66  eturn value of f
2a140 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20  unction C to be 
2a150 74 68 65 20 33 32 2d 62 69 74 20 69 6e 74 65 67  the 32-bit integ
2a160 65 72 20 76 61 6c 75 65 20 56 2e 0a 2a 2a 0a 2a  er value V..**.*
2a170 2a 20 7b 46 31 36 34 33 30 7d 20 54 68 65 20 5b  * {F16430} The [
2a180 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
2a190 6e 74 36 34 28 43 2c 56 29 5d 20 69 6e 74 65 72  nt64(C,V)] inter
2a1a0 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65  face changes the
2a1b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74  .**          ret
2a1c0 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e  urn value of fun
2a1d0 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68  ction C to be th
2a1e0 65 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72  e 64-bit integer
2a1f0 20 76 61 6c 75 65 20 56 2e 0a 2a 2a 0a 2a 2a 20   value V..**.** 
2a200 7b 46 31 36 34 33 33 7d 20 54 68 65 20 5b 73 71  {F16433} The [sq
2a210 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c  lite3_result_nul
2a220 6c 28 43 29 5d 20 69 6e 74 65 72 66 61 63 65 20  l(C)] interface 
2a230 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20  changes the.**  
2a240 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 76          return v
2a250 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e  alue of function
2a260 20 43 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a   C to be NULL..*
2a270 2a 0a 2a 2a 20 7b 46 31 36 34 33 36 7d 20 54 68  *.** {F16436} Th
2a280 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  e [sqlite3_resul
2a290 74 5f 74 65 78 74 28 43 2c 56 2c 4e 2c 44 29 5d  t_text(C,V,N,D)]
2a2a0 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67   interface chang
2a2b0 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  es the.**       
2a2c0 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20     return value 
2a2d0 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f  of function C to
2a2e0 20 62 65 20 74 68 65 20 55 54 46 38 20 73 74 72   be the UTF8 str
2a2f0 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ing.**          
2a300 56 20 75 70 20 74 68 72 6f 75 67 68 20 74 68 65  V up through the
2a310 20 66 69 72 73 74 20 7a 65 72 6f 20 6f 72 20 75   first zero or u
2a320 6e 74 69 6c 20 4e 20 62 79 74 65 73 20 61 72 65  ntil N bytes are
2a330 20 72 65 61 64 20 69 66 20 4e 0a 2a 2a 20 20 20   read if N.**   
2a340 20 20 20 20 20 20 20 69 73 20 70 6f 73 69 74 69         is positi
2a350 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 33  ve..**.** {F1643
2a360 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  9} The [sqlite3_
2a370 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 43 2c  result_text16(C,
2a380 56 2c 4e 2c 44 29 5d 20 69 6e 74 65 72 66 61 63  V,N,D)] interfac
2a390 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a  e changes the.**
2a3a0 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e            return
2a3b0 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69   value of functi
2a3c0 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65 20 55  on C to be the U
2a3d0 54 46 31 36 20 6e 61 74 69 76 65 20 62 79 74 65  TF16 native byte
2a3e0 20 6f 72 64 65 72 0a 2a 2a 20 20 20 20 20 20 20   order.**       
2a3f0 20 20 20 73 74 72 69 6e 67 20 20 56 20 75 70 20     string  V up 
2a400 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 73  through the firs
2a410 74 20 7a 65 72 6f 20 6f 72 20 75 6e 74 69 6c 20  t zero or until 
2a420 4e 20 62 79 74 65 73 20 61 72 65 20 72 65 61 64  N bytes are read
2a430 20 69 66 20 4e 0a 2a 2a 20 20 20 20 20 20 20 20   if N.**        
2a440 20 20 69 73 20 70 6f 73 69 74 69 76 65 2e 0a 2a    is positive..*
2a450 2a 0a 2a 2a 20 7b 46 31 36 34 34 32 7d 20 54 68  *.** {F16442} Th
2a460 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  e [sqlite3_resul
2a470 74 5f 74 65 78 74 31 36 62 65 28 43 2c 56 2c 4e  t_text16be(C,V,N
2a480 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  ,D)] interface c
2a490 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20  hanges the.**   
2a4a0 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 61         return va
2a4b0 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20  lue of function 
2a4c0 43 20 74 6f 20 62 65 20 74 68 65 20 55 54 46 31  C to be the UTF1
2a4d0 36 20 62 69 67 2d 65 6e 64 69 61 6e 0a 2a 2a 20  6 big-endian.** 
2a4e0 20 20 20 20 20 20 20 20 20 73 74 72 69 6e 67 20           string 
2a4f0 20 56 20 75 70 20 74 68 72 6f 75 67 68 20 74 68   V up through th
2a500 65 20 66 69 72 73 74 20 7a 65 72 6f 20 6f 72 20  e first zero or 
2a510 75 6e 74 69 6c 20 4e 20 62 79 74 65 73 20 61 72  until N bytes ar
2a520 65 20 72 65 61 64 20 69 66 20 4e 0a 2a 2a 20 20  e read if N.**  
2a530 20 20 20 20 20 20 20 20 69 73 20 70 6f 73 69 74          is posit
2a540 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34  ive..**.** {F164
2a550 34 35 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  45} The [sqlite3
2a560 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65  _result_text16le
2a570 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74 65 72  (C,V,N,D)] inter
2a580 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65  face changes the
2a590 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74  .**          ret
2a5a0 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e  urn value of fun
2a5b0 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68  ction C to be th
2a5c0 65 20 55 54 46 31 36 20 6c 69 74 74 6c 65 2d 65  e UTF16 little-e
2a5d0 6e 64 69 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20  ndian.**        
2a5e0 20 20 73 74 72 69 6e 67 20 20 56 20 75 70 20 74    string  V up t
2a5f0 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74  hrough the first
2a600 20 7a 65 72 6f 20 6f 72 20 75 6e 74 69 6c 20 4e   zero or until N
2a610 20 62 79 74 65 73 20 61 72 65 20 72 65 61 64 20   bytes are read 
2a620 69 66 20 4e 0a 2a 2a 20 20 20 20 20 20 20 20 20  if N.**         
2a630 20 69 73 20 70 6f 73 69 74 69 76 65 2e 0a 2a 2a   is positive..**
2a640 0a 2a 2a 20 7b 46 31 36 34 34 38 7d 20 54 68 65  .** {F16448} The
2a650 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
2a660 5f 76 61 6c 75 65 28 43 2c 56 29 5d 20 69 6e 74  _value(C,V)] int
2a670 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74  erface changes t
2a680 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  he.**          r
2a690 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66  eturn value of f
2a6a0 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20  unction C to be 
2a6b0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
2a6c0 6f 62 6a 65 63 74 20 56 2e 0a 2a 2a 0a 2a 2a 20  object V..**.** 
2a6d0 7b 46 31 36 34 35 31 7d 20 54 68 65 20 5b 73 71  {F16451} The [sq
2a6e0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72  lite3_result_zer
2a6f0 6f 62 6c 6f 62 28 43 2c 4e 29 5d 20 69 6e 74 65  oblob(C,N)] inte
2a700 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68  rface changes th
2a710 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  e.**          re
2a720 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75  turn value of fu
2a730 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 61  nction C to be a
2a740 6e 20 4e 2d 62 79 74 65 20 62 6c 6f 62 20 6f 66  n N-byte blob of
2a750 20 61 6c 6c 20 7a 65 72 6f 73 2e 0a 2a 2a 0a 2a   all zeros..**.*
2a760 2a 20 7b 46 31 36 34 35 34 7d 20 54 68 65 20 5b  * {F16454} The [
2a770 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
2a780 72 72 6f 72 28 29 5d 20 61 6e 64 20 5b 73 71 6c  rror()] and [sql
2a790 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
2a7a0 72 31 36 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20  r16()].**       
2a7b0 20 20 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61     interfaces ma
2a7c0 6b 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  ke a copy of the
2a7d0 69 72 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  ir error message
2a7e0 20 73 74 72 69 6e 67 73 20 62 65 66 6f 72 65 0a   strings before.
2a7f0 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75  **          retu
2a800 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  rning..**.** {F1
2a810 36 34 35 37 7d 20 49 66 20 74 68 65 20 44 20 64  6457} If the D d
2a820 65 73 74 72 75 63 74 6f 72 20 70 61 72 61 6d 65  estructor parame
2a830 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
2a840 72 65 73 75 6c 74 5f 62 6c 6f 62 28 43 2c 56 2c  result_blob(C,V,
2a850 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  N,D)],.**       
2a860 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75     [sqlite3_resu
2a870 6c 74 5f 74 65 78 74 28 43 2c 56 2c 4e 2c 44 29  lt_text(C,V,N,D)
2a880 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  ], [sqlite3_resu
2a890 6c 74 5f 74 65 78 74 31 36 28 43 2c 56 2c 4e 2c  lt_text16(C,V,N,
2a8a0 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  D)],.**         
2a8b0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
2a8c0 5f 74 65 78 74 31 36 62 65 28 43 2c 56 2c 4e 2c  _text16be(C,V,N,
2a8d0 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20  D)], or.**      
2a8e0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73      [sqlite3_res
2a8f0 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 43 2c 56  ult_text16le(C,V
2a900 2c 4e 2c 44 29 5d 20 69 73 20 74 68 65 20 63 6f  ,N,D)] is the co
2a910 6e 73 74 61 6e 74 20 5b 53 51 4c 49 54 45 5f 53  nstant [SQLITE_S
2a920 54 41 54 49 43 5d 0a 2a 2a 20 20 20 20 20 20 20  TATIC].**       
2a930 20 20 20 74 68 65 6e 20 6e 6f 20 64 65 73 74 72     then no destr
2a940 75 63 74 6f 72 20 69 73 20 65 76 65 72 20 63 61  uctor is ever ca
2a950 6c 6c 65 64 20 6f 6e 20 74 68 65 20 70 6f 69 6e  lled on the poin
2a960 74 65 72 20 56 20 61 6e 64 20 53 51 4c 69 74 65  ter V and SQLite
2a970 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 73 73  .**          ass
2a980 75 6d 65 73 20 74 68 61 74 20 56 20 69 73 20 69  umes that V is i
2a990 6d 6d 75 74 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20  mmutable..**.** 
2a9a0 7b 46 31 36 34 36 30 7d 20 49 66 20 74 68 65 20  {F16460} If the 
2a9b0 44 20 64 65 73 74 72 75 63 74 6f 72 20 70 61 72  D destructor par
2a9c0 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
2a9d0 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 43  e3_result_blob(C
2a9e0 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20  ,V,N,D)],.**    
2a9f0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72        [sqlite3_r
2aa00 65 73 75 6c 74 5f 74 65 78 74 28 43 2c 56 2c 4e  esult_text(C,V,N
2aa10 2c 44 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 72  ,D)], [sqlite3_r
2aa20 65 73 75 6c 74 5f 74 65 78 74 31 36 28 43 2c 56  esult_text16(C,V
2aa30 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20  ,N,D)],.**      
2aa40 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73      [sqlite3_res
2aa50 75 6c 74 5f 74 65 78 74 31 36 62 65 28 43 2c 56  ult_text16be(C,V
2aa60 2c 4e 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20  ,N,D)], or.**   
2aa70 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
2aa80 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28  result_text16le(
2aa90 43 2c 56 2c 4e 2c 44 29 5d 20 69 73 20 74 68 65  C,V,N,D)] is the
2aaa0 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20 20 20 20   constant.**    
2aab0 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 54 52        [SQLITE_TR
2aac0 41 4e 53 49 45 4e 54 5d 20 74 68 65 6e 20 74 68  ANSIENT] then th
2aad0 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6b  e interfaces mak
2aae0 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  es a copy of the
2aaf0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e  .**          con
2ab00 74 65 6e 74 20 6f 66 20 56 20 61 6e 64 20 72 65  tent of V and re
2ab10 74 61 69 6e 73 20 74 68 65 20 63 6f 70 79 2e 0a  tains the copy..
2ab20 2a 2a 0a 2a 2a 20 7b 46 31 36 34 36 33 7d 20 49  **.** {F16463} I
2ab30 66 20 74 68 65 20 44 20 64 65 73 74 72 75 63 74  f the D destruct
2ab40 6f 72 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  or parameter to 
2ab50 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
2ab60 62 6c 6f 62 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a  blob(C,V,N,D)],.
2ab70 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
2ab80 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
2ab90 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 5b 73 71 6c  (C,V,N,D)], [sql
2aba0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
2abb0 31 36 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a  16(C,V,N,D)],.**
2abc0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
2abd0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
2abe0 62 65 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 6f 72  be(C,V,N,D)], or
2abf0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
2ac00 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
2ac10 74 31 36 6c 65 28 43 2c 56 2c 4e 2c 44 29 5d 20  t16le(C,V,N,D)] 
2ac20 69 73 20 73 6f 6d 65 20 76 61 6c 75 65 20 6f 74  is some value ot
2ac30 68 65 72 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20  her than.**     
2ac40 20 20 20 20 20 74 68 65 20 63 6f 6e 73 74 61 6e       the constan
2ac50 74 73 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49  ts [SQLITE_STATI
2ac60 43 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 54  C] and [SQLITE_T
2ac70 52 41 4e 53 49 45 4e 54 5d 20 74 68 65 6e 20 0a  RANSIENT] then .
2ac80 2a 2a 20 20 20 20 20 20 20 20 20 20 53 51 4c 69  **          SQLi
2ac90 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74  te will invoke t
2aca0 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 44 20  he destructor D 
2acb0 77 69 74 68 20 56 20 61 73 20 69 74 73 20 6f 6e  with V as its on
2acc0 6c 79 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 20  ly argument.**  
2acd0 20 20 20 20 20 20 20 20 77 68 65 6e 20 69 74 20          when it 
2ace0 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74  has finished wit
2acf0 68 20 74 68 65 20 56 20 76 61 6c 75 65 2e 0a 2a  h the V value..*
2ad00 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  /.void sqlite3_r
2ad10 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 74  esult_blob(sqlit
2ad20 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
2ad30 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76  st void*, int, v
2ad40 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
2ad50 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
2ad60 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74  ult_double(sqlit
2ad70 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f 75  e3_context*, dou
2ad80 62 6c 65 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  ble);.void sqlit
2ad90 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
2ada0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2adb0 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69  , const char*, i
2adc0 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  nt);.void sqlite
2add0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
2ade0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2adf0 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
2ae00 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  int);.void sqlit
2ae10 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
2ae20 74 6f 6f 62 69 67 28 73 71 6c 69 74 65 33 5f 63  toobig(sqlite3_c
2ae30 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73  ontext*);.void s
2ae40 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
2ae50 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74 65  ror_nomem(sqlite
2ae60 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69  3_context*);.voi
2ae70 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
2ae80 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73 71 6c 69  _error_code(sqli
2ae90 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
2aea0 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  t);.void sqlite3
2aeb0 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69  _result_int(sqli
2aec0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
2aed0 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  t);.void sqlite3
2aee0 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 73 71  _result_int64(sq
2aef0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
2af00 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a  sqlite3_int64);.
2af10 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
2af20 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33  ult_null(sqlite3
2af30 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64  _context*);.void
2af40 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2af50 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e  text(sqlite3_con
2af60 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61  text*, const cha
2af70 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  r*, int, void(*)
2af80 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
2af90 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
2afa0 78 74 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e  xt16(sqlite3_con
2afb0 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
2afc0 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  d*, int, void(*)
2afd0 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
2afe0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
2aff0 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 63  xt16le(sqlite3_c
2b000 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
2b010 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a  oid*, int,void(*
2b020 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20  )(void*));.void 
2b030 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
2b040 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f  ext16be(sqlite3_
2b050 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
2b060 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28  void*, int,void(
2b070 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64  *)(void*));.void
2b080 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2b090 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 63 6f  value(sqlite3_co
2b0a0 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f  ntext*, sqlite3_
2b0b0 76 61 6c 75 65 2a 29 3b 0a 76 6f 69 64 20 73 71  value*);.void sq
2b0c0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72  lite3_result_zer
2b0d0 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f  oblob(sqlite3_co
2b0e0 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a  ntext*, int n);.
2b0f0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2b100 20 44 65 66 69 6e 65 20 4e 65 77 20 43 6f 6c 6c   Define New Coll
2b110 61 74 69 6e 67 20 53 65 71 75 65 6e 63 65 73 20  ating Sequences 
2b120 7b 46 31 36 36 30 30 7d 0a 2a 2a 0a 2a 2a 20 54  {F16600}.**.** T
2b130 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61  hese functions a
2b140 72 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 6e  re used to add n
2b150 65 77 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  ew collation seq
2b160 75 65 6e 63 65 73 20 74 6f 20 74 68 65 0a 2a 2a  uences to the.**
2b170 20 5b 73 71 6c 69 74 65 33 2a 5d 20 68 61 6e 64   [sqlite3*] hand
2b180 6c 65 20 73 70 65 63 69 66 69 65 64 20 61 73 20  le specified as 
2b190 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
2b1a0 6e 74 2e 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e  nt. .**.** The n
2b1b0 61 6d 65 20 6f 66 20 74 68 65 20 6e 65 77 20 63  ame of the new c
2b1c0 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
2b1d0 65 20 69 73 20 73 70 65 63 69 66 69 65 64 20 61  e is specified a
2b1e0 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67  s a UTF-8 string
2b1f0 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  .** for sqlite3_
2b200 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
2b210 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  () and sqlite3_c
2b220 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
2b230 76 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55 54  v2().** and a UT
2b240 46 2d 31 36 20 73 74 72 69 6e 67 20 66 6f 72 20  F-16 string for 
2b250 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
2b260 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 20 49 6e  ollation16(). In
2b270 20 61 6c 6c 20 63 61 73 65 73 0a 2a 2a 20 74 68   all cases.** th
2b280 65 20 6e 61 6d 65 20 69 73 20 70 61 73 73 65 64  e name is passed
2b290 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66   as the second f
2b2a0 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74  unction argument
2b2b0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72  ..**.** The thir
2b2c0 64 20 61 72 67 75 6d 65 6e 74 20 6d 61 79 20 62  d argument may b
2b2d0 65 20 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e  e one of the con
2b2e0 73 74 61 6e 74 73 20 5b 53 51 4c 49 54 45 5f 55  stants [SQLITE_U
2b2f0 54 46 38 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  TF8],.** [SQLITE
2b300 5f 55 54 46 31 36 4c 45 5d 20 6f 72 20 5b 53 51  _UTF16LE] or [SQ
2b310 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 20 69  LITE_UTF16BE], i
2b320 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 74  ndicating that t
2b330 68 65 20 75 73 65 72 2d 73 75 70 70 6c 69 65 64  he user-supplied
2b340 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 65 78 70 65  .** routine expe
2b350 63 74 73 20 74 6f 20 62 65 20 70 61 73 73 65 64  cts to be passed
2b360 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72   pointers to str
2b370 69 6e 67 73 20 65 6e 63 6f 64 65 64 20 75 73 69  ings encoded usi
2b380 6e 67 20 55 54 46 2d 38 2c 0a 2a 2a 20 55 54 46  ng UTF-8,.** UTF
2b390 2d 31 36 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61  -16 little-endia
2b3a0 6e 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67 2d  n or UTF-16 big-
2b3b0 65 6e 64 69 61 6e 20 72 65 73 70 65 63 74 69 76  endian respectiv
2b3c0 65 6c 79 2e 20 54 68 65 0a 2a 2a 20 74 68 69 72  ely. The.** thir
2b3d0 64 20 61 72 67 75 6d 65 6e 74 20 6d 69 67 68 74  d argument might
2b3e0 20 61 6c 73 6f 20 62 65 20 5b 53 51 4c 49 54 45   also be [SQLITE
2b3f0 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20  _UTF16_ALIGNED] 
2b400 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74  to indicate that
2b410 0a 2a 2a 20 74 68 65 20 72 6f 75 74 69 6e 65 20  .** the routine 
2b420 65 78 70 65 63 74 73 20 70 6f 69 6e 74 65 72 73  expects pointers
2b430 20 74 6f 20 31 36 2d 62 69 74 20 77 6f 72 64 20   to 16-bit word 
2b440 61 6c 69 67 6e 65 64 20 73 74 72 69 6e 67 73 0a  aligned strings.
2b450 2a 2a 20 6f 66 20 55 54 46 31 36 20 69 6e 20 74  ** of UTF16 in t
2b460 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  he native byte o
2b470 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74  rder of the host
2b480 20 63 6f 6d 70 75 74 65 72 2e 0a 2a 2a 0a 2a 2a   computer..**.**
2b490 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   A pointer to th
2b4a0 65 20 75 73 65 72 20 73 75 70 70 6c 69 65 64 20  e user supplied 
2b4b0 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20  routine must be 
2b4c0 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69  passed as the fi
2b4d0 66 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e  fth.** argument.
2b4e0 20 20 49 66 20 69 74 20 69 73 20 4e 55 4c 4c 2c    If it is NULL,
2b4f0 20 74 68 69 73 20 69 73 20 74 68 65 20 73 61 6d   this is the sam
2b500 65 20 61 73 20 64 65 6c 65 74 69 6e 67 20 74 68  e as deleting th
2b510 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73  e collation.** s
2b520 65 71 75 65 6e 63 65 20 28 73 6f 20 74 68 61 74  equence (so that
2b530 20 53 51 4c 69 74 65 20 63 61 6e 6e 6f 74 20 63   SQLite cannot c
2b540 61 6c 6c 20 69 74 20 61 6e 79 6d 6f 72 65 29 2e  all it anymore).
2b550 0a 2a 2a 20 45 61 63 68 20 74 69 6d 65 20 74 68  .** Each time th
2b560 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a  e application.**
2b570 20 73 75 70 70 6c 69 65 64 20 66 75 6e 63 74 69   supplied functi
2b580 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69  on is invoked, i
2b590 74 20 69 73 20 70 61 73 73 65 64 20 61 20 63 6f  t is passed a co
2b5a0 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20  py of the void* 
2b5b0 70 61 73 73 65 64 20 61 73 0a 2a 2a 20 74 68 65  passed as.** the
2b5c0 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
2b5d0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61   to sqlite3_crea
2b5e0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 6f  te_collation() o
2b5f0 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65  r.** sqlite3_cre
2b600 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28  ate_collation16(
2b610 29 20 61 73 20 69 74 73 20 66 69 72 73 74 20 70  ) as its first p
2b620 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
2b630 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 61 72  The remaining ar
2b640 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 61  guments to the a
2b650 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c  pplication-suppl
2b660 69 65 64 20 72 6f 75 74 69 6e 65 20 61 72 65 20  ied routine are 
2b670 74 77 6f 20 73 74 72 69 6e 67 73 2c 0a 2a 2a 20  two strings,.** 
2b680 65 61 63 68 20 72 65 70 72 65 73 65 6e 74 65 64  each represented
2b690 20 62 79 20 61 20 28 6c 65 6e 67 74 68 2c 20 64   by a (length, d
2b6a0 61 74 61 29 20 70 61 69 72 20 61 6e 64 20 65 6e  ata) pair and en
2b6b0 63 6f 64 65 64 20 69 6e 20 74 68 65 20 65 6e 63  coded in the enc
2b6c0 6f 64 69 6e 67 0a 2a 2a 20 74 68 61 74 20 77 61  oding.** that wa
2b6d0 73 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  s passed as the 
2b6e0 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 77  third argument w
2b6f0 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f  hen the collatio
2b700 6e 20 73 65 71 75 65 6e 63 65 20 77 61 73 0a 2a  n sequence was.*
2b710 2a 20 72 65 67 69 73 74 65 72 65 64 2e 20 7b 45  * registered. {E
2b720 4e 44 7d 20 54 68 65 20 61 70 70 6c 69 63 61 74  ND} The applicat
2b730 69 6f 6e 20 64 65 66 69 6e 65 64 20 63 6f 6c 6c  ion defined coll
2b740 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 20 73 68  ation routine sh
2b750 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 6e  ould.** return n
2b760 65 67 61 74 69 76 65 2c 20 7a 65 72 6f 20 6f 72  egative, zero or
2b770 20 70 6f 73 69 74 69 76 65 20 69 66 0a 2a 2a 20   positive if.** 
2b780 74 68 65 20 66 69 72 73 74 20 73 74 72 69 6e 67  the first string
2b790 20 69 73 20 6c 65 73 73 20 74 68 61 6e 2c 20 65   is less than, e
2b7a0 71 75 61 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61  qual to, or grea
2b7b0 74 65 72 20 74 68 61 6e 20 74 68 65 20 73 65 63  ter than the sec
2b7c0 6f 6e 64 0a 2a 2a 20 73 74 72 69 6e 67 2e 20 69  ond.** string. i
2b7d0 2e 65 2e 20 28 53 54 52 49 4e 47 31 20 2d 20 53  .e. (STRING1 - S
2b7e0 54 52 49 4e 47 32 29 2e 0a 2a 2a 0a 2a 2a 20 54  TRING2)..**.** T
2b7f0 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  he sqlite3_creat
2b800 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29  e_collation_v2()
2b810 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69   works like sqli
2b820 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
2b830 74 69 6f 6e 28 29 0a 2a 2a 20 65 78 63 61 70 74  tion().** excapt
2b840 20 74 68 61 74 20 69 74 20 74 61 6b 65 73 20 61   that it takes a
2b850 6e 20 65 78 74 72 61 20 61 72 67 75 6d 65 6e 74  n extra argument
2b860 20 77 68 69 63 68 20 69 73 20 61 20 64 65 73 74   which is a dest
2b870 72 75 63 74 6f 72 20 66 6f 72 0a 2a 2a 20 74 68  ructor for.** th
2b880 65 20 63 6f 6c 6c 61 74 69 6f 6e 2e 20 20 54 68  e collation.  Th
2b890 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20  e destructor is 
2b8a0 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20  called when the 
2b8b0 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 0a 2a 2a 20  collation is.** 
2b8c0 64 65 73 74 72 6f 79 65 64 20 61 6e 64 20 69 73  destroyed and is
2b8d0 20 70 61 73 73 65 64 20 61 20 63 6f 70 79 20 6f   passed a copy o
2b8e0 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
2b8f0 61 6d 65 74 65 72 20 76 6f 69 64 2a 20 70 6f 69  ameter void* poi
2b900 6e 74 65 72 0a 2a 2a 20 6f 66 20 74 68 65 20 73  nter.** of the s
2b910 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
2b920 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a  llation_v2()..**
2b930 20 43 6f 6c 6c 61 74 69 6f 6e 73 20 61 72 65 20   Collations are 
2b940 64 65 73 74 72 6f 79 65 64 20 77 68 65 6e 0a 2a  destroyed when.*
2b950 2a 20 74 68 65 79 20 61 72 65 20 6f 76 65 72 72  * they are overr
2b960 69 64 64 65 6e 20 62 79 20 6c 61 74 65 72 20 63  idden by later c
2b970 61 6c 6c 73 20 74 6f 20 74 68 65 20 63 6f 6c 6c  alls to the coll
2b980 61 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 66  ation creation f
2b990 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 6f 72 20 77  unctions.** or w
2b9a0 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33  hen the [sqlite3
2b9b0 2a 5d 20 64 61 74 61 62 61 73 65 20 68 61 6e 64  *] database hand
2b9c0 6c 65 20 69 73 20 63 6c 6f 73 65 64 20 75 73 69  le is closed usi
2b9d0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73  ng [sqlite3_clos
2b9e0 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  e()]..**.** INVA
2b9f0 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  RIANTS:.**.** {F
2ba00 31 36 36 30 33 7d 20 41 20 73 75 63 63 65 73 73  16603} A success
2ba10 66 75 6c 20 63 61 6c 6c 20 74 6f 20 74 68 65 0a  ful call to the.
2ba20 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
2ba30 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
2ba40 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50  ation_v2(B,X,E,P
2ba50 2c 46 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65  ,F,D)] interface
2ba60 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 67  .**          reg
2ba70 69 73 74 65 72 73 20 66 75 6e 63 74 69 6f 6e 20  isters function 
2ba80 46 20 61 73 20 74 68 65 20 63 6f 6d 70 61 72 69  F as the compari
2ba90 73 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 75 73 65  son function use
2baa0 64 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20  d to.**         
2bab0 20 69 6d 70 6c 65 6d 65 6e 74 20 63 6f 6c 6c 61   implement colla
2bac0 74 69 6f 6e 20 58 20 6f 6e 20 5b 64 61 74 61 62  tion X on [datab
2bad0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
2bae0 42 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  B for.**        
2baf0 20 20 64 61 74 61 62 61 73 65 73 20 68 61 76 69    databases havi
2bb00 6e 67 20 65 6e 63 6f 64 69 6e 67 20 45 2e 0a 2a  ng encoding E..*
2bb10 2a 0a 2a 2a 20 7b 46 31 36 36 30 34 7d 20 53 51  *.** {F16604} SQ
2bb20 4c 69 74 65 20 75 6e 64 65 72 73 74 61 6e 64 73  Lite understands
2bb30 20 74 68 65 20 58 20 70 61 72 61 6d 65 74 65 72   the X parameter
2bb40 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   to.**          
2bb50 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2bb60 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c 58  collation_v2(B,X
2bb70 2c 45 2c 50 2c 46 2c 44 29 5d 20 61 73 20 61 20  ,E,P,F,D)] as a 
2bb80 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
2bb90 2a 2a 20 20 20 20 20 20 20 20 20 20 55 54 46 2d  **          UTF-
2bba0 38 20 73 74 72 69 6e 67 20 69 6e 20 77 68 69 63  8 string in whic
2bbb0 68 20 63 61 73 65 20 69 73 20 69 67 6e 6f 72 65  h case is ignore
2bbc0 64 20 66 6f 72 20 41 53 43 49 49 20 63 68 61 72  d for ASCII char
2bbd0 61 63 74 65 72 73 20 61 6e 64 0a 2a 2a 20 20 20  acters and.**   
2bbe0 20 20 20 20 20 20 20 69 73 20 73 69 67 6e 69 66         is signif
2bbf0 69 63 61 6e 74 20 66 6f 72 20 6e 6f 6e 2d 41 53  icant for non-AS
2bc00 43 49 49 20 63 68 61 72 61 63 74 65 72 73 2e 0a  CII characters..
2bc10 2a 2a 0a 2a 2a 20 7b 46 31 36 36 30 36 7d 20 53  **.** {F16606} S
2bc20 75 63 63 65 73 73 69 76 65 20 63 61 6c 6c 73 20  uccessive calls 
2bc30 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  to [sqlite3_crea
2bc40 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
2bc50 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 0a 2a 2a  B,X,E,P,F,D)].**
2bc60 20 20 20 20 20 20 20 20 20 20 77 69 74 68 20 74            with t
2bc70 68 65 20 73 61 6d 65 20 76 61 6c 75 65 73 20 66  he same values f
2bc80 6f 72 20 42 2c 20 58 2c 20 61 6e 64 20 45 2c 20  or B, X, and E, 
2bc90 6f 76 65 72 72 69 64 65 20 70 72 69 6f 72 20 76  override prior v
2bca0 61 6c 75 65 73 0a 2a 2a 20 20 20 20 20 20 20 20  alues.**        
2bcb0 20 20 6f 66 20 50 2c 20 46 2c 20 61 6e 64 20 44    of P, F, and D
2bcc0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36 30 39 7d  ..**.** {F16609}
2bcd0 20 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   The destructor 
2bce0 44 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 63 72  D in [sqlite3_cr
2bcf0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
2bd00 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 0a  2(B,X,E,P,F,D)].
2bd10 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 6e  **          is n
2bd20 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 69 74 20  ot NULL then it 
2bd30 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61  is called with a
2bd40 72 67 75 6d 65 6e 74 20 50 20 77 68 65 6e 20 74  rgument P when t
2bd50 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63  he.**          c
2bd60 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
2bd70 6e 20 69 73 20 64 72 6f 70 70 65 64 20 62 79 20  n is dropped by 
2bd80 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46  SQLite..**.** {F
2bd90 31 36 36 31 32 7d 20 41 20 63 6f 6c 6c 61 74 69  16612} A collati
2bda0 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64  ng function is d
2bdb0 72 6f 70 70 65 64 20 77 68 65 6e 20 69 74 20 69  ropped when it i
2bdc0 73 20 6f 76 65 72 6c 6f 61 64 65 64 2e 0a 2a 2a  s overloaded..**
2bdd0 0a 2a 2a 20 7b 46 31 36 36 31 35 7d 20 41 20 63  .** {F16615} A c
2bde0 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
2bdf0 6e 20 69 73 20 64 72 6f 70 70 65 64 20 77 68 65  n is dropped whe
2be00 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
2be10 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20  onnection.**    
2be20 20 20 20 20 20 20 69 73 20 63 6c 6f 73 65 64 20        is closed 
2be30 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63  using [sqlite3_c
2be40 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  lose()]..**.** {
2be50 46 31 36 36 31 38 7d 20 54 68 65 20 70 6f 69 6e  F16618} The poin
2be60 74 65 72 20 50 20 69 6e 20 5b 73 71 6c 69 74 65  ter P in [sqlite
2be70 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
2be80 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c  on_v2(B,X,E,P,F,
2be90 44 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  D)].**          
2bea0 69 73 20 70 61 73 73 65 64 20 74 68 72 6f 75 67  is passed throug
2beb0 68 20 61 73 20 74 68 65 20 66 69 72 73 74 20 70  h as the first p
2bec0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
2bed0 63 6f 6d 70 61 72 69 73 6f 6e 0a 2a 2a 20 20 20  comparison.**   
2bee0 20 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 20         function 
2bef0 46 20 66 6f 72 20 61 6c 6c 20 73 75 62 73 65 71  F for all subseq
2bf00 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73  uent invocations
2bf10 20 6f 66 20 46 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31   of F..**.** {F1
2bf20 36 36 32 31 7d 20 41 20 63 61 6c 6c 20 74 6f 20  6621} A call to 
2bf30 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2bf40 63 6f 6c 6c 61 74 69 6f 6e 28 42 2c 58 2c 45 2c  collation(B,X,E,
2bf50 50 2c 46 29 5d 20 69 73 20 65 78 61 63 74 6c 79  P,F)] is exactly
2bf60 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
2bf70 20 73 61 6d 65 20 61 73 20 61 20 63 61 6c 6c 20   same as a call 
2bf80 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  to [sqlite3_crea
2bf90 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
2bfa0 29 5d 20 77 69 74 68 0a 2a 2a 20 20 20 20 20 20  )] with.**      
2bfb0 20 20 20 20 74 68 65 20 73 61 6d 65 20 70 61 72      the same par
2bfc0 61 6d 65 74 65 72 73 20 61 6e 64 20 61 20 4e 55  ameters and a NU
2bfd0 4c 4c 20 64 65 73 74 72 75 63 74 6f 72 2e 0a 2a  LL destructor..*
2bfe0 2a 0a 2a 2a 20 7b 46 31 36 36 32 34 7d 20 46 6f  *.** {F16624} Fo
2bff0 6c 6c 6f 77 69 6e 67 20 61 20 5b 73 71 6c 69 74  llowing a [sqlit
2c000 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
2c010 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46  ion_v2(B,X,E,P,F
2c020 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  ,D)],.**        
2c030 20 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 68    SQLite uses th
2c040 65 20 63 6f 6d 70 61 72 69 73 6f 6e 20 66 75 6e  e comparison fun
2c050 63 74 69 6f 6e 20 46 20 66 6f 72 20 61 6c 6c 20  ction F for all 
2c060 74 65 78 74 20 63 6f 6d 70 61 72 69 73 6f 6e 0a  text comparison.
2c070 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 70 65 72  **          oper
2c080 61 74 69 6f 6e 73 20 6f 6e 20 5b 64 61 74 61 62  ations on [datab
2c090 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
2c0a0 42 20 6f 6e 20 74 65 78 74 20 76 61 6c 75 65 73  B on text values
2c0b0 20 74 68 61 74 0a 2a 2a 20 20 20 20 20 20 20 20   that.**        
2c0c0 20 20 75 73 65 20 74 68 65 20 63 6f 6c 6c 61 74    use the collat
2c0d0 69 6e 67 20 73 65 71 75 65 6e 63 65 20 6e 61 6d  ing sequence nam
2c0e0 65 20 58 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36  e X..**.** {F166
2c0f0 32 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  27} The [sqlite3
2c100 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
2c110 6e 31 36 28 42 2c 58 2c 45 2c 50 2c 46 29 5d 20  n16(B,X,E,P,F)] 
2c120 77 6f 72 6b 73 20 74 68 65 20 73 61 6d 65 0a 2a  works the same.*
2c130 2a 20 20 20 20 20 20 20 20 20 20 61 73 20 5b 73  *          as [s
2c140 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
2c150 6c 6c 61 74 69 6f 6e 28 42 2c 58 2c 45 2c 50 2c  llation(B,X,E,P,
2c160 46 29 5d 20 65 78 63 65 70 74 20 74 68 61 74 20  F)] except that 
2c170 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
2c180 63 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 20 58  collation name X
2c190 20 69 73 20 75 6e 64 65 72 73 74 6f 6f 64 20 61   is understood a
2c1a0 73 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69  s UTF-16 in nati
2c1b0 76 65 20 62 79 74 65 20 6f 72 64 65 72 0a 2a 2a  ve byte order.**
2c1c0 20 20 20 20 20 20 20 20 20 20 69 6e 73 74 65 61            instea
2c1d0 64 20 6f 66 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a  d of UTF-8..**.*
2c1e0 2a 20 7b 46 31 36 36 33 30 7d 20 57 68 65 6e 20  * {F16630} When 
2c1f0 6d 75 6c 74 69 70 6c 65 20 63 6f 6d 70 61 72 69  multiple compari
2c200 73 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 20 61 72  son functions ar
2c210 65 20 61 76 61 69 6c 61 62 6c 65 20 66 6f 72 20  e available for 
2c220 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20  the same.**     
2c230 20 20 20 20 20 63 6f 6c 6c 61 74 69 6e 67 20 73       collating s
2c240 65 71 75 65 6e 63 65 2c 20 53 51 4c 69 74 65 20  equence, SQLite 
2c250 63 68 6f 6f 73 65 73 20 74 68 65 20 6f 6e 65 20  chooses the one 
2c260 77 68 6f 73 65 20 74 65 78 74 20 65 6e 63 6f 64  whose text encod
2c270 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ing.**          
2c280 72 65 71 75 69 72 65 73 20 74 68 65 20 6c 65 61  requires the lea
2c290 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 63 6f 6e  st amount of con
2c2a0 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20 74 68 65  version from the
2c2b0 20 64 65 66 61 75 6c 74 0a 2a 2a 20 20 20 20 20   default.**     
2c2c0 20 20 20 20 20 74 65 78 74 20 65 6e 63 6f 64 69       text encodi
2c2d0 6e 67 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  ng of the databa
2c2e0 73 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  se..*/.int sqlit
2c2f0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
2c300 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  ion(.  sqlite3*,
2c310 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a   .  const char *
2c320 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54  zName, .  int eT
2c330 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a  extRep, .  void*
2c340 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72  ,.  int(*xCompar
2c350 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  e)(void*,int,con
2c360 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  st void*,int,con
2c370 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74  st void*).);.int
2c380 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2c390 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a 20 20  collation_v2(.  
2c3a0 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e  sqlite3*, .  con
2c3b0 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
2c3c0 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
2c3d0 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74   .  void*,.  int
2c3e0 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64  (*xCompare)(void
2c3f0 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
2c400 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
2c410 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73  *),.  void(*xDes
2c420 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a  troy)(void*).);.
2c430 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
2c440 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a  te_collation16(.
2c450 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63    sqlite3*, .  c
2c460 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
2c470 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  , .  int eTextRe
2c480 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69  p, .  void*,.  i
2c490 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f  nt(*xCompare)(vo
2c4a0 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
2c4b0 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
2c4c0 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  id*).);../*.** C
2c4d0 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c 61 74 69  API3REF: Collati
2c4e0 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c 6c 62 61  on Needed Callba
2c4f0 63 6b 73 20 7b 46 31 36 37 30 30 7d 0a 2a 2a 0a  cks {F16700}.**.
2c500 2a 2a 20 54 6f 20 61 76 6f 69 64 20 68 61 76 69  ** To avoid havi
2c510 6e 67 20 74 6f 20 72 65 67 69 73 74 65 72 20 61  ng to register a
2c520 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  ll collation seq
2c530 75 65 6e 63 65 73 20 62 65 66 6f 72 65 20 61 20  uences before a 
2c540 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 61 6e 20  database.** can 
2c550 62 65 20 75 73 65 64 2c 20 61 20 73 69 6e 67 6c  be used, a singl
2c560 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
2c570 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73  ion may be regis
2c580 74 65 72 65 64 20 77 69 74 68 20 74 68 65 0a 2a  tered with the.*
2c590 2a 20 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * database handl
2c5a0 65 20 74 6f 20 62 65 20 63 61 6c 6c 65 64 20 77  e to be called w
2c5b0 68 65 6e 65 76 65 72 20 61 6e 20 75 6e 64 65 66  henever an undef
2c5c0 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73  ined collation s
2c5d0 65 71 75 65 6e 63 65 20 69 73 0a 2a 2a 20 72 65  equence is.** re
2c5e0 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66  quired..**.** If
2c5f0 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73   the function is
2c600 20 72 65 67 69 73 74 65 72 65 64 20 75 73 69 6e   registered usin
2c610 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  g the sqlite3_co
2c620 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29  llation_needed()
2c630 20 41 50 49 2c 0a 2a 2a 20 74 68 65 6e 20 69 74   API,.** then it
2c640 20 69 73 20 70 61 73 73 65 64 20 74 68 65 20 6e   is passed the n
2c650 61 6d 65 73 20 6f 66 20 75 6e 64 65 66 69 6e 65  ames of undefine
2c660 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  d collation sequ
2c670 65 6e 63 65 73 20 61 73 20 73 74 72 69 6e 67 73  ences as strings
2c680 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 69 6e 20 55  .** encoded in U
2c690 54 46 2d 38 2e 20 7b 46 31 36 37 30 33 7d 20 49  TF-8. {F16703} I
2c6a0 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  f sqlite3_collat
2c6b0 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 20 69  ion_needed16() i
2c6c0 73 20 75 73 65 64 2c 20 74 68 65 20 6e 61 6d 65  s used, the name
2c6d0 73 0a 2a 2a 20 61 72 65 20 70 61 73 73 65 64 20  s.** are passed 
2c6e0 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6d 61 63  as UTF-16 in mac
2c6f0 68 69 6e 65 20 6e 61 74 69 76 65 20 62 79 74 65  hine native byte
2c700 20 6f 72 64 65 72 2e 20 41 20 63 61 6c 6c 20 74   order. A call t
2c710 6f 20 65 69 74 68 65 72 0a 2a 2a 20 66 75 6e 63  o either.** func
2c720 74 69 6f 6e 20 72 65 70 6c 61 63 65 73 20 61 6e  tion replaces an
2c730 79 20 65 78 69 73 74 69 6e 67 20 63 61 6c 6c 62  y existing callb
2c740 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  ack..**.** When 
2c750 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  the callback is 
2c760 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20 66 69 72  invoked, the fir
2c770 73 74 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73  st argument pass
2c780 65 64 20 69 73 20 61 20 63 6f 70 79 0a 2a 2a 20  ed is a copy.** 
2c790 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  of the second ar
2c7a0 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
2c7b0 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
2c7c0 65 64 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74  ed() or.** sqlit
2c7d0 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
2c7e0 64 65 64 31 36 28 29 2e 20 20 54 68 65 20 73 65  ded16().  The se
2c7f0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
2c800 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
2c810 20 68 61 6e 64 6c 65 2e 20 20 54 68 65 20 74 68   handle.  The th
2c820 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ird argument is 
2c830 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55  one of [SQLITE_U
2c840 54 46 38 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  TF8],.** [SQLITE
2c850 5f 55 54 46 31 36 42 45 5d 2c 20 6f 72 20 5b 53  _UTF16BE], or [S
2c860 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20  QLITE_UTF16LE], 
2c870 69 6e 64 69 63 61 74 69 6e 67 20 74 68 65 20 6d  indicating the m
2c880 6f 73 74 0a 2a 2a 20 64 65 73 69 72 61 62 6c 65  ost.** desirable
2c890 20 66 6f 72 6d 20 6f 66 20 74 68 65 20 63 6f 6c   form of the col
2c8a0 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20  lation sequence 
2c8b0 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65  function require
2c8c0 64 2e 0a 2a 2a 20 54 68 65 20 66 6f 75 72 74 68  d..** The fourth
2c8d0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
2c8e0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a  e name of the.**
2c8f0 20 72 65 71 75 69 72 65 64 20 63 6f 6c 6c 61 74   required collat
2c900 69 6f 6e 20 73 65 71 75 65 6e 63 65 2e 0a 2a 2a  ion sequence..**
2c910 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b  .** The callback
2c920 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64   function should
2c930 20 72 65 67 69 73 74 65 72 20 74 68 65 20 64 65   register the de
2c940 73 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20  sired collation 
2c950 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
2c960 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
2c970 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  on()], [sqlite3_
2c980 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
2c990 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71  16()], or.** [sq
2c9a0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
2c9b0 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2a  lation_v2()]..**
2c9c0 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
2c9d0 2a 2a 0a 2a 2a 20 7b 46 31 36 37 30 32 7d 20 41  **.** {F16702} A
2c9e0 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c   successful call
2c9f0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   to [sqlite3_col
2ca00 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 44 2c  lation_needed(D,
2ca10 50 2c 46 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  P,F)].**        
2ca20 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63 6f    or [sqlite3_co
2ca30 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36  llation_needed16
2ca40 28 44 2c 50 2c 46 29 5d 20 63 61 75 73 65 73 0a  (D,P,F)] causes.
2ca50 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
2ca60 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2ca70 74 69 6f 6e 5d 20 44 20 74 6f 20 69 6e 76 6f 6b  tion] D to invok
2ca80 65 20 63 61 6c 6c 62 61 63 6b 20 46 20 77 69 74  e callback F wit
2ca90 68 20 66 69 72 73 74 0a 2a 2a 20 20 20 20 20 20  h first.**      
2caa0 20 20 20 20 70 61 72 61 6d 65 74 65 72 20 50 20      parameter P 
2cab0 77 68 65 6e 65 76 65 72 20 69 74 20 6e 65 65 64  whenever it need
2cac0 73 20 61 20 63 6f 6d 70 61 72 69 73 6f 6e 20 66  s a comparison f
2cad0 75 6e 63 74 69 6f 6e 20 66 6f 72 20 61 0a 2a 2a  unction for a.**
2cae0 20 20 20 20 20 20 20 20 20 20 63 6f 6c 6c 61 74            collat
2caf0 69 6e 67 20 73 65 71 75 65 6e 63 65 20 74 68 61  ing sequence tha
2cb00 74 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 6b 6e  t it does not kn
2cb10 6f 77 20 61 62 6f 75 74 2e 0a 2a 2a 0a 2a 2a 20  ow about..**.** 
2cb20 7b 46 31 36 37 30 34 7d 20 45 61 63 68 20 73 75  {F16704} Each su
2cb30 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f  ccessful call to
2cb40 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74   [sqlite3_collat
2cb50 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d 20 6f 72  ion_needed()] or
2cb60 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
2cb70 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
2cb80 6e 65 65 64 65 64 31 36 28 29 5d 20 6f 76 65 72  needed16()] over
2cb90 72 69 64 65 73 20 74 68 65 20 63 61 6c 6c 62 61  rides the callba
2cba0 63 6b 20 72 65 67 69 73 74 65 72 65 64 0a 2a 2a  ck registered.**
2cbb0 20 20 20 20 20 20 20 20 20 20 6f 6e 20 74 68 65            on the
2cbc0 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20   same [database 
2cbd0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 62 79 20 70  connection] by p
2cbe0 72 69 6f 72 20 63 61 6c 6c 73 20 74 6f 20 65 69  rior calls to ei
2cbf0 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  ther.**         
2cc00 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
2cc10 2a 20 7b 46 31 36 37 30 36 7d 20 54 68 65 20 6e  * {F16706} The n
2cc20 61 6d 65 20 6f 66 20 74 68 65 20 72 65 71 75 65  ame of the reque
2cc30 73 74 65 64 20 63 6f 6c 6c 61 74 69 6e 67 20 66  sted collating f
2cc40 75 6e 63 74 69 6f 6e 20 70 61 73 73 65 64 20 69  unction passed i
2cc50 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  n the.**        
2cc60 20 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20    4th parameter 
2cc70 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
2cc80 69 73 20 69 6e 20 55 54 46 2d 38 20 69 66 20 74  is in UTF-8 if t
2cc90 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20  he callback.**  
2cca0 20 20 20 20 20 20 20 20 77 61 73 20 72 65 67 69          was regi
2ccb0 73 74 65 72 65 64 20 75 73 69 6e 67 20 5b 73 71  stered using [sq
2ccc0 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
2ccd0 6e 65 65 64 65 64 28 29 5d 20 61 6e 64 0a 2a 2a  needed()] and.**
2cce0 20 20 20 20 20 20 20 20 20 20 69 73 20 69 6e 20            is in 
2ccf0 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79  UTF-16 native by
2cd00 74 65 20 6f 72 64 65 72 20 69 66 20 74 68 65 20  te order if the 
2cd10 63 61 6c 6c 62 61 63 6b 20 77 61 73 0a 2a 2a 20  callback was.** 
2cd20 20 20 20 20 20 20 20 20 20 72 65 67 69 73 74 65           registe
2cd30 72 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  red using [sqlit
2cd40 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
2cd50 64 65 64 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  ded16()]..**.** 
2cd60 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2cd70 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
2cd80 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
2cd90 20 76 6f 69 64 2a 2c 20 0a 20 20 76 6f 69 64 28   void*, .  void(
2cda0 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33  *)(void*,sqlite3
2cdb0 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63  *,int eTextRep,c
2cdc0 6f 6e 73 74 20 63 68 61 72 2a 29 0a 29 3b 0a 69  onst char*).);.i
2cdd0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  nt sqlite3_colla
2cde0 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 0a 20  tion_needed16(. 
2cdf0 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f   sqlite3*, .  vo
2ce00 69 64 2a 2c 0a 20 20 76 6f 69 64 28 2a 29 28 76  id*,.  void(*)(v
2ce10 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e  oid*,sqlite3*,in
2ce20 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74  t eTextRep,const
2ce30 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a   void*).);../*.*
2ce40 2a 20 53 70 65 63 69 66 79 20 74 68 65 20 6b 65  * Specify the ke
2ce50 79 20 66 6f 72 20 61 6e 20 65 6e 63 72 79 70 74  y for an encrypt
2ce60 65 64 20 64 61 74 61 62 61 73 65 2e 20 20 54 68  ed database.  Th
2ce70 69 73 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c  is routine shoul
2ce80 64 20 62 65 0a 2a 2a 20 63 61 6c 6c 65 64 20 72  d be.** called r
2ce90 69 67 68 74 20 61 66 74 65 72 20 73 71 6c 69 74  ight after sqlit
2cea0 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a  e3_open()..**.**
2ceb0 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70   The code to imp
2cec0 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20  lement this API 
2ced0 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65  is not available
2cee0 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72   in the public r
2cef0 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c  elease.** of SQL
2cf00 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ite..*/.int sqli
2cf10 74 65 33 5f 6b 65 79 28 0a 20 20 73 71 6c 69 74  te3_key(.  sqlit
2cf20 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
2cf30 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
2cf40 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65  abase to be reke
2cf50 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  yed */.  const v
2cf60 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e  oid *pKey, int n
2cf70 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6b  Key     /* The k
2cf80 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ey */.);../*.** 
2cf90 43 68 61 6e 67 65 20 74 68 65 20 6b 65 79 20 6f  Change the key o
2cfa0 6e 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61  n an open databa
2cfb0 73 65 2e 20 20 49 66 20 74 68 65 20 63 75 72 72  se.  If the curr
2cfc0 65 6e 74 20 64 61 74 61 62 61 73 65 20 69 73 20  ent database is 
2cfd0 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79 70 74 65 64  not.** encrypted
2cfe0 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  , this routine w
2cff0 69 6c 6c 20 65 6e 63 72 79 70 74 20 69 74 2e 20  ill encrypt it. 
2d000 20 49 66 20 70 4e 65 77 3d 3d 30 20 6f 72 20 6e   If pNew==0 or n
2d010 4e 65 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a 20 64  New==0, the.** d
2d020 61 74 61 62 61 73 65 20 69 73 20 64 65 63 72 79  atabase is decry
2d030 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  pted..**.** The 
2d040 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  code to implemen
2d050 74 20 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f  t this API is no
2d060 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74  t available in t
2d070 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73  he public releas
2d080 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a  e.** of SQLite..
2d090 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72  */.int sqlite3_r
2d0a0 65 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20  ekey(.  sqlite3 
2d0b0 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
2d0c0 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
2d0d0 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64  se to be rekeyed
2d0e0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
2d0f0 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79   *pKey, int nKey
2d100 20 20 20 20 20 2f 2a 20 54 68 65 20 6e 65 77 20       /* The new 
2d110 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  key */.);../*.**
2d120 20 43 41 50 49 33 52 45 46 3a 20 20 53 75 73 70   CAPI3REF:  Susp
2d130 65 6e 64 20 45 78 65 63 75 74 69 6f 6e 20 46 6f  end Execution Fo
2d140 72 20 41 20 53 68 6f 72 74 20 54 69 6d 65 20 7b  r A Short Time {
2d150 46 31 30 35 33 30 7d 0a 2a 2a 0a 2a 2a 20 54 68  F10530}.**.** Th
2d160 65 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28  e sqlite3_sleep(
2d170 29 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61  ) function.** ca
2d180 75 73 65 73 20 74 68 65 20 63 75 72 72 65 6e 74  uses the current
2d190 20 74 68 72 65 61 64 20 74 6f 20 73 75 73 70 65   thread to suspe
2d1a0 6e 64 20 65 78 65 63 75 74 69 6f 6e 0a 2a 2a 20  nd execution.** 
2d1b0 66 6f 72 20 61 74 20 6c 65 61 73 74 20 61 20 6e  for at least a n
2d1c0 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65  umber of millise
2d1d0 63 6f 6e 64 73 20 73 70 65 63 69 66 69 65 64 20  conds specified 
2d1e0 69 6e 20 69 74 73 20 70 61 72 61 6d 65 74 65 72  in its parameter
2d1f0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6f  ..**.** If the o
2d200 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20  perating system 
2d210 64 6f 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74  does not support
2d220 20 73 6c 65 65 70 20 72 65 71 75 65 73 74 73 20   sleep requests 
2d230 77 69 74 68 20 0a 2a 2a 20 6d 69 6c 6c 69 73 65  with .** millise
2d240 63 6f 6e 64 20 74 69 6d 65 20 72 65 73 6f 6c 75  cond time resolu
2d250 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 74  tion, then the t
2d260 69 6d 65 20 77 69 6c 6c 20 62 65 20 72 6f 75 6e  ime will be roun
2d270 64 65 64 20 75 70 20 74 6f 20 0a 2a 2a 20 74 68  ded up to .** th
2d280 65 20 6e 65 61 72 65 73 74 20 73 65 63 6f 6e 64  e nearest second
2d290 2e 20 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  . The number of 
2d2a0 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20  milliseconds of 
2d2b0 73 6c 65 65 70 20 61 63 74 75 61 6c 6c 79 20 0a  sleep actually .
2d2c0 2a 2a 20 72 65 71 75 65 73 74 65 64 20 66 72 6f  ** requested fro
2d2d0 6d 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  m the operating 
2d2e0 73 79 73 74 65 6d 20 69 73 20 72 65 74 75 72 6e  system is return
2d2f0 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  ed..**.** SQLite
2d300 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 69 73   implements this
2d310 20 69 6e 74 65 72 66 61 63 65 20 62 79 20 63 61   interface by ca
2d320 6c 6c 69 6e 67 20 74 68 65 20 78 53 6c 65 65 70  lling the xSleep
2d330 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20  ().** method of 
2d340 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c  the default [sql
2d350 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
2d360 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
2d370 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 35 33  TS:.**.** {F1053
2d380 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  3} The [sqlite3_
2d390 73 6c 65 65 70 28 4d 29 5d 20 69 6e 74 65 72 66  sleep(M)] interf
2d3a0 61 63 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20  ace invokes the 
2d3b0 78 53 6c 65 65 70 0a 2a 2a 20 20 20 20 20 20 20  xSleep.**       
2d3c0 20 20 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65     method of the
2d3d0 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65   default [sqlite
2d3e0 33 5f 76 66 73 7c 56 46 53 5d 20 69 6e 20 6f 72  3_vfs|VFS] in or
2d3f0 64 65 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20  der to.**       
2d400 20 20 20 73 75 73 70 65 6e 64 20 65 78 65 63 75     suspend execu
2d410 74 69 6f 6e 20 6f 66 20 74 68 65 20 63 75 72 72  tion of the curr
2d420 65 6e 74 20 74 68 72 65 61 64 20 66 6f 72 20 61  ent thread for a
2d430 74 20 6c 65 61 73 74 0a 2a 2a 20 20 20 20 20 20  t least.**      
2d440 20 20 20 20 4d 20 6d 69 6c 6c 69 73 65 63 6f 6e      M millisecon
2d450 64 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 35 33  ds..**.** {F1053
2d460 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  6} The [sqlite3_
2d470 73 6c 65 65 70 28 4d 29 5d 20 69 6e 74 65 72 66  sleep(M)] interf
2d480 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
2d490 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 20 20 20  number of.**    
2d4a0 20 20 20 20 20 20 6d 69 6c 6c 69 73 65 63 6f 6e        millisecon
2d4b0 64 73 20 6f 66 20 73 6c 65 65 70 20 61 63 74 75  ds of sleep actu
2d4c0 61 6c 6c 79 20 72 65 71 75 65 73 74 65 64 20 6f  ally requested o
2d4d0 66 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 0a  f the operating.
2d4e0 2a 2a 20 20 20 20 20 20 20 20 20 20 73 79 73 74  **          syst
2d4f0 65 6d 2c 20 77 68 69 63 68 20 6d 69 67 68 74 20  em, which might 
2d500 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74  be larger than t
2d510 68 65 20 70 61 72 61 6d 65 74 65 72 20 4d 2e 0a  he parameter M..
2d520 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  */.int sqlite3_s
2d530 6c 65 65 70 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  leep(int);../*.*
2d540 2a 20 43 41 50 49 33 52 45 46 3a 20 20 4e 61 6d  * CAPI3REF:  Nam
2d550 65 20 4f 66 20 54 68 65 20 46 6f 6c 64 65 72 20  e Of The Folder 
2d560 48 6f 6c 64 69 6e 67 20 54 65 6d 70 6f 72 61 72  Holding Temporar
2d570 79 20 46 69 6c 65 73 20 7b 46 31 30 33 31 30 7d  y Files {F10310}
2d580 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 69 73 20 67  .**.** If this g
2d590 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 20 69  lobal variable i
2d5a0 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20  s made to point 
2d5b0 74 6f 20 61 20 73 74 72 69 6e 67 20 77 68 69 63  to a string whic
2d5c0 68 20 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65  h is.** the name
2d5d0 20 6f 66 20 61 20 66 6f 6c 64 65 72 20 28 61 2e   of a folder (a.
2d5e0 6b 61 2e 20 64 69 72 65 63 74 6f 72 79 29 2c 20  ka. directory), 
2d5f0 74 68 65 6e 20 61 6c 6c 20 74 65 6d 70 6f 72 61  then all tempora
2d600 72 79 20 66 69 6c 65 73 0a 2a 2a 20 63 72 65 61  ry files.** crea
2d610 74 65 64 20 62 79 20 53 51 4c 69 74 65 20 77 69  ted by SQLite wi
2d620 6c 6c 20 62 65 20 70 6c 61 63 65 64 20 69 6e 20  ll be placed in 
2d630 74 68 61 74 20 64 69 72 65 63 74 6f 72 79 2e 20  that directory. 
2d640 20 49 66 20 74 68 69 73 20 76 61 72 69 61 62 6c   If this variabl
2d650 65 0a 2a 2a 20 69 73 20 4e 55 4c 4c 20 70 6f 69  e.** is NULL poi
2d660 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74  nter, then SQLit
2d670 65 20 64 6f 65 73 20 61 20 73 65 61 72 63 68 20  e does a search 
2d680 66 6f 72 20 61 6e 20 61 70 70 72 6f 70 72 69 61  for an appropria
2d690 74 65 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20  te temporary.** 
2d6a0 66 69 6c 65 20 64 69 72 65 63 74 6f 72 79 2e 0a  file directory..
2d6b0 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20  **.** It is not 
2d6c0 73 61 66 65 20 74 6f 20 6d 6f 64 69 66 79 20 74  safe to modify t
2d6d0 68 69 73 20 76 61 72 69 61 62 6c 65 20 6f 6e 63  his variable onc
2d6e0 65 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e  e a database con
2d6f0 6e 65 63 74 69 6f 6e 0a 2a 2a 20 68 61 73 20 62  nection.** has b
2d700 65 65 6e 20 6f 70 65 6e 65 64 2e 20 20 49 74 20  een opened.  It 
2d710 69 73 20 69 6e 74 65 6e 64 65 64 20 74 68 61 74  is intended that
2d720 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 62   this variable b
2d730 65 20 73 65 74 20 6f 6e 63 65 0a 2a 2a 20 61 73  e set once.** as
2d740 20 70 61 72 74 20 6f 66 20 70 72 6f 63 65 73 73   part of process
2d750 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
2d760 61 6e 64 20 62 65 66 6f 72 65 20 61 6e 79 20 53  and before any S
2d770 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 0a  QLite interface.
2d780 2a 2a 20 72 6f 75 74 69 6e 65 73 20 68 61 76 65  ** routines have
2d790 20 62 65 65 6e 20 63 61 6c 6c 20 61 6e 64 20 72   been call and r
2d7a0 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65 64 20  emain unchanged 
2d7b0 74 68 65 72 65 61 66 74 65 72 2e 0a 2a 2f 0a 53  thereafter..*/.S
2d7c0 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 63 68 61  QLITE_EXTERN cha
2d7d0 72 20 2a 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f  r *sqlite3_temp_
2d7e0 64 69 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a  directory;../*.*
2d7f0 2a 20 43 41 50 49 33 52 45 46 3a 20 20 54 65 73  * CAPI3REF:  Tes
2d800 74 20 54 6f 20 53 65 65 20 49 66 20 54 68 65 20  t To See If The 
2d810 44 61 74 61 62 61 73 65 20 49 73 20 49 6e 20 41  Database Is In A
2d820 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d 6f 64 65 20  uto-Commit Mode 
2d830 7b 46 31 32 39 33 30 7d 0a 2a 2a 0a 2a 2a 20 54  {F12930}.**.** T
2d840 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  he sqlite3_get_a
2d850 75 74 6f 63 6f 6d 6d 69 74 28 29 20 69 6e 74 65  utocommit() inte
2d860 72 66 61 63 65 73 20 72 65 74 75 72 6e 73 20 6e  rfaces returns n
2d870 6f 6e 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20 7a 65  on-zero or.** ze
2d880 72 6f 20 69 66 20 74 68 65 20 67 69 76 65 6e 20  ro if the given 
2d890 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2d8a0 69 6f 6e 20 69 73 20 6f 72 20 69 73 20 6e 6f 74  ion is or is not
2d8b0 20 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 20 6d   in autocommit m
2d8c0 6f 64 65 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69  ode,.** respecti
2d8d0 76 65 6c 79 2e 20 20 20 41 75 74 6f 63 6f 6d 6d  vely.   Autocomm
2d8e0 69 74 20 6d 6f 64 65 20 69 73 20 6f 6e 0a 2a 2a  it mode is on.**
2d8f0 20 62 79 20 64 65 66 61 75 6c 74 2e 20 20 41 75   by default.  Au
2d900 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73  tocommit mode is
2d910 20 64 69 73 61 62 6c 65 64 20 62 79 20 61 20 5b   disabled by a [
2d920 42 45 47 49 4e 5d 20 73 74 61 74 65 6d 65 6e 74  BEGIN] statement
2d930 2e 0a 2a 2a 20 41 75 74 6f 63 6f 6d 6d 69 74 20  ..** Autocommit 
2d940 6d 6f 64 65 20 69 73 20 72 65 65 6e 61 62 6c 65  mode is reenable
2d950 64 20 62 79 20 61 20 5b 43 4f 4d 4d 49 54 5d 20  d by a [COMMIT] 
2d960 6f 72 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a  or [ROLLBACK]..*
2d970 2a 0a 2a 2a 20 49 66 20 63 65 72 74 61 69 6e 20  *.** If certain 
2d980 6b 69 6e 64 73 20 6f 66 20 65 72 72 6f 72 73 20  kinds of errors 
2d990 6f 63 63 75 72 20 6f 6e 20 61 20 73 74 61 74 65  occur on a state
2d9a0 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20 6d 75  ment within a mu
2d9b0 6c 74 69 2d 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  lti-statement.**
2d9c0 20 74 72 61 6e 73 61 63 74 69 6f 6e 73 20 28 65   transactions (e
2d9d0 72 72 6f 72 73 20 69 6e 63 6c 75 64 69 6e 67 20  rrors including 
2d9e0 5b 53 51 4c 49 54 45 5f 46 55 4c 4c 5d 2c 20 5b  [SQLITE_FULL], [
2d9f0 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 2c 20 0a  SQLITE_IOERR], .
2da00 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  ** [SQLITE_NOMEM
2da10 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  ], [SQLITE_BUSY]
2da20 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 49 4e  , and [SQLITE_IN
2da30 54 45 52 52 55 50 54 5d 29 20 74 68 65 6e 20 74  TERRUPT]) then t
2da40 68 65 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f  he.** transactio
2da50 6e 20 6d 69 67 68 74 20 62 65 20 72 6f 6c 6c 65  n might be rolle
2da60 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63  d back automatic
2da70 61 6c 6c 79 2e 20 20 54 68 65 20 6f 6e 6c 79 20  ally.  The only 
2da80 77 61 79 20 74 6f 0a 2a 2a 20 66 69 6e 64 20 6f  way to.** find o
2da90 75 74 20 69 66 20 53 51 4c 69 74 65 20 61 75 74  ut if SQLite aut
2daa0 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65  omatically rolle
2dab0 64 20 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73  d back the trans
2dac0 61 63 74 69 6f 6e 20 61 66 74 65 72 0a 2a 2a 20  action after.** 
2dad0 61 6e 20 65 72 72 6f 72 20 69 73 20 74 6f 20 75  an error is to u
2dae0 73 65 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  se this function
2daf0 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
2db00 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 33  TS:.**.** {F1293
2db10 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
2db20 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 44  get_autocommit(D
2db30 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
2db40 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72  urns non-zero or
2db50 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72  .**          zer
2db60 6f 20 69 66 20 74 68 65 20 5b 64 61 74 61 62 61  o if the [databa
2db70 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
2db80 20 69 73 20 6f 72 20 69 73 20 6e 6f 74 20 69 6e   is or is not in
2db90 20 61 75 74 6f 63 6f 6d 6d 69 74 0a 2a 2a 20 20   autocommit.**  
2dba0 20 20 20 20 20 20 20 20 6d 6f 64 65 2c 20 72 65          mode, re
2dbb0 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a  spectively..**.*
2dbc0 2a 20 7b 46 31 32 39 33 32 7d 20 41 75 74 6f 63  * {F12932} Autoc
2dbd0 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 6f 6e  ommit mode is on
2dbe0 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a   by default..**.
2dbf0 2a 2a 20 7b 46 31 32 39 33 33 7d 20 41 75 74 6f  ** {F12933} Auto
2dc00 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 64  commit mode is d
2dc10 69 73 61 62 6c 65 64 20 62 79 20 61 20 73 75 63  isabled by a suc
2dc20 63 65 73 73 66 75 6c 20 5b 42 45 47 49 4e 5d 20  cessful [BEGIN] 
2dc30 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a  statement..**.**
2dc40 20 7b 46 31 32 39 33 34 7d 20 41 75 74 6f 63 6f   {F12934} Autoco
2dc50 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 65 6e 61  mmit mode is ena
2dc60 62 6c 65 64 20 62 79 20 61 20 73 75 63 63 65 73  bled by a succes
2dc70 73 66 75 6c 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72  sful [COMMIT] or
2dc80 20 5b 52 4f 4c 4c 42 41 43 4b 5d 0a 2a 2a 20 20   [ROLLBACK].**  
2dc90 20 20 20 20 20 20 20 20 73 74 61 74 65 6d 65 6e          statemen
2dca0 74 2e 0a 2a 2a 20 0a 2a 2a 0a 2a 2a 20 4c 49 4d  t..** .**.** LIM
2dcb0 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a 2a 0a 2a 2a  ITATIONS:.***.**
2dcc0 20 7b 55 31 32 39 33 36 7d 20 49 66 20 61 6e 6f   {U12936} If ano
2dcd0 74 68 65 72 20 74 68 72 65 61 64 20 63 68 61 6e  ther thread chan
2dce0 67 65 73 20 74 68 65 20 61 75 74 6f 63 6f 6d 6d  ges the autocomm
2dcf0 69 74 20 73 74 61 74 75 73 20 6f 66 20 74 68 65  it status of the
2dd00 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 20 20 20   database.**    
2dd10 20 20 20 20 20 20 63 6f 6e 6e 65 63 74 69 6f 6e        connection
2dd20 20 77 68 69 6c 65 20 74 68 69 73 20 72 6f 75 74   while this rout
2dd30 69 6e 65 20 69 73 20 72 75 6e 6e 69 6e 67 2c 20  ine is running, 
2dd40 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20  then the return 
2dd50 76 61 6c 75 65 0a 2a 2a 20 20 20 20 20 20 20 20  value.**        
2dd60 20 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a    is undefined..
2dd70 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67  */.int sqlite3_g
2dd80 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 73 71  et_autocommit(sq
2dd90 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
2dda0 43 41 50 49 33 52 45 46 3a 20 20 46 69 6e 64 20  CAPI3REF:  Find 
2ddb0 54 68 65 20 44 61 74 61 62 61 73 65 20 48 61 6e  The Database Han
2ddc0 64 6c 65 20 4f 66 20 41 20 50 72 65 70 61 72 65  dle Of A Prepare
2ddd0 64 20 53 74 61 74 65 6d 65 6e 74 20 7b 46 31 33  d Statement {F13
2dde0 31 32 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  120}.**.** The s
2ddf0 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65  qlite3_db_handle
2de00 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 65   interface.** re
2de10 74 75 72 6e 73 20 74 68 65 20 5b 73 71 6c 69 74  turns the [sqlit
2de20 65 33 2a 5d 20 64 61 74 61 62 61 73 65 20 68 61  e3*] database ha
2de30 6e 64 6c 65 20 74 6f 20 77 68 69 63 68 20 61 0a  ndle to which a.
2de40 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
2de50 74 65 6d 65 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e  tement] belongs.
2de60 0a 2a 2a 20 54 68 65 20 64 61 74 61 62 61 73 65  .** The database
2de70 20 68 61 6e 64 6c 65 20 72 65 74 75 72 6e 65 64   handle returned
2de80 20 62 79 20 73 71 6c 69 74 65 33 5f 64 62 5f 68   by sqlite3_db_h
2de90 61 6e 64 6c 65 0a 2a 2a 20 69 73 20 74 68 65 20  andle.** is the 
2dea0 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 68 61  same database ha
2deb0 6e 64 6c 65 20 74 68 61 74 20 77 61 73 0a 2a 2a  ndle that was.**
2dec0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
2ded0 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ent to the [sqli
2dee0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
2def0 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74  ] or its variant
2df00 73 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 75 73  s.** that was us
2df10 65 64 20 74 6f 20 63 72 65 61 74 65 20 74 68 65  ed to create the
2df20 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68   statement in th
2df30 65 20 66 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a  e first place..*
2df40 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
2df50 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 31 32 33 7d 20  .**.** {F13123} 
2df60 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f  The [sqlite3_db_
2df70 68 61 6e 64 6c 65 28 53 29 5d 20 69 6e 74 65 72  handle(S)] inter
2df80 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70  face returns a p
2df90 6f 69 6e 74 65 72 0a 2a 2a 20 20 20 20 20 20 20  ointer.**       
2dfa0 20 20 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62     to the [datab
2dfb0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
2dfc0 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 0a  associated with.
2dfd0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65  **          [pre
2dfe0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2dff0 20 53 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a   S..*/.sqlite3 *
2e000 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c  sqlite3_db_handl
2e010 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  e(sqlite3_stmt*)
2e020 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  ;.../*.** CAPI3R
2e030 45 46 3a 20 43 6f 6d 6d 69 74 20 41 6e 64 20 52  EF: Commit And R
2e040 6f 6c 6c 62 61 63 6b 20 4e 6f 74 69 66 69 63 61  ollback Notifica
2e050 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 20 7b  tion Callbacks {
2e060 46 31 32 39 35 30 7d 0a 2a 2a 0a 2a 2a 20 54 68  F12950}.**.** Th
2e070 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74  e sqlite3_commit
2e080 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63  _hook() interfac
2e090 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61  e registers a ca
2e0a0 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69  llback.** functi
2e0b0 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64  on to be invoked
2e0c0 20 77 68 65 6e 65 76 65 72 20 61 20 74 72 61 6e   whenever a tran
2e0d0 73 61 63 74 69 6f 6e 20 69 73 20 63 6f 6d 6d 69  saction is commi
2e0e0 74 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 63 61 6c  tted..** Any cal
2e0f0 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61 20 70  lback set by a p
2e100 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20  revious call to 
2e110 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68  sqlite3_commit_h
2e120 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65  ook().** for the
2e130 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
2e140 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65  onnection is ove
2e150 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 54 68 65 20  rridden..** The 
2e160 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b  sqlite3_rollback
2e170 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63  _hook() interfac
2e180 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61  e registers a ca
2e190 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69  llback.** functi
2e1a0 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64  on to be invoked
2e1b0 20 77 68 65 6e 65 76 65 72 20 61 20 74 72 61 6e   whenever a tran
2e1c0 73 61 63 74 69 6f 6e 20 69 73 20 63 6f 6d 6d 69  saction is commi
2e1d0 74 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 63 61 6c  tted..** Any cal
2e1e0 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61 20 70  lback set by a p
2e1f0 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20  revious call to 
2e200 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68  sqlite3_commit_h
2e210 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65  ook().** for the
2e220 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
2e230 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65  onnection is ove
2e240 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 54 68 65 20  rridden..** The 
2e250 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20 69 73  pArg argument is
2e260 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 0a   passed through.
2e270 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  ** to the callba
2e280 63 6b 2e 20 20 49 66 20 74 68 65 20 63 61 6c 6c  ck.  If the call
2e290 62 61 63 6b 20 6f 6e 20 61 20 63 6f 6d 6d 69 74  back on a commit
2e2a0 20 68 6f 6f 6b 20 66 75 6e 63 74 69 6f 6e 20 0a   hook function .
2e2b0 2a 2a 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  ** returns non-z
2e2c0 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 63 6f  ero, then the co
2e2d0 6d 6d 69 74 20 69 73 20 63 6f 6e 76 65 72 74 65  mmit is converte
2e2e0 64 20 69 6e 74 6f 20 61 20 72 6f 6c 6c 62 61 63  d into a rollbac
2e2f0 6b 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74  k..**.** If anot
2e300 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 77 61 73  her function was
2e310 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 67 69   previously regi
2e320 73 74 65 72 65 64 2c 20 69 74 73 0a 2a 2a 20 70  stered, its.** p
2e330 41 72 67 20 76 61 6c 75 65 20 69 73 20 72 65 74  Arg value is ret
2e340 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73  urned.  Otherwis
2e350 65 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e  e NULL is return
2e360 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74  ed..**.** Regist
2e370 65 72 69 6e 67 20 61 20 4e 55 4c 4c 20 66 75 6e  ering a NULL fun
2e380 63 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 20 74  ction disables t
2e390 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a  he callback..**.
2e3a0 2a 2a 20 46 6f 72 20 74 68 65 20 70 75 72 70 6f  ** For the purpo
2e3b0 73 65 73 20 6f 66 20 74 68 69 73 20 41 50 49 2c  ses of this API,
2e3c0 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69   a transaction i
2e3d0 73 20 73 61 69 64 20 74 6f 20 68 61 76 65 20 62  s said to have b
2e3e0 65 65 6e 20 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62  een .** rolled b
2e3f0 61 63 6b 20 69 66 20 61 6e 20 65 78 70 6c 69 63  ack if an explic
2e400 69 74 20 22 52 4f 4c 4c 42 41 43 4b 22 20 73 74  it "ROLLBACK" st
2e410 61 74 65 6d 65 6e 74 20 69 73 20 65 78 65 63 75  atement is execu
2e420 74 65 64 2c 20 6f 72 0a 2a 2a 20 61 6e 20 65 72  ted, or.** an er
2e430 72 6f 72 20 6f 72 20 63 6f 6e 73 74 72 61 69 6e  ror or constrain
2e440 74 20 63 61 75 73 65 73 20 61 6e 20 69 6d 70 6c  t causes an impl
2e450 69 63 69 74 20 72 6f 6c 6c 62 61 63 6b 20 74 6f  icit rollback to
2e460 20 6f 63 63 75 72 2e 0a 2a 2a 20 54 68 65 20 72   occur..** The r
2e470 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c 62 61 63 6b  ollback callback
2e480 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20   is not invoked 
2e490 69 66 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  if a transaction
2e4a0 20 69 73 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63   is.** automatic
2e4b0 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ally rolled back
2e4c0 20 62 65 63 61 75 73 65 20 74 68 65 20 64 61 74   because the dat
2e4d0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2e4e0 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 54   is closed..** T
2e4f0 68 65 20 72 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c  he rollback call
2e500 62 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f  back is not invo
2e510 6b 65 64 20 69 66 20 61 20 74 72 61 6e 73 61 63  ked if a transac
2e520 74 69 6f 6e 20 69 73 0a 2a 2a 20 72 6f 6c 6c 65  tion is.** rolle
2e530 64 20 62 61 63 6b 20 62 65 63 61 75 73 65 20 61  d back because a
2e540 20 63 6f 6d 6d 69 74 20 63 61 6c 6c 62 61 63 6b   commit callback
2e550 20 72 65 74 75 72 6e 65 64 20 6e 6f 6e 2d 7a 65   returned non-ze
2e560 72 6f 2e 0a 2a 2a 20 3c 74 6f 64 6f 3e 20 43 68  ro..** <todo> Ch
2e570 65 63 6b 20 6f 6e 20 74 68 69 73 20 3c 2f 74 6f  eck on this </to
2e580 64 6f 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  do>.**.** These 
2e590 61 72 65 20 65 78 70 65 72 69 6d 65 6e 74 61 6c  are experimental
2e5a0 20 69 6e 74 65 72 66 61 63 65 73 20 61 6e 64 20   interfaces and 
2e5b0 61 72 65 20 73 75 62 6a 65 63 74 20 74 6f 20 63  are subject to c
2e5c0 68 61 6e 67 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  hange..**.** INV
2e5d0 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
2e5e0 46 31 32 39 35 31 7d 20 54 68 65 20 5b 73 71 6c  F12951} The [sql
2e5f0 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b  ite3_commit_hook
2e600 28 44 2c 46 2c 50 29 5d 20 69 6e 74 65 72 66 61  (D,F,P)] interfa
2e610 63 65 20 72 65 67 69 73 74 65 72 73 20 74 68 65  ce registers the
2e620 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c  .**          cal
2e630 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 46  lback function F
2e640 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77   to be invoked w
2e650 69 74 68 20 61 72 67 75 6d 65 6e 74 20 50 20 77  ith argument P w
2e660 68 65 6e 65 76 65 72 0a 2a 2a 20 20 20 20 20 20  henever.**      
2e670 20 20 20 20 61 20 74 72 61 6e 73 61 63 74 69 6f      a transactio
2e680 6e 20 63 6f 6d 6d 69 74 73 20 6f 6e 20 5b 64 61  n commits on [da
2e690 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2e6a0 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  n] D..**.** {F12
2e6b0 39 35 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  952} The [sqlite
2e6c0 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c  3_commit_hook(D,
2e6d0 46 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20  F,P)] interface 
2e6e0 72 65 74 75 72 6e 73 20 74 68 65 20 50 0a 2a 2a  returns the P.**
2e6f0 20 20 20 20 20 20 20 20 20 20 61 72 67 75 6d 65            argume
2e700 6e 74 20 66 72 6f 6d 20 74 68 65 20 70 72 65 76  nt from the prev
2e710 69 6f 75 73 20 63 61 6c 6c 20 77 69 74 68 20 74  ious call with t
2e720 68 65 20 73 61 6d 65 20 0a 2a 2a 20 20 20 20 20  he same .**     
2e730 20 20 20 20 20 5b 64 61 74 61 62 61 73 65 20 63       [database c
2e740 6f 6e 6e 65 63 74 69 6f 6e 20 5d 20 44 20 2c 20  onnection ] D , 
2e750 6f 72 20 4e 55 4c 4c 20 6f 6e 20 74 68 65 20 66  or NULL on the f
2e760 69 72 73 74 20 63 61 6c 6c 0a 2a 2a 20 20 20 20  irst call.**    
2e770 20 20 20 20 20 20 66 6f 72 20 61 20 70 61 72 74        for a part
2e780 69 63 75 6c 61 72 20 5b 64 61 74 61 62 61 73 65  icular [database
2e790 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a   connection] D..
2e7a0 2a 2a 0a 2a 2a 20 7b 46 31 32 39 35 33 7d 20 45  **.** {F12953} E
2e7b0 61 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ach call to [sql
2e7c0 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b  ite3_commit_hook
2e7d0 28 29 5d 20 6f 76 65 72 77 72 69 74 65 73 20 74  ()] overwrites t
2e7e0 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20  he callback.**  
2e7f0 20 20 20 20 20 20 20 20 72 65 67 69 73 74 65 72          register
2e800 65 64 20 62 79 20 70 72 69 6f 72 20 63 61 6c 6c  ed by prior call
2e810 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 35 34  s..**.** {F12954
2e820 7d 20 49 66 20 74 68 65 20 46 20 61 72 67 75 6d  } If the F argum
2e830 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ent to [sqlite3_
2e840 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c 46 2c  commit_hook(D,F,
2e850 50 29 5d 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20 20  P)] is NULL.**  
2e860 20 20 20 20 20 20 20 20 74 68 65 6e 20 74 68 65          then the
2e870 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 63 61 6c   commit hook cal
2e880 6c 62 61 63 6b 20 69 73 20 63 61 6e 63 65 6c 6c  lback is cancell
2e890 65 64 20 61 6e 64 20 6e 6f 20 63 61 6c 6c 62 61  ed and no callba
2e8a0 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  ck.**          i
2e8b0 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 61  s invoked when a
2e8c0 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6d   transaction com
2e8d0 6d 69 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  mits..**.** {F12
2e8e0 39 35 35 7d 20 49 66 20 74 68 65 20 63 6f 6d 6d  955} If the comm
2e8f0 69 74 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  it callback retu
2e900 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 74 68 65  rns non-zero the
2e910 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 69 73 0a  n the commit is.
2e920 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e 76  **          conv
2e930 65 72 74 65 64 20 69 6e 74 6f 20 61 20 72 6f 6c  erted into a rol
2e940 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  lback..**.** {F1
2e950 32 39 36 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  2961} The [sqlit
2e960 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b  e3_rollback_hook
2e970 28 44 2c 46 2c 50 29 5d 20 69 6e 74 65 72 66 61  (D,F,P)] interfa
2e980 63 65 20 72 65 67 69 73 74 65 72 73 20 74 68 65  ce registers the
2e990 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c  .**          cal
2e9a0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 46  lback function F
2e9b0 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77   to be invoked w
2e9c0 69 74 68 20 61 72 67 75 6d 65 6e 74 20 50 20 77  ith argument P w
2e9d0 68 65 6e 65 76 65 72 0a 2a 2a 20 20 20 20 20 20  henever.**      
2e9e0 20 20 20 20 61 20 74 72 61 6e 73 61 63 74 69 6f      a transactio
2e9f0 6e 20 72 6f 6c 6c 73 20 62 61 63 6b 20 6f 6e 20  n rolls back on 
2ea00 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2ea10 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b  tion] D..**.** {
2ea20 46 31 32 39 36 32 7d 20 54 68 65 20 5b 73 71 6c  F12962} The [sql
2ea30 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f  ite3_rollback_ho
2ea40 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 6e 74 65 72  ok(D,F,P)] inter
2ea50 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
2ea60 20 50 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61   P.**          a
2ea70 72 67 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68 65  rgument from the
2ea80 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 77   previous call w
2ea90 69 74 68 20 74 68 65 20 73 61 6d 65 20 0a 2a 2a  ith the same .**
2eaa0 20 20 20 20 20 20 20 20 20 20 5b 64 61 74 61 62            [datab
2eab0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 5d  ase connection ]
2eac0 20 44 20 2c 20 6f 72 20 4e 55 4c 4c 20 6f 6e 20   D , or NULL on 
2ead0 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 0a 2a  the first call.*
2eae0 2a 20 20 20 20 20 20 20 20 20 20 66 6f 72 20 61  *          for a
2eaf0 20 70 61 72 74 69 63 75 6c 61 72 20 5b 64 61 74   particular [dat
2eb00 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2eb10 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39  ] D..**.** {F129
2eb20 36 33 7d 20 45 61 63 68 20 63 61 6c 6c 20 74 6f  63} Each call to
2eb30 20 5b 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61   [sqlite3_rollba
2eb40 63 6b 5f 68 6f 6f 6b 28 29 5d 20 6f 76 65 72 77  ck_hook()] overw
2eb50 72 69 74 65 73 20 74 68 65 20 63 61 6c 6c 62 61  rites the callba
2eb60 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  ck.**          r
2eb70 65 67 69 73 74 65 72 65 64 20 62 79 20 70 72 69  egistered by pri
2eb80 6f 72 20 63 61 6c 6c 73 2e 0a 2a 2a 0a 2a 2a 20  or calls..**.** 
2eb90 7b 46 31 32 39 36 34 7d 20 49 66 20 74 68 65 20  {F12964} If the 
2eba0 46 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73  F argument to [s
2ebb0 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f  qlite3_rollback_
2ebc0 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 73 20  hook(D,F,P)] is 
2ebd0 4e 55 4c 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20  NULL.**         
2ebe0 20 74 68 65 6e 20 74 68 65 20 72 6f 6c 6c 62 61   then the rollba
2ebf0 63 6b 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b  ck hook callback
2ec00 20 69 73 20 63 61 6e 63 65 6c 6c 65 64 20 61 6e   is cancelled an
2ec10 64 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  d no callback.**
2ec20 20 20 20 20 20 20 20 20 20 20 69 73 20 69 6e 76            is inv
2ec30 6f 6b 65 64 20 77 68 65 6e 20 61 20 74 72 61 6e  oked when a tran
2ec40 73 61 63 74 69 6f 6e 20 72 6f 6c 6c 73 20 62 61  saction rolls ba
2ec50 63 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c  ck..*/.void *sql
2ec60 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b  ite3_commit_hook
2ec70 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a  (sqlite3*, int(*
2ec80 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29  )(void*), void*)
2ec90 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  ;.void *sqlite3_
2eca0 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 73 71  rollback_hook(sq
2ecb0 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 29 28  lite3*, void(*)(
2ecc0 76 6f 69 64 20 2a 29 2c 20 76 6f 69 64 2a 29 3b  void *), void*);
2ecd0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2ece0 3a 20 44 61 74 61 20 43 68 61 6e 67 65 20 4e 6f  : Data Change No
2ecf0 74 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62  tification Callb
2ed00 61 63 6b 73 20 7b 46 31 32 39 37 30 7d 0a 2a 2a  acks {F12970}.**
2ed10 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
2ed20 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 20 69 6e  update_hook() in
2ed30 74 65 72 66 61 63 65 0a 2a 2a 20 72 65 67 69 73  terface.** regis
2ed40 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20  ters a callback 
2ed50 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 74 68  function with th
2ed60 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
2ed70 63 74 69 6f 6e 20 69 64 65 6e 74 69 66 69 65 64  ction identified
2ed80 20 62 79 20 74 68 65 20 0a 2a 2a 20 66 69 72 73   by the .** firs
2ed90 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 62 65  t argument to be
2eda0 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65   invoked wheneve
2edb0 72 20 61 20 72 6f 77 20 69 73 20 75 70 64 61 74  r a row is updat
2edc0 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 20  ed, inserted or 
2edd0 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 41 6e 79 20  deleted..** Any 
2ede0 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20  callback set by 
2edf0 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  a previous call 
2ee00 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  to this function
2ee10 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 0a 2a   for the same .*
2ee20 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
2ee30 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64  ction is overrid
2ee40 64 65 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  den..**.** The s
2ee50 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69  econd argument i
2ee60 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
2ee70 68 65 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 69  he function to i
2ee80 6e 76 6f 6b 65 20 77 68 65 6e 20 61 20 0a 2a 2a  nvoke when a .**
2ee90 20 72 6f 77 20 69 73 20 75 70 64 61 74 65 64 2c   row is updated,
2eea0 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c   inserted or del
2eeb0 65 74 65 64 2e 20 0a 2a 2a 20 54 68 65 20 66 69  eted. .** The fi
2eec0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
2eed0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 0a  the callback is.
2eee0 2a 2a 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  ** a copy of the
2eef0 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
2ef00 74 6f 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74  to sqlite3_updat
2ef10 65 5f 68 6f 6f 6b 28 29 2e 0a 2a 2a 20 54 68 65  e_hook()..** The
2ef20 20 73 65 63 6f 6e 64 20 63 61 6c 6c 62 61 63 6b   second callback
2ef30 20 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73   .** argument is
2ef40 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f   one of [SQLITE_
2ef50 49 4e 53 45 52 54 5d 2c 20 5b 53 51 4c 49 54 45  INSERT], [SQLITE
2ef60 5f 44 45 4c 45 54 45 5d 20 6f 72 20 5b 53 51 4c  _DELETE] or [SQL
2ef70 49 54 45 5f 55 50 44 41 54 45 5d 2c 0a 2a 2a 20  ITE_UPDATE],.** 
2ef80 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  depending on the
2ef90 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20   operation that 
2efa0 63 61 75 73 65 64 20 74 68 65 20 63 61 6c 6c 62  caused the callb
2efb0 61 63 6b 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65  ack to be invoke
2efc0 64 2e 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20  d..** The third 
2efd0 61 6e 64 20 0a 2a 2a 20 66 6f 75 72 74 68 20 61  and .** fourth a
2efe0 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20  rguments to the 
2eff0 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e  callback contain
2f000 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65   pointers to the
2f010 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 0a 2a   database and .*
2f020 2a 20 74 61 62 6c 65 20 6e 61 6d 65 20 63 6f 6e  * table name con
2f030 74 61 69 6e 69 6e 67 20 74 68 65 20 61 66 66 65  taining the affe
2f040 63 74 65 64 20 72 6f 77 2e 0a 2a 2a 20 54 68 65  cted row..** The
2f050 20 66 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20   final callback 
2f060 70 61 72 61 6d 65 74 65 72 20 69 73 20 0a 2a 2a  parameter is .**
2f070 20 74 68 65 20 72 6f 77 69 64 20 6f 66 20 74 68   the rowid of th
2f080 65 20 72 6f 77 2e 0a 2a 2a 20 49 6e 20 74 68 65  e row..** In the
2f090 20 63 61 73 65 20 6f 66 20 61 6e 20 75 70 64 61   case of an upda
2f0a0 74 65 2c 20 74 68 69 73 20 69 73 20 74 68 65 20  te, this is the 
2f0b0 72 6f 77 69 64 20 61 66 74 65 72 20 0a 2a 2a 20  rowid after .** 
2f0c0 74 68 65 20 75 70 64 61 74 65 20 74 61 6b 65 73  the update takes
2f0d0 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68   place..**.** Th
2f0e0 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 20 69 73  e update hook is
2f0f0 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77 68 65   not invoked whe
2f100 6e 20 69 6e 74 65 72 6e 61 6c 20 73 79 73 74 65  n internal syste
2f110 6d 20 74 61 62 6c 65 73 20 61 72 65 0a 2a 2a 20  m tables are.** 
2f120 6d 6f 64 69 66 69 65 64 20 28 69 2e 65 2e 20 73  modified (i.e. s
2f130 71 6c 69 74 65 5f 6d 61 73 74 65 72 20 61 6e 64  qlite_master and
2f140 20 73 71 6c 69 74 65 5f 73 65 71 75 65 6e 63 65   sqlite_sequence
2f150 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74  )..**.** If anot
2f160 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 77 61 73  her function was
2f170 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 67 69   previously regi
2f180 73 74 65 72 65 64 2c 20 69 74 73 20 70 41 72 67  stered, its pArg
2f190 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 72 65 74   value.** is ret
2f1a0 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73  urned.  Otherwis
2f1b0 65 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e  e NULL is return
2f1c0 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  ed..**.** INVARI
2f1d0 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  ANTS:.**.** {F12
2f1e0 39 37 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  971} The [sqlite
2f1f0 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44 2c  3_update_hook(D,
2f200 46 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20  F,P)] interface 
2f210 63 61 75 73 65 73 20 63 61 6c 6c 62 61 63 6b 0a  causes callback.
2f220 2a 2a 20 20 20 20 20 20 20 20 20 20 66 75 6e 63  **          func
2f230 74 69 6f 6e 20 46 20 74 6f 20 62 65 20 69 6e 76  tion F to be inv
2f240 6f 6b 65 64 20 77 69 74 68 20 66 69 72 73 74 20  oked with first 
2f250 70 61 72 61 6d 65 74 65 72 20 50 20 77 68 65 6e  parameter P when
2f260 65 76 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  ever.**         
2f270 20 61 20 74 61 62 6c 65 20 72 6f 77 20 69 73 20   a table row is 
2f280 6d 6f 64 69 66 69 65 64 2c 20 69 6e 73 65 72 74  modified, insert
2f290 65 64 2c 20 6f 72 20 64 65 6c 65 74 65 64 20 6f  ed, or deleted o
2f2a0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64  n.**          [d
2f2b0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2f2c0 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  on] D..**.** {F1
2f2d0 32 39 37 33 7d 20 54 68 65 20 5b 73 71 6c 69 74  2973} The [sqlit
2f2e0 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44  e3_update_hook(D
2f2f0 2c 46 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 65  ,F,P)] interface
2f300 20 72 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c   returns the val
2f310 75 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  ue.**          o
2f320 66 20 50 20 66 6f 72 20 74 68 65 20 70 72 65 76  f P for the prev
2f330 69 6f 75 73 20 63 61 6c 6c 20 6f 6e 20 74 68 65  ious call on the
2f340 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20   same [database 
2f350 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 0a 2a  connection] D,.*
2f360 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 4e 55  *          or NU
2f370 4c 4c 20 66 6f 72 20 74 68 65 20 66 69 72 73 74  LL for the first
2f380 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31   call..**.** {F1
2f390 32 39 37 35 7d 20 49 66 20 74 68 65 20 75 70 64  2975} If the upd
2f3a0 61 74 65 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63  ate hook callbac
2f3b0 6b 20 46 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f  k F in [sqlite3_
2f3c0 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44 2c 46 2c  update_hook(D,F,
2f3d0 50 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  P)].**          
2f3e0 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65  is NULL then the
2f3f0 20 6e 6f 20 75 70 64 61 74 65 20 63 61 6c 6c 62   no update callb
2f400 61 63 6b 73 20 61 72 65 20 6d 61 64 65 2e 0a 2a  acks are made..*
2f410 2a 0a 2a 2a 20 7b 46 31 32 39 37 37 7d 20 45 61  *.** {F12977} Ea
2f420 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ch call to [sqli
2f430 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28  te3_update_hook(
2f440 44 2c 46 2c 50 29 5d 20 6f 76 65 72 72 69 64 65  D,F,P)] override
2f450 73 20 70 72 69 6f 72 20 63 61 6c 6c 73 0a 2a 2a  s prior calls.**
2f460 20 20 20 20 20 20 20 20 20 20 74 6f 20 74 68 65            to the
2f470 20 73 61 6d 65 20 69 6e 74 65 72 66 61 63 65 20   same interface 
2f480 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74  on the same [dat
2f490 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2f4a0 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39  ] D..**.** {F129
2f4b0 37 39 7d 20 54 68 65 20 75 70 64 61 74 65 20 68  79} The update h
2f4c0 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ook callback is 
2f4d0 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e  not invoked when
2f4e0 20 69 6e 74 65 72 6e 61 6c 20 73 79 73 74 65 6d   internal system
2f4f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 61 62  .**          tab
2f500 6c 65 73 20 73 75 63 68 20 61 73 20 73 71 6c 69  les such as sqli
2f510 74 65 5f 6d 61 73 74 65 72 20 61 6e 64 20 73 71  te_master and sq
2f520 6c 69 74 65 5f 73 65 71 75 65 6e 63 65 20 61 72  lite_sequence ar
2f530 65 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a  e modified..**.*
2f540 2a 20 7b 46 31 32 39 38 31 7d 20 54 68 65 20 73  * {F12981} The s
2f550 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
2f560 74 6f 20 74 68 65 20 75 70 64 61 74 65 20 63 61  to the update ca
2f570 6c 6c 62 61 63 6b 20 0a 2a 2a 20 20 20 20 20 20  llback .**      
2f580 20 20 20 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53      is one of [S
2f590 51 4c 49 54 45 5f 49 4e 53 45 52 54 5d 2c 20 5b  QLITE_INSERT], [
2f5a0 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 6f  SQLITE_DELETE] o
2f5b0 72 20 5b 53 51 4c 49 54 45 5f 55 50 44 41 54 45  r [SQLITE_UPDATE
2f5c0 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64  ],.**          d
2f5d0 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
2f5e0 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20 63  operation that c
2f5f0 61 75 73 65 64 20 74 68 65 20 63 61 6c 6c 62 61  aused the callba
2f600 63 6b 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64  ck to be invoked
2f610 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 38 33 7d  ..**.** {F12983}
2f620 20 54 68 65 20 74 68 69 72 64 20 61 6e 64 20 66   The third and f
2f630 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 73 20  ourth arguments 
2f640 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
2f650 63 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65 72 73  contain pointers
2f660 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20  .**          to 
2f670 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
2f680 55 54 46 2d 38 20 73 74 72 69 6e 67 73 20 77 68  UTF-8 strings wh
2f690 69 63 68 20 61 72 65 20 74 68 65 20 6e 61 6d 65  ich are the name
2f6a0 73 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20  s of the.**     
2f6b0 20 20 20 20 20 64 61 74 61 62 61 73 65 20 61 6e       database an
2f6c0 64 20 74 61 62 6c 65 20 74 68 61 74 20 69 73 20  d table that is 
2f6d0 62 65 69 6e 67 20 75 70 64 61 74 65 64 2e 0a 0a  being updated...
2f6e0 2a 2a 20 7b 46 31 32 39 38 35 7d 20 54 68 65 20  ** {F12985} The 
2f6f0 66 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 70  final callback p
2f700 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
2f710 72 6f 77 69 64 20 6f 66 20 74 68 65 20 72 6f 77  rowid of the row
2f720 20 61 66 74 65 72 0a 2a 2a 20 20 20 20 20 20 20   after.**       
2f730 20 20 20 74 68 65 20 63 68 61 6e 67 65 20 6f 63     the change oc
2f740 63 75 72 73 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73  curs..*/.void *s
2f750 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f  qlite3_update_ho
2f760 6f 6b 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  ok(.  sqlite3*, 
2f770 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 20  .  void(*)(void 
2f780 2a 2c 69 6e 74 20 2c 63 68 61 72 20 63 6f 6e 73  *,int ,char cons
2f790 74 20 2a 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a  t *,char const *
2f7a0 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 2c  ,sqlite3_int64),
2f7b0 0a 20 20 76 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a  .  void*.);../*.
2f7c0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 45 6e  ** CAPI3REF:  En
2f7d0 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20  able Or Disable 
2f7e0 53 68 61 72 65 64 20 50 61 67 65 72 20 43 61 63  Shared Pager Cac
2f7f0 68 65 20 7b 46 31 30 33 33 30 7d 0a 2a 2a 0a 2a  he {F10330}.**.*
2f800 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 65  * This routine e
2f810 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c  nables or disabl
2f820 65 73 20 74 68 65 20 73 68 61 72 69 6e 67 20 6f  es the sharing o
2f830 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  f the database c
2f840 61 63 68 65 0a 2a 2a 20 61 6e 64 20 73 63 68 65  ache.** and sche
2f850 6d 61 20 64 61 74 61 20 73 74 72 75 63 74 75 72  ma data structur
2f860 65 73 20 62 65 74 77 65 65 6e 20 63 6f 6e 6e 65  es between conne
2f870 63 74 69 6f 6e 73 20 74 6f 20 74 68 65 20 73 61  ctions to the sa
2f880 6d 65 20 64 61 74 61 62 61 73 65 2e 0a 2a 2a 20  me database..** 
2f890 53 68 61 72 69 6e 67 20 69 73 20 65 6e 61 62 6c  Sharing is enabl
2f8a0 65 64 20 69 66 20 74 68 65 20 61 72 67 75 6d 65  ed if the argume
2f8b0 6e 74 20 69 73 20 74 72 75 65 20 61 6e 64 20 64  nt is true and d
2f8c0 69 73 61 62 6c 65 64 20 69 66 20 74 68 65 20 61  isabled if the a
2f8d0 72 67 75 6d 65 6e 74 0a 2a 2a 20 69 73 20 66 61  rgument.** is fa
2f8e0 6c 73 65 2e 0a 2a 2a 0a 2a 2a 20 43 61 63 68 65  lse..**.** Cache
2f8f0 20 73 68 61 72 69 6e 67 20 69 73 20 65 6e 61 62   sharing is enab
2f900 6c 65 64 20 61 6e 64 20 64 69 73 61 62 6c 65 64  led and disabled
2f910 0a 2a 2a 20 66 6f 72 20 61 6e 20 65 6e 74 69 72  .** for an entir
2f920 65 20 70 72 6f 63 65 73 73 2e 20 7b 45 4e 44 7d  e process. {END}
2f930 20 54 68 69 73 20 69 73 20 61 20 63 68 61 6e 67   This is a chang
2f940 65 20 61 73 20 6f 66 20 53 51 4c 69 74 65 20 76  e as of SQLite v
2f950 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2e 0a 2a 2a  ersion 3.5.0..**
2f960 20 49 6e 20 70 72 69 6f 72 20 76 65 72 73 69 6f   In prior versio
2f970 6e 73 20 6f 66 20 53 51 4c 69 74 65 2c 20 73 68  ns of SQLite, sh
2f980 61 72 69 6e 67 20 77 61 73 0a 2a 2a 20 65 6e 61  aring was.** ena
2f990 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64  bled or disabled
2f9a0 20 66 6f 72 20 65 61 63 68 20 74 68 72 65 61 64   for each thread
2f9b0 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a   separately..**.
2f9c0 2a 2a 20 54 68 65 20 63 61 63 68 65 20 73 68 61  ** The cache sha
2f9d0 72 69 6e 67 20 6d 6f 64 65 20 73 65 74 20 62 79  ring mode set by
2f9e0 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
2f9f0 65 66 66 65 63 74 73 20 61 6c 6c 20 73 75 62 73  effects all subs
2fa00 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20  equent.** calls 
2fa10 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  to [sqlite3_open
2fa20 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
2fa30 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20 5b 73  en_v2()], and [s
2fa40 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
2fa50 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 64 61  ..** Existing da
2fa60 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2fa70 6e 73 20 63 6f 6e 74 69 6e 75 65 20 75 73 65 20  ns continue use 
2fa80 74 68 65 20 73 68 61 72 69 6e 67 20 6d 6f 64 65  the sharing mode
2fa90 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 69 6e 20  .** that was in 
2faa0 65 66 66 65 63 74 20 61 74 20 74 68 65 20 74 69  effect at the ti
2fab0 6d 65 20 74 68 65 79 20 77 65 72 65 20 6f 70 65  me they were ope
2fac0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 56 69 72 74 75  ned..**.** Virtu
2fad0 61 6c 20 74 61 62 6c 65 73 20 63 61 6e 6e 6f 74  al tables cannot
2fae0 20 62 65 20 75 73 65 64 20 77 69 74 68 20 61 20   be used with a 
2faf0 73 68 61 72 65 64 20 63 61 63 68 65 2e 20 20 20  shared cache.   
2fb00 57 68 65 6e 20 73 68 61 72 65 64 0a 2a 2a 20 63  When shared.** c
2fb10 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64 2c  ache is enabled,
2fb20 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72   the [sqlite3_cr
2fb30 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 5d 20 41  eate_module()] A
2fb40 50 49 20 75 73 65 64 20 74 6f 20 72 65 67 69 73  PI used to regis
2fb50 74 65 72 0a 2a 2a 20 76 69 72 74 75 61 6c 20 74  ter.** virtual t
2fb60 61 62 6c 65 73 20 77 69 6c 6c 20 61 6c 77 61 79  ables will alway
2fb70 73 20 72 65 74 75 72 6e 20 61 6e 20 65 72 72 6f  s return an erro
2fb80 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  r..**.** This ro
2fb90 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53  utine returns [S
2fba0 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 20 73 68 61  QLITE_OK] if sha
2fbb0 72 65 64 20 63 61 63 68 65 20 77 61 73 0a 2a 2a  red cache was.**
2fbc0 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61   enabled or disa
2fbd0 62 6c 65 64 20 73 75 63 63 65 73 73 66 75 6c 6c  bled successfull
2fbe0 79 2e 20 20 41 6e 20 5b 65 72 72 6f 72 20 63 6f  y.  An [error co
2fbf0 64 65 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e  de].** is return
2fc00 65 64 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a  ed otherwise..**
2fc10 0a 2a 2a 20 53 68 61 72 65 64 20 63 61 63 68 65  .** Shared cache
2fc20 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20   is disabled by 
2fc30 64 65 66 61 75 6c 74 2e 20 42 75 74 20 74 68 69  default. But thi
2fc40 73 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69  s might change i
2fc50 6e 0a 2a 2a 20 66 75 74 75 72 65 20 72 65 6c 65  n.** future rele
2fc60 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20  ases of SQLite. 
2fc70 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   Applications th
2fc80 61 74 20 63 61 72 65 20 61 62 6f 75 74 20 73 68  at care about sh
2fc90 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 73 65  ared.** cache se
2fca0 74 74 69 6e 67 20 73 68 6f 75 6c 64 20 73 65 74  tting should set
2fcb0 20 69 74 20 65 78 70 6c 69 63 69 74 6c 79 2e 0a   it explicitly..
2fcc0 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
2fcd0 3a 0a 2a 2a 20 0a 2a 2a 20 7b 46 31 30 33 33 31  :.** .** {F10331
2fce0 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 69  } A successful i
2fcf0 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71  nvocation of [sq
2fd00 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61  lite3_enable_sha
2fd10 72 65 64 5f 63 61 63 68 65 28 42 29 5d 0a 2a 2a  red_cache(B)].**
2fd20 20 20 20 20 20 20 20 20 20 20 77 69 6c 6c 20 65            will e
2fd30 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65  nable or disable
2fd40 20 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f   shared cache mo
2fd50 64 65 20 66 6f 72 20 61 6e 79 20 73 75 62 73 65  de for any subse
2fd60 71 75 65 6e 74 6c 79 0a 2a 2a 20 20 20 20 20 20  quently.**      
2fd70 20 20 20 20 63 72 65 61 74 65 64 20 5b 64 61 74      created [dat
2fd80 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2fd90 5d 20 69 6e 20 74 68 65 20 73 61 6d 65 20 70 72  ] in the same pr
2fda0 6f 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  ocess..**.** {F1
2fdb0 30 33 33 36 7d 20 57 68 65 6e 20 73 68 61 72 65  0336} When share
2fdc0 64 20 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c  d cache is enabl
2fdd0 65 64 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ed, the [sqlite3
2fde0 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29  _create_module()
2fdf0 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  ].**          in
2fe00 74 65 72 66 61 63 65 20 77 69 6c 6c 20 61 6c 77  terface will alw
2fe10 61 79 73 20 72 65 74 75 72 6e 20 61 6e 20 65 72  ays return an er
2fe20 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 33  ror..**.** {F103
2fe30 33 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  37} The [sqlite3
2fe40 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63  _enable_shared_c
2fe50 61 63 68 65 28 42 29 5d 20 69 6e 74 65 72 66 61  ache(B)] interfa
2fe60 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20  ce returns.**   
2fe70 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 4f         [SQLITE_O
2fe80 4b 5d 20 69 66 20 73 68 61 72 65 64 20 63 61 63  K] if shared cac
2fe90 68 65 20 77 61 73 20 65 6e 61 62 6c 65 64 20 6f  he was enabled o
2fea0 72 20 64 69 73 61 62 6c 65 64 20 73 75 63 63 65  r disabled succe
2feb0 73 73 66 75 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b  ssfully..**.** {
2fec0 46 31 30 33 33 39 7d 20 53 68 61 72 65 64 20 63  F10339} Shared c
2fed0 61 63 68 65 20 69 73 20 64 69 73 61 62 6c 65 64  ache is disabled
2fee0 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2f 0a   by default..*/.
2fef0 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 6e 61 62  int sqlite3_enab
2ff00 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28  le_shared_cache(
2ff10 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
2ff20 49 33 52 45 46 3a 20 20 41 74 74 65 6d 70 74 20  I3REF:  Attempt 
2ff30 54 6f 20 46 72 65 65 20 48 65 61 70 20 4d 65 6d  To Free Heap Mem
2ff40 6f 72 79 20 7b 46 31 37 33 34 30 7d 0a 2a 2a 0a  ory {F17340}.**.
2ff50 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
2ff60 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20  elease_memory() 
2ff70 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70  interface attemp
2ff80 74 73 20 74 6f 0a 2a 2a 20 66 72 65 65 20 4e 20  ts to.** free N 
2ff90 62 79 74 65 73 20 6f 66 20 68 65 61 70 20 6d 65  bytes of heap me
2ffa0 6d 6f 72 79 20 62 79 20 64 65 61 6c 6c 6f 63 61  mory by dealloca
2ffb0 74 69 6e 67 20 6e 6f 6e 2d 65 73 73 65 6e 74 69  ting non-essenti
2ffc0 61 6c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c  al memory.** all
2ffd0 6f 63 61 74 69 6f 6e 73 20 68 65 6c 64 20 62 79  ocations held by
2ffe0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6c 61   the database la
2fff0 62 72 61 72 79 2e 20 7b 45 4e 44 7d 20 20 4d 65  brary. {END}  Me
30000 6d 6f 72 79 20 75 73 65 64 0a 2a 2a 20 74 6f 20  mory used.** to 
30010 63 61 63 68 65 20 64 61 74 61 62 61 73 65 20 70  cache database p
30020 61 67 65 73 20 74 6f 20 69 6d 70 72 6f 76 65 20  ages to improve 
30030 70 65 72 66 6f 72 6d 61 6e 63 65 20 69 73 20 61  performance is a
30040 6e 20 65 78 61 6d 70 6c 65 20 6f 66 0a 2a 2a 20  n example of.** 
30050 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 20 6d 65  non-essential me
30060 6d 6f 72 79 2e 20 20 53 71 6c 69 74 65 33 5f 72  mory.  Sqlite3_r
30070 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20  elease_memory() 
30080 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e  returns.** the n
30090 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 61  umber of bytes a
300a0 63 74 75 61 6c 6c 79 20 66 72 65 65 64 2c 20 77  ctually freed, w
300b0 68 69 63 68 20 6d 69 67 68 74 20 62 65 20 6d 6f  hich might be mo
300c0 72 65 20 6f 72 20 6c 65 73 73 0a 2a 2a 20 74 68  re or less.** th
300d0 61 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20 72 65  an the amount re
300e0 71 75 65 73 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  quested..**.** I
300f0 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
30100 20 7b 46 31 37 33 34 31 7d 20 54 68 65 20 5b 73   {F17341} The [s
30110 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d  qlite3_release_m
30120 65 6d 6f 72 79 28 4e 29 5d 20 69 6e 74 65 72 66  emory(N)] interf
30130 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 0a  ace attempts to.
30140 2a 2a 20 20 20 20 20 20 20 20 20 20 66 72 65 65  **          free
30150 20 4e 20 62 79 74 65 73 20 6f 66 20 68 65 61 70   N bytes of heap
30160 20 6d 65 6d 6f 72 79 20 62 79 20 64 65 61 6c 6c   memory by deall
30170 6f 63 61 74 69 6e 67 20 6e 6f 6e 2d 65 73 73 65  ocating non-esse
30180 6e 74 69 61 6c 0a 2a 2a 20 20 20 20 20 20 20 20  ntial.**        
30190 20 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74    memory allocat
301a0 69 6f 6e 73 20 68 65 6c 64 20 62 79 20 74 68 65  ions held by the
301b0 20 64 61 74 61 62 61 73 65 20 6c 61 62 72 61 72   database labrar
301c0 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 33 34 32  y..**.** {F16342
301d0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  } The [sqlite3_r
301e0 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 4e 29  elease_memory(N)
301f0 5d 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  ] returns the nu
30200 6d 62 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  mber.**         
30210 20 6f 66 20 62 79 74 65 73 20 61 63 74 75 61 6c   of bytes actual
30220 6c 79 20 66 72 65 65 64 2c 20 77 68 69 63 68 20  ly freed, which 
30230 6d 69 67 68 74 20 62 65 20 6d 6f 72 65 20 6f 72  might be more or
30240 20 6c 65 73 73 0a 2a 2a 20 20 20 20 20 20 20 20   less.**        
30250 20 20 74 68 61 6e 20 74 68 65 20 61 6d 6f 75 6e    than the amoun
30260 74 20 72 65 71 75 65 73 74 65 64 2e 0a 2a 2f 0a  t requested..*/.
30270 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6c 65  int sqlite3_rele
30280 61 73 65 5f 6d 65 6d 6f 72 79 28 69 6e 74 29 3b  ase_memory(int);
30290 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
302a0 3a 20 20 49 6d 70 6f 73 65 20 41 20 4c 69 6d 69  :  Impose A Limi
302b0 74 20 4f 6e 20 48 65 61 70 20 53 69 7a 65 20 7b  t On Heap Size {
302c0 46 31 37 33 35 30 7d 0a 2a 2a 0a 2a 2a 20 54 68  F17350}.**.** Th
302d0 65 20 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68  e sqlite3_soft_h
302e0 65 61 70 5f 6c 69 6d 69 74 28 29 20 69 6e 74 65  eap_limit() inte
302f0 72 66 61 63 65 0a 2a 2a 20 70 6c 61 63 65 73 20  rface.** places 
30300 61 20 22 73 6f 66 74 22 20 6c 69 6d 69 74 20 6f  a "soft" limit o
30310 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20  n the amount of 
30320 68 65 61 70 20 6d 65 6d 6f 72 79 20 74 68 61 74  heap memory that
30330 20 6d 61 79 20 62 65 20 61 6c 6c 6f 63 61 74 65   may be allocate
30340 64 0a 2a 2a 20 62 79 20 53 51 4c 69 74 65 2e 20  d.** by SQLite. 
30350 49 66 20 61 6e 20 69 6e 74 65 72 6e 61 6c 20 61  If an internal a
30360 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 72 65 71  llocation is req
30370 75 65 73 74 65 64 20 0a 2a 2a 20 74 68 61 74 20  uested .** that 
30380 77 6f 75 6c 64 20 65 78 63 65 65 64 20 74 68 65  would exceed the
30390 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
303a0 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61  , [sqlite3_relea
303b0 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 69 73 0a  se_memory()] is.
303c0 2a 2a 20 69 6e 76 6f 6b 65 64 20 6f 6e 65 20 6f  ** invoked one o
303d0 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20  r more times to 
303e0 66 72 65 65 20 75 70 20 73 6f 6d 65 20 73 70 61  free up some spa
303f0 63 65 20 62 65 66 6f 72 65 20 74 68 65 20 61 6c  ce before the al
30400 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6d  location.** is m
30410 61 64 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c  ade..**.** The l
30420 69 6d 69 74 20 69 73 20 63 61 6c 6c 65 64 20 22  imit is called "
30430 73 6f 66 74 22 2c 20 62 65 63 61 75 73 65 20 69  soft", because i
30440 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  f.** [sqlite3_re
30450 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20  lease_memory()] 
30460 63 61 6e 6e 6f 74 0a 2a 2a 20 66 72 65 65 20 73  cannot.** free s
30470 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79  ufficient memory
30480 20 74 6f 20 70 72 65 76 65 6e 74 20 74 68 65 20   to prevent the 
30490 6c 69 6d 69 74 20 66 72 6f 6d 20 62 65 69 6e 67  limit from being
304a0 20 65 78 63 65 65 64 65 64 2c 0a 2a 2a 20 74 68   exceeded,.** th
304b0 65 20 6d 65 6d 6f 72 79 20 69 73 20 61 6c 6c 6f  e memory is allo
304c0 63 61 74 65 64 20 61 6e 79 77 61 79 20 61 6e 64  cated anyway and
304d0 20 74 68 65 20 63 75 72 72 65 6e 74 20 6f 70 65   the current ope
304e0 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 2e  ration proceeds.
304f0 0a 2a 2a 0a 2a 2a 20 41 20 6e 65 67 61 74 69 76  .**.** A negativ
30500 65 20 6f 72 20 7a 65 72 6f 20 76 61 6c 75 65 20  e or zero value 
30510 66 6f 72 20 4e 20 6d 65 61 6e 73 20 74 68 61 74  for N means that
30520 20 74 68 65 72 65 20 69 73 20 6e 6f 20 73 6f 66   there is no sof
30530 74 20 68 65 61 70 20 6c 69 6d 69 74 20 61 6e 64  t heap limit and
30540 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c  .** [sqlite3_rel
30550 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 77  ease_memory()] w
30560 69 6c 6c 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c  ill only be call
30570 65 64 20 77 68 65 6e 20 6d 65 6d 6f 72 79 20 69  ed when memory i
30580 73 20 65 78 68 61 75 73 74 65 64 2e 0a 2a 2a 20  s exhausted..** 
30590 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75  The default valu
305a0 65 20 66 6f 72 20 74 68 65 20 73 6f 66 74 20 68  e for the soft h
305b0 65 61 70 20 6c 69 6d 69 74 20 69 73 20 7a 65 72  eap limit is zer
305c0 6f 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  o..**.** SQLite 
305d0 6d 61 6b 65 73 20 61 20 62 65 73 74 20 65 66 66  makes a best eff
305e0 6f 72 74 20 74 6f 20 68 6f 6e 6f 72 20 74 68 65  ort to honor the
305f0 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
30600 2e 20 20 0a 2a 2a 20 42 75 74 20 69 66 20 74 68  .  .** But if th
30610 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69  e soft heap limi
30620 74 20 63 61 6e 6e 6f 74 20 68 6f 6e 6f 72 65 64  t cannot honored
30630 2c 20 65 78 65 63 75 74 69 6f 6e 20 77 69 6c 6c  , execution will
30640 0a 2a 2a 20 63 6f 6e 74 69 6e 75 65 20 77 69 74  .** continue wit
30650 68 6f 75 74 20 65 72 72 6f 72 20 6f 72 20 6e 6f  hout error or no
30660 74 69 66 69 63 61 74 69 6f 6e 2e 20 20 54 68 69  tification.  Thi
30670 73 20 69 73 20 77 68 79 20 74 68 65 20 6c 69 6d  s is why the lim
30680 69 74 20 69 73 20 0a 2a 2a 20 63 61 6c 6c 65 64  it is .** called
30690 20 61 20 22 73 6f 66 74 22 20 6c 69 6d 69 74 2e   a "soft" limit.
306a0 20 20 49 74 20 69 73 20 61 64 76 69 73 6f 72 79    It is advisory
306b0 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 50 72 69   only..**.** Pri
306c0 6f 72 20 74 6f 20 53 51 4c 69 74 65 20 76 65 72  or to SQLite ver
306d0 73 69 6f 6e 20 33 2e 35 2e 30 2c 20 74 68 69 73  sion 3.5.0, this
306e0 20 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 63 6f   routine only co
306f0 6e 73 74 72 61 69 6e 65 64 20 74 68 65 20 6d 65  nstrained the me
30700 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65  mory.** allocate
30710 64 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68  d by a single th
30720 72 65 61 64 20 2d 20 74 68 65 20 73 61 6d 65 20  read - the same 
30730 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 20  thread in which 
30740 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20  this routine.** 
30750 72 75 6e 73 2e 20 20 42 65 67 69 6e 6e 69 6e 67  runs.  Beginning
30760 20 77 69 74 68 20 53 51 4c 69 74 65 20 76 65 72   with SQLite ver
30770 73 69 6f 6e 20 33 2e 35 2e 30 2c 20 74 68 65 20  sion 3.5.0, the 
30780 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20  soft heap limit 
30790 69 73 0a 2a 2a 20 61 70 70 6c 69 65 64 20 74 6f  is.** applied to
307a0 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 20 54 68   all threads. Th
307b0 65 20 76 61 6c 75 65 20 73 70 65 63 69 66 69 65  e value specifie
307c0 64 20 66 6f 72 20 74 68 65 20 73 6f 66 74 20 68  d for the soft h
307d0 65 61 70 20 6c 69 6d 69 74 0a 2a 2a 20 69 73 20  eap limit.** is 
307e0 61 6e 20 75 70 70 65 72 20 62 6f 75 6e 64 20 6f  an upper bound o
307f0 6e 20 74 68 65 20 74 6f 74 61 6c 20 6d 65 6d 6f  n the total memo
30800 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f  ry allocation fo
30810 72 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 20 49  r all threads. I
30820 6e 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 33 2e 35  n.** version 3.5
30830 2e 30 20 74 68 65 72 65 20 69 73 20 6e 6f 20 6d  .0 there is no m
30840 65 63 68 61 6e 69 73 6d 20 66 6f 72 20 6c 69 6d  echanism for lim
30850 69 74 69 6e 67 20 74 68 65 20 68 65 61 70 20 75  iting the heap u
30860 73 61 67 65 20 66 6f 72 0a 2a 2a 20 69 6e 64 69  sage for.** indi
30870 76 69 64 75 61 6c 20 74 68 72 65 61 64 73 2e 0a  vidual threads..
30880 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
30890 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 33 35 31 7d  :.**.** {F16351}
308a0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 6f   The [sqlite3_so
308b0 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 4e 29  ft_heap_limit(N)
308c0 5d 20 69 6e 74 65 72 66 61 63 65 20 70 6c 61 63  ] interface plac
308d0 65 73 20 61 20 73 6f 66 74 20 6c 69 6d 69 74 0a  es a soft limit.
308e0 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 4e  **          of N
308f0 20 62 79 74 65 73 20 6f 6e 20 74 68 65 20 61 6d   bytes on the am
30900 6f 75 6e 74 20 6f 66 20 68 65 61 70 20 6d 65 6d  ount of heap mem
30910 6f 72 79 20 74 68 61 74 20 6d 61 79 20 62 65 20  ory that may be 
30920 61 6c 6c 6f 63 61 74 65 64 0a 2a 2a 20 20 20 20  allocated.**    
30930 20 20 20 20 20 20 75 73 69 6e 67 20 5b 73 71 6c        using [sql
30940 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f  ite3_malloc()] o
30950 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  r [sqlite3_reall
30960 6f 63 28 29 5d 20 61 74 20 61 6e 79 20 70 6f 69  oc()] at any poi
30970 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  nt.**          i
30980 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46  n time..**.** {F
30990 31 36 33 35 32 7d 20 49 66 20 61 20 63 61 6c 6c  16352} If a call
309a0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   to [sqlite3_mal
309b0 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  loc()] or [sqlit
309c0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 77 6f  e3_realloc()] wo
309d0 75 6c 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  uld.**          
309e0 63 61 75 73 65 20 74 68 65 20 74 6f 74 61 6c 20  cause the total 
309f0 61 6d 6f 75 6e 74 20 6f 66 20 61 6c 6c 6f 63 61  amount of alloca
30a00 74 65 64 20 6d 65 6d 6f 72 79 20 74 6f 20 65 78  ted memory to ex
30a10 63 65 65 64 20 74 68 65 0a 2a 2a 20 20 20 20 20  ceed the.**     
30a20 20 20 20 20 20 73 6f 66 74 20 68 65 61 70 20 6c       soft heap l
30a30 69 6d 69 74 2c 20 74 68 65 6e 20 5b 73 71 6c 69  imit, then [sqli
30a40 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f  te3_release_memo
30a50 72 79 28 29 5d 20 69 73 20 69 6e 76 6f 6b 65 64  ry()] is invoked
30a60 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20  .**          in 
30a70 61 6e 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65  an attempt to re
30a80 64 75 63 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  duce the memory 
30a90 75 73 61 67 65 20 70 72 69 6f 72 20 74 6f 20 70  usage prior to p
30aa0 72 6f 63 65 65 64 69 6e 67 0a 2a 2a 20 20 20 20  roceeding.**    
30ab0 20 20 20 20 20 20 77 69 74 68 20 74 68 65 20 6d        with the m
30ac0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
30ad0 20 61 74 74 65 6d 70 74 2e 0a 2a 2a 0a 2a 2a 20   attempt..**.** 
30ae0 7b 46 31 36 33 35 33 7d 20 43 61 6c 6c 73 20 74  {F16353} Calls t
30af0 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  o [sqlite3_mallo
30b00 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  c()] or [sqlite3
30b10 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74  _realloc()] that
30b20 20 74 72 69 67 67 65 72 0a 2a 2a 20 20 20 20 20   trigger.**     
30b30 20 20 20 20 20 61 74 74 65 6d 70 74 73 20 74 6f       attempts to
30b40 20 72 65 64 75 63 65 20 6d 65 6d 6f 72 79 20 75   reduce memory u
30b50 73 61 67 65 20 74 68 72 6f 75 67 68 20 74 68 65  sage through the
30b60 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
30b70 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 65 63  .**          mec
30b80 68 61 6e 69 73 6d 20 63 6f 6e 74 69 6e 75 65 20  hanism continue 
30b90 65 76 65 6e 20 69 66 20 74 68 65 20 61 74 74 65  even if the atte
30ba0 6d 70 74 20 74 6f 20 72 65 64 75 63 65 20 6d 65  mpt to reduce me
30bb0 6d 6f 72 79 0a 2a 2a 20 20 20 20 20 20 20 20 20  mory.**         
30bc0 20 75 73 61 67 65 20 69 73 20 75 6e 73 75 63 63   usage is unsucc
30bd0 65 73 73 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 46  essful..**.** {F
30be0 31 36 33 35 34 7d 20 41 20 6e 65 67 61 74 69 76  16354} A negativ
30bf0 65 20 6f 72 20 7a 65 72 6f 20 76 61 6c 75 65 20  e or zero value 
30c00 66 6f 72 20 4e 20 69 6e 20 61 20 63 61 6c 6c 20  for N in a call 
30c10 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  to.**          [
30c20 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61  sqlite3_soft_hea
30c30 70 5f 6c 69 6d 69 74 28 4e 29 5d 20 6d 65 61 6e  p_limit(N)] mean
30c40 73 20 74 68 61 74 20 74 68 65 72 65 20 69 73 20  s that there is 
30c50 6e 6f 20 73 6f 66 74 0a 2a 2a 20 20 20 20 20 20  no soft.**      
30c60 20 20 20 20 68 65 61 70 20 6c 69 6d 69 74 20 61      heap limit a
30c70 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65  nd [sqlite3_rele
30c80 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 77 69  ase_memory()] wi
30c90 6c 6c 20 6f 6e 6c 79 20 62 65 0a 2a 2a 20 20 20  ll only be.**   
30ca0 20 20 20 20 20 20 20 63 61 6c 6c 65 64 20 77 68         called wh
30cb0 65 6e 20 6d 65 6d 6f 72 79 20 69 73 20 63 6f 6d  en memory is com
30cc0 70 6c 65 74 65 6c 79 20 65 78 68 61 75 73 74 65  pletely exhauste
30cd0 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 33 35 35  d..**.** {F16355
30ce0 7d 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61  } The default va
30cf0 6c 75 65 20 66 6f 72 20 74 68 65 20 73 6f 66 74  lue for the soft
30d00 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20 7a   heap limit is z
30d10 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 33  ero..**.** {F163
30d20 35 38 7d 20 45 61 63 68 20 63 61 6c 6c 20 74 6f  58} Each call to
30d30 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68   [sqlite3_soft_h
30d40 65 61 70 5f 6c 69 6d 69 74 28 4e 29 5d 20 6f 76  eap_limit(N)] ov
30d50 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 20  errides the.**  
30d60 20 20 20 20 20 20 20 20 76 61 6c 75 65 73 20 73          values s
30d70 65 74 20 62 79 20 61 6c 6c 20 70 72 69 6f 72 20  et by all prior 
30d80 63 61 6c 6c 73 2e 0a 2a 2f 0a 76 6f 69 64 20 73  calls..*/.void s
30d90 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70  qlite3_soft_heap
30da0 5f 6c 69 6d 69 74 28 69 6e 74 29 3b 0a 0a 2f 2a  _limit(int);../*
30db0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 45  .** CAPI3REF:  E
30dc0 78 74 72 61 63 74 20 4d 65 74 61 64 61 74 61 20  xtract Metadata 
30dd0 41 62 6f 75 74 20 41 20 43 6f 6c 75 6d 6e 20 4f  About A Column O
30de0 66 20 41 20 54 61 62 6c 65 20 7b 46 31 32 38 35  f A Table {F1285
30df0 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  0}.**.** This ro
30e00 75 74 69 6e 65 0a 2a 2a 20 72 65 74 75 72 6e 73  utine.** returns
30e10 20 6d 65 74 61 2d 64 61 74 61 20 61 62 6f 75 74   meta-data about
30e20 20 61 20 73 70 65 63 69 66 69 63 20 63 6f 6c 75   a specific colu
30e30 6d 6e 20 6f 66 20 61 20 73 70 65 63 69 66 69 63  mn of a specific
30e40 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 74 61 62   database.** tab
30e50 6c 65 20 61 63 63 65 73 73 69 62 6c 65 20 75 73  le accessible us
30e60 69 6e 67 20 74 68 65 20 63 6f 6e 6e 65 63 74 69  ing the connecti
30e70 6f 6e 20 68 61 6e 64 6c 65 20 70 61 73 73 65 64  on handle passed
30e80 20 61 73 20 74 68 65 20 66 69 72 73 74 20 66 75   as the first fu
30e90 6e 63 74 69 6f 6e 20 0a 2a 2a 20 61 72 67 75 6d  nction .** argum
30ea0 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  ent..**.** The c
30eb0 6f 6c 75 6d 6e 20 69 73 20 69 64 65 6e 74 69 66  olumn is identif
30ec0 69 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e  ied by the secon
30ed0 64 2c 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75  d, third and fou
30ee0 72 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74  rth parameters t
30ef0 6f 20 0a 2a 2a 20 74 68 69 73 20 66 75 6e 63 74  o .** this funct
30f00 69 6f 6e 2e 20 54 68 65 20 73 65 63 6f 6e 64 20  ion. The second 
30f10 70 61 72 61 6d 65 74 65 72 20 69 73 20 65 69 74  parameter is eit
30f20 68 65 72 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  her the name of 
30f30 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
30f40 28 69 2e 65 2e 20 22 6d 61 69 6e 22 2c 20 22 74  (i.e. "main", "t
30f50 65 6d 70 22 20 6f 72 20 61 6e 20 61 74 74 61 63  emp" or an attac
30f60 68 65 64 20 64 61 74 61 62 61 73 65 29 20 63 6f  hed database) co
30f70 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 73 70 65  ntaining the spe
30f80 63 69 66 69 65 64 0a 2a 2a 20 74 61 62 6c 65 20  cified.** table 
30f90 6f 72 20 4e 55 4c 4c 2e 20 49 66 20 69 74 20 69  or NULL. If it i
30fa0 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 61 6c 6c  s NULL, then all
30fb0 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61   attached databa
30fc0 73 65 73 20 61 72 65 20 73 65 61 72 63 68 65 64  ses are searched
30fd0 0a 2a 2a 20 66 6f 72 20 74 68 65 20 74 61 62 6c  .** for the tabl
30fe0 65 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65  e using the same
30ff0 20 61 6c 67 6f 72 69 74 68 6d 20 61 73 20 74 68   algorithm as th
31000 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e  e database engin
31010 65 20 75 73 65 73 20 74 6f 20 0a 2a 2a 20 72 65  e uses to .** re
31020 73 6f 6c 76 65 20 75 6e 71 75 61 6c 69 66 69 65  solve unqualifie
31030 64 20 74 61 62 6c 65 20 72 65 66 65 72 65 6e 63  d table referenc
31040 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68  es..**.** The th
31050 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 70  ird and fourth p
31060 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 69  arameters to thi
31070 73 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 74  s function are t
31080 68 65 20 74 61 62 6c 65 20 61 6e 64 20 63 6f 6c  he table and col
31090 75 6d 6e 20 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20  umn .** name of 
310a0 74 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c 75  the desired colu
310b0 6d 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79  mn, respectively
310c0 2e 20 4e 65 69 74 68 65 72 20 6f 66 20 74 68 65  . Neither of the
310d0 73 65 20 70 61 72 61 6d 65 74 65 72 73 20 0a 2a  se parameters .*
310e0 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c 2e 0a 2a  * may be NULL..*
310f0 2a 0a 2a 2a 20 4d 65 74 61 20 69 6e 66 6f 72 6d  *.** Meta inform
31100 61 74 69 6f 6e 20 69 73 20 72 65 74 75 72 6e 65  ation is returne
31110 64 20 62 79 20 77 72 69 74 69 6e 67 20 74 6f 20  d by writing to 
31120 74 68 65 20 6d 65 6d 6f 72 79 20 6c 6f 63 61 74  the memory locat
31130 69 6f 6e 73 20 70 61 73 73 65 64 20 61 73 0a 2a  ions passed as.*
31140 2a 20 74 68 65 20 35 74 68 20 61 6e 64 20 73 75  * the 5th and su
31150 62 73 65 71 75 65 6e 74 20 70 61 72 61 6d 65 74  bsequent paramet
31160 65 72 73 20 74 6f 20 74 68 69 73 20 66 75 6e 63  ers to this func
31170 74 69 6f 6e 2e 20 41 6e 79 20 6f 66 20 74 68 65  tion. Any of the
31180 73 65 20 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73  se .** arguments
31190 20 6d 61 79 20 62 65 20 4e 55 4c 4c 2c 20 69 6e   may be NULL, in
311a0 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20   which case the 
311b0 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 65 6c  corresponding el
311c0 65 6d 65 6e 74 20 6f 66 20 6d 65 74 61 20 0a 2a  ement of meta .*
311d0 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  * information is
311e0 20 6f 6d 6d 69 74 74 65 64 2e 0a 2a 2a 0a 2a 2a   ommitted..**.**
311f0 20 3c 70 72 65 3e 0a 2a 2a 20 50 61 72 61 6d 65   <pre>.** Parame
31200 74 65 72 20 20 20 20 20 4f 75 74 70 75 74 20 54  ter     Output T
31210 79 70 65 20 20 20 20 20 20 44 65 73 63 72 69 70  ype      Descrip
31220 74 69 6f 6e 0a 2a 2a 20 2d 2d 2d 2d 2d 2d 2d 2d  tion.** --------
31230 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
31240 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 0a 2a  -----------.**.*
31250 2a 20 20 20 35 74 68 20 20 20 20 20 20 20 20 20  *   5th         
31260 63 6f 6e 73 74 20 63 68 61 72 2a 20 20 20 20 20  const char*     
31270 20 44 61 74 61 20 74 79 70 65 0a 2a 2a 20 20 20   Data type.**   
31280 36 74 68 20 20 20 20 20 20 20 20 20 63 6f 6e 73  6th         cons
31290 74 20 63 68 61 72 2a 20 20 20 20 20 20 4e 61 6d  t char*      Nam
312a0 65 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74  e of the default
312b0 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
312c0 6e 63 65 20 0a 2a 2a 20 20 20 37 74 68 20 20 20  nce .**   7th   
312d0 20 20 20 20 20 20 69 6e 74 20 20 20 20 20 20 20        int       
312e0 20 20 20 20 20 20 20 54 72 75 65 20 69 66 20 74         True if t
312f0 68 65 20 63 6f 6c 75 6d 6e 20 68 61 73 20 61 20  he column has a 
31300 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61  NOT NULL constra
31310 69 6e 74 0a 2a 2a 20 20 20 38 74 68 20 20 20 20  int.**   8th    
31320 20 20 20 20 20 69 6e 74 20 20 20 20 20 20 20 20       int        
31330 20 20 20 20 20 20 54 72 75 65 20 69 66 20 74 68        True if th
31340 65 20 63 6f 6c 75 6d 6e 20 69 73 20 70 61 72 74  e column is part
31350 20 6f 66 20 74 68 65 20 50 52 49 4d 41 52 59 20   of the PRIMARY 
31360 4b 45 59 0a 2a 2a 20 20 20 39 74 68 20 20 20 20  KEY.**   9th    
31370 20 20 20 20 20 69 6e 74 20 20 20 20 20 20 20 20       int        
31380 20 20 20 20 20 20 54 72 75 65 20 69 66 20 74 68        True if th
31390 65 20 63 6f 6c 75 6d 6e 20 69 73 20 41 55 54 4f  e column is AUTO
313a0 49 4e 43 52 45 4d 45 4e 54 0a 2a 2a 20 3c 2f 70  INCREMENT.** </p
313b0 72 65 3e 0a 2a 2a 0a 2a 2a 0a 2a 2a 20 54 68 65  re>.**.**.** The
313c0 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 64 20   memory pointed 
313d0 74 6f 20 62 79 20 74 68 65 20 63 68 61 72 61 63  to by the charac
313e0 74 65 72 20 70 6f 69 6e 74 65 72 73 20 72 65 74  ter pointers ret
313f0 75 72 6e 65 64 20 66 6f 72 20 74 68 65 20 0a 2a  urned for the .*
31400 2a 20 64 65 63 6c 61 72 61 74 69 6f 6e 20 74 79  * declaration ty
31410 70 65 20 61 6e 64 20 63 6f 6c 6c 61 74 69 6f 6e  pe and collation
31420 20 73 65 71 75 65 6e 63 65 20 69 73 20 76 61 6c   sequence is val
31430 69 64 20 6f 6e 6c 79 20 75 6e 74 69 6c 20 74 68  id only until th
31440 65 20 6e 65 78 74 20 0a 2a 2a 20 63 61 6c 6c 20  e next .** call 
31450 74 6f 20 61 6e 79 20 73 71 6c 69 74 65 20 41 50  to any sqlite AP
31460 49 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a  I function..**.*
31470 2a 20 49 66 20 74 68 65 20 73 70 65 63 69 66 69  * If the specifi
31480 65 64 20 74 61 62 6c 65 20 69 73 20 61 63 74 75  ed table is actu
31490 61 6c 6c 79 20 61 20 76 69 65 77 2c 20 74 68 65  ally a view, the
314a0 6e 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65  n an error is re
314b0 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66  turned..**.** If
314c0 20 74 68 65 20 73 70 65 63 69 66 69 65 64 20 63   the specified c
314d0 6f 6c 75 6d 6e 20 69 73 20 22 72 6f 77 69 64 22  olumn is "rowid"
314e0 2c 20 22 6f 69 64 22 20 6f 72 20 22 5f 72 6f 77  , "oid" or "_row
314f0 69 64 5f 22 20 61 6e 64 20 61 6e 20 0a 2a 2a 20  id_" and an .** 
31500 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20  INTEGER PRIMARY 
31510 4b 45 59 20 63 6f 6c 75 6d 6e 20 68 61 73 20 62  KEY column has b
31520 65 65 6e 20 65 78 70 6c 69 63 69 74 6c 79 20 64  een explicitly d
31530 65 63 6c 61 72 65 64 2c 20 74 68 65 6e 20 74 68  eclared, then th
31540 65 20 6f 75 74 70 75 74 20 0a 2a 2a 20 70 61 72  e output .** par
31550 61 6d 65 74 65 72 73 20 61 72 65 20 73 65 74 20  ameters are set 
31560 66 6f 72 20 74 68 65 20 65 78 70 6c 69 63 69 74  for the explicit
31570 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75  ly declared colu
31580 6d 6e 2e 20 49 66 20 74 68 65 72 65 20 69 73 20  mn. If there is 
31590 6e 6f 0a 2a 2a 20 65 78 70 6c 69 63 69 74 6c 79  no.** explicitly
315a0 20 64 65 63 6c 61 72 65 64 20 49 50 4b 20 63 6f   declared IPK co
315b0 6c 75 6d 6e 2c 20 74 68 65 6e 20 74 68 65 20 6f  lumn, then the o
315c0 75 74 70 75 74 20 70 61 72 61 6d 65 74 65 72 73  utput parameters
315d0 20 61 72 65 20 73 65 74 20 61 73 20 0a 2a 2a 20   are set as .** 
315e0 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c  follows:.**.** <
315f0 70 72 65 3e 0a 2a 2a 20 20 20 20 20 64 61 74 61  pre>.**     data
31600 20 74 79 70 65 3a 20 22 49 4e 54 45 47 45 52 22   type: "INTEGER"
31610 0a 2a 2a 20 20 20 20 20 63 6f 6c 6c 61 74 69 6f  .**     collatio
31620 6e 20 73 65 71 75 65 6e 63 65 3a 20 22 42 49 4e  n sequence: "BIN
31630 41 52 59 22 0a 2a 2a 20 20 20 20 20 6e 6f 74 20  ARY".**     not 
31640 6e 75 6c 6c 3a 20 30 0a 2a 2a 20 20 20 20 20 70  null: 0.**     p
31650 72 69 6d 61 72 79 20 6b 65 79 3a 20 31 0a 2a 2a  rimary key: 1.**
31660 20 20 20 20 20 61 75 74 6f 20 69 6e 63 72 65 6d       auto increm
31670 65 6e 74 3a 20 30 0a 2a 2a 20 3c 2f 70 72 65 3e  ent: 0.** </pre>
31680 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63  .**.** This func
31690 74 69 6f 6e 20 6d 61 79 20 6c 6f 61 64 20 6f 6e  tion may load on
316a0 65 20 6f 72 20 6d 6f 72 65 20 73 63 68 65 6d 61  e or more schema
316b0 73 20 66 72 6f 6d 20 64 61 74 61 62 61 73 65 20  s from database 
316c0 66 69 6c 65 73 2e 20 49 66 20 61 6e 0a 2a 2a 20  files. If an.** 
316d0 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72  error occurs dur
316e0 69 6e 67 20 74 68 69 73 20 70 72 6f 63 65 73 73  ing this process
316f0 2c 20 6f 72 20 69 66 20 74 68 65 20 72 65 71 75  , or if the requ
31700 65 73 74 65 64 20 74 61 62 6c 65 20 6f 72 20 63  ested table or c
31710 6f 6c 75 6d 6e 0a 2a 2a 20 63 61 6e 6e 6f 74 20  olumn.** cannot 
31720 62 65 20 66 6f 75 6e 64 2c 20 61 6e 20 53 51 4c  be found, an SQL
31730 49 54 45 20 65 72 72 6f 72 20 63 6f 64 65 20 69  ITE error code i
31740 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 61  s returned and a
31750 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 0a  n error message.
31760 2a 2a 20 6c 65 66 74 20 69 6e 20 74 68 65 20 64  ** left in the d
31770 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 28  atabase handle (
31780 74 6f 20 62 65 20 72 65 74 72 69 65 76 65 64 20  to be retrieved 
31790 75 73 69 6e 67 20 73 71 6c 69 74 65 33 5f 65 72  using sqlite3_er
317a0 72 6d 73 67 28 29 29 2e 0a 2a 2a 0a 2a 2a 20 54  rmsg())..**.** T
317b0 68 69 73 20 41 50 49 20 69 73 20 6f 6e 6c 79 20  his API is only 
317c0 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65  available if the
317d0 20 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d   library was com
317e0 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  piled with the.*
317f0 2a 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f  * SQLITE_ENABLE_
31800 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 20  COLUMN_METADATA 
31810 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d  preprocessor sym
31820 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a  bol defined..*/.
31830 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 61 62 6c  int sqlite3_tabl
31840 65 5f 63 6f 6c 75 6d 6e 5f 6d 65 74 61 64 61 74  e_column_metadat
31850 61 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  a(.  sqlite3 *db
31860 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
31870 20 2f 2a 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 68   /* Connection h
31880 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
31890 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65 2c 20   char *zDbName, 
318a0 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
318b0 73 65 20 6e 61 6d 65 20 6f 72 20 4e 55 4c 4c 20  se name or NULL 
318c0 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
318d0 2a 7a 54 61 62 6c 65 4e 61 6d 65 2c 20 20 20 20  *zTableName,    
318e0 20 2f 2a 20 54 61 62 6c 65 20 6e 61 6d 65 20 2a   /* Table name *
318f0 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
31900 7a 43 6f 6c 75 6d 6e 4e 61 6d 65 2c 20 20 20 20  zColumnName,    
31910 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 61 6d 65 20 2a  /* Column name *
31920 2f 0a 20 20 63 68 61 72 20 63 6f 6e 73 74 20 2a  /.  char const *
31930 2a 70 7a 44 61 74 61 54 79 70 65 2c 20 20 20 20  *pzDataType,    
31940 2f 2a 20 4f 55 54 50 55 54 3a 20 44 65 63 6c 61  /* OUTPUT: Decla
31950 72 65 64 20 64 61 74 61 20 74 79 70 65 20 2a 2f  red data type */
31960 0a 20 20 63 68 61 72 20 63 6f 6e 73 74 20 2a 2a  .  char const **
31970 70 7a 43 6f 6c 6c 53 65 71 2c 20 20 20 20 20 2f  pzCollSeq,     /
31980 2a 20 4f 55 54 50 55 54 3a 20 43 6f 6c 6c 61 74  * OUTPUT: Collat
31990 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 6e 61 6d  ion sequence nam
319a0 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 4e 6f 74  e */.  int *pNot
319b0 4e 75 6c 6c 2c 20 20 20 20 20 20 20 20 20 20 20  Null,           
319c0 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72     /* OUTPUT: Tr
319d0 75 65 20 69 66 20 4e 4f 54 20 4e 55 4c 4c 20 63  ue if NOT NULL c
319e0 6f 6e 73 74 72 61 69 6e 74 20 65 78 69 73 74 73  onstraint exists
319f0 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 50 72 69 6d   */.  int *pPrim
31a00 61 72 79 4b 65 79 2c 20 20 20 20 20 20 20 20 20  aryKey,         
31a10 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75    /* OUTPUT: Tru
31a20 65 20 69 66 20 63 6f 6c 75 6d 6e 20 70 61 72 74  e if column part
31a30 20 6f 66 20 50 4b 20 2a 2f 0a 20 20 69 6e 74 20   of PK */.  int 
31a40 2a 70 41 75 74 6f 69 6e 63 20 20 20 20 20 20 20  *pAutoinc       
31a50 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55          /* OUTPU
31a60 54 3a 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d  T: True if colum
31a70 6e 20 69 73 20 61 75 74 6f 2d 69 6e 63 72 65 6d  n is auto-increm
31a80 65 6e 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  ent */.);../*.**
31a90 20 43 41 50 49 33 52 45 46 3a 20 4c 6f 61 64 20   CAPI3REF: Load 
31aa0 41 6e 20 45 78 74 65 6e 73 69 6f 6e 20 7b 46 31  An Extension {F1
31ab0 32 36 30 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  2600}.**.** {F12
31ac0 36 30 31 7d 20 54 68 65 20 73 71 6c 69 74 65 33  601} The sqlite3
31ad0 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28  _load_extension(
31ae0 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 61  ) interface.** a
31af0 74 74 65 6d 70 74 73 20 74 6f 20 6c 6f 61 64 20  ttempts to load 
31b00 61 6e 20 53 51 4c 69 74 65 20 65 78 74 65 6e 73  an SQLite extens
31b10 69 6f 6e 20 6c 69 62 72 61 72 79 20 63 6f 6e 74  ion library cont
31b20 61 69 6e 65 64 20 69 6e 20 74 68 65 20 66 69 6c  ained in the fil
31b30 65 0a 2a 2a 20 7a 46 69 6c 65 2e 20 7b 46 31 32  e.** zFile. {F12
31b40 36 30 32 7d 20 54 68 65 20 65 6e 74 72 79 20 70  602} The entry p
31b50 6f 69 6e 74 20 69 73 20 7a 50 72 6f 63 2e 20 7b  oint is zProc. {
31b60 46 31 32 36 30 33 7d 20 7a 50 72 6f 63 20 6d 61  F12603} zProc ma
31b70 79 20 62 65 20 30 0a 2a 2a 20 69 6e 20 77 68 69  y be 0.** in whi
31b80 63 68 20 63 61 73 65 20 74 68 65 20 6e 61 6d 65  ch case the name
31b90 20 6f 66 20 74 68 65 20 65 6e 74 72 79 20 70 6f   of the entry po
31ba0 69 6e 74 20 64 65 66 61 75 6c 74 73 0a 2a 2a 20  int defaults.** 
31bb0 74 6f 20 22 73 71 6c 69 74 65 33 5f 65 78 74 65  to "sqlite3_exte
31bc0 6e 73 69 6f 6e 5f 69 6e 69 74 22 2e 0a 2a 2a 0a  nsion_init"..**.
31bd0 2a 2a 20 7b 46 31 32 36 30 34 7d 20 54 68 65 20  ** {F12604} The 
31be0 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74  sqlite3_load_ext
31bf0 65 6e 73 69 6f 6e 28 29 20 69 6e 74 65 72 66 61  ension() interfa
31c00 63 65 20 73 68 61 6c 6c 0a 2a 2a 20 72 65 74 75  ce shall.** retu
31c10 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  rn [SQLITE_OK] o
31c20 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20 5b 53  n success and [S
31c30 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20  QLITE_ERROR] if 
31c40 73 6f 6d 65 74 68 69 6e 67 20 67 6f 65 73 20 77  something goes w
31c50 72 6f 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  rong..**.** {F12
31c60 36 30 35 7d 0a 2a 2a 20 49 66 20 61 6e 20 65 72  605}.** If an er
31c70 72 6f 72 20 6f 63 63 75 72 73 20 61 6e 64 20 70  ror occurs and p
31c80 7a 45 72 72 4d 73 67 20 69 73 20 6e 6f 74 20 30  zErrMsg is not 0
31c90 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 73 71  , then the.** sq
31ca0 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e  lite3_load_exten
31cb0 73 69 6f 6e 28 29 20 69 6e 74 65 72 66 61 63 65  sion() interface
31cc0 20 73 68 61 6c 6c 20 61 74 74 65 6d 70 74 20 74   shall attempt t
31cd0 6f 20 66 69 6c 6c 20 2a 70 7a 45 72 72 4d 73 67  o fill *pzErrMsg
31ce0 20 77 69 74 68 20 0a 2a 2a 20 65 72 72 6f 72 20   with .** error 
31cf0 6d 65 73 73 61 67 65 20 74 65 78 74 20 73 74 6f  message text sto
31d00 72 65 64 20 69 6e 20 6d 65 6d 6f 72 79 20 6f 62  red in memory ob
31d10 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
31d20 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a  ite3_malloc()]..
31d30 2a 2a 20 7b 45 4e 44 7d 20 20 54 68 65 20 63 61  ** {END}  The ca
31d40 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 73  lling function s
31d50 68 6f 75 6c 64 20 66 72 65 65 20 74 68 69 73 20  hould free this 
31d60 6d 65 6d 6f 72 79 0a 2a 2a 20 62 79 20 63 61 6c  memory.** by cal
31d70 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72  ling [sqlite3_fr
31d80 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  ee()]..**.** {F1
31d90 32 36 30 36 7d 0a 2a 2a 20 45 78 74 65 6e 73 69  2606}.** Extensi
31da0 6f 6e 20 6c 6f 61 64 69 6e 67 20 6d 75 73 74 20  on loading must 
31db0 62 65 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67  be enabled using
31dc0 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65   [sqlite3_enable
31dd0 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28  _load_extension(
31de0 29 5d 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63  )].** prior to c
31df0 61 6c 6c 69 6e 67 20 74 68 69 73 20 41 50 49 20  alling this API 
31e00 6f 72 20 61 6e 20 65 72 72 6f 72 20 77 69 6c 6c  or an error will
31e10 20 62 65 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2f   be returned..*/
31e20 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 6f 61  .int sqlite3_loa
31e30 64 5f 65 78 74 65 6e 73 69 6f 6e 28 0a 20 20 73  d_extension(.  s
31e40 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
31e50 20 20 20 20 20 2f 2a 20 4c 6f 61 64 20 74 68 65       /* Load the
31e60 20 65 78 74 65 6e 73 69 6f 6e 20 69 6e 74 6f 20   extension into 
31e70 74 68 69 73 20 64 61 74 61 62 61 73 65 20 63 6f  this database co
31e80 6e 6e 65 63 74 69 6f 6e 20 2a 2f 0a 20 20 63 6f  nnection */.  co
31e90 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c  nst char *zFile,
31ea0 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74      /* Name of t
31eb0 68 65 20 73 68 61 72 65 64 20 6c 69 62 72 61 72  he shared librar
31ec0 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 65 78 74  y containing ext
31ed0 65 6e 73 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73  ension */.  cons
31ee0 74 20 63 68 61 72 20 2a 7a 50 72 6f 63 2c 20 20  t char *zProc,  
31ef0 20 20 2f 2a 20 45 6e 74 72 79 20 70 6f 69 6e 74    /* Entry point
31f00 2e 20 20 44 65 72 69 76 65 64 20 66 72 6f 6d 20  .  Derived from 
31f10 7a 46 69 6c 65 20 69 66 20 30 20 2a 2f 0a 20 20  zFile if 0 */.  
31f20 63 68 61 72 20 2a 2a 70 7a 45 72 72 4d 73 67 20  char **pzErrMsg 
31f30 20 20 20 20 20 20 2f 2a 20 50 75 74 20 65 72 72        /* Put err
31f40 6f 72 20 6d 65 73 73 61 67 65 20 68 65 72 65 20  or message here 
31f50 69 66 20 6e 6f 74 20 30 20 2a 2f 0a 29 3b 0a 0a  if not 0 */.);..
31f60 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
31f70 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62   Enable Or Disab
31f80 6c 65 20 45 78 74 65 6e 73 69 6f 6e 20 4c 6f 61  le Extension Loa
31f90 64 69 6e 67 20 7b 46 31 32 36 32 30 7d 0a 2a 2a  ding {F12620}.**
31fa0 0a 2a 2a 20 53 6f 20 61 73 20 6e 6f 74 20 74 6f  .** So as not to
31fb0 20 6f 70 65 6e 20 73 65 63 75 72 69 74 79 20 68   open security h
31fc0 6f 6c 65 73 20 69 6e 20 6f 6c 64 65 72 20 61 70  oles in older ap
31fd0 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
31fe0 61 72 65 0a 2a 2a 20 75 6e 70 72 65 70 61 72 65  are.** unprepare
31ff0 64 20 74 6f 20 64 65 61 6c 20 77 69 74 68 20 65  d to deal with e
32000 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67  xtension loading
32010 2c 20 61 6e 64 20 61 73 20 61 20 6d 65 61 6e 73  , and as a means
32020 20 6f 66 20 64 69 73 61 62 6c 69 6e 67 0a 2a 2a   of disabling.**
32030 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69   extension loadi
32040 6e 67 20 77 68 69 6c 65 20 65 76 61 6c 75 61 74  ng while evaluat
32050 69 6e 67 20 75 73 65 72 2d 65 6e 74 65 72 65 64  ing user-entered
32060 20 53 51 4c 2c 20 74 68 65 20 66 6f 6c 6c 6f 77   SQL, the follow
32070 69 6e 67 0a 2a 2a 20 41 50 49 20 69 73 20 70 72  ing.** API is pr
32080 6f 76 69 64 65 64 20 74 6f 20 74 75 72 6e 20 74  ovided to turn t
32090 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64  he [sqlite3_load
320a0 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 6d 65  _extension()] me
320b0 63 68 61 6e 69 73 6d 20 6f 6e 20 61 6e 64 0a 2a  chanism on and.*
320c0 2a 20 6f 66 66 2e 20 20 7b 46 31 32 36 32 32 7d  * off.  {F12622}
320d0 20 49 74 20 69 73 20 6f 66 66 20 62 79 20 64 65   It is off by de
320e0 66 61 75 6c 74 2e 20 7b 45 4e 44 7d 20 53 65 65  fault. {END} See
320f0 20 74 69 63 6b 65 74 20 23 31 38 36 33 2e 0a 2a   ticket #1863..*
32100 2a 0a 2a 2a 20 7b 46 31 32 36 32 31 7d 20 43 61  *.** {F12621} Ca
32110 6c 6c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65  ll the sqlite3_e
32120 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e  nable_load_exten
32130 73 69 6f 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a  sion() routine.*
32140 2a 20 77 69 74 68 20 6f 6e 6f 66 66 3d 3d 31 20  * with onoff==1 
32150 74 6f 20 74 75 72 6e 20 65 78 74 65 6e 73 69 6f  to turn extensio
32160 6e 20 6c 6f 61 64 69 6e 67 20 6f 6e 0a 2a 2a 20  n loading on.** 
32170 61 6e 64 20 63 61 6c 6c 20 69 74 20 77 69 74 68  and call it with
32180 20 6f 6e 6f 66 66 3d 3d 30 20 74 6f 20 74 75 72   onoff==0 to tur
32190 6e 20 69 74 20 62 61 63 6b 20 6f 66 66 20 61 67  n it back off ag
321a0 61 69 6e 2e 20 7b 45 4e 44 7d 0a 2a 2f 0a 69 6e  ain. {END}.*/.in
321b0 74 20 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65  t sqlite3_enable
321c0 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28  _load_extension(
321d0 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 69 6e 74  sqlite3 *db, int
321e0 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20   onoff);../*.** 
321f0 43 41 50 49 33 52 45 46 3a 20 4d 61 6b 65 20 41  CAPI3REF: Make A
32200 72 72 61 6e 67 65 6d 65 6e 74 73 20 54 6f 20 41  rrangements To A
32210 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 4c 6f 61  utomatically Loa
32220 64 20 41 6e 20 45 78 74 65 6e 73 69 6f 6e 20 7b  d An Extension {
32230 46 31 32 36 34 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46  F12640}.**.** {F
32240 31 32 36 34 31 7d 20 54 68 69 73 20 66 75 6e 63  12641} This func
32250 74 69 6f 6e 0a 2a 2a 20 72 65 67 69 73 74 65 72  tion.** register
32260 73 20 61 6e 20 65 78 74 65 6e 73 69 6f 6e 20 65  s an extension e
32270 6e 74 72 79 20 70 6f 69 6e 74 20 74 68 61 74 20  ntry point that 
32280 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  is automatically
32290 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e   invoked.** when
322a0 65 76 65 72 20 61 20 6e 65 77 20 64 61 74 61 62  ever a new datab
322b0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
322c0 73 20 6f 70 65 6e 65 64 20 75 73 69 6e 67 0a 2a  s opened using.*
322d0 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  * [sqlite3_open(
322e0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
322f0 6e 31 36 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69  n16()], or [sqli
32300 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20  te3_open_v2()]. 
32310 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73  {END}.**.** This
32320 20 41 50 49 20 63 61 6e 20 62 65 20 69 6e 76 6f   API can be invo
32330 6b 65 64 20 61 74 20 70 72 6f 67 72 61 6d 20 73  ked at program s
32340 74 61 72 74 75 70 20 69 6e 20 6f 72 64 65 72 20  tartup in order 
32350 74 6f 20 72 65 67 69 73 74 65 72 0a 2a 2a 20 6f  to register.** o
32360 6e 65 20 6f 72 20 6d 6f 72 65 20 73 74 61 74 69  ne or more stati
32370 63 61 6c 6c 79 20 6c 69 6e 6b 65 64 20 65 78 74  cally linked ext
32380 65 6e 73 69 6f 6e 73 20 74 68 61 74 20 77 69 6c  ensions that wil
32390 6c 20 62 65 20 61 76 61 69 6c 61 62 6c 65 0a 2a  l be available.*
323a0 2a 20 74 6f 20 61 6c 6c 20 6e 65 77 20 64 61 74  * to all new dat
323b0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
323c0 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36 34 32  s..**.** {F12642
323d0 7d 20 44 75 70 6c 69 63 61 74 65 20 65 78 74 65  } Duplicate exte
323e0 6e 73 69 6f 6e 73 20 61 72 65 20 64 65 74 65 63  nsions are detec
323f0 74 65 64 20 73 6f 20 63 61 6c 6c 69 6e 67 20 74  ted so calling t
32400 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 6c 74  his routine mult
32410 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 20 77 69  iple.** times wi
32420 74 68 20 74 68 65 20 73 61 6d 65 20 65 78 74 65  th the same exte
32430 6e 73 69 6f 6e 20 69 73 20 68 61 72 6d 6c 65 73  nsion is harmles
32440 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36 34 33  s..**.** {F12643
32450 7d 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73  } This routine s
32460 74 6f 72 65 73 20 61 20 70 6f 69 6e 74 65 72 20  tores a pointer 
32470 74 6f 20 74 68 65 20 65 78 74 65 6e 73 69 6f 6e  to the extension
32480 20 69 6e 20 61 6e 20 61 72 72 61 79 0a 2a 2a 20   in an array.** 
32490 74 68 61 74 20 69 73 20 6f 62 74 61 69 6e 65 64  that is obtained
324a0 20 66 72 6f 6d 20 73 71 6c 69 74 65 5f 6d 61 6c   from sqlite_mal
324b0 6c 6f 63 28 29 2e 20 7b 45 4e 44 7d 20 49 66 20  loc(). {END} If 
324c0 79 6f 75 20 72 75 6e 20 61 20 6d 65 6d 6f 72 79  you run a memory
324d0 20 6c 65 61 6b 0a 2a 2a 20 63 68 65 63 6b 65 72   leak.** checker
324e0 20 6f 6e 20 79 6f 75 72 20 70 72 6f 67 72 61 6d   on your program
324f0 20 61 6e 64 20 69 74 20 72 65 70 6f 72 74 73 20   and it reports 
32500 61 20 6c 65 61 6b 20 62 65 63 61 75 73 65 20 6f  a leak because o
32510 66 20 74 68 69 73 0a 2a 2a 20 61 72 72 61 79 2c  f this.** array,
32520 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 5b 73 71   then invoke [sq
32530 6c 69 74 65 33 5f 72 65 73 65 74 5f 61 75 74 6f  lite3_reset_auto
32540 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 70 72  _extension()] pr
32550 69 6f 72 0a 2a 2a 20 74 6f 20 73 68 75 74 64 6f  ior.** to shutdo
32560 77 6e 20 74 6f 20 66 72 65 65 20 74 68 65 20 6d  wn to free the m
32570 65 6d 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  emory..**.** {F1
32580 32 36 34 34 7d 20 41 75 74 6f 6d 61 74 69 63 20  2644} Automatic 
32590 65 78 74 65 6e 73 69 6f 6e 73 20 61 70 70 6c 79  extensions apply
325a0 20 61 63 72 6f 73 73 20 61 6c 6c 20 74 68 72 65   across all thre
325b0 61 64 73 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a  ads. {END}.**.**
325c0 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   This interface 
325d0 69 73 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20  is experimental 
325e0 61 6e 64 20 69 73 20 73 75 62 6a 65 63 74 20 74  and is subject t
325f0 6f 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 72  o change or.** r
32600 65 6d 6f 76 61 6c 20 69 6e 20 66 75 74 75 72 65  emoval in future
32610 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
32620 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ite..*/.int sqli
32630 74 65 33 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69  te3_auto_extensi
32640 6f 6e 28 76 6f 69 64 20 2a 78 45 6e 74 72 79 50  on(void *xEntryP
32650 6f 69 6e 74 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43  oint);.../*.** C
32660 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41  API3REF: Reset A
32670 75 74 6f 6d 61 74 69 63 20 45 78 74 65 6e 73 69  utomatic Extensi
32680 6f 6e 20 4c 6f 61 64 69 6e 67 20 7b 46 31 32 36  on Loading {F126
32690 36 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36 36  60}.**.** {F1266
326a0 31 7d 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  1} This function
326b0 20 64 69 73 61 62 6c 65 73 20 61 6c 6c 20 70 72   disables all pr
326c0 65 76 69 6f 75 73 6c 79 20 72 65 67 69 73 74 65  eviously registe
326d0 72 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63  red.** automatic
326e0 20 65 78 74 65 6e 73 69 6f 6e 73 2e 20 7b 45 4e   extensions. {EN
326f0 44 7d 20 20 54 68 69 73 0a 2a 2a 20 72 6f 75 74  D}  This.** rout
32700 69 6e 65 20 75 6e 64 6f 65 73 20 74 68 65 20 65  ine undoes the e
32710 66 66 65 63 74 20 6f 66 20 61 6c 6c 20 70 72 69  ffect of all pri
32720 6f 72 20 5b 73 71 6c 69 74 65 33 5f 61 75 74 6f  or [sqlite3_auto
32730 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 0a 2a 2a  _extension()].**
32740 20 63 61 6c 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46   calls..**.** {F
32750 31 32 36 36 32 7d 20 54 68 69 73 20 63 61 6c 6c  12662} This call
32760 20 64 69 73 61 62 6c 65 64 20 61 75 74 6f 6d 61   disabled automa
32770 74 69 63 20 65 78 74 65 6e 73 69 6f 6e 73 20 69  tic extensions i
32780 6e 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 20 7b  n all threads. {
32790 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  END}.**.** This 
327a0 69 6e 74 65 72 66 61 63 65 20 69 73 20 65 78 70  interface is exp
327b0 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73  erimental and is
327c0 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e   subject to chan
327d0 67 65 20 6f 72 0a 2a 2a 20 72 65 6d 6f 76 61 6c  ge or.** removal
327e0 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
327f0 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ses of SQLite..*
32800 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  /.void sqlite3_r
32810 65 73 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73  eset_auto_extens
32820 69 6f 6e 28 76 6f 69 64 29 3b 0a 0a 0a 2f 2a 0a  ion(void);.../*.
32830 2a 2a 2a 2a 2a 2a 20 45 58 50 45 52 49 4d 45 4e  ****** EXPERIMEN
32840 54 41 4c 20 2d 20 73 75 62 6a 65 63 74 20 74 6f  TAL - subject to
32850 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75 74 20   change without 
32860 6e 6f 74 69 63 65 20 2a 2a 2a 2a 2a 2a 2a 2a 2a  notice *********
32870 2a 2a 2a 2a 2a 0a 2a 2a 0a 2a 2a 20 54 68 65 20  *****.**.** The 
32880 69 6e 74 65 72 66 61 63 65 20 74 6f 20 74 68 65  interface to the
32890 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d   virtual-table m
328a0 65 63 68 61 6e 69 73 6d 20 69 73 20 63 75 72 72  echanism is curr
328b0 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 64  ently considered
328c0 0a 2a 2a 20 74 6f 20 62 65 20 65 78 70 65 72 69  .** to be experi
328d0 6d 65 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e 74  mental.  The int
328e0 65 72 66 61 63 65 20 6d 69 67 68 74 20 63 68 61  erface might cha
328f0 6e 67 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74 69  nge in incompati
32900 62 6c 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66 20  ble ways..** If 
32910 74 68 69 73 20 69 73 20 61 20 70 72 6f 62 6c 65  this is a proble
32920 6d 20 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e 6f  m for you, do no
32930 74 20 75 73 65 20 74 68 65 20 69 6e 74 65 72 66  t use the interf
32940 61 63 65 20 61 74 20 74 68 69 73 20 74 69 6d 65  ace at this time
32950 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65  ..**.** When the
32960 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d   virtual-table m
32970 65 63 68 61 6e 69 73 6d 20 73 74 61 62 6c 69 7a  echanism stabliz
32980 65 73 2c 20 77 65 20 77 69 6c 6c 20 64 65 63 6c  es, we will decl
32990 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74 65 72  are the.** inter
329a0 66 61 63 65 20 66 69 78 65 64 2c 20 73 75 70 70  face fixed, supp
329b0 6f 72 74 20 69 74 20 69 6e 64 65 66 69 6e 69 74  ort it indefinit
329c0 65 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76 65 20  ely, and remove 
329d0 74 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2f  this comment..*/
329e0 0a 0a 2f 2a 0a 2a 2a 20 53 74 72 75 63 74 75 72  ../*.** Structur
329f0 65 73 20 75 73 65 64 20 62 79 20 74 68 65 20 76  es used by the v
32a00 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6e 74  irtual table int
32a10 65 72 66 61 63 65 0a 2a 2f 0a 74 79 70 65 64 65  erface.*/.typede
32a20 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
32a30 5f 76 74 61 62 20 73 71 6c 69 74 65 33 5f 76 74  _vtab sqlite3_vt
32a40 61 62 3b 0a 74 79 70 65 64 65 66 20 73 74 72 75  ab;.typedef stru
32a50 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78  ct sqlite3_index
32a60 5f 69 6e 66 6f 20 73 71 6c 69 74 65 33 5f 69 6e  _info sqlite3_in
32a70 64 65 78 5f 69 6e 66 6f 3b 0a 74 79 70 65 64 65  dex_info;.typede
32a80 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
32a90 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 73 71 6c  _vtab_cursor sql
32aa0 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72  ite3_vtab_cursor
32ab0 3b 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  ;.typedef struct
32ac0 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20   sqlite3_module 
32ad0 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 3b 0a  sqlite3_module;.
32ae0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
32af0 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 4f   Virtual Table O
32b00 62 6a 65 63 74 20 7b 46 31 38 30 30 30 7d 0a 2a  bject {F18000}.*
32b10 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69  * KEYWORDS: sqli
32b20 74 65 33 5f 6d 6f 64 75 6c 65 0a 2a 2a 0a 2a 2a  te3_module.**.**
32b30 20 41 20 6d 6f 64 75 6c 65 20 69 73 20 61 20 63   A module is a c
32b40 6c 61 73 73 20 6f 66 20 76 69 72 74 75 61 6c 20  lass of virtual 
32b50 74 61 62 6c 65 73 2e 20 20 45 61 63 68 20 6d 6f  tables.  Each mo
32b60 64 75 6c 65 20 69 73 20 64 65 66 69 6e 65 64 0a  dule is defined.
32b70 2a 2a 20 62 79 20 61 6e 20 69 6e 73 74 61 6e 63  ** by an instanc
32b80 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  e of the followi
32b90 6e 67 20 73 74 72 75 63 74 75 72 65 2e 20 20 54  ng structure.  T
32ba0 68 69 73 20 73 74 72 75 63 74 75 72 65 20 63 6f  his structure co
32bb0 6e 73 69 73 74 73 0a 2a 2a 20 6d 6f 73 74 6c 79  nsists.** mostly
32bc0 20 6f 66 20 6d 65 74 68 6f 64 73 20 66 6f 72 20   of methods for 
32bd0 74 68 65 20 6d 6f 64 75 6c 65 2e 0a 2a 2f 0a 73  the module..*/.s
32be0 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 6f  truct sqlite3_mo
32bf0 64 75 6c 65 20 7b 0a 20 20 69 6e 74 20 69 56 65  dule {.  int iVe
32c00 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78  rsion;.  int (*x
32c10 43 72 65 61 74 65 29 28 73 71 6c 69 74 65 33 2a  Create)(sqlite3*
32c20 2c 20 76 6f 69 64 20 2a 70 41 75 78 2c 0a 20 20  , void *pAux,.  
32c30 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74               int
32c40 20 61 72 67 63 2c 20 63 6f 6e 73 74 20 63 68 61   argc, const cha
32c50 72 20 2a 63 6f 6e 73 74 2a 61 72 67 76 2c 0a 20  r *const*argv,. 
32c60 20 20 20 20 20 20 20 20 20 20 20 20 20 20 73 71                sq
32c70 6c 69 74 65 33 5f 76 74 61 62 20 2a 2a 70 70 56  lite3_vtab **ppV
32c80 54 61 62 2c 20 63 68 61 72 2a 2a 29 3b 0a 20 20  Tab, char**);.  
32c90 69 6e 74 20 28 2a 78 43 6f 6e 6e 65 63 74 29 28  int (*xConnect)(
32ca0 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 20 2a  sqlite3*, void *
32cb0 70 41 75 78 2c 0a 20 20 20 20 20 20 20 20 20 20  pAux,.          
32cc0 20 20 20 20 20 69 6e 74 20 61 72 67 63 2c 20 63       int argc, c
32cd0 6f 6e 73 74 20 63 68 61 72 20 2a 63 6f 6e 73 74  onst char *const
32ce0 2a 61 72 67 76 2c 0a 20 20 20 20 20 20 20 20 20  *argv,.         
32cf0 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 76 74        sqlite3_vt
32d00 61 62 20 2a 2a 70 70 56 54 61 62 2c 20 63 68 61  ab **ppVTab, cha
32d10 72 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 42  r**);.  int (*xB
32d20 65 73 74 49 6e 64 65 78 29 28 73 71 6c 69 74 65  estIndex)(sqlite
32d30 33 5f 76 74 61 62 20 2a 70 56 54 61 62 2c 20 73  3_vtab *pVTab, s
32d40 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66  qlite3_index_inf
32d50 6f 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 69  o*);.  int (*xDi
32d60 73 63 6f 6e 6e 65 63 74 29 28 73 71 6c 69 74 65  sconnect)(sqlite
32d70 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a  3_vtab *pVTab);.
32d80 20 20 69 6e 74 20 28 2a 78 44 65 73 74 72 6f 79    int (*xDestroy
32d90 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a  )(sqlite3_vtab *
32da0 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a  pVTab);.  int (*
32db0 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76  xOpen)(sqlite3_v
32dc0 74 61 62 20 2a 70 56 54 61 62 2c 20 73 71 6c 69  tab *pVTab, sqli
32dd0 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20  te3_vtab_cursor 
32de0 2a 2a 70 70 43 75 72 73 6f 72 29 3b 0a 20 20 69  **ppCursor);.  i
32df0 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c  nt (*xClose)(sql
32e00 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72  ite3_vtab_cursor
32e10 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c  *);.  int (*xFil
32e20 74 65 72 29 28 73 71 6c 69 74 65 33 5f 76 74 61  ter)(sqlite3_vta
32e30 62 5f 63 75 72 73 6f 72 2a 2c 20 69 6e 74 20 69  b_cursor*, int i
32e40 64 78 4e 75 6d 2c 20 63 6f 6e 73 74 20 63 68 61  dxNum, const cha
32e50 72 20 2a 69 64 78 53 74 72 2c 0a 20 20 20 20 20  r *idxStr,.     
32e60 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 61             int a
32e70 72 67 63 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c  rgc, sqlite3_val
32e80 75 65 20 2a 2a 61 72 67 76 29 3b 0a 20 20 69 6e  ue **argv);.  in
32e90 74 20 28 2a 78 4e 65 78 74 29 28 73 71 6c 69 74  t (*xNext)(sqlit
32ea0 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 29  e3_vtab_cursor*)
32eb0 3b 0a 20 20 69 6e 74 20 28 2a 78 45 6f 66 29 28  ;.  int (*xEof)(
32ec0 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72  sqlite3_vtab_cur
32ed0 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  sor*);.  int (*x
32ee0 43 6f 6c 75 6d 6e 29 28 73 71 6c 69 74 65 33 5f  Column)(sqlite3_
32ef0 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 73 71  vtab_cursor*, sq
32f00 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
32f10 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52  int);.  int (*xR
32f20 6f 77 69 64 29 28 73 71 6c 69 74 65 33 5f 76 74  owid)(sqlite3_vt
32f30 61 62 5f 63 75 72 73 6f 72 2a 2c 20 73 71 6c 69  ab_cursor*, sqli
32f40 74 65 33 5f 69 6e 74 36 34 20 2a 70 52 6f 77 69  te3_int64 *pRowi
32f50 64 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 70 64  d);.  int (*xUpd
32f60 61 74 65 29 28 73 71 6c 69 74 65 33 5f 76 74 61  ate)(sqlite3_vta
32f70 62 20 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65  b *, int, sqlite
32f80 33 5f 76 61 6c 75 65 20 2a 2a 2c 20 73 71 6c 69  3_value **, sqli
32f90 74 65 33 5f 69 6e 74 36 34 20 2a 29 3b 0a 20 20  te3_int64 *);.  
32fa0 69 6e 74 20 28 2a 78 42 65 67 69 6e 29 28 73 71  int (*xBegin)(sq
32fb0 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61  lite3_vtab *pVTa
32fc0 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e  b);.  int (*xSyn
32fd0 63 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20  c)(sqlite3_vtab 
32fe0 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28  *pVTab);.  int (
32ff0 2a 78 43 6f 6d 6d 69 74 29 28 73 71 6c 69 74 65  *xCommit)(sqlite
33000 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a  3_vtab *pVTab);.
33010 20 20 69 6e 74 20 28 2a 78 52 6f 6c 6c 62 61 63    int (*xRollbac
33020 6b 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20  k)(sqlite3_vtab 
33030 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28  *pVTab);.  int (
33040 2a 78 46 69 6e 64 46 75 6e 63 74 69 6f 6e 29 28  *xFindFunction)(
33050 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56  sqlite3_vtab *pV
33060 74 61 62 2c 20 69 6e 74 20 6e 41 72 67 2c 20 63  tab, int nArg, c
33070 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
33080 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
33090 20 20 20 20 20 20 20 20 20 76 6f 69 64 20 28 2a           void (*
330a0 2a 70 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33  *pxFunc)(sqlite3
330b0 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
330c0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
330d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
330e0 20 20 20 20 20 20 20 76 6f 69 64 20 2a 2a 70 70         void **pp
330f0 41 72 67 29 3b 0a 0a 20 20 69 6e 74 20 28 2a 78  Arg);..  int (*x
33100 52 65 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f  Rename)(sqlite3_
33110 76 74 61 62 20 2a 70 56 74 61 62 2c 20 63 6f 6e  vtab *pVtab, con
33120 73 74 20 63 68 61 72 20 2a 7a 4e 65 77 29 3b 0a  st char *zNew);.
33130 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
33140 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c  EF: Virtual Tabl
33150 65 20 49 6e 64 65 78 69 6e 67 20 49 6e 66 6f 72  e Indexing Infor
33160 6d 61 74 69 6f 6e 20 7b 46 31 38 31 30 30 7d 0a  mation {F18100}.
33170 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c  ** KEYWORDS: sql
33180 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 0a  ite3_index_info.
33190 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
331a0 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73 74 72  3_index_info str
331b0 75 63 74 75 72 65 20 61 6e 64 20 69 74 73 20 73  ucture and its s
331c0 75 62 73 74 72 75 63 74 75 72 65 73 20 69 73 20  ubstructures is 
331d0 75 73 65 64 20 74 6f 0a 2a 2a 20 70 61 73 73 20  used to.** pass 
331e0 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 6e 74 6f  information into
331f0 20 61 6e 64 20 72 65 63 65 69 76 65 20 74 68 65   and receive the
33200 20 72 65 70 6c 79 20 66 72 6f 6d 20 74 68 65 20   reply from the 
33210 78 42 65 73 74 49 6e 64 65 78 0a 2a 2a 20 6d 65  xBestIndex.** me
33220 74 68 6f 64 20 6f 66 20 61 6e 20 73 71 6c 69 74  thod of an sqlit
33230 65 33 5f 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20  e3_module.  The 
33240 66 69 65 6c 64 73 20 75 6e 64 65 72 20 2a 2a 49  fields under **I
33250 6e 70 75 74 73 2a 2a 20 61 72 65 20 74 68 65 0a  nputs** are the.
33260 2a 2a 20 69 6e 70 75 74 73 20 74 6f 20 78 42 65  ** inputs to xBe
33270 73 74 49 6e 64 65 78 20 61 6e 64 20 61 72 65 20  stIndex and are 
33280 72 65 61 64 2d 6f 6e 6c 79 2e 20 20 78 42 65 73  read-only.  xBes
33290 74 49 6e 64 65 78 20 69 6e 73 65 72 74 73 20 69  tIndex inserts i
332a0 74 73 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e  ts.** results in
332b0 74 6f 20 74 68 65 20 2a 2a 4f 75 74 70 75 74 73  to the **Outputs
332c0 2a 2a 20 66 69 65 6c 64 73 2e 0a 2a 2a 0a 2a 2a  ** fields..**.**
332d0 20 54 68 65 20 61 43 6f 6e 73 74 72 61 69 6e 74   The aConstraint
332e0 5b 5d 20 61 72 72 61 79 20 72 65 63 6f 72 64 73  [] array records
332f0 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 63 6f   WHERE clause co
33300 6e 73 74 72 61 69 6e 74 73 20 6f 66 20 74 68 65  nstraints of the
33310 0a 2a 2a 20 66 6f 72 6d 3a 0a 2a 2a 0a 2a 2a 20  .** form:.**.** 
33320 20 20 20 20 20 20 20 20 63 6f 6c 75 6d 6e 20 4f          column O
33330 50 20 65 78 70 72 0a 2a 2a 0a 2a 2a 20 57 68 65  P expr.**.** Whe
33340 72 65 20 4f 50 20 69 73 20 3d 2c 20 26 6c 74 3b  re OP is =, &lt;
33350 2c 20 26 6c 74 3b 3d 2c 20 26 67 74 3b 2c 20 6f  , &lt;=, &gt;, o
33360 72 20 26 67 74 3b 3d 2e 20 20 0a 2a 2a 20 54 68  r &gt;=.  .** Th
33370 65 20 70 61 72 74 69 63 75 6c 61 72 20 6f 70 65  e particular ope
33380 72 61 74 6f 72 20 69 73 20 73 74 6f 72 65 64 0a  rator is stored.
33390 2a 2a 20 69 6e 20 61 43 6f 6e 73 74 72 61 69 6e  ** in aConstrain
333a0 74 5b 5d 2e 6f 70 2e 20 20 54 68 65 20 69 6e 64  t[].op.  The ind
333b0 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  ex of the column
333c0 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 0a 2a   is stored in .*
333d0 2a 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e  * aConstraint[].
333e0 69 43 6f 6c 75 6d 6e 2e 20 20 61 43 6f 6e 73 74  iColumn.  aConst
333f0 72 61 69 6e 74 5b 5d 2e 75 73 61 62 6c 65 20 69  raint[].usable i
33400 73 20 54 52 55 45 20 69 66 20 74 68 65 0a 2a 2a  s TRUE if the.**
33410 20 65 78 70 72 20 6f 6e 20 74 68 65 20 72 69 67   expr on the rig
33420 68 74 2d 68 61 6e 64 20 73 69 64 65 20 63 61 6e  ht-hand side can
33430 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 28 61   be evaluated (a
33440 6e 64 20 74 68 75 73 20 74 68 65 20 63 6f 6e 73  nd thus the cons
33450 74 72 61 69 6e 74 0a 2a 2a 20 69 73 20 75 73 61  traint.** is usa
33460 62 6c 65 29 20 61 6e 64 20 66 61 6c 73 65 20 69  ble) and false i
33470 66 20 69 74 20 63 61 6e 6e 6f 74 2e 0a 2a 2a 0a  f it cannot..**.
33480 2a 2a 20 54 68 65 20 6f 70 74 69 6d 69 7a 65 72  ** The optimizer
33490 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69   automatically i
334a0 6e 76 65 72 74 73 20 74 65 72 6d 73 20 6f 66 20  nverts terms of 
334b0 74 68 65 20 66 6f 72 6d 20 22 65 78 70 72 20 4f  the form "expr O
334c0 50 20 63 6f 6c 75 6d 6e 22 0a 2a 2a 20 61 6e 64  P column".** and
334d0 20 6d 61 6b 65 73 20 6f 74 68 65 72 20 73 69 6d   makes other sim
334e0 70 6c 69 66 69 63 61 74 69 6f 6e 73 20 74 6f 20  plifications to 
334f0 74 68 65 20 57 48 45 52 45 20 63 6c 61 75 73 65  the WHERE clause
33500 20 69 6e 20 61 6e 20 61 74 74 65 6d 70 74 20 74   in an attempt t
33510 6f 0a 2a 2a 20 67 65 74 20 61 73 20 6d 61 6e 79  o.** get as many
33520 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 74 65   WHERE clause te
33530 72 6d 73 20 69 6e 74 6f 20 74 68 65 20 66 6f 72  rms into the for
33540 6d 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 61 73  m shown above as
33550 20 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a 20 54 68   possible..** Th
33560 65 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20  e aConstraint[] 
33570 61 72 72 61 79 20 6f 6e 6c 79 20 72 65 70 6f 72  array only repor
33580 74 73 20 57 48 45 52 45 20 63 6c 61 75 73 65 20  ts WHERE clause 
33590 74 65 72 6d 73 20 69 6e 20 74 68 65 20 63 6f 72  terms in the cor
335a0 72 65 63 74 0a 2a 2a 20 66 6f 72 6d 20 74 68 61  rect.** form tha
335b0 74 20 72 65 66 65 72 20 74 6f 20 74 68 65 20 70  t refer to the p
335c0 61 72 74 69 63 75 6c 61 72 20 76 69 72 74 75 61  articular virtua
335d0 6c 20 74 61 62 6c 65 20 62 65 69 6e 67 20 71 75  l table being qu
335e0 65 72 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 66  eried..**.** Inf
335f0 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74  ormation about t
33600 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75  he ORDER BY clau
33610 73 65 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20  se is stored in 
33620 61 4f 72 64 65 72 42 79 5b 5d 2e 0a 2a 2a 20 45  aOrderBy[]..** E
33630 61 63 68 20 74 65 72 6d 20 6f 66 20 61 4f 72 64  ach term of aOrd
33640 65 72 42 79 20 72 65 63 6f 72 64 73 20 61 20 63  erBy records a c
33650 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 4f 52 44  olumn of the ORD
33660 45 52 20 42 59 20 63 6c 61 75 73 65 2e 0a 2a 2a  ER BY clause..**
33670 0a 2a 2a 20 54 68 65 20 78 42 65 73 74 49 6e 64  .** The xBestInd
33680 65 78 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 66  ex method must f
33690 69 6c 6c 20 61 43 6f 6e 73 74 72 61 69 6e 74 55  ill aConstraintU
336a0 73 61 67 65 5b 5d 20 77 69 74 68 20 69 6e 66 6f  sage[] with info
336b0 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74  rmation.** about
336c0 20 77 68 61 74 20 70 61 72 61 6d 65 74 65 72 73   what parameters
336d0 20 74 6f 20 70 61 73 73 20 74 6f 20 78 46 69 6c   to pass to xFil
336e0 74 65 72 2e 20 20 49 66 20 61 72 67 76 49 6e 64  ter.  If argvInd
336f0 65 78 3e 30 20 74 68 65 6e 0a 2a 2a 20 74 68 65  ex>0 then.** the
33700 20 72 69 67 68 74 2d 68 61 6e 64 20 73 69 64 65   right-hand side
33710 20 6f 66 20 74 68 65 20 63 6f 72 72 65 73 70 6f   of the correspo
33720 6e 64 69 6e 67 20 61 43 6f 6e 73 74 72 61 69 6e  nding aConstrain
33730 74 5b 5d 20 69 73 20 65 76 61 6c 75 61 74 65 64  t[] is evaluated
33740 0a 2a 2a 20 61 6e 64 20 62 65 63 6f 6d 65 73 20  .** and becomes 
33750 74 68 65 20 61 72 67 76 49 6e 64 65 78 2d 74 68  the argvIndex-th
33760 20 65 6e 74 72 79 20 69 6e 20 61 72 67 76 2e 20   entry in argv. 
33770 20 49 66 20 61 43 6f 6e 73 74 72 61 69 6e 74 55   If aConstraintU
33780 73 61 67 65 5b 5d 2e 6f 6d 69 74 0a 2a 2a 20 69  sage[].omit.** i
33790 73 20 74 72 75 65 2c 20 74 68 65 6e 20 74 68 65  s true, then the
337a0 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 61   constraint is a
337b0 73 73 75 6d 65 64 20 74 6f 20 62 65 20 66 75 6c  ssumed to be ful
337c0 6c 79 20 68 61 6e 64 6c 65 64 20 62 79 20 74 68  ly handled by th
337d0 65 0a 2a 2a 20 76 69 72 74 75 61 6c 20 74 61 62  e.** virtual tab
337e0 6c 65 20 61 6e 64 20 69 73 20 6e 6f 74 20 63 68  le and is not ch
337f0 65 63 6b 65 64 20 61 67 61 69 6e 20 62 79 20 53  ecked again by S
33800 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  QLite..**.** The
33810 20 69 64 78 4e 75 6d 20 61 6e 64 20 69 64 78 50   idxNum and idxP
33820 74 72 20 76 61 6c 75 65 73 20 61 72 65 20 72 65  tr values are re
33830 63 6f 72 64 65 64 20 61 6e 64 20 70 61 73 73 65  corded and passe
33840 64 20 69 6e 74 6f 20 78 46 69 6c 74 65 72 2e 0a  d into xFilter..
33850 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  ** sqlite3_free(
33860 29 20 69 73 20 75 73 65 64 20 74 6f 20 66 72 65  ) is used to fre
33870 65 20 69 64 78 50 74 72 20 69 66 20 6e 65 65 64  e idxPtr if need
33880 54 6f 46 72 65 65 49 64 78 50 74 72 20 69 73 20  ToFreeIdxPtr is 
33890 74 72 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  true..**.** The 
338a0 6f 72 64 65 72 42 79 43 6f 6e 73 75 6d 65 64 20  orderByConsumed 
338b0 6d 65 61 6e 73 20 74 68 61 74 20 6f 75 74 70 75  means that outpu
338c0 74 20 66 72 6f 6d 20 78 46 69 6c 74 65 72 20 77  t from xFilter w
338d0 69 6c 6c 20 6f 63 63 75 72 20 69 6e 0a 2a 2a 20  ill occur in.** 
338e0 74 68 65 20 63 6f 72 72 65 63 74 20 6f 72 64 65  the correct orde
338f0 72 20 74 6f 20 73 61 74 69 73 66 79 20 74 68 65  r to satisfy the
33900 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 65   ORDER BY clause
33910 20 73 6f 20 74 68 61 74 20 6e 6f 20 73 65 70 61   so that no sepa
33920 72 61 74 65 0a 2a 2a 20 73 6f 72 74 69 6e 67 20  rate.** sorting 
33930 73 74 65 70 20 69 73 20 72 65 71 75 69 72 65 64  step is required
33940 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 65 73 74 69  ..**.** The esti
33950 6d 61 74 65 64 43 6f 73 74 20 76 61 6c 75 65 20  matedCost value 
33960 69 73 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f  is an estimate o
33970 66 20 74 68 65 20 63 6f 73 74 20 6f 66 20 64 6f  f the cost of do
33980 69 6e 67 20 74 68 65 0a 2a 2a 20 70 61 72 74 69  ing the.** parti
33990 63 75 6c 61 72 20 6c 6f 6f 6b 75 70 2e 20 20 41  cular lookup.  A
339a0 20 66 75 6c 6c 20 73 63 61 6e 20 6f 66 20 61 20   full scan of a 
339b0 74 61 62 6c 65 20 77 69 74 68 20 4e 20 65 6e 74  table with N ent
339c0 72 69 65 73 20 73 68 6f 75 6c 64 20 68 61 76 65  ries should have
339d0 0a 2a 2a 20 61 20 63 6f 73 74 20 6f 66 20 4e 2e  .** a cost of N.
339e0 20 20 41 20 62 69 6e 61 72 79 20 73 65 61 72 63    A binary searc
339f0 68 20 6f 66 20 61 20 74 61 62 6c 65 20 6f 66 20  h of a table of 
33a00 4e 20 65 6e 74 72 69 65 73 20 73 68 6f 75 6c 64  N entries should
33a10 20 68 61 76 65 20 61 0a 2a 2a 20 63 6f 73 74 20   have a.** cost 
33a20 6f 66 20 61 70 70 72 6f 78 69 6d 61 74 65 6c 79  of approximately
33a30 20 6c 6f 67 28 4e 29 2e 0a 2a 2f 0a 73 74 72 75   log(N)..*/.stru
33a40 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78  ct sqlite3_index
33a50 5f 69 6e 66 6f 20 7b 0a 20 20 2f 2a 20 49 6e 70  _info {.  /* Inp
33a60 75 74 73 20 2a 2f 0a 20 20 69 6e 74 20 6e 43 6f  uts */.  int nCo
33a70 6e 73 74 72 61 69 6e 74 3b 20 20 20 20 20 20 20  nstraint;       
33a80 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66      /* Number of
33a90 20 65 6e 74 72 69 65 73 20 69 6e 20 61 43 6f 6e   entries in aCon
33aa0 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 73 74 72  straint */.  str
33ab0 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65  uct sqlite3_inde
33ac0 78 5f 63 6f 6e 73 74 72 61 69 6e 74 20 7b 0a 20  x_constraint {. 
33ad0 20 20 20 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b      int iColumn;
33ae0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
33af0 20 43 6f 6c 75 6d 6e 20 6f 6e 20 6c 65 66 74 2d   Column on left-
33b00 68 61 6e 64 20 73 69 64 65 20 6f 66 20 63 6f 6e  hand side of con
33b10 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 20 20 20  straint */.     
33b20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 6f 70  unsigned char op
33b30 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e  ;         /* Con
33b40 73 74 72 61 69 6e 74 20 6f 70 65 72 61 74 6f 72  straint operator
33b50 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e 65   */.     unsigne
33b60 64 20 63 68 61 72 20 75 73 61 62 6c 65 3b 20 20  d char usable;  
33b70 20 20 20 2f 2a 20 54 72 75 65 20 69 66 20 74 68     /* True if th
33b80 69 73 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73  is constraint is
33b90 20 75 73 61 62 6c 65 20 2a 2f 0a 20 20 20 20 20   usable */.     
33ba0 69 6e 74 20 69 54 65 72 6d 4f 66 66 73 65 74 3b  int iTermOffset;
33bb0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 55 73 65            /* Use
33bc0 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 2d 20 78  d internally - x
33bd0 42 65 73 74 49 6e 64 65 78 20 73 68 6f 75 6c 64  BestIndex should
33be0 20 69 67 6e 6f 72 65 20 2a 2f 0a 20 20 7d 20 2a   ignore */.  } *
33bf0 61 43 6f 6e 73 74 72 61 69 6e 74 3b 20 20 20 20  aConstraint;    
33c00 20 20 20 20 20 20 20 20 2f 2a 20 54 61 62 6c 65          /* Table
33c10 20 6f 66 20 57 48 45 52 45 20 63 6c 61 75 73 65   of WHERE clause
33c20 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 2a 2f 0a   constraints */.
33c30 20 20 69 6e 74 20 6e 4f 72 64 65 72 42 79 3b 20    int nOrderBy; 
33c40 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
33c50 4e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20  Number of terms 
33c60 69 6e 20 74 68 65 20 4f 52 44 45 52 20 42 59 20  in the ORDER BY 
33c70 63 6c 61 75 73 65 20 2a 2f 0a 20 20 73 74 72 75  clause */.  stru
33c80 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78  ct sqlite3_index
33c90 5f 6f 72 64 65 72 62 79 20 7b 0a 20 20 20 20 20  _orderby {.     
33ca0 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 20 20 20  int iColumn;    
33cb0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6c            /* Col
33cc0 75 6d 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a 20 20  umn number */.  
33cd0 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72     unsigned char
33ce0 20 64 65 73 63 3b 20 20 20 20 20 20 20 2f 2a 20   desc;       /* 
33cf0 54 72 75 65 20 66 6f 72 20 44 45 53 43 2e 20 20  True for DESC.  
33d00 46 61 6c 73 65 20 66 6f 72 20 41 53 43 2e 20 2a  False for ASC. *
33d10 2f 0a 20 20 7d 20 2a 61 4f 72 64 65 72 42 79 3b  /.  } *aOrderBy;
33d20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
33d30 2a 20 54 68 65 20 4f 52 44 45 52 20 42 59 20 63  * The ORDER BY c
33d40 6c 61 75 73 65 20 2a 2f 0a 0a 20 20 2f 2a 20 4f  lause */..  /* O
33d50 75 74 70 75 74 73 20 2a 2f 0a 20 20 73 74 72 75  utputs */.  stru
33d60 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78  ct sqlite3_index
33d70 5f 63 6f 6e 73 74 72 61 69 6e 74 5f 75 73 61 67  _constraint_usag
33d80 65 20 7b 0a 20 20 20 20 69 6e 74 20 61 72 67 76  e {.    int argv
33d90 49 6e 64 65 78 3b 20 20 20 20 20 20 20 20 20 20  Index;          
33da0 20 2f 2a 20 69 66 20 3e 30 2c 20 63 6f 6e 73 74   /* if >0, const
33db0 72 61 69 6e 74 20 69 73 20 70 61 72 74 20 6f 66  raint is part of
33dc0 20 61 72 67 76 20 74 6f 20 78 46 69 6c 74 65 72   argv to xFilter
33dd0 20 2a 2f 0a 20 20 20 20 75 6e 73 69 67 6e 65 64   */.    unsigned
33de0 20 63 68 61 72 20 6f 6d 69 74 3b 20 20 20 20 20   char omit;     
33df0 20 2f 2a 20 44 6f 20 6e 6f 74 20 63 6f 64 65 20   /* Do not code 
33e00 61 20 74 65 73 74 20 66 6f 72 20 74 68 69 73 20  a test for this 
33e10 63 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20  constraint */.  
33e20 7d 20 2a 61 43 6f 6e 73 74 72 61 69 6e 74 55 73  } *aConstraintUs
33e30 61 67 65 3b 0a 20 20 69 6e 74 20 69 64 78 4e 75  age;.  int idxNu
33e40 6d 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  m;              
33e50 20 20 2f 2a 20 4e 75 6d 62 65 72 20 75 73 65 64    /* Number used
33e60 20 74 6f 20 69 64 65 6e 74 69 66 79 20 74 68 65   to identify the
33e70 20 69 6e 64 65 78 20 2a 2f 0a 20 20 63 68 61 72   index */.  char
33e80 20 2a 69 64 78 53 74 72 3b 20 20 20 20 20 20 20   *idxStr;       
33e90 20 20 20 20 20 20 20 2f 2a 20 53 74 72 69 6e 67         /* String
33ea0 2c 20 70 6f 73 73 69 62 6c 79 20 6f 62 74 61 69  , possibly obtai
33eb0 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ned from sqlite3
33ec0 5f 6d 61 6c 6c 6f 63 20 2a 2f 0a 20 20 69 6e 74  _malloc */.  int
33ed0 20 6e 65 65 64 54 6f 46 72 65 65 49 64 78 53 74   needToFreeIdxSt
33ee0 72 3b 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20  r;      /* Free 
33ef0 69 64 78 53 74 72 20 75 73 69 6e 67 20 73 71 6c  idxStr using sql
33f00 69 74 65 33 5f 66 72 65 65 28 29 20 69 66 20 74  ite3_free() if t
33f10 72 75 65 20 2a 2f 0a 20 20 69 6e 74 20 6f 72 64  rue */.  int ord
33f20 65 72 42 79 43 6f 6e 73 75 6d 65 64 3b 20 20 20  erByConsumed;   
33f30 20 20 20 20 2f 2a 20 54 72 75 65 20 69 66 20 6f      /* True if o
33f40 75 74 70 75 74 20 69 73 20 61 6c 72 65 61 64 79  utput is already
33f50 20 6f 72 64 65 72 65 64 20 2a 2f 0a 20 20 64 6f   ordered */.  do
33f60 75 62 6c 65 20 65 73 74 69 6d 61 74 65 64 43 6f  uble estimatedCo
33f70 73 74 3b 20 20 20 20 20 20 2f 2a 20 45 73 74 69  st;      /* Esti
33f80 6d 61 74 65 64 20 63 6f 73 74 20 6f 66 20 75 73  mated cost of us
33f90 69 6e 67 20 74 68 69 73 20 69 6e 64 65 78 20 2a  ing this index *
33fa0 2f 0a 7d 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c  /.};.#define SQL
33fb0 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52  ITE_INDEX_CONSTR
33fc0 41 49 4e 54 5f 45 51 20 20 20 20 32 0a 23 64 65  AINT_EQ    2.#de
33fd0 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45  fine SQLITE_INDE
33fe0 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 47 54 20  X_CONSTRAINT_GT 
33ff0 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c     4.#define SQL
34000 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52  ITE_INDEX_CONSTR
34010 41 49 4e 54 5f 4c 45 20 20 20 20 38 0a 23 64 65  AINT_LE    8.#de
34020 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45  fine SQLITE_INDE
34030 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4c 54 20  X_CONSTRAINT_LT 
34040 20 20 20 31 36 0a 23 64 65 66 69 6e 65 20 53 51     16.#define SQ
34050 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54  LITE_INDEX_CONST
34060 52 41 49 4e 54 5f 47 45 20 20 20 20 33 32 0a 23  RAINT_GE    32.#
34070 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
34080 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4d  DEX_CONSTRAINT_M
34090 41 54 43 48 20 36 34 0a 0a 2f 2a 0a 2a 2a 20 43  ATCH 64../*.** C
340a0 41 50 49 33 52 45 46 3a 20 52 65 67 69 73 74 65  API3REF: Registe
340b0 72 20 41 20 56 69 72 74 75 61 6c 20 54 61 62 6c  r A Virtual Tabl
340c0 65 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e Implementation
340d0 20 7b 46 31 38 32 30 30 7d 0a 2a 2a 0a 2a 2a 20   {F18200}.**.** 
340e0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  This routine is 
340f0 75 73 65 64 20 74 6f 20 72 65 67 69 73 74 65 72  used to register
34100 20 61 20 6e 65 77 20 6d 6f 64 75 6c 65 20 6e 61   a new module na
34110 6d 65 20 77 69 74 68 20 61 6e 20 53 51 4c 69 74  me with an SQLit
34120 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  e.** connection.
34130 20 20 4d 6f 64 75 6c 65 20 6e 61 6d 65 73 20 6d    Module names m
34140 75 73 74 20 62 65 20 72 65 67 69 73 74 65 72 65  ust be registere
34150 64 20 62 65 66 6f 72 65 20 63 72 65 61 74 69 6e  d before creatin
34160 67 20 6e 65 77 0a 2a 2a 20 76 69 72 74 75 61 6c  g new.** virtual
34170 20 74 61 62 6c 65 73 20 6f 6e 20 74 68 65 20 6d   tables on the m
34180 6f 64 75 6c 65 2c 20 6f 72 20 62 65 66 6f 72 65  odule, or before
34190 20 75 73 69 6e 67 20 70 72 65 65 78 69 73 74 69   using preexisti
341a0 6e 67 20 76 69 72 74 75 61 6c 0a 2a 2a 20 74 61  ng virtual.** ta
341b0 62 6c 65 73 20 6f 66 20 74 68 65 20 6d 6f 64 75  bles of the modu
341c0 6c 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  le..*/.int sqlit
341d0 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65  e3_create_module
341e0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
341f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
34200 2a 20 53 51 4c 69 74 65 20 63 6f 6e 6e 65 63 74  * SQLite connect
34210 69 6f 6e 20 74 6f 20 72 65 67 69 73 74 65 72 20  ion to register 
34220 6d 6f 64 75 6c 65 20 77 69 74 68 20 2a 2f 0a 20  module with */. 
34230 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
34240 6d 65 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4e  me,         /* N
34250 61 6d 65 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c  ame of the modul
34260 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 73 71 6c  e */.  const sql
34270 69 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 2c 20 20  ite3_module *,  
34280 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72    /* Methods for
34290 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20   the module */. 
342a0 20 76 6f 69 64 20 2a 20 20 20 20 20 20 20 20 20   void *         
342b0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43              /* C
342c0 6c 69 65 6e 74 20 64 61 74 61 20 66 6f 72 20 78  lient data for x
342d0 43 72 65 61 74 65 2f 78 43 6f 6e 6e 65 63 74 20  Create/xConnect 
342e0 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
342f0 49 33 52 45 46 3a 20 52 65 67 69 73 74 65 72 20  I3REF: Register 
34300 41 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20  A Virtual Table 
34310 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 7b  Implementation {
34320 46 31 38 32 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 68  F18210}.**.** Th
34330 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 69 64  is routine is id
34340 65 6e 74 69 63 61 6c 20 74 6f 20 74 68 65 20 73  entical to the s
34350 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f  qlite3_create_mo
34360 64 75 6c 65 28 29 20 6d 65 74 68 6f 64 20 61 62  dule() method ab
34370 6f 76 65 2c 0a 2a 2a 20 65 78 63 65 70 74 20 74  ove,.** except t
34380 68 61 74 20 69 74 20 61 6c 6c 6f 77 73 20 61 20  hat it allows a 
34390 64 65 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74  destructor funct
343a0 69 6f 6e 20 74 6f 20 62 65 20 73 70 65 63 69 66  ion to be specif
343b0 69 65 64 2e 20 49 74 20 69 73 0a 2a 2a 20 65 76  ied. It is.** ev
343c0 65 6e 20 6d 6f 72 65 20 65 78 70 65 72 69 6d 65  en more experime
343d0 6e 74 61 6c 20 74 68 61 6e 20 74 68 65 20 72 65  ntal than the re
343e0 73 74 20 6f 66 20 74 68 65 20 76 69 72 74 75 61  st of the virtua
343f0 6c 20 74 61 62 6c 65 73 20 41 50 49 2e 0a 2a 2f  l tables API..*/
34400 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65  .int sqlite3_cre
34410 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 0a 20  ate_module_v2(. 
34420 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
34430 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53              /* S
34440 51 4c 69 74 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  QLite connection
34450 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d 6f 64   to register mod
34460 75 6c 65 20 77 69 74 68 20 2a 2f 0a 20 20 63 6f  ule with */.  co
34470 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
34480 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65           /* Name
34490 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a   of the module *
344a0 2f 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69 74 65  /.  const sqlite
344b0 33 5f 6d 6f 64 75 6c 65 20 2a 2c 20 20 20 20 2f  3_module *,    /
344c0 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 74 68  * Methods for th
344d0 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 76 6f  e module */.  vo
344e0 69 64 20 2a 2c 20 20 20 20 20 20 20 20 20 20 20  id *,           
344f0 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6c 69 65           /* Clie
34500 6e 74 20 64 61 74 61 20 66 6f 72 20 78 43 72 65  nt data for xCre
34510 61 74 65 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a  ate/xConnect */.
34520 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79    void(*xDestroy
34530 29 28 76 6f 69 64 2a 29 20 20 20 20 20 2f 2a 20  )(void*)     /* 
34540 4d 6f 64 75 6c 65 20 64 65 73 74 72 75 63 74 6f  Module destructo
34550 72 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 29 3b  r function */.);
34560 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
34570 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20  : Virtual Table 
34580 49 6e 73 74 61 6e 63 65 20 4f 62 6a 65 63 74 20  Instance Object 
34590 7b 46 31 38 30 31 30 7d 0a 2a 2a 20 4b 45 59 57  {F18010}.** KEYW
345a0 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76 74  ORDS: sqlite3_vt
345b0 61 62 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 6d  ab.**.** Every m
345c0 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  odule implementa
345d0 74 69 6f 6e 20 75 73 65 73 20 61 20 73 75 62 63  tion uses a subc
345e0 6c 61 73 73 20 6f 66 20 74 68 65 20 66 6f 6c 6c  lass of the foll
345f0 6f 77 69 6e 67 20 73 74 72 75 63 74 75 72 65 0a  owing structure.
34600 2a 2a 20 74 6f 20 64 65 73 63 72 69 62 65 20 61  ** to describe a
34610 20 70 61 72 74 69 63 75 6c 61 72 20 69 6e 73 74   particular inst
34620 61 6e 63 65 20 6f 66 20 74 68 65 20 6d 6f 64 75  ance of the modu
34630 6c 65 2e 20 20 45 61 63 68 20 73 75 62 63 6c 61  le.  Each subcla
34640 73 73 20 77 69 6c 6c 0a 2a 2a 20 62 65 20 74 61  ss will.** be ta
34650 69 6c 6f 72 65 64 20 74 6f 20 74 68 65 20 73 70  ilored to the sp
34660 65 63 69 66 69 63 20 6e 65 65 64 73 20 6f 66 20  ecific needs of 
34670 74 68 65 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65  the module imple
34680 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 20 54 68 65  mentation.   The
34690 0a 2a 2a 20 70 75 72 70 6f 73 65 20 6f 66 20 74  .** purpose of t
346a0 68 69 73 20 73 75 70 65 72 63 6c 61 73 73 20 69  his superclass i
346b0 73 20 74 6f 20 64 65 66 69 6e 65 20 63 65 72 74  s to define cert
346c0 61 69 6e 20 66 69 65 6c 64 73 20 74 68 61 74 20  ain fields that 
346d0 61 72 65 20 63 6f 6d 6d 6f 6e 0a 2a 2a 20 74 6f  are common.** to
346e0 20 61 6c 6c 20 6d 6f 64 75 6c 65 20 69 6d 70 6c   all module impl
346f0 65 6d 65 6e 74 61 74 69 6f 6e 73 2e 0a 2a 2a 0a  ementations..**.
34700 2a 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65  ** Virtual table
34710 73 20 6d 65 74 68 6f 64 73 20 63 61 6e 20 73 65  s methods can se
34720 74 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61  t an error messa
34730 67 65 20 62 79 20 61 73 73 69 67 6e 69 6e 67 20  ge by assigning 
34740 61 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 62 74 61  a.** string obta
34750 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65  ined from sqlite
34760 33 5f 6d 70 72 69 6e 74 66 28 29 20 74 6f 20 7a  3_mprintf() to z
34770 45 72 72 4d 73 67 2e 20 20 54 68 65 20 6d 65 74  ErrMsg.  The met
34780 68 6f 64 20 73 68 6f 75 6c 64 0a 2a 2a 20 74 61  hod should.** ta
34790 6b 65 20 63 61 72 65 20 74 68 61 74 20 61 6e 79  ke care that any
347a0 20 70 72 69 6f 72 20 73 74 72 69 6e 67 20 69 73   prior string is
347b0 20 66 72 65 65 64 20 62 79 20 61 20 63 61 6c 6c   freed by a call
347c0 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65   to sqlite3_free
347d0 28 29 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 61  ().** prior to a
347e0 73 73 69 67 6e 69 6e 67 20 61 20 6e 65 77 20 73  ssigning a new s
347f0 74 72 69 6e 67 20 74 6f 20 7a 45 72 72 4d 73 67  tring to zErrMsg
34800 2e 20 20 41 66 74 65 72 20 74 68 65 20 65 72 72  .  After the err
34810 6f 72 20 6d 65 73 73 61 67 65 0a 2a 2a 20 69 73  or message.** is
34820 20 64 65 6c 69 76 65 72 65 64 20 75 70 20 74 6f   delivered up to
34830 20 74 68 65 20 63 6c 69 65 6e 74 20 61 70 70 6c   the client appl
34840 69 63 61 74 69 6f 6e 2c 20 74 68 65 20 73 74 72  ication, the str
34850 69 6e 67 20 77 69 6c 6c 20 62 65 20 61 75 74 6f  ing will be auto
34860 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 66 72 65  matically.** fre
34870 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 66 72  ed by sqlite3_fr
34880 65 65 28 29 20 61 6e 64 20 74 68 65 20 7a 45 72  ee() and the zEr
34890 72 4d 73 67 20 66 69 65 6c 64 20 77 69 6c 6c 20  rMsg field will 
348a0 62 65 20 7a 65 72 6f 65 64 2e 20 20 4e 6f 74 65  be zeroed.  Note
348b0 0a 2a 2a 20 74 68 61 74 20 73 71 6c 69 74 65 33  .** that sqlite3
348c0 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73  _mprintf() and s
348d0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 61 72  qlite3_free() ar
348e0 65 20 75 73 65 64 20 6f 6e 20 74 68 65 20 7a 45  e used on the zE
348f0 72 72 4d 73 67 20 66 69 65 6c 64 0a 2a 2a 20 73  rrMsg field.** s
34900 69 6e 63 65 20 76 69 72 74 75 61 6c 20 74 61 62  ince virtual tab
34910 6c 65 73 20 61 72 65 20 63 6f 6d 6d 6f 6e 6c 79  les are commonly
34920 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 69 6e 20   implemented in 
34930 6c 6f 61 64 61 62 6c 65 20 65 78 74 65 6e 73 69  loadable extensi
34940 6f 6e 73 20 77 68 69 63 68 0a 2a 2a 20 64 6f 20  ons which.** do 
34950 6e 6f 74 20 68 61 76 65 20 61 63 63 65 73 73 20  not have access 
34960 74 6f 20 73 71 6c 69 74 65 33 4d 50 72 69 6e 74  to sqlite3MPrint
34970 66 28 29 20 6f 72 20 73 71 6c 69 74 65 33 46 72  f() or sqlite3Fr
34980 65 65 28 29 2e 0a 2a 2f 0a 73 74 72 75 63 74 20  ee()..*/.struct 
34990 73 71 6c 69 74 65 33 5f 76 74 61 62 20 7b 0a 20  sqlite3_vtab {. 
349a0 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d   const sqlite3_m
349b0 6f 64 75 6c 65 20 2a 70 4d 6f 64 75 6c 65 3b 20  odule *pModule; 
349c0 20 2f 2a 20 54 68 65 20 6d 6f 64 75 6c 65 20 66   /* The module f
349d0 6f 72 20 74 68 69 73 20 76 69 72 74 75 61 6c 20  or this virtual 
349e0 74 61 62 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6e  table */.  int n
349f0 52 65 66 3b 20 20 20 20 20 20 20 20 20 20 20 20  Ref;            
34a00 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 55 73             /* Us
34a10 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 2a 2f  ed internally */
34a20 0a 20 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67  .  char *zErrMsg
34a30 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ;               
34a40 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 65 73 73     /* Error mess
34a50 61 67 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  age from sqlite3
34a60 5f 6d 70 72 69 6e 74 66 28 29 20 2a 2f 0a 20 20  _mprintf() */.  
34a70 2f 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65  /* Virtual table
34a80 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
34a90 20 77 69 6c 6c 20 74 79 70 69 63 61 6c 6c 79 20   will typically 
34aa0 61 64 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 66  add additional f
34ab0 69 65 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a  ields */.};../*.
34ac0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69 72  ** CAPI3REF: Vir
34ad0 74 75 61 6c 20 54 61 62 6c 65 20 43 75 72 73 6f  tual Table Curso
34ae0 72 20 4f 62 6a 65 63 74 20 20 7b 46 31 38 30 32  r Object  {F1802
34af0 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  0}.** KEYWORDS: 
34b00 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72  sqlite3_vtab_cur
34b10 73 6f 72 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20  sor.**.** Every 
34b20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  module implement
34b30 61 74 69 6f 6e 20 75 73 65 73 20 61 20 73 75 62  ation uses a sub
34b40 63 6c 61 73 73 20 6f 66 20 74 68 65 20 66 6f 6c  class of the fol
34b50 6c 6f 77 69 6e 67 20 73 74 72 75 63 74 75 72 65  lowing structure
34b60 0a 2a 2a 20 74 6f 20 64 65 73 63 72 69 62 65 20  .** to describe 
34b70 63 75 72 73 6f 72 73 20 74 68 61 74 20 70 6f 69  cursors that poi
34b80 6e 74 20 69 6e 74 6f 20 74 68 65 20 76 69 72 74  nt into the virt
34b90 75 61 6c 20 74 61 62 6c 65 20 61 6e 64 20 61 72  ual table and ar
34ba0 65 20 75 73 65 64 0a 2a 2a 20 74 6f 20 6c 6f 6f  e used.** to loo
34bb0 70 20 74 68 72 6f 75 67 68 20 74 68 65 20 76 69  p through the vi
34bc0 72 74 75 61 6c 20 74 61 62 6c 65 2e 20 20 43 75  rtual table.  Cu
34bd0 72 73 6f 72 73 20 61 72 65 20 63 72 65 61 74 65  rsors are create
34be0 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 78  d using the.** x
34bf0 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6f 66 20 74  Open method of t
34c00 68 65 20 6d 6f 64 75 6c 65 2e 20 20 45 61 63 68  he module.  Each
34c10 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e   module implemen
34c20 74 61 74 69 6f 6e 20 77 69 6c 6c 20 64 65 66 69  tation will defi
34c30 6e 65 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e  ne.** the conten
34c40 74 20 6f 66 20 61 20 63 75 72 73 6f 72 20 73 74  t of a cursor st
34c50 72 75 63 74 75 72 65 20 74 6f 20 73 75 69 74 20  ructure to suit 
34c60 69 74 73 20 6f 77 6e 20 6e 65 65 64 73 2e 0a 2a  its own needs..*
34c70 2a 0a 2a 2a 20 54 68 69 73 20 73 75 70 65 72 63  *.** This superc
34c80 6c 61 73 73 20 65 78 69 73 74 73 20 69 6e 20 6f  lass exists in o
34c90 72 64 65 72 20 74 6f 20 64 65 66 69 6e 65 20 66  rder to define f
34ca0 69 65 6c 64 73 20 6f 66 20 74 68 65 20 63 75 72  ields of the cur
34cb0 73 6f 72 20 74 68 61 74 0a 2a 2a 20 61 72 65 20  sor that.** are 
34cc0 63 6f 6d 6d 6f 6e 20 74 6f 20 61 6c 6c 20 69 6d  common to all im
34cd0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2e 0a 2a  plementations..*
34ce0 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  /.struct sqlite3
34cf0 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 7b 0a 20  _vtab_cursor {. 
34d00 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70   sqlite3_vtab *p
34d10 56 74 61 62 3b 20 20 20 20 20 20 2f 2a 20 56 69  Vtab;      /* Vi
34d20 72 74 75 61 6c 20 74 61 62 6c 65 20 6f 66 20 74  rtual table of t
34d30 68 69 73 20 63 75 72 73 6f 72 20 2a 2f 0a 20 20  his cursor */.  
34d40 2f 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65  /* Virtual table
34d50 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
34d60 20 77 69 6c 6c 20 74 79 70 69 63 61 6c 6c 79 20   will typically 
34d70 61 64 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 66  add additional f
34d80 69 65 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a  ields */.};../*.
34d90 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 63  ** CAPI3REF: Dec
34da0 6c 61 72 65 20 54 68 65 20 53 63 68 65 6d 61 20  lare The Schema 
34db0 4f 66 20 41 20 56 69 72 74 75 61 6c 20 54 61 62  Of A Virtual Tab
34dc0 6c 65 20 7b 46 31 38 32 38 30 7d 0a 2a 2a 0a 2a  le {F18280}.**.*
34dd0 2a 20 54 68 65 20 78 43 72 65 61 74 65 20 61 6e  * The xCreate an
34de0 64 20 78 43 6f 6e 6e 65 63 74 20 6d 65 74 68 6f  d xConnect metho
34df0 64 73 20 6f 66 20 61 20 6d 6f 64 75 6c 65 20 75  ds of a module u
34e00 73 65 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  se the following
34e10 20 41 50 49 0a 2a 2a 20 74 6f 20 64 65 63 6c 61   API.** to decla
34e20 72 65 20 74 68 65 20 66 6f 72 6d 61 74 20 28 74  re the format (t
34e30 68 65 20 6e 61 6d 65 73 20 61 6e 64 20 64 61 74  he names and dat
34e40 61 74 79 70 65 73 20 6f 66 20 74 68 65 20 63 6f  atypes of the co
34e50 6c 75 6d 6e 73 29 20 6f 66 0a 2a 2a 20 74 68 65  lumns) of.** the
34e60 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20   virtual tables 
34e70 74 68 65 79 20 69 6d 70 6c 65 6d 65 6e 74 2e 0a  they implement..
34e80 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64  */.int sqlite3_d
34e90 65 63 6c 61 72 65 5f 76 74 61 62 28 73 71 6c 69  eclare_vtab(sqli
34ea0 74 65 33 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  te3*, const char
34eb0 20 2a 7a 43 72 65 61 74 65 54 61 62 6c 65 29 3b   *zCreateTable);
34ec0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
34ed0 3a 20 4f 76 65 72 6c 6f 61 64 20 41 20 46 75 6e  : Overload A Fun
34ee0 63 74 69 6f 6e 20 46 6f 72 20 41 20 56 69 72 74  ction For A Virt
34ef0 75 61 6c 20 54 61 62 6c 65 20 7b 46 31 38 33 30  ual Table {F1830
34f00 30 7d 0a 2a 2a 0a 2a 2a 20 56 69 72 74 75 61 6c  0}.**.** Virtual
34f10 20 74 61 62 6c 65 73 20 63 61 6e 20 70 72 6f 76   tables can prov
34f20 69 64 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20  ide alternative 
34f30 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
34f40 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  of functions.** 
34f50 75 73 69 6e 67 20 74 68 65 20 78 46 69 6e 64 46  using the xFindF
34f60 75 6e 63 74 69 6f 6e 20 6d 65 74 68 6f 64 2e 20  unction method. 
34f70 20 42 75 74 20 67 6c 6f 62 61 6c 20 76 65 72 73   But global vers
34f80 69 6f 6e 73 20 6f 66 20 74 68 6f 73 65 20 66 75  ions of those fu
34f90 6e 63 74 69 6f 6e 73 0a 2a 2a 20 6d 75 73 74 20  nctions.** must 
34fa0 65 78 69 73 74 20 69 6e 20 6f 72 64 65 72 20 74  exist in order t
34fb0 6f 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 2e  o be overloaded.
34fc0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49 20  .**.** This API 
34fd0 6d 61 6b 65 73 20 73 75 72 65 20 61 20 67 6c 6f  makes sure a glo
34fe0 62 61 6c 20 76 65 72 73 69 6f 6e 20 6f 66 20 61  bal version of a
34ff0 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61   function with a
35000 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 6e   particular.** n
35010 61 6d 65 20 61 6e 64 20 6e 75 6d 62 65 72 20 6f  ame and number o
35020 66 20 70 61 72 61 6d 65 74 65 72 73 20 65 78 69  f parameters exi
35030 73 74 73 2e 20 20 49 66 20 6e 6f 20 73 75 63 68  sts.  If no such
35040 20 66 75 6e 63 74 69 6f 6e 20 65 78 69 73 74 73   function exists
35050 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 69 73 20  .** before this 
35060 41 50 49 20 69 73 20 63 61 6c 6c 65 64 2c 20 61  API is called, a
35070 20 6e 65 77 20 66 75 6e 63 74 69 6f 6e 20 69 73   new function is
35080 20 63 72 65 61 74 65 64 2e 20 20 54 68 65 20 69   created.  The i
35090 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a  mplementation.**
350a0 20 6f 66 20 74 68 65 20 6e 65 77 20 66 75 6e 63   of the new func
350b0 74 69 6f 6e 20 61 6c 77 61 79 73 20 63 61 75 73  tion always caus
350c0 65 73 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20  es an exception 
350d0 74 6f 20 62 65 20 74 68 72 6f 77 6e 2e 20 20 53  to be thrown.  S
350e0 6f 0a 2a 2a 20 74 68 65 20 6e 65 77 20 66 75 6e  o.** the new fun
350f0 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 67 6f 6f  ction is not goo
35100 64 20 66 6f 72 20 61 6e 79 74 68 69 6e 67 20 62  d for anything b
35110 79 20 69 74 73 65 6c 66 2e 20 20 49 74 73 20 6f  y itself.  Its o
35120 6e 6c 79 0a 2a 2a 20 70 75 72 70 6f 73 65 20 69  nly.** purpose i
35130 73 20 74 6f 20 62 65 20 61 20 70 6c 61 63 65 2d  s to be a place-
35140 68 6f 6c 64 65 72 20 66 75 6e 63 74 69 6f 6e 20  holder function 
35150 74 68 61 74 20 63 61 6e 20 62 65 20 6f 76 65 72  that can be over
35160 6c 6f 61 64 65 64 0a 2a 2a 20 62 79 20 76 69 72  loaded.** by vir
35170 74 75 61 6c 20 74 61 62 6c 65 73 2e 0a 2a 2a 0a  tual tables..**.
35180 2a 2a 20 54 68 69 73 20 41 50 49 20 73 68 6f 75  ** This API shou
35190 6c 64 20 62 65 20 63 6f 6e 73 69 64 65 72 65 64  ld be considered
351a0 20 70 61 72 74 20 6f 66 20 74 68 65 20 76 69 72   part of the vir
351b0 74 75 61 6c 20 74 61 62 6c 65 20 69 6e 74 65 72  tual table inter
351c0 66 61 63 65 2c 0a 2a 2a 20 77 68 69 63 68 20 69  face,.** which i
351d0 73 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61  s experimental a
351e0 6e 64 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68  nd subject to ch
351f0 61 6e 67 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ange..*/.int sql
35200 69 74 65 33 5f 6f 76 65 72 6c 6f 61 64 5f 66 75  ite3_overload_fu
35210 6e 63 74 69 6f 6e 28 73 71 6c 69 74 65 33 2a 2c  nction(sqlite3*,
35220 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75   const char *zFu
35230 6e 63 4e 61 6d 65 2c 20 69 6e 74 20 6e 41 72 67  ncName, int nArg
35240 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 69 6e  );../*.** The in
35250 74 65 72 66 61 63 65 20 74 6f 20 74 68 65 20 76  terface to the v
35260 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63  irtual-table mec
35270 68 61 6e 69 73 6d 20 64 65 66 69 6e 65 64 20 61  hanism defined a
35280 62 6f 76 65 20 28 62 61 63 6b 20 75 70 0a 2a 2a  bove (back up.**
35290 20 74 6f 20 61 20 63 6f 6d 6d 65 6e 74 20 72 65   to a comment re
352a0 6d 61 72 6b 61 62 6c 79 20 73 69 6d 69 6c 61 72  markably similar
352b0 20 74 6f 20 74 68 69 73 20 6f 6e 65 29 20 69 73   to this one) is
352c0 20 63 75 72 72 65 6e 74 6c 79 20 63 6f 6e 73 69   currently consi
352d0 64 65 72 65 64 0a 2a 2a 20 74 6f 20 62 65 20 65  dered.** to be e
352e0 78 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 54 68  xperimental.  Th
352f0 65 20 69 6e 74 65 72 66 61 63 65 20 6d 69 67 68  e interface migh
35300 74 20 63 68 61 6e 67 65 20 69 6e 20 69 6e 63 6f  t change in inco
35310 6d 70 61 74 69 62 6c 65 20 77 61 79 73 2e 0a 2a  mpatible ways..*
35320 2a 20 49 66 20 74 68 69 73 20 69 73 20 61 20 70  * If this is a p
35330 72 6f 62 6c 65 6d 20 66 6f 72 20 79 6f 75 2c 20  roblem for you, 
35340 64 6f 20 6e 6f 74 20 75 73 65 20 74 68 65 20 69  do not use the i
35350 6e 74 65 72 66 61 63 65 20 61 74 20 74 68 69 73  nterface at this
35360 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65   time..**.** Whe
35370 6e 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61  n the virtual-ta
35380 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 73 74  ble mechanism st
35390 61 62 69 6c 69 7a 65 73 2c 20 77 65 20 77 69 6c  abilizes, we wil
353a0 6c 20 64 65 63 6c 61 72 65 20 74 68 65 0a 2a 2a  l declare the.**
353b0 20 69 6e 74 65 72 66 61 63 65 20 66 69 78 65 64   interface fixed
353c0 2c 20 73 75 70 70 6f 72 74 20 69 74 20 69 6e 64  , support it ind
353d0 65 66 69 6e 69 74 65 6c 79 2c 20 61 6e 64 20 72  efinitely, and r
353e0 65 6d 6f 76 65 20 74 68 69 73 20 63 6f 6d 6d 65  emove this comme
353f0 6e 74 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 20 45 58  nt..**.****** EX
35400 50 45 52 49 4d 45 4e 54 41 4c 20 2d 20 73 75 62  PERIMENTAL - sub
35410 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 77  ject to change w
35420 69 74 68 6f 75 74 20 6e 6f 74 69 63 65 20 2a 2a  ithout notice **
35430 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2f 0a  ************.*/.
35440 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
35450 20 41 20 48 61 6e 64 6c 65 20 54 6f 20 41 6e 20   A Handle To An 
35460 4f 70 65 6e 20 42 4c 4f 42 20 7b 46 31 37 38 30  Open BLOB {F1780
35470 30 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74  0}.**.** An inst
35480 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
35490 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61  ect represents a
354a0 6e 20 6f 70 65 6e 20 42 4c 4f 42 20 6f 6e 20 77  n open BLOB on w
354b0 68 69 63 68 0a 2a 2a 20 69 6e 63 72 65 6d 65 6e  hich.** incremen
354c0 74 61 6c 20 49 2f 4f 20 63 61 6e 20 62 65 20 70  tal I/O can be p
354d0 72 65 66 6f 72 6d 65 64 2e 0a 2a 2a 20 4f 62 6a  reformed..** Obj
354e0 65 63 74 73 20 6f 66 20 74 68 69 73 20 74 79 70  ects of this typ
354f0 65 20 61 72 65 20 63 72 65 61 74 65 64 20 62 79  e are created by
35500 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  .** [sqlite3_blo
35510 62 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20 64 65  b_open()] and de
35520 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69  stroyed by [sqli
35530 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29  te3_blob_close()
35540 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  ]..** The [sqlit
35550 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29 5d 20  e3_blob_read()] 
35560 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  and [sqlite3_blo
35570 62 5f 77 72 69 74 65 28 29 5d 20 69 6e 74 65 72  b_write()] inter
35580 66 61 63 65 73 0a 2a 2a 20 63 61 6e 20 62 65 20  faces.** can be 
35590 75 73 65 64 20 74 6f 20 72 65 61 64 20 6f 72 20  used to read or 
355a0 77 72 69 74 65 20 73 6d 61 6c 6c 20 73 75 62 73  write small subs
355b0 65 63 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 62  ections of the b
355c0 6c 6f 62 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  lob..** The [sql
355d0 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28  ite3_blob_bytes(
355e0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
355f0 75 72 6e 73 20 74 68 65 20 73 69 7a 65 20 6f 66  urns the size of
35600 20 74 68 65 0a 2a 2a 20 62 6c 6f 62 20 69 6e 20   the.** blob in 
35610 62 79 74 65 73 2e 0a 2a 2f 0a 74 79 70 65 64 65  bytes..*/.typede
35620 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
35630 5f 62 6c 6f 62 20 73 71 6c 69 74 65 33 5f 62 6c  _blob sqlite3_bl
35640 6f 62 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  ob;../*.** CAPI3
35650 52 45 46 3a 20 4f 70 65 6e 20 41 20 42 4c 4f 42  REF: Open A BLOB
35660 20 46 6f 72 20 49 6e 63 72 65 6d 65 6e 74 61 6c   For Incremental
35670 20 49 2f 4f 20 7b 46 31 37 38 31 30 7d 0a 2a 2a   I/O {F17810}.**
35680 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61  .** This interfa
35690 63 65 73 20 6f 70 65 6e 73 20 61 20 68 61 6e 64  ces opens a hand
356a0 6c 65 20 74 6f 20 74 68 65 20 62 6c 6f 62 20 6c  le to the blob l
356b0 6f 63 61 74 65 64 0a 2a 2a 20 69 6e 20 72 6f 77  ocated.** in row
356c0 20 69 52 6f 77 2c 2c 20 63 6f 6c 75 6d 6e 20 7a   iRow,, column z
356d0 43 6f 6c 75 6d 6e 2c 20 74 61 62 6c 65 20 7a 54  Column, table zT
356e0 61 62 6c 65 20 69 6e 20 64 61 74 61 62 61 73 65  able in database
356f0 20 7a 44 62 3b 0a 2a 2a 20 69 6e 20 6f 74 68 65   zDb;.** in othe
35700 72 20 77 6f 72 64 73 2c 20 20 74 68 65 20 73 61  r words,  the sa
35710 6d 65 20 62 6c 6f 62 20 74 68 61 74 20 77 6f 75  me blob that wou
35720 6c 64 20 62 65 20 73 65 6c 65 63 74 65 64 20 62  ld be selected b
35730 79 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a  y:.**.** <pre>.*
35740 2a 20 20 20 20 20 53 45 4c 45 43 54 20 7a 43 6f  *     SELECT zCo
35750 6c 75 6d 6e 20 46 52 4f 4d 20 7a 44 62 2e 7a 54  lumn FROM zDb.zT
35760 61 62 6c 65 20 57 48 45 52 45 20 72 6f 77 69 64  able WHERE rowid
35770 20 3d 20 69 52 6f 77 3b 0a 2a 2a 20 3c 2f 70 72   = iRow;.** </pr
35780 65 3e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 49  e> {END}.**.** I
35790 66 20 74 68 65 20 66 6c 61 67 73 20 70 61 72 61  f the flags para
357a0 6d 65 74 65 72 20 69 73 20 6e 6f 6e 2d 7a 65 72  meter is non-zer
357b0 6f 2c 20 74 68 65 20 62 6c 6f 62 20 69 73 20 6f  o, the blob is o
357c0 70 65 6e 65 64 20 66 6f 72 20 0a 2a 2a 20 72 65  pened for .** re
357d0 61 64 20 61 6e 64 20 77 72 69 74 65 20 61 63 63  ad and write acc
357e0 65 73 73 2e 20 49 66 20 69 74 20 69 73 20 7a 65  ess. If it is ze
357f0 72 6f 2c 20 74 68 65 20 62 6c 6f 62 20 69 73 20  ro, the blob is 
35800 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 20  opened for read 
35810 0a 2a 2a 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a  .** access..**.*
35820 2a 20 4f 6e 20 73 75 63 63 65 73 73 2c 20 5b 53  * On success, [S
35830 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74  QLITE_OK] is ret
35840 75 72 6e 65 64 20 61 6e 64 20 74 68 65 20 6e 65  urned and the ne
35850 77 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  w .** [sqlite3_b
35860 6c 6f 62 20 7c 20 62 6c 6f 62 20 68 61 6e 64 6c  lob | blob handl
35870 65 5d 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f  e] is written to
35880 20 2a 70 70 42 6c 6f 62 2e 20 0a 2a 2a 20 4f 74   *ppBlob. .** Ot
35890 68 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72  herwise an error
358a0 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65   code is returne
358b0 64 20 61 6e 64 20 0a 2a 2a 20 61 6e 79 20 76 61  d and .** any va
358c0 6c 75 65 20 77 72 69 74 74 65 6e 20 74 6f 20 2a  lue written to *
358d0 70 70 42 6c 6f 62 20 73 68 6f 75 6c 64 20 6e 6f  ppBlob should no
358e0 74 20 62 65 20 75 73 65 64 20 62 79 20 74 68 65  t be used by the
358f0 20 63 61 6c 6c 65 72 2e 0a 2a 2a 20 54 68 69 73   caller..** This
35900 20 66 75 6e 63 74 69 6f 6e 20 73 65 74 73 20 74   function sets t
35910 68 65 20 64 61 74 61 62 61 73 65 2d 68 61 6e 64  he database-hand
35920 6c 65 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e  le error code an
35930 64 20 6d 65 73 73 61 67 65 0a 2a 2a 20 61 63 63  d message.** acc
35940 65 73 73 69 62 6c 65 20 76 69 61 20 5b 73 71 6c  essible via [sql
35950 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20  ite3_errcode()] 
35960 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  and [sqlite3_err
35970 6d 73 67 28 29 5d 2e 0a 2a 2a 20 0a 2a 2a 20 49  msg()]..** .** I
35980 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
35990 20 7b 46 31 37 38 31 33 7d 20 41 20 73 75 63 63   {F17813} A succ
359a0 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f  essful invocatio
359b0 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  n of the [sqlite
359c0 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 44 2c 42 2c  3_blob_open(D,B,
359d0 54 2c 43 2c 52 2c 46 2c 50 29 5d 0a 2a 2a 20 20  T,C,R,F,P)].**  
359e0 20 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 63          interfac
359f0 65 20 6f 70 65 6e 73 20 61 6e 20 5b 73 71 6c 69  e opens an [sqli
35a00 74 65 33 5f 62 6c 6f 62 5d 20 6f 62 6a 65 63 74  te3_blob] object
35a10 20 50 20 6f 6e 20 74 68 65 20 62 6c 6f 62 0a 2a   P on the blob.*
35a20 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 63 6f  *          in co
35a30 6c 75 6d 6e 20 43 20 6f 66 20 74 61 62 6c 65 20  lumn C of table 
35a40 54 20 69 6e 20 64 61 74 61 62 61 73 65 20 42 20  T in database B 
35a50 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  on [database con
35a60 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a  nection] D..**.*
35a70 2a 20 7b 46 31 37 38 31 34 7d 20 41 20 73 75 63  * {F17814} A suc
35a80 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69  cessful invocati
35a90 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 62  on of [sqlite3_b
35aa0 6c 6f 62 5f 6f 70 65 6e 28 44 2c 2e 2e 2e 29 5d  lob_open(D,...)]
35ab0 20 73 74 61 72 74 73 0a 2a 2a 20 20 20 20 20 20   starts.**      
35ac0 20 20 20 20 61 20 6e 65 77 20 74 72 61 6e 73 61      a new transa
35ad0 63 74 69 6f 6e 20 6f 6e 20 5b 64 61 74 61 62 61  ction on [databa
35ae0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
35af0 20 69 66 20 74 68 61 74 20 63 6f 6e 6e 65 63 74   if that connect
35b00 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ion.**          
35b10 69 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 69  is not already i
35b20 6e 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e  n a transaction.
35b30 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 38 31 36 7d 20  .**.** {F17816} 
35b40 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  The [sqlite3_blo
35b50 62 5f 6f 70 65 6e 28 44 2c 42 2c 54 2c 43 2c 52  b_open(D,B,T,C,R
35b60 2c 46 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 65  ,F,P)] interface
35b70 20 6f 70 65 6e 73 20 74 68 65 20 62 6c 6f 62 0a   opens the blob.
35b80 2a 2a 20 20 20 20 20 20 20 20 20 20 66 6f 72 20  **          for 
35b90 72 65 61 64 20 61 6e 64 20 77 72 69 74 65 20 61  read and write a
35ba0 63 63 65 73 73 20 69 66 20 61 6e 64 20 6f 6e 6c  ccess if and onl
35bb0 79 20 69 66 20 74 68 65 20 46 20 70 61 72 61 6d  y if the F param
35bc0 65 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  eter.**         
35bd0 20 69 73 20 6e 6f 6e 2d 7a 65 72 6f 2e 0a 2a 2a   is non-zero..**
35be0 0a 2a 2a 20 7b 46 31 37 38 31 39 7d 20 54 68 65  .** {F17819} The
35bf0 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f   [sqlite3_blob_o
35c00 70 65 6e 28 29 5d 20 69 6e 74 65 72 66 61 63 65  pen()] interface
35c10 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
35c20 5f 4f 4b 5d 20 6f 6e 20 0a 2a 2a 20 20 20 20 20  _OK] on .**     
35c30 20 20 20 20 20 73 75 63 63 65 73 73 20 61 6e 64       success and
35c40 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20   an appropriate 
35c50 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 6e 20  [error code] on 
35c60 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 7b  failure..**.** {
35c70 46 31 37 38 32 31 7d 20 49 66 20 61 6e 20 65 72  F17821} If an er
35c80 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e  ror occurs durin
35c90 67 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20  g evaluation of 
35ca0 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70  [sqlite3_blob_op
35cb0 65 6e 28 44 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20  en(D,...)].**   
35cc0 20 20 20 20 20 20 20 74 68 65 6e 20 73 75 62 73         then subs
35cd0 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20  equent calls to 
35ce0 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65  [sqlite3_errcode
35cf0 28 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  (D)],.**        
35d00 20 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73    [sqlite3_errms
35d10 67 28 44 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  g(D)], and [sqli
35d20 74 65 33 5f 65 72 72 6d 73 67 31 36 28 44 29 5d  te3_errmsg16(D)]
35d30 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20   will return.** 
35d40 20 20 20 20 20 20 20 20 20 69 6e 66 6f 72 6d 61           informa
35d50 74 69 6f 6e 20 61 70 70 72 6f 70 72 61 74 65 20  tion approprate 
35d60 66 6f 72 20 74 68 61 74 20 65 72 72 6f 72 2e 0a  for that error..
35d70 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
35d80 6c 6f 62 5f 6f 70 65 6e 28 0a 20 20 73 71 6c 69  lob_open(.  sqli
35d90 74 65 33 2a 2c 0a 20 20 63 6f 6e 73 74 20 63 68  te3*,.  const ch
35da0 61 72 20 2a 7a 44 62 2c 0a 20 20 63 6f 6e 73 74  ar *zDb,.  const
35db0 20 63 68 61 72 20 2a 7a 54 61 62 6c 65 2c 0a 20   char *zTable,. 
35dc0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 43 6f   const char *zCo
35dd0 6c 75 6d 6e 2c 0a 20 20 73 71 6c 69 74 65 33 5f  lumn,.  sqlite3_
35de0 69 6e 74 36 34 20 69 52 6f 77 2c 0a 20 20 69 6e  int64 iRow,.  in
35df0 74 20 66 6c 61 67 73 2c 0a 20 20 73 71 6c 69 74  t flags,.  sqlit
35e00 65 33 5f 62 6c 6f 62 20 2a 2a 70 70 42 6c 6f 62  e3_blob **ppBlob
35e10 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
35e20 52 45 46 3a 20 20 43 6c 6f 73 65 20 41 20 42 4c  REF:  Close A BL
35e30 4f 42 20 48 61 6e 64 6c 65 20 7b 46 31 37 38 33  OB Handle {F1783
35e40 30 7d 0a 2a 2a 0a 2a 2a 20 43 6c 6f 73 65 20 61  0}.**.** Close a
35e50 6e 20 6f 70 65 6e 20 5b 73 71 6c 69 74 65 33 5f  n open [sqlite3_
35e60 62 6c 6f 62 20 7c 20 62 6c 6f 62 20 68 61 6e 64  blob | blob hand
35e70 6c 65 5d 2e 0a 2a 2a 0a 2a 2a 20 43 6c 6f 73 69  le]..**.** Closi
35e80 6e 67 20 61 20 42 4c 4f 42 20 73 68 61 6c 6c 20  ng a BLOB shall 
35e90 63 61 75 73 65 20 74 68 65 20 63 75 72 72 65 6e  cause the curren
35ea0 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 6f  t transaction to
35eb0 20 63 6f 6d 6d 69 74 0a 2a 2a 20 69 66 20 74 68   commit.** if th
35ec0 65 72 65 20 61 72 65 20 6e 6f 20 6f 74 68 65 72  ere are no other
35ed0 20 42 4c 4f 42 73 2c 20 6e 6f 20 70 65 6e 64 69   BLOBs, no pendi
35ee0 6e 67 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ng prepared stat
35ef0 65 6d 65 6e 74 73 2c 20 61 6e 64 20 74 68 65 0a  ements, and the.
35f00 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
35f10 65 63 74 69 6f 6e 20 69 73 20 69 6e 20 61 75 74  ection is in aut
35f20 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 2e 0a 2a 2a  ocommit mode..**
35f30 20 49 66 20 61 6e 79 20 77 72 69 74 65 73 20 77   If any writes w
35f40 65 72 65 20 6d 61 64 65 20 74 6f 20 74 68 65 20  ere made to the 
35f50 42 4c 4f 42 2c 20 74 68 65 79 20 6d 69 67 68 74  BLOB, they might
35f60 20 62 65 20 68 65 6c 64 20 69 6e 20 63 61 63 68   be held in cach
35f70 65 0a 2a 2a 20 75 6e 74 69 6c 20 74 68 65 20 63  e.** until the c
35f80 6c 6f 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 69  lose operation i
35f90 66 20 74 68 65 79 20 77 69 6c 6c 20 66 69 74 2e  f they will fit.
35fa0 20 7b 45 4e 44 7d 0a 2a 2a 20 43 6c 6f 73 69 6e   {END}.** Closin
35fb0 67 20 74 68 65 20 42 4c 4f 42 20 6f 66 74 65 6e  g the BLOB often
35fc0 20 66 6f 72 63 65 73 20 74 68 65 20 63 68 61 6e   forces the chan
35fd0 67 65 73 0a 2a 2a 20 6f 75 74 20 74 6f 20 64 69  ges.** out to di
35fe0 73 6b 20 61 6e 64 20 73 6f 20 69 66 20 61 6e 79  sk and so if any
35ff0 20 49 2f 4f 20 65 72 72 6f 72 73 20 6f 63 63 75   I/O errors occu
36000 72 2c 20 74 68 65 79 20 77 69 6c 6c 20 6c 69 6b  r, they will lik
36010 65 6c 79 20 6f 63 63 75 72 0a 2a 2a 20 61 74 20  ely occur.** at 
36020 74 68 65 20 74 69 6d 65 20 77 68 65 6e 20 74 68  the time when th
36030 65 20 42 4c 4f 42 20 69 73 20 63 6c 6f 73 65 64  e BLOB is closed
36040 2e 20 20 7b 46 31 37 38 33 33 7d 20 41 6e 79 20  .  {F17833} Any 
36050 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75  errors that occu
36060 72 20 64 75 72 69 6e 67 0a 2a 2a 20 63 6c 6f 73  r during.** clos
36070 69 6e 67 20 61 72 65 20 72 65 70 6f 72 74 65 64  ing are reported
36080 20 61 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 72   as a non-zero r
36090 65 74 75 72 6e 20 76 61 6c 75 65 2e 0a 2a 2a 0a  eturn value..**.
360a0 2a 2a 20 54 68 65 20 42 4c 4f 42 20 69 73 20 63  ** The BLOB is c
360b0 6c 6f 73 65 64 20 75 6e 63 6f 6e 64 69 74 69 6f  losed unconditio
360c0 6e 61 6c 6c 79 2e 20 20 45 76 65 6e 20 69 66 20  nally.  Even if 
360d0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  this routine ret
360e0 75 72 6e 73 0a 2a 2a 20 61 6e 20 65 72 72 6f 72  urns.** an error
360f0 20 63 6f 64 65 2c 20 74 68 65 20 42 4c 4f 42 20   code, the BLOB 
36100 69 73 20 73 74 69 6c 6c 20 63 6c 6f 73 65 64 2e  is still closed.
36110 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
36120 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 38 33 33  S:.**.** {F17833
36130 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  } The [sqlite3_b
36140 6c 6f 62 5f 63 6c 6f 73 65 28 50 29 5d 20 69 6e  lob_close(P)] in
36150 74 65 72 66 61 63 65 20 63 6c 6f 73 65 73 20 61  terface closes a
36160 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  n.**          [s
36170 71 6c 69 74 65 33 5f 62 6c 6f 62 5d 20 6f 62 6a  qlite3_blob] obj
36180 65 63 74 20 50 20 70 72 65 76 69 6f 75 73 6c 79  ect P previously
36190 20 6f 70 65 6e 65 64 20 75 73 69 6e 67 0a 2a 2a   opened using.**
361a0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
361b0 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 2e  e3_blob_open()].
361c0 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 38 33 36 7d 20  .**.** {F17836} 
361d0 43 6c 6f 73 69 6e 67 20 61 6e 20 5b 73 71 6c 69  Closing an [sqli
361e0 74 65 33 5f 62 6c 6f 62 5d 20 6f 62 6a 65 63 74  te3_blob] object
361f0 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20   using.**       
36200 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62     [sqlite3_blob
36210 5f 63 6c 6f 73 65 28 29 5d 20 73 68 61 6c 6c 20  _close()] shall 
36220 63 61 75 73 65 20 74 68 65 20 63 75 72 72 65 6e  cause the curren
36230 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 6f  t transaction to
36240 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6d  .**          com
36250 6d 69 74 20 69 66 20 74 68 65 72 65 20 61 72 65  mit if there are
36260 20 6e 6f 20 6f 74 68 65 72 20 6f 70 65 6e 20 5b   no other open [
36270 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5d 20 6f 62  sqlite3_blob] ob
36280 6a 65 63 74 73 0a 2a 2a 20 20 20 20 20 20 20 20  jects.**        
36290 20 20 6f 72 20 5b 70 72 65 70 61 72 65 64 20 73    or [prepared s
362a0 74 61 74 65 6d 65 6e 74 73 5d 20 6f 6e 20 74 68  tatements] on th
362b0 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65  e same [database
362c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64   connection] and
362d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
362e0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
362f0 63 74 69 6f 6e 5d 20 69 73 20 69 6e 0a 2a 2a 20  ction] is in.** 
36300 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
36310 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74  3_get_autocommit
36320 20 7c 20 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f   | autocommit mo
36330 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 38  de]..**.** {F178
36340 33 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  39} The [sqlite3
36350 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 50 29 5d 20  _blob_close(P)] 
36360 69 6e 74 65 72 66 61 63 65 73 20 63 6c 6f 73 65  interfaces close
36370 73 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 20 20  s the .**       
36380 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62     [sqlite3_blob
36390 5d 20 6f 62 6a 65 63 74 20 50 20 75 6e 63 6f 6e  ] object P uncon
363a0 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 65 76 65 6e  ditionally, even
363b0 20 69 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   if.**          
363c0 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c  [sqlite3_blob_cl
363d0 6f 73 65 28 50 29 5d 20 72 65 74 75 72 6e 73 20  ose(P)] returns 
363e0 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20  something other 
363f0 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  than [SQLITE_OK]
36400 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 0a 2a  ..**          .*
36410 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c  /.int sqlite3_bl
36420 6f 62 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33  ob_close(sqlite3
36430 5f 62 6c 6f 62 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  _blob *);../*.**
36440 20 43 41 50 49 33 52 45 46 3a 20 20 52 65 74 75   CAPI3REF:  Retu
36450 72 6e 20 54 68 65 20 53 69 7a 65 20 4f 66 20 41  rn The Size Of A
36460 6e 20 4f 70 65 6e 20 42 4c 4f 42 20 7b 46 31 37  n Open BLOB {F17
36470 38 34 30 7d 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72  840}.**.** Retur
36480 6e 20 74 68 65 20 73 69 7a 65 20 69 6e 20 62 79  n the size in by
36490 74 65 73 20 6f 66 20 74 68 65 20 62 6c 6f 62 20  tes of the blob 
364a0 61 63 63 65 73 73 69 62 6c 65 20 76 69 61 20 74  accessible via t
364b0 68 65 20 6f 70 65 6e 20 0a 2a 2a 20 5b 73 71 6c  he open .** [sql
364c0 69 74 65 33 5f 62 6c 6f 62 5d 20 6f 62 6a 65 63  ite3_blob] objec
364d0 74 20 69 6e 20 69 74 73 20 6f 6e 6c 79 20 61 72  t in its only ar
364e0 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 49 4e  gument..**.** IN
364f0 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
36500 7b 46 31 37 38 34 33 7d 20 54 68 65 20 5b 73 71  {F17843} The [sq
36510 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73  lite3_blob_bytes
36520 28 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  (P)] interface r
36530 65 74 75 72 6e 73 20 74 68 65 20 73 69 7a 65 0a  eturns the size.
36540 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 62  **          in b
36550 79 74 65 73 20 6f 66 20 74 68 65 20 42 4c 4f 42  ytes of the BLOB
36560 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74   that the [sqlit
36570 65 33 5f 62 6c 6f 62 5d 20 6f 62 6a 65 63 74 20  e3_blob] object 
36580 50 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  P.**          re
36590 66 65 72 73 20 74 6f 2e 0a 2a 2f 0a 69 6e 74 20  fers to..*/.int 
365a0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74  sqlite3_blob_byt
365b0 65 73 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20  es(sqlite3_blob 
365c0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
365d0 52 45 46 3a 20 20 52 65 61 64 20 44 61 74 61 20  REF:  Read Data 
365e0 46 72 6f 6d 20 41 20 42 4c 4f 42 20 49 6e 63 72  From A BLOB Incr
365f0 65 6d 65 6e 74 61 6c 6c 79 20 7b 46 31 37 38 35  ementally {F1785
36600 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75  0}.**.** This fu
36610 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74  nction is used t
36620 6f 20 72 65 61 64 20 64 61 74 61 20 66 72 6f 6d  o read data from
36630 20 61 6e 20 6f 70 65 6e 20 0a 2a 2a 20 5b 73 71   an open .** [sq
36640 6c 69 74 65 33 5f 62 6c 6f 62 20 7c 20 62 6c 6f  lite3_blob | blo
36650 62 2d 68 61 6e 64 6c 65 5d 20 69 6e 74 6f 20 61  b-handle] into a
36660 20 63 61 6c 6c 65 72 20 73 75 70 70 6c 69 65 64   caller supplied
36670 20 62 75 66 66 65 72 2e 0a 2a 2a 20 4e 20 62 79   buffer..** N by
36680 74 65 73 20 6f 66 20 64 61 74 61 20 61 72 65 20  tes of data are 
36690 63 6f 70 69 65 64 20 69 6e 74 6f 20 62 75 66 66  copied into buff
366a0 65 72 0a 2a 2a 20 5a 20 66 72 6f 6d 20 74 68 65  er.** Z from the
366b0 20 6f 70 65 6e 20 62 6c 6f 62 2c 20 73 74 61 72   open blob, star
366c0 74 69 6e 67 20 61 74 20 6f 66 66 73 65 74 20 69  ting at offset i
366d0 4f 66 66 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 49 66  Offset..**.** If
366e0 20 6f 66 66 73 65 74 20 69 4f 66 66 73 65 74 20   offset iOffset 
366f0 69 73 20 6c 65 73 73 20 74 68 61 6e 20 4e 20 62  is less than N b
36700 79 74 65 73 20 66 72 6f 6d 20 74 68 65 20 65 6e  ytes from the en
36710 64 20 6f 66 20 74 68 65 20 62 6c 6f 62 2c 20 0a  d of the blob, .
36720 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ** [SQLITE_ERROR
36730 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e  ] is returned an
36740 64 20 6e 6f 20 64 61 74 61 20 69 73 20 72 65 61  d no data is rea
36750 64 2e 20 20 49 66 20 4e 20 6f 72 20 69 4f 66 66  d.  If N or iOff
36760 73 65 74 20 69 73 0a 2a 2a 20 6c 65 73 73 20 74  set is.** less t
36770 68 61 6e 20 7a 65 72 6f 20 5b 53 51 4c 49 54 45  han zero [SQLITE
36780 5f 45 52 52 4f 52 5d 20 69 73 20 72 65 74 75 72  _ERROR] is retur
36790 6e 65 64 20 61 6e 64 20 6e 6f 20 64 61 74 61 20  ned and no data 
367a0 69 73 20 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 4f  is read..**.** O
367b0 6e 20 73 75 63 63 65 73 73 2c 20 53 51 4c 49 54  n success, SQLIT
367c0 45 5f 4f 4b 20 69 73 20 72 65 74 75 72 6e 65 64  E_OK is returned
367d0 2e 20 4f 74 68 65 72 77 69 73 65 2c 20 61 6e 20  . Otherwise, an 
367e0 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  .** [error code]
367f0 20 6f 72 20 61 6e 20 5b 65 78 74 65 6e 64 65 64   or an [extended
36800 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20   error code] is 
36810 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
36820 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
36830 2a 20 7b 46 31 37 38 35 33 7d 20 54 68 65 20 5b  * {F17853} The [
36840 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61  sqlite3_blob_rea
36850 64 28 50 2c 5a 2c 4e 2c 58 29 5d 20 69 6e 74 65  d(P,Z,N,X)] inte
36860 72 66 61 63 65 20 72 65 61 64 73 20 4e 20 62 79  rface reads N by
36870 74 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  tes.**          
36880 62 65 67 69 6e 6e 69 6e 67 20 61 74 20 6f 66 66  beginning at off
36890 73 65 74 20 58 20 66 72 6f 6d 0a 2a 2a 20 20 20  set X from.**   
368a0 20 20 20 20 20 20 20 74 68 65 20 62 6c 6f 62 20         the blob 
368b0 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 62 6c  that [sqlite3_bl
368c0 6f 62 5d 20 6f 62 6a 65 63 74 20 50 20 72 65 66  ob] object P ref
368d0 65 72 73 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20  ers to.**       
368e0 20 20 20 61 6e 64 20 77 72 69 74 65 73 20 74 68     and writes th
368f0 6f 73 65 20 4e 20 62 79 74 65 73 20 69 6e 74 6f  ose N bytes into
36900 20 62 75 66 66 65 72 20 5a 2e 0a 2a 2a 0a 2a 2a   buffer Z..**.**
36910 20 7b 46 31 37 38 35 36 7d 20 49 6e 20 5b 73 71   {F17856} In [sq
36920 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28  lite3_blob_read(
36930 50 2c 5a 2c 4e 2c 58 29 5d 20 69 66 20 74 68 65  P,Z,N,X)] if the
36940 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 6c 6f   size of the blo
36950 62 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73  b.**          is
36960 20 6c 65 73 73 20 74 68 61 6e 20 4e 2b 58 20 62   less than N+X b
36970 79 74 65 73 2c 20 74 68 65 6e 20 74 68 65 20 66  ytes, then the f
36980 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
36990 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 0a 2a  [SQLITE_ERROR].*
369a0 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64 20 6e  *          and n
369b0 6f 74 68 69 6e 67 20 69 73 20 72 65 61 64 20 66  othing is read f
369c0 72 6f 6d 20 74 68 65 20 62 6c 6f 62 2e 0a 2a 2a  rom the blob..**
369d0 0a 2a 2a 20 7b 46 31 37 38 35 39 7d 20 49 6e 20  .** {F17859} In 
369e0 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65  [sqlite3_blob_re
369f0 61 64 28 50 2c 5a 2c 4e 2c 58 29 5d 20 69 66 20  ad(P,Z,N,X)] if 
36a00 58 20 6f 72 20 4e 20 69 73 20 6c 65 73 73 20 74  X or N is less t
36a10 68 61 6e 20 7a 65 72 6f 0a 2a 2a 20 20 20 20 20  han zero.**     
36a20 20 20 20 20 20 74 68 65 6e 20 74 68 65 20 66 75       then the fu
36a30 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 5b  nction returns [
36a40 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 0a 2a 2a  SQLITE_ERROR].**
36a50 20 20 20 20 20 20 20 20 20 20 61 6e 64 20 6e 6f            and no
36a60 74 68 69 6e 67 20 69 73 20 72 65 61 64 20 66 72  thing is read fr
36a70 6f 6d 20 74 68 65 20 62 6c 6f 62 2e 0a 2a 2a 0a  om the blob..**.
36a80 2a 2a 20 7b 46 31 37 38 36 32 7d 20 54 68 65 20  ** {F17862} The 
36a90 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65  [sqlite3_blob_re
36aa0 61 64 28 50 2c 5a 2c 4e 2c 58 29 5d 20 69 6e 74  ad(P,Z,N,X)] int
36ab0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 5b  erface returns [
36ac0 53 51 4c 49 54 45 5f 4f 4b 5d 0a 2a 2a 20 20 20  SQLITE_OK].**   
36ad0 20 20 20 20 20 20 20 69 66 20 4e 20 62 79 74 65         if N byte
36ae0 73 20 77 68 65 72 65 20 73 75 63 63 65 73 73 66  s where successf
36af0 75 6c 6c 79 20 72 65 61 64 20 69 6e 74 6f 20 62  ully read into b
36b00 75 66 66 65 72 20 5a 2e 0a 2a 2a 0a 2a 2a 20 7b  uffer Z..**.** {
36b10 46 31 37 38 36 35 7d 20 49 66 20 74 68 65 20 72  F17865} If the r
36b20 65 71 75 65 73 74 65 64 20 72 65 61 64 20 63 6f  equested read co
36b30 75 6c 64 20 6e 6f 74 20 62 65 20 63 6f 6d 70 6c  uld not be compl
36b40 65 74 65 64 2c 0a 2a 2a 20 20 20 20 20 20 20 20  eted,.**        
36b50 20 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62    the [sqlite3_b
36b60 6c 6f 62 5f 72 65 61 64 28 50 2c 5a 2c 4e 2c 58  lob_read(P,Z,N,X
36b70 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
36b80 75 72 6e 73 20 61 6e 0a 2a 2a 20 20 20 20 20 20  urns an.**      
36b90 20 20 20 20 61 70 70 72 6f 70 72 69 61 74 65 20      appropriate 
36ba0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 20  [error code] or 
36bb0 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  [extended error 
36bc0 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  code]..**.** {F1
36bd0 37 38 36 38 7d 20 49 66 20 61 6e 20 65 72 72 6f  7868} If an erro
36be0 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20  r occurs during 
36bf0 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 5b 73  evaluation of [s
36c00 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64  qlite3_blob_read
36c10 28 44 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20  (D,...)].**     
36c20 20 20 20 20 20 74 68 65 6e 20 73 75 62 73 65 71       then subseq
36c30 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73  uent calls to [s
36c40 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 44  qlite3_errcode(D
36c50 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  )],.**          
36c60 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
36c70 44 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  D)], and [sqlite
36c80 33 5f 65 72 72 6d 73 67 31 36 28 44 29 5d 20 77  3_errmsg16(D)] w
36c90 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20  ill return.**   
36ca0 20 20 20 20 20 20 20 69 6e 66 6f 72 6d 61 74 69         informati
36cb0 6f 6e 20 61 70 70 72 6f 70 72 61 74 65 20 66 6f  on approprate fo
36cc0 72 20 74 68 61 74 20 65 72 72 6f 72 2e 0a 2a 2f  r that error..*/
36cd0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f  .int sqlite3_blo
36ce0 62 5f 72 65 61 64 28 73 71 6c 69 74 65 33 5f 62  b_read(sqlite3_b
36cf0 6c 6f 62 20 2a 2c 20 76 6f 69 64 20 2a 5a 2c 20  lob *, void *Z, 
36d00 69 6e 74 20 4e 2c 20 69 6e 74 20 69 4f 66 66 73  int N, int iOffs
36d10 65 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  et);../*.** CAPI
36d20 33 52 45 46 3a 20 20 57 72 69 74 65 20 44 61 74  3REF:  Write Dat
36d30 61 20 49 6e 74 6f 20 41 20 42 4c 4f 42 20 49 6e  a Into A BLOB In
36d40 63 72 65 6d 65 6e 74 61 6c 6c 79 20 7b 46 31 37  crementally {F17
36d50 38 37 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  870}.**.** This 
36d60 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64  function is used
36d70 20 74 6f 20 77 72 69 74 65 20 64 61 74 61 20 69   to write data i
36d80 6e 74 6f 20 61 6e 20 6f 70 65 6e 20 0a 2a 2a 20  nto an open .** 
36d90 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 7c 20  [sqlite3_blob | 
36da0 62 6c 6f 62 2d 68 61 6e 64 6c 65 5d 20 66 72 6f  blob-handle] fro
36db0 6d 20 61 20 75 73 65 72 20 73 75 70 70 6c 69 65  m a user supplie
36dc0 64 20 62 75 66 66 65 72 2e 0a 2a 2a 20 6e 20 62  d buffer..** n b
36dd0 79 74 65 73 20 6f 66 20 64 61 74 61 20 61 72 65  ytes of data are
36de0 20 63 6f 70 69 65 64 20 66 72 6f 6d 20 74 68 65   copied from the
36df0 20 62 75 66 66 65 72 0a 2a 2a 20 70 6f 69 6e 74   buffer.** point
36e00 65 64 20 74 6f 20 62 79 20 7a 20 69 6e 74 6f 20  ed to by z into 
36e10 74 68 65 20 6f 70 65 6e 20 62 6c 6f 62 2c 20 73  the open blob, s
36e20 74 61 72 74 69 6e 67 20 61 74 20 6f 66 66 73 65  tarting at offse
36e30 74 20 69 4f 66 66 73 65 74 2e 0a 2a 2a 0a 2a 2a  t iOffset..**.**
36e40 20 49 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   If the [sqlite3
36e50 5f 62 6c 6f 62 20 7c 20 62 6c 6f 62 2d 68 61 6e  _blob | blob-han
36e60 64 6c 65 5d 20 70 61 73 73 65 64 20 61 73 20 74  dle] passed as t
36e70 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
36e80 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 70 65  t.** was not ope
36e90 6e 65 64 20 66 6f 72 20 77 72 69 74 69 6e 67 20  ned for writing 
36ea0 28 74 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d  (the flags param
36eb0 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
36ec0 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 0a 2a 2a  _blob_open()].**
36ed0 2a 20 77 61 73 20 7a 65 72 6f 29 2c 20 74 68 69  * was zero), thi
36ee0 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  s function retur
36ef0 6e 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 4f  ns [SQLITE_READO
36f00 4e 4c 59 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  NLY]..**.** This
36f10 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 6f 6e   function may on
36f20 6c 79 20 6d 6f 64 69 66 79 20 74 68 65 20 63 6f  ly modify the co
36f30 6e 74 65 6e 74 73 20 6f 66 20 74 68 65 20 62 6c  ntents of the bl
36f40 6f 62 3b 20 69 74 20 69 73 0a 2a 2a 20 6e 6f 74  ob; it is.** not
36f50 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e 63   possible to inc
36f60 72 65 61 73 65 20 74 68 65 20 73 69 7a 65 20 6f  rease the size o
36f70 66 20 61 20 62 6c 6f 62 20 75 73 69 6e 67 20 74  f a blob using t
36f80 68 69 73 20 41 50 49 2e 0a 2a 2a 20 49 66 20 6f  his API..** If o
36f90 66 66 73 65 74 20 69 4f 66 66 73 65 74 20 69 73  ffset iOffset is
36fa0 20 6c 65 73 73 20 74 68 61 6e 20 6e 20 62 79 74   less than n byt
36fb0 65 73 20 66 72 6f 6d 20 74 68 65 20 65 6e 64 20  es from the end 
36fc0 6f 66 20 74 68 65 20 62 6c 6f 62 2c 20 0a 2a 2a  of the blob, .**
36fd0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
36fe0 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20  is returned and 
36ff0 6e 6f 20 64 61 74 61 20 69 73 20 77 72 69 74 74  no data is writt
37000 65 6e 2e 20 20 49 66 20 6e 20 69 73 0a 2a 2a 20  en.  If n is.** 
37010 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 20 5b  less than zero [
37020 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 73  SQLITE_ERROR] is
37030 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f   returned and no
37040 20 64 61 74 61 20 69 73 20 77 72 69 74 74 65 6e   data is written
37050 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63 65  ..**.** On succe
37060 73 73 2c 20 53 51 4c 49 54 45 5f 4f 4b 20 69 73  ss, SQLITE_OK is
37070 20 72 65 74 75 72 6e 65 64 2e 20 4f 74 68 65 72   returned. Other
37080 77 69 73 65 2c 20 61 6e 20 0a 2a 2a 20 5b 65 72  wise, an .** [er
37090 72 6f 72 20 63 6f 64 65 5d 20 6f 72 20 61 6e 20  ror code] or an 
370a0 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  [extended error 
370b0 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65  code] is returne
370c0 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  d..**.** INVARIA
370d0 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 38  NTS:.**.** {F178
370e0 37 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  73} The [sqlite3
370f0 5f 62 6c 6f 62 5f 77 72 69 74 65 28 50 2c 5a 2c  _blob_write(P,Z,
37100 4e 2c 58 29 5d 20 69 6e 74 65 72 66 61 63 65 20  N,X)] interface 
37110 77 72 69 74 65 73 20 4e 20 62 79 74 65 73 0a 2a  writes N bytes.*
37120 2a 20 20 20 20 20 20 20 20 20 20 66 72 6f 6d 20  *          from 
37130 62 75 66 66 65 72 20 5a 20 69 6e 74 6f 0a 2a 2a  buffer Z into.**
37140 20 20 20 20 20 20 20 20 20 20 74 68 65 20 62 6c            the bl
37150 6f 62 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33  ob that [sqlite3
37160 5f 62 6c 6f 62 5d 20 6f 62 6a 65 63 74 20 50 20  _blob] object P 
37170 72 65 66 65 72 73 20 74 6f 0a 2a 2a 20 20 20 20  refers to.**    
37180 20 20 20 20 20 20 62 65 67 69 6e 6e 69 6e 67 20        beginning 
37190 61 74 20 61 6e 20 6f 66 66 73 65 74 20 6f 66 20  at an offset of 
371a0 58 20 69 6e 74 6f 20 74 68 65 20 62 6c 6f 62 2e  X into the blob.
371b0 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 38 37 35 7d 20  .**.** {F17875} 
371c0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  The [sqlite3_blo
371d0 62 5f 77 72 69 74 65 28 50 2c 5a 2c 4e 2c 58 29  b_write(P,Z,N,X)
371e0 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
371f0 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  rns.**          
37200 5b 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59  [SQLITE_READONLY
37210 5d 20 69 66 20 74 68 65 20 5b 73 71 6c 69 74 65  ] if the [sqlite
37220 33 5f 62 6c 6f 62 5d 20 6f 62 6a 65 63 74 20 50  3_blob] object P
37230 20 77 61 73 0a 2a 2a 20 20 20 20 20 20 20 20 20   was.**         
37240 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f   [sqlite3_blob_o
37250 70 65 6e 20 7c 20 6f 70 65 6e 65 64 5d 20 66 6f  pen | opened] fo
37260 72 20 72 65 61 64 69 6e 67 20 6f 6e 6c 79 2e 0a  r reading only..
37270 2a 2a 0a 2a 2a 20 7b 46 31 37 38 37 36 7d 20 49  **.** {F17876} I
37280 6e 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  n [sqlite3_blob_
37290 77 72 69 74 65 28 50 2c 5a 2c 4e 2c 58 29 5d 20  write(P,Z,N,X)] 
372a0 69 66 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  if the size of t
372b0 68 65 20 62 6c 6f 62 0a 2a 2a 20 20 20 20 20 20  he blob.**      
372c0 20 20 20 20 69 73 20 6c 65 73 73 20 74 68 61 6e      is less than
372d0 20 4e 2b 58 20 62 79 74 65 73 2c 20 74 68 65 6e   N+X bytes, then
372e0 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 72 65   the function re
372f0 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 45 52  turns [SQLITE_ER
37300 52 4f 52 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ROR].**         
37310 20 61 6e 64 20 6e 6f 74 68 69 6e 67 20 69 73 20   and nothing is 
37320 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65  written into the
37330 20 62 6c 6f 62 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31   blob..**.** {F1
37340 37 38 37 39 7d 20 49 6e 20 5b 73 71 6c 69 74 65  7879} In [sqlite
37350 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 50 2c 5a  3_blob_write(P,Z
37360 2c 4e 2c 58 29 5d 20 69 66 20 58 20 6f 72 20 4e  ,N,X)] if X or N
37370 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 7a 65   is less than ze
37380 72 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  ro.**          t
37390 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  hen the function
373a0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
373b0 5f 45 52 52 4f 52 5d 0a 2a 2a 20 20 20 20 20 20  _ERROR].**      
373c0 20 20 20 20 61 6e 64 20 6e 6f 74 68 69 6e 67 20      and nothing 
373d0 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  is written into 
373e0 74 68 65 20 62 6c 6f 62 2e 0a 2a 2a 0a 2a 2a 20  the blob..**.** 
373f0 7b 46 31 37 38 38 32 7d 20 54 68 65 20 5b 73 71  {F17882} The [sq
37400 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65  lite3_blob_write
37410 28 50 2c 5a 2c 4e 2c 58 29 5d 20 69 6e 74 65 72  (P,Z,N,X)] inter
37420 66 61 63 65 20 72 65 74 75 72 6e 73 20 5b 53 51  face returns [SQ
37430 4c 49 54 45 5f 4f 4b 5d 0a 2a 2a 20 20 20 20 20  LITE_OK].**     
37440 20 20 20 20 20 69 66 20 4e 20 62 79 74 65 73 20       if N bytes 
37450 77 68 65 72 65 20 73 75 63 63 65 73 73 66 75 6c  where successful
37460 6c 79 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  ly written into 
37470 62 6c 6f 62 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37  blob..**.** {F17
37480 38 38 35 7d 20 49 66 20 74 68 65 20 72 65 71 75  885} If the requ
37490 65 73 74 65 64 20 77 72 69 74 65 20 63 6f 75 6c  ested write coul
374a0 64 20 6e 6f 74 20 62 65 20 63 6f 6d 70 6c 65 74  d not be complet
374b0 65 64 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ed,.**          
374c0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  the [sqlite3_blo
374d0 62 5f 77 72 69 74 65 28 50 2c 5a 2c 4e 2c 58 29  b_write(P,Z,N,X)
374e0 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
374f0 72 6e 73 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20  rns an.**       
37500 20 20 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b     appropriate [
37510 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 20 5b  error code] or [
37520 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63  extended error c
37530 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37  ode]..**.** {F17
37540 38 38 38 7d 20 49 66 20 61 6e 20 65 72 72 6f 72  888} If an error
37550 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 65   occurs during e
37560 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 5b 73 71  valuation of [sq
37570 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65  lite3_blob_write
37580 28 44 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20  (D,...)].**     
37590 20 20 20 20 20 74 68 65 6e 20 73 75 62 73 65 71       then subseq
375a0 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73  uent calls to [s
375b0 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 44  qlite3_errcode(D
375c0 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  )],.**          
375d0 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
375e0 44 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  D)], and [sqlite
375f0 33 5f 65 72 72 6d 73 67 31 36 28 44 29 5d 20 77  3_errmsg16(D)] w
37600 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20  ill return.**   
37610 20 20 20 20 20 20 20 69 6e 66 6f 72 6d 61 74 69         informati
37620 6f 6e 20 61 70 70 72 6f 70 72 61 74 65 20 66 6f  on approprate fo
37630 72 20 74 68 61 74 20 65 72 72 6f 72 2e 0a 2a 2f  r that error..*/
37640 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f  .int sqlite3_blo
37650 62 5f 77 72 69 74 65 28 73 71 6c 69 74 65 33 5f  b_write(sqlite3_
37660 62 6c 6f 62 20 2a 2c 20 63 6f 6e 73 74 20 76 6f  blob *, const vo
37670 69 64 20 2a 7a 2c 20 69 6e 74 20 6e 2c 20 69 6e  id *z, int n, in
37680 74 20 69 4f 66 66 73 65 74 29 3b 0a 0a 2f 2a 0a  t iOffset);../*.
37690 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 56 69  ** CAPI3REF:  Vi
376a0 72 74 75 61 6c 20 46 69 6c 65 20 53 79 73 74 65  rtual File Syste
376b0 6d 20 4f 62 6a 65 63 74 73 20 7b 46 31 31 32 30  m Objects {F1120
376c0 30 7d 0a 2a 2a 0a 2a 2a 20 41 20 76 69 72 74 75  0}.**.** A virtu
376d0 61 6c 20 66 69 6c 65 73 79 73 74 65 6d 20 28 56  al filesystem (V
376e0 46 53 29 20 69 73 20 61 6e 20 5b 73 71 6c 69 74  FS) is an [sqlit
376f0 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 0a 2a  e3_vfs] object.*
37700 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20 75 73  * that SQLite us
37710 65 73 20 74 6f 20 69 6e 74 65 72 61 63 74 0a 2a  es to interact.*
37720 2a 20 77 69 74 68 20 74 68 65 20 75 6e 64 65 72  * with the under
37730 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20  lying operating 
37740 73 79 73 74 65 6d 2e 20 20 4d 6f 73 74 20 53 51  system.  Most SQ
37750 4c 69 74 65 20 62 75 69 6c 64 73 20 63 6f 6d 65  Lite builds come
37760 20 77 69 74 68 20 61 0a 2a 2a 20 73 69 6e 67 6c   with a.** singl
37770 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 74 68  e default VFS th
37780 61 74 20 69 73 20 61 70 70 72 6f 70 72 69 61 74  at is appropriat
37790 65 20 66 6f 72 20 74 68 65 20 68 6f 73 74 20 63  e for the host c
377a0 6f 6d 70 75 74 65 72 2e 0a 2a 2a 20 4e 65 77 20  omputer..** New 
377b0 56 46 53 65 73 20 63 61 6e 20 62 65 20 72 65 67  VFSes can be reg
377c0 69 73 74 65 72 65 64 20 61 6e 64 20 65 78 69 73  istered and exis
377d0 74 69 6e 67 20 56 46 53 65 73 20 63 61 6e 20 62  ting VFSes can b
377e0 65 20 75 6e 72 65 67 69 73 74 65 72 65 64 2e 0a  e unregistered..
377f0 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  ** The following
37800 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
37810 70 72 6f 76 69 64 65 64 2e 0a 2a 2a 0a 2a 2a 20  provided..**.** 
37820 54 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 5f  The sqlite3_vfs_
37830 66 69 6e 64 28 29 20 69 6e 74 65 72 66 61 63 65  find() interface
37840 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
37850 65 72 20 74 6f 20 0a 2a 2a 20 61 20 56 46 53 20  er to .** a VFS 
37860 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20  given its name. 
37870 20 4e 61 6d 65 73 20 61 72 65 20 63 61 73 65 20   Names are case 
37880 73 65 6e 73 69 74 69 76 65 2e 0a 2a 2a 20 4e 61  sensitive..** Na
37890 6d 65 73 20 61 72 65 20 7a 65 72 6f 2d 74 65 72  mes are zero-ter
378a0 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74  minated UTF-8 st
378b0 72 69 6e 67 73 2e 0a 2a 2a 20 49 66 20 74 68 65  rings..** If the
378c0 72 65 20 69 73 20 6e 6f 20 6d 61 74 63 68 2c 20  re is no match, 
378d0 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65  a NULL.** pointe
378e0 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  r is returned.  
378f0 49 66 20 7a 56 66 73 4e 61 6d 65 20 69 73 20 4e  If zVfsName is N
37900 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 64 65 66  ULL then the def
37910 61 75 6c 74 20 0a 2a 2a 20 56 46 53 20 69 73 20  ault .** VFS is 
37920 72 65 74 75 72 6e 65 64 2e 20 0a 2a 2a 0a 2a 2a  returned. .**.**
37930 20 4e 65 77 20 56 46 53 65 73 20 61 72 65 20 72   New VFSes are r
37940 65 67 69 73 74 65 72 65 64 20 77 69 74 68 20 73  egistered with s
37950 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73  qlite3_vfs_regis
37960 74 65 72 28 29 2e 0a 2a 2a 20 45 61 63 68 20 6e  ter()..** Each n
37970 65 77 20 56 46 53 20 62 65 63 6f 6d 65 73 20 74  ew VFS becomes t
37980 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 69  he default VFS i
37990 66 20 74 68 65 20 6d 61 6b 65 44 66 6c 74 20 66  f the makeDflt f
379a0 6c 61 67 20 69 73 20 73 65 74 2e 0a 2a 2a 20 54  lag is set..** T
379b0 68 65 20 73 61 6d 65 20 56 46 53 20 63 61 6e 20  he same VFS can 
379c0 62 65 20 72 65 67 69 73 74 65 72 65 64 20 6d 75  be registered mu
379d0 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 77 69 74  ltiple times wit
379e0 68 6f 75 74 20 69 6e 6a 75 72 79 2e 0a 2a 2a 20  hout injury..** 
379f0 54 6f 20 6d 61 6b 65 20 61 6e 20 65 78 69 73 74  To make an exist
37a00 69 6e 67 20 56 46 53 20 69 6e 74 6f 20 74 68 65  ing VFS into the
37a10 20 64 65 66 61 75 6c 74 20 56 46 53 2c 20 72 65   default VFS, re
37a20 67 69 73 74 65 72 20 69 74 20 61 67 61 69 6e 0a  gister it again.
37a30 2a 2a 20 77 69 74 68 20 74 68 65 20 6d 61 6b 65  ** with the make
37a40 44 66 6c 74 20 66 6c 61 67 20 73 65 74 2e 20 20  Dflt flag set.  
37a50 49 66 20 74 77 6f 20 64 69 66 66 65 72 65 6e 74  If two different
37a60 20 56 46 53 65 73 20 77 69 74 68 20 74 68 65 0a   VFSes with the.
37a70 2a 2a 20 73 61 6d 65 20 6e 61 6d 65 20 61 72 65  ** same name are
37a80 20 72 65 67 69 73 74 65 72 65 64 2c 20 74 68 65   registered, the
37a90 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
37aa0 65 66 69 6e 65 64 2e 20 20 49 66 20 61 0a 2a 2a  efined.  If a.**
37ab0 20 56 46 53 20 69 73 20 72 65 67 69 73 74 65 72   VFS is register
37ac0 65 64 20 77 69 74 68 20 61 20 6e 61 6d 65 20 74  ed with a name t
37ad0 68 61 74 20 69 73 20 4e 55 4c 4c 20 6f 72 20 61  hat is NULL or a
37ae0 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 0a  n empty string,.
37af0 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  ** then the beha
37b00 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
37b10 64 2e 0a 2a 2a 20 0a 2a 2a 20 55 6e 72 65 67 69  d..** .** Unregi
37b20 73 74 65 72 20 61 20 56 46 53 20 77 69 74 68 20  ster a VFS with 
37b30 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 5f  the sqlite3_vfs_
37b40 75 6e 72 65 67 69 73 74 65 72 28 29 20 69 6e 74  unregister() int
37b50 65 72 66 61 63 65 2e 0a 2a 2a 20 49 66 20 74 68  erface..** If th
37b60 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 69 73  e default VFS is
37b70 20 75 6e 72 65 67 69 73 74 65 72 65 64 2c 20 61   unregistered, a
37b80 6e 6f 74 68 65 72 20 56 46 53 20 69 73 20 63 68  nother VFS is ch
37b90 6f 73 65 6e 20 61 73 0a 2a 2a 20 74 68 65 20 64  osen as.** the d
37ba0 65 66 61 75 6c 74 2e 20 20 54 68 65 20 63 68 6f  efault.  The cho
37bb0 69 63 65 20 66 6f 72 20 74 68 65 20 6e 65 77 20  ice for the new 
37bc0 56 46 53 20 69 73 20 61 72 62 69 74 72 61 72 79  VFS is arbitrary
37bd0 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
37be0 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 32 30  TS:.**.** {F1120
37bf0 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  3} The [sqlite3_
37c00 76 66 73 5f 66 69 6e 64 28 4e 29 5d 20 69 6e 74  vfs_find(N)] int
37c10 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
37c20 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a   pointer to the.
37c30 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 67 69  **          regi
37c40 73 74 65 72 65 64 20 5b 73 71 6c 69 74 65 33 5f  stered [sqlite3_
37c50 76 66 73 5d 20 6f 62 6a 65 63 74 20 77 68 6f 73  vfs] object whos
37c60 65 20 6e 61 6d 65 20 65 78 61 63 74 6c 79 20 6d  e name exactly m
37c70 61 74 63 68 65 73 0a 2a 2a 20 20 20 20 20 20 20  atches.**       
37c80 20 20 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d     the zero-term
37c90 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72  inated UTF-8 str
37ca0 69 6e 67 20 4e 2c 20 6f 72 20 69 74 20 72 65 74  ing N, or it ret
37cb0 75 72 6e 73 20 4e 55 4c 4c 20 69 66 0a 2a 2a 20  urns NULL if.** 
37cc0 20 20 20 20 20 20 20 20 20 74 68 65 72 65 20 69           there i
37cd0 73 20 6e 6f 20 6d 61 74 63 68 2e 0a 2a 2a 0a 2a  s no match..**.*
37ce0 2a 20 7b 46 31 31 32 30 36 7d 20 49 66 20 74 68  * {F11206} If th
37cf0 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 74 6f  e N parameter to
37d00 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69   [sqlite3_vfs_fi
37d10 6e 64 28 4e 29 5d 20 69 73 20 4e 55 4c 4c 20 74  nd(N)] is NULL t
37d20 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  hen.**          
37d30 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  the function ret
37d40 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
37d50 6f 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73  o the default [s
37d60 71 6c 69 74 65 33 5f 76 66 73 5d 0a 2a 2a 20 20  qlite3_vfs].**  
37d70 20 20 20 20 20 20 20 20 6f 62 6a 65 63 74 20 69          object i
37d80 66 20 74 68 65 72 65 20 69 73 20 6f 6e 65 2c 20  f there is one, 
37d90 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 72 65  or NULL if there
37da0 20 69 73 20 6e 6f 20 64 65 66 61 75 6c 74 20 0a   is no default .
37db0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
37dc0 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
37dd0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 32 30 39 7d  ..**.** {F11209}
37de0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   The [sqlite3_vf
37df0 73 5f 72 65 67 69 73 74 65 72 28 50 2c 46 29 5d  s_register(P,F)]
37e00 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73   interface regis
37e10 74 65 72 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  ters the.**     
37e20 20 20 20 20 20 77 65 6c 6c 2d 66 6f 72 6d 65 64       well-formed
37e30 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
37e40 62 6a 65 63 74 20 50 20 75 73 69 6e 67 20 74 68  bject P using th
37e50 65 20 6e 61 6d 65 20 67 69 76 65 6e 0a 2a 2a 20  e name given.** 
37e60 20 20 20 20 20 20 20 20 20 62 79 20 74 68 65 20           by the 
37e70 7a 4e 61 6d 65 20 66 69 65 6c 64 20 6f 66 20 74  zName field of t
37e80 68 65 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a  he object..**.**
37e90 20 7b 46 31 31 32 31 32 7d 20 55 73 69 6e 67 20   {F11212} Using 
37ea0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
37eb0 5f 72 65 67 69 73 74 65 72 28 50 2c 46 29 5d 20  _register(P,F)] 
37ec0 69 6e 74 65 72 66 61 63 65 20 74 6f 20 72 65 67  interface to reg
37ed0 69 73 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  ister.**        
37ee0 20 20 74 68 65 20 73 61 6d 65 20 5b 73 71 6c 69    the same [sqli
37ef0 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20  te3_vfs] object 
37f00 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 69  multiple times i
37f10 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d  s a harmless no-
37f20 6f 70 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 32 31  op..**.** {F1121
37f30 35 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  5} The [sqlite3_
37f40 76 66 73 5f 72 65 67 69 73 74 65 72 28 50 2c 46  vfs_register(P,F
37f50 29 5d 20 69 6e 74 65 72 66 61 63 65 20 6d 61 6b  )] interface mak
37f60 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  es the.**       
37f70 20 20 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f     the [sqlite3_
37f80 76 66 73 5d 20 6f 62 6a 65 63 74 20 50 20 74 68  vfs] object P th
37f90 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  e default [sqlit
37fa0 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 0a 2a  e3_vfs] object.*
37fb0 2a 20 20 20 20 20 20 20 20 20 20 69 66 20 46 20  *          if F 
37fc0 69 73 20 6e 6f 6e 2d 7a 65 72 6f 2e 0a 2a 2a 0a  is non-zero..**.
37fd0 2a 2a 20 7b 46 31 31 32 31 38 7d 20 54 68 65 20  ** {F11218} The 
37fe0 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72  [sqlite3_vfs_unr
37ff0 65 67 69 73 74 65 72 28 50 29 5d 20 69 6e 74 65  egister(P)] inte
38000 72 66 61 63 65 20 75 6e 72 65 67 69 73 74 65 72  rface unregister
38010 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
38020 20 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20    [sqlite3_vfs] 
38030 6f 62 6a 65 63 74 20 50 20 73 6f 20 74 68 61 74  object P so that
38040 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72   it is no longer
38050 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
38060 20 20 20 20 20 20 20 20 20 73 75 62 73 65 71 75           subsequ
38070 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  ent calls to [sq
38080 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29  lite3_vfs_find()
38090 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 76 66  ]..*/.sqlite3_vf
380a0 73 20 2a 73 71 6c 69 74 65 33 5f 76 66 73 5f 66  s *sqlite3_vfs_f
380b0 69 6e 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a  ind(const char *
380c0 7a 56 66 73 4e 61 6d 65 29 3b 0a 69 6e 74 20 73  zVfsName);.int s
380d0 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73  qlite3_vfs_regis
380e0 74 65 72 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ter(sqlite3_vfs*
380f0 2c 20 69 6e 74 20 6d 61 6b 65 44 66 6c 74 29 3b  , int makeDflt);
38100 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 66 73  .int sqlite3_vfs
38110 5f 75 6e 72 65 67 69 73 74 65 72 28 73 71 6c 69  _unregister(sqli
38120 74 65 33 5f 76 66 73 2a 29 3b 0a 0a 2f 2a 0a 2a  te3_vfs*);../*.*
38130 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65  * CAPI3REF: Mute
38140 78 65 73 20 7b 46 31 37 30 30 30 7d 0a 2a 2a 0a  xes {F17000}.**.
38150 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  ** The SQLite co
38160 72 65 20 75 73 65 73 20 74 68 65 73 65 20 72 6f  re uses these ro
38170 75 74 69 6e 65 73 20 66 6f 72 20 74 68 72 65 61  utines for threa
38180 64 0a 2a 2a 20 73 79 6e 63 68 72 6f 6e 69 7a 61  d.** synchroniza
38190 74 69 6f 6e 2e 20 20 54 68 6f 75 67 68 20 74 68  tion.  Though th
381a0 65 79 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20  ey are intended 
381b0 66 6f 72 20 69 6e 74 65 72 6e 61 6c 0a 2a 2a 20  for internal.** 
381c0 75 73 65 20 62 79 20 53 51 4c 69 74 65 2c 20 63  use by SQLite, c
381d0 6f 64 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61  ode that links a
381e0 67 61 69 6e 73 74 20 53 51 4c 69 74 65 20 69 73  gainst SQLite is
381f0 0a 2a 2a 20 70 65 72 6d 69 74 74 65 64 20 74 6f  .** permitted to
38200 20 75 73 65 20 61 6e 79 20 6f 66 20 74 68 65 73   use any of thes
38210 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  e routines..**.*
38220 2a 20 54 68 65 20 53 51 4c 69 74 65 20 73 6f 75  * The SQLite sou
38230 72 63 65 20 63 6f 64 65 20 63 6f 6e 74 61 69 6e  rce code contain
38240 73 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65  s multiple imple
38250 6d 65 6e 74 61 74 69 6f 6e 73 20 0a 2a 2a 20 6f  mentations .** o
38260 66 20 74 68 65 73 65 20 6d 75 74 65 78 20 72 6f  f these mutex ro
38270 75 74 69 6e 65 73 2e 20 20 41 6e 20 61 70 70 72  utines.  An appr
38280 6f 70 72 69 61 74 65 20 69 6d 70 6c 65 6d 65 6e  opriate implemen
38290 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 73 65 6c  tation.** is sel
382a0 65 63 74 65 64 20 61 75 74 6f 6d 61 74 69 63 61  ected automatica
382b0 6c 6c 79 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74  lly at compile-t
382c0 69 6d 65 2e 20 20 54 68 65 20 66 6f 6c 6c 6f 77  ime.  The follow
382d0 69 6e 67 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  ing.** implement
382e0 61 74 69 6f 6e 73 20 61 72 65 20 61 76 61 69 6c  ations are avail
382f0 61 62 6c 65 20 69 6e 20 74 68 65 20 53 51 4c 69  able in the SQLi
38300 74 65 20 63 6f 72 65 3a 0a 2a 2a 0a 2a 2a 20 3c  te core:.**.** <
38310 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51  ul>.** <li>   SQ
38320 4c 49 54 45 5f 4d 55 54 45 58 5f 4f 53 32 0a 2a  LITE_MUTEX_OS2.*
38330 2a 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f  * <li>   SQLITE_
38340 4d 55 54 45 58 5f 50 54 48 52 45 41 44 0a 2a 2a  MUTEX_PTHREAD.**
38350 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d   <li>   SQLITE_M
38360 55 54 45 58 5f 57 33 32 0a 2a 2a 20 3c 6c 69 3e  UTEX_W32.** <li>
38370 20 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f     SQLITE_MUTEX_
38380 4e 4f 4f 50 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  NOOP.** </ul>.**
38390 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 4d  .** The SQLITE_M
383a0 55 54 45 58 5f 4e 4f 4f 50 20 69 6d 70 6c 65 6d  UTEX_NOOP implem
383b0 65 6e 74 61 74 69 6f 6e 20 69 73 20 61 20 73 65  entation is a se
383c0 74 20 6f 66 20 72 6f 75 74 69 6e 65 73 20 0a 2a  t of routines .*
383d0 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 20 72  * that does no r
383e0 65 61 6c 20 6c 6f 63 6b 69 6e 67 20 61 6e 64 20  eal locking and 
383f0 69 73 20 61 70 70 72 6f 70 72 69 61 74 65 20 66  is appropriate f
38400 6f 72 20 75 73 65 20 69 6e 20 0a 2a 2a 20 61 20  or use in .** a 
38410 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 20  single-threaded 
38420 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68  application.  Th
38430 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4f  e SQLITE_MUTEX_O
38440 53 32 2c 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 55  S2,.** SQLITE_MU
38450 54 45 58 5f 50 54 48 52 45 41 44 2c 20 61 6e 64  TEX_PTHREAD, and
38460 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 57 33   SQLITE_MUTEX_W3
38470 32 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  2 implementation
38480 73 0a 2a 2a 20 61 72 65 20 61 70 70 72 6f 70 72  s.** are appropr
38490 69 61 74 65 20 66 6f 72 20 75 73 65 20 6f 6e 20  iate for use on 
384a0 6f 73 2f 32 2c 20 75 6e 69 78 2c 20 61 6e 64 20  os/2, unix, and 
384b0 77 69 6e 64 6f 77 73 2e 0a 2a 2a 20 0a 2a 2a 20  windows..** .** 
384c0 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
384d0 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 20 53  piled with the S
384e0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 41 50 50 44  QLITE_MUTEX_APPD
384f0 45 46 20 70 72 65 70 72 6f 63 65 73 73 6f 72 0a  EF preprocessor.
38500 2a 2a 20 6d 61 63 72 6f 20 64 65 66 69 6e 65 64  ** macro defined
38510 20 28 77 69 74 68 20 22 2d 44 53 51 4c 49 54 45   (with "-DSQLITE
38520 5f 4d 55 54 45 58 5f 41 50 50 44 45 46 3d 31 22  _MUTEX_APPDEF=1"
38530 29 2c 20 74 68 65 6e 20 6e 6f 20 6d 75 74 65 78  ), then no mutex
38540 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
38550 6f 6e 20 69 73 20 69 6e 63 6c 75 64 65 64 20 77  on is included w
38560 69 74 68 20 74 68 65 20 6c 69 62 72 61 72 79 2e  ith the library.
38570 20 20 54 68 65 0a 2a 2a 20 6d 75 74 65 78 20 69    The.** mutex i
38580 6e 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65  nterface routine
38590 73 20 64 65 66 69 6e 65 64 20 68 65 72 65 20 62  s defined here b
385a0 65 63 6f 6d 65 20 65 78 74 65 72 6e 61 6c 0a 2a  ecome external.*
385b0 2a 20 72 65 66 65 72 65 6e 63 65 73 20 69 6e 20  * references in 
385c0 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61  the SQLite libra
385d0 72 79 20 66 6f 72 20 77 68 69 63 68 20 69 6d 70  ry for which imp
385e0 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20  lementations.** 
385f0 6d 75 73 74 20 62 65 20 70 72 6f 76 69 64 65 64  must be provided
38600 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74   by the applicat
38610 69 6f 6e 2e 20 20 54 68 69 73 20 66 61 63 69 6c  ion.  This facil
38620 69 74 79 20 61 6c 6c 6f 77 73 20 61 6e 0a 2a 2a  ity allows an.**
38630 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 68 61   application tha
38640 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20  t links against 
38650 53 51 4c 69 74 65 20 74 6f 20 70 72 6f 76 69 64  SQLite to provid
38660 65 20 69 74 73 20 6f 77 6e 20 6d 75 74 65 78 0a  e its own mutex.
38670 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
38680 6e 20 77 69 74 68 6f 75 74 20 68 61 76 69 6e 67  n without having
38690 20 74 6f 20 6d 6f 64 69 66 79 20 74 68 65 20 53   to modify the S
386a0 51 4c 69 74 65 20 63 6f 72 65 2e 0a 2a 2a 0a 2a  QLite core..**.*
386b0 2a 20 7b 46 31 37 30 31 31 7d 20 54 68 65 20 73  * {F17011} The s
386c0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c  qlite3_mutex_all
386d0 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 61 6c 6c  oc() routine all
386e0 6f 63 61 74 65 73 20 61 20 6e 65 77 0a 2a 2a 20  ocates a new.** 
386f0 6d 75 74 65 78 20 61 6e 64 20 72 65 74 75 72 6e  mutex and return
38700 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69  s a pointer to i
38710 74 2e 20 7b 46 31 37 30 31 32 7d 20 49 66 20 69  t. {F17012} If i
38720 74 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 0a 2a  t returns NULL.*
38730 2a 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 61  * that means tha
38740 74 20 61 20 6d 75 74 65 78 20 63 6f 75 6c 64 20  t a mutex could 
38750 6e 6f 74 20 62 65 20 61 6c 6c 6f 63 61 74 65 64  not be allocated
38760 2e 20 7b 46 31 37 30 31 33 7d 20 53 51 4c 69 74  . {F17013} SQLit
38770 65 0a 2a 2a 20 77 69 6c 6c 20 75 6e 77 69 6e 64  e.** will unwind
38780 20 69 74 73 20 73 74 61 63 6b 20 61 6e 64 20 72   its stack and r
38790 65 74 75 72 6e 20 61 6e 20 65 72 72 6f 72 2e 20  eturn an error. 
387a0 7b 46 31 37 30 31 34 7d 20 54 68 65 20 61 72 67  {F17014} The arg
387b0 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69  ument.** to sqli
387c0 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28  te3_mutex_alloc(
387d0 29 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 73  ) is one of thes
387e0 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61  e integer consta
387f0 6e 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  nts:.**.** <ul>.
38800 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
38810 4d 55 54 45 58 5f 46 41 53 54 0a 2a 2a 20 3c 6c  MUTEX_FAST.** <l
38820 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  i>  SQLITE_MUTEX
38830 5f 52 45 43 55 52 53 49 56 45 0a 2a 2a 20 3c 6c  _RECURSIVE.** <l
38840 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  i>  SQLITE_MUTEX
38850 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 52 0a 2a  _STATIC_MASTER.*
38860 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d  * <li>  SQLITE_M
38870 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 0a  UTEX_STATIC_MEM.
38880 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
38890 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d  MUTEX_STATIC_MEM
388a0 32 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  2.** <li>  SQLIT
388b0 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 50  E_MUTEX_STATIC_P
388c0 52 4e 47 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  RNG.** <li>  SQL
388d0 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43  ITE_MUTEX_STATIC
388e0 5f 4c 52 55 0a 2a 2a 20 3c 2f 75 6c 3e 20 7b 45  _LRU.** </ul> {E
388f0 4e 44 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 30 31  ND}.**.** {F1701
38900 35 7d 20 54 68 65 20 66 69 72 73 74 20 74 77 6f  5} The first two
38910 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 75 73 65   constants cause
38920 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61   sqlite3_mutex_a
38930 6c 6c 6f 63 28 29 20 74 6f 20 63 72 65 61 74 65  lloc() to create
38940 0a 2a 2a 20 61 20 6e 65 77 20 6d 75 74 65 78 2e  .** a new mutex.
38950 20 20 54 68 65 20 6e 65 77 20 6d 75 74 65 78 20    The new mutex 
38960 69 73 20 72 65 63 75 72 73 69 76 65 20 77 68 65  is recursive whe
38970 6e 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52  n SQLITE_MUTEX_R
38980 45 43 55 52 53 49 56 45 0a 2a 2a 20 69 73 20 75  ECURSIVE.** is u
38990 73 65 64 20 62 75 74 20 6e 6f 74 20 6e 65 63 65  sed but not nece
389a0 73 73 61 72 69 6c 79 20 73 6f 20 77 68 65 6e 20  ssarily so when 
389b0 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53  SQLITE_MUTEX_FAS
389c0 54 20 69 73 20 75 73 65 64 2e 20 7b 45 4e 44 7d  T is used. {END}
389d0 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 69 6d  .** The mutex im
389e0 70 6c 65 6d 65 6e 74 61 74 69