/ Hex Artifact Content
Login

Artifact bf986db272eebf11be5c2d49b187a0f9562e2ee4:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 20 0a 2a 2a 20 74 6f  e changes .** to
0390: 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e   experimental in
03a0: 74 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73  terfaces but res
03b0: 65 72 76 65 20 74 6f 20 6d 61 6b 65 20 6d 69 6e  erve to make min
03c0: 6f 72 20 63 68 61 6e 67 65 73 20 69 66 0a 2a 2a  or changes if.**
03d0: 20 65 78 70 65 72 69 65 6e 63 65 20 66 72 6f 6d   experience from
03e0: 20 75 73 65 20 22 69 6e 20 74 68 65 20 77 69 6c   use "in the wil
03f0: 64 22 20 73 75 67 67 65 73 74 20 73 75 63 68 20  d" suggest such 
0400: 63 68 61 6e 67 65 73 20 61 72 65 20 70 72 75 64  changes are prud
0410: 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f  ent..**.** The o
0420: 66 66 69 63 69 61 6c 20 43 2d 6c 61 6e 67 75 61  fficial C-langua
0430: 67 65 20 41 50 49 20 64 6f 63 75 6d 65 6e 74 61  ge API documenta
0440: 74 69 6f 6e 20 66 6f 72 20 53 51 4c 69 74 65 20  tion for SQLite 
0450: 69 73 20 64 65 72 69 76 65 64 0a 2a 2a 20 66 72  is derived.** fr
0460: 6f 6d 20 63 6f 6d 6d 65 6e 74 73 20 69 6e 20 74  om comments in t
0470: 68 69 73 20 66 69 6c 65 2e 20 20 54 68 69 73 20  his file.  This 
0480: 66 69 6c 65 20 69 73 20 74 68 65 20 61 75 74 68  file is the auth
0490: 6f 72 69 74 61 74 69 76 65 20 73 6f 75 72 63 65  oritative source
04a0: 0a 2a 2a 20 6f 6e 20 68 6f 77 20 53 51 4c 69 74  .** on how SQLit
04b0: 65 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  e interfaces are
04c0: 20 73 75 70 70 6f 73 65 20 74 6f 20 6f 70 65 72   suppose to oper
04d0: 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e  ate..**.** The n
04e0: 61 6d 65 20 6f 66 20 74 68 69 73 20 66 69 6c 65  ame of this file
04f0: 20 75 6e 64 65 72 20 63 6f 6e 66 69 67 75 72 61   under configura
0500: 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 20  tion management 
0510: 69 73 20 22 73 71 6c 69 74 65 2e 68 2e 69 6e 22  is "sqlite.h.in"
0520: 2e 0a 2a 2a 20 54 68 65 20 6d 61 6b 65 66 69 6c  ..** The makefil
0530: 65 20 6d 61 6b 65 73 20 73 6f 6d 65 20 6d 69 6e  e makes some min
0540: 6f 72 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  or changes to th
0550: 69 73 20 66 69 6c 65 20 28 73 75 63 68 20 61 73  is file (such as
0560: 20 69 6e 73 65 72 74 69 6e 67 0a 2a 2a 20 74 68   inserting.** th
0570: 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72  e version number
0580: 29 20 61 6e 64 20 63 68 61 6e 67 65 73 20 69 74  ) and changes it
0590: 73 20 6e 61 6d 65 20 74 6f 20 22 73 71 6c 69 74  s name to "sqlit
05a0: 65 33 2e 68 22 20 61 73 0a 2a 2a 20 70 61 72 74  e3.h" as.** part
05b0: 20 6f 66 20 74 68 65 20 62 75 69 6c 64 20 70 72   of the build pr
05c0: 6f 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 40 28 23  ocess..**.** @(#
05d0: 29 20 24 49 64 3a 20 73 71 6c 69 74 65 2e 68 2e  ) $Id: sqlite.h.
05e0: 69 6e 2c 76 20 31 2e 33 31 31 20 32 30 30 38 2f  in,v 1.311 2008/
05f0: 30 35 2f 31 31 20 31 31 3a 30 37 3a 30 37 20 64  05/11 11:07:07 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 69 73 20 66 61 6c 73 65 2c 0a  macro is 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 20 7b 64 61 74 61 62 61 73  ection} {databas
16d0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d 0a 2a  e connections}.*
16e0: 2a 0a 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20 53  *.** Each open S
16f0: 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 69  QLite database i
1700: 73 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79  s represented by
1710: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
1720: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 0a 2a  nstance of the.*
1730: 2a 20 6f 70 61 71 75 65 20 73 74 72 75 63 74 75  * opaque structu
1740: 72 65 20 6e 61 6d 65 64 20 22 73 71 6c 69 74 65  re named "sqlite
1750: 33 22 2e 20 20 49 74 20 69 73 20 75 73 65 66 75  3".  It is usefu
1760: 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61 6e  l to think of an
1770: 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69 6e   sqlite3.** poin
1780: 74 65 72 20 61 73 20 61 6e 20 6f 62 6a 65 63 74  ter as an object
1790: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
17a0: 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
17b0: 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64  3_open16()], and
17c0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  .** [sqlite3_ope
17d0: 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63  n_v2()] interfac
17e0: 65 73 20 61 72 65 20 69 74 73 20 63 6f 6e 73 74  es are its const
17f0: 72 75 63 74 6f 72 73 0a 2a 2a 20 61 6e 64 20 5b  ructors.** and [
1800: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d  sqlite3_close()]
1810: 20 69 73 20 69 74 73 20 64 65 73 74 72 75 63 74   is its destruct
1820: 6f 72 2e 20 20 54 68 65 72 65 20 61 72 65 20 6d  or.  There are m
1830: 61 6e 79 20 6f 74 68 65 72 20 69 6e 74 65 72 66  any other interf
1840: 61 63 65 73 0a 2a 2a 20 28 73 75 63 68 20 61 73  aces.** (such as
1850: 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1860: 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65  e_v2()], [sqlite
1870: 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
1880: 6e 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  n()], and.** [sq
1890: 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f  lite3_busy_timeo
18a0: 75 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75  ut()] to name bu
18b0: 74 20 74 68 72 65 65 29 20 74 68 61 74 20 61 72  t three) that ar
18c0: 65 20 6d 65 74 68 6f 64 73 20 6f 6e 20 74 68 69  e methods on thi
18d0: 73 0a 2a 2a 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a  s.** object..*/.
18e0: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
18f0: 71 6c 69 74 65 33 20 73 71 6c 69 74 65 33 3b 0a  qlite3 sqlite3;.
1900: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1910: 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67 65 72  : 64-Bit Integer
1920: 20 54 79 70 65 73 20 7b 46 31 30 32 30 30 7d 0a   Types {F10200}.
1930: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c  ** KEYWORDS: sql
1940: 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  ite_int64 sqlite
1950: 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a 20 42 65  _uint64.**.** Be
1960: 63 61 75 73 65 20 74 68 65 72 65 20 69 73 20 6e  cause there is n
1970: 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66 6f 72 6d  o cross-platform
1980: 20 77 61 79 20 74 6f 20 73 70 65 63 69 66 79 20   way to specify 
1990: 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 74  64-bit integer t
19a0: 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74 65 20 69  ypes.** SQLite i
19b0: 6e 63 6c 75 64 65 73 20 74 79 70 65 64 65 66 73  ncludes typedefs
19c0: 20 66 6f 72 20 36 34 2d 62 69 74 20 73 69 67 6e   for 64-bit sign
19d0: 65 64 20 61 6e 64 20 75 6e 73 69 67 6e 65 64 20  ed and unsigned 
19e0: 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  integers..**.** 
19f0: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  The sqlite3_int6
1a00: 34 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 75 69  4 and sqlite3_ui
1a10: 6e 74 36 34 20 61 72 65 20 74 68 65 20 70 72 65  nt64 are the pre
1a20: 66 65 72 72 65 64 20 74 79 70 65 0a 2a 2a 20 64  ferred type.** d
1a30: 65 66 69 6e 69 74 69 6f 6e 73 2e 20 20 54 68 65  efinitions.  The
1a40: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 61 6e   sqlite_int64 an
1a50: 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 20  d sqlite_uint64 
1a60: 74 79 70 65 73 20 61 72 65 0a 2a 2a 20 73 75 70  types are.** sup
1a70: 70 6f 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77  ported for backw
1a80: 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
1a90: 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 49  ty only..**.** I
1aa0: 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
1ab0: 20 7b 46 31 30 32 30 31 7d 20 54 68 65 20 5b 73   {F10201} The [s
1ac0: 71 6c 69 74 65 5f 69 6e 74 36 34 5d 20 61 6e 64  qlite_int64] and
1ad0: 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 5d   [sqlite3_int64]
1ae0: 20 74 79 70 65 73 20 73 70 65 63 69 66 79 20 61   types specify a
1af0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 36 34 2d  .**          64-
1b00: 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
1b10: 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 32 30  er..**.** {F1020
1b20: 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 5f 75  2} The [sqlite_u
1b30: 69 6e 74 36 34 5d 20 61 6e 64 20 5b 73 71 6c 69  int64] and [sqli
1b40: 74 65 33 5f 75 69 6e 74 36 34 5d 20 74 79 70 65  te3_uint64] type
1b50: 73 20 73 70 65 63 69 66 79 0a 2a 2a 20 20 20 20  s specify.**    
1b60: 20 20 20 20 20 20 61 20 36 34 2d 62 69 74 20 75        a 64-bit u
1b70: 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 2e  nsigned integer.
1b80: 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54  .*/.#ifdef SQLIT
1b90: 45 5f 49 4e 54 36 34 5f 54 59 50 45 0a 20 20 74  E_INT64_TYPE.  t
1ba0: 79 70 65 64 65 66 20 53 51 4c 49 54 45 5f 49 4e  ypedef SQLITE_IN
1bb0: 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74 65 5f  T64_TYPE sqlite_
1bc0: 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66  int64;.  typedef
1bd0: 20 75 6e 73 69 67 6e 65 64 20 53 51 4c 49 54 45   unsigned SQLITE
1be0: 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69  _INT64_TYPE sqli
1bf0: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 69 66  te_uint64;.#elif
1c00: 20 64 65 66 69 6e 65 64 28 5f 4d 53 43 5f 56 45   defined(_MSC_VE
1c10: 52 29 20 7c 7c 20 64 65 66 69 6e 65 64 28 5f 5f  R) || defined(__
1c20: 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a 20 20 74 79  BORLANDC__).  ty
1c30: 70 65 64 65 66 20 5f 5f 69 6e 74 36 34 20 73 71  pedef __int64 sq
1c40: 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79  lite_int64;.  ty
1c50: 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 5f  pedef unsigned _
1c60: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69  _int64 sqlite_ui
1c70: 6e 74 36 34 3b 0a 23 65 6c 73 65 0a 20 20 74 79  nt64;.#else.  ty
1c80: 70 65 64 65 66 20 6c 6f 6e 67 20 6c 6f 6e 67 20  pedef long long 
1c90: 69 6e 74 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  int sqlite_int64
1ca0: 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73 69  ;.  typedef unsi
1cb0: 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69  gned long long i
1cc0: 6e 74 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  nt sqlite_uint64
1cd0: 3b 0a 23 65 6e 64 69 66 0a 74 79 70 65 64 65 66  ;.#endif.typedef
1ce0: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71   sqlite_int64 sq
1cf0: 6c 69 74 65 33 5f 69 6e 74 36 34 3b 0a 74 79 70  lite3_int64;.typ
1d00: 65 64 65 66 20 73 71 6c 69 74 65 5f 75 69 6e 74  edef sqlite_uint
1d10: 36 34 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  64 sqlite3_uint6
1d20: 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66 20 63 6f 6d  4;../*.** If com
1d30: 70 69 6c 69 6e 67 20 66 6f 72 20 61 20 70 72 6f  piling for a pro
1d40: 63 65 73 73 6f 72 20 74 68 61 74 20 6c 61 63 6b  cessor that lack
1d50: 73 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  s floating point
1d60: 20 73 75 70 70 6f 72 74 2c 0a 2a 2a 20 73 75 62   support,.** sub
1d70: 73 74 69 74 75 74 65 20 69 6e 74 65 67 65 72 20  stitute integer 
1d80: 66 6f 72 20 66 6c 6f 61 74 69 6e 67 2d 70 6f 69  for floating-poi
1d90: 6e 74 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c  nt.*/.#ifdef SQL
1da0: 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f 41 54 49 4e  ITE_OMIT_FLOATIN
1db0: 47 5f 50 4f 49 4e 54 0a 23 20 64 65 66 69 6e 65  G_POINT.# define
1dc0: 20 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f   double sqlite3_
1dd0: 69 6e 74 36 34 0a 23 65 6e 64 69 66 0a 0a 2f 2a  int64.#endif../*
1de0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6c  .** CAPI3REF: Cl
1df0: 6f 73 69 6e 67 20 41 20 44 61 74 61 62 61 73 65  osing A Database
1e00: 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 7b 46 31 32   Connection {F12
1e10: 30 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  010}.**.** This 
1e20: 72 6f 75 74 69 6e 65 20 69 73 20 74 68 65 20 64  routine is the d
1e30: 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74 68  estructor for th
1e40: 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  e [sqlite3] obje
1e50: 63 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 41 70 70 6c  ct.  .**.** Appl
1e60: 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ications should 
1e70: 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
1e80: 65 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c  e | finalize] al
1e90: 6c 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  l.** [prepared s
1ea0: 74 61 74 65 6d 65 6e 74 73 5d 20 61 6e 64 0a 2a  tatements] and.*
1eb0: 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  * [sqlite3_blob_
1ec0: 63 6c 6f 73 65 20 7c 20 63 6c 6f 73 65 5d 20 61  close | close] a
1ed0: 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  ll [sqlite3_blob
1ee0: 20 7c 20 42 4c 4f 42 73 5d 20 0a 2a 2a 20 61 73   | BLOBs] .** as
1ef0: 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
1f00: 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  e [sqlite3] obje
1f10: 63 74 20 70 72 69 6f 72 0a 2a 2a 20 74 6f 20 61  ct prior.** to a
1f20: 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 63 6c 6f  ttempting to clo
1f30: 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d  se the [sqlite3]
1f40: 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 3c   object..**.** <
1f50: 74 6f 64 6f 3e 57 68 61 74 20 68 61 70 70 65 6e  todo>What happen
1f60: 73 20 74 6f 20 70 65 6e 64 69 6e 67 20 74 72 61  s to pending tra
1f70: 6e 73 61 63 74 69 6f 6e 73 3f 20 20 41 72 65 20  nsactions?  Are 
1f80: 74 68 65 79 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62  they.** rolled b
1f90: 61 63 6b 2c 20 6f 72 20 61 62 61 6e 64 6f 6e 65  ack, or abandone
1fa0: 64 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20  d?</todo>.**.** 
1fb0: 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
1fc0: 2a 20 7b 46 31 32 30 31 31 7d 20 54 68 65 20 5b  * {F12011} The [
1fd0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d  sqlite3_close()]
1fe0: 20 69 6e 74 65 72 66 61 63 65 20 64 65 73 74 72   interface destr
1ff0: 6f 79 73 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d  oys an [sqlite3]
2000: 20 6f 62 6a 65 63 74 0a 2a 2a 20 20 20 20 20 20   object.**      
2010: 20 20 20 20 61 6c 6c 6f 63 61 74 65 64 20 62 79      allocated by
2020: 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f   a prior call to
2030: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
2040: 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ],.**          [
2050: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
2060: 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f  ], or [sqlite3_o
2070: 70 65 6e 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a  pen_v2()]..**.**
2080: 20 7b 46 31 32 30 31 32 7d 20 54 68 65 20 5b 73   {F12012} The [s
2090: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20  qlite3_close()] 
20a0: 66 75 6e 63 74 69 6f 6e 20 72 65 6c 65 61 73 65  function release
20b0: 73 20 61 6c 6c 20 6d 65 6d 6f 72 79 20 75 73 65  s all memory use
20c0: 64 20 62 79 20 74 68 65 0a 2a 2a 20 20 20 20 20  d by the.**     
20d0: 20 20 20 20 20 63 6f 6e 6e 65 63 74 69 6f 6e 20       connection 
20e0: 61 6e 64 20 63 6c 6f 73 65 73 20 61 6c 6c 20 6f  and closes all o
20f0: 70 65 6e 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a  pen files..**.**
2100: 20 7b 46 31 32 30 31 33 7d 20 49 66 20 74 68 65   {F12013} If the
2110: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
2120: 74 69 6f 6e 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a  tion contains.**
2130: 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61            [prepa
2140: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20  red statements] 
2150: 74 68 61 74 20 68 61 76 65 20 6e 6f 74 20 62 65  that have not be
2160: 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  en.**          f
2170: 69 6e 61 6c 69 7a 65 64 20 62 79 20 5b 73 71 6c  inalized by [sql
2180: 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
2190: 2c 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f  , then [sqlite3_
21a0: 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 20 20 20 20  close()].**     
21b0: 20 20 20 20 20 72 65 74 75 72 6e 73 20 5b 53 51       returns [SQ
21c0: 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 20 6c  LITE_BUSY] and l
21d0: 65 61 76 65 73 20 74 68 65 20 63 6f 6e 6e 65 63  eaves the connec
21e0: 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2a 0a 2a 2a  tion open..**.**
21f0: 20 7b 46 31 32 30 31 34 7d 20 47 69 76 69 6e 67   {F12014} Giving
2200: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29   sqlite3_close()
2210: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
2220: 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f  is a harmless no
2230: 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49 54  -op..**.** LIMIT
2240: 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 55  ATIONS:.**.** {U
2250: 31 32 30 31 35 7d 20 54 68 65 20 70 61 72 61 6d  12015} The param
2260: 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
2270: 5f 63 6c 6f 73 65 28 29 5d 20 6d 75 73 74 20 62  _close()] must b
2280: 65 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f  e an [sqlite3] o
2290: 62 6a 65 63 74 0a 2a 2a 20 20 20 20 20 20 20 20  bject.**        
22a0: 20 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f    pointer previo
22b0: 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72  usly obtained fr
22c0: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  om [sqlite3_open
22d0: 28 29 5d 20 6f 72 20 74 68 65 20 0a 2a 2a 20 20  ()] or the .**  
22e0: 20 20 20 20 20 20 20 20 65 71 75 69 76 61 6c 65          equivale
22f0: 6e 74 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a  nt, or NULL..**.
2300: 2a 2a 20 7b 55 31 32 30 31 36 7d 20 54 68 65 20  ** {U12016} The 
2310: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
2320: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 6d  lite3_close()] m
2330: 75 73 74 20 6e 6f 74 20 68 61 76 65 20 62 65 65  ust not have bee
2340: 6e 20 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a 20  n previously.** 
2350: 20 20 20 20 20 20 20 20 20 63 6c 6f 73 65 64 2e           closed.
2360: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2370: 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 20 2a 29  close(sqlite3 *)
2380: 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79 70  ;../*.** The typ
2390: 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 63 6b  e for a callback
23a0: 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68   function..** Th
23b0: 69 73 20 69 73 20 6c 65 67 61 63 79 20 61 6e 64  is is legacy and
23c0: 20 64 65 70 72 65 63 61 74 65 64 2e 20 20 49 74   deprecated.  It
23d0: 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66 6f 72   is included for
23e0: 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20 63   historical.** c
23f0: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61 6e 64  ompatibility and
2400: 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e 74   is not document
2410: 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 69  ed..*/.typedef i
2420: 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63 61 6c  nt (*sqlite3_cal
2430: 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74  lback)(void*,int
2440: 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a 29  ,char**, char**)
2450: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2460: 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75 65 72  F: One-Step Quer
2470: 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e 74 65  y Execution Inte
2480: 72 66 61 63 65 20 7b 46 31 32 31 30 30 7d 0a 2a  rface {F12100}.*
2490: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
24a0: 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61 63  _exec() interfac
24b0: 65 20 69 73 20 61 20 63 6f 6e 76 65 6e 69 65 6e  e is a convenien
24c0: 74 20 77 61 79 20 6f 66 20 72 75 6e 6e 69 6e 67  t way of running
24d0: 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  .** one or more 
24e0: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 77  SQL statements w
24f0: 69 74 68 6f 75 74 20 61 20 6c 6f 74 20 6f 66 20  ithout a lot of 
2500: 43 20 63 6f 64 65 2e 20 20 54 68 65 0a 2a 2a 20  C code.  The.** 
2510: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61  SQL statements a
2520: 72 65 20 70 61 73 73 65 64 20 69 6e 20 61 73 20  re passed in as 
2530: 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
2540: 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  eter to.** sqlit
2550: 65 33 5f 65 78 65 63 28 29 2e 20 20 54 68 65 20  e3_exec().  The 
2560: 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 65  statements are e
2570: 76 61 6c 75 61 74 65 64 20 6f 6e 65 20 62 79 20  valuated one by 
2580: 6f 6e 65 0a 2a 2a 20 75 6e 74 69 6c 20 65 69 74  one.** until eit
2590: 68 65 72 20 61 6e 20 65 72 72 6f 72 20 6f 72 20  her an error or 
25a0: 61 6e 20 69 6e 74 65 72 72 75 70 74 20 69 73 20  an interrupt is 
25b0: 65 6e 63 6f 75 6e 74 65 72 65 64 20 6f 72 0a 2a  encountered or.*
25c0: 2a 20 75 6e 74 69 6c 20 74 68 65 79 20 61 72 65  * until they are
25d0: 20 61 6c 6c 20 64 6f 6e 65 2e 20 20 54 68 65 20   all done.  The 
25e0: 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  3rd parameter is
25f0: 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 0a 2a 2a 20   an optional.** 
2600: 63 61 6c 6c 62 61 63 6b 20 74 68 61 74 20 69 73  callback that is
2610: 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 65 20 66 6f   invoked once fo
2620: 72 20 65 61 63 68 20 72 6f 77 20 6f 66 20 61 6e  r each row of an
2630: 79 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 0a  y query results.
2640: 2a 2a 20 70 72 6f 64 75 63 65 64 20 62 79 20 74  ** produced by t
2650: 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
2660: 73 2e 20 20 54 68 65 20 35 74 68 20 70 61 72 61  s.  The 5th para
2670: 6d 65 74 65 72 20 74 65 6c 6c 73 20 77 68 65 72  meter tells wher
2680: 65 0a 2a 2a 20 74 6f 20 77 72 69 74 65 20 61 6e  e.** to write an
2690: 79 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 73  y error messages
26a0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
26b0: 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72  te3_exec() inter
26c0: 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e  face is implemen
26d0: 74 65 64 20 69 6e 20 74 65 72 6d 73 20 6f 66 0a  ted in terms of.
26e0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
26f0: 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69  are_v2()], [sqli
2700: 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64  te3_step()], and
2710: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2720: 7a 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 71  ze()]..** The sq
2730: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 72 6f 75  lite3_exec() rou
2740: 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 68 69 6e  tine does nothin
2750: 67 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65  g that cannot be
2760: 20 64 6f 6e 65 0a 2a 2a 20 62 79 20 5b 73 71 6c   done.** by [sql
2770: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2780: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  )], [sqlite3_ste
2790: 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  p()], and [sqlit
27a0: 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a  e3_finalize()]..
27b0: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65  ** The sqlite3_e
27c0: 78 65 63 28 29 20 69 73 20 6a 75 73 74 20 61 20  xec() is just a 
27d0: 63 6f 6e 76 65 6e 69 65 6e 74 20 77 72 61 70 70  convenient wrapp
27e0: 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  er..**.** INVARI
27f0: 41 4e 54 53 3a 0a 2a 2a 20 0a 2a 2a 20 7b 46 31  ANTS:.** .** {F1
2800: 32 31 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  2101} The [sqlit
2810: 65 33 5f 65 78 65 63 28 29 5d 20 69 6e 74 65 72  e3_exec()] inter
2820: 66 61 63 65 20 65 76 61 6c 75 61 74 65 73 20 7a  face evaluates z
2830: 65 72 6f 20 6f 72 20 6d 6f 72 65 20 55 54 46 2d  ero or more UTF-
2840: 38 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 6e  8.**          en
2850: 63 6f 64 65 64 2c 20 73 65 6d 69 63 6f 6c 6f 6e  coded, semicolon
2860: 2d 73 65 70 61 72 61 74 65 64 2c 20 53 51 4c 20  -separated, SQL 
2870: 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68  statements in th
2880: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65  e.**          ze
2890: 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74  ro-terminated st
28a0: 72 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 20  ring of its 2nd 
28b0: 70 61 72 61 6d 65 74 65 72 20 77 69 74 68 69 6e  parameter within
28c0: 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
28d0: 20 63 6f 6e 74 65 78 74 20 6f 66 20 74 68 65 20   context of the 
28e0: 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
28f0: 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 31 73   given in the 1s
2900: 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  t parameter..**.
2910: 2a 2a 20 7b 46 31 32 31 30 34 7d 20 54 68 65 20  ** {F12104} The 
2920: 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
2930: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
2940: 20 69 73 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66   is SQLITE_OK if
2950: 20 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20   all.**         
2960: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
2970: 72 75 6e 20 73 75 63 63 65 73 73 66 75 6c 6c 79  run successfully
2980: 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31 30 35 7d  ..**.** {F12105}
2990: 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   The return valu
29a0: 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 65 78  e of [sqlite3_ex
29b0: 65 63 28 29 5d 20 69 73 20 61 6e 20 61 70 70 72  ec()] is an appr
29c0: 6f 70 72 69 61 74 65 20 0a 2a 2a 20 20 20 20 20  opriate .**     
29d0: 20 20 20 20 20 6e 6f 6e 2d 7a 65 72 6f 20 65 72       non-zero er
29e0: 72 6f 72 20 63 6f 64 65 20 69 66 20 61 6e 79 20  ror code if any 
29f0: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 61  SQL statement fa
2a00: 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31  ils..**.** {F121
2a10: 30 37 7d 20 49 66 20 6f 6e 65 20 6f 72 20 6d 6f  07} If one or mo
2a20: 72 65 20 6f 66 20 74 68 65 20 53 51 4c 20 73 74  re of the SQL st
2a30: 61 74 65 6d 65 6e 74 73 20 68 61 6e 64 65 64 20  atements handed 
2a40: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  to [sqlite3_exec
2a50: 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ()].**          
2a60: 72 65 74 75 72 6e 20 72 65 73 75 6c 74 73 20 61  return results a
2a70: 6e 64 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  nd the 3rd param
2a80: 65 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  eter is not NULL
2a90: 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20  , then.**       
2aa0: 20 20 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20     the callback 
2ab0: 66 75 6e 63 74 69 6f 6e 20 73 70 65 63 69 66 69  function specifi
2ac0: 65 64 20 62 79 20 74 68 65 20 33 72 64 20 70 61  ed by the 3rd pa
2ad0: 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 20 20  rameter is.**   
2ae0: 20 20 20 20 20 20 20 69 6e 76 6f 6b 65 64 20 6f         invoked o
2af0: 6e 63 65 20 66 6f 72 20 65 61 63 68 20 72 6f 77  nce for each row
2b00: 20 6f 66 20 72 65 73 75 6c 74 2e 0a 2a 2a 0a 2a   of result..**.*
2b10: 2a 20 7b 46 31 32 31 31 30 7d 20 49 66 20 74 68  * {F12110} If th
2b20: 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
2b30: 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 76 61  ns a non-zero va
2b40: 6c 75 65 20 74 68 65 6e 20 5b 73 71 6c 69 74 65  lue then [sqlite
2b50: 33 5f 65 78 65 63 28 29 5d 0a 2a 2a 20 20 20 20  3_exec()].**    
2b60: 20 20 20 20 20 20 77 69 6c 6c 20 61 62 6f 72 74        will abort
2b70: 65 64 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  ed the SQL state
2b80: 6d 65 6e 74 20 69 74 20 69 73 20 63 75 72 72 65  ment it is curre
2b90: 6e 74 6c 79 20 65 76 61 6c 75 61 74 69 6e 67 2c  ntly evaluating,
2ba0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 6b 69  .**          ski
2bb0: 70 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74  p all subsequent
2bc0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2c   SQL statements,
2bd0: 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c   and return [SQL
2be0: 49 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 20 20  ITE_ABORT]..**  
2bf0: 20 20 20 20 20 20 20 20 3c 74 6f 64 6f 3e 57 68          <todo>Wh
2c00: 61 74 20 68 61 70 70 65 6e 73 20 74 6f 20 2a 65  at happens to *e
2c10: 72 72 6d 73 67 20 68 65 72 65 3f 20 20 44 6f 65  rrmsg here?  Doe
2c20: 73 20 74 68 65 20 72 65 73 75 6c 74 20 63 6f 64  s the result cod
2c30: 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  e for.**        
2c40: 20 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64    sqlite3_errcod
2c50: 65 28 29 20 67 65 74 20 73 65 74 3f 3c 2f 74 6f  e() get set?</to
2c60: 64 6f 3e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31 31  do>.**.** {F1211
2c70: 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  3} The [sqlite3_
2c80: 65 78 65 63 28 29 5d 20 72 6f 75 74 69 6e 65 20  exec()] routine 
2c90: 77 69 6c 6c 20 70 61 73 73 20 69 74 73 20 34 74  will pass its 4t
2ca0: 68 20 70 61 72 61 6d 65 74 65 72 20 74 68 72 6f  h parameter thro
2cb0: 75 67 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ugh.**          
2cc0: 61 73 20 74 68 65 20 31 73 74 20 70 61 72 61 6d  as the 1st param
2cd0: 65 74 65 72 20 6f 66 20 74 68 65 20 63 61 6c 6c  eter of the call
2ce0: 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  back..**.** {F12
2cf0: 31 31 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  116} The [sqlite
2d00: 33 5f 65 78 65 63 28 29 5d 20 72 6f 75 74 69 6e  3_exec()] routin
2d10: 65 20 73 65 74 73 20 74 68 65 20 32 6e 64 20 70  e sets the 2nd p
2d20: 61 72 61 6d 65 74 65 72 20 6f 66 20 69 74 73 0a  arameter of its.
2d30: 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c  **          call
2d40: 62 61 63 6b 20 74 6f 20 62 65 20 74 68 65 20 6e  back to be the n
2d50: 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
2d60: 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20   in the current 
2d70: 72 6f 77 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20  row of.**       
2d80: 20 20 20 72 65 73 75 6c 74 2e 0a 2a 2a 0a 2a 2a     result..**.**
2d90: 20 7b 46 31 32 31 31 39 7d 20 54 68 65 20 5b 73   {F12119} The [s
2da0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 72  qlite3_exec()] r
2db0: 6f 75 74 69 6e 65 20 73 65 74 73 20 74 68 65 20  outine sets the 
2dc0: 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66  3rd parameter of
2dd0: 20 69 74 73 20 0a 2a 2a 20 20 20 20 20 20 20 20   its .**        
2de0: 20 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 62 65    callback to be
2df0: 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
2e00: 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73  nters to strings
2e10: 20 68 6f 6c 64 69 6e 67 20 74 68 65 0a 2a 2a 20   holding the.** 
2e20: 20 20 20 20 20 20 20 20 20 76 61 6c 75 65 73 20           values 
2e30: 66 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e 20  for each column 
2e40: 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72  in the current r
2e50: 65 73 75 6c 74 20 73 65 74 20 72 6f 77 20 61 73  esult set row as
2e60: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 62 74  .**          obt
2e70: 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
2e80: 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
2e90: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31 32  )]..**.** {F1212
2ea0: 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  2} The [sqlite3_
2eb0: 65 78 65 63 28 29 5d 20 72 6f 75 74 69 6e 65 20  exec()] routine 
2ec0: 73 65 74 73 20 74 68 65 20 34 74 68 20 70 61 72  sets the 4th par
2ed0: 61 6d 65 74 65 72 20 6f 66 20 69 74 73 0a 2a 2a  ameter of its.**
2ee0: 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c 62 61            callba
2ef0: 63 6b 20 74 6f 20 62 65 20 61 6e 20 61 72 72 61  ck to be an arra
2f00: 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f  y of pointers to
2f10: 20 73 74 72 69 6e 67 73 20 68 6f 6c 64 69 6e 67   strings holding
2f20: 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
2f30: 20 6e 61 6d 65 73 20 6f 66 20 72 65 73 75 6c 74   names of result
2f40: 20 63 6f 6c 75 6d 6e 73 20 61 73 20 6f 62 74 61   columns as obta
2f50: 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
2f60: 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29  e3_column_name()
2f70: 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31 32 35  ]..**.** {F12125
2f80: 7d 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72  } If the 3rd par
2f90: 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
2fa0: 65 33 5f 65 78 65 63 28 29 5d 20 69 73 20 4e 55  e3_exec()] is NU
2fb0: 4c 4c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20  LL then.**      
2fc0: 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 65 78 65      [sqlite3_exe
2fd0: 63 28 29 5d 20 6e 65 76 65 72 20 69 6e 76 6f 6b  c()] never invok
2fe0: 65 73 20 61 20 63 61 6c 6c 62 61 63 6b 2e 20 20  es a callback.  
2ff0: 41 6c 6c 20 71 75 65 72 79 0a 2a 2a 20 20 20 20  All query.**    
3000: 20 20 20 20 20 20 72 65 73 75 6c 74 73 20 61 72        results ar
3010: 65 20 73 69 6c 65 6e 74 6c 79 20 64 69 73 63 61  e silently disca
3020: 72 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  rded..**.** {F12
3030: 31 32 38 7d 20 49 66 20 61 6e 20 65 72 72 6f 72  128} If an error
3040: 20 6f 63 63 75 72 73 20 77 68 69 6c 65 20 70 61   occurs while pa
3050: 72 73 69 6e 67 20 6f 72 20 65 76 61 6c 75 61 74  rsing or evaluat
3060: 69 6e 67 20 61 6e 79 20 6f 66 20 74 68 65 20 53  ing any of the S
3070: 51 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73  QL.**          s
3080: 74 61 74 65 6d 65 6e 74 73 20 68 61 6e 64 65 64  tatements handed
3090: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65   to [sqlite3_exe
30a0: 63 28 29 5d 20 74 68 65 6e 20 5b 73 71 6c 69 74  c()] then [sqlit
30b0: 65 33 5f 65 78 65 63 28 29 5d 20 77 69 6c 6c 0a  e3_exec()] will.
30c0: 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75  **          retu
30d0: 72 6e 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64  rn an [error cod
30e0: 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  e] other than [S
30f0: 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a  QLITE_OK]..**.**
3100: 20 7b 46 31 32 31 33 31 7d 20 49 66 20 61 6e 20   {F12131} If an 
3110: 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 69  error occurs whi
3120: 6c 65 20 70 61 72 73 69 6e 67 20 6f 72 20 65 76  le parsing or ev
3130: 61 6c 75 61 74 69 6e 67 20 61 6e 79 20 6f 66 20  aluating any of 
3140: 74 68 65 20 53 51 4c 0a 2a 2a 20 20 20 20 20 20  the SQL.**      
3150: 20 20 20 20 68 61 6e 64 65 64 20 74 6f 20 5b 73      handed to [s
3160: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 61  qlite3_exec()] a
3170: 6e 64 20 69 66 20 74 68 65 20 35 74 68 20 70 61  nd if the 5th pa
3180: 72 61 6d 65 74 65 72 20 28 65 72 72 6d 73 67 29  rameter (errmsg)
3190: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20  .**          to 
31a0: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
31b0: 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68   is not NULL, th
31c0: 65 6e 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73  en an error mess
31d0: 61 67 65 20 69 73 0a 2a 2a 20 20 20 20 20 20 20  age is.**       
31e0: 20 20 20 61 6c 6c 6f 63 61 74 65 64 20 75 73 69     allocated usi
31f0: 6e 67 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e  ng the equivalen
3200: 74 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 70  t of [sqlite3_mp
3210: 72 69 6e 74 66 28 29 5d 20 61 6e 64 0a 2a 2a 20  rintf()] and.** 
3220: 20 20 20 20 20 20 20 20 20 2a 65 72 72 6d 73 67           *errmsg
3230: 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e   is made to poin
3240: 74 20 74 6f 20 74 68 61 74 20 6d 65 73 73 61 67  t to that messag
3250: 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31 33 34  e..**.** {F12134
3260: 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65  } The [sqlite3_e
3270: 78 65 63 28 29 5d 20 72 6f 75 74 69 6e 65 20 64  xec()] routine d
3280: 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74  oes not change t
3290: 68 65 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 20  he value of.**  
32a0: 20 20 20 20 20 20 20 20 2a 65 72 72 6d 73 67 20          *errmsg 
32b0: 69 66 20 65 72 72 6d 73 67 20 69 73 20 4e 55 4c  if errmsg is NUL
32c0: 4c 20 6f 72 20 69 66 20 74 68 65 72 65 20 61 72  L or if there ar
32d0: 65 20 6e 6f 20 65 72 72 6f 72 73 2e 0a 2a 2a 0a  e no errors..**.
32e0: 2a 2a 20 7b 46 31 32 31 33 37 7d 20 54 68 65 20  ** {F12137} The 
32f0: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
3300: 20 66 75 6e 63 74 69 6f 6e 20 73 65 74 73 20 74   function sets t
3310: 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e  he error code an
3320: 64 20 6d 65 73 73 61 67 65 0a 2a 2a 20 20 20 20  d message.**    
3330: 20 20 20 20 20 20 61 63 63 65 73 73 69 62 6c 65        accessible
3340: 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 65 72   via [sqlite3_er
3350: 72 63 6f 64 65 28 29 5d 2c 20 5b 73 71 6c 69 74  rcode()], [sqlit
3360: 65 33 5f 65 72 72 6d 73 67 28 29 5d 2c 20 61 6e  e3_errmsg()], an
3370: 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  d.**          [s
3380: 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
3390: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49 54 41  )]..**.** LIMITA
33a0: 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 55 31  TIONS:.**.** {U1
33b0: 32 31 34 31 7d 20 54 68 65 20 66 69 72 73 74 20  2141} The first 
33c0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
33d0: 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 6d 75  lite3_exec()] mu
33e0: 73 74 20 62 65 20 61 6e 20 76 61 6c 69 64 20 61  st be an valid a
33f0: 6e 64 20 6f 70 65 6e 0a 2a 2a 20 20 20 20 20 20  nd open.**      
3400: 20 20 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f      [database co
3410: 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a  nnection]..**.**
3420: 20 7b 55 31 32 31 34 32 7d 20 54 68 65 20 64 61   {U12142} The da
3430: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
3440: 6e 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 63 6c  n must not be cl
3450: 6f 73 65 64 20 77 68 69 6c 65 0a 2a 2a 20 20 20  osed while.**   
3460: 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
3470: 65 78 65 63 28 29 5d 20 69 73 20 72 75 6e 6e 69  exec()] is runni
3480: 6e 67 2e 0a 2a 2a 20 0a 2a 2a 20 7b 55 31 32 31  ng..** .** {U121
3490: 34 33 7d 20 54 68 65 20 63 61 6c 6c 69 6e 67 20  43} The calling 
34a0: 66 75 6e 63 74 69 6f 6e 20 69 73 20 73 68 6f 75  function is shou
34b0: 6c 64 20 75 73 65 20 5b 73 71 6c 69 74 65 33 5f  ld use [sqlite3_
34c0: 66 72 65 65 28 29 5d 20 74 6f 20 66 72 65 65 0a  free()] to free.
34d0: 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
34e0: 6d 65 6d 6f 72 79 20 74 68 61 74 20 2a 65 72 72  memory that *err
34f0: 6d 73 67 20 69 73 20 6c 65 66 74 20 70 6f 69 6e  msg is left poin
3500: 74 69 6e 67 20 61 74 20 6f 6e 63 65 20 74 68 65  ting at once the
3510: 20 65 72 72 6f 72 0a 2a 2a 20 20 20 20 20 20 20   error.**       
3520: 20 20 20 6d 65 73 73 61 67 65 20 69 73 20 6e 6f     message is no
3530: 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a   longer needed..
3540: 2a 2a 0a 2a 2a 20 7b 55 31 32 31 34 35 7d 20 54  **.** {U12145} T
3550: 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
3560: 20 74 65 78 74 20 69 6e 20 74 68 65 20 32 6e 64   text in the 2nd
3570: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
3580: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 0a 2a  qlite3_exec()].*
3590: 2a 20 20 20 20 20 20 20 20 20 20 6d 75 73 74 20  *          must 
35a0: 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65 64  remain unchanged
35b0: 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f   while [sqlite3_
35c0: 65 78 65 63 28 29 5d 20 69 73 20 72 75 6e 6e 69  exec()] is runni
35d0: 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ng..*/.int sqlit
35e0: 65 33 5f 65 78 65 63 28 0a 20 20 73 71 6c 69 74  e3_exec(.  sqlit
35f0: 65 33 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20  e3*,            
3600: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3610: 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e        /* An open
3620: 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63   database */.  c
3630: 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 2c 20  onst char *sql, 
3640: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3650: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c            /* SQL
3660: 20 74 6f 20 62 65 20 65 76 61 6c 75 74 65 64 20   to be evaluted 
3670: 2a 2f 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62  */.  int (*callb
3680: 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  ack)(void*,int,c
3690: 68 61 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20  har**,char**),  
36a0: 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63  /* Callback func
36b0: 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  tion */.  void *
36c0: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
36d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
36e0: 20 20 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75       /* 1st argu
36f0: 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b  ment to callback
3700: 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72   */.  char **err
3710: 6d 73 67 20 20 20 20 20 20 20 20 20 20 20 20 20  msg             
3720: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3730: 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72   /* Error msg wr
3740: 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b  itten here */.);
3750: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
3760: 3a 20 52 65 73 75 6c 74 20 43 6f 64 65 73 20 7b  : Result Codes {
3770: 46 31 30 32 31 30 7d 0a 2a 2a 20 4b 45 59 57 4f  F10210}.** KEYWO
3780: 52 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b 20 7b  RDS: SQLITE_OK {
3790: 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 72 72  error code} {err
37a0: 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20  or codes}.**.** 
37b0: 4d 61 6e 79 20 53 51 4c 69 74 65 20 66 75 6e 63  Many SQLite func
37c0: 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 61 6e 20  tions return an 
37d0: 69 6e 74 65 67 65 72 20 72 65 73 75 6c 74 20 63  integer result c
37e0: 6f 64 65 20 66 72 6f 6d 20 74 68 65 20 73 65 74  ode from the set
37f0: 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72 65 20 69   shown.** here i
3800: 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 64 69 63  n order to indic
3810: 61 74 65 73 20 73 75 63 63 65 73 73 20 6f 72 20  ates success or 
3820: 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 53  failure..**.** S
3830: 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45  ee also: [SQLITE
3840: 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 65 78  _IOERR_READ | ex
3850: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
3860: 64 65 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  des].*/.#define 
3870: 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20 20  SQLITE_OK       
3880: 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63 65      0   /* Succe
3890: 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a  ssful result */.
38a0: 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d  /* beginning-of-
38b0: 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23  error-codes */.#
38c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 52  define SQLITE_ER
38d0: 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 20 2f  ROR        1   /
38e0: 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d  * SQL error or m
38f0: 69 73 73 69 6e 67 20 64 61 74 61 62 61 73 65 20  issing database 
3900: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
3910: 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20 32  E_INTERNAL     2
3920: 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c     /* Internal l
3930: 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53 51  ogic error in SQ
3940: 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  Lite */.#define 
3950: 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20 20  SQLITE_PERM     
3960: 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65 73      3   /* Acces
3970: 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e  s permission den
3980: 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ied */.#define S
3990: 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20 20  QLITE_ABORT     
39a0: 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61     4   /* Callba
39b0: 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75 65  ck routine reque
39c0: 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f  sted an abort */
39d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
39e0: 42 55 53 59 20 20 20 20 20 20 20 20 20 35 20 20  BUSY         5  
39f0: 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65   /* The database
3a00: 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20   file is locked 
3a10: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
3a20: 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 36  E_LOCKED       6
3a30: 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e     /* A table in
3a40: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
3a50: 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69   locked */.#defi
3a60: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20  ne SQLITE_NOMEM 
3a70: 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41 20         7   /* A 
3a80: 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64 20  malloc() failed 
3a90: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
3aa0: 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 38  E_READONLY     8
3ab0: 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f     /* Attempt to
3ac0: 20 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e 6c   write a readonl
3ad0: 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64  y database */.#d
3ae0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54  efine SQLITE_INT
3af0: 45 52 52 55 50 54 20 20 20 20 39 20 20 20 2f 2a  ERRUPT    9   /*
3b00: 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d 69   Operation termi
3b10: 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33  nated by sqlite3
3b20: 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a 23  _interrupt()*/.#
3b30: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
3b40: 45 52 52 20 20 20 20 20 20 20 31 30 20 20 20 2f  ERR       10   /
3b50: 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64  * Some kind of d
3b60: 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63  isk I/O error oc
3b70: 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e  curred */.#defin
3b80: 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54  e SQLITE_CORRUPT
3b90: 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68 65       11   /* The
3ba0: 20 64 61 74 61 62 61 73 65 20 64 69 73 6b 20 69   database disk i
3bb0: 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65  mage is malforme
3bc0: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
3bd0: 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20  ITE_NOTFOUND    
3be0: 31 32 20 20 20 2f 2a 20 4e 4f 54 20 55 53 45 44  12   /* NOT USED
3bf0: 2e 20 54 61 62 6c 65 20 6f 72 20 72 65 63 6f 72  . Table or recor
3c00: 64 20 6e 6f 74 20 66 6f 75 6e 64 20 2a 2f 0a 23  d not found */.#
3c10: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55  define SQLITE_FU
3c20: 4c 4c 20 20 20 20 20 20 20 20 31 33 20 20 20 2f  LL        13   /
3c30: 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c  * Insertion fail
3c40: 65 64 20 62 65 63 61 75 73 65 20 64 61 74 61 62  ed because datab
3c50: 61 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f 0a 23  ase is full */.#
3c60: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41  define SQLITE_CA
3c70: 4e 54 4f 50 45 4e 20 20 20 20 31 34 20 20 20 2f  NTOPEN    14   /
3c80: 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70 65 6e  * Unable to open
3c90: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
3ca0: 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  le */.#define SQ
3cb0: 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20 20 20  LITE_PROTOCOL   
3cc0: 20 31 35 20 20 20 2f 2a 20 4e 4f 54 20 55 53 45   15   /* NOT USE
3cd0: 44 2e 20 44 61 74 61 62 61 73 65 20 6c 6f 63 6b  D. Database lock
3ce0: 20 70 72 6f 74 6f 63 6f 6c 20 65 72 72 6f 72 20   protocol error 
3cf0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
3d00: 45 5f 45 4d 50 54 59 20 20 20 20 20 20 20 31 36  E_EMPTY       16
3d10: 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 69     /* Database i
3d20: 73 20 65 6d 70 74 79 20 2a 2f 0a 23 64 65 66 69  s empty */.#defi
3d30: 6e 65 20 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  ne SQLITE_SCHEMA
3d40: 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 54 68        17   /* Th
3d50: 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d  e database schem
3d60: 61 20 63 68 61 6e 67 65 64 20 2a 2f 0a 23 64 65  a changed */.#de
3d70: 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 4f 4f 42  fine SQLITE_TOOB
3d80: 49 47 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20  IG      18   /* 
3d90: 53 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 65  String or BLOB e
3da0: 78 63 65 65 64 73 20 73 69 7a 65 20 6c 69 6d 69  xceeds size limi
3db0: 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
3dc0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 20  ITE_CONSTRAINT  
3dd0: 31 39 20 20 20 2f 2a 20 41 62 6f 72 74 20 64 75  19   /* Abort du
3de0: 65 20 74 6f 20 63 6f 6e 73 74 72 61 69 6e 74 20  e to constraint 
3df0: 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64 65  violation */.#de
3e00: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 4d  fine SQLITE_MISM
3e10: 41 54 43 48 20 20 20 20 32 30 20 20 20 2f 2a 20  ATCH    20   /* 
3e20: 44 61 74 61 20 74 79 70 65 20 6d 69 73 6d 61 74  Data type mismat
3e30: 63 68 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ch */.#define SQ
3e40: 4c 49 54 45 5f 4d 49 53 55 53 45 20 20 20 20 20  LITE_MISUSE     
3e50: 20 32 31 20 20 20 2f 2a 20 4c 69 62 72 61 72 79   21   /* Library
3e60: 20 75 73 65 64 20 69 6e 63 6f 72 72 65 63 74 6c   used incorrectl
3e70: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
3e80: 49 54 45 5f 4e 4f 4c 46 53 20 20 20 20 20 20 20  ITE_NOLFS       
3e90: 32 32 20 20 20 2f 2a 20 55 73 65 73 20 4f 53 20  22   /* Uses OS 
3ea0: 66 65 61 74 75 72 65 73 20 6e 6f 74 20 73 75 70  features not sup
3eb0: 70 6f 72 74 65 64 20 6f 6e 20 68 6f 73 74 20 2a  ported on host *
3ec0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3ed0: 5f 41 55 54 48 20 20 20 20 20 20 20 20 32 33 20  _AUTH        23 
3ee0: 20 20 2f 2a 20 41 75 74 68 6f 72 69 7a 61 74 69    /* Authorizati
3ef0: 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65  on denied */.#de
3f00: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4f 52 4d  fine SQLITE_FORM
3f10: 41 54 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20  AT      24   /* 
3f20: 41 75 78 69 6c 69 61 72 79 20 64 61 74 61 62 61  Auxiliary databa
3f30: 73 65 20 66 6f 72 6d 61 74 20 65 72 72 6f 72 20  se format error 
3f40: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
3f50: 45 5f 52 41 4e 47 45 20 20 20 20 20 20 20 32 35  E_RANGE       25
3f60: 20 20 20 2f 2a 20 32 6e 64 20 70 61 72 61 6d 65     /* 2nd parame
3f70: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ter to sqlite3_b
3f80: 69 6e 64 20 6f 75 74 20 6f 66 20 72 61 6e 67 65  ind out of range
3f90: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
3fa0: 54 45 5f 4e 4f 54 41 44 42 20 20 20 20 20 20 32  TE_NOTADB      2
3fb0: 36 20 20 20 2f 2a 20 46 69 6c 65 20 6f 70 65 6e  6   /* File open
3fc0: 65 64 20 74 68 61 74 20 69 73 20 6e 6f 74 20 61  ed that is not a
3fd0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a   database file *
3fe0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3ff0: 5f 52 4f 57 20 20 20 20 20 20 20 20 20 31 30 30  _ROW         100
4000: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65    /* sqlite3_ste
4010: 70 28 29 20 68 61 73 20 61 6e 6f 74 68 65 72 20  p() has another 
4020: 72 6f 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 65  row ready */.#de
4030: 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45  fine SQLITE_DONE
4040: 20 20 20 20 20 20 20 20 31 30 31 20 20 2f 2a 20          101  /* 
4050: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68  sqlite3_step() h
4060: 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63  as finished exec
4070: 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d  uting */./* end-
4080: 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a  of-error-codes *
4090: 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
40a0: 46 3a 20 45 78 74 65 6e 64 65 64 20 52 65 73 75  F: Extended Resu
40b0: 6c 74 20 43 6f 64 65 73 20 7b 46 31 30 32 32 30  lt Codes {F10220
40c0: 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  }.** KEYWORDS: {
40d0: 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63  extended error c
40e0: 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20 65  ode} {extended e
40f0: 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b  rror codes}.** K
4100: 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64  EYWORDS: {extend
4110: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 7d  ed result codes}
4120: 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74 73 20 64 65  .**.** In its de
4130: 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74  fault configurat
4140: 69 6f 6e 2c 20 53 51 4c 69 74 65 20 41 50 49 20  ion, SQLite API 
4150: 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
4160: 6f 6e 65 20 6f 66 20 32 36 20 69 6e 74 65 67 65  one of 26 intege
4170: 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 20  r.** [SQLITE_OK 
4180: 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e  | result codes].
4190: 20 20 48 6f 77 65 76 65 72 2c 20 65 78 70 65 72    However, exper
41a0: 69 65 6e 63 65 20 68 61 73 20 73 68 6f 77 6e 20  ience has shown 
41b0: 74 68 61 74 0a 2a 2a 20 6d 61 6e 79 20 6f 66 20  that.** many of 
41c0: 74 68 65 73 65 20 72 65 73 75 6c 74 20 63 6f 64  these result cod
41d0: 65 73 20 61 72 65 20 74 6f 6f 20 63 6f 75 72 73  es are too cours
41e0: 65 2d 67 72 61 69 6e 65 64 2e 20 20 54 68 65 79  e-grained.  They
41f0: 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64 65 20   do not provide 
4200: 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66 6f 72  as.** much infor
4210: 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 70 72 6f  mation about pro
4220: 62 6c 65 6d 73 20 61 73 20 70 72 6f 67 72 61 6d  blems as program
4230: 6d 65 72 73 20 6d 69 67 68 74 20 6c 69 6b 65 2e  mers might like.
4240: 20 20 49 6e 20 61 6e 20 65 66 66 6f 72 74 20 74    In an effort t
4250: 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20 74 68 69  o.** address thi
4260: 73 2c 20 6e 65 77 65 72 20 76 65 72 73 69 6f 6e  s, newer version
4270: 73 20 6f 66 20 53 51 4c 69 74 65 20 28 76 65 72  s of SQLite (ver
4280: 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e 64 20 6c  sion 3.3.8 and l
4290: 61 74 65 72 29 20 69 6e 63 6c 75 64 65 0a 2a 2a  ater) include.**
42a0: 20 73 75 70 70 6f 72 74 20 66 6f 72 20 61 64 64   support for add
42b0: 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c 74 20 63  itional result c
42c0: 6f 64 65 73 20 74 68 61 74 20 70 72 6f 76 69 64  odes that provid
42d0: 65 20 6d 6f 72 65 20 64 65 74 61 69 6c 65 64 20  e more detailed 
42e0: 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61  information.** a
42f0: 62 6f 75 74 20 65 72 72 6f 72 73 2e 20 54 68 65  bout errors. The
4300: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
4310: 20 63 6f 64 65 73 20 61 72 65 20 65 6e 61 62 6c   codes are enabl
4320: 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a  ed or disabled.*
4330: 2a 20 66 6f 72 20 65 61 63 68 20 64 61 74 61 62  * for each datab
4340: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 75  ase connection u
4350: 73 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65  sing the [sqlite
4360: 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c  3_extended_resul
4370: 74 5f 63 6f 64 65 73 28 29 5d 0a 2a 2a 20 41 50  t_codes()].** AP
4380: 49 2e 0a 2a 2a 20 0a 2a 2a 20 53 6f 6d 65 20 6f  I..** .** Some o
4390: 66 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20  f the available 
43a0: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
43b0: 63 6f 64 65 73 20 61 72 65 20 6c 69 73 74 65 64  codes are listed
43c0: 20 68 65 72 65 2e 0a 2a 2a 20 4f 6e 65 20 6d 61   here..** One ma
43d0: 79 20 65 78 70 65 63 74 20 74 68 65 20 6e 75 6d  y expect the num
43e0: 62 65 72 20 6f 66 20 65 78 74 65 6e 64 65 64 20  ber of extended 
43f0: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 77 69 6c  result codes wil
4400: 6c 20 62 65 20 65 78 70 61 6e 64 0a 2a 2a 20 6f  l be expand.** o
4410: 76 65 72 20 74 69 6d 65 2e 20 20 53 6f 66 74 77  ver time.  Softw
4420: 61 72 65 20 74 68 61 74 20 75 73 65 73 20 65 78  are that uses ex
4430: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
4440: 64 65 73 20 73 68 6f 75 6c 64 20 65 78 70 65 63  des should expec
4450: 74 0a 2a 2a 20 74 6f 20 73 65 65 20 6e 65 77 20  t.** to see new 
4460: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 69 6e 20  result codes in 
4470: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
4480: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a  of SQLite..**.**
4490: 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 4b 20 72   The SQLITE_OK r
44a0: 65 73 75 6c 74 20 63 6f 64 65 20 77 69 6c 6c 20  esult code will 
44b0: 6e 65 76 65 72 20 62 65 20 65 78 74 65 6e 64 65  never be extende
44c0: 64 2e 20 20 49 74 20 77 69 6c 6c 20 61 6c 77 61  d.  It will alwa
44d0: 79 73 0a 2a 2a 20 62 65 20 65 78 61 63 74 6c 79  ys.** be exactly
44e0: 20 7a 65 72 6f 2e 0a 2a 2a 20 0a 2a 2a 20 49 4e   zero..** .** IN
44f0: 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
4500: 7b 46 31 30 32 32 33 7d 20 54 68 65 20 73 79 6d  {F10223} The sym
4510: 62 6f 6c 69 63 20 6e 61 6d 65 20 66 6f 72 20 61  bolic name for a
4520: 6e 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  n extended resul
4530: 74 20 63 6f 64 65 20 61 6c 77 61 79 73 20 63 6f  t code always co
4540: 6e 74 61 69 6e 73 0a 2a 2a 20 20 20 20 20 20 20  ntains.**       
4550: 20 20 20 61 20 72 65 6c 61 74 65 64 20 70 72 69     a related pri
4560: 6d 61 72 79 20 72 65 73 75 6c 74 20 63 6f 64 65  mary result code
4570: 20 61 73 20 61 20 70 72 65 66 69 78 2e 0a 2a 2a   as a prefix..**
4580: 0a 2a 2a 20 7b 46 31 30 32 32 34 7d 20 50 72 69  .** {F10224} Pri
4590: 6d 61 72 79 20 72 65 73 75 6c 74 20 63 6f 64 65  mary result code
45a0: 20 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 20 61   names contain a
45b0: 20 73 69 6e 67 6c 65 20 22 5f 22 20 63 68 61 72   single "_" char
45c0: 61 63 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  acter..**.** {F1
45d0: 30 32 32 35 7d 20 45 78 74 65 6e 64 65 64 20 72  0225} Extended r
45e0: 65 73 75 6c 74 20 63 6f 64 65 20 6e 61 6d 65 73  esult code names
45f0: 20 63 6f 6e 74 61 69 6e 20 74 77 6f 20 6f 72 20   contain two or 
4600: 6d 6f 72 65 20 22 5f 22 20 63 68 61 72 61 63 74  more "_" charact
4610: 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 32  ers..**.** {F102
4620: 32 36 7d 20 54 68 65 20 6e 75 6d 65 72 69 63 20  26} The numeric 
4630: 76 61 6c 75 65 20 6f 66 20 61 6e 20 65 78 74 65  value of an exte
4640: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
4650: 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 0a 2a 2a   contains the.**
4660: 20 20 20 20 20 20 20 20 20 20 6e 75 6d 65 72 69            numeri
4670: 63 20 76 61 6c 75 65 20 6f 66 20 69 74 73 20 63  c value of its c
4680: 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 70 72 69  orresponding pri
4690: 6d 61 72 79 20 72 65 73 75 6c 74 20 63 6f 64 65  mary result code
46a0: 20 69 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   in.**          
46b0: 69 74 73 20 6c 65 61 73 74 20 73 69 67 6e 69 66  its least signif
46c0: 69 63 61 6e 74 20 38 20 62 69 74 73 2e 0a 2a 2f  icant 8 bits..*/
46d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
46e0: 49 4f 45 52 52 5f 52 45 41 44 20 20 20 20 20 20  IOERR_READ      
46f0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4700: 52 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  R | (1<<8)).#def
4710: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4720: 5f 53 48 4f 52 54 5f 52 45 41 44 20 20 20 20 28  _SHORT_READ    (
4730: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
4740: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
4750: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 57 52 49 54  QLITE_IOERR_WRIT
4760: 45 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  E         (SQLIT
4770: 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29  E_IOERR | (3<<8)
4780: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
4790: 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20  _IOERR_FSYNC    
47a0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
47b0: 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65  RR | (4<<8)).#de
47c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
47d0: 52 5f 44 49 52 5f 46 53 59 4e 43 20 20 20 20 20  R_DIR_FSYNC     
47e0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
47f0: 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (5<<8)).#define 
4800: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52 55  SQLITE_IOERR_TRU
4810: 4e 43 41 54 45 20 20 20 20 20 20 28 53 51 4c 49  NCATE      (SQLI
4820: 54 45 5f 49 4f 45 52 52 20 7c 20 28 36 3c 3c 38  TE_IOERR | (6<<8
4830: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
4840: 45 5f 49 4f 45 52 52 5f 46 53 54 41 54 20 20 20  E_IOERR_FSTAT   
4850: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
4860: 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64  ERR | (7<<8)).#d
4870: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4880: 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20  RR_UNLOCK       
4890: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
48a0: 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (8<<8)).#define
48b0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 44   SQLITE_IOERR_RD
48c0: 4c 4f 43 4b 20 20 20 20 20 20 20 20 28 53 51 4c  LOCK        (SQL
48d0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c  ITE_IOERR | (9<<
48e0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
48f0: 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 20  TE_IOERR_DELETE 
4900: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
4910: 4f 45 52 52 20 7c 20 28 31 30 3c 3c 38 29 29 0a  OERR | (10<<8)).
4920: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4930: 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20  OERR_BLOCKED    
4940: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
4950: 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66   | (11<<8)).#def
4960: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4970: 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 28  _NOMEM         (
4980: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
4990: 31 32 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43  12<<8))../*.** C
49a0: 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46  API3REF: Flags F
49b0: 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65  or File Open Ope
49c0: 72 61 74 69 6f 6e 73 20 7b 46 31 30 32 33 30 7d  rations {F10230}
49d0: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 62 69 74  .**.** These bit
49e0: 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 74 65   values are inte
49f0: 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20  nded for use in 
4a00: 74 68 65 0a 2a 2a 20 33 72 64 20 70 61 72 61 6d  the.** 3rd param
4a10: 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c  eter to the [sql
4a20: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20  ite3_open_v2()] 
4a30: 69 6e 74 65 72 66 61 63 65 20 61 6e 64 0a 2a 2a  interface and.**
4a40: 20 69 6e 20 74 68 65 20 34 74 68 20 70 61 72 61   in the 4th para
4a50: 6d 65 74 65 72 20 74 6f 20 74 68 65 20 78 4f 70  meter to the xOp
4a60: 65 6e 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65  en method of the
4a70: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  .** [sqlite3_vfs
4a80: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65  ] object..*/.#de
4a90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
4aa0: 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 20 20  _READONLY       
4ab0: 20 20 30 78 30 30 30 30 30 30 30 31 0a 23 64 65    0x00000001.#de
4ac0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
4ad0: 5f 52 45 41 44 57 52 49 54 45 20 20 20 20 20 20  _READWRITE      
4ae0: 20 20 30 78 30 30 30 30 30 30 30 32 0a 23 64 65    0x00000002.#de
4af0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
4b00: 5f 43 52 45 41 54 45 20 20 20 20 20 20 20 20 20  _CREATE         
4b10: 20 20 30 78 30 30 30 30 30 30 30 34 0a 23 64 65    0x00000004.#de
4b20: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
4b30: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20 20  _DELETEONCLOSE  
4b40: 20 20 30 78 30 30 30 30 30 30 30 38 0a 23 64 65    0x00000008.#de
4b50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
4b60: 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 20 20  _EXCLUSIVE      
4b70: 20 20 30 78 30 30 30 30 30 30 31 30 0a 23 64 65    0x00000010.#de
4b80: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
4b90: 5f 4d 41 49 4e 5f 44 42 20 20 20 20 20 20 20 20  _MAIN_DB        
4ba0: 20 20 30 78 30 30 30 30 30 31 30 30 0a 23 64 65    0x00000100.#de
4bb0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
4bc0: 5f 54 45 4d 50 5f 44 42 20 20 20 20 20 20 20 20  _TEMP_DB        
4bd0: 20 20 30 78 30 30 30 30 30 32 30 30 0a 23 64 65    0x00000200.#de
4be0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
4bf0: 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 20 20 20  _TRANSIENT_DB   
4c00: 20 20 30 78 30 30 30 30 30 34 30 30 0a 23 64 65    0x00000400.#de
4c10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
4c20: 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20  _MAIN_JOURNAL   
4c30: 20 20 30 78 30 30 30 30 30 38 30 30 0a 23 64 65    0x00000800.#de
4c40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
4c50: 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20 20  _TEMP_JOURNAL   
4c60: 20 20 30 78 30 30 30 30 31 30 30 30 0a 23 64 65    0x00001000.#de
4c70: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
4c80: 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20 20  _SUBJOURNAL     
4c90: 20 20 30 78 30 30 30 30 32 30 30 30 0a 23 64 65    0x00002000.#de
4ca0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
4cb0: 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 20  _MASTER_JOURNAL 
4cc0: 20 20 30 78 30 30 30 30 34 30 30 30 0a 0a 2f 2a    0x00004000../*
4cd0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
4ce0: 76 69 63 65 20 43 68 61 72 61 63 74 65 72 69 73  vice Characteris
4cf0: 74 69 63 73 20 7b 46 31 30 32 34 30 7d 0a 2a 2a  tics {F10240}.**
4d00: 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65 43  .** The xDeviceC
4d10: 61 70 61 62 69 6c 69 74 69 65 73 20 6d 65 74 68  apabilities meth
4d20: 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  od of the [sqlit
4d30: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a  e3_io_methods].*
4d40: 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 73  * object returns
4d50: 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63   an integer whic
4d60: 68 20 69 73 20 61 20 76 65 63 74 6f 72 20 6f 66  h is a vector of
4d70: 20 74 68 65 20 74 68 65 73 65 0a 2a 2a 20 62 69   the these.** bi
4d80: 74 20 76 61 6c 75 65 73 20 65 78 70 72 65 73 73  t values express
4d90: 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65  ing I/O characte
4da0: 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d  ristics of the m
4db0: 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64  ass storage.** d
4dc0: 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73  evice that holds
4dd0: 20 74 68 65 20 66 69 6c 65 20 74 68 61 74 20 74   the file that t
4de0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  he [sqlite3_io_m
4df0: 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72  ethods].** refer
4e00: 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  s to..**.** The 
4e10: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
4e20: 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61  MIC property mea
4e30: 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74  ns that all writ
4e40: 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a  es of.** any siz
4e50: 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  e are atomic.  T
4e60: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
4e70: 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73  ATOMICnnn values
4e80: 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72  .** mean that wr
4e90: 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74  ites of blocks t
4ea0: 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65  hat are nnn byte
4eb0: 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a  s in size and.**
4ec0: 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20   are aligned to 
4ed0: 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68  an address which
4ee0: 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d   is an integer m
4ef0: 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e  ultiple of.** nn
4f00: 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  n are atomic.  T
4f10: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
4f20: 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75  SAFE_APPEND valu
4f30: 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20  e means.** that 
4f40: 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70  when data is app
4f50: 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c  ended to a file,
4f60: 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70   the data is app
4f70: 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74  ended.** first t
4f80: 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20  hen the size of 
4f90: 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65  the file is exte
4fa0: 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20  nded, never the 
4fb0: 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f  other.** way aro
4fc0: 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45  und.  The SQLITE
4fd0: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
4fe0: 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  L property means
4ff0: 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61   that.** informa
5000: 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20  tion is written 
5010: 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73  to disk in the s
5020: 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c  ame order as cal
5030: 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28  ls.** to xWrite(
5040: 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  )..*/.#define SQ
5050: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
5060: 43 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  C          0x000
5070: 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51  00001.#define SQ
5080: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
5090: 43 35 31 32 20 20 20 20 20 20 20 30 78 30 30 30  C512       0x000
50a0: 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51  00002.#define SQ
50b0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
50c0: 43 31 4b 20 20 20 20 20 20 20 20 30 78 30 30 30  C1K        0x000
50d0: 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51  00004.#define SQ
50e0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
50f0: 43 32 4b 20 20 20 20 20 20 20 20 30 78 30 30 30  C2K        0x000
5100: 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51  00008.#define SQ
5110: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
5120: 43 34 4b 20 20 20 20 20 20 20 20 30 78 30 30 30  C4K        0x000
5130: 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53 51  00010.#define SQ
5140: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
5150: 43 38 4b 20 20 20 20 20 20 20 20 30 78 30 30 30  C8K        0x000
5160: 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53 51  00020.#define SQ
5170: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
5180: 43 31 36 4b 20 20 20 20 20 20 20 30 78 30 30 30  C16K       0x000
5190: 30 30 30 34 30 0a 23 64 65 66 69 6e 65 20 53 51  00040.#define SQ
51a0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
51b0: 43 33 32 4b 20 20 20 20 20 20 20 30 78 30 30 30  C32K       0x000
51c0: 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20 53 51  00080.#define SQ
51d0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
51e0: 43 36 34 4b 20 20 20 20 20 20 20 30 78 30 30 30  C64K       0x000
51f0: 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00100.#define SQ
5200: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f  LITE_IOCAP_SAFE_
5210: 41 50 50 45 4e 44 20 20 20 20 20 30 78 30 30 30  APPEND     0x000
5220: 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00200.#define SQ
5230: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
5240: 4e 54 49 41 4c 20 20 20 20 20 20 30 78 30 30 30  NTIAL      0x000
5250: 30 30 34 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  00400../*.** CAP
5260: 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63 6b  I3REF: File Lock
5270: 69 6e 67 20 4c 65 76 65 6c 73 20 7b 46 31 30 32  ing Levels {F102
5280: 35 30 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  50}.**.** SQLite
5290: 20 75 73 65 73 20 6f 6e 65 20 6f 66 20 74 68 65   uses one of the
52a0: 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  se integer value
52b0: 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a  s as the second.
52c0: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63  ** argument to c
52d0: 61 6c 6c 73 20 69 74 20 6d 61 6b 65 73 20 74 6f  alls it makes to
52e0: 20 74 68 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64   the xLock() and
52f0: 20 78 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f   xUnlock() metho
5300: 64 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c  ds.** of an [sql
5310: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
5320: 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66   object..*/.#def
5330: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
5340: 4e 4f 4e 45 20 20 20 20 20 20 20 20 20 20 30 0a  NONE          0.
5350: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
5360: 4f 43 4b 5f 53 48 41 52 45 44 20 20 20 20 20 20  OCK_SHARED      
5370: 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
5380: 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44  TE_LOCK_RESERVED
5390: 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
53a0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44  SQLITE_LOCK_PEND
53b0: 49 4e 47 20 20 20 20 20 20 20 33 0a 23 64 65 66  ING       3.#def
53c0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
53d0: 45 58 43 4c 55 53 49 56 45 20 20 20 20 20 34 0a  EXCLUSIVE     4.
53e0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
53f0: 20 53 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e   Synchronization
5400: 20 54 79 70 65 20 46 6c 61 67 73 20 7b 46 31 30   Type Flags {F10
5410: 32 36 30 7d 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  260}.**.** When 
5420: 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74  SQLite invokes t
5430: 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68 6f  he xSync() metho
5440: 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69  d of an.** [sqli
5450: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
5460: 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73 20 61  object it uses a
5470: 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a   combination of.
5480: 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65 72  ** these integer
5490: 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73   values as the s
54a0: 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a  econd argument..
54b0: 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 53  **.** When the S
54c0: 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f  QLITE_SYNC_DATAO
54d0: 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65 64  NLY flag is used
54e0: 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20  , it means that 
54f0: 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72  the.** sync oper
5500: 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73  ation only needs
5510: 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20 74   to flush data t
5520: 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e 20  o mass storage. 
5530: 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d   Inode.** inform
5540: 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62  ation need not b
5550: 65 20 66 6c 75 73 68 65 64 2e 20 54 68 65 20 53  e flushed. The S
5560: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
5570: 4c 20 66 6c 61 67 20 6d 65 61 6e 73 20 0a 2a 2a  L flag means .**
5580: 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20 66   to use normal f
5590: 73 79 6e 63 28 29 20 73 65 6d 61 6e 74 69 63 73  sync() semantics
55a0: 2e 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59 4e  . The SQLITE_SYN
55b0: 43 5f 46 55 4c 4c 20 66 6c 61 67 20 6d 65 61 6e  C_FULL flag mean
55c0: 73 20 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63  s .** to use Mac
55d0: 20 4f 53 2d 58 20 73 74 79 6c 65 20 66 75 6c 6c   OS-X style full
55e0: 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f 66 20  sync instead of 
55f0: 66 73 79 6e 63 28 29 2e 0a 2a 2f 0a 23 64 65 66  fsync()..*/.#def
5600: 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ine SQLITE_SYNC_
5610: 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20 20 30 78  NORMAL        0x
5620: 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51  00002.#define SQ
5630: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 20  LITE_SYNC_FULL  
5640: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 33 0a          0x00003.
5650: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
5660: 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20 20 20  YNC_DATAONLY    
5670: 20 20 30 78 30 30 30 31 30 0a 0a 0a 2f 2a 0a 2a    0x00010.../*.*
5680: 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49  * CAPI3REF: OS I
5690: 6e 74 65 72 66 61 63 65 20 4f 70 65 6e 20 46 69  nterface Open Fi
56a0: 6c 65 20 48 61 6e 64 6c 65 20 7b 46 31 31 31 31  le Handle {F1111
56b0: 30 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c  0}.**.** An [sql
56c0: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
56d0: 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20  t represents an 
56e0: 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20 74 68 65  open file in the
56f0: 20 4f 53 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65   OS.** interface
5700: 20 6c 61 79 65 72 2e 20 20 49 6e 64 69 76 69 64   layer.  Individ
5710: 75 61 6c 20 4f 53 20 69 6e 74 65 72 66 61 63 65  ual OS interface
5720: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
5730: 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f   will.** want to
5740: 20 73 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f   subclass this o
5750: 62 6a 65 63 74 20 62 79 20 61 70 70 65 6e 64 69  bject by appendi
5760: 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69  ng additional fi
5770: 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69  elds.** for thei
5780: 72 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20  r own use.  The 
5790: 70 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69  pMethods entry i
57a0: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
57b0: 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f  n.** [sqlite3_io
57c0: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
57d0: 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65   that defines me
57e0: 74 68 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72  thods for perfor
57f0: 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72  ming.** I/O oper
5800: 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70  ations on the op
5810: 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65  en file..*/.type
5820: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
5830: 65 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f  e3_file sqlite3_
5840: 66 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c  file;.struct sql
5850: 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f  ite3_file {.  co
5860: 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c 69 74  nst struct sqlit
5870: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70  e3_io_methods *p
5880: 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74  Methods;  /* Met
5890: 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e  hods for an open
58a0: 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a   file */.};../*.
58b0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20  ** CAPI3REF: OS 
58c0: 49 6e 74 65 72 66 61 63 65 20 46 69 6c 65 20 56  Interface File V
58d0: 69 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f  irtual Methods O
58e0: 62 6a 65 63 74 20 7b 46 31 31 31 32 30 7d 0a 2a  bject {F11120}.*
58f0: 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69 6c 65 20  *.** Every file 
5900: 6f 70 65 6e 65 64 20 62 79 20 74 68 65 20 5b 73  opened by the [s
5910: 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 4f 70 65  qlite3_vfs] xOpe
5920: 6e 20 6d 65 74 68 6f 64 20 63 6f 6e 74 61 69 6e  n method contain
5930: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a  s a pointer to.*
5940: 2a 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  * an instance of
5950: 20 74 68 69 73 20 6f 62 6a 65 63 74 2e 20 20 54   this object.  T
5960: 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e  his object defin
5970: 65 73 20 74 68 65 0a 2a 2a 20 6d 65 74 68 6f 64  es the.** method
5980: 73 20 75 73 65 64 20 74 6f 20 70 65 72 66 6f 72  s used to perfor
5990: 6d 20 76 61 72 69 6f 75 73 20 6f 70 65 72 61 74  m various operat
59a0: 69 6f 6e 73 20 61 67 61 69 6e 73 74 20 74 68 65  ions against the
59b0: 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2a 0a 2a   open file..**.*
59c0: 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75  * The flags argu
59d0: 6d 65 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61  ment to xSync ma
59e0: 79 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c  y be one of [SQL
59f0: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d  ITE_SYNC_NORMAL]
5a00: 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53   or.** [SQLITE_S
5a10: 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20  YNC_FULL].  The 
5a20: 66 69 72 73 74 20 63 68 6f 69 63 65 20 69 73 20  first choice is 
5a30: 74 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63  the normal fsync
5a40: 28 29 2e 0a 2a 20 20 54 68 65 20 73 65 63 6f 6e  ()..*  The secon
5a50: 64 20 63 68 6f 69 63 65 20 69 73 20 61 6e 0a 2a  d choice is an.*
5a60: 2a 20 4f 53 2d 58 20 73 74 79 6c 65 20 66 75 6c  * OS-X style ful
5a70: 6c 73 79 6e 63 2e 20 20 54 68 65 20 53 51 4c 49  lsync.  The SQLI
5a80: 54 45 5f 53 59 4e 43 5f 44 41 54 41 20 66 6c 61  TE_SYNC_DATA fla
5a90: 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20 69 6e  g may be ORed in
5aa0: 20 74 6f 0a 2a 2a 20 69 6e 64 69 63 61 74 65 20   to.** indicate 
5ab0: 74 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61  that only the da
5ac0: 74 61 20 6f 66 20 74 68 65 20 66 69 6c 65 20 61  ta of the file a
5ad0: 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65  nd not its inode
5ae0: 20 6e 65 65 64 73 20 74 6f 20 62 65 0a 2a 2a 20   needs to be.** 
5af0: 73 79 6e 63 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 54  synced..** .** T
5b00: 68 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  he integer value
5b10: 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64  s to xLock() and
5b20: 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f   xUnlock() are o
5b30: 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  ne of.** <ul>.**
5b40: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
5b50: 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69  CK_NONE],.** <li
5b60: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53  > [SQLITE_LOCK_S
5b70: 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  HARED],.** <li> 
5b80: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53  [SQLITE_LOCK_RES
5b90: 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  ERVED],.** <li> 
5ba0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e  [SQLITE_LOCK_PEN
5bb0: 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69  DING], or.** <li
5bc0: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45  > [SQLITE_LOCK_E
5bd0: 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f  XCLUSIVE]..** </
5be0: 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69  ul>.** xLock() i
5bf0: 6e 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63  ncreases the loc
5c00: 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63  k. xUnlock() dec
5c10: 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e  reases the lock.
5c20: 20 20 0a 2a 2a 20 54 68 65 20 78 43 68 65 63 6b    .** The xCheck
5c30: 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d  ReservedLock() m
5c40: 65 74 68 6f 64 20 6c 6f 6f 6b 73 0a 2a 2a 20 74  ethod looks.** t
5c50: 6f 20 73 65 65 20 69 66 20 61 6e 79 20 64 61 74  o see if any dat
5c60: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
5c70: 2c 20 65 69 74 68 65 72 20 69 6e 20 74 68 69 73  , either in this
5c80: 0a 2a 2a 20 70 72 6f 63 65 73 73 20 6f 72 20 69  .** process or i
5c90: 6e 20 73 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f  n some other pro
5ca0: 63 65 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67  cess, is holding
5cb0: 20 61 6e 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a   an RESERVED,.**
5cc0: 20 50 45 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43   PENDING, or EXC
5cd0: 4c 55 53 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74  LUSIVE lock on t
5ce0: 68 65 20 66 69 6c 65 2e 20 20 49 74 20 72 65 74  he file.  It ret
5cf0: 75 72 6e 73 20 74 72 75 65 0a 2a 2a 20 69 66 20  urns true.** if 
5d00: 73 75 63 68 20 61 20 6c 6f 63 6b 20 65 78 69 73  such a lock exis
5d10: 74 73 20 61 6e 64 20 66 61 6c 73 65 20 69 66 20  ts and false if 
5d20: 6e 6f 74 2e 0a 2a 2a 20 0a 2a 2a 20 54 68 65 20  not..** .** The 
5d30: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d  xFileControl() m
5d40: 65 74 68 6f 64 20 69 73 20 61 20 67 65 6e 65 72  ethod is a gener
5d50: 69 63 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  ic interface tha
5d60: 74 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a  t allows custom.
5d70: 2a 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  ** VFS implement
5d80: 61 74 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 74  ations to direct
5d90: 6c 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70  ly control an op
5da0: 65 6e 20 66 69 6c 65 20 75 73 69 6e 67 20 74 68  en file using th
5db0: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  e.** [sqlite3_fi
5dc0: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e  le_control()] in
5dd0: 74 65 72 66 61 63 65 2e 20 20 54 68 65 20 73 65  terface.  The se
5de0: 63 6f 6e 64 20 22 6f 70 22 20 61 72 67 75 6d 65  cond "op" argume
5df0: 6e 74 0a 2a 2a 20 69 73 20 61 6e 20 69 6e 74 65  nt.** is an inte
5e00: 67 65 72 20 6f 70 63 6f 64 65 2e 20 20 20 54 68  ger opcode.   Th
5e10: 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d  e third.** argum
5e20: 65 6e 74 20 69 73 20 61 20 67 65 6e 65 72 69 63  ent is a generic
5e30: 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 20 69   pointer which i
5e40: 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 62 65  s intended to be
5e50: 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
5e60: 20 61 20 73 74 72 75 63 74 75 72 65 20 74 68 61   a structure tha
5e70: 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 61 72  t may contain ar
5e80: 67 75 6d 65 6e 74 73 20 6f 72 20 73 70 61 63 65  guments or space
5e90: 20 69 6e 20 77 68 69 63 68 20 74 6f 0a 2a 2a 20   in which to.** 
5ea0: 77 72 69 74 65 20 72 65 74 75 72 6e 20 76 61 6c  write return val
5eb0: 75 65 73 2e 20 20 50 6f 74 65 6e 74 69 61 6c 20  ues.  Potential 
5ec0: 75 73 65 73 20 66 6f 72 20 78 46 69 6c 65 43 6f  uses for xFileCo
5ed0: 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74 20 62 65  ntrol() might be
5ee0: 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f  .** functions to
5ef0: 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b 69 6e 67   enable blocking
5f00: 20 6c 6f 63 6b 73 20 77 69 74 68 20 74 69 6d 65   locks with time
5f10: 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e 67 65 20  outs, to change 
5f20: 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20 73  the.** locking s
5f30: 74 72 61 74 65 67 79 20 28 66 6f 72 20 65 78 61  trategy (for exa
5f40: 6d 70 6c 65 20 74 6f 20 75 73 65 20 64 6f 74 2d  mple to use dot-
5f50: 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 74 6f 20  file locks), to 
5f60: 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62 6f 75 74  inquire.** about
5f70: 20 74 68 65 20 73 74 61 74 75 73 20 6f 66 20 61   the status of a
5f80: 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 62 72 65   lock, or to bre
5f90: 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b 73 2e 20  ak stale locks. 
5fa0: 20 54 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 63   The SQLite.** c
5fb0: 6f 72 65 20 72 65 73 65 72 76 65 73 20 6f 70 63  ore reserves opc
5fc0: 6f 64 65 73 20 6c 65 73 73 20 74 68 61 6e 20 31  odes less than 1
5fd0: 30 30 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 75  00 for its own u
5fe0: 73 65 2e 20 0a 2a 2a 20 41 20 5b 53 51 4c 49 54  se. .** A [SQLIT
5ff0: 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54  E_FCNTL_LOCKSTAT
6000: 45 20 7c 20 6c 69 73 74 20 6f 66 20 6f 70 63 6f  E | list of opco
6010: 64 65 73 5d 20 6c 65 73 73 20 74 68 61 6e 20 31  des] less than 1
6020: 30 30 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e  00 is available.
6030: 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  .** Applications
6040: 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 20 63   that define a c
6050: 75 73 74 6f 6d 20 78 46 69 6c 65 43 6f 6e 74 72  ustom xFileContr
6060: 6f 6c 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64  ol method should
6070: 20 75 73 65 20 6f 70 63 6f 64 65 73 20 0a 2a 2a   use opcodes .**
6080: 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 31 30   greater than 10
6090: 30 20 74 6f 20 61 76 6f 69 64 20 63 6f 6e 66 6c  0 to avoid confl
60a0: 69 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  icts..**.** The 
60b0: 78 53 65 63 74 6f 72 53 69 7a 65 28 29 20 6d 65  xSectorSize() me
60c0: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 74 68 65  thod returns the
60d0: 20 73 65 63 74 6f 72 20 73 69 7a 65 20 6f 66 20   sector size of 
60e0: 74 68 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68  the.** device th
60f0: 61 74 20 75 6e 64 65 72 6c 69 65 73 20 74 68 65  at underlies the
6100: 20 66 69 6c 65 2e 20 20 54 68 65 20 73 65 63 74   file.  The sect
6110: 6f 72 20 73 69 7a 65 20 69 73 20 74 68 65 0a 2a  or size is the.*
6120: 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69 74 65 20  * minimum write 
6130: 74 68 61 74 20 63 61 6e 20 62 65 20 70 65 72 66  that can be perf
6140: 6f 72 6d 65 64 20 77 69 74 68 6f 75 74 20 64 69  ormed without di
6150: 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f 74 68 65  sturbing.** othe
6160: 72 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 66  r bytes in the f
6170: 69 6c 65 2e 20 20 54 68 65 20 78 44 65 76 69 63  ile.  The xDevic
6180: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73  eCharacteristics
6190: 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74  ().** method ret
61a0: 75 72 6e 73 20 61 20 62 69 74 20 76 65 63 74 6f  urns a bit vecto
61b0: 72 20 64 65 73 63 72 69 62 69 6e 67 20 62 65 68  r describing beh
61c0: 61 76 69 6f 72 73 20 6f 66 20 74 68 65 0a 2a 2a  aviors of the.**
61d0: 20 75 6e 64 65 72 6c 79 69 6e 67 20 64 65 76 69   underlying devi
61e0: 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  ce:.**.** <ul>.*
61f0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
6200: 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20  OCAP_ATOMIC].** 
6210: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
6220: 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a  AP_ATOMIC512].**
6230: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
6240: 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a  CAP_ATOMIC1K].**
6250: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
6260: 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a  CAP_ATOMIC2K].**
6270: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
6280: 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a  CAP_ATOMIC4K].**
6290: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
62a0: 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a  CAP_ATOMIC8K].**
62b0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
62c0: 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a  CAP_ATOMIC16K].*
62d0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
62e0: 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a  OCAP_ATOMIC32K].
62f0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
6300: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 5d  IOCAP_ATOMIC64K]
6310: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
6320: 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45  _IOCAP_SAFE_APPE
6330: 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  ND].** <li> [SQL
6340: 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e  ITE_IOCAP_SEQUEN
6350: 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  TIAL].** </ul>.*
6360: 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f  *.** The SQLITE_
6370: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f  IOCAP_ATOMIC pro
6380: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
6390: 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a   all writes of.*
63a0: 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61  * any size are a
63b0: 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49  tomic.  The SQLI
63c0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e  TE_IOCAP_ATOMICn
63d0: 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61  nn values.** mea
63e0: 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 6f 66  n that writes of
63f0: 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65   blocks that are
6400: 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69   nnn bytes in si
6410: 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c  ze and.** are al
6420: 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72  igned to an addr
6430: 65 73 73 20 77 68 69 63 68 20 69 73 20 61 6e 20  ess which is an 
6440: 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65  integer multiple
6450: 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61   of.** nnn are a
6460: 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49  tomic.  The SQLI
6470: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50  TE_IOCAP_SAFE_AP
6480: 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73  PEND value means
6490: 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61  .** that when da
64a0: 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 20 74  ta is appended t
64b0: 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61  o a file, the da
64c0: 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a  ta is appended.*
64d0: 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 68 65  * first then the
64e0: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c   size of the fil
64f0: 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e  e is extended, n
6500: 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a  ever the other.*
6510: 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54  * way around.  T
6520: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
6530: 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65  SEQUENTIAL prope
6540: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a  rty means that.*
6550: 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  * information is
6560: 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b   written to disk
6570: 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64   in the same ord
6580: 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74  er as calls.** t
6590: 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2f 0a 74  o xWrite()..*/.t
65a0: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
65b0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
65c0: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
65d0: 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69  ods;.struct sqli
65e0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b  te3_io_methods {
65f0: 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b  .  int iVersion;
6600: 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29  .  int (*xClose)
6610: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b  (sqlite3_file*);
6620: 0a 20 20 69 6e 74 20 28 2a 78 52 65 61 64 29 28  .  int (*xRead)(
6630: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76  sqlite3_file*, v
6640: 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20  oid*, int iAmt, 
6650: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f  sqlite3_int64 iO
6660: 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57  fst);.  int (*xW
6670: 72 69 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69  rite)(sqlite3_fi
6680: 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  le*, const void*
6690: 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69  , int iAmt, sqli
66a0: 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29  te3_int64 iOfst)
66b0: 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72 75 6e 63  ;.  int (*xTrunc
66c0: 61 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ate)(sqlite3_fil
66d0: 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  e*, sqlite3_int6
66e0: 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28  4 size);.  int (
66f0: 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f  *xSync)(sqlite3_
6700: 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73  file*, int flags
6710: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65  );.  int (*xFile
6720: 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69  Size)(sqlite3_fi
6730: 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  le*, sqlite3_int
6740: 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e  64 *pSize);.  in
6750: 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74  t (*xLock)(sqlit
6760: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a  e3_file*, int);.
6770: 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29    int (*xUnlock)
6780: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
6790: 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43  int);.  int (*xC
67a0: 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b  heckReservedLock
67b0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
67c0: 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 43  ;.  int (*xFileC
67d0: 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f  ontrol)(sqlite3_
67e0: 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76  file*, int op, v
67f0: 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e  oid *pArg);.  in
6800: 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65 29  t (*xSectorSize)
6810: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b  (sqlite3_file*);
6820: 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63 65  .  int (*xDevice
6830: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 29  Characteristics)
6840: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b  (sqlite3_file*);
6850: 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c  .  /* Additional
6860: 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65 20   methods may be 
6870: 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
6880: 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a  releases */.};..
6890: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
68a0: 53 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43 6f  Standard File Co
68b0: 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73 20 7b 46  ntrol Opcodes {F
68c0: 31 31 33 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  11310}.**.** The
68d0: 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74  se integer const
68e0: 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65 73  ants are opcodes
68f0: 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43 6f   for the xFileCo
6900: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20  ntrol method.** 
6910: 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
6920: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
6930: 63 74 20 61 6e 64 20 74 6f 20 74 68 65 20 5b 73  ct and to the [s
6940: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
6950: 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66  rol()].** interf
6960: 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  ace..**.** The [
6970: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43  SQLITE_FCNTL_LOC
6980: 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64 65 20 69  KSTATE] opcode i
6990: 73 20 75 73 65 64 20 66 6f 72 20 64 65 62 75 67  s used for debug
69a0: 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f  ging.  This.** o
69b0: 70 63 6f 64 65 20 63 61 75 73 65 73 20 74 68 65  pcode causes the
69c0: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65   xFileControl me
69d0: 74 68 6f 64 20 74 6f 20 77 72 69 74 65 20 74 68  thod to write th
69e0: 65 20 63 75 72 72 65 6e 74 20 73 74 61 74 65 20  e current state 
69f0: 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b 20 28  of.** the lock (
6a00: 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4c  one of [SQLITE_L
6a10: 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49  OCK_NONE], [SQLI
6a20: 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c  TE_LOCK_SHARED],
6a30: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  .** [SQLITE_LOCK
6a40: 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b 53 51 4c  _RESERVED], [SQL
6a50: 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47  ITE_LOCK_PENDING
6a60: 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4c 4f  ], or [SQLITE_LO
6a70: 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29 0a 2a  CK_EXCLUSIVE]).*
6a80: 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65 67 65  * into an intege
6a90: 72 20 74 68 61 74 20 74 68 65 20 70 41 72 67 20  r that the pArg 
6aa0: 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20  argument points 
6ab0: 74 6f 2e 20 54 68 69 73 20 63 61 70 61 62 69 6c  to. This capabil
6ac0: 69 74 79 0a 2a 2a 20 69 73 20 75 73 65 64 20 64  ity.** is used d
6ad0: 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20 61 6e  uring testing an
6ae0: 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20  d only needs to 
6af0: 62 65 20 73 75 70 70 6f 72 74 65 64 20 77 68 65  be supported whe
6b00: 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a  n SQLITE_TEST.**
6b10: 20 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a   is defined..*/.
6b20: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
6b30: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20  CNTL_LOCKSTATE  
6b40: 20 20 20 20 20 20 31 0a 0a 2f 2a 0a 2a 2a 20 43        1../*.** C
6b50: 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20 48  API3REF: Mutex H
6b60: 61 6e 64 6c 65 20 7b 46 31 37 31 31 30 7d 0a 2a  andle {F17110}.*
6b70: 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d  *.** The mutex m
6b80: 6f 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c  odule within SQL
6b90: 69 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c  ite defines [sql
6ba0: 69 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62  ite3_mutex] to b
6bb0: 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74  e an.** abstract
6bc0: 20 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65   type for a mute
6bd0: 78 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53  x object.  The S
6be0: 51 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72  QLite core never
6bf0: 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65   looks.** at the
6c00: 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73   internal repres
6c10: 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b  entation of an [
6c20: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20  sqlite3_mutex]. 
6c30: 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c   It only.** deal
6c40: 73 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20  s with pointers 
6c50: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
6c60: 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a  mutex] object..*
6c70: 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65  *.** Mutexes are
6c80: 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b   created using [
6c90: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c  sqlite3_mutex_al
6ca0: 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64  loc()]..*/.typed
6cb0: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
6cc0: 33 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f  3_mutex sqlite3_
6cd0: 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  mutex;../*.** CA
6ce0: 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72  PI3REF: OS Inter
6cf0: 66 61 63 65 20 4f 62 6a 65 63 74 20 7b 46 31 31  face Object {F11
6d00: 31 34 30 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e  140}.**.** An in
6d10: 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
6d20: 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68  bject defines th
6d30: 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77  e interface betw
6d40: 65 65 6e 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74  een the.** SQLit
6d50: 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20 75  e core and the u
6d60: 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 74  nderlying operat
6d70: 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68 65  ing system.  The
6d80: 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65   "vfs".** in the
6d90: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a   name of the obj
6da0: 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20 22  ect stands for "
6db0: 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73  virtual file sys
6dc0: 74 65 6d 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  tem"..**.** The 
6dd0: 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 69  iVersion field i
6de0: 73 20 69 6e 69 74 69 61 6c 6c 79 20 31 20 62 75  s initially 1 bu
6df0: 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 20  t may be larger 
6e00: 66 6f 72 20 66 75 74 75 72 65 0a 2a 2a 20 76 65  for future.** ve
6e10: 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
6e20: 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 66 69  .  Additional fi
6e30: 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70 65  elds may be appe
6e40: 6e 64 65 64 20 74 6f 20 74 68 69 73 0a 2a 2a 20  nded to this.** 
6e50: 6f 62 6a 65 63 74 20 77 68 65 6e 20 74 68 65 20  object when the 
6e60: 69 56 65 72 73 69 6f 6e 20 76 61 6c 75 65 20 69  iVersion value i
6e70: 73 20 69 6e 63 72 65 61 73 65 64 2e 0a 2a 2a 0a  s increased..**.
6e80: 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20  ** The szOsFile 
6e90: 66 69 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a  field is the siz
6ea0: 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73  e of the subclas
6eb0: 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  sed [sqlite3_fil
6ec0: 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  e].** structure 
6ed0: 75 73 65 64 20 62 79 20 74 68 69 73 20 56 46 53  used by this VFS
6ee0: 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73  .  mxPathname is
6ef0: 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e   the maximum len
6f00: 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68  gth of.** a path
6f10: 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53  name in this VFS
6f20: 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72  ..**.** Register
6f30: 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f  ed sqlite3_vfs o
6f40: 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74 20  bjects are kept 
6f50: 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74  on a linked list
6f60: 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68   formed by.** th
6f70: 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e  e pNext pointer.
6f80: 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76    The [sqlite3_v
6f90: 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a  fs_register()].*
6fa0: 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76  * and [sqlite3_v
6fb0: 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d  fs_unregister()]
6fc0: 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61   interfaces mana
6fd0: 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20  ge this list.** 
6fe0: 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66 65  in a thread-safe
6ff0: 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69   way.  The [sqli
7000: 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20  te3_vfs_find()] 
7010: 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61  interface.** sea
7020: 72 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e 0a  rches the list..
7030: 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74 20  **.** The pNext 
7040: 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c  field is the onl
7050: 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65 20 73  y field in the s
7060: 71 6c 69 74 65 33 5f 76 66 73 20 0a 2a 2a 20 73  qlite3_vfs .** s
7070: 74 72 75 63 74 75 72 65 20 74 68 61 74 20 53 51  tructure that SQ
7080: 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20 6d  Lite will ever m
7090: 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20 77  odify.  SQLite w
70a0: 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a  ill only access.
70b0: 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69  ** or modify thi
70c0: 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68 6f  s field while ho
70d0: 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63 75 6c  lding a particul
70e0: 61 72 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e  ar static mutex.
70f0: 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
7100: 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72  ion should never
7110: 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e 67   modify anything
7120: 20 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c 69   within the sqli
7130: 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63  te3_vfs.** objec
7140: 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 63  t once the objec
7150: 74 20 68 61 73 20 62 65 65 6e 20 72 65 67 69 73  t has been regis
7160: 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tered..**.** The
7170: 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c   zName field hol
7180: 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  ds the name of t
7190: 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20  he VFS module.  
71a0: 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a  The name must.**
71b0: 20 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f 73   be unique acros
71c0: 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65  s all VFS module
71d0: 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 31 34 31  s..**.** {F11141
71e0: 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 67 75  } SQLite will gu
71f0: 61 72 61 6e 74 65 65 20 74 68 61 74 20 74 68 65  arantee that the
7200: 20 7a 46 69 6c 65 6e 61 6d 65 20 73 74 72 69 6e   zFilename strin
7210: 67 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 78  g passed to.** x
7220: 4f 70 65 6e 28 29 20 69 73 20 61 20 66 75 6c 6c  Open() is a full
7230: 20 70 61 74 68 6e 61 6d 65 20 61 73 20 67 65 6e   pathname as gen
7240: 65 72 61 74 65 64 20 62 79 20 78 46 75 6c 6c 50  erated by xFullP
7250: 61 74 68 6e 61 6d 65 28 29 20 61 6e 64 0a 2a 2a  athname() and.**
7260: 20 74 68 61 74 20 74 68 65 20 73 74 72 69 6e 67   that the string
7270: 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61   will be valid a
7280: 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75 6e 74  nd unchanged unt
7290: 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a  il xClose() is.*
72a0: 2a 20 63 61 6c 6c 65 64 2e 20 20 7b 45 4e 44 7d  * called.  {END}
72b0: 20 53 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   So the [sqlite3
72c0: 5f 66 69 6c 65 5d 20 63 61 6e 20 73 74 6f 72 65  _file] can store
72d0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
72e0: 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66  e.** filename if
72f0: 20 69 74 20 6e 65 65 64 73 20 74 6f 20 72 65 6d   it needs to rem
7300: 65 6d 62 65 72 20 74 68 65 20 66 69 6c 65 6e 61  ember the filena
7310: 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73  me for some reas
7320: 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 31 34  on..**.** {F1114
7330: 32 7d 20 54 68 65 20 66 6c 61 67 73 20 61 72 67  2} The flags arg
7340: 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29  ument to xOpen()
7350: 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62 69   includes all bi
7360: 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65  ts set in.** the
7370: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
7380: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  to [sqlite3_open
7390: 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b  _v2()].  Or if [
73a0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a  sqlite3_open()].
73b0: 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f  ** or [sqlite3_o
73c0: 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65 64  pen16()] is used
73d0: 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69 6e 63  , then flags inc
73e0: 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74 0a 2a  ludes at least.*
73f0: 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  * [SQLITE_OPEN_R
7400: 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c  EADWRITE] | [SQL
7410: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d  ITE_OPEN_CREATE]
7420: 2e 20 7b 45 4e 44 7d 0a 2a 2a 20 49 66 20 78 4f  . {END}.** If xO
7430: 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 69  pen() opens a fi
7440: 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65  le read-only the
7450: 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74 46  n it sets *pOutF
7460: 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75  lags to.** inclu
7470: 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  de [SQLITE_OPEN_
7480: 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65  READONLY].  Othe
7490: 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 46  r bits in *pOutF
74a0: 6c 61 67 73 20 6d 61 79 20 62 65 0a 2a 2a 20 73  lags may be.** s
74b0: 65 74 2e 0a 2a 2a 20 0a 2a 2a 20 7b 46 31 31 31  et..** .** {F111
74c0: 34 33 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  43} SQLite will 
74d0: 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20  also add one of 
74e0: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c  the following fl
74f0: 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e  ags to the xOpen
7500: 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65  ().** call, depe
7510: 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a  nding on the obj
7520: 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64  ect being opened
7530: 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  :.** .** <ul>.**
7540: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
7550: 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20  PEN_MAIN_DB].** 
7560: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
7570: 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d  EN_MAIN_JOURNAL]
7580: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
7590: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a  E_OPEN_TEMP_DB].
75a0: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
75b0: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e  _OPEN_TEMP_JOURN
75c0: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  AL].** <li>  [SQ
75d0: 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49  LITE_OPEN_TRANSI
75e0: 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20  ENT_DB].** <li> 
75f0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55   [SQLITE_OPEN_SU
7600: 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69  BJOURNAL].** <li
7610: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
7620: 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a  MASTER_JOURNAL].
7630: 2a 2a 20 3c 2f 75 6c 3e 20 7b 45 4e 44 7d 0a 2a  ** </ul> {END}.*
7640: 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20 49 2f  *.** The file I/
7650: 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  O implementation
7660: 20 63 61 6e 20 75 73 65 20 74 68 65 20 6f 62 6a   can use the obj
7670: 65 63 74 20 74 79 70 65 20 66 6c 61 67 73 20 74  ect type flags t
7680: 6f 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 68 65  o.** changes the
7690: 20 77 61 79 20 69 74 20 64 65 61 6c 73 20 77 69   way it deals wi
76a0: 74 68 20 66 69 6c 65 73 2e 20 20 46 6f 72 20 65  th files.  For e
76b0: 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69  xample, an appli
76c0: 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 64  cation.** that d
76d0: 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 61 62 6f  oes not care abo
76e0: 75 74 20 63 72 61 73 68 20 72 65 63 6f 76 65 72  ut crash recover
76f0: 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d 69  y or rollback mi
7700: 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65 20  ght make.** the 
7710: 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e 61  open of a journa
7720: 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20  l file a no-op. 
7730: 20 57 72 69 74 65 73 20 74 6f 20 74 68 69 73 20   Writes to this 
7740: 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a  journal would.**
7750: 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c   also be no-ops,
7760: 20 61 6e 64 20 61 6e 79 20 61 74 74 65 6d 70 74   and any attempt
7770: 20 74 6f 20 72 65 61 64 20 74 68 65 20 6a 6f 75   to read the jou
7780: 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74 75 72  rnal would retur
7790: 6e 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 45  n .** SQLITE_IOE
77a0: 52 52 2e 20 20 4f 72 20 74 68 65 20 69 6d 70 6c  RR.  Or the impl
77b0: 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74  ementation might
77c0: 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 61 74 20   recognize that 
77d0: 61 20 64 61 74 61 62 61 73 65 20 0a 2a 2a 20 66  a database .** f
77e0: 69 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f 69 6e  ile will be doin
77f0: 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 20 73  g page-aligned s
7800: 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e 64 20  ector reads and 
7810: 77 72 69 74 65 73 20 69 6e 20 61 20 72 61 6e 64  writes in a rand
7820: 6f 6d 20 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64  om .** order and
7830: 20 73 65 74 20 75 70 20 69 74 73 20 49 2f 4f 20   set up its I/O 
7840: 73 75 62 73 79 73 74 65 6d 20 61 63 63 6f 72 64  subsystem accord
7850: 69 6e 67 6c 79 2e 0a 2a 2a 20 0a 2a 2a 20 53 51  ingly..** .** SQ
7860: 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f 20  Lite might also 
7870: 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66  add one of the f
7880: 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74  ollowing flags t
7890: 6f 20 74 68 65 20 78 4f 70 65 6e 0a 2a 2a 20 6d  o the xOpen.** m
78a0: 65 74 68 6f 64 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75  ethod:.** .** <u
78b0: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
78c0: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
78d0: 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  CLOSE].** <li> [
78e0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
78f0: 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a  USIVE].** </ul>.
7900: 2a 2a 20 0a 2a 2a 20 7b 46 31 31 31 34 35 7d 20  ** .** {F11145} 
7910: 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  The [SQLITE_OPEN
7920: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20  _DELETEONCLOSE] 
7930: 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66  flag means the f
7940: 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a  ile should be.**
7950: 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69 74   deleted when it
7960: 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 7b 46 31   is closed.  {F1
7970: 31 31 34 36 7d 20 54 68 65 20 5b 53 51 4c 49 54  1146} The [SQLIT
7980: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
7990: 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65  LOSE].** will be
79a0: 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20 20 64   set for TEMP  d
79b0: 61 74 61 62 61 73 65 73 2c 20 6a 6f 75 72 6e 61  atabases, journa
79c0: 6c 73 20 61 6e 64 20 66 6f 72 20 73 75 62 6a 6f  ls and for subjo
79d0: 75 72 6e 61 6c 73 2e 20 0a 2a 2a 20 7b 46 31 31  urnals. .** {F11
79e0: 31 34 37 7d 20 54 68 65 20 5b 53 51 4c 49 54 45  147} The [SQLITE
79f0: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d  _OPEN_EXCLUSIVE]
7a00: 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20   flag means the 
7a10: 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 6f  file should be o
7a20: 70 65 6e 65 64 0a 2a 2a 20 66 6f 72 20 65 78 63  pened.** for exc
7a30: 6c 75 73 69 76 65 20 61 63 63 65 73 73 2e 20 20  lusive access.  
7a40: 54 68 69 73 20 66 6c 61 67 20 69 73 20 73 65 74  This flag is set
7a50: 20 66 6f 72 20 61 6c 6c 20 66 69 6c 65 73 20 65   for all files e
7a60: 78 63 65 70 74 0a 2a 2a 20 66 6f 72 20 74 68 65  xcept.** for the
7a70: 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20 66   main database f
7a80: 69 6c 65 2e 20 7b 45 4e 44 7d 0a 2a 2a 20 0a 2a  ile. {END}.** .*
7a90: 2a 20 7b 46 31 31 31 34 38 7d 20 41 74 20 6c 65  * {F11148} At le
7aa0: 61 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 74  ast szOsFile byt
7ab0: 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65  es of memory are
7ac0: 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51   allocated by SQ
7ad0: 4c 69 74 65 20 0a 2a 2a 20 74 6f 20 68 6f 6c 64  Lite .** to hold
7ae0: 20 74 68 65 20 20 5b 73 71 6c 69 74 65 33 5f 66   the  [sqlite3_f
7af0: 69 6c 65 5d 20 73 74 72 75 63 74 75 72 65 20 70  ile] structure p
7b00: 61 73 73 65 64 20 61 73 20 74 68 65 20 74 68 69  assed as the thi
7b10: 72 64 20 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  rd .** argument 
7b20: 74 6f 20 78 4f 70 65 6e 2e 20 20 7b 45 4e 44 7d  to xOpen.  {END}
7b30: 20 20 54 68 65 20 78 4f 70 65 6e 20 6d 65 74 68    The xOpen meth
7b40: 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65  od does not have
7b50: 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20   to.** allocate 
7b60: 74 68 65 20 73 74 72 75 63 74 75 72 65 3b 20 69  the structure; i
7b70: 74 20 73 68 6f 75 6c 64 20 6a 75 73 74 20 66 69  t should just fi
7b80: 6c 6c 20 69 74 20 69 6e 2e 0a 2a 2a 20 0a 2a 2a  ll it in..** .**
7b90: 20 7b 46 31 31 31 34 39 7d 20 54 68 65 20 66 6c   {F11149} The fl
7ba0: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ags argument to 
7bb0: 78 41 63 63 65 73 73 28 29 20 6d 61 79 20 62 65  xAccess() may be
7bc0: 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f   [SQLITE_ACCESS_
7bd0: 45 58 49 53 54 53 5d 20 0a 2a 2a 20 74 6f 20 74  EXISTS] .** to t
7be0: 65 73 74 20 66 6f 72 20 74 68 65 20 65 78 69 73  est for the exis
7bf0: 74 61 6e 63 65 20 6f 66 20 61 20 66 69 6c 65 2c  tance of a file,
7c00: 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41  .** or [SQLITE_A
7c10: 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 5d  CCESS_READWRITE]
7c20: 20 74 6f 20 74 65 73 74 20 74 6f 20 73 65 65 0a   to test to see.
7c30: 2a 2a 20 69 66 20 61 20 66 69 6c 65 20 69 73 20  ** if a file is 
7c40: 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69  readable and wri
7c50: 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54  table, or [SQLIT
7c60: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a  E_ACCESS_READ].*
7c70: 2a 20 74 6f 20 74 65 73 74 20 74 6f 20 73 65 65  * to test to see
7c80: 20 69 66 20 61 20 66 69 6c 65 20 69 73 20 61 74   if a file is at
7c90: 20 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e   least readable.
7ca0: 20 20 7b 45 4e 44 7d 20 54 68 65 20 66 69 6c 65    {END} The file
7cb0: 20 63 61 6e 20 62 65 20 61 20 0a 2a 2a 20 64 69   can be a .** di
7cc0: 72 65 63 74 6f 72 79 2e 0a 2a 2a 20 0a 2a 2a 20  rectory..** .** 
7cd0: 7b 46 31 31 31 35 30 7d 20 53 51 4c 69 74 65 20  {F11150} SQLite 
7ce0: 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f  will always allo
7cf0: 63 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78  cate at least mx
7d00: 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73  Pathname+1 bytes
7d10: 20 66 6f 72 0a 2a 2a 20 74 68 65 20 6f 75 74 70   for.** the outp
7d20: 75 74 20 62 75 66 66 65 72 73 20 66 6f 72 20 78  ut buffers for x
7d30: 47 65 74 54 65 6d 70 6e 61 6d 65 20 61 6e 64 20  GetTempname and 
7d40: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 7b  xFullPathname. {
7d50: 46 31 31 31 35 31 7d 20 54 68 65 20 65 78 61 63  F11151} The exac
7d60: 74 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 74 68 65  t.** size of the
7d70: 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 20 69   output buffer i
7d80: 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61 73  s also passed as
7d90: 20 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20   a parameter to 
7da0: 62 6f 74 68 20 0a 2a 2a 20 6d 65 74 68 6f 64 73  both .** methods
7db0: 2e 20 7b 45 4e 44 7d 20 49 66 20 74 68 65 20 6f  . {END} If the o
7dc0: 75 74 70 75 74 20 62 75 66 66 65 72 20 69 73 20  utput buffer is 
7dd0: 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75 67 68  not large enough
7de0: 2c 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45  , SQLITE_CANTOPE
7df0: 4e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72  N.** should be r
7e00: 65 74 75 72 6e 65 64 2e 20 41 73 20 74 68 69 73  eturned. As this
7e10: 20 69 73 20 68 61 6e 64 6c 65 64 20 61 73 20 61   is handled as a
7e20: 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20   fatal error by 
7e30: 53 51 4c 69 74 65 2c 0a 2a 2a 20 76 66 73 20 69  SQLite,.** vfs i
7e40: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73  mplementations s
7e50: 68 6f 75 6c 64 20 65 6e 64 65 61 76 6f 72 20 74  hould endeavor t
7e60: 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73 20 62  o prevent this b
7e70: 79 20 73 65 74 74 69 6e 67 20 0a 2a 2a 20 6d 78  y setting .** mx
7e80: 50 61 74 68 6e 61 6d 65 20 74 6f 20 61 20 73 75  Pathname to a su
7e90: 66 66 69 63 69 65 6e 74 6c 79 20 6c 61 72 67 65  fficiently large
7ea0: 20 76 61 6c 75 65 2e 0a 2a 2a 20 0a 2a 2a 20 54   value..** .** T
7eb0: 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29  he xRandomness()
7ec0: 2c 20 78 53 6c 65 65 70 28 29 2c 20 61 6e 64 20  , xSleep(), and 
7ed0: 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69  xCurrentTime() i
7ee0: 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 61 72 65  nterfaces.** are
7ef0: 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20   not strictly a 
7f00: 70 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65  part of the file
7f10: 73 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79  system, but they
7f20: 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64   are.** included
7f30: 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 72 75   in the VFS stru
7f40: 63 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65  cture for comple
7f50: 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78  teness..** The x
7f60: 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e  Randomness() fun
7f70: 63 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74  ction attempts t
7f80: 6f 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20  o return nBytes 
7f90: 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64  bytes.** of good
7fa0: 2d 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e  -quality randomn
7fb0: 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20  ess into zOut.  
7fc0: 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  The return value
7fd0: 20 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61   is.** the actua
7fe0: 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  l number of byte
7ff0: 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20  s of randomness 
8000: 6f 62 74 61 69 6e 65 64 2e 20 20 54 68 65 0a 2a  obtained.  The.*
8010: 2a 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f  * xSleep() metho
8020: 64 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c  d causes the cal
8030: 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73  ling thread to s
8040: 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c  leep for at.** l
8050: 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20  east the number 
8060: 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20  of microseconds 
8070: 67 69 76 65 6e 2e 20 20 54 68 65 20 78 43 75 72  given.  The xCur
8080: 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65  rentTime().** me
8090: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a  thod returns a J
80a0: 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72  ulian Day Number
80b0: 20 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74   for the current
80c0: 20 64 61 74 65 20 61 6e 64 0a 2a 2a 20 74 69 6d   date and.** tim
80d0: 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  e..*/.typedef st
80e0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73  ruct sqlite3_vfs
80f0: 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 73 74   sqlite3_vfs;.st
8100: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73  ruct sqlite3_vfs
8110: 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f   {.  int iVersio
8120: 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  n;            /*
8130: 20 53 74 72 75 63 74 75 72 65 20 76 65 72 73 69   Structure versi
8140: 6f 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a 20 20 69  on number */.  i
8150: 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20  nt szOsFile;    
8160: 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 20          /* Size 
8170: 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20 73 71  of subclassed sq
8180: 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20  lite3_file */.  
8190: 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20  int mxPathname; 
81a0: 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
81b0: 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 6d  mum file pathnam
81c0: 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71  e length */.  sq
81d0: 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 74  lite3_vfs *pNext
81e0: 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 72  ;      /* Next r
81f0: 65 67 69 73 74 65 72 65 64 20 56 46 53 20 2a 2f  egistered VFS */
8200: 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
8210: 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e  Name;       /* N
8220: 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72 74  ame of this virt
8230: 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 20  ual file system 
8240: 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44  */.  void *pAppD
8250: 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  ata;          /*
8260: 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 6c   Pointer to appl
8270: 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63  ication-specific
8280: 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28   data */.  int (
8290: 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f  *xOpen)(sqlite3_
82a0: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
82b0: 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33   *zName, sqlite3
82c0: 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20  _file*,.        
82d0: 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67 73         int flags
82e0: 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73  , int *pOutFlags
82f0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c 65  );.  int (*xDele
8300: 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  te)(sqlite3_vfs*
8310: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
8320: 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 72  ame, int syncDir
8330: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 65  );.  int (*xAcce
8340: 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ss)(sqlite3_vfs*
8350: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
8360: 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b  ame, int flags);
8370: 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 54 65 6d  .  int (*xGetTem
8380: 70 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76  pname)(sqlite3_v
8390: 66 73 2a 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63  fs*, int nOut, c
83a0: 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e  har *zOut);.  in
83b0: 74 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d  t (*xFullPathnam
83c0: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
83d0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
83e0: 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68  me, int nOut, ch
83f0: 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69  ar *zOut);.  voi
8400: 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71  d *(*xDlOpen)(sq
8410: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
8420: 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d  t char *zFilenam
8430: 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c  e);.  void (*xDl
8440: 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76  Error)(sqlite3_v
8450: 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20  fs*, int nByte, 
8460: 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a  char *zErrMsg);.
8470: 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c 53 79 6d    void *(*xDlSym
8480: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76  )(sqlite3_vfs*,v
8490: 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  oid*, const char
84a0: 20 2a 7a 53 79 6d 62 6f 6c 29 3b 0a 20 20 76 6f   *zSymbol);.  vo
84b0: 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29 28 73  id (*xDlClose)(s
84c0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76 6f 69  qlite3_vfs*, voi
84d0: 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 61  d*);.  int (*xRa
84e0: 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69 74 65  ndomness)(sqlite
84f0: 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74  3_vfs*, int nByt
8500: 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a  e, char *zOut);.
8510: 20 20 69 6e 74 20 28 2a 78 53 6c 65 65 70 29 28    int (*xSleep)(
8520: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e  sqlite3_vfs*, in
8530: 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 29 3b  t microseconds);
8540: 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65 6e  .  int (*xCurren
8550: 74 54 69 6d 65 29 28 73 71 6c 69 74 65 33 5f 76  tTime)(sqlite3_v
8560: 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a 20  fs*, double*);. 
8570: 20 2f 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d   /* New fields m
8580: 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 69  ay be appended i
8590: 6e 20 66 69 67 75 72 65 20 76 65 72 73 69 6f 6e  n figure version
85a0: 73 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e  s.  The iVersion
85b0: 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c  .  ** value will
85c0: 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65   increment whene
85d0: 76 65 72 20 74 68 69 73 20 68 61 70 70 65 6e 73  ver this happens
85e0: 2e 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43  . */.};../*.** C
85f0: 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66  API3REF: Flags f
8600: 6f 72 20 74 68 65 20 78 41 63 63 65 73 73 20 56  or the xAccess V
8610: 46 53 20 6d 65 74 68 6f 64 20 7b 46 31 31 31 39  FS method {F1119
8620: 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 31 39 31  0}.**.** {F11191
8630: 7d 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20  } These integer 
8640: 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62 65  constants can be
8650: 20 75 73 65 64 20 61 73 20 74 68 65 20 74 68 69   used as the thi
8660: 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  rd parameter to.
8670: 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  ** the xAccess m
8680: 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c  ethod of an [sql
8690: 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
86a0: 2e 20 7b 45 4e 44 7d 20 20 54 68 65 79 20 64 65  . {END}  They de
86b0: 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20  termine.** what 
86c0: 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 73 69  kind of permissi
86d0: 6f 6e 73 20 74 68 65 20 78 41 63 63 65 73 73 20  ons the xAccess 
86e0: 6d 65 74 68 6f 64 20 69 73 0a 2a 2a 20 6c 6f 6f  method is.** loo
86f0: 6b 69 6e 67 20 66 6f 72 2e 20 20 7b 46 31 31 31  king for.  {F111
8700: 39 32 7d 20 57 69 74 68 20 53 51 4c 49 54 45 5f  92} With SQLITE_
8710: 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20 74  ACCESS_EXISTS, t
8720: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
8730: 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65 63  d.** simply chec
8740: 6b 73 20 74 6f 20 73 65 65 20 69 66 20 74 68 65  ks to see if the
8750: 20 66 69 6c 65 20 65 78 69 73 74 73 2e 20 7b 46   file exists. {F
8760: 31 31 31 39 33 7d 20 57 69 74 68 0a 2a 2a 20 53  11193} With.** S
8770: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
8780: 44 57 52 49 54 45 2c 20 74 68 65 20 78 41 63 63  DWRITE, the xAcc
8790: 65 73 73 20 6d 65 74 68 6f 64 20 63 68 65 63 6b  ess method check
87a0: 73 20 74 6f 20 73 65 65 0a 2a 2a 20 69 66 20 74  s to see.** if t
87b0: 68 65 20 66 69 6c 65 20 69 73 20 62 6f 74 68 20  he file is both 
87c0: 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69  readable and wri
87d0: 74 61 62 6c 65 2e 20 20 7b 46 31 31 31 39 34 7d  table.  {F11194}
87e0: 20 57 69 74 68 0a 2a 2a 20 53 51 4c 49 54 45 5f   With.** SQLITE_
87f0: 41 43 43 45 53 53 5f 52 45 41 44 20 74 68 65 20  ACCESS_READ the 
8800: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a  xAccess method.*
8810: 2a 20 63 68 65 63 6b 73 20 74 6f 20 73 65 65 20  * checks to see 
8820: 69 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 72  if the file is r
8830: 65 61 64 61 62 6c 65 2e 0a 2a 2f 0a 23 64 65 66  eadable..*/.#def
8840: 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ine SQLITE_ACCES
8850: 53 5f 45 58 49 53 54 53 20 20 20 20 30 0a 23 64  S_EXISTS    0.#d
8860: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43  efine SQLITE_ACC
8870: 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 31 0a  ESS_READWRITE 1.
8880: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
8890: 43 43 45 53 53 5f 52 45 41 44 20 20 20 20 20 20  CCESS_READ      
88a0: 32 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  2../*.** CAPI3RE
88b0: 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73  F: Enable Or Dis
88c0: 61 62 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65  able Extended Re
88d0: 73 75 6c 74 20 43 6f 64 65 73 20 7b 46 31 32 32  sult Codes {F122
88e0: 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  00}.**.** The sq
88f0: 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72  lite3_extended_r
8900: 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f  esult_codes() ro
8910: 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72  utine enables or
8920: 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a   disables the.**
8930: 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52   [SQLITE_IOERR_R
8940: 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64 20 72  EAD | extended r
8950: 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61  esult codes] fea
8960: 74 75 72 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ture of SQLite..
8970: 2a 2a 20 54 68 65 20 65 78 74 65 6e 64 65 64 20  ** The extended 
8980: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
8990: 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66   disabled by def
89a0: 61 75 6c 74 20 66 6f 72 20 68 69 73 74 6f 72 69  ault for histori
89b0: 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69  cal.** compatibi
89c0: 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  lity..**.** INVA
89d0: 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  RIANTS:.**.** {F
89e0: 31 32 32 30 31 7d 20 45 61 63 68 20 6e 65 77 20  12201} Each new 
89f0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
8a00: 74 69 6f 6e 5d 20 68 61 73 20 74 68 65 20 0a 2a  tion] has the .*
8a10: 2a 20 20 20 20 20 20 20 20 20 20 5b 65 78 74 65  *          [exte
8a20: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
8a30: 73 5d 20 66 65 61 74 75 72 65 0a 2a 2a 20 20 20  s] feature.**   
8a40: 20 20 20 20 20 20 20 64 69 73 61 62 6c 65 64 20         disabled 
8a50: 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a  by default..**.*
8a60: 2a 20 7b 46 31 32 32 30 32 7d 20 54 68 65 20 5b  * {F12202} The [
8a70: 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
8a80: 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 44 2c  _result_codes(D,
8a90: 46 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69  F)] interface wi
8aa0: 6c 6c 20 65 6e 61 62 6c 65 0a 2a 2a 20 20 20 20  ll enable.**    
8ab0: 20 20 20 20 20 20 5b 65 78 74 65 6e 64 65 64 20        [extended 
8ac0: 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 6f  result codes] fo
8ad0: 72 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 20 20  r the .**       
8ae0: 20 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e     [database con
8af0: 6e 65 63 74 69 6f 6e 5d 20 44 20 69 66 20 74 68  nection] D if th
8b00: 65 20 46 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  e F parameter.**
8b10: 20 20 20 20 20 20 20 20 20 20 69 73 20 74 72 75            is tru
8b20: 65 2c 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68  e, or disable th
8b30: 65 6d 20 69 66 20 46 20 69 73 20 66 61 6c 73 65  em if F is false
8b40: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
8b50: 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74  _extended_result
8b60: 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a 2c  _codes(sqlite3*,
8b70: 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a   int onoff);../*
8b80: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 61  .** CAPI3REF: La
8b90: 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64 20  st Insert Rowid 
8ba0: 7b 46 31 32 32 32 30 7d 0a 2a 2a 0a 2a 2a 20 45  {F12220}.**.** E
8bb0: 61 63 68 20 65 6e 74 72 79 20 69 6e 20 61 6e 20  ach entry in an 
8bc0: 53 51 4c 69 74 65 20 74 61 62 6c 65 20 68 61 73  SQLite table has
8bd0: 20 61 20 75 6e 69 71 75 65 20 36 34 2d 62 69 74   a unique 64-bit
8be0: 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67   signed.** integ
8bf0: 65 72 20 6b 65 79 20 63 61 6c 6c 65 64 20 74 68  er key called th
8c00: 65 20 22 72 6f 77 69 64 22 2e 20 54 68 65 20 72  e "rowid". The r
8c10: 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73 20 61  owid is always a
8c20: 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61  vailable.** as a
8c30: 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c  n undeclared col
8c40: 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c  umn named ROWID,
8c50: 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f   OID, or _ROWID_
8c60: 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73   as long as thos
8c70: 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e  e.** names are n
8c80: 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20  ot also used by 
8c90: 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61  explicitly decla
8ca0: 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 49 66 0a  red columns. If.
8cb0: 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61 73  ** the table has
8cc0: 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70   a column of typ
8cd0: 65 20 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52  e INTEGER PRIMAR
8ce0: 59 20 4b 45 59 20 74 68 65 6e 20 74 68 61 74 20  Y KEY then that 
8cf0: 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f  column.** is ano
8d00: 74 68 65 72 20 61 6c 69 61 73 20 66 6f 72 20 74  ther alias for t
8d10: 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20  he rowid..**.** 
8d20: 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  This routine ret
8d30: 75 72 6e 73 20 74 68 65 20 72 6f 77 69 64 20 6f  urns the rowid o
8d40: 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
8d50: 74 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20  t.** successful 
8d60: 49 4e 53 45 52 54 20 69 6e 74 6f 20 74 68 65 20  INSERT into the 
8d70: 64 61 74 61 62 61 73 65 20 66 72 6f 6d 20 74 68  database from th
8d80: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
8d90: 63 74 69 6f 6e 0a 2a 2a 20 73 68 6f 77 6e 20 69  ction.** shown i
8da0: 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
8db0: 6d 65 6e 74 2e 20 20 49 66 20 6e 6f 20 73 75 63  ment.  If no suc
8dc0: 63 65 73 73 66 75 6c 20 69 6e 73 65 72 74 73 0a  cessful inserts.
8dd0: 2a 2a 20 68 61 76 65 20 65 76 65 72 20 6f 63 63  ** have ever occ
8de0: 75 72 72 65 64 20 6f 6e 20 74 68 69 73 20 64 61  urred on this da
8df0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
8e00: 6e 2c 20 7a 65 72 6f 20 69 73 20 72 65 74 75 72  n, zero is retur
8e10: 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e  ned..**.** If an
8e20: 20 49 4e 53 45 52 54 20 6f 63 63 75 72 73 20 77   INSERT occurs w
8e30: 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 2c  ithin a trigger,
8e40: 20 74 68 65 6e 20 74 68 65 20 72 6f 77 69 64 20   then the rowid 
8e50: 6f 66 20 74 68 65 0a 2a 2a 20 69 6e 73 65 72 74  of the.** insert
8e60: 65 64 20 72 6f 77 20 69 73 20 72 65 74 75 72 6e  ed row is return
8e70: 65 64 20 62 79 20 74 68 69 73 20 72 6f 75 74 69  ed by this routi
8e80: 6e 65 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  ne as long as th
8e90: 65 20 74 72 69 67 67 65 72 0a 2a 2a 20 69 73 20  e trigger.** is 
8ea0: 72 75 6e 6e 69 6e 67 2e 20 20 42 75 74 20 6f 6e  running.  But on
8eb0: 63 65 20 74 68 65 20 74 72 69 67 67 65 72 20 74  ce the trigger t
8ec0: 65 72 6d 69 6e 61 74 65 73 2c 20 74 68 65 20 76  erminates, the v
8ed0: 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a  alue returned.**
8ee0: 20 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65   by this routine
8ef0: 20 72 65 76 65 72 74 73 20 74 6f 20 74 68 65 20   reverts to the 
8f00: 6c 61 73 74 20 76 61 6c 75 65 20 69 6e 73 65 72  last value inser
8f10: 74 65 64 20 62 65 66 6f 72 65 20 74 68 65 0a 2a  ted before the.*
8f20: 2a 20 74 72 69 67 67 65 72 20 66 69 72 65 64 2e  * trigger fired.
8f30: 0a 2a 2a 0a 2a 2a 20 41 6e 20 49 4e 53 45 52 54  .**.** An INSERT
8f40: 20 74 68 61 74 20 66 61 69 6c 73 20 64 75 65 20   that fails due 
8f50: 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20  to a constraint 
8f60: 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74  violation is not
8f70: 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c   a.** successful
8f80: 20 69 6e 73 65 72 74 20 61 6e 64 20 64 6f 65 73   insert and does
8f90: 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20   not change the 
8fa0: 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
8fb0: 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e  y this.** routin
8fc0: 65 2e 20 20 54 68 75 73 20 49 4e 53 45 52 54 20  e.  Thus INSERT 
8fd0: 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 54 20  OR FAIL, INSERT 
8fe0: 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52  OR IGNORE, INSER
8ff0: 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a  T OR ROLLBACK,.*
9000: 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f 52 20  * and INSERT OR 
9010: 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68  ABORT make no ch
9020: 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72 65 74  anges to the ret
9030: 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69  urn value of thi
9040: 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68 65  s.** routine whe
9050: 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74 69 6f  n their insertio
9060: 6e 20 66 61 69 6c 73 2e 20 20 57 68 65 6e 20 49  n fails.  When I
9070: 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45  NSERT OR REPLACE
9080: 20 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20   .** encounters 
9090: 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f  a constraint vio
90a0: 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20  lation, it does 
90b0: 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a  not fail.  The.*
90c0: 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75  * INSERT continu
90d0: 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e  es to completion
90e0: 20 61 66 74 65 72 20 64 65 6c 65 74 69 6e 67 20   after deleting 
90f0: 72 6f 77 73 20 74 68 61 74 20 63 61 75 73 65 64  rows that caused
9100: 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72 61 69  .** the constrai
9110: 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e  nt problem so IN
9120: 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 20  SERT OR REPLACE 
9130: 77 69 6c 6c 20 61 6c 77 61 79 73 20 63 68 61 6e  will always chan
9140: 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 6e  ge.** the return
9150: 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20 69   value of this i
9160: 6e 74 65 72 66 61 63 65 2e 20 0a 2a 2a 0a 2a 2a  nterface. .**.**
9170: 20 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65   For the purpose
9180: 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e  s of this routin
9190: 65 2c 20 61 6e 20 69 6e 73 65 72 74 20 69 73 20  e, an insert is 
91a0: 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a  considered to.**
91b0: 20 62 65 20 73 75 63 63 65 73 73 66 75 6c 20 65   be successful e
91c0: 76 65 6e 20 69 66 20 69 74 20 69 73 20 73 75 62  ven if it is sub
91d0: 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64  sequently rolled
91e0: 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56   back..**.** INV
91f0: 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
9200: 46 31 32 32 32 31 7d 20 54 68 65 20 5b 73 71 6c  F12221} The [sql
9210: 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
9220: 5f 72 6f 77 69 64 28 29 5d 20 66 75 6e 63 74 69  _rowid()] functi
9230: 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a  on returns the.*
9240: 2a 20 20 20 20 20 20 20 20 20 20 72 6f 77 69 64  *          rowid
9250: 20 6f 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63   of the most rec
9260: 65 6e 74 20 73 75 63 63 65 73 73 66 75 6c 20 69  ent successful i
9270: 6e 73 65 72 74 20 64 6f 6e 65 0a 2a 2a 20 20 20  nsert done.**   
9280: 20 20 20 20 20 20 20 6f 6e 20 74 68 65 20 73 61         on the sa
9290: 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
92a0: 65 63 74 69 6f 6e 20 61 6e 64 20 77 69 74 68 69  ection and withi
92b0: 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20  n the same.**   
92c0: 20 20 20 20 20 20 20 74 72 69 67 67 65 72 20 63         trigger c
92d0: 6f 6e 74 65 78 74 2c 20 6f 72 20 7a 65 72 6f 20  ontext, or zero 
92e0: 69 66 20 74 68 65 72 65 20 68 61 76 65 0a 2a 2a  if there have.**
92f0: 20 20 20 20 20 20 20 20 20 20 62 65 65 6e 20 6e            been n
9300: 6f 20 71 75 61 6c 69 66 79 69 6e 67 20 69 6e 73  o qualifying ins
9310: 65 72 74 73 20 6f 6e 20 74 68 61 74 20 63 6f 6e  erts on that con
9320: 6e 65 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b  nection..**.** {
9330: 46 31 32 32 32 33 7d 20 54 68 65 20 5b 73 71 6c  F12223} The [sql
9340: 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
9350: 5f 72 6f 77 69 64 28 29 5d 20 66 75 6e 63 74 69  _rowid()] functi
9360: 6f 6e 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20  on returns.**   
9370: 20 20 20 20 20 20 20 73 61 6d 65 20 76 61 6c 75         same valu
9380: 65 20 77 68 65 6e 20 63 61 6c 6c 65 64 20 66 72  e when called fr
9390: 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 72 69 67  om the same trig
93a0: 67 65 72 20 63 6f 6e 74 65 78 74 0a 2a 2a 20 20  ger context.**  
93b0: 20 20 20 20 20 20 20 20 69 6d 6d 65 64 69 61 74          immediat
93c0: 65 6c 79 20 62 65 66 6f 72 65 20 61 6e 64 20 61  ely before and a
93d0: 66 74 65 72 20 61 20 52 4f 4c 4c 42 41 43 4b 2e  fter a ROLLBACK.
93e0: 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49 54 41 54 49 4f  .**.** LIMITATIO
93f0: 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 55 31 32 32 33  NS:.**.** {U1223
9400: 32 7d 20 49 66 20 61 20 73 65 70 61 72 61 74 65  2} If a separate
9410: 20 74 68 72 65 61 64 20 64 6f 65 73 20 61 20 6e   thread does a n
9420: 65 77 20 69 6e 73 65 72 74 20 6f 6e 20 74 68 65  ew insert on the
9430: 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20   same.**        
9440: 20 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65    database conne
9450: 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 65 20  ction while the 
9460: 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e  [sqlite3_last_in
9470: 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a  sert_rowid()].**
9480: 20 20 20 20 20 20 20 20 20 20 66 75 6e 63 74 69            functi
9490: 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e  on is running an
94a0: 64 20 74 68 75 73 20 63 68 61 6e 67 65 73 20 74  d thus changes t
94b0: 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20 72  he last insert r
94c0: 6f 77 69 64 2c 0a 2a 2a 20 20 20 20 20 20 20 20  owid,.**        
94d0: 20 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65    then the value
94e0: 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
94f0: 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
9500: 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a  t_rowid()] is.**
9510: 20 20 20 20 20 20 20 20 20 20 75 6e 70 72 65 64            unpred
9520: 69 63 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 68  ictable and migh
9530: 74 20 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 68  t not equal eith
9540: 65 72 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 68  er the old or th
9550: 65 20 6e 65 77 0a 2a 2a 20 20 20 20 20 20 20 20  e new.**        
9560: 20 20 6c 61 73 74 20 69 6e 73 65 72 74 20 72 6f    last insert ro
9570: 77 69 64 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f  wid..*/.sqlite3_
9580: 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c 61  int64 sqlite3_la
9590: 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
95a0: 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
95b0: 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75 6e  * CAPI3REF: Coun
95c0: 74 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 20  t The Number Of 
95d0: 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 20 7b 46  Rows Modified {F
95e0: 31 32 32 34 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69  12240}.**.** Thi
95f0: 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  s function retur
9600: 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
9610: 20 64 61 74 61 62 61 73 65 20 72 6f 77 73 20 74   database rows t
9620: 68 61 74 20 77 65 72 65 20 63 68 61 6e 67 65 64  hat were changed
9630: 0a 2a 2a 20 6f 72 20 69 6e 73 65 72 74 65 64 20  .** or inserted 
9640: 6f 72 20 64 65 6c 65 74 65 64 20 62 79 20 74 68  or deleted by th
9650: 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20  e most recently 
9660: 63 6f 6d 70 6c 65 74 65 64 20 53 51 4c 20 73 74  completed SQL st
9670: 61 74 65 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 74 68  atement.** on th
9680: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 70 65  e connection spe
9690: 63 69 66 69 65 64 20 62 79 20 74 68 65 20 66 69  cified by the fi
96a0: 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20 20  rst parameter.  
96b0: 4f 6e 6c 79 0a 2a 2a 20 63 68 61 6e 67 65 73 20  Only.** changes 
96c0: 74 68 61 74 20 61 72 65 20 64 69 72 65 63 74 6c  that are directl
96d0: 79 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  y specified by t
96e0: 68 65 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  he INSERT, UPDAT
96f0: 45 2c 20 6f 72 0a 2a 2a 20 44 45 4c 45 54 45 20  E, or.** DELETE 
9700: 73 74 61 74 65 6d 65 6e 74 20 61 72 65 20 63 6f  statement are co
9710: 75 6e 74 65 64 2e 20 20 41 75 78 69 6c 69 61 72  unted.  Auxiliar
9720: 79 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64  y changes caused
9730: 20 62 79 0a 2a 2a 20 74 72 69 67 67 65 72 73 20   by.** triggers 
9740: 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e  are not counted.
9750: 20 55 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65   Use the [sqlite
9760: 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
9770: 29 5d 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74  )] function.** t
9780: 6f 20 66 69 6e 64 20 74 68 65 20 74 6f 74 61 6c  o find the total
9790: 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 6e 67   number of chang
97a0: 65 73 20 69 6e 63 6c 75 64 69 6e 67 20 63 68 61  es including cha
97b0: 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20 74  nges caused by t
97c0: 72 69 67 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 41  riggers..**.** A
97d0: 20 22 72 6f 77 20 63 68 61 6e 67 65 22 20 69 73   "row change" is
97e0: 20 61 20 63 68 61 6e 67 65 20 74 6f 20 61 20 73   a change to a s
97f0: 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20 61 20 73  ingle row of a s
9800: 69 6e 67 6c 65 20 74 61 62 6c 65 0a 2a 2a 20 63  ingle table.** c
9810: 61 75 73 65 64 20 62 79 20 61 6e 20 49 4e 53 45  aused by an INSE
9820: 52 54 2c 20 44 45 4c 45 54 45 2c 20 6f 72 20 55  RT, DELETE, or U
9830: 50 44 41 54 45 20 73 74 61 74 65 6d 65 6e 74 2e  PDATE statement.
9840: 20 20 52 6f 77 73 20 74 68 61 74 0a 2a 2a 20 61    Rows that.** a
9850: 72 65 20 63 68 61 6e 67 65 64 20 61 73 20 73 69  re changed as si
9860: 64 65 20 65 66 66 65 63 74 73 20 6f 66 20 52 45  de effects of RE
9870: 50 4c 41 43 45 20 63 6f 6e 73 74 72 61 69 6e 74  PLACE constraint
9880: 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 0a 2a 2a 20   resolution,.** 
9890: 72 6f 6c 6c 62 61 63 6b 2c 20 41 42 4f 52 54 20  rollback, ABORT 
98a0: 70 72 6f 63 65 73 73 69 6e 67 2c 20 44 52 4f 50  processing, DROP
98b0: 20 54 41 42 4c 45 2c 20 6f 72 20 62 79 20 61 6e   TABLE, or by an
98c0: 79 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 63 68 61  y other.** mecha
98d0: 6e 69 73 6d 73 20 64 6f 20 6e 6f 74 20 63 6f 75  nisms do not cou
98e0: 6e 74 20 61 73 20 64 69 72 65 63 74 20 72 6f 77  nt as direct row
98f0: 20 63 68 61 6e 67 65 73 2e 0a 2a 2a 0a 2a 2a 20   changes..**.** 
9900: 41 20 22 74 72 69 67 67 65 72 20 63 6f 6e 74 65  A "trigger conte
9910: 78 74 22 20 69 73 20 61 20 73 63 6f 70 65 20 6f  xt" is a scope o
9920: 66 20 65 78 65 63 75 74 69 6f 6e 20 74 68 61 74  f execution that
9930: 20 62 65 67 69 6e 73 20 61 6e 64 0a 2a 2a 20 65   begins and.** e
9940: 6e 64 73 20 77 69 74 68 20 74 68 65 20 73 63 72  nds with the scr
9950: 69 70 74 20 6f 66 20 61 20 74 72 69 67 67 65 72  ipt of a trigger
9960: 2e 20 20 4d 6f 73 74 20 53 51 4c 20 73 74 61 74  .  Most SQL stat
9970: 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a 20 65 76  ements are.** ev
9980: 61 6c 75 61 74 65 64 20 6f 75 74 73 69 64 65 20  aluated outside 
9990: 6f 66 20 61 6e 79 20 74 72 69 67 67 65 72 2e 20  of any trigger. 
99a0: 20 54 68 69 73 20 69 73 20 74 68 65 20 22 74 6f   This is the "to
99b0: 70 20 6c 65 76 65 6c 22 0a 2a 2a 20 74 72 69 67  p level".** trig
99c0: 67 65 72 20 63 6f 6e 74 65 78 74 2e 20 20 49 66  ger context.  If
99d0: 20 61 20 74 72 69 67 67 65 72 20 66 69 72 65 73   a trigger fires
99e0: 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65   from the top le
99f0: 76 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20 74 72  vel, a.** new tr
9a00: 69 67 67 65 72 20 63 6f 6e 74 65 78 74 20 69 73  igger context is
9a10: 20 65 6e 74 65 72 65 64 20 66 6f 72 20 74 68 65   entered for the
9a20: 20 64 75 72 61 74 69 6f 6e 20 6f 66 20 74 68 61   duration of tha
9a30: 74 20 6f 6e 65 0a 2a 2a 20 74 72 69 67 67 65 72  t one.** trigger
9a40: 2e 20 20 53 75 62 74 72 69 67 67 65 72 73 20 63  .  Subtriggers c
9a50: 72 65 61 74 65 20 73 75 62 63 6f 6e 74 65 78 74  reate subcontext
9a60: 73 20 66 6f 72 20 74 68 65 69 72 20 64 75 72 61  s for their dura
9a70: 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c  tion..**.** Call
9a80: 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  ing [sqlite3_exe
9a90: 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  c()] or [sqlite3
9aa0: 5f 73 74 65 70 28 29 5d 20 72 65 63 75 72 73 69  _step()] recursi
9ab0: 76 65 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74  vely does.** not
9ac0: 20 63 72 65 61 74 65 20 61 20 6e 65 77 20 74 72   create a new tr
9ad0: 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a  igger context..*
9ae0: 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69  *.** This functi
9af0: 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  on returns the n
9b00: 75 6d 62 65 72 20 6f 66 20 64 69 72 65 63 74 20  umber of direct 
9b10: 72 6f 77 20 63 68 61 6e 67 65 73 20 69 6e 20 74  row changes in t
9b20: 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e  he.** most recen
9b30: 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  t INSERT, UPDATE
9b40: 2c 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74  , or DELETE stat
9b50: 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65  ement within the
9b60: 20 73 61 6d 65 0a 2a 2a 20 74 72 69 67 67 65 72   same.** trigger
9b70: 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20   context..**.** 
9b80: 53 6f 20 77 68 65 6e 20 63 61 6c 6c 65 64 20 66  So when called f
9b90: 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65  rom the top leve
9ba0: 6c 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  l, this function
9bb0: 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20   returns the.** 
9bc0: 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65  number of change
9bd0: 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65  s in the most re
9be0: 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44  cent INSERT, UPD
9bf0: 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a  ATE, or DELETE.*
9c00: 2a 20 74 68 61 74 20 61 6c 73 6f 20 6f 63 63 75  * that also occu
9c10: 72 72 65 64 20 61 74 20 74 68 65 20 74 6f 70 20  rred at the top 
9c20: 6c 65 76 65 6c 2e 0a 2a 2a 20 57 69 74 68 69 6e  level..** Within
9c30: 20 74 68 65 20 62 6f 64 79 20 6f 66 20 61 20 74   the body of a t
9c40: 72 69 67 67 65 72 2c 20 74 68 65 20 73 71 6c 69  rigger, the sqli
9c50: 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69 6e  te3_changes() in
9c60: 74 65 72 66 61 63 65 0a 2a 2a 20 63 61 6e 20 62  terface.** can b
9c70: 65 20 63 61 6c 6c 65 64 20 74 6f 20 66 69 6e 64  e called to find
9c80: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
9c90: 2a 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65  * changes in the
9ca0: 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63   most recently c
9cb0: 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 52 54 2c  ompleted INSERT,
9cc0: 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45   UPDATE, or DELE
9cd0: 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  TE.** statement 
9ce0: 77 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20  within the body 
9cf0: 6f 66 20 74 68 65 20 73 61 6d 65 20 74 72 69 67  of the same trig
9d00: 67 65 72 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c  ger..** However,
9d10: 20 74 68 65 20 6e 75 6d 62 65 72 20 72 65 74 75   the number retu
9d20: 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e  rned does not in
9d30: 63 6c 75 64 65 20 69 6e 20 63 68 61 6e 67 65 73  clude in changes
9d40: 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20 73 75  .** caused by su
9d50: 62 74 72 69 67 67 65 72 73 20 73 69 6e 63 65 20  btriggers since 
9d60: 74 68 65 79 20 68 61 76 65 20 74 68 65 69 72 20  they have their 
9d70: 6f 77 6e 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a  own context..**.
9d80: 2a 2a 20 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d  ** SQLite implem
9d90: 65 6e 74 73 20 74 68 65 20 63 6f 6d 6d 61 6e 64  ents the command
9da0: 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61   "DELETE FROM ta
9db0: 62 6c 65 22 20 77 69 74 68 6f 75 74 0a 2a 2a 20  ble" without.** 
9dc0: 61 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 62  a WHERE clause b
9dd0: 79 20 64 72 6f 70 70 69 6e 67 20 61 6e 64 20 72  y dropping and r
9de0: 65 63 72 65 61 74 69 6e 67 20 74 68 65 20 74 61  ecreating the ta
9df0: 62 6c 65 2e 20 20 28 54 68 69 73 20 69 73 20 6d  ble.  (This is m
9e00: 75 63 68 0a 2a 2a 20 66 61 73 74 65 72 20 74 68  uch.** faster th
9e10: 61 6e 20 67 6f 69 6e 67 20 74 68 72 6f 75 67 68  an going through
9e20: 20 61 6e 64 20 64 65 6c 65 74 69 6e 67 20 69 6e   and deleting in
9e30: 64 69 76 69 64 75 61 6c 20 65 6c 65 6d 65 6e 74  dividual element
9e40: 73 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 61  s from the.** ta
9e50: 62 6c 65 2e 29 20 20 42 65 63 61 75 73 65 20 6f  ble.)  Because o
9e60: 66 20 74 68 69 73 20 6f 70 74 69 6d 69 7a 61 74  f this optimizat
9e70: 69 6f 6e 2c 20 74 68 65 20 64 65 6c 65 74 69 6f  ion, the deletio
9e80: 6e 73 20 69 6e 0a 2a 2a 20 22 44 45 4c 45 54 45  ns in.** "DELETE
9e90: 20 46 52 4f 4d 20 74 61 62 6c 65 22 20 61 72 65   FROM table" are
9ea0: 20 6e 6f 74 20 72 6f 77 20 63 68 61 6e 67 65 73   not row changes
9eb0: 20 61 6e 64 20 77 69 6c 6c 20 6e 6f 74 20 62 65   and will not be
9ec0: 20 63 6f 75 6e 74 65 64 0a 2a 2a 20 62 79 20 74   counted.** by t
9ed0: 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  he sqlite3_chang
9ee0: 65 73 28 29 20 6f 72 20 5b 73 71 6c 69 74 65 33  es() or [sqlite3
9ef0: 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
9f00: 5d 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 20  ] functions..** 
9f10: 54 6f 20 67 65 74 20 61 6e 20 61 63 63 75 72 61  To get an accura
9f20: 74 65 20 63 6f 75 6e 74 20 6f 66 20 74 68 65 20  te count of the 
9f30: 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 64  number of rows d
9f40: 65 6c 65 74 65 64 2c 20 75 73 65 0a 2a 2a 20 22  eleted, use.** "
9f50: 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c  DELETE FROM tabl
9f60: 65 20 57 48 45 52 45 20 31 22 20 69 6e 73 74 65  e WHERE 1" inste
9f70: 61 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  ad..**.** INVARI
9f80: 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  ANTS:.**.** {F12
9f90: 32 34 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  241} The [sqlite
9fa0: 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 66 75 6e  3_changes()] fun
9fb0: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
9fc0: 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 20  e number of.**  
9fd0: 20 20 20 20 20 20 20 20 72 6f 77 20 63 68 61 6e          row chan
9fe0: 67 65 73 20 63 61 75 73 65 64 20 62 79 20 74 68  ges caused by th
9ff0: 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e  e most recent IN
a000: 53 45 52 54 2c 20 55 50 44 41 54 45 2c 0a 2a 2a  SERT, UPDATE,.**
a010: 20 20 20 20 20 20 20 20 20 20 6f 72 20 44 45 4c            or DEL
a020: 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 6f 6e  ETE statement on
a030: 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
a040: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 61 6e  se connection an
a050: 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69  d.**          wi
a060: 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 74 72  thin the same tr
a070: 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2c 20 6f  igger context, o
a080: 72 20 7a 65 72 6f 20 69 66 20 74 68 65 72 65 20  r zero if there 
a090: 68 61 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  have.**         
a0a0: 20 6e 6f 74 20 62 65 65 6e 20 61 6e 79 20 71 75   not been any qu
a0b0: 61 6c 69 66 79 69 6e 67 20 72 6f 77 20 63 68 61  alifying row cha
a0c0: 6e 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49  nges..**.** LIMI
a0d0: 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b  TATIONS:.**.** {
a0e0: 55 31 32 32 35 32 7d 20 49 66 20 61 20 73 65 70  U12252} If a sep
a0f0: 61 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b  arate thread mak
a100: 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68  es changes on th
a110: 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
a120: 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20  connection.**   
a130: 20 20 20 20 20 20 20 77 68 69 6c 65 20 5b 73 71         while [sq
a140: 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d  lite3_changes()]
a150: 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e   is running then
a160: 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
a170: 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ned.**          
a180: 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65  is unpredictable
a190: 20 61 6e 64 20 75 6e 6d 65 61 6e 69 6e 67 66 75   and unmeaningfu
a1a0: 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  l..*/.int sqlite
a1b0: 33 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65  3_changes(sqlite
a1c0: 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
a1d0: 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62  3REF: Total Numb
a1e0: 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66  er Of Rows Modif
a1f0: 69 65 64 20 7b 46 31 32 32 36 30 7d 0a 2a 2a 2a  ied {F12260}.***
a200: 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f  .** This functio
a210: 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
a220: 6d 62 65 72 20 6f 66 20 72 6f 77 20 63 68 61 6e  mber of row chan
a230: 67 65 73 20 63 61 75 73 65 64 0a 2a 2a 20 62 79  ges caused.** by
a240: 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20   INSERT, UPDATE 
a250: 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d  or DELETE statem
a260: 65 6e 74 73 20 73 69 6e 63 65 20 74 68 65 20 64  ents since the d
a270: 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 0a 2a  atabase handle.*
a280: 2a 20 77 61 73 20 6f 70 65 6e 65 64 2e 20 20 54  * was opened.  T
a290: 68 65 20 63 6f 75 6e 74 20 69 6e 63 6c 75 64 65  he count include
a2a0: 73 20 61 6c 6c 20 63 68 61 6e 67 65 73 20 66 72  s all changes fr
a2b0: 6f 6d 20 61 6c 6c 20 74 72 69 67 67 65 72 0a 2a  om all trigger.*
a2c0: 2a 20 63 6f 6e 74 65 78 74 73 2e 20 20 42 75 74  * contexts.  But
a2d0: 20 74 68 65 20 63 6f 75 6e 74 20 64 6f 65 73 20   the count does 
a2e0: 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e  not include chan
a2f0: 67 65 73 20 75 73 65 64 20 74 6f 0a 2a 2a 20 69  ges used to.** i
a300: 6d 70 6c 65 6d 65 6e 74 20 52 45 50 4c 41 43 45  mplement REPLACE
a310: 20 63 6f 6e 73 74 72 61 69 6e 74 73 2c 20 64 6f   constraints, do
a320: 20 72 6f 6c 6c 62 61 63 6b 73 20 6f 72 20 41 42   rollbacks or AB
a330: 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 0a  ORT processing,.
a340: 2a 2a 20 6f 72 20 44 52 4f 50 20 74 61 62 6c 65  ** or DROP table
a350: 20 70 72 6f 63 65 73 73 69 6e 67 2e 0a 2a 2a 20   processing..** 
a360: 54 68 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 61  The changes.** a
a370: 72 65 20 63 6f 75 6e 74 65 64 20 61 73 20 73 6f  re counted as so
a380: 6f 6e 20 61 73 20 74 68 65 20 73 74 61 74 65 6d  on as the statem
a390: 65 6e 74 20 74 68 61 74 20 6d 61 6b 65 73 20 74  ent that makes t
a3a0: 68 65 6d 20 69 73 20 63 6f 6d 70 6c 65 74 65 64  hem is completed
a3b0: 20 0a 2a 2a 20 28 77 68 65 6e 20 74 68 65 20 73   .** (when the s
a3c0: 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
a3d0: 69 73 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71  is passed to [sq
a3e0: 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
a3f0: 72 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  r .** [sqlite3_f
a400: 69 6e 61 6c 69 7a 65 28 29 5d 29 2e 0a 2a 2a 0a  inalize()])..**.
a410: 2a 2a 20 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d  ** SQLite implem
a420: 65 6e 74 73 20 74 68 65 20 63 6f 6d 6d 61 6e 64  ents the command
a430: 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61   "DELETE FROM ta
a440: 62 6c 65 22 20 77 69 74 68 6f 75 74 0a 2a 2a 20  ble" without.** 
a450: 61 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 62  a WHERE clause b
a460: 79 20 64 72 6f 70 70 69 6e 67 20 61 6e 64 20 72  y dropping and r
a470: 65 63 72 65 61 74 69 6e 67 20 74 68 65 20 74 61  ecreating the ta
a480: 62 6c 65 2e 20 20 28 54 68 69 73 20 69 73 20 6d  ble.  (This is m
a490: 75 63 68 0a 2a 2a 20 66 61 73 74 65 72 20 74 68  uch.** faster th
a4a0: 61 6e 20 67 6f 69 6e 67 0a 2a 2a 20 74 68 72 6f  an going.** thro
a4b0: 75 67 68 20 61 6e 64 20 64 65 6c 65 74 69 6e 67  ugh and deleting
a4c0: 20 69 6e 64 69 76 69 64 75 61 6c 20 65 6c 65 6d   individual elem
a4d0: 65 6e 74 73 20 66 72 6f 6d 20 74 68 65 20 74 61  ents from the ta
a4e0: 62 6c 65 2e 29 20 20 42 65 63 61 75 73 65 20 6f  ble.)  Because o
a4f0: 66 0a 2a 2a 20 74 68 69 73 20 6f 70 74 69 6d 69  f.** this optimi
a500: 7a 61 74 69 6f 6e 2c 20 74 68 65 20 63 68 61 6e  zation, the chan
a510: 67 65 20 63 6f 75 6e 74 20 66 6f 72 20 22 44 45  ge count for "DE
a520: 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 22  LETE FROM table"
a530: 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 7a 65 72 6f   will be.** zero
a540: 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74   regardless of t
a550: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 6c 65  he number of ele
a560: 6d 65 6e 74 73 20 74 68 61 74 20 77 65 72 65 20  ments that were 
a570: 6f 72 69 67 69 6e 61 6c 6c 79 20 69 6e 20 74 68  originally in th
a580: 65 0a 2a 2a 20 74 61 62 6c 65 2e 20 54 6f 20 67  e.** table. To g
a590: 65 74 20 61 6e 20 61 63 63 75 72 61 74 65 20 63  et an accurate c
a5a0: 6f 75 6e 74 20 6f 66 20 74 68 65 20 6e 75 6d 62  ount of the numb
a5b0: 65 72 20 6f 66 20 72 6f 77 73 20 64 65 6c 65 74  er of rows delet
a5c0: 65 64 2c 20 75 73 65 0a 2a 2a 20 22 44 45 4c 45  ed, use.** "DELE
a5d0: 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 20 57 48  TE FROM table WH
a5e0: 45 52 45 20 31 22 20 69 6e 73 74 65 61 64 2e 0a  ERE 1" instead..
a5f0: 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74  **.** See also t
a600: 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e  he [sqlite3_chan
a610: 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ges()] interface
a620: 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
a630: 54 53 3a 0a 2a 2a 20 0a 2a 2a 20 7b 46 31 32 32  TS:.** .** {F122
a640: 36 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  61} The [sqlite3
a650: 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
a660: 5d 20 72 65 74 75 72 6e 73 20 74 68 65 20 74 6f  ] returns the to
a670: 74 61 6c 20 6e 75 6d 62 65 72 0a 2a 2a 20 20 20  tal number.**   
a680: 20 20 20 20 20 20 20 6f 66 20 72 6f 77 20 63 68         of row ch
a690: 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20  anges caused by 
a6a0: 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20  INSERT, UPDATE, 
a6b0: 61 6e 64 2f 6f 72 20 44 45 4c 45 54 45 0a 2a 2a  and/or DELETE.**
a6c0: 20 20 20 20 20 20 20 20 20 20 73 74 61 74 65 6d            statem
a6d0: 65 6e 74 73 20 6f 6e 20 74 68 65 20 73 61 6d 65  ents on the same
a6e0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
a6f0: 63 74 69 6f 6e 5d 2c 20 69 6e 20 61 6e 79 0a 2a  ction], in any.*
a700: 2a 20 20 20 20 20 20 20 20 20 20 74 72 69 67 67  *          trigg
a710: 65 72 20 63 6f 6e 74 65 78 74 2c 20 73 69 6e 63  er context, sinc
a720: 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  e the database c
a730: 6f 6e 6e 65 63 74 69 6f 6e 20 77 61 73 0a 2a 2a  onnection was.**
a740: 20 20 20 20 20 20 20 20 20 20 63 72 65 61 74 65            create
a750: 64 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49 54 41 54  d..**.** LIMITAT
a760: 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 55 31 32  IONS:.**.** {U12
a770: 32 36 34 7d 20 49 66 20 61 20 73 65 70 61 72 61  264} If a separa
a780: 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20  te thread makes 
a790: 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73  changes on the s
a7a0: 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
a7b0: 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20  nection.**      
a7c0: 20 20 20 20 77 68 69 6c 65 20 5b 73 71 6c 69 74      while [sqlit
a7d0: 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
a7e0: 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74  ()] is running t
a7f0: 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 0a 2a  hen the value .*
a800: 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72  *          retur
a810: 6e 65 64 20 69 73 20 75 6e 70 72 65 64 69 63 74  ned is unpredict
a820: 61 62 6c 65 20 61 6e 64 20 75 6e 6d 65 61 6e 69  able and unmeani
a830: 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ngful..*/.int sq
a840: 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
a850: 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  ges(sqlite3*);..
a860: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
a870: 49 6e 74 65 72 72 75 70 74 20 41 20 4c 6f 6e 67  Interrupt A Long
a880: 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 79 20 7b  -Running Query {
a890: 46 31 32 32 37 30 7d 0a 2a 2a 0a 2a 2a 20 54 68  F12270}.**.** Th
a8a0: 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73  is function caus
a8b0: 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67 20 64  es any pending d
a8c0: 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f  atabase operatio
a8d0: 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a  n to abort and.*
a8e0: 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74 73 20  * return at its 
a8f0: 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72 74 75  earliest opportu
a900: 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75 74 69  nity. This routi
a910: 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c 79 0a  ne is typically.
a920: 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72 65 73  ** called in res
a930: 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65 72 20  ponse to a user 
a940: 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73 20 70  action such as p
a950: 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65 6c 22  ressing "Cancel"
a960: 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77 68  .** or Ctrl-C wh
a970: 65 72 65 20 74 68 65 20 75 73 65 72 20 77 61 6e  ere the user wan
a980: 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72 79 20  ts a long query 
a990: 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c  operation to hal
a9a0: 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79  t.** immediately
a9b0: 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 73 61  ..**.** It is sa
a9c0: 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20  fe to call this 
a9d0: 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61 20 74  routine from a t
a9e0: 68 72 65 61 64 20 64 69 66 66 65 72 65 6e 74 20  hread different 
a9f0: 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65  from the.** thre
aa00: 61 64 20 74 68 61 74 20 69 73 20 63 75 72 72 65  ad that is curre
aa10: 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68 65  ntly running the
aa20: 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74   database operat
aa30: 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20  ion.  But it.** 
aa40: 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 63  is not safe to c
aa50: 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65  all this routine
aa60: 20 77 69 74 68 20 61 20 64 61 74 61 62 61 73 65   with a database
aa70: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
aa80: 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f 72  .** is closed or
aa90: 20 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 65 66   might close bef
aaa0: 6f 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  ore sqlite3_inte
aab0: 72 72 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e  rrupt() returns.
aac0: 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 53 51 4c  .**.** If an SQL
aad0: 20 69 73 20 76 65 72 79 20 6e 65 61 72 6c 79 20   is very nearly 
aae0: 66 69 6e 69 73 68 65 64 20 61 74 20 74 68 65 20  finished at the 
aaf0: 74 69 6d 65 20 77 68 65 6e 20 73 71 6c 69 74 65  time when sqlite
ab00: 33 5f 69 6e 74 65 72 72 75 70 74 28 29 0a 2a 2a  3_interrupt().**
ab10: 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e   is called, then
ab20: 20 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 68 61   it might not ha
ab30: 76 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74  ve an opportunit
ab40: 79 20 74 6f 20 62 65 20 69 6e 74 65 72 72 75 70  y to be interrup
ab50: 74 65 64 2e 0a 2a 2a 20 49 74 20 6d 69 67 68 74  ted..** It might
ab60: 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d   continue to com
ab70: 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 20 41 6e 20 53  pletion..** An S
ab80: 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61  QL operation tha
ab90: 74 20 69 73 20 69 6e 74 65 72 72 75 70 74 65 64  t is interrupted
aba0: 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20   will return.** 
abb0: 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50  [SQLITE_INTERRUP
abc0: 54 5d 2e 20 20 49 66 20 74 68 65 20 69 6e 74 65  T].  If the inte
abd0: 72 72 75 70 74 65 64 20 53 51 4c 20 6f 70 65 72  rrupted SQL oper
abe0: 61 74 69 6f 6e 20 69 73 20 61 6e 0a 2a 2a 20 49  ation is an.** I
abf0: 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f  NSERT, UPDATE, o
ac00: 72 20 44 45 4c 45 54 45 20 74 68 61 74 20 69 73  r DELETE that is
ac10: 20 69 6e 73 69 64 65 20 61 6e 20 65 78 70 6c 69   inside an expli
ac20: 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c  cit transaction,
ac30: 20 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 65 6e   .** then the en
ac40: 74 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e  tire transaction
ac50: 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20   will be rolled 
ac60: 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c  back automatical
ac70: 6c 79 2e 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f  ly..** A call to
ac80: 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
ac90: 70 74 28 29 20 68 61 73 20 6e 6f 20 65 66 66 65  pt() has no effe
aca0: 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d  ct on SQL statem
acb0: 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ents.** that are
acc0: 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20 73   started after s
acd0: 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
ace0: 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a  () returns..**.*
acf0: 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
ad00: 0a 2a 2a 20 7b 46 31 32 32 37 31 7d 20 54 68 65  .** {F12271} The
ad10: 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72   [sqlite3_interr
ad20: 75 70 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65  upt()] interface
ad30: 20 77 69 6c 6c 20 66 6f 72 63 65 20 61 6c 6c 20   will force all 
ad40: 72 75 6e 6e 69 6e 67 0a 2a 2a 20 20 20 20 20 20  running.**      
ad50: 20 20 20 20 53 51 4c 20 73 74 61 74 65 6d 65 6e      SQL statemen
ad60: 74 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ts associated wi
ad70: 74 68 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  th the same data
ad80: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
ad90: 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 68  **          to h
ada0: 61 6c 74 20 61 66 74 65 72 20 70 72 6f 63 65 73  alt after proces
adb0: 73 69 6e 67 20 61 74 20 6d 6f 73 74 20 6f 6e 65  sing at most one
adc0: 20 61 64 64 69 74 69 6f 6e 61 6c 20 72 6f 77 20   additional row 
add0: 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64  of.**          d
ade0: 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32  ata..**.** {F122
adf0: 37 32 7d 20 41 6e 79 20 53 51 4c 20 73 74 61 74  72} Any SQL stat
ae00: 65 6d 65 6e 74 20 74 68 61 74 20 69 73 20 69 6e  ement that is in
ae10: 74 65 72 72 75 70 74 65 64 20 62 79 20 5b 73 71  terrupted by [sq
ae20: 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
ae30: 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77  )].**          w
ae40: 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ill return [SQLI
ae50: 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a  TE_INTERRUPT]..*
ae60: 2a 0a 2a 2a 20 4c 49 4d 49 54 41 54 49 4f 4e 53  *.** LIMITATIONS
ae70: 3a 0a 2a 2a 0a 2a 2a 20 7b 55 31 32 32 37 39 7d  :.**.** {U12279}
ae80: 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65   If the database
ae90: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73   connection clos
aea0: 65 73 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65  es while [sqlite
aeb0: 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a  3_interrupt()].*
aec0: 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 72 75  *          is ru
aed0: 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61 64 20 74  nning then bad t
aee0: 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c  hings will likel
aef0: 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 76 6f 69  y happen..*/.voi
af00: 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  d sqlite3_interr
af10: 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  upt(sqlite3*);..
af20: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
af30: 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20  Determine If An 
af40: 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 49 73  SQL Statement Is
af50: 20 43 6f 6d 70 6c 65 74 65 20 7b 46 31 30 35 31   Complete {F1051
af60: 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  0}.**.** These r
af70: 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 66  outines are usef
af80: 75 6c 20 66 6f 72 20 63 6f 6d 6d 61 6e 64 2d 6c  ul for command-l
af90: 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65 74  ine input to det
afa0: 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a  ermine if the.**
afb0: 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72   currently enter
afc0: 65 64 20 74 65 78 74 20 73 65 65 6d 73 20 74 6f  ed text seems to
afd0: 20 66 6f 72 6d 20 63 6f 6d 70 6c 65 74 65 20 61   form complete a
afe0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f   SQL statement o
aff0: 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 6f 6e  r.** if addition
b000: 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 65 64  al input is need
b010: 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64 69 6e  ed before sendin
b020: 67 20 74 68 65 20 74 65 78 74 20 69 6e 74 6f 0a  g the text into.
b030: 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 70 61  ** SQLite for pa
b040: 72 73 69 6e 67 2e 20 20 54 68 65 73 65 20 72 6f  rsing.  These ro
b050: 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 72  utines return tr
b060: 75 65 20 69 66 20 74 68 65 20 69 6e 70 75 74 20  ue if the input 
b070: 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72  string.** appear
b080: 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65  s to be a comple
b090: 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  te SQL statement
b0a0: 2e 20 20 41 20 73 74 61 74 65 6d 65 6e 74 20 69  .  A statement i
b0b0: 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65 0a 2a  s judged to be.*
b0c0: 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69 74  * complete if it
b0d0: 20 65 6e 64 73 20 77 69 74 68 20 61 20 73 65 6d   ends with a sem
b0e0: 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64  icolon token and
b0f0: 20 69 73 20 6e 6f 74 20 61 20 66 72 61 67 6d 65   is not a fragme
b100: 6e 74 20 6f 66 20 61 0a 2a 2a 20 43 52 45 41 54  nt of a.** CREAT
b110: 45 20 54 52 49 47 47 45 52 20 73 74 61 74 65 6d  E TRIGGER statem
b120: 65 6e 74 2e 20 20 53 65 6d 69 63 6f 6c 6f 6e 73  ent.  Semicolons
b130: 20 74 68 61 74 20 61 72 65 20 65 6d 62 65 64 64   that are embedd
b140: 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72  ed within.** str
b150: 69 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f 72 20  ing literals or 
b160: 71 75 6f 74 65 64 20 69 64 65 6e 74 69 66 69 65  quoted identifie
b170: 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65  r names or comme
b180: 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69  nts are not.** i
b190: 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e  ndependent token
b1a0: 73 20 28 74 68 65 79 20 61 72 65 20 70 61 72 74  s (they are part
b1b0: 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e   of the token in
b1c0: 20 77 68 69 63 68 20 74 68 65 79 20 61 72 65 0a   which they are.
b1d0: 2a 2a 20 65 6d 62 65 64 64 65 64 29 20 61 6e 64  ** embedded) and
b1e0: 20 74 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75   thus do not cou
b1f0: 6e 74 20 61 73 20 61 20 73 74 61 74 65 6d 65 6e  nt as a statemen
b200: 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a  t terminator..**
b210: 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
b220: 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73 65 20  es do not parse 
b230: 74 68 65 20 53 51 4c 20 61 6e 64 0a 2a 2a 20 73  the SQL and.** s
b240: 6f 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63  o will not detec
b250: 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79 20  t syntactically 
b260: 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a  incorrect SQL..*
b270: 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
b280: 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 35 31 31 7d 20  .**.** {F10511} 
b290: 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  The sqlite3_comp
b2a0: 6c 65 74 65 28 29 20 61 6e 64 20 73 71 6c 69 74  lete() and sqlit
b2b0: 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20  e3_complete16() 
b2c0: 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 20 20 20  functions.**    
b2d0: 20 20 20 20 20 20 72 65 74 75 72 6e 20 74 72 75        return tru
b2e0: 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 20  e (non-zero) if 
b2f0: 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20  and only if the 
b300: 6c 61 73 74 0a 2a 2a 20 20 20 20 20 20 20 20 20  last.**         
b310: 20 6e 6f 6e 2d 77 68 69 74 65 73 70 61 63 65 20   non-whitespace 
b320: 74 6f 6b 65 6e 20 69 6e 20 74 68 65 69 72 20 69  token in their i
b330: 6e 70 75 74 20 69 73 20 61 20 73 65 6d 69 63 6f  nput is a semico
b340: 6c 6f 6e 20 74 68 61 74 0a 2a 2a 20 20 20 20 20  lon that.**     
b350: 20 20 20 20 20 69 73 20 6e 6f 74 20 69 6e 20 62       is not in b
b360: 65 74 77 65 65 6e 20 74 68 65 20 42 45 47 49 4e  etween the BEGIN
b370: 20 61 6e 64 20 45 4e 44 20 6f 66 20 61 20 43 52   and END of a CR
b380: 45 41 54 45 20 54 52 49 47 47 45 52 0a 2a 2a 20  EATE TRIGGER.** 
b390: 20 20 20 20 20 20 20 20 20 73 74 61 74 65 6d 65           stateme
b3a0: 6e 74 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49 54 41  nt..**.** LIMITA
b3b0: 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 55 31  TIONS:.**.** {U1
b3c0: 30 35 31 32 7d 20 54 68 65 20 69 6e 70 75 74 20  0512} The input 
b3d0: 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  to sqlite3_compl
b3e0: 65 74 65 28 29 20 6d 75 73 74 20 62 65 20 61 20  ete() must be a 
b3f0: 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
b400: 2a 2a 20 20 20 20 20 20 20 20 20 20 55 54 46 2d  **          UTF-
b410: 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  8 string..**.** 
b420: 7b 55 31 30 35 31 33 7d 20 54 68 65 20 69 6e 70  {U10513} The inp
b430: 75 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ut to sqlite3_co
b440: 6d 70 6c 65 74 65 31 36 28 29 20 6d 75 73 74 20  mplete16() must 
b450: 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  be a zero-termin
b460: 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  ated.**         
b470: 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69   UTF-16 string i
b480: 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  n native byte or
b490: 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  der..*/.int sqli
b4a0: 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e  te3_complete(con
b4b0: 73 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a 69  st char *sql);.i
b4c0: 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  nt sqlite3_compl
b4d0: 65 74 65 31 36 28 63 6f 6e 73 74 20 76 6f 69 64  ete16(const void
b4e0: 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43   *sql);../*.** C
b4f0: 41 50 49 33 52 45 46 3a 20 52 65 67 69 73 74 65  API3REF: Registe
b500: 72 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20  r A Callback To 
b510: 48 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42 55  Handle SQLITE_BU
b520: 53 59 20 45 72 72 6f 72 73 20 7b 46 31 32 33 31  SY Errors {F1231
b530: 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  0}.**.** This ro
b540: 75 74 69 6e 65 20 69 64 65 6e 74 69 66 69 65 73  utine identifies
b550: 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63   a callback func
b560: 74 69 6f 6e 20 74 68 61 74 20 6d 69 67 68 74 20  tion that might 
b570: 62 65 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 77 68  be.** invoked wh
b580: 65 6e 65 76 65 72 20 61 6e 20 61 74 74 65 6d 70  enever an attemp
b590: 74 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65  t is made to ope
b5a0: 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62  n a database tab
b5b0: 6c 65 20 0a 2a 2a 20 74 68 61 74 20 61 6e 6f 74  le .** that anot
b5c0: 68 65 72 20 74 68 72 65 61 64 20 6f 72 20 70 72  her thread or pr
b5d0: 6f 63 65 73 73 20 68 61 73 20 6c 6f 63 6b 65 64  ocess has locked
b5e0: 2e 0a 2a 2a 20 49 66 20 74 68 65 20 62 75 73 79  ..** If the busy
b5f0: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c   callback is NUL
b600: 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f  L, then [SQLITE_
b610: 42 55 53 59 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c  BUSY].** or [SQL
b620: 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45  ITE_IOERR_BLOCKE
b630: 44 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65  D].** is returne
b640: 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 70  d immediately up
b650: 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20  on encountering 
b660: 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 49 66 20  the lock..** If 
b670: 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63  the busy callbac
b680: 6b 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74  k is not NULL, t
b690: 68 65 6e 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 62  hen the.** callb
b6a0: 61 63 6b 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f  ack will be invo
b6b0: 6b 65 64 20 77 69 74 68 20 74 77 6f 20 61 72 67  ked with two arg
b6c0: 75 6d 65 6e 74 73 2e 20 20 54 68 65 0a 2a 2a 20  uments.  The.** 
b6d0: 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
b6e0: 6f 20 74 68 65 20 68 61 6e 64 6c 65 72 20 69 73  o the handler is
b6f0: 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76   a copy of the v
b700: 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69  oid* pointer whi
b710: 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69  ch.** is the thi
b720: 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  rd argument to t
b730: 68 69 73 20 72 6f 75 74 69 6e 65 2e 20 20 54 68  his routine.  Th
b740: 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
b750: 74 20 74 6f 0a 2a 2a 20 74 68 65 20 68 61 6e 64  t to.** the hand
b760: 6c 65 72 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ler is the numbe
b770: 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20  r of times that 
b780: 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
b790: 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76   has.** been inv
b7a0: 6f 6b 65 64 20 66 6f 72 20 74 68 69 73 20 6c 6f  oked for this lo
b7b0: 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20 20 49  cking event.   I
b7c0: 66 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61  f the.** busy ca
b7d0: 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30  llback returns 0
b7e0: 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69  , then no additi
b7f0: 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72  onal attempts ar
b800: 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63  e made to.** acc
b810: 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ess the database
b820: 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53   and [SQLITE_BUS
b830: 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f  Y] or [SQLITE_IO
b840: 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 73 20  ERR_BLOCKED] is 
b850: 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 49 66 20  returned..** If 
b860: 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
b870: 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
b880: 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 74 65  hen another atte
b890: 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74  mpt.** is made t
b8a0: 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62  o open the datab
b8b0: 61 73 65 20 66 6f 72 20 72 65 61 64 69 6e 67 20  ase for reading 
b8c0: 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20 72 65  and the cycle re
b8d0: 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  peats..**.** The
b8e0: 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62   presence of a b
b8f0: 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73  usy handler does
b900: 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74   not guarantee t
b910: 68 61 74 0a 2a 2a 20 69 74 20 77 69 6c 6c 20 62  hat.** it will b
b920: 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74  e invoked when t
b930: 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e  here is lock con
b940: 74 65 6e 74 69 6f 6e 2e 0a 2a 2a 20 49 66 20 53  tention..** If S
b950: 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73  QLite determines
b960: 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74   that invoking t
b970: 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
b980: 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 0a  could result in.
b990: 2a 2a 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69  ** a deadlock, i
b9a0: 74 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 20  t will go ahead 
b9b0: 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  and return [SQLI
b9c0: 54 45 5f 42 55 53 59 5d 20 6f 72 0a 2a 2a 20 5b  TE_BUSY] or.** [
b9d0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
b9e0: 43 4b 45 44 5d 20 69 6e 73 74 65 61 64 20 6f 66  CKED] instead of
b9f0: 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 0a 2a 2a   invoking the.**
ba00: 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a   busy handler..*
ba10: 2a 20 43 6f 6e 73 69 64 65 72 20 61 20 73 63 65  * Consider a sce
ba20: 6e 61 72 69 6f 20 77 68 65 72 65 20 6f 6e 65 20  nario where one 
ba30: 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69  process is holdi
ba40: 6e 67 20 61 20 72 65 61 64 20 6c 6f 63 6b 20 74  ng a read lock t
ba50: 68 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 72 79  hat.** it is try
ba60: 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74  ing to promote t
ba70: 6f 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63  o a reserved loc
ba80: 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e  k and.** a secon
ba90: 64 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c  d process is hol
baa0: 64 69 6e 67 20 61 20 72 65 73 65 72 76 65 64 20  ding a reserved 
bab0: 6c 6f 63 6b 20 74 68 61 74 20 69 74 20 69 73 20  lock that it is 
bac0: 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f  trying.** to pro
bad0: 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 6c 75  mote to an exclu
bae0: 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20  sive lock.  The 
baf0: 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 63 61  first process ca
bb00: 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20  nnot proceed.** 
bb10: 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c  because it is bl
bb20: 6f 63 6b 65 64 20 62 79 20 74 68 65 20 73 65 63  ocked by the sec
bb30: 6f 6e 64 20 61 6e 64 20 74 68 65 20 73 65 63 6f  ond and the seco
bb40: 6e 64 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f  nd process canno
bb50: 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 65 63  t.** proceed bec
bb60: 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b  ause it is block
bb70: 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 2e  ed by the first.
bb80: 20 20 49 66 20 62 6f 74 68 20 70 72 6f 63 65 73    If both proces
bb90: 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68  ses.** invoke th
bba0: 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2c  e busy handlers,
bbb0: 20 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 6d 61   neither will ma
bbc0: 6b 65 20 61 6e 79 20 70 72 6f 67 72 65 73 73 2e  ke any progress.
bbd0: 20 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20    Therefore,.** 
bbe0: 53 51 4c 69 74 65 20 72 65 74 75 72 6e 73 20 5b  SQLite returns [
bbf0: 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f 72  SQLITE_BUSY] for
bc00: 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65   the first proce
bc10: 73 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 74 20  ss, hoping that 
bc20: 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64  this.** will ind
bc30: 75 63 65 20 74 68 65 20 66 69 72 73 74 20 70 72  uce the first pr
bc40: 6f 63 65 73 73 20 74 6f 20 72 65 6c 65 61 73 65  ocess to release
bc50: 20 69 74 73 20 72 65 61 64 20 6c 6f 63 6b 20 61   its read lock a
bc60: 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20  nd allow.** the 
bc70: 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 74  second process t
bc80: 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a  o proceed..**.**
bc90: 20 54 68 65 20 64 65 66 61 75 6c 74 20 62 75 73   The default bus
bca0: 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55  y callback is NU
bcb0: 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53  LL..**.** The [S
bcc0: 51 4c 49 54 45 5f 42 55 53 59 5d 20 65 72 72 6f  QLITE_BUSY] erro
bcd0: 72 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20 74  r is converted t
bce0: 6f 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  o [SQLITE_IOERR_
bcf0: 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 77 68 65 6e  BLOCKED].** when
bd00: 20 53 51 4c 69 74 65 20 69 73 20 69 6e 20 74 68   SQLite is in th
bd10: 65 20 6d 69 64 64 6c 65 20 6f 66 20 61 20 6c 61  e middle of a la
bd20: 72 67 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  rge transaction 
bd30: 77 68 65 72 65 20 61 6c 6c 20 74 68 65 0a 2a 2a  where all the.**
bd40: 20 63 68 61 6e 67 65 73 20 77 69 6c 6c 20 6e 6f   changes will no
bd50: 74 20 66 69 74 20 69 6e 74 6f 20 74 68 65 20 69  t fit into the i
bd60: 6e 2d 6d 65 6d 6f 72 79 20 63 61 63 68 65 2e 20  n-memory cache. 
bd70: 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20   SQLite will.** 
bd80: 61 6c 72 65 61 64 79 20 68 6f 6c 64 20 61 20 52  already hold a R
bd90: 45 53 45 52 56 45 44 20 6c 6f 63 6b 20 6f 6e 20  ESERVED lock on 
bda0: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
bdb0: 65 2c 20 62 75 74 20 69 74 20 6e 65 65 64 73 0a  e, but it needs.
bdc0: 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68  ** to promote th
bdd0: 69 73 20 6c 6f 63 6b 20 74 6f 20 45 58 43 4c 55  is lock to EXCLU
bde0: 53 49 56 45 20 73 6f 20 74 68 61 74 20 69 74 20  SIVE so that it 
bdf0: 63 61 6e 20 73 70 69 6c 6c 20 63 61 63 68 65 0a  can spill cache.
be00: 2a 2a 20 70 61 67 65 73 20 69 6e 74 6f 20 74 68  ** pages into th
be10: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
be20: 77 69 74 68 6f 75 74 20 68 61 72 6d 20 74 6f 20  without harm to 
be30: 63 6f 6e 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65  concurrent.** re
be40: 61 64 65 72 73 2e 20 20 49 66 20 69 74 20 69 73  aders.  If it is
be50: 20 75 6e 61 62 6c 65 20 74 6f 20 70 72 6f 6d 6f   unable to promo
be60: 74 65 20 74 68 65 20 6c 6f 63 6b 2c 20 74 68 65  te the lock, the
be70: 6e 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a  n the in-memory.
be80: 2a 2a 20 63 61 63 68 65 20 77 69 6c 6c 20 62 65  ** cache will be
be90: 20 6c 65 66 74 20 69 6e 20 61 6e 20 69 6e 63 6f   left in an inco
bea0: 6e 73 69 73 74 65 6e 74 20 73 74 61 74 65 20 61  nsistent state a
beb0: 6e 64 20 73 6f 20 74 68 65 20 65 72 72 6f 72 0a  nd so the error.
bec0: 2a 2a 20 63 6f 64 65 20 69 73 20 70 72 6f 6d 6f  ** code is promo
bed0: 74 65 64 20 66 72 6f 6d 20 74 68 65 20 72 65 6c  ted from the rel
bee0: 61 74 69 76 65 6c 79 20 62 65 6e 69 67 6e 20 5b  atively benign [
bef0: 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 74 6f 0a  SQLITE_BUSY] to.
bf00: 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 65 76 65  ** the more seve
bf10: 72 65 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  re [SQLITE_IOERR
bf20: 5f 42 4c 4f 43 4b 45 44 5d 2e 20 20 54 68 69 73  _BLOCKED].  This
bf30: 20 65 72 72 6f 72 20 63 6f 64 65 20 70 72 6f 6d   error code prom
bf40: 6f 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65 73 20  otion.** forces 
bf50: 61 6e 20 61 75 74 6f 6d 61 74 69 63 20 72 6f 6c  an automatic rol
bf60: 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 63 68 61  lback of the cha
bf70: 6e 67 65 73 2e 20 20 53 65 65 20 74 68 65 0a 2a  nges.  See the.*
bf80: 2a 20 3c 61 20 68 72 65 66 3d 22 68 74 74 70 3a  * <a href="http:
bf90: 2f 2f 77 77 77 2e 73 71 6c 69 74 65 2e 6f 72 67  //www.sqlite.org
bfa0: 2f 63 76 73 74 72 61 63 2f 77 69 6b 69 3f 70 3d  /cvstrac/wiki?p=
bfb0: 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77  CorruptionFollow
bfc0: 69 6e 67 42 75 73 79 45 72 72 6f 72 22 3e 0a 2a  ingBusyError">.*
bfd0: 2a 20 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c  * CorruptionFoll
bfe0: 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72 3c 2f  owingBusyError</
bff0: 61 3e 20 77 69 6b 69 20 70 61 67 65 20 66 6f 72  a> wiki page for
c000: 20 61 20 64 69 73 63 75 73 73 69 6f 6e 20 6f 66   a discussion of
c010: 20 77 68 79 0a 2a 2a 20 74 68 69 73 20 69 73 20   why.** this is 
c020: 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a 2a 09 0a 2a  important..**..*
c030: 2a 20 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79  * There can only
c040: 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73   be a single bus
c050: 79 20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65  y handler define
c060: 64 20 66 6f 72 20 65 61 63 68 20 64 61 74 61 62  d for each datab
c070: 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
c080: 6e 2e 20 20 53 65 74 74 69 6e 67 20 61 20 6e 65  n.  Setting a ne
c090: 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63  w busy handler c
c0a0: 6c 65 61 72 73 20 61 6e 79 20 70 72 65 76 69 6f  lears any previo
c0b0: 75 73 20 6f 6e 65 2e 20 0a 2a 2a 20 4e 6f 74 65  us one. .** Note
c0c0: 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73   that calling [s
c0d0: 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65  qlite3_busy_time
c0e0: 6f 75 74 28 29 5d 20 77 69 6c 6c 20 61 6c 73 6f  out()] will also
c0f0: 20 73 65 74 20 6f 72 20 63 6c 65 61 72 0a 2a 2a   set or clear.**
c100: 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
c110: 72 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  r..**.** INVARIA
c120: 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33  NTS:.**.** {F123
c130: 31 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  11} The [sqlite3
c140: 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d  _busy_handler()]
c150: 20 66 75 6e 63 74 69 6f 6e 20 72 65 70 6c 61 63   function replac
c160: 65 73 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  es the busy hand
c170: 6c 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ler.**          
c180: 63 61 6c 6c 62 61 63 6b 20 69 6e 20 74 68 65 20  callback in the 
c190: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
c1a0: 69 6f 6e 20 69 64 65 6e 74 69 66 69 65 64 20 62  ion identified b
c1b0: 79 20 74 68 65 20 31 73 74 0a 2a 2a 20 20 20 20  y the 1st.**    
c1c0: 20 20 20 20 20 20 70 61 72 61 6d 65 74 65 72 20        parameter 
c1d0: 77 69 74 68 20 61 20 6e 65 77 20 62 75 73 79 20  with a new busy 
c1e0: 68 61 6e 64 6c 65 72 20 69 64 65 6e 74 69 66 69  handler identifi
c1f0: 65 64 20 62 79 20 74 68 65 20 32 6e 64 20 61 6e  ed by the 2nd an
c200: 64 20 33 72 64 0a 2a 2a 20 20 20 20 20 20 20 20  d 3rd.**        
c210: 20 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2a    parameters..**
c220: 0a 2a 2a 20 7b 46 31 32 33 31 32 7d 20 54 68 65  .** {F12312} The
c230: 20 64 65 66 61 75 6c 74 20 62 75 73 79 20 68 61   default busy ha
c240: 6e 64 6c 65 72 20 66 6f 72 20 6e 65 77 20 64 61  ndler for new da
c250: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
c260: 6e 73 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  ns is NULL..**.*
c270: 2a 20 7b 46 31 32 33 31 34 7d 20 57 68 65 6e 20  * {F12314} When 
c280: 74 77 6f 20 6f 72 20 6d 6f 72 65 20 64 61 74 61  two or more data
c290: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
c2a0: 73 68 61 72 65 20 61 20 63 6f 6d 6d 6f 6e 20 63  share a common c
c2b0: 61 63 68 65 2c 0a 2a 2a 20 20 20 20 20 20 20 20  ache,.**        
c2c0: 20 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c    the busy handl
c2d0: 65 72 20 66 6f 72 20 74 68 65 20 64 61 74 61 62  er for the datab
c2e0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63  ase connection c
c2f0: 75 72 72 65 6e 74 6c 79 20 75 73 69 6e 67 0a 2a  urrently using.*
c300: 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 63  *          the c
c310: 61 63 68 65 20 69 73 20 69 6e 76 6f 6b 65 64 20  ache is invoked 
c320: 77 68 65 6e 20 74 68 65 20 63 61 63 68 65 20 65  when the cache e
c330: 6e 63 6f 75 6e 74 65 72 73 20 61 20 6c 6f 63 6b  ncounters a lock
c340: 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 31 36 7d  ..**.** {F12316}
c350: 20 49 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c   If a busy handl
c360: 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  er callback retu
c370: 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20 74  rns zero, then t
c380: 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 20 20 20  he SQLite.**    
c390: 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 20        interface 
c3a0: 74 68 61 74 20 70 72 6f 76 6f 6b 65 64 20 74 68  that provoked th
c3b0: 65 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 20  e locking event 
c3c0: 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 20  will return.**  
c3d0: 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f          [SQLITE_
c3e0: 42 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  BUSY]..**.** {F1
c3f0: 32 33 31 38 7d 20 53 51 4c 69 74 65 20 77 69 6c  2318} SQLite wil
c400: 6c 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 62 75  l invokes the bu
c410: 73 79 20 68 61 6e 64 6c 65 72 20 77 69 74 68 20  sy handler with 
c420: 74 77 6f 20 61 72 67 75 6d 65 6e 74 20 77 68 69  two argument whi
c430: 63 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  ch.**          a
c440: 72 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  re a copy of the
c450: 20 70 6f 69 6e 74 65 72 20 73 75 70 70 6c 69 65   pointer supplie
c460: 64 20 62 79 20 74 68 65 20 33 72 64 20 70 61 72  d by the 3rd par
c470: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 20 20 20  ameter to.**    
c480: 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62        [sqlite3_b
c490: 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 20 61  usy_handler()] a
c4a0: 6e 64 20 61 20 63 6f 75 6e 74 20 6f 66 20 74 68  nd a count of th
c4b0: 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 72 69 6f  e number of prio
c4c0: 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  r.**          in
c4d0: 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  vocations of the
c4e0: 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f   busy handler fo
c4f0: 72 20 74 68 65 20 73 61 6d 65 20 6c 6f 63 6b 69  r the same locki
c500: 6e 67 20 65 76 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  ng event..**.** 
c510: 4c 49 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a  LIMITATIONS:.**.
c520: 2a 2a 20 7b 55 31 32 33 31 39 7d 20 41 20 62 75  ** {U12319} A bu
c530: 73 79 20 68 61 6e 64 6c 65 72 20 73 68 6f 75 6c  sy handler shoul
c540: 64 20 6e 6f 74 20 63 61 6c 6c 20 63 6c 6f 73 65  d not call close
c550: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
c560: 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20  nnection.**     
c570: 20 20 20 20 20 6f 72 20 70 72 65 70 61 72 65 64       or prepared
c580: 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20   statement that 
c590: 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79  invoked the busy
c5a0: 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e 74   handler..*/.int
c5b0: 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61   sqlite3_busy_ha
c5c0: 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20  ndler(sqlite3*, 
c5d0: 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74  int(*)(void*,int
c5e0: 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ), void*);../*.*
c5f0: 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 20  * CAPI3REF: Set 
c600: 41 20 42 75 73 79 20 54 69 6d 65 6f 75 74 20 7b  A Busy Timeout {
c610: 46 31 32 33 34 30 7d 0a 2a 2a 0a 2a 2a 20 54 68  F12340}.**.** Th
c620: 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20  is routine sets 
c630: 61 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  a [sqlite3_busy_
c640: 68 61 6e 64 6c 65 72 20 7c 20 62 75 73 79 20 68  handler | busy h
c650: 61 6e 64 6c 65 72 5d 0a 2a 2a 20 74 68 61 74 20  andler].** that 
c660: 73 6c 65 65 70 73 20 66 6f 72 20 61 20 77 68 69  sleeps for a whi
c670: 6c 65 20 77 68 65 6e 20 61 0a 2a 2a 20 74 61 62  le when a.** tab
c680: 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20 54  le is locked.  T
c690: 68 65 20 68 61 6e 64 6c 65 72 20 77 69 6c 6c 20  he handler will 
c6a0: 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74  sleep multiple t
c6b0: 69 6d 65 73 20 75 6e 74 69 6c 20 0a 2a 2a 20 61  imes until .** a
c6c0: 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c  t least "ms" mil
c6d0: 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65  liseconds of sle
c6e0: 65 70 69 6e 67 20 68 61 76 65 20 62 65 65 6e 20  eping have been 
c6f0: 64 6f 6e 65 2e 20 7b 46 31 32 33 34 33 7d 20 41  done. {F12343} A
c700: 66 74 65 72 0a 2a 2a 20 22 6d 73 22 20 6d 69 6c  fter.** "ms" mil
c710: 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65  liseconds of sle
c720: 65 70 69 6e 67 2c 20 74 68 65 20 68 61 6e 64 6c  eping, the handl
c730: 65 72 20 72 65 74 75 72 6e 73 20 30 20 77 68 69  er returns 0 whi
c740: 63 68 0a 2a 2a 20 63 61 75 73 65 73 20 5b 73 71  ch.** causes [sq
c750: 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 74 6f  lite3_step()] to
c760: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
c770: 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45  BUSY] or [SQLITE
c780: 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e  _IOERR_BLOCKED].
c790: 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20 74  .**.** Calling t
c7a0: 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68  his routine with
c7b0: 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65 73   an argument les
c7c0: 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20  s than or equal 
c7d0: 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73  to zero.** turns
c7e0: 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20 68 61   off all busy ha
c7f0: 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  ndlers..**.** Th
c800: 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20  ere can only be 
c810: 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61  a single busy ha
c820: 6e 64 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74  ndler for a part
c830: 69 63 75 6c 61 72 20 64 61 74 61 62 61 73 65 0a  icular database.
c840: 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  ** connection.  
c850: 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79 20  If another busy 
c860: 68 61 6e 64 6c 65 72 20 77 61 73 20 64 65 66 69  handler was defi
c870: 6e 65 64 20 20 0a 2a 2a 20 28 75 73 69 6e 67 20  ned  .** (using 
c880: 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61  [sqlite3_busy_ha
c890: 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 20  ndler()]) prior 
c8a0: 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68  to calling.** th
c8b0: 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 74  is routine, that
c8c0: 20 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64   other busy hand
c8d0: 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e 0a  ler is cleared..
c8e0: 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
c8f0: 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 34 31 7d  :.**.** {F12341}
c900: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 75   The [sqlite3_bu
c910: 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 66 75  sy_timeout()] fu
c920: 6e 63 74 69 6f 6e 20 6f 76 65 72 72 69 64 65 73  nction overrides
c930: 20 61 6e 79 20 70 72 69 6f 72 0a 2a 2a 20 20 20   any prior.**   
c940: 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
c950: 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20  busy_timeout()] 
c960: 6f 72 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  or [sqlite3_busy
c970: 5f 68 61 6e 64 6c 65 72 28 29 5d 20 73 65 74 74  _handler()] sett
c980: 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ing.**          
c990: 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  on the same data
c9a0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  base connection.
c9b0: 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 34 33 7d 20  .**.** {F12343} 
c9c0: 49 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  If the 2nd param
c9d0: 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
c9e0: 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
c9f0: 20 69 73 20 6c 65 73 73 20 74 68 61 6e 0a 2a 2a   is less than.**
ca00: 20 20 20 20 20 20 20 20 20 20 6f 72 20 65 71 75            or equ
ca10: 61 6c 20 74 6f 20 7a 65 72 6f 2c 20 74 68 65 6e  al to zero, then
ca20: 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
ca30: 72 20 69 73 20 63 6c 65 61 72 65 64 20 73 6f 20  r is cleared so 
ca40: 74 68 61 74 0a 2a 2a 20 20 20 20 20 20 20 20 20  that.**         
ca50: 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20   all subsequent 
ca60: 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 73 20 69  locking events i
ca70: 6d 6d 65 64 69 61 74 65 6c 79 20 72 65 74 75 72  mmediately retur
ca80: 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e  n [SQLITE_BUSY].
ca90: 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 34 34 7d 20  .**.** {F12344} 
caa0: 49 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  If the 2nd param
cab0: 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
cac0: 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
cad0: 20 69 73 20 61 20 70 6f 73 69 74 69 76 65 0a 2a   is a positive.*
cae0: 2a 20 20 20 20 20 20 20 20 20 20 6e 75 6d 62 65  *          numbe
caf0: 72 20 4e 2c 20 74 68 65 6e 20 61 20 62 75 73 79  r N, then a busy
cb00: 20 68 61 6e 64 6c 65 72 20 69 73 20 73 65 74 20   handler is set 
cb10: 74 68 61 74 20 72 65 70 65 61 74 65 64 6c 79 20  that repeatedly 
cb20: 63 61 6c 6c 73 0a 2a 2a 20 20 20 20 20 20 20 20  calls.**        
cb30: 20 20 74 68 65 20 78 53 6c 65 65 70 28 29 20 6d    the xSleep() m
cb40: 65 74 68 6f 64 20 69 6e 20 74 68 65 20 56 46 53  ethod in the VFS
cb50: 20 69 6e 74 65 72 66 61 63 65 20 75 6e 74 69 6c   interface until
cb60: 20 65 69 74 68 65 72 20 74 68 65 0a 2a 2a 20 20   either the.**  
cb70: 20 20 20 20 20 20 20 20 6c 6f 63 6b 20 63 6c 65          lock cle
cb80: 61 72 73 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  ars or until the
cb90: 20 63 75 6d 75 6c 61 74 69 76 65 20 73 6c 65 65   cumulative slee
cba0: 70 20 74 69 6d 65 20 72 65 70 6f 72 74 65 64 20  p time reported 
cbb0: 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20  back.**         
cbc0: 20 62 79 20 78 53 6c 65 65 70 28 29 20 65 78 63   by xSleep() exc
cbd0: 65 65 64 73 20 4e 20 6d 69 6c 6c 69 73 65 63 6f  eeds N milliseco
cbe0: 6e 64 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  nds..*/.int sqli
cbf0: 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74  te3_busy_timeout
cc00: 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d  (sqlite3*, int m
cc10: 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  s);../*.** CAPI3
cc20: 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65  REF: Convenience
cc30: 20 52 6f 75 74 69 6e 65 73 20 46 6f 72 20 52 75   Routines For Ru
cc40: 6e 6e 69 6e 67 20 51 75 65 72 69 65 73 20 7b 46  nning Queries {F
cc50: 31 32 33 37 30 7d 0a 2a 2a 0a 2a 2a 20 44 65 66  12370}.**.** Def
cc60: 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65  inition: A <b>re
cc70: 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69  sult table</b> i
cc80: 73 20 6d 65 6d 6f 72 79 20 64 61 74 61 20 73 74  s memory data st
cc90: 72 75 63 74 75 72 65 20 63 72 65 61 74 65 64 20  ructure created 
cca0: 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  by the.** [sqlit
ccb0: 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20  e3_get_table()] 
ccc0: 69 6e 74 65 72 66 61 63 65 2e 20 20 41 20 72 65  interface.  A re
ccd0: 73 75 6c 74 20 74 61 62 6c 65 20 72 65 63 6f 72  sult table recor
cce0: 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65  ds the.** comple
ccf0: 74 65 20 71 75 65 72 79 20 72 65 73 75 6c 74 73  te query results
cd00: 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72   from one or mor
cd10: 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a  e queries..**.**
cd20: 20 54 68 65 20 74 61 62 6c 65 20 63 6f 6e 63 65   The table conce
cd30: 70 74 75 61 6c 6c 79 20 68 61 73 20 61 20 6e 75  ptually has a nu
cd40: 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 61 6e 64  mber of rows and
cd50: 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a   columns.  But.*
cd60: 2a 20 74 68 65 73 65 20 6e 75 6d 62 65 72 73 20  * these numbers 
cd70: 61 72 65 20 6e 6f 74 20 70 61 72 74 20 6f 66 20  are not part of 
cd80: 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65  the result table
cd90: 20 69 74 73 65 6c 66 2e 20 20 54 68 65 73 65 0a   itself.  These.
cda0: 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6f  ** numbers are o
cdb0: 62 74 61 69 6e 65 64 20 73 65 70 61 72 61 74 65  btained separate
cdc0: 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65 20 74 68  ly.  Let N be th
cdd0: 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73  e number of rows
cde0: 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74 68 65  .** and M be the
cdf0: 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
ce00: 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75  ns..**.** A resu
ce10: 6c 74 20 74 61 62 6c 65 20 69 73 20 61 6e 20 61  lt table is an a
ce20: 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73  rray of pointers
ce30: 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61   to zero-termina
ce40: 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72  ted.** UTF-8 str
ce50: 69 6e 67 73 2e 20 20 54 68 65 72 65 20 61 72 65  ings.  There are
ce60: 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74   (N+1)*M element
ce70: 73 20 69 6e 20 74 68 65 20 61 72 72 61 79 2e 20  s in the array. 
ce80: 20 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 4d   .** The first M
ce90: 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74 20   pointers point 
cea0: 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  to zero-terminat
ceb0: 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20  ed strings that 
cec0: 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 74 68 65 20  .** contain the 
ced0: 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63 6f 6c  names of the col
cee0: 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d  umns..** The rem
cef0: 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 20 61  aining entries a
cf00: 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 65 72  ll point to quer
cf10: 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c  y results.  NULL
cf20: 0a 2a 2a 20 76 61 6c 75 65 73 20 61 72 65 20 67  .** values are g
cf30: 69 76 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ive a NULL point
cf40: 65 72 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 76  er.  All other v
cf50: 61 6c 75 65 73 20 61 72 65 20 69 6e 0a 2a 2a 20  alues are in.** 
cf60: 74 68 65 69 72 20 55 54 46 2d 38 20 7a 65 72 6f  their UTF-8 zero
cf70: 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69  -terminated stri
cf80: 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  ng representatio
cf90: 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20 62 79  n as returned by
cfa0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
cfb0: 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a  umn_text()]..**.
cfc0: 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c  ** A result tabl
cfd0: 65 20 6d 69 67 68 74 20 63 6f 6e 73 69 73 74 73  e might consists
cfe0: 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20   of one or more 
cff0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
d000: 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74  ns..** It is not
d010: 20 73 61 66 65 20 74 6f 20 70 61 73 73 20 61 20   safe to pass a 
d020: 72 65 73 75 6c 74 20 74 61 62 6c 65 20 64 69 72  result table dir
d030: 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65  ectly to [sqlite
d040: 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20  3_free()]..** A 
d050: 72 65 73 75 6c 74 20 74 61 62 6c 65 20 73 68 6f  result table sho
d060: 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63 61 74  uld be deallocat
d070: 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
d080: 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e  3_free_table()].
d090: 0a 2a 2a 0a 2a 2a 20 41 73 20 61 6e 20 65 78 61  .**.** As an exa
d0a0: 6d 70 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75  mple of the resu
d0b0: 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c  lt table format,
d0c0: 20 73 75 70 70 6f 73 65 20 61 20 71 75 65 72 79   suppose a query
d0d0: 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73   result.** is as
d0e0: 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
d0f0: 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
d100: 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65  >.**        Name
d110: 20 20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a          | Age.**
d120: 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d          --------
d130: 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a  ---------------.
d140: 2a 2a 20 20 20 20 20 20 20 20 41 6c 69 63 65 20  **        Alice 
d150: 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20        | 43.**   
d160: 20 20 20 20 20 42 6f 62 20 20 20 20 20 20 20 20       Bob        
d170: 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20   | 28.**        
d180: 43 69 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31  Cindy       | 21
d190: 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
d1a0: 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
d1b0: 65 72 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75  ere are two colu
d1c0: 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68  mn (M==2) and th
d1d0: 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e  ree rows (N==3).
d1e0: 20 20 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65    Thus the.** re
d1f0: 73 75 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38  sult table has 8
d200: 20 65 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f   entries.  Suppo
d210: 73 65 20 74 68 65 20 72 65 73 75 6c 74 20 74 61  se the result ta
d220: 62 6c 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a  ble is stored.**
d230: 20 69 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d   in an array nam
d240: 65 73 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68  es azResult.  Th
d250: 65 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64  en azResult hold
d260: 73 20 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a  s this content:.
d270: 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
d280: 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20  e><pre>.**      
d290: 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30    azResult&#91;0
d2a0: 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20  ] = "Name";.**  
d2b0: 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
d2c0: 39 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a  91;1] = "Age";.*
d2d0: 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
d2e0: 74 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63  t&#91;2] = "Alic
d2f0: 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  e";.**        az
d300: 52 65 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20  Result&#91;3] = 
d310: 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  "43";.**        
d320: 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20  azResult&#91;4] 
d330: 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20  = "Bob";.**     
d340: 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
d350: 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20  5] = "28";.**   
d360: 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
d370: 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a  1;6] = "Cindy";.
d380: 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
d390: 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22  lt&#91;7] = "21"
d3a0: 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
d3b0: 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
d3c0: 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  he sqlite3_get_t
d3d0: 61 62 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20  able() function 
d3e0: 65 76 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72  evaluates one or
d3f0: 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c   more.** semicol
d400: 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 53 51 4c  on-separated SQL
d410: 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74   statements in t
d420: 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  he zero-terminat
d430: 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69  ed UTF-8.** stri
d440: 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 20 70 61  ng of its 2nd pa
d450: 72 61 6d 65 74 65 72 2e 20 20 49 74 20 72 65 74  rameter.  It ret
d460: 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20 74 61  urns a result ta
d470: 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f  ble to the.** po
d480: 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e 20 69  inter given in i
d490: 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  ts 3rd parameter
d4a0: 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68  ..**.** After th
d4b0: 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69  e calling functi
d4c0: 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  on has finished 
d4d0: 75 73 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74  using the result
d4e0: 2c 20 69 74 20 73 68 6f 75 6c 64 20 0a 2a 2a 20  , it should .** 
d4f0: 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72  pass the pointer
d500: 20 74 6f 20 74 68 65 20 72 65 73 75 6c 74 20 74   to the result t
d510: 61 62 6c 65 20 74 6f 20 73 71 6c 69 74 65 33 5f  able to sqlite3_
d520: 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20  free_table() in 
d530: 6f 72 64 65 72 20 74 6f 20 0a 2a 2a 20 72 65 6c  order to .** rel
d540: 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  ease the memory 
d550: 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 2d  that was malloc-
d560: 65 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20  ed.  Because of 
d570: 74 68 65 20 77 61 79 20 74 68 65 20 0a 2a 2a 20  the way the .** 
d580: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
d590: 29 5d 20 68 61 70 70 65 6e 73 20 77 69 74 68 69  )] happens withi
d5a0: 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  n sqlite3_get_ta
d5b0: 62 6c 65 28 29 2c 20 74 68 65 20 63 61 6c 6c 69  ble(), the calli
d5c0: 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d  ng.** function m
d5d0: 75 73 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63  ust not try to c
d5e0: 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  all [sqlite3_fre
d5f0: 65 28 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20  e()] directly.  
d600: 4f 6e 6c 79 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  Only .** [sqlite
d610: 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 20  3_free_table()] 
d620: 69 73 20 61 62 6c 65 20 74 6f 20 72 65 6c 65 61  is able to relea
d630: 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72  se the memory pr
d640: 6f 70 65 72 6c 79 20 61 6e 64 20 73 61 66 65 6c  operly and safel
d650: 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  y..**.** The sql
d660: 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
d670: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 6d   interface is im
d680: 70 6c 65 6d 65 6e 74 65 64 20 61 73 20 61 20 77  plemented as a w
d690: 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a  rapper around.**
d6a0: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
d6b0: 5d 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  ].  The sqlite3_
d6c0: 67 65 74 5f 74 61 62 6c 65 28 29 20 72 6f 75 74  get_table() rout
d6d0: 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68 61 76  ine does not hav
d6e0: 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61  e access.** to a
d6f0: 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61  ny internal data
d700: 20 73 74 72 75 63 74 75 72 65 73 20 6f 66 20 53   structures of S
d710: 51 4c 69 74 65 2e 20 20 49 74 20 75 73 65 73 20  QLite.  It uses 
d720: 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c 69 63 0a  only the public.
d730: 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 64 65 66  ** interface def
d740: 69 6e 65 64 20 68 65 72 65 2e 20 20 41 73 20 61  ined here.  As a
d750: 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65 72   consequence, er
d760: 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72 20  rors that occur 
d770: 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70 70 65  in the.** wrappe
d780: 72 20 6c 61 79 65 72 20 6f 75 74 73 69 64 65 20  r layer outside 
d790: 6f 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20  of the internal 
d7a0: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
d7b0: 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a   call are not.**
d7c0: 20 72 65 66 6c 65 63 74 65 64 20 69 6e 20 73 75   reflected in su
d7d0: 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74  bsequent calls t
d7e0: 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  o [sqlite3_errco
d7f0: 64 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  de()] or.** [sql
d800: 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a  ite3_errmsg()]..
d810: 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
d820: 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 37 31 7d  :.**.** {F12371}
d830: 20 49 66 20 61 20 5b 73 71 6c 69 74 65 33 5f 67   If a [sqlite3_g
d840: 65 74 5f 74 61 62 6c 65 28 29 5d 20 66 61 69 6c  et_table()] fail
d850: 73 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  s a memory alloc
d860: 61 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 20  ation, then.**  
d870: 20 20 20 20 20 20 20 20 69 74 20 66 72 65 65 73          it frees
d880: 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
d890: 65 20 75 6e 64 65 72 20 63 6f 6e 73 74 72 75 63  e under construc
d8a0: 74 69 6f 6e 2c 20 61 62 6f 72 74 73 20 74 68 65  tion, aborts the
d8b0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 71 75 65  .**          que
d8c0: 72 79 20 69 6e 20 70 72 6f 63 65 73 73 2c 20 73  ry in process, s
d8d0: 6b 69 70 73 20 61 6e 79 20 73 75 62 73 65 71 75  kips any subsequ
d8e0: 65 6e 74 20 71 75 65 72 69 65 73 2c 20 73 65 74  ent queries, set
d8f0: 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
d900: 20 20 2a 72 65 73 75 6c 74 70 20 6f 75 74 70 75    *resultp outpu
d910: 74 20 70 6f 69 6e 74 65 72 20 74 6f 20 4e 55 4c  t pointer to NUL
d920: 4c 20 61 6e 64 20 72 65 74 75 72 6e 73 20 5b 53  L and returns [S
d930: 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a  QLITE_NOMEM]..**
d940: 0a 2a 2a 20 7b 46 31 32 33 37 33 7d 20 49 66 20  .** {F12373} If 
d950: 74 68 65 20 6e 63 6f 6c 75 6d 6e 20 70 61 72 61  the ncolumn para
d960: 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
d970: 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69  3_get_table()] i
d980: 73 20 6e 6f 74 20 4e 55 4c 4c 0a 2a 2a 20 20 20  s not NULL.**   
d990: 20 20 20 20 20 20 20 74 68 65 6e 20 5b 73 71 6c         then [sql
d9a0: 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
d9b0: 5d 20 77 72 69 74 65 20 74 68 65 20 6e 75 6d 62  ] write the numb
d9c0: 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
d9d0: 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
d9e0: 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74   result set of t
d9f0: 68 65 20 71 75 65 72 79 20 69 6e 74 6f 20 2a 6e  he query into *n
da00: 63 6f 6c 75 6d 6e 20 69 66 20 74 68 65 20 71 75  column if the qu
da10: 65 72 79 20 69 73 0a 2a 2a 20 20 20 20 20 20 20  ery is.**       
da20: 20 20 20 73 75 63 63 65 73 73 66 75 6c 20 28 69     successful (i
da30: 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 72  f the function r
da40: 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b  eturns SQLITE_OK
da50: 29 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 37 34  )..**.** {F12374
da60: 7d 20 49 66 20 74 68 65 20 6e 72 6f 77 20 70 61  } If the nrow pa
da70: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
da80: 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d  te3_get_table()]
da90: 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 0a 2a 2a 20   is not NULL.** 
daa0: 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 5b 73           then [s
dab0: 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
dac0: 28 29 5d 20 77 72 69 74 65 20 74 68 65 20 6e 75  ()] write the nu
dad0: 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 69 6e 20  mber of rows in 
dae0: 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
daf0: 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68  result set of th
db00: 65 20 71 75 65 72 79 20 69 6e 74 6f 20 2a 6e 72  e query into *nr
db10: 6f 77 20 69 66 20 74 68 65 20 71 75 65 72 79 20  ow if the query 
db20: 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73  is.**          s
db30: 75 63 63 65 73 73 66 75 6c 20 28 69 66 20 74 68  uccessful (if th
db40: 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  e function retur
db50: 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 29 2e 0a 2a  ns SQLITE_OK)..*
db60: 2a 0a 2a 2a 20 7b 46 31 32 33 37 36 7d 20 54 68  *.** {F12376} Th
db70: 65 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  e [sqlite3_get_t
db80: 61 62 6c 65 28 29 5d 20 66 75 6e 63 74 69 6f 6e  able()] function
db90: 20 73 65 74 73 20 69 74 73 20 2a 6e 63 6f 6c 75   sets its *ncolu
dba0: 6d 6e 20 76 61 6c 75 65 0a 2a 2a 20 20 20 20 20  mn value.**     
dbb0: 20 20 20 20 20 74 6f 20 74 68 65 20 6e 75 6d 62       to the numb
dbc0: 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
dbd0: 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
dbe0: 6f 66 20 74 68 65 20 71 75 65 72 79 20 69 6e 20  of the query in 
dbf0: 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
dc00: 73 71 6c 20 70 61 72 61 6d 65 74 65 72 2c 20 6f  sql parameter, o
dc10: 72 20 74 6f 20 7a 65 72 6f 20 69 66 20 74 68 65  r to zero if the
dc20: 20 71 75 65 72 79 20 69 6e 20 73 71 6c 20 68 61   query in sql ha
dc30: 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 20 20  s an empty.**   
dc40: 20 20 20 20 20 20 20 72 65 73 75 6c 74 20 73 65         result se
dc50: 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  t..*/.int sqlite
dc60: 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 20 73  3_get_table(.  s
dc70: 71 6c 69 74 65 33 2a 2c 20 20 20 20 20 20 20 20  qlite3*,        
dc80: 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20       /* An open 
dc90: 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f  database */.  co
dca0: 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20  nst char *sql,  
dcb0: 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65      /* SQL to be
dcc0: 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20   evaluated */.  
dcd0: 63 68 61 72 20 2a 2a 2a 70 52 65 73 75 6c 74 2c  char ***pResult,
dce0: 20 20 20 20 20 20 2f 2a 20 52 65 73 75 6c 74 73        /* Results
dcf0: 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 2a 2f   of the query */
dd00: 0a 20 20 69 6e 74 20 2a 6e 72 6f 77 2c 20 20 20  .  int *nrow,   
dd10: 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62           /* Numb
dd20: 65 72 20 6f 66 20 72 65 73 75 6c 74 20 72 6f 77  er of result row
dd30: 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a  s written here *
dd40: 2f 0a 20 20 69 6e 74 20 2a 6e 63 6f 6c 75 6d 6e  /.  int *ncolumn
dd50: 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d  ,         /* Num
dd60: 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 63 6f  ber of result co
dd70: 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 68 65  lumns written he
dd80: 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 65  re */.  char **e
dd90: 72 72 6d 73 67 20 20 20 20 20 20 20 20 20 2f 2a  rrmsg         /*
dda0: 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74   Error msg writt
ddb0: 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f  en here */.);.vo
ddc0: 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  id sqlite3_free_
ddd0: 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 73  table(char **res
dde0: 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ult);../*.** CAP
ddf0: 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 64  I3REF: Formatted
de00: 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e 67   String Printing
de10: 20 46 75 6e 63 74 69 6f 6e 73 20 7b 46 31 37 34   Functions {F174
de20: 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  00}.**.** These 
de30: 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72  routines are wor
de40: 6b 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20 22  kalikes of the "
de50: 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c 79  printf()" family
de60: 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a   of functions.**
de70: 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61   from the standa
de80: 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a  rd C library..**
de90: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
dea0: 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73 71  mprintf() and sq
deb0: 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 29  lite3_vmprintf()
dec0: 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65 20   routines write 
ded0: 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73  their.** results
dee0: 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
def0: 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
df00: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a  te3_malloc()]..*
df10: 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20 72 65  * The strings re
df20: 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20  turned by these 
df30: 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68 6f  two routines sho
df40: 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73  uld be.** releas
df50: 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66  ed by [sqlite3_f
df60: 72 65 65 28 29 5d 2e 20 20 20 42 6f 74 68 20 72  ree()].   Both r
df70: 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 61  outines return a
df80: 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  .** NULL pointer
df90: 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   if [sqlite3_mal
dfa0: 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c 65  loc()] is unable
dfb0: 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f   to allocate eno
dfc0: 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f  ugh.** memory to
dfd0: 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74   hold the result
dfe0: 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  ing string..**.*
dff0: 2a 20 49 6e 20 73 71 6c 69 74 65 33 5f 73 6e 70  * In sqlite3_snp
e000: 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20  rintf() routine 
e010: 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 22 73  is similar to "s
e020: 6e 70 72 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a  nprintf()" from.
e030: 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72 64 20  ** the standard 
e040: 43 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20  C library.  The 
e050: 72 65 73 75 6c 74 20 69 73 20 77 72 69 74 74 65  result is writte
e060: 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75  n into the.** bu
e070: 66 66 65 72 20 73 75 70 70 6c 69 65 64 20 61 73  ffer supplied as
e080: 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
e090: 6d 65 74 65 72 20 77 68 6f 73 65 20 73 69 7a 65  meter whose size
e0a0: 20 69 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20   is given by.** 
e0b0: 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
e0c0: 74 65 72 2e 20 4e 6f 74 65 20 74 68 61 74 20 74  ter. Note that t
e0d0: 68 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65 0a  he order of the.
e0e0: 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 70 61 72  ** first two par
e0f0: 61 6d 65 74 65 72 73 20 69 73 20 72 65 76 65 72  ameters is rever
e100: 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74  sed from snprint
e110: 66 28 29 2e 20 20 54 68 69 73 20 69 73 20 61 6e  f().  This is an
e120: 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 61  .** historical a
e130: 63 63 69 64 65 6e 74 20 74 68 61 74 20 63 61 6e  ccident that can
e140: 6e 6f 74 20 62 65 20 66 69 78 65 64 20 77 69 74  not be fixed wit
e150: 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a  hout breaking.**
e160: 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
e170: 74 69 62 69 6c 69 74 79 2e 20 20 4e 6f 74 65 20  tibility.  Note 
e180: 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74 65  also that sqlite
e190: 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20  3_snprintf().** 
e1a0: 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
e1b0: 72 20 74 6f 20 69 74 73 20 62 75 66 66 65 72 20  r to its buffer 
e1c0: 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 6e  instead of the n
e1d0: 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72  umber of.** char
e1e0: 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79 20  acters actually 
e1f0: 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65  written into the
e200: 20 62 75 66 66 65 72 2e 20 20 57 65 20 61 64 6d   buffer.  We adm
e210: 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e  it that.** the n
e220: 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74  umber of charact
e230: 65 72 73 20 77 72 69 74 74 65 6e 20 77 6f 75 6c  ers written woul
e240: 64 20 62 65 20 61 20 6d 6f 72 65 20 75 73 65 66  d be a more usef
e250: 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c  ul return.** val
e260: 75 65 20 62 75 74 20 77 65 20 63 61 6e 6e 6f 74  ue but we cannot
e270: 20 63 68 61 6e 67 65 20 74 68 65 20 69 6d 70 6c   change the impl
e280: 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71  ementation of sq
e290: 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
e2a0: 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 20  .** now without 
e2b0: 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69  breaking compati
e2c0: 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 41 73  bility..**.** As
e2d0: 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75 66   long as the buf
e2e0: 66 65 72 20 73 69 7a 65 20 69 73 20 67 72 65 61  fer size is grea
e2f0: 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73  ter than zero, s
e300: 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
e310: 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20  ).** guarantees 
e320: 74 68 61 74 20 74 68 65 20 62 75 66 66 65 72 20  that the buffer 
e330: 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74  is always zero-t
e340: 65 72 6d 69 6e 61 74 65 64 2e 20 20 54 68 65 20  erminated.  The 
e350: 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74  first.** paramet
e360: 65 72 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f  er "n" is the to
e370: 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20  tal size of the 
e380: 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e  buffer, includin
e390: 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74  g space for.** t
e3a0: 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  he zero terminat
e3b0: 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67  or.  So the long
e3c0: 65 73 74 20 73 74 72 69 6e 67 20 74 68 61 74 20  est string that 
e3d0: 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c  can be completel
e3e0: 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c  y.** written wil
e3f0: 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74  l be n-1 charact
e400: 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ers..**.** These
e410: 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d   routines all im
e420: 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64  plement some add
e430: 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69  itional formatti
e440: 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68  ng.** options th
e450: 61 74 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f  at are useful fo
e460: 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53  r constructing S
e470: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  QL statements..*
e480: 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75  * All of the usu
e490: 61 6c 20 70 72 69 6e 74 66 20 66 6f 72 6d 61 74  al printf format
e4a0: 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70 70  ting options app
e4b0: 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f 6e  ly.  In addition
e4c0: 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61 72  , there.** is ar
e4d0: 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20 61 6e  e "%q", "%Q", an
e4e0: 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a  d "%z" options..
e4f0: 2a 2a 0a 2a 2a 20 54 68 65 20 25 71 20 6f 70 74  **.** The %q opt
e500: 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25  ion works like %
e510: 73 20 69 6e 20 74 68 61 74 20 69 74 20 73 75 62  s in that it sub
e520: 73 74 69 74 75 74 65 73 20 61 20 6e 75 6c 6c 2d  stitutes a null-
e530: 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74  terminated.** st
e540: 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 20 61 72  ring from the ar
e550: 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42 75  gument list.  Bu
e560: 74 20 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65  t %q also double
e570: 73 20 65 76 65 72 79 20 27 5c 27 27 20 63 68 61  s every '\'' cha
e580: 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73  racter..** %q is
e590: 20 64 65 73 69 67 6e 65 64 20 66 6f 72 20 75 73   designed for us
e5a0: 65 20 69 6e 73 69 64 65 20 61 20 73 74 72 69 6e  e inside a strin
e5b0: 67 20 6c 69 74 65 72 61 6c 2e 20 20 42 79 20 64  g literal.  By d
e5c0: 6f 75 62 6c 69 6e 67 20 65 61 63 68 20 27 5c 27  oubling each '\'
e5d0: 27 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 20 69  '.** character i
e5e0: 74 20 65 73 63 61 70 65 73 20 74 68 61 74 20 63  t escapes that c
e5f0: 68 61 72 61 63 74 65 72 20 61 6e 64 20 61 6c 6c  haracter and all
e600: 6f 77 73 20 69 74 20 74 6f 20 62 65 20 69 6e 73  ows it to be ins
e610: 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68  erted into.** th
e620: 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  e string..**.** 
e630: 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 73 6f 20  For example, so 
e640: 73 6f 6d 65 20 73 74 72 69 6e 67 20 76 61 72 69  some string vari
e650: 61 62 6c 65 20 63 6f 6e 74 61 69 6e 73 20 74 65  able contains te
e660: 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  xt as follows:.*
e670: 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
e680: 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20  ><pre>.**  char 
e690: 2a 7a 54 65 78 74 20 3d 20 22 49 74 27 73 20 61  *zText = "It's a
e6a0: 20 68 61 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a   happy day!";.**
e6b0: 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
e6c0: 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63  ote>.**.** One c
e6d0: 61 6e 20 75 73 65 20 74 68 69 73 20 74 65 78 74  an use this text
e6e0: 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65   in an SQL state
e6f0: 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  ment as follows:
e700: 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
e710: 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61  te><pre>.**  cha
e720: 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65  r *zSQL = sqlite
e730: 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52  3_mprintf("INSER
e740: 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c  T INTO table VAL
e750: 55 45 53 28 27 25 71 27 29 22 2c 20 7a 54 65 78  UES('%q')", zTex
e760: 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  t);.**  sqlite3_
e770: 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30  exec(db, zSQL, 0
e780: 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c  , 0, 0);.**  sql
e790: 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b  ite3_free(zSQL);
e7a0: 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
e7b0: 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65  kquote>.**.** Be
e7c0: 63 61 75 73 65 20 74 68 65 20 25 71 20 66 6f 72  cause the %q for
e7d0: 6d 61 74 20 73 74 72 69 6e 67 20 69 73 20 75 73  mat string is us
e7e0: 65 64 2c 20 74 68 65 20 27 5c 27 27 20 63 68 61  ed, the '\'' cha
e7f0: 72 61 63 74 65 72 20 69 6e 20 7a 54 65 78 74 0a  racter in zText.
e800: 2a 2a 20 69 73 20 65 73 63 61 70 65 64 20 61 6e  ** is escaped an
e810: 64 20 74 68 65 20 53 51 4c 20 67 65 6e 65 72 61  d the SQL genera
e820: 74 65 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77  ted is as follow
e830: 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
e840: 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49  uote><pre>.**  I
e850: 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
e860: 31 20 56 41 4c 55 45 53 28 27 49 74 27 27 73 20  1 VALUES('It''s 
e870: 61 20 68 61 70 70 79 20 64 61 79 21 27 29 0a 2a  a happy day!').*
e880: 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
e890: 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  uote>.**.** This
e8a0: 20 69 73 20 63 6f 72 72 65 63 74 2e 20 20 48 61   is correct.  Ha
e8b0: 64 20 77 65 20 75 73 65 64 20 25 73 20 69 6e 73  d we used %s ins
e8c0: 74 65 61 64 20 6f 66 20 25 71 2c 20 74 68 65 20  tead of %q, the 
e8d0: 67 65 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a  generated SQL.**
e8e0: 20 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b   would have look
e8f0: 65 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a  ed like this:.**
e900: 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
e910: 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54  <pre>.**  INSERT
e920: 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c   INTO table1 VAL
e930: 55 45 53 28 27 49 74 27 73 20 61 20 68 61 70 70  UES('It's a happ
e940: 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70  y day!');.** </p
e950: 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
e960: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f  .**.** This seco
e970: 6e 64 20 65 78 61 6d 70 6c 65 20 69 73 20 61 6e  nd example is an
e980: 20 53 51 4c 20 73 79 6e 74 61 78 20 65 72 72 6f   SQL syntax erro
e990: 72 2e 20 20 41 73 20 61 20 67 65 6e 65 72 61 6c  r.  As a general
e9a0: 20 72 75 6c 65 20 79 6f 75 0a 2a 2a 20 73 68 6f   rule you.** sho
e9b0: 75 6c 64 20 61 6c 77 61 79 73 20 75 73 65 20 25  uld always use %
e9c0: 71 20 69 6e 73 74 65 61 64 20 6f 66 20 25 73 20  q instead of %s 
e9d0: 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 74  when inserting t
e9e0: 65 78 74 20 69 6e 74 6f 20 61 20 73 74 72 69 6e  ext into a strin
e9f0: 67 20 0a 2a 2a 20 6c 69 74 65 72 61 6c 2e 0a 2a  g .** literal..*
ea00: 2a 0a 2a 2a 20 54 68 65 20 25 51 20 6f 70 74 69  *.** The %Q opti
ea10: 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71  on works like %q
ea20: 20 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f 20   except it also 
ea30: 61 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f 74  adds single quot
ea40: 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65  es around.** the
ea50: 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20   outside of the 
ea60: 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20 4f  total string.  O
ea70: 72 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  r if the paramet
ea80: 65 72 20 69 6e 20 74 68 65 20 61 72 67 75 6d 65  er in the argume
ea90: 6e 74 0a 2a 2a 20 6c 69 73 74 20 69 73 20 61 20  nt.** list is a 
eaa0: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51  NULL pointer, %Q
eab0: 20 73 75 62 73 74 69 74 75 74 65 73 20 74 68 65   substitutes the
eac0: 20 74 65 78 74 20 22 4e 55 4c 4c 22 20 28 77 69   text "NULL" (wi
ead0: 74 68 6f 75 74 20 73 69 6e 67 6c 65 0a 2a 2a 20  thout single.** 
eae0: 71 75 6f 74 65 73 29 20 69 6e 20 70 6c 61 63 65  quotes) in place
eaf0: 20 6f 66 20 74 68 65 20 25 51 20 6f 70 74 69 6f   of the %Q optio
eb00: 6e 2e 20 7b 45 4e 44 7d 20 20 53 6f 2c 20 66 6f  n. {END}  So, fo
eb10: 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63  r example, one c
eb20: 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20  ould say:.**.** 
eb30: 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
eb40: 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c  >.**  char *zSQL
eb50: 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e   = sqlite3_mprin
eb60: 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20  tf("INSERT INTO 
eb70: 74 61 62 6c 65 20 56 41 4c 55 45 53 28 25 51 29  table VALUES(%Q)
eb80: 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73  ", zText);.**  s
eb90: 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20  qlite3_exec(db, 
eba0: 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a  zSQL, 0, 0, 0);.
ebb0: 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65  **  sqlite3_free
ebc0: 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65  (zSQL);.** </pre
ebd0: 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
ebe0: 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 61 62  *.** The code ab
ebf0: 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64 65 72 20  ove will render 
ec00: 61 20 63 6f 72 72 65 63 74 20 53 51 4c 20 73 74  a correct SQL st
ec10: 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a  atement in the z
ec20: 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20  SQL.** variable 
ec30: 65 76 65 6e 20 69 66 20 74 68 65 20 7a 54 65 78  even if the zTex
ec40: 74 20 76 61 72 69 61 62 6c 65 20 69 73 20 61 20  t variable is a 
ec50: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
ec60: 0a 2a 2a 20 54 68 65 20 22 25 7a 22 20 66 6f 72  .** The "%z" for
ec70: 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77  matting option w
ec80: 6f 72 6b 73 20 65 78 61 63 74 6c 79 20 6c 69 6b  orks exactly lik
ec90: 65 20 22 25 73 22 20 77 69 74 68 20 74 68 65 0a  e "%s" with the.
eca0: 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74  ** addition that
ecb0: 20 61 66 74 65 72 20 74 68 65 20 73 74 72 69 6e   after the strin
ecc0: 67 20 68 61 73 20 62 65 65 6e 20 72 65 61 64 20  g has been read 
ecd0: 61 6e 64 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a  and copied into.
ece0: 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 2c 20 5b  ** the result, [
ecf0: 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
ed00: 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65  is called on the
ed10: 20 69 6e 70 75 74 20 73 74 72 69 6e 67 2e 20 7b   input string. {
ed20: 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  END}.**.** INVAR
ed30: 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31  IANTS:.**.** {F1
ed40: 37 34 30 33 7d 20 20 54 68 65 20 5b 73 71 6c 69  7403}  The [sqli
ed50: 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 20 61  te3_mprintf()] a
ed60: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 6d 70 72  nd [sqlite3_vmpr
ed70: 69 6e 74 66 28 29 5d 20 69 6e 74 65 72 66 61 63  intf()] interfac
ed80: 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  es.**           
ed90: 72 65 74 75 72 6e 20 65 69 74 68 65 72 20 70 6f  return either po
eda0: 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74  inters to zero-t
edb0: 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20  erminated UTF-8 
edc0: 73 74 72 69 6e 67 73 20 68 65 6c 64 20 69 6e 0a  strings held in.
edd0: 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6d 65 6d  **           mem
ede0: 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
edf0: 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
ee00: 63 28 29 5d 20 6f 72 20 4e 55 4c 4c 20 70 6f 69  c()] or NULL poi
ee10: 6e 74 65 72 73 20 69 66 0a 2a 2a 20 20 20 20 20  nters if.**     
ee20: 20 20 20 20 20 20 61 20 63 61 6c 6c 20 74 6f 20        a call to 
ee30: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
ee40: 29 5d 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20  )] fails..**.** 
ee50: 7b 46 31 37 34 30 36 7d 20 20 54 68 65 20 5b 73  {F17406}  The [s
ee60: 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
ee70: 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 72 69  )] interface wri
ee80: 74 65 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69  tes a zero-termi
ee90: 6e 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  nated.**        
eea0: 20 20 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20     UTF-8 string 
eeb0: 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72 20  into the buffer 
eec0: 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68  pointed to by th
eed0: 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
eee0: 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  er.**           
eef0: 70 72 6f 76 69 64 65 64 20 74 68 61 74 20 74 68  provided that th
ef00: 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
ef10: 72 20 69 73 20 67 72 65 61 74 65 72 20 74 68 61  r is greater tha
ef20: 6e 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 7b 46  n zero..**.** {F
ef30: 31 37 34 30 37 7d 20 20 54 68 65 20 5b 73 71 6c  17407}  The [sql
ef40: 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
ef50: 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20   interface does 
ef60: 6e 6f 74 20 77 72 69 74 65 73 20 73 6c 6f 74 73  not writes slots
ef70: 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   of.**          
ef80: 20 69 74 73 20 6f 75 74 70 75 74 20 62 75 66 66   its output buff
ef90: 65 72 20 28 74 68 65 20 73 65 63 6f 6e 64 20 70  er (the second p
efa0: 61 72 61 6d 65 74 65 72 29 20 6f 75 74 73 69 64  arameter) outsid
efb0: 65 20 74 68 65 20 72 61 6e 67 65 0a 2a 2a 20 20  e the range.**  
efc0: 20 20 20 20 20 20 20 20 20 6f 66 20 30 20 74 68           of 0 th
efd0: 72 6f 75 67 68 20 4e 2d 31 20 28 77 68 65 72 65  rough N-1 (where
efe0: 20 4e 20 69 73 20 74 68 65 20 66 69 72 73 74 20   N is the first 
eff0: 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 20 20  parameter).**   
f000: 20 20 20 20 20 20 20 20 72 65 67 61 72 64 6c 65          regardle
f010: 73 73 20 6f 66 20 74 68 65 20 6c 65 6e 67 74 68  ss of the length
f020: 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 0a 2a   of the string.*
f030: 2a 20 20 20 20 20 20 20 20 20 20 20 72 65 71 75  *           requ
f040: 65 73 74 65 64 20 62 79 20 74 68 65 20 66 6f 72  ested by the for
f050: 6d 61 74 20 73 70 65 63 69 66 69 63 61 74 69 6f  mat specificatio
f060: 6e 2e 0a 2a 2a 20 20 20 0a 2a 2f 0a 63 68 61 72  n..**   .*/.char
f070: 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74   *sqlite3_mprint
f080: 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e  f(const char*,..
f090: 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65  .);.char *sqlite
f0a0: 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74  3_vmprintf(const
f0b0: 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29   char*, va_list)
f0c0: 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  ;.char *sqlite3_
f0d0: 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61  snprintf(int,cha
f0e0: 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  r*,const char*, 
f0f0: 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ...);../*.** CAP
f100: 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c  I3REF: Memory Al
f110: 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73 74  location Subsyst
f120: 65 6d 20 7b 46 31 37 33 30 30 7d 0a 2a 2a 0a 2a  em {F17300}.**.*
f130: 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72  * The SQLite cor
f140: 65 20 20 75 73 65 73 20 74 68 65 73 65 20 74 68  e  uses these th
f150: 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72  ree routines for
f160: 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a   all of its own.
f170: 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f  ** internal memo
f180: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65  ry allocation ne
f190: 65 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74  eds. "Core" in t
f1a0: 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74  he previous sent
f1b0: 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74  ence.** does not
f1c0: 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69   include operati
f1d0: 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66  ng-system specif
f1e0: 69 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  ic VFS implement
f1f0: 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 77  ation.  The.** w
f200: 69 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73 20  indows VFS uses 
f210: 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 20 61 6e  native malloc an
f220: 64 20 66 72 65 65 20 66 6f 72 20 73 6f 6d 65 20  d free for some 
f230: 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  operations..**.*
f240: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61  * The sqlite3_ma
f250: 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 72  lloc() routine r
f260: 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
f270: 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f   to a block.** o
f280: 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61 73  f memory at leas
f290: 74 20 4e 20 62 79 74 65 73 20 69 6e 20 6c 65 6e  t N bytes in len
f2a0: 67 74 68 2c 20 77 68 65 72 65 20 4e 20 69 73 20  gth, where N is 
f2b0: 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  the parameter..*
f2c0: 2a 20 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c  * If sqlite3_mal
f2d0: 6c 6f 63 28 29 20 69 73 20 75 6e 61 62 6c 65 20  loc() is unable 
f2e0: 74 6f 20 6f 62 74 61 69 6e 20 73 75 66 66 69 63  to obtain suffic
f2f0: 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d  ient free.** mem
f300: 6f 72 79 2c 20 69 74 20 72 65 74 75 72 6e 73 20  ory, it returns 
f310: 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20  a NULL pointer. 
f320: 20 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   If the paramete
f330: 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  r N to.** sqlite
f340: 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65  3_malloc() is ze
f350: 72 6f 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74  ro or negative t
f360: 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  hen sqlite3_mall
f370: 6f 63 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20  oc() returns.** 
f380: 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
f390: 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20 73 71  **.** Calling sq
f3a0: 6c 69 74 65 33 5f 66 72 65 65 28 29 20 77 69 74  lite3_free() wit
f3b0: 68 20 61 20 70 6f 69 6e 74 65 72 20 70 72 65 76  h a pointer prev
f3c0: 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 0a  iously returned.
f3d0: 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61  ** by sqlite3_ma
f3e0: 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65  lloc() or sqlite
f3f0: 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65  3_realloc() rele
f400: 61 73 65 73 20 74 68 61 74 20 6d 65 6d 6f 72 79  ases that memory
f410: 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d   so.** that it m
f420: 69 67 68 74 20 62 65 20 72 65 75 73 65 64 2e 20  ight be reused. 
f430: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65   The sqlite3_fre
f440: 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a  e() routine is.*
f450: 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20  * a no-op if is 
f460: 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55  called with a NU
f470: 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73  LL pointer.  Pas
f480: 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  sing a NULL poin
f490: 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65  ter.** to sqlite
f4a0: 33 5f 66 72 65 65 28 29 20 69 73 20 68 61 72 6d  3_free() is harm
f4b0: 6c 65 73 73 2e 20 20 41 66 74 65 72 20 62 65 69  less.  After bei
f4c0: 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79  ng freed, memory
f4d0: 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68  .** should neith
f4e0: 65 72 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77  er be read nor w
f4f0: 72 69 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65  ritten.  Even re
f500: 61 64 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79  ading previously
f510: 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79   freed.** memory
f520: 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e   might result in
f530: 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20   a segmentation 
f540: 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73  fault or other s
f550: 65 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20  evere error..** 
f560: 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f  Memory corruptio
f570: 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f  n, a segmentatio
f580: 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65  n fault, or othe
f590: 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a  r severe error.*
f5a0: 2a 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69  * might result i
f5b0: 66 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  f sqlite3_free()
f5c0: 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20   is called with 
f5d0: 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74  a non-NULL point
f5e0: 65 72 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e  er that.** was n
f5f0: 6f 74 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ot obtained from
f600: 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
f610: 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 66 72 65  ) or sqlite3_fre
f620: 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  e()..**.** The s
f630: 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
f640: 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d   interface attem
f650: 70 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61 0a  pts to resize a.
f660: 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20  ** prior memory 
f670: 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65  allocation to be
f680: 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65   at least N byte
f690: 73 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  s, where N is th
f6a0: 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61  e.** second para
f6b0: 6d 65 74 65 72 2e 20 20 54 68 65 20 6d 65 6d 6f  meter.  The memo
f6c0: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f  ry allocation to
f6d0: 20 62 65 20 72 65 73 69 7a 65 64 20 69 73 20 74   be resized is t
f6e0: 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61  he first.** para
f6f0: 6d 65 74 65 72 2e 20 20 49 66 20 74 68 65 20 66  meter.  If the f
f700: 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
f710: 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  o sqlite3_reallo
f720: 63 28 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c  c().** is a NULL
f730: 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74   pointer then it
f740: 73 20 62 65 68 61 76 69 6f 72 20 69 73 20 69 64  s behavior is id
f750: 65 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69  entical to calli
f760: 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61  ng.** sqlite3_ma
f770: 6c 6c 6f 63 28 4e 29 20 77 68 65 72 65 20 4e 20  lloc(N) where N 
f780: 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  is the second pa
f790: 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
f7a0: 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a  e3_realloc()..**
f7b0: 20 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 70   If the second p
f7c0: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
f7d0: 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 73  te3_realloc() is
f7e0: 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61   zero or.** nega
f7f0: 74 69 76 65 20 74 68 65 6e 20 74 68 65 20 62 65  tive then the be
f800: 68 61 76 69 6f 72 20 69 73 20 65 78 61 63 74 6c  havior is exactl
f810: 79 20 74 68 65 20 73 61 6d 65 20 61 73 20 63 61  y the same as ca
f820: 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33  lling.** sqlite3
f830: 5f 66 72 65 65 28 50 29 20 77 68 65 72 65 20 50  _free(P) where P
f840: 20 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61   is the first pa
f850: 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
f860: 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a  e3_realloc()..**
f870: 20 53 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   Sqlite3_realloc
f880: 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  () returns a poi
f890: 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79  nter to a memory
f8a0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f   allocation.** o
f8b0: 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74  f at least N byt
f8c0: 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55  es in size or NU
f8d0: 4c 4c 20 69 66 20 73 75 66 66 69 63 69 65 6e 74  LL if sufficient
f8e0: 20 6d 65 6d 6f 72 79 20 69 73 20 75 6e 61 76 61   memory is unava
f8f0: 69 6c 61 62 6c 65 2e 0a 2a 2a 20 49 66 20 4d 20  ilable..** If M 
f900: 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  is the size of t
f910: 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
f920: 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c  ion, then min(N,
f930: 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74  M) bytes.** of t
f940: 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
f950: 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 20 69  ion are copied i
f960: 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e  nto the beginnin
f970: 67 20 6f 66 20 62 75 66 66 65 72 20 72 65 74 75  g of buffer retu
f980: 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74  rned.** by sqlit
f990: 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64  e3_realloc() and
f9a0: 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
f9b0: 61 74 69 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a  ation is freed..
f9c0: 2a 2a 20 49 66 20 73 71 6c 69 74 65 33 5f 72 65  ** If sqlite3_re
f9d0: 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20  alloc() returns 
f9e0: 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 70  NULL, then the p
f9f0: 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  rior allocation.
fa00: 2a 2a 20 69 73 20 6e 6f 74 20 66 72 65 65 64 2e  ** is not freed.
fa10: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 65 6d 6f 72  .**.** The memor
fa20: 79 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  y returned by sq
fa30: 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 61  lite3_malloc() a
fa40: 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  nd sqlite3_reall
fa50: 6f 63 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61 79  oc().** is alway
fa60: 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 74 20  s aligned to at 
fa70: 6c 65 61 73 74 20 61 6e 20 38 20 62 79 74 65 20  least an 8 byte 
fa80: 62 6f 75 6e 64 61 72 79 2e 20 7b 45 4e 44 7d 0a  boundary. {END}.
fa90: 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c  **.** The defaul
faa0: 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  t implementation
fab0: 0a 2a 2a 20 6f 66 20 74 68 65 20 6d 65 6d 6f 72  .** of the memor
fac0: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62  y allocation sub
fad0: 73 79 73 74 65 6d 20 75 73 65 73 20 74 68 65 20  system uses the 
fae0: 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f  malloc(), reallo
faf0: 63 28 29 0a 2a 2a 20 61 6e 64 20 66 72 65 65 28  c().** and free(
fb00: 29 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68  ) provided by th
fb10: 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  e standard C lib
fb20: 72 61 72 79 2e 20 7b 46 31 37 33 38 32 7d 20 48  rary. {F17382} H
fb30: 6f 77 65 76 65 72 2c 20 69 66 20 0a 2a 2a 20 53  owever, if .** S
fb40: 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
fb50: 64 20 77 69 74 68 20 74 68 65 20 66 6f 6c 6c 6f  d with the follo
fb60: 77 69 6e 67 20 43 20 70 72 65 70 72 6f 63 65 73  wing C preproces
fb70: 73 6f 72 20 6d 61 63 72 6f 0a 2a 2a 0a 2a 2a 20  sor macro.**.** 
fb80: 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 20 53 51 4c  <blockquote> SQL
fb90: 49 54 45 5f 4d 45 4d 4f 52 59 5f 53 49 5a 45 3d  ITE_MEMORY_SIZE=
fba0: 3c 69 3e 4e 4e 4e 3c 2f 69 3e 20 3c 2f 62 6c 6f  <i>NNN</i> </blo
fbb0: 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 77  ckquote>.**.** w
fbc0: 68 65 72 65 20 3c 69 3e 4e 4e 4e 3c 2f 69 3e 20  here <i>NNN</i> 
fbd0: 69 73 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74  is an integer, t
fbe0: 68 65 6e 20 53 51 4c 69 74 65 20 63 72 65 61 74  hen SQLite creat
fbf0: 65 20 61 20 73 74 61 74 69 63 0a 2a 2a 20 61 72  e a static.** ar
fc00: 72 61 79 20 6f 66 20 61 74 20 6c 65 61 73 74 20  ray of at least 
fc10: 3c 69 3e 4e 4e 4e 3c 2f 69 3e 20 62 79 74 65 73  <i>NNN</i> bytes
fc20: 20 69 6e 20 73 69 7a 65 20 61 6e 64 20 75 73 65   in size and use
fc30: 20 74 68 61 74 20 61 72 72 61 79 0a 2a 2a 20 66   that array.** f
fc40: 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79  or all of its dy
fc50: 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c  namic memory all
fc60: 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 7b  ocation needs. {
fc70: 45 4e 44 7d 20 20 41 64 64 69 74 69 6f 6e 61 6c  END}  Additional
fc80: 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
fc90: 61 74 6f 72 20 6f 70 74 69 6f 6e 73 20 6d 61 79  ator options may
fca0: 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74   be added in fut
fcb0: 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a  ure releases..**
fcc0: 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 65  .** In SQLite ve
fcd0: 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20  rsion 3.5.0 and 
fce0: 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70 6f  3.5.1, it was po
fcf0: 73 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e 65  ssible to define
fd00: 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f 4f  .** the SQLITE_O
fd10: 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43  MIT_MEMORY_ALLOC
fd20: 41 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c  ATION which woul
fd30: 64 20 63 61 75 73 65 20 74 68 65 20 62 75 69 6c  d cause the buil
fd40: 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  t-in.** implemen
fd50: 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 20  tation of these 
fd60: 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 6f  routines to be o
fd70: 6d 69 74 74 65 64 2e 20 20 54 68 61 74 20 63 61  mitted.  That ca
fd80: 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e  pability.** is n
fd90: 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 65  o longer provide
fda0: 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69  d.  Only built-i
fdb0: 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
fdc0: 6f 72 73 20 63 61 6e 20 62 65 0a 2a 2a 20 75 73  ors can be.** us
fdd0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 77 69  ed..**.** The wi
fde0: 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65 72 66 61  ndows OS interfa
fdf0: 63 65 20 6c 61 79 65 72 20 63 61 6c 6c 73 0a 2a  ce layer calls.*
fe00: 2a 20 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c  * the system mal
fe10: 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29  loc() and free()
fe20: 20 64 69 72 65 63 74 6c 79 20 77 68 65 6e 20 63   directly when c
fe30: 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c  onverting.** fil
fe40: 65 6e 61 6d 65 73 20 62 65 74 77 65 65 6e 20 74  enames between t
fe50: 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e  he UTF-8 encodin
fe60: 67 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65  g used by SQLite
fe70: 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65 76 65 72  .** and whatever
fe80: 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69   filename encodi
fe90: 6e 67 20 69 73 20 75 73 65 64 20 62 79 20 74 68  ng is used by th
fea0: 65 20 70 61 72 74 69 63 75 6c 61 72 20 77 69 6e  e particular win
feb0: 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61  dows.** installa
fec0: 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c  tion.  Memory al
fed0: 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 73 20  location errors 
fee0: 61 72 65 20 64 65 74 65 63 74 65 64 2c 20 62 75  are detected, bu
fef0: 74 0a 2a 2a 20 74 68 65 79 20 61 72 65 20 72 65  t.** they are re
ff00: 70 6f 72 74 65 64 20 62 61 63 6b 20 61 73 20 5b  ported back as [
ff10: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d  SQLITE_CANTOPEN]
ff20: 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49   or.** [SQLITE_I
ff30: 4f 45 52 52 5d 20 72 61 74 68 65 72 20 74 68 61  OERR] rather tha
ff40: 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d  n [SQLITE_NOMEM]
ff50: 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
ff60: 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 30  TS:.**.** {F1730
ff70: 33 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  3}  The [sqlite3
ff80: 5f 6d 61 6c 6c 6f 63 28 4e 29 5d 20 69 6e 74 65  _malloc(N)] inte
ff90: 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 65 69  rface returns ei
ffa0: 74 68 65 72 20 61 20 70 6f 69 6e 74 65 72 20 74  ther a pointer t
ffb0: 6f 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  o .**           
ffc0: 6e 65 77 6c 79 20 63 68 65 63 6b 65 64 2d 6f 75  newly checked-ou
ffd0: 74 20 62 6c 6f 63 6b 20 6f 66 20 61 74 20 6c 65  t block of at le
ffe0: 61 73 74 20 4e 20 62 79 74 65 73 20 6f 66 20 6d  ast N bytes of m
fff0: 65 6d 6f 72 79 0a 2a 2a 20 20 20 20 20 20 20 20  emory.**        
10000 20 20 20 74 68 61 74 20 69 73 20 38 2d 62 79 74     that is 8-byt
10010 65 20 61 6c 69 67 6e 65 64 2c 20 0a 2a 2a 20 20  e aligned, .**  
10020 20 20 20 20 20 20 20 20 20 6f 72 20 69 74 20 72           or it r
10030 65 74 75 72 6e 73 20 4e 55 4c 4c 20 69 66 20 69  eturns NULL if i
10040 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 66  t is unable to f
10050 75 6c 66 69 6c 6c 20 74 68 65 20 72 65 71 75 65  ulfill the reque
10060 73 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 30  st..**.** {F1730
10070 34 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  4}  The [sqlite3
10080 5f 6d 61 6c 6c 6f 63 28 4e 29 5d 20 69 6e 74 65  _malloc(N)] inte
10090 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
100a0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 0a  NULL pointer if.
100b0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 4e 20 69  **           N i
100c0 73 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65  s less than or e
100d0 71 75 61 6c 20 74 6f 20 7a 65 72 6f 2e 0a 2a 2a  qual to zero..**
100e0 0a 2a 2a 20 7b 46 31 37 33 30 35 7d 20 20 54 68  .** {F17305}  Th
100f0 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  e [sqlite3_free(
10100 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  P)] interface re
10110 6c 65 61 73 65 73 20 6d 65 6d 6f 72 79 20 70 72  leases memory pr
10120 65 76 69 6f 75 73 6c 79 0a 2a 2a 20 20 20 20 20  eviously.**     
10130 20 20 20 20 20 20 72 65 74 75 72 6e 65 64 20 66        returned f
10140 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
10150 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  loc()] or [sqlit
10160 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2c 0a 2a  e3_realloc()],.*
10170 2a 20 20 20 20 20 20 20 20 20 20 20 6d 61 6b 69  *           maki
10180 6e 67 20 69 74 20 61 76 61 69 6c 61 62 6c 65 20  ng it available 
10190 66 6f 72 20 72 65 75 73 65 2e 0a 2a 2a 0a 2a 2a  for reuse..**.**
101a0 20 7b 46 31 37 33 30 36 7d 20 20 41 20 63 61 6c   {F17306}  A cal
101b0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72  l to [sqlite3_fr
101c0 65 65 28 4e 55 4c 4c 29 5d 20 69 73 20 61 20 68  ee(NULL)] is a h
101d0 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a  armless no-op..*
101e0 2a 0a 2a 2a 20 7b 46 31 37 33 31 30 7d 20 20 41  *.** {F17310}  A
101f0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
10200 33 5f 72 65 61 6c 6c 6f 63 28 30 2c 4e 29 5d 20  3_realloc(0,N)] 
10210 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f  is equivalent to
10220 20 61 20 63 61 6c 6c 0a 2a 2a 20 20 20 20 20 20   a call.**      
10230 20 20 20 20 20 74 6f 20 5b 73 71 6c 69 74 65 33       to [sqlite3
10240 5f 6d 61 6c 6c 6f 63 28 4e 29 5d 2e 0a 2a 2a 0a  _malloc(N)]..**.
10250 2a 2a 20 7b 46 31 37 33 31 32 7d 20 20 41 20 63  ** {F17312}  A c
10260 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
10270 72 65 61 6c 6c 6f 63 28 50 2c 30 29 5d 20 69 73  realloc(P,0)] is
10280 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 61   equivalent to a
10290 20 63 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20   call.**        
102a0 20 20 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66     to [sqlite3_f
102b0 72 65 65 28 50 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  ree(P)]..**.** {
102c0 46 31 37 33 31 35 7d 20 20 54 68 65 20 53 51 4c  F17315}  The SQL
102d0 69 74 65 20 63 6f 72 65 20 75 73 65 73 20 5b 73  ite core uses [s
102e0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
102f0 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  , [sqlite3_reall
10300 6f 63 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  oc()],.**       
10310 20 20 20 20 61 6e 64 20 5b 73 71 6c 69 74 65 33      and [sqlite3
10320 5f 66 72 65 65 28 29 5d 20 66 6f 72 20 61 6c 6c  _free()] for all
10330 20 6f 66 20 69 74 73 20 6d 65 6d 6f 72 79 20 61   of its memory a
10340 6c 6c 6f 63 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a  llocation and.**
10350 20 20 20 20 20 20 20 20 20 20 20 64 65 61 6c 6c             deall
10360 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a  ocation needs..*
10370 2a 0a 2a 2a 20 7b 46 31 37 33 31 38 7d 20 20 54  *.** {F17318}  T
10380 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  he [sqlite3_real
10390 6c 6f 63 28 50 2c 4e 29 5d 20 69 6e 74 65 72 66  loc(P,N)] interf
103a0 61 63 65 20 72 65 74 75 72 6e 73 20 65 69 74 68  ace returns eith
103b0 65 72 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  er a pointer.** 
103c0 20 20 20 20 20 20 20 20 20 20 74 6f 20 61 20 62            to a b
103d0 6c 6f 63 6b 20 6f 66 20 63 68 65 63 6b 65 64 2d  lock of checked-
103e0 6f 75 74 20 6d 65 6d 6f 72 79 20 6f 66 20 61 74  out memory of at
103f0 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69   least N bytes i
10400 6e 20 73 69 7a 65 0a 2a 2a 20 20 20 20 20 20 20  n size.**       
10410 20 20 20 20 74 68 61 74 20 69 73 20 38 2d 62 79      that is 8-by
10420 74 65 20 61 6c 69 67 6e 65 64 2c 20 6f 72 20 61  te aligned, or a
10430 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
10440 2a 0a 2a 2a 20 7b 46 31 37 33 32 31 7d 20 20 57  *.** {F17321}  W
10450 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 61  hen [sqlite3_rea
10460 6c 6c 6f 63 28 50 2c 4e 29 5d 20 72 65 74 75 72  lloc(P,N)] retur
10470 6e 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f  ns a non-NULL po
10480 69 6e 74 65 72 2c 20 69 74 20 66 69 72 73 74 0a  inter, it first.
10490 2a 2a 20 20 20 20 20 20 20 20 20 20 20 63 6f 70  **           cop
104a0 69 65 73 20 74 68 65 20 66 69 72 73 74 20 4b 20  ies the first K 
104b0 62 79 74 65 73 20 6f 66 20 63 6f 6e 74 65 6e 74  bytes of content
104c0 20 66 72 6f 6d 20 50 20 69 6e 74 6f 20 74 68 65   from P into the
104d0 20 6e 65 77 6c 79 20 61 6c 6c 6f 63 61 74 65 64   newly allocated
104e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 77 68  .**           wh
104f0 65 72 65 20 4b 20 69 73 20 74 68 65 20 6c 65 73  ere K is the les
10500 73 6f 72 20 6f 66 20 4e 20 61 6e 64 20 74 68 65  sor of N and the
10510 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66   size of the buf
10520 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  fer P..**.** {F1
10530 37 33 32 32 7d 20 20 57 68 65 6e 20 5b 73 71 6c  7322}  When [sql
10540 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 50 2c 4e  ite3_realloc(P,N
10550 29 5d 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e  )] returns a non
10560 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69  -NULL pointer, i
10570 74 20 66 69 72 73 74 0a 2a 2a 20 20 20 20 20 20  t first.**      
10580 20 20 20 20 20 72 65 6c 65 61 73 65 73 20 74 68       releases th
10590 65 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a  e buffer P..**.*
105a0 2a 20 7b 46 31 37 33 32 33 7d 20 20 57 68 65 6e  * {F17323}  When
105b0 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
105c0 63 28 50 2c 4e 29 5d 20 72 65 74 75 72 6e 73 20  c(P,N)] returns 
105d0 4e 55 4c 4c 2c 20 74 68 65 20 62 75 66 66 65 72  NULL, the buffer
105e0 20 50 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20   P is.**        
105f0 20 20 20 6e 6f 74 20 6d 6f 64 69 66 69 65 64 20     not modified 
10600 6f 72 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a  or released..**.
10610 2a 2a 20 4c 49 4d 49 54 41 54 49 4f 4e 53 3a 0a  ** LIMITATIONS:.
10620 2a 2a 0a 2a 2a 20 7b 55 31 37 33 35 30 7d 20 20  **.** {U17350}  
10630 54 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75  The pointer argu
10640 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65  ments to [sqlite
10650 33 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73  3_free()] and [s
10660 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
10670 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6d  ].**           m
10680 75 73 74 20 62 65 20 65 69 74 68 65 72 20 4e 55  ust be either NU
10690 4c 4c 20 6f 72 20 65 6c 73 65 20 61 20 70 6f 69  LL or else a poi
106a0 6e 74 65 72 20 6f 62 74 61 69 6e 65 64 20 66 72  nter obtained fr
106b0 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20 20 20  om a prior.**   
106c0 20 20 20 20 20 20 20 20 69 6e 76 6f 63 61 74 69          invocati
106d0 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d  on of [sqlite3_m
106e0 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c  alloc()] or [sql
106f0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20  ite3_realloc()] 
10700 74 68 61 74 20 68 61 73 0a 2a 2a 20 20 20 20 20  that has.**     
10710 20 20 20 20 20 20 6e 6f 74 20 62 65 65 6e 20 72        not been r
10720 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b  eleased..**.** {
10730 55 31 37 33 35 31 7d 20 20 54 68 65 20 61 70 70  U17351}  The app
10740 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  lication must no
10750 74 20 72 65 61 64 20 6f 72 20 77 72 69 74 65 20  t read or write 
10760 61 6e 79 20 70 61 72 74 20 6f 66 20 0a 2a 2a 20  any part of .** 
10770 20 20 20 20 20 20 20 20 20 20 61 20 62 6c 6f 63            a bloc
10780 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65  k of memory afte
10790 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 72 65  r it has been re
107a0 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20  leased using.** 
107b0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
107c0 65 33 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b 73  e3_free()] or [s
107d0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
107e0 5d 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 2a 73  ]..**.*/.void *s
107f0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e  qlite3_malloc(in
10800 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  t);.void *sqlite
10810 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c  3_realloc(void*,
10820 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69   int);.void sqli
10830 74 65 33 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b  te3_free(void*);
10840 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
10850 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74  : Memory Allocat
10860 6f 72 20 53 74 61 74 69 73 74 69 63 73 20 7b 46  or Statistics {F
10870 31 37 33 37 30 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c  17370}.**.** SQL
10880 69 74 65 20 70 72 6f 76 69 64 65 73 20 74 68 65  ite provides the
10890 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61 63 65  se two interface
108a0 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e 67 20  s for reporting 
108b0 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a 2a 2a  on the status.**
108c0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
108d0 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c  _malloc()], [sql
108e0 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e  ite3_free()], an
108f0 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  d [sqlite3_reall
10900 6f 63 28 29 5d 0a 2a 2a 20 74 68 65 20 6d 65 6d  oc()].** the mem
10910 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
10920 75 62 73 79 73 74 65 6d 20 69 6e 63 6c 75 64 65  ubsystem include
10930 64 20 77 69 74 68 69 6e 20 74 68 65 20 53 51 4c  d within the SQL
10940 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ite..**.** INVAR
10950 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31  IANTS:.**.** {F1
10960 37 33 37 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  7371} The [sqlit
10970 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
10980 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ] routine return
10990 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
109a0 20 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65    number of byte
109b0 73 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72 72  s of memory curr
109c0 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e  ently outstandin
109d0 67 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 28  g .**          (
109e0 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f 74  malloced but not
109f0 20 66 72 65 65 64 29 2e 0a 2a 2a 0a 2a 2a 20 7b   freed)..**.** {
10a00 46 31 37 33 37 33 7d 20 54 68 65 20 5b 73 71 6c  F17373} The [sql
10a10 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
10a20 77 61 74 65 72 28 29 5d 20 72 6f 75 74 69 6e 65  water()] routine
10a30 20 72 65 74 75 72 6e 73 20 74 68 65 20 6d 61 78   returns the max
10a40 69 6d 75 6d 0a 2a 2a 20 20 20 20 20 20 20 20 20  imum.**         
10a50 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74   value of [sqlit
10a60 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
10a70 5d 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73  ] .**          s
10a80 69 6e 63 65 20 74 68 65 20 68 69 67 68 77 61 74  ince the highwat
10a90 65 72 20 6d 61 72 6b 20 77 61 73 20 6c 61 73 74  er mark was last
10aa0 20 72 65 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46   reset..**.** {F
10ab0 31 37 33 37 34 7d 20 54 68 65 20 76 61 6c 75 65  17374} The value
10ac0 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  s returned by [s
10ad0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
10ae0 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 20 20 20  ed()] and.**    
10af0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6d        [sqlite3_m
10b00 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
10b10 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f  )] include any o
10b20 76 65 72 68 65 61 64 0a 2a 2a 20 20 20 20 20 20  verhead.**      
10b30 20 20 20 20 61 64 64 65 64 20 62 79 20 53 51 4c      added by SQL
10b40 69 74 65 20 69 6e 20 69 74 73 20 69 6d 70 6c 65  ite in its imple
10b50 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71  mentation of [sq
10b60 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c  lite3_malloc()],
10b70 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 75 74  .**          but
10b80 20 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 61 64   not overhead ad
10b90 64 65 64 20 62 79 20 74 68 65 20 61 6e 79 20 75  ded by the any u
10ba0 6e 64 65 72 6c 79 69 6e 67 20 73 79 73 74 65 6d  nderlying system
10bb0 20 6c 69 62 72 61 72 79 0a 2a 2a 20 20 20 20 20   library.**     
10bc0 20 20 20 20 20 72 6f 75 74 69 6e 65 73 20 74 68       routines th
10bd0 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  at [sqlite3_mall
10be0 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a  oc()] may call..
10bf0 2a 2a 20 0a 2a 2a 20 7b 46 31 37 33 37 35 7d 20  ** .** {F17375} 
10c00 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 68 77  The memory highw
10c10 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72 65 73  ater mark is res
10c20 65 74 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e  et to the curren
10c30 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 20 20  t value of.**   
10c40 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
10c50 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 69  memory_used()] i
10c60 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68  f and only if th
10c70 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  e parameter to.*
10c80 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
10c90 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
10ca0 61 74 65 72 28 29 5d 20 69 73 20 74 72 75 65 2e  ater()] is true.
10cb0 20 20 54 68 65 20 76 61 6c 75 65 20 72 65 74 75    The value retu
10cc0 72 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  rned.**         
10cd0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d   by [sqlite3_mem
10ce0 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 31 29  ory_highwater(1)
10cf0 5d 20 69 73 20 74 68 65 20 68 69 67 68 77 61 74  ] is the highwat
10d00 65 72 20 6d 61 72 6b 0a 2a 2a 20 20 20 20 20 20  er mark.**      
10d10 20 20 20 20 70 72 69 6f 72 20 74 6f 20 74 68 65      prior to the
10d20 20 72 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74   reset..*/.sqlit
10d30 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
10d40 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69  _memory_used(voi
10d50 64 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  d);.sqlite3_int6
10d60 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79  4 sqlite3_memory
10d70 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74 20 72  _highwater(int r
10d80 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a  esetFlag);../*.*
10d90 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73 65 75  * CAPI3REF: Pseu
10da0 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72  do-Random Number
10db0 20 47 65 6e 65 72 61 74 6f 72 20 7b 46 31 37 33   Generator {F173
10dc0 39 30 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  90}.**.** SQLite
10dd0 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67 68   contains a high
10de0 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d  -quality pseudo-
10df0 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65  random number ge
10e00 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20 75  nerator (PRNG) u
10e10 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74  sed to.** select
10e20 20 72 61 6e 64 6f 6d 20 52 4f 57 49 44 73 20 77   random ROWIDs w
10e30 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e 65  hen inserting ne
10e40 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f 20 61  w records into a
10e50 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61   table that.** a
10e60 6c 72 65 61 64 79 20 75 73 65 73 20 74 68 65 20  lready uses the 
10e70 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62 6c 65  largest possible
10e80 20 52 4f 57 49 44 2e 20 20 54 68 65 20 50 52 4e   ROWID.  The PRN
10e90 47 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 66  G is also used f
10ea0 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d  or.** the build-
10eb0 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20  in random() and 
10ec0 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c  randomblob() SQL
10ed0 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69   functions.  Thi
10ee0 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f  s interface allo
10ef0 77 73 0a 2a 2a 20 61 70 70 6c 69 61 74 69 6f 6e  ws.** appliation
10f00 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20  s to access the 
10f10 73 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f 74  same PRNG for ot
10f20 68 65 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a  her purposes..**
10f30 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 74 68  .** A call to th
10f40 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65  is routine store
10f50 73 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61 6e  s N bytes of ran
10f60 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66  domness into buf
10f70 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  fer P..**.** The
10f80 20 66 69 72 73 74 20 74 69 6d 65 20 74 68 69 73   first time this
10f90 20 72 6f 75 74 69 6e 65 20 69 73 20 69 6e 76 6f   routine is invo
10fa0 6b 65 64 20 28 65 69 74 68 65 72 20 69 6e 74 65  ked (either inte
10fb0 72 6e 61 6c 6c 79 20 6f 72 20 62 79 0a 2a 2a 20  rnally or by.** 
10fc0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 29  the application)
10fd0 20 74 68 65 20 50 52 4e 47 20 69 73 20 73 65 65   the PRNG is see
10fe0 64 65 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d  ded using random
10ff0 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a  ness obtained.**
11000 20 66 72 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f   from the xRando
11010 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20  mness method of 
11020 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c  the default [sql
11030 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
11040 2e 0a 2a 2a 20 4f 6e 20 61 6c 6c 20 73 75 62 73  ..** On all subs
11050 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f  equent invocatio
11060 6e 73 2c 20 74 68 65 20 70 73 65 75 64 6f 2d 72  ns, the pseudo-r
11070 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e  andomness is gen
11080 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e  erated.** intern
11090 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f 75 74  ally and without
110a0 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74 68 65   recourse to the
110b0 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78   [sqlite3_vfs] x
110c0 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65  Randomness.** me
110d0 74 68 6f 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  thod..**.** INVA
110e0 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  RIANTS:.**.** {F
110f0 31 37 33 39 32 7d 20 54 68 65 20 5b 73 71 6c 69  17392} The [sqli
11100 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 4e  te3_randomness(N
11110 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77  ,P)] interface w
11120 72 69 74 65 73 20 4e 20 62 79 74 65 73 20 6f 66  rites N bytes of
11130 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 68 69 67  .**          hig
11140 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f  h-quality pseudo
11150 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f  -randomness into
11160 20 62 75 66 66 65 72 20 50 2e 0a 2a 2f 0a 76 6f   buffer P..*/.vo
11170 69 64 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f  id sqlite3_rando
11180 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69  mness(int N, voi
11190 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  d *P);../*.** CA
111a0 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d  PI3REF: Compile-
111b0 54 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69  Time Authorizati
111c0 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 20 7b 46 31  on Callbacks {F1
111d0 32 35 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73  2500}.**.** This
111e0 20 72 6f 75 74 69 6e 65 20 72 65 67 69 73 74 65   routine registe
111f0 72 73 20 61 20 61 75 74 68 6f 72 69 7a 65 72 20  rs a authorizer 
11200 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 61 20  callback with a 
11210 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64  particular.** [d
11220 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
11230 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20 69 6e  on], supplied in
11240 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
11250 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68  ent..** The auth
11260 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
11270 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51  is invoked as SQ
11280 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65  L statements are
11290 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a   being compiled.
112a0 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70  ** by [sqlite3_p
112b0 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73  repare()] or its
112c0 20 76 61 72 69 61 6e 74 73 20 5b 73 71 6c 69 74   variants [sqlit
112d0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
112e0 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  ,.** [sqlite3_pr
112f0 65 70 61 72 65 31 36 28 29 5d 20 61 6e 64 20 5b  epare16()] and [
11300 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
11310 36 5f 76 32 28 29 5d 2e 20 20 41 74 20 76 61 72  6_v2()].  At var
11320 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64  ious.** points d
11330 75 72 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c  uring the compil
11340 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61  ation process, a
11350 73 20 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67  s logic is being
11360 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70   created.** to p
11370 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61  erform various a
11380 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68  ctions, the auth
11390 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
113a0 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a  is invoked to.**
113b0 20 73 65 65 20 69 66 20 74 68 6f 73 65 20 61 63   see if those ac
113c0 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65  tions are allowe
113d0 64 2e 20 20 54 68 65 20 61 75 74 68 6f 72 69 7a  d.  The authoriz
113e0 65 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75  er callback shou
113f0 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ld.** return [SQ
11400 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f  LITE_OK] to allo
11410 77 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53  w the action, [S
11420 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f  QLITE_IGNORE] to
11430 20 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a   disallow the.**
11440 20 73 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e   specific action
11450 20 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53   but allow the S
11460 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  QL statement to 
11470 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a  continue to be.*
11480 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b  * compiled, or [
11490 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20  SQLITE_DENY] to 
114a0 63 61 75 73 65 20 74 68 65 20 65 6e 74 69 72 65  cause the entire
114b0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
114c0 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64  o be.** rejected
114d0 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20   with an error. 
114e0 20 20 49 66 20 74 68 65 20 61 75 74 68 6f 72 69    If the authori
114f0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  zer callback ret
11500 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75  urns.** any valu
11510 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  e other than [SQ
11520 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53  LITE_IGNORE], [S
11530 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53  QLITE_OK], or [S
11540 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74  QLITE_DENY].** t
11550 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hen [sqlite3_pre
11560 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71  pare_v2()] or eq
11570 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68  uivalent call th
11580 61 74 20 74 72 69 67 67 65 72 65 64 0a 2a 2a 20  at triggered.** 
11590 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 77  the authorizer w
115a0 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e  ill fail with an
115b0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a   error message..
115c0 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63  **.** When the c
115d0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
115e0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61  [SQLITE_OK], tha
115f0 74 20 6d 65 61 6e 73 20 74 68 65 20 6f 70 65 72  t means the oper
11600 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74  ation.** request
11610 65 64 20 69 73 20 6f 6b 2e 20 20 57 68 65 6e 20  ed is ok.  When 
11620 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
11630 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e  urns [SQLITE_DEN
11640 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  Y], the.** [sqli
11650 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
11660 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20  ] or equivalent 
11670 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65  call that trigge
11680 72 65 64 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f  red the.** autho
11690 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20  rizer will fail 
116a0 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65  with an error me
116b0 73 73 61 67 65 20 65 78 70 6c 61 69 6e 69 6e 67  ssage explaining
116c0 20 74 68 61 74 0a 2a 2a 20 61 63 63 65 73 73 20   that.** access 
116d0 69 73 20 64 65 6e 69 65 64 2e 20 20 49 66 20 74  is denied.  If t
116e0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f  he authorizer co
116f0 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 45  de is [SQLITE_RE
11700 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63  AD].** and the c
11710 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
11720 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20  [SQLITE_IGNORE] 
11730 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65  then the.** [pre
11740 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
11750 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f   statement is co
11760 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73 75 62  nstructed to sub
11770 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c  stitute.** a NUL
11780 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65  L value in place
11790 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f   of the table co
117a0 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20  lumn that would 
117b0 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61  have.** been rea
117c0 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  d if [SQLITE_OK]
117d0 20 68 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e   had been return
117e0 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45  ed.  The [SQLITE
117f0 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75  _IGNORE].** retu
11800 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  rn can be used t
11810 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72 75 73  o deny an untrus
11820 74 65 64 20 75 73 65 72 20 61 63 63 65 73 73 20  ted user access 
11830 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a  to individual.**
11840 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61   columns of a ta
11850 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  ble..**.** The f
11860 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
11870 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  o the authorizer
11880 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63   callback is a c
11890 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 74 68  opy of.** the th
118a0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
118b0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74   the sqlite3_set
118c0 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 20 69 6e  _authorizer() in
118d0 74 65 72 66 61 63 65 2e 0a 2a 2a 20 54 68 65 20  terface..** The 
118e0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
118f0 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
11900 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 0a   is an integer .
11910 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20  ** [SQLITE_COPY 
11920 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74  | action code] t
11930 68 61 74 20 73 70 65 63 69 66 69 65 73 20 74 68  hat specifies th
11940 65 20 70 61 72 74 69 63 75 6c 61 72 20 61 63 74  e particular act
11950 69 6f 6e 0a 2a 2a 20 74 6f 20 62 65 20 61 75 74  ion.** to be aut
11960 68 6f 72 69 7a 65 64 2e 20 54 68 65 20 74 68 69  horized. The thi
11970 72 64 20 74 68 72 6f 75 67 68 20 73 69 78 74 68  rd through sixth
11980 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 74  .** parameters t
11990 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61  o the callback a
119a0 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  re zero-terminat
119b0 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20  ed strings that 
119c0 63 6f 6e 74 61 69 6e 20 0a 2a 2a 20 61 64 64 69  contain .** addi
119d0 74 69 6f 6e 61 6c 20 64 65 74 61 69 6c 73 20 61  tional details a
119e0 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20  bout the action 
119f0 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64  to be authorized
11a00 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f  ..**.** An autho
11a10 72 69 7a 65 72 20 69 73 20 75 73 65 64 20 77 68  rizer is used wh
11a20 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  en [sqlite3_prep
11a30 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d  are | preparing]
11a40 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
11a50 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75  ts from an untru
11a60 73 74 65 64 0a 2a 2a 20 73 6f 75 72 63 65 2c 20  sted.** source, 
11a70 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20 74  to ensure that t
11a80 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
11a90 73 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20  s do not try to 
11aa0 61 63 63 65 73 73 20 64 61 74 61 0a 2a 2a 20 74  access data.** t
11ab0 68 61 74 20 74 68 65 79 20 61 72 65 20 6e 6f 74  hat they are not
11ac0 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c   allowed to see,
11ad0 20 6f 72 20 74 68 61 74 20 74 68 65 79 20 64 6f   or that they do
11ae0 20 6e 6f 74 20 74 72 79 20 74 6f 0a 2a 2a 20 65   not try to.** e
11af0 78 65 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 73  xecute malicious
11b00 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74   statements that
11b10 20 64 61 6d 61 67 65 20 74 68 65 20 64 61 74 61   damage the data
11b20 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78  base.  For.** ex
11b30 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63  ample, an applic
11b40 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20  ation may allow 
11b50 61 20 75 73 65 72 20 74 6f 20 65 6e 74 65 72 20  a user to enter 
11b60 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c  arbitrary.** SQL
11b70 20 71 75 65 72 69 65 73 20 66 6f 72 20 65 76 61   queries for eva
11b80 6c 75 61 74 69 6f 6e 20 62 79 20 61 20 64 61 74  luation by a dat
11b90 61 62 61 73 65 2e 20 20 42 75 74 20 74 68 65 20  abase.  But the 
11ba0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73  application does
11bb0 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 65  .** not want the
11bc0 20 75 73 65 72 20 74 6f 20 62 65 20 61 62 6c 65   user to be able
11bd0 20 74 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 61   to make arbitra
11be0 72 79 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  ry changes to th
11bf0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20  e.** database.  
11c00 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f  An authorizer co
11c10 75 6c 64 20 74 68 65 6e 20 62 65 20 70 75 74 20  uld then be put 
11c20 69 6e 20 70 6c 61 63 65 20 77 68 69 6c 65 20 74  in place while t
11c30 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72  he.** user-enter
11c40 65 64 20 53 51 4c 20 69 73 20 62 65 69 6e 67 20  ed SQL is being 
11c50 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
11c60 20 7c 20 70 72 65 70 61 72 65 64 5d 20 74 68 61   | prepared] tha
11c70 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65  t.** disallows e
11c80 76 65 72 79 74 68 69 6e 67 20 65 78 63 65 70 74  verything except
11c90 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
11ca0 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c  ents..**.** Appl
11cb0 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6e 65  ications that ne
11cc0 65 64 20 74 6f 20 70 72 6f 63 65 73 73 20 53 51  ed to process SQ
11cd0 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73 74 65 64  L from untrusted
11ce0 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68   sources.** migh
11cf0 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20  t also consider 
11d00 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f 75 72 63  lowering resourc
11d10 65 20 6c 69 6d 69 74 73 20 75 73 69 6e 67 20 5b  e limits using [
11d20 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d  sqlite3_limit()]
11d30 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67  .** and limiting
11d40 20 64 61 74 61 62 61 73 65 20 73 69 7a 65 20 75   database size u
11d50 73 69 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70 61  sing the [max_pa
11d60 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d  ge_count] [PRAGM
11d70 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f  A].** in additio
11d80 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e 20 61 75  n to using an au
11d90 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20  thorizer..**.** 
11da0 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 75  Only a single au
11db0 74 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 20  thorizer can be 
11dc0 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 61  in place on a da
11dd0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
11de0 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e 20  n.** at a time. 
11df0 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71   Each call to sq
11e00 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
11e10 69 7a 65 72 20 6f 76 65 72 72 69 64 65 73 20 74  izer overrides t
11e20 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 63  he.** previous c
11e30 61 6c 6c 2e 20 20 44 69 73 61 62 6c 65 20 74 68  all.  Disable th
11e40 65 20 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20  e authorizer by 
11e50 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c  installing a NUL
11e60 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54  L callback..** T
11e70 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73  he authorizer is
11e80 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66   disabled by def
11e90 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  ault..**.** Note
11ea0 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72   that the author
11eb0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
11ec0 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75   invoked only du
11ed0 72 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  ring .** [sqlite
11ee0 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20  3_prepare()] or 
11ef0 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41  its variants.  A
11f00 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20  uthorization is 
11f10 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64  not.** performed
11f20 20 64 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e   during statemen
11f30 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20  t evaluation in 
11f40 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
11f50 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
11f60 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 30  TS:.**.** {F1250
11f70 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
11f80 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 44  set_authorizer(D
11f90 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65  ,...)] interface
11fa0 20 72 65 67 69 73 74 65 72 73 20 61 0a 2a 2a 20   registers a.** 
11fb0 20 20 20 20 20 20 20 20 20 61 75 74 68 6f 72 69           authori
11fc0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 74  zer callback wit
11fd0 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  h database conne
11fe0 63 74 69 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b  ction D..**.** {
11ff0 46 31 32 35 30 32 7d 20 54 68 65 20 61 75 74 68  F12502} The auth
12000 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
12010 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51  is invoked as SQ
12020 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65  L statements are
12030 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 65 69  .**          bei
12040 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 0a 2a  ng compiled.**.*
12050 2a 20 7b 46 31 32 35 30 33 7d 20 49 66 20 74 68  * {F12503} If th
12060 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
12070 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 61 6e  lback returns an
12080 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68  y value other th
12090 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  an.**          [
120a0 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20  SQLITE_IGNORE], 
120b0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20  [SQLITE_OK], or 
120c0 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 68  [SQLITE_DENY] th
120d0 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  en.**          t
120e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  he [sqlite3_prep
120f0 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75  are_v2()] or equ
12100 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61  ivalent call tha
12110 74 20 63 61 75 73 65 64 0a 2a 2a 20 20 20 20 20  t caused.**     
12120 20 20 20 20 20 74 68 65 20 61 75 74 68 6f 72 69       the authori
12130 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20  zer callback to 
12140 72 75 6e 20 73 68 61 6c 6c 20 66 61 69 6c 20 77  run shall fail w
12150 69 74 68 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20  ith an.**       
12160 20 20 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52     [SQLITE_ERROR
12170 5d 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64  ] error code and
12180 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20   an appropriate 
12190 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a  error message..*
121a0 2a 0a 2a 2a 20 7b 46 31 32 35 30 34 7d 20 57 68  *.** {F12504} Wh
121b0 65 6e 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  en the authorize
121c0 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  r callback retur
121d0 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20  ns [SQLITE_OK], 
121e0 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a  the operation.**
121f0 20 20 20 20 20 20 20 20 20 20 64 65 73 63 72 69            descri
12200 62 65 64 20 69 73 20 63 6f 64 65 64 20 6e 6f 72  bed is coded nor
12210 6d 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  mally..**.** {F1
12220 32 35 30 35 7d 20 57 68 65 6e 20 74 68 65 20 61  2505} When the a
12230 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
12240 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ck returns [SQLI
12250 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a  TE_DENY], the.**
12260 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
12270 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
12280 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63   or equivalent c
12290 61 6c 6c 20 74 68 61 74 20 63 61 75 73 65 64 20  all that caused 
122a0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
122b0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
122c0 61 63 6b 20 74 6f 20 72 75 6e 20 73 68 61 6c 6c  ack to run shall
122d0 20 66 61 69 6c 0a 2a 2a 20 20 20 20 20 20 20 20   fail.**        
122e0 20 20 77 69 74 68 20 61 6e 20 5b 53 51 4c 49 54    with an [SQLIT
122f0 45 5f 45 52 52 4f 52 5d 20 65 72 72 6f 72 20 63  E_ERROR] error c
12300 6f 64 65 20 61 6e 64 20 61 6e 20 65 72 72 6f 72  ode and an error
12310 20 6d 65 73 73 61 67 65 0a 2a 2a 20 20 20 20 20   message.**     
12320 20 20 20 20 20 65 78 70 6c 61 69 6e 69 6e 67 20       explaining 
12330 74 68 61 74 20 61 63 63 65 73 73 20 69 73 20 64  that access is d
12340 65 6e 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  enied..**.** {F1
12350 32 35 30 36 7d 20 49 66 20 74 68 65 20 61 75 74  2506} If the aut
12360 68 6f 72 69 7a 65 72 20 63 6f 64 65 20 28 74 68  horizer code (th
12370 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
12380 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  to the authorize
12390 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61  r.**          ca
123a0 6c 6c 62 61 63 6b 29 20 69 73 20 5b 53 51 4c 49  llback) is [SQLI
123b0 54 45 5f 52 45 41 44 5d 20 61 6e 64 20 74 68 65  TE_READ] and the
123c0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
123d0 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20  back returns.** 
123e0 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45           [SQLITE
123f0 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68  _IGNORE] then th
12400 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
12410 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63  ment is construc
12420 74 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20  ted to.**       
12430 20 20 20 69 6e 73 65 72 74 20 61 20 4e 55 4c 4c     insert a NULL
12440 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20   value in place 
12450 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c  of the table col
12460 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68  umn that would h
12470 61 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ave.**          
12480 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51  been read if [SQ
12490 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65  LITE_OK] had bee
124a0 6e 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  n returned..**.*
124b0 2a 20 7b 46 31 32 35 30 37 7d 20 49 66 20 74 68  * {F12507} If th
124c0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 64  e authorizer cod
124d0 65 20 28 74 68 65 20 32 6e 64 20 70 61 72 61 6d  e (the 2nd param
124e0 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68  eter to the auth
124f0 6f 72 69 7a 65 72 0a 2a 2a 20 20 20 20 20 20 20  orizer.**       
12500 20 20 20 63 61 6c 6c 62 61 63 6b 29 20 69 73 20     callback) is 
12510 61 6e 79 74 68 69 6e 67 20 6f 74 68 65 72 20 74  anything other t
12520 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 45 41 44  han [SQLITE_READ
12530 5d 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20  ], then.**      
12540 20 20 20 20 61 20 72 65 74 75 72 6e 20 6f 66 20      a return of 
12550 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20  [SQLITE_IGNORE] 
12560 68 61 73 20 74 68 65 20 73 61 6d 65 20 65 66 66  has the same eff
12570 65 63 74 20 61 73 20 5b 53 51 4c 49 54 45 5f 44  ect as [SQLITE_D
12580 45 4e 59 5d 2e 20 0a 2a 2a 0a 2a 2a 20 7b 46 31  ENY]. .**.** {F1
12590 32 35 31 30 7d 20 54 68 65 20 66 69 72 73 74 20  2510} The first 
125a0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
125b0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
125c0 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f  back is a copy o
125d0 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  f.**          th
125e0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
125f0 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  r to the [sqlite
12600 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
12610 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ()] interface..*
12620 2a 0a 2a 2a 20 7b 46 31 32 35 31 31 7d 20 54 68  *.** {F12511} Th
12630 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
12640 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  er to the callba
12650 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ck is an integer
12660 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53   .**          [S
12670 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74  QLITE_COPY | act
12680 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73  ion code] that s
12690 70 65 63 69 66 69 65 73 20 74 68 65 20 70 61 72  pecifies the par
126a0 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 0a 2a  ticular action.*
126b0 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 62 65  *          to be
126c0 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a   authorized..**.
126d0 2a 2a 20 7b 46 31 32 35 31 32 7d 20 54 68 65 20  ** {F12512} The 
126e0 74 68 69 72 64 20 74 68 72 6f 75 67 68 20 73 69  third through si
126f0 78 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74  xth parameters t
12700 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61  o the callback a
12710 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a  re.**          z
12720 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73  ero-terminated s
12730 74 72 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74  trings that cont
12740 61 69 6e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  ain .**         
12750 20 61 64 64 69 74 69 6f 6e 61 6c 20 64 65 74 61   additional deta
12760 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61 63  ils about the ac
12770 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f  tion to be autho
12780 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  rized..**.** {F1
12790 32 35 32 30 7d 20 45 61 63 68 20 63 61 6c 6c 20  2520} Each call 
127a0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  to [sqlite3_set_
127b0 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 6f 76  authorizer()] ov
127c0 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 20  errides the.**  
127d0 20 20 20 20 20 20 20 20 61 6e 79 20 70 72 65 76          any prev
127e0 69 6f 75 73 6c 79 20 69 6e 73 74 61 6c 6c 65 64  iously installed
127f0 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a   authorizer..**.
12800 2a 2a 20 7b 46 31 32 35 32 31 7d 20 41 20 4e 55  ** {F12521} A NU
12810 4c 4c 20 61 75 74 68 6f 72 69 7a 65 72 20 6d 65  LL authorizer me
12820 61 6e 73 20 74 68 61 74 20 6e 6f 20 61 75 74 68  ans that no auth
12830 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 20 20 20  orization.**    
12840 20 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 20 69        callback i
12850 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a  s invoked..**.**
12860 20 7b 46 31 32 35 32 32 7d 20 54 68 65 20 64 65   {F12522} The de
12870 66 61 75 6c 74 20 61 75 74 68 6f 72 69 7a 65 72  fault authorizer
12880 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74   is NULL..*/.int
12890 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74   sqlite3_set_aut
128a0 68 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 74  horizer(.  sqlit
128b0 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75  e3*,.  int (*xAu
128c0 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  th)(void*,int,co
128d0 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20  nst char*,const 
128e0 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
128f0 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a  *,const char*),.
12900 20 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61 74    void *pUserDat
12910 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  a.);../*.** CAPI
12920 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72  3REF: Authorizer
12930 20 52 65 74 75 72 6e 20 43 6f 64 65 73 20 7b 46   Return Codes {F
12940 31 32 35 39 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  12590}.**.** The
12950 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
12960 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f  thorizer | autho
12970 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 66  rizer callback f
12980 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a  unction] must.**
12990 20 72 65 74 75 72 6e 20 65 69 74 68 65 72 20 5b   return either [
129a0 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e  SQLITE_OK] or on
129b0 65 20 6f 66 20 74 68 65 73 65 20 74 77 6f 20 63  e of these two c
129c0 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72 64 65  onstants in orde
129d0 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53  r.** to signal S
129e0 51 4c 69 74 65 20 77 68 65 74 68 65 72 20 6f 72  QLite whether or
129f0 20 6e 6f 74 20 74 68 65 20 61 63 74 69 6f 6e 20   not the action 
12a00 69 73 20 70 65 72 6d 69 74 74 65 64 2e 20 20 53  is permitted.  S
12a10 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ee the.** [sqlit
12a20 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
12a30 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 64  r | authorizer d
12a40 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f  ocumentation] fo
12a50 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  r additional.** 
12a60 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a  information..*/.
12a70 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
12a80 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f  ENY   1   /* Abo
12a90 72 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  rt the SQL state
12aa0 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72  ment with an err
12ab0 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  or */.#define SQ
12ac0 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20  LITE_IGNORE 2   
12ad0 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61  /* Don't allow a
12ae0 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74  ccess, but don't
12af0 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72   generate an err
12b00 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  or */../*.** CAP
12b10 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65  I3REF: Authorize
12b20 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 20 7b  r Action Codes {
12b30 46 31 32 35 35 30 7d 0a 2a 2a 0a 2a 2a 20 54 68  F12550}.**.** Th
12b40 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  e [sqlite3_set_a
12b50 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74  uthorizer()] int
12b60 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73  erface registers
12b70 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63   a callback func
12b80 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20  tion.** that is 
12b90 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f  invoked to autho
12ba0 72 69 7a 65 72 20 63 65 72 74 61 69 6e 20 53 51  rizer certain SQ
12bb0 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 63 74 69  L statement acti
12bc0 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63  ons.  The.** sec
12bd0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
12be0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
12bf0 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65   an integer code
12c00 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a   that specifies.
12c10 2a 2a 20 77 68 61 74 20 61 63 74 69 6f 6e 20 69  ** what action i
12c20 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72 69 7a  s being authoriz
12c30 65 64 2e 20 20 54 68 65 73 65 20 61 72 65 20 74  ed.  These are t
12c40 68 65 20 69 6e 74 65 67 65 72 20 61 63 74 69 6f  he integer actio
12c50 6e 20 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a 20  n codes that.** 
12c60 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
12c70 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65 20 70  allback may be p
12c80 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  assed..**.** The
12c90 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 76  se action code v
12ca0 61 6c 75 65 73 20 73 69 67 6e 69 66 79 20 77 68  alues signify wh
12cb0 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72 61  at kind of opera
12cc0 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 20 0a 2a  tion is to be .*
12cd0 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54  * authorized.  T
12ce0 68 65 20 33 72 64 20 61 6e 64 20 34 74 68 20 70  he 3rd and 4th p
12cf0 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65  arameters to the
12d00 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a   authorization.*
12d10 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  * callback funct
12d20 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 72 61  ion will be para
12d30 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64  meters or NULL d
12d40 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63  epending on whic
12d50 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f  h of these.** co
12d60 64 65 73 20 69 73 20 75 73 65 64 20 61 73 20 74  des is used as t
12d70 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
12d80 74 65 72 2e 20 20 54 68 65 20 35 74 68 20 70 61  ter.  The 5th pa
12d90 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a  rameter to the.*
12da0 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  * authorizer cal
12db0 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 61 6d  lback is the nam
12dc0 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  e of the databas
12dd0 65 20 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70  e ("main", "temp
12de0 22 2c 20 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20  ", .** etc.) if 
12df0 61 70 70 6c 69 63 61 62 6c 65 2e 20 20 54 68 65  applicable.  The
12e00 20 36 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   6th parameter t
12e10 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  o the authorizer
12e20 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20   callback.** is 
12e30 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
12e40 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67  inner-most trigg
12e50 65 72 20 6f 72 20 76 69 65 77 20 74 68 61 74 20  er or view that 
12e60 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
12e70 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73  or.** the access
12e80 20 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c   attempt or NULL
12e90 20 69 66 20 74 68 69 73 20 61 63 63 65 73 73 20   if this access 
12ea0 61 74 74 65 6d 70 74 20 69 73 20 64 69 72 65 63  attempt is direc
12eb0 74 6c 79 20 66 72 6f 6d 20 0a 2a 2a 20 74 6f 70  tly from .** top
12ec0 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e  -level SQL code.
12ed0 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
12ee0 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 35 31  S:.**.** {F12551
12ef0 7d 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72  } The second par
12f00 61 6d 65 74 65 72 20 74 6f 20 61 6e 20 0a 2a 2a  ameter to an .**
12f10 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
12f20 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
12f30 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63  r | authorizer c
12f40 61 6c 6c 62 61 63 6b 20 69 73 20 61 6c 77 61 79  allback is alway
12f50 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20  s an integer.** 
12f60 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45           [SQLITE
12f70 5f 43 4f 50 59 20 7c 20 61 75 74 68 6f 72 69 7a  _COPY | authoriz
12f80 65 72 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70  er code] that sp
12f90 65 63 69 66 69 65 73 20 77 68 61 74 20 61 63 74  ecifies what act
12fa0 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ion.**          
12fb0 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72 69  is being authori
12fc0 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35  zed..**.** {F125
12fd0 35 32 7d 20 54 68 65 20 33 72 64 20 61 6e 64 20  52} The 3rd and 
12fe0 34 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74  4th parameters t
12ff0 6f 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 20 20  o the .**       
13000 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f     [sqlite3_set_
13010 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74  authorizer | aut
13020 68 6f 72 69 7a 61 74 69 6f 6e 20 63 61 6c 6c 62  horization callb
13030 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 0a 2a 2a  ack function].**
13040 20 20 20 20 20 20 20 20 20 20 77 69 6c 6c 20 62            will b
13050 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20  e parameters or 
13060 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f  NULL depending o
13070 6e 20 77 68 69 63 68 20 0a 2a 2a 20 20 20 20 20  n which .**     
13080 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 43 4f 50       [SQLITE_COP
13090 59 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63  Y | authorizer c
130a0 6f 64 65 5d 20 69 73 20 75 73 65 64 20 61 73 20  ode] is used as 
130b0 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
130c0 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  eter..**.** {F12
130d0 35 35 33 7d 20 54 68 65 20 35 74 68 20 70 61 72  553} The 5th par
130e0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a  ameter to the.**
130f0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
13100 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
13110 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63  r | authorizer c
13120 61 6c 6c 62 61 63 6b 5d 20 69 73 20 74 68 65 20  allback] is the 
13130 6e 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  name.**         
13140 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
13150 20 28 65 78 61 6d 70 6c 65 3a 20 22 6d 61 69 6e   (example: "main
13160 22 2c 20 22 74 65 6d 70 22 2c 20 65 74 63 2e 29  ", "temp", etc.)
13170 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 0a   if applicable..
13180 2a 2a 0a 2a 2a 20 7b 46 31 32 35 35 34 7d 20 54  **.** {F12554} T
13190 68 65 20 36 74 68 20 70 61 72 61 6d 65 74 65 72  he 6th parameter
131a0 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   to the.**      
131b0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 65 74      [sqlite3_set
131c0 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75  _authorizer | au
131d0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
131e0 6b 5d 20 69 73 20 74 68 65 20 6e 61 6d 65 0a 2a  k] is the name.*
131f0 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 74 68  *          of th
13200 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69  e inner-most tri
13210 67 67 65 72 20 6f 72 20 76 69 65 77 20 74 68 61  gger or view tha
13220 74 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65  t is responsible
13230 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20   for.**         
13240 20 74 68 65 20 61 63 63 65 73 73 20 61 74 74 65   the access atte
13250 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74  mpt or NULL if t
13260 68 69 73 20 61 63 63 65 73 73 20 61 74 74 65 6d  his access attem
13270 70 74 20 69 73 20 64 69 72 65 63 74 6c 79 20 66  pt is directly f
13280 72 6f 6d 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  rom .**         
13290 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63   top-level SQL c
132a0 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a  ode..*/./*******
132b0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
132c0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
132d0 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a  **** 3rd *******
132e0 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a  ***** 4th ******
132f0 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  *****/.#define S
13300 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e 44  QLITE_CREATE_IND
13310 45 58 20 20 20 20 20 20 20 20 20 20 31 20 20 20  EX          1   
13320 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
13330 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
13340 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
13350 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42 4c  LITE_CREATE_TABL
13360 45 20 20 20 20 20 20 20 20 20 20 32 20 20 20 2f  E          2   /
13370 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
13380 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
13390 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
133a0 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
133b0 49 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f 2a  INDEX     3   /*
133c0 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
133d0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
133e0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
133f0 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54  TE_CREATE_TEMP_T
13400 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a 20  ABLE     4   /* 
13410 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
13420 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
13430 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
13440 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 52  E_CREATE_TEMP_TR
13450 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20 54  IGGER   5   /* T
13460 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
13470 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
13480 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
13490 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 45  _CREATE_TEMP_VIE
134a0 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56 69  W      6   /* Vi
134b0 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
134c0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
134d0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
134e0 43 52 45 41 54 45 5f 54 52 49 47 47 45 52 20 20  CREATE_TRIGGER  
134f0 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72 69        7   /* Tri
13500 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
13510 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
13520 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
13530 52 45 41 54 45 5f 56 49 45 57 20 20 20 20 20 20  REATE_VIEW      
13540 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65 77       8   /* View
13550 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
13560 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
13570 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
13580 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20  LETE            
13590 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 65      9   /* Table
135a0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
135b0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
135c0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
135d0 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20  P_INDEX         
135e0 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 20    10   /* Index 
135f0 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
13600 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
13610 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
13620 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  _TABLE          
13630 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   11   /* Table N
13640 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
13650 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
13660 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
13670 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 20  TEMP_INDEX      
13680 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61  12   /* Index Na
13690 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
136a0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
136b0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
136c0 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20 31  EMP_TABLE      1
136d0 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  3   /* Table Nam
136e0 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
136f0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
13700 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
13710 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20 31 34  MP_TRIGGER    14
13720 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
13730 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
13740 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
13750 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d   SQLITE_DROP_TEM
13760 50 5f 56 49 45 57 20 20 20 20 20 20 20 31 35 20  P_VIEW       15 
13770 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
13780 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
13790 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
137a0 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 47  SQLITE_DROP_TRIG
137b0 47 45 52 20 20 20 20 20 20 20 20 20 31 36 20 20  GER         16  
137c0 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
137d0 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
137e0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
137f0 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 20  QLITE_DROP_VIEW 
13800 20 20 20 20 20 20 20 20 20 20 20 31 37 20 20 20             17   
13810 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
13820 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
13830 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
13840 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20 20  LITE_INSERT     
13850 20 20 20 20 20 20 20 20 20 20 31 38 20 20 20 2f            18   /
13860 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
13870 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
13880 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
13890 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20 20  ITE_PRAGMA      
138a0 20 20 20 20 20 20 20 20 20 31 39 20 20 20 2f 2a           19   /*
138b0 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 20   Pragma Name    
138c0 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c   1st arg or NULL
138d0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
138e0 54 45 5f 52 45 41 44 20 20 20 20 20 20 20 20 20  TE_READ         
138f0 20 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20          20   /* 
13900 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
13910 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20  Column Name     
13920 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
13930 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20  E_SELECT        
13940 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4e         21   /* N
13950 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e  ULL            N
13960 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
13970 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
13980 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 20  _TRANSACTION    
13990 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4e 55        22   /* NU
139a0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e 55  LL            NU
139b0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
139c0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
139d0 55 50 44 41 54 45 20 20 20 20 20 20 20 20 20 20  UPDATE          
139e0 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61 62       23   /* Tab
139f0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c  le Name      Col
13a00 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  umn Name     */.
13a10 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
13a20 54 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20  TTACH           
13a30 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 65      24   /* File
13a40 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c 4c  name        NULL
13a50 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
13a60 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
13a70 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20  TACH            
13a80 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61 62     25   /* Datab
13a90 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20  ase Name   NULL 
13aa0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
13ab0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54  efine SQLITE_ALT
13ac0 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20  ER_TABLE        
13ad0 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62 61    26   /* Databa
13ae0 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 20  se Name   Table 
13af0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
13b00 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 4e  fine SQLITE_REIN
13b10 44 45 58 20 20 20 20 20 20 20 20 20 20 20 20 20  DEX             
13b20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e   27   /* Index N
13b30 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
13b40 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
13b50 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59  ine SQLITE_ANALY
13b60 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ZE              
13b70 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  28   /* Table Na
13b80 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
13b90 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
13ba0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
13bb0 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 32  _VTABLE        2
13bc0 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  9   /* Table Nam
13bd0 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61  e      Module Na
13be0 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
13bf0 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54  e SQLITE_DROP_VT
13c00 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 33 30  ABLE          30
13c10 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
13c20 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d        Module Nam
13c30 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
13c40 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e   SQLITE_FUNCTION
13c50 20 20 20 20 20 20 20 20 20 20 20 20 20 33 31 20               31 
13c60 20 20 2f 2a 20 46 75 6e 63 74 69 6f 6e 20 4e 61    /* Function Na
13c70 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20  me   NULL       
13c80 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
13c90 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20  SQLITE_COPY     
13ca0 20 20 20 20 20 20 20 20 20 20 20 20 20 30 20 20               0  
13cb0 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73   /* No longer us
13cc0 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ed */../*.** CAP
13cd0 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41  I3REF: Tracing A
13ce0 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e  nd Profiling Fun
13cf0 63 74 69 6f 6e 73 20 7b 46 31 32 32 38 30 7d 0a  ctions {F12280}.
13d00 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
13d10 69 6e 65 73 20 72 65 67 69 73 74 65 72 20 63 61  ines register ca
13d20 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73  llback functions
13d30 20 74 68 61 74 20 63 61 6e 20 62 65 20 75 73 65   that can be use
13d40 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67  d for.** tracing
13d50 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 74   and profiling t
13d60 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20  he execution of 
13d70 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  SQL statements..
13d80 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61  **.** The callba
13d90 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69  ck function regi
13da0 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65  stered by sqlite
13db0 33 5f 74 72 61 63 65 28 29 20 69 73 20 69 6e 76  3_trace() is inv
13dc0 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f  oked at.** vario
13dd0 75 73 20 74 69 6d 65 73 20 77 68 65 6e 20 61 6e  us times when an
13de0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69   SQL statement i
13df0 73 20 62 65 69 6e 67 20 72 75 6e 20 62 79 20 5b  s being run by [
13e00 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
13e10 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b  .** The callback
13e20 20 72 65 74 75 72 6e 73 20 61 20 55 54 46 2d 38   returns a UTF-8
13e30 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68   rendering of th
13e40 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
13e50 74 65 78 74 0a 2a 2a 20 61 73 20 74 68 65 20 73  text.** as the s
13e60 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20 62  tatement first b
13e70 65 67 69 6e 73 20 65 78 65 63 75 74 69 6e 67 2e  egins executing.
13e80 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 63 61 6c    Additional cal
13e90 6c 62 61 63 6b 73 20 6f 63 63 75 72 0a 2a 2a 20  lbacks occur.** 
13ea0 61 73 20 65 61 63 68 20 74 72 69 67 67 65 72 73  as each triggers
13eb0 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74  ubprogram is ent
13ec0 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62  ered.  The callb
13ed0 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72  acks for trigger
13ee0 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55  s.** contain a U
13ef0 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74  TF-8 SQL comment
13f00 20 74 68 61 74 20 69 64 65 6e 74 69 66 69 65 73   that identifies
13f10 20 74 68 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a   the trigger..**
13f20 20 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63   .** The callbac
13f30 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73  k function regis
13f40 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33  tered by sqlite3
13f50 5f 70 72 6f 66 69 6c 65 28 29 20 69 73 20 69 6e  _profile() is in
13f60 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63 68  voked.** as each
13f70 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66   SQL statement f
13f80 69 6e 69 73 68 65 73 2e 20 20 54 68 65 20 70 72  inishes.  The pr
13f90 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63  ofile callback c
13fa0 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f  ontains.** the o
13fb0 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e  riginal statemen
13fc0 74 20 74 65 78 74 20 61 6e 64 20 61 6e 20 65 73  t text and an es
13fd0 74 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63  timate of wall-c
13fe0 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20  lock time.** of 
13ff0 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 74  how long that st
14000 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20  atement took to 
14010 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  run..**.** The s
14020 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29  qlite3_profile()
14030 20 41 50 49 20 69 73 20 63 75 72 72 65 6e 74 6c   API is currentl
14040 79 20 63 6f 6e 73 69 64 65 72 65 64 20 65 78 70  y considered exp
14050 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 0a 2a 2a  erimental and.**
14060 20 69 73 20 73 75 62 6a 65 63 74 20 74 6f 20 63   is subject to c
14070 68 61 6e 67 65 20 6f 72 20 72 65 6d 6f 76 61 6c  hange or removal
14080 20 69 6e 20 61 20 66 75 74 75 72 65 20 72 65 6c   in a future rel
14090 65 61 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ease..**.** The 
140a0 74 72 69 67 67 65 72 20 72 65 70 6f 72 74 69 6e  trigger reportin
140b0 67 20 66 65 61 74 75 72 65 20 6f 66 20 74 68 65  g feature of the
140c0 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 20   trace callback 
140d0 69 73 20 63 6f 6e 73 69 64 65 72 65 64 0a 2a 2a  is considered.**
140e0 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e   experimental an
140f0 64 20 69 73 20 73 75 62 6a 65 63 74 20 74 6f 20  d is subject to 
14100 63 68 61 6e 67 65 20 6f 72 20 72 65 6d 6f 76 61  change or remova
14110 6c 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  l in future rele
14120 61 73 65 73 2e 0a 2a 2a 20 46 75 74 75 72 65 20  ases..** Future 
14130 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
14140 74 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 61 64  te might also ad
14150 64 20 6e 65 77 20 74 72 61 63 65 20 63 61 6c 6c  d new trace call
14160 62 61 63 6b 20 0a 2a 2a 20 69 6e 76 6f 63 61 74  back .** invocat
14170 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  ions..**.** INVA
14180 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  RIANTS:.**.** {F
14190 31 32 32 38 31 7d 20 54 68 65 20 63 61 6c 6c 62  12281} The callb
141a0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67  ack function reg
141b0 69 73 74 65 72 65 64 20 62 79 20 5b 73 71 6c 69  istered by [sqli
141c0 74 65 33 5f 74 72 61 63 65 28 29 5d 20 69 73 0a  te3_trace()] is.
141d0 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68 65 6e  **          when
141e0 65 76 65 72 20 61 6e 20 53 51 4c 20 73 74 61 74  ever an SQL stat
141f0 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65 67 69  ement first begi
14200 6e 73 20 74 6f 20 65 78 65 63 75 74 65 20 61 6e  ns to execute an
14210 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68  d.**          wh
14220 65 6e 65 76 65 72 20 61 20 74 72 69 67 67 65 72  enever a trigger
14230 20 73 75 62 70 72 6f 67 72 61 6d 20 66 69 72 73   subprogram firs
14240 74 20 62 65 67 69 6e 73 20 74 6f 20 72 75 6e 2e  t begins to run.
14250 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 38 32 7d 20  .**.** {F12282} 
14260 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71  Each call to [sq
14270 6c 69 74 65 33 5f 74 72 61 63 65 28 29 5d 20 6f  lite3_trace()] o
14280 76 65 72 72 69 64 65 73 20 74 68 65 20 70 72 65  verrides the pre
14290 76 69 6f 75 73 6c 79 0a 2a 2a 20 20 20 20 20 20  viously.**      
142a0 20 20 20 20 72 65 67 69 73 74 65 72 65 64 20 74      registered t
142b0 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a  race callback..*
142c0 2a 0a 2a 2a 20 7b 46 31 32 32 38 33 7d 20 41 20  *.** {F12283} A 
142d0 4e 55 4c 4c 20 74 72 61 63 65 20 63 61 6c 6c 62  NULL trace callb
142e0 61 63 6b 20 64 69 73 61 62 6c 65 73 20 74 72 61  ack disables tra
142f0 63 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  cing..**.** {F12
14300 32 38 34 7d 20 54 68 65 20 66 69 72 73 74 20 61  284} The first a
14310 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 74  rgument to the t
14320 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 20 69 73  race callback is
14330 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 20 20   a copy of.**   
14340 20 20 20 20 20 20 20 74 68 65 20 70 6f 69 6e 74         the point
14350 65 72 20 77 68 69 63 68 20 77 61 73 20 74 68 65  er which was the
14360 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f   3rd argument to
14370 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28   [sqlite3_trace(
14380 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 38  )]..**.** {F1228
14390 35 7d 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72  5} The second ar
143a0 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 74 72  gument to the tr
143b0 61 63 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ace callback is 
143c0 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65  a.**          ze
143d0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
143e0 46 38 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69  F8 string contai
143f0 6e 69 6e 67 20 74 68 65 20 6f 72 69 67 69 6e 61  ning the origina
14400 6c 20 74 65 78 74 0a 2a 2a 20 20 20 20 20 20 20  l text.**       
14410 20 20 20 6f 66 20 74 68 65 20 53 51 4c 20 73 74     of the SQL st
14420 61 74 65 6d 65 6e 74 20 61 73 20 69 74 20 77 61  atement as it wa
14430 73 20 70 61 73 73 65 64 20 69 6e 74 6f 20 5b 73  s passed into [s
14440 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
14450 32 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  2()].**         
14460 20 6f 72 20 74 68 65 20 65 71 75 69 76 61 6c 65   or the equivale
14470 6e 74 2c 20 6f 72 20 61 6e 20 53 51 4c 20 63 6f  nt, or an SQL co
14480 6d 6d 65 6e 74 20 69 6e 64 69 63 61 74 69 6e 67  mment indicating
14490 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a   the beginning.*
144a0 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 61 20  *          of a 
144b0 74 72 69 67 67 65 72 20 73 75 62 70 72 6f 67 72  trigger subprogr
144c0 61 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 38  am..**.** {F1228
144d0 37 7d 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  7} The callback 
144e0 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65  function registe
144f0 72 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  red by [sqlite3_
14500 70 72 6f 66 69 6c 65 28 29 5d 20 69 73 20 69 6e  profile()] is in
14510 76 6f 6b 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  voked.**        
14520 20 20 61 73 20 65 61 63 68 20 53 51 4c 20 73 74    as each SQL st
14530 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73  atement finishes
14540 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 38 38 7d  ..**.** {F12288}
14550 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   The first param
14560 65 74 65 72 20 74 6f 20 74 68 65 20 70 72 6f 66  eter to the prof
14570 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ile callback is 
14580 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 20 20 20  a copy of.**    
14590 20 20 20 20 20 20 74 68 65 20 33 72 64 20 70 61        the 3rd pa
145a0 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
145b0 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 5d 2e 0a  te3_profile()]..
145c0 2a 2a 0a 2a 2a 20 7b 46 31 32 32 38 39 7d 20 54  **.** {F12289} T
145d0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
145e0 74 65 72 20 74 6f 20 74 68 65 20 70 72 6f 66 69  ter to the profi
145f0 6c 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  le callback is a
14600 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72  .**          zer
14610 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
14620 2d 38 20 73 74 72 69 6e 67 20 74 68 61 74 20 63  -8 string that c
14630 6f 6e 74 61 69 6e 73 20 74 68 65 20 63 6f 6d 70  ontains the comp
14640 6c 65 74 65 20 74 65 78 74 20 6f 66 0a 2a 2a 20  lete text of.** 
14650 20 20 20 20 20 20 20 20 20 74 68 65 20 53 51 4c           the SQL
14660 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20 69 74   statement as it
14670 20 77 61 73 20 70 72 6f 63 65 73 73 65 64 20 62   was processed b
14680 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  y [sqlite3_prepa
14690 72 65 5f 76 32 28 29 5d 0a 2a 2a 20 20 20 20 20  re_v2()].**     
146a0 20 20 20 20 20 6f 72 20 74 68 65 20 65 71 75 69       or the equi
146b0 76 61 6c 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46  valent..**.** {F
146c0 31 32 32 39 30 7d 20 54 68 65 20 74 68 69 72 64  12290} The third
146d0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
146e0 65 20 70 72 6f 66 69 6c 65 20 20 63 61 6c 6c 62  e profile  callb
146f0 61 63 6b 20 69 73 20 61 6e 20 65 73 74 69 6d 61  ack is an estima
14700 74 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  te.**          o
14710 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  f the number of 
14720 6e 61 6e 6f 73 65 63 6f 6e 64 73 20 6f 66 20 77  nanoseconds of w
14730 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 20 72  all-clock time r
14740 65 71 75 69 72 65 64 20 74 6f 0a 2a 2a 20 20 20  equired to.**   
14750 20 20 20 20 20 20 20 72 75 6e 20 74 68 65 20 53         run the S
14760 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 72 6f  QL statement fro
14770 6d 20 73 74 61 72 74 20 74 6f 20 66 69 6e 69 73  m start to finis
14780 68 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  h..*/.void *sqli
14790 74 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74 65  te3_trace(sqlite
147a0 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61 63 65  3*, void(*xTrace
147b0 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68  )(void*,const ch
147c0 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 76 6f  ar*), void*);.vo
147d0 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66  id *sqlite3_prof
147e0 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20  ile(sqlite3*,.  
147f0 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65 29   void(*xProfile)
14800 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61  (void*,const cha
14810 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  r*,sqlite3_uint6
14820 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  4), void*);../*.
14830 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75 65  ** CAPI3REF: Que
14840 72 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c 6c  ry Progress Call
14850 62 61 63 6b 73 20 7b 46 31 32 39 31 30 7d 0a 2a  backs {F12910}.*
14860 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
14870 65 20 63 6f 6e 66 69 67 75 72 65 73 20 61 20 63  e configures a c
14880 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
14890 20 2d 20 74 68 65 0a 2a 2a 20 70 72 6f 67 72 65   - the.** progre
148a0 73 73 20 63 61 6c 6c 62 61 63 6b 20 2d 20 74 68  ss callback - th
148b0 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 70 65  at is invoked pe
148c0 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e  riodically durin
148d0 67 20 6c 6f 6e 67 0a 2a 2a 20 72 75 6e 6e 69 6e  g long.** runnin
148e0 67 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  g calls to [sqli
148f0 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71  te3_exec()], [sq
14900 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 61 6e  lite3_step()] an
14910 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65  d.** [sqlite3_ge
14920 74 5f 74 61 62 6c 65 28 29 5d 2e 20 20 20 41 6e  t_table()].   An
14930 20 65 78 61 6d 70 6c 65 20 75 73 65 20 66 6f 72   example use for
14940 20 74 68 69 73 20 0a 2a 2a 20 69 6e 74 65 72 66   this .** interf
14950 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70 20 61  ace is to keep a
14960 20 47 55 49 20 75 70 64 61 74 65 64 20 64 75 72   GUI updated dur
14970 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75 65 72  ing a large quer
14980 79 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  y..**.** If the 
14990 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63  progress callbac
149a0 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  k returns non-ze
149b0 72 6f 2c 20 74 68 65 20 6f 70 65 72 74 69 6f 6e  ro, the opertion
149c0 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74   is.** interrupt
149d0 65 64 2e 20 20 54 68 69 73 20 66 65 61 74 75 72  ed.  This featur
149e0 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
149f0 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20   implement a.** 
14a00 22 43 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20  "Cancel" button 
14a10 6f 6e 20 61 20 47 55 49 20 64 69 61 6c 6f 67 20  on a GUI dialog 
14a20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  box..**.** INVAR
14a30 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31  IANTS:.**.** {F1
14a40 32 39 31 31 7d 20 54 68 65 20 63 61 6c 6c 62 61  2911} The callba
14a50 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69  ck function regi
14a60 73 74 65 72 65 64 20 62 79 20 5b 73 71 6c 69 74  stered by [sqlit
14a70 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64  e3_progress_hand
14a80 6c 65 72 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ler()].**       
14a90 20 20 20 69 73 20 69 6e 76 6f 6b 65 64 20 70 65     is invoked pe
14aa0 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e  riodically durin
14ab0 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63  g long running c
14ac0 61 6c 6c 73 20 74 6f 0a 2a 2a 20 20 20 20 20 20  alls to.**      
14ad0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65      [sqlite3_ste
14ae0 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  p()]..**.** {F12
14af0 39 31 32 7d 20 54 68 65 20 70 72 6f 67 72 65 73  912} The progres
14b00 73 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  s callback is in
14b10 76 6f 6b 65 64 20 6f 6e 63 65 20 66 6f 72 20 65  voked once for e
14b20 76 65 72 79 20 4e 20 76 69 72 74 75 61 6c 0a 2a  very N virtual.*
14b30 2a 20 20 20 20 20 20 20 20 20 20 6d 61 63 68 69  *          machi
14b40 6e 65 20 6f 70 63 6f 64 65 73 2c 20 77 68 65 72  ne opcodes, wher
14b50 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e  e N is the secon
14b60 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 0a 2a  d argument to .*
14b70 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b  *          the [
14b80 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73  sqlite3_progress
14b90 5f 68 61 6e 64 6c 65 72 28 29 5d 20 63 61 6c 6c  _handler()] call
14ba0 20 74 68 61 74 20 72 65 67 69 73 74 65 72 65 64   that registered
14bb0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
14bc0 20 63 61 6c 6c 62 61 63 6b 2e 20 20 3c 74 6f 64   callback.  <tod
14bd0 6f 3e 57 68 61 74 20 69 66 20 4e 20 69 73 20 6c  o>What if N is l
14be0 65 73 73 20 74 68 61 6e 20 31 3f 3c 2f 74 6f 64  ess than 1?</tod
14bf0 6f 3e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 31 33  o>.**.** {F12913
14c00 7d 20 54 68 65 20 70 72 6f 67 72 65 73 73 20 63  } The progress c
14c10 61 6c 6c 62 61 63 6b 20 69 74 73 65 6c 66 20 69  allback itself i
14c20 73 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20  s identified by 
14c30 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 20 20 20  the third.**    
14c40 20 20 20 20 20 20 61 72 67 75 6d 65 6e 74 20 74        argument t
14c50 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 67 72  o [sqlite3_progr
14c60 65 73 73 5f 68 61 6e 64 6c 65 72 28 29 5d 2e 0a  ess_handler()]..
14c70 2a 2a 0a 2a 2a 20 7b 46 31 32 39 31 34 7d 20 54  **.** {F12914} T
14c80 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
14c90 6e 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 67  nt [sqlite3_prog
14ca0 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 29 5d 20  ress_handler()] 
14cb0 69 73 20 61 0a 2a 2a 2a 20 20 20 20 20 20 20 20  is a.***        
14cc0 20 76 6f 69 64 20 70 6f 69 6e 74 65 72 20 70 61   void pointer pa
14cd0 73 73 65 64 20 74 6f 20 74 68 65 20 70 72 6f 67  ssed to the prog
14ce0 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  ress callback.**
14cf0 20 20 20 20 20 20 20 20 20 20 66 75 6e 63 74 69            functi
14d00 6f 6e 20 65 61 63 68 20 74 69 6d 65 20 69 74 20  on each time it 
14d10 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a  is invoked..**.*
14d20 2a 20 7b 46 31 32 39 31 35 7d 20 49 66 20 61 20  * {F12915} If a 
14d30 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
14d40 5f 73 74 65 70 28 29 5d 20 72 65 73 75 6c 74 73  _step()] results
14d50 20 69 6e 20 66 65 77 65 72 20 74 68 61 6e 0a 2a   in fewer than.*
14d60 2a 20 20 20 20 20 20 20 20 20 20 4e 20 6f 70 63  *          N opc
14d70 6f 64 65 73 20 62 65 69 6e 67 20 65 78 65 63 75  odes being execu
14d80 74 65 64 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ted,.**         
14d90 20 74 68 65 6e 20 74 68 65 20 70 72 6f 67 72 65   then the progre
14da0 73 73 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e  ss callback is n
14db0 65 76 65 72 20 69 6e 76 6f 6b 65 64 2e 20 7b 45  ever invoked. {E
14dc0 4e 44 7d 0a 2a 2a 20 0a 2a 2a 20 7b 46 31 32 39  ND}.** .** {F129
14dd0 31 36 7d 20 45 76 65 72 79 20 63 61 6c 6c 20 74  16} Every call t
14de0 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 67 72  o [sqlite3_progr
14df0 65 73 73 5f 68 61 6e 64 6c 65 72 28 29 5d 0a 2a  ess_handler()].*
14e00 2a 20 20 20 20 20 20 20 20 20 20 6f 76 65 72 77  *          overw
14e10 72 69 74 65 73 20 61 6e 79 20 70 72 65 76 69 6f  rites any previo
14e20 75 73 6c 79 20 72 65 67 69 73 74 65 72 65 20 70  usly registere p
14e30 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e  rogress handler.
14e40 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 31 37 7d 20  .**.** {F12917} 
14e50 49 66 20 74 68 65 20 70 72 6f 67 72 65 73 73 20  If the progress 
14e60 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b  handler callback
14e70 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 6e 6f   is NULL then no
14e80 20 70 72 6f 67 72 65 73 73 0a 2a 2a 20 20 20 20   progress.**    
14e90 20 20 20 20 20 20 68 61 6e 64 6c 65 72 20 69 73        handler is
14ea0 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20   invoked..**.** 
14eb0 7b 46 31 32 39 31 38 7d 20 49 66 20 74 68 65 20  {F12918} If the 
14ec0 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63  progress callbac
14ed0 6b 20 72 65 74 75 72 6e 73 20 61 20 72 65 73 75  k returns a resu
14ee0 6c 74 20 6f 74 68 65 72 20 74 68 61 6e 20 30 2c  lt other than 0,
14ef0 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20   then.**        
14f00 20 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69    the behavior i
14f10 73 20 61 20 69 66 20 5b 73 71 6c 69 74 65 33 5f  s a if [sqlite3_
14f20 69 6e 74 65 72 72 75 70 74 28 29 5d 20 68 61 64  interrupt()] had
14f30 20 62 65 65 6e 20 63 61 6c 6c 65 64 2e 0a 2a 2f   been called..*/
14f40 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 70 72  .void sqlite3_pr
14f50 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 73  ogress_handler(s
14f60 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e  qlite3*, int, in
14f70 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69  t(*)(void*), voi
14f80 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
14f90 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20  3REF: Opening A 
14fa0 4e 65 77 20 44 61 74 61 62 61 73 65 20 43 6f 6e  New Database Con
14fb0 6e 65 63 74 69 6f 6e 20 7b 46 31 32 37 30 30 7d  nection {F12700}
14fc0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
14fd0 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53 51  tines open an SQ
14fe0 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 66 69  Lite database fi
14ff0 6c 65 20 77 68 6f 73 65 20 6e 61 6d 65 0a 2a 2a  le whose name.**
15000 20 69 73 20 67 69 76 65 6e 20 62 79 20 74 68 65   is given by the
15010 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65   filename argume
15020 6e 74 2e 0a 2a 2a 20 54 68 65 20 66 69 6c 65 6e  nt..** The filen
15030 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ame argument is 
15040 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55  interpreted as U
15050 54 46 2d 38 0a 2a 2a 20 66 6f 72 20 5b 73 71 6c  TF-8.** for [sql
15060 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 61 6e 64  ite3_open()] and
15070 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
15080 32 28 29 5d 20 61 6e 64 20 61 73 20 55 54 46 2d  2()] and as UTF-
15090 31 36 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74  16.** in the nat
150a0 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 66  ive byte order f
150b0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  or [sqlite3_open
150c0 31 36 28 29 5d 2e 0a 2a 2a 20 41 6e 20 5b 73 71  16()]..** An [sq
150d0 6c 69 74 65 33 2a 5d 20 68 61 6e 64 6c 65 20 69  lite3*] handle i
150e0 73 20 75 73 75 61 6c 6c 79 20 72 65 74 75 72 6e  s usually return
150f0 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 65 76 65  ed in *ppDb, eve
15100 6e 0a 2a 2a 20 69 66 20 61 6e 20 65 72 72 6f 72  n.** if an error
15110 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e   occurs.  The on
15120 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20  ly exception is 
15130 69 66 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61  if SQLite is una
15140 62 6c 65 0a 2a 2a 20 74 6f 20 61 6c 6c 6f 63 61  ble.** to alloca
15150 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c  te memory to hol
15160 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20  d the [sqlite3] 
15170 6f 62 6a 65 63 74 2c 20 61 20 4e 55 4c 4c 20 77  object, a NULL w
15180 69 6c 6c 0a 2a 2a 20 62 65 20 77 72 69 74 74 65  ill.** be writte
15190 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73  n into *ppDb ins
151a0 74 65 61 64 20 6f 66 20 61 20 70 6f 69 6e 74 65  tead of a pointe
151b0 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  r to the [sqlite
151c0 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 49 66  3] object..** If
151d0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
151e0 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20   opened (and/or 
151f0 63 72 65 61 74 65 64 29 0a 2a 2a 20 73 75 63 63  created).** succ
15200 65 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e 20 5b  essfully, then [
15210 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65  SQLITE_OK] is re
15220 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69  turned.  Otherwi
15230 73 65 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 63  se an.** error c
15240 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ode is returned.
15250 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65    The.** [sqlite
15260 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b  3_errmsg()] or [
15270 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
15280 28 29 5d 20 20 72 6f 75 74 69 6e 65 73 20 63 61  ()]  routines ca
15290 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74  n be used to obt
152a0 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73  ain.** an Englis
152b0 68 20 6c 61 6e 67 75 61 67 65 20 64 65 73 63 72  h language descr
152c0 69 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 65 72  iption of the er
152d0 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64  ror..**.** The d
152e0 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20  efault encoding 
152f0 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 65  for the database
15300 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38 20 69   will be UTF-8 i
15310 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70  f.** [sqlite3_op
15320 65 6e 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  en()] or [sqlite
15330 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 73 20  3_open_v2()] is 
15340 63 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20 55 54  called and.** UT
15350 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69  F-16 in the nati
15360 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 69 66  ve byte order if
15370 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
15380 28 29 5d 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a  ()] is used..**.
15390 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f  ** Whether or no
153a0 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  t an error occur
153b0 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70 65  s when it is ope
153c0 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a  ned, resources.*
153d0 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  * associated wit
153e0 68 20 74 68 65 20 5b 73 71 6c 69 74 65 33 2a 5d  h the [sqlite3*]
153f0 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62   handle should b
15400 65 20 72 65 6c 65 61 73 65 64 20 62 79 20 70 61  e released by pa
15410 73 73 69 6e 67 20 69 74 0a 2a 2a 20 74 6f 20 5b  ssing it.** to [
15420 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d  sqlite3_close()]
15430 20 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c   when it is no l
15440 6f 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e 0a  onger required..
15450 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  **.** The [sqlit
15460 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e  e3_open_v2()] in
15470 74 65 72 66 61 63 65 20 77 6f 72 6b 73 20 6c 69  terface works li
15480 6b 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ke [sqlite3_open
15490 28 29 5d 20 0a 2a 2a 20 65 78 63 65 70 74 20 74  ()] .** except t
154a0 68 61 74 20 69 74 20 61 63 63 63 65 70 74 73 20  hat it acccepts 
154b0 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 70  two additional p
154c0 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20 61 64  arameters for ad
154d0 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c  ditional control
154e0 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e 65 77  .** over the new
154f0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
15500 74 69 6f 6e 2e 20 20 54 68 65 20 66 6c 61 67 73  tion.  The flags
15510 20 70 61 72 61 6d 65 74 65 72 20 63 61 6e 20 62   parameter can b
15520 65 0a 2a 2a 20 6f 6e 65 20 6f 66 3a 0a 2a 2a 0a  e.** one of:.**.
15530 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ol>.** <li> 
15540 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
15550 41 44 4f 4e 4c 59 5d 0a 2a 2a 20 3c 6c 69 3e 20  ADONLY].** <li> 
15560 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
15570 41 44 57 52 49 54 45 5d 0a 2a 2a 20 3c 6c 69 3e  ADWRITE].** <li>
15580 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52    [SQLITE_OPEN_R
15590 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c  EADWRITE] | [SQL
155a0 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d  ITE_OPEN_CREATE]
155b0 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ol>.**.** 
155c0 54 68 65 20 66 69 72 73 74 20 76 61 6c 75 65 20  The first value 
155d0 6f 70 65 6e 73 20 74 68 65 20 64 61 74 61 62 61  opens the databa
155e0 73 65 20 72 65 61 64 2d 6f 6e 6c 79 2e 20 0a 2a  se read-only. .*
155f0 2a 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73  * If the databas
15600 65 20 64 6f 65 73 20 6e 6f 74 20 70 72 65 76 69  e does not previ
15610 6f 75 73 6c 79 20 65 78 69 73 74 2c 20 61 6e 20  ously exist, an 
15620 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
15630 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  d..** The second
15640 20 6f 70 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a   option opens.**
15650 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 6f   the database fo
15660 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72  r reading and wr
15670 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62 6c  iting if possibl
15680 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 20 6f 6e  e, or reading on
15690 6c 79 20 69 66 0a 2a 2a 20 69 66 20 74 68 65 20  ly if.** if the 
156a0 66 69 6c 65 20 69 73 20 77 72 69 74 65 20 70 72  file is write pr
156b0 6f 74 65 63 74 65 64 2e 20 20 49 6e 20 65 69 74  otected.  In eit
156c0 68 65 72 20 63 61 73 65 20 74 68 65 20 64 61 74  her case the dat
156d0 61 62 61 73 65 0a 2a 2a 20 6d 75 73 74 20 61 6c  abase.** must al
156e0 72 65 61 64 79 20 65 78 69 73 74 20 6f 72 20 61  ready exist or a
156f0 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  n error is retur
15700 6e 65 64 2e 20 20 54 68 65 20 74 68 69 72 64 20  ned.  The third 
15710 6f 70 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20  option.** opens 
15720 74 68 65 20 64 61 74 61 62 61 73 65 20 66 6f 72  the database for
15730 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69   reading and wri
15740 74 69 6e 67 20 61 6e 64 20 63 72 65 61 74 65 73  ting and creates
15750 20 69 74 20 69 66 20 69 74 20 64 6f 65 73 0a 2a   it if it does.*
15760 2a 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 65 78  * not already ex
15770 69 73 74 2e 0a 2a 2a 20 54 68 65 20 74 68 69 72  ist..** The thir
15780 64 20 6f 70 74 69 6f 6e 73 20 69 73 20 62 65 68  d options is beh
15790 61 76 69 6f 72 20 74 68 61 74 20 69 73 20 61 6c  avior that is al
157a0 77 61 79 73 20 75 73 65 64 20 66 6f 72 20 5b 73  ways used for [s
157b0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a  qlite3_open()].*
157c0 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f  * and [sqlite3_o
157d0 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  pen16()]..**.** 
157e0 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  If the 3rd param
157f0 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
15800 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 73 20 6e  _open_v2()] is n
15810 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a  ot one of the.**
15820 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68   combinations sh
15830 6f 77 6e 20 61 62 6f 76 65 20 74 68 65 6e 20 74  own above then t
15840 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75  he behavior is u
15850 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
15860 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  If the filename 
15870 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74  is ":memory:", t
15880 68 65 6e 20 61 6e 20 70 72 69 76 61 74 65 0a 2a  hen an private.*
15890 2a 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61  * in-memory data
158a0 62 61 73 65 20 69 73 20 63 72 65 61 74 65 64 20  base is created 
158b0 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69  for the connecti
158c0 6f 6e 2e 20 20 54 68 69 73 20 69 6e 2d 6d 65 6d  on.  This in-mem
158d0 6f 72 79 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  ory.** database 
158e0 77 69 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 6e  will vanish when
158f0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
15900 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73  nnection is clos
15910 65 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76  ed.  Future.** v
15920 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65  ersion of SQLite
15930 20 6d 69 67 68 74 20 6d 61 6b 65 20 75 73 65 20   might make use 
15940 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 70  of additional sp
15950 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73 0a  ecial filenames.
15960 2a 2a 20 74 68 61 74 20 62 65 67 69 6e 20 77 69  ** that begin wi
15970 74 68 20 74 68 65 20 22 3a 22 20 63 68 61 72 61  th the ":" chara
15980 63 74 65 72 2e 20 20 49 74 20 69 73 20 72 65 63  cter.  It is rec
15990 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 0a 2a  ommended that .*
159a0 2a 20 77 68 65 6e 20 61 20 64 61 74 61 62 61 73  * when a databas
159b0 65 20 66 69 6c 65 6e 61 6d 65 20 72 65 61 6c 6c  e filename reall
159c0 79 20 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74  y does begin wit
159d0 68 0a 2a 2a 20 22 3a 22 20 74 68 61 74 20 79 6f  h.** ":" that yo
159e0 75 20 70 72 65 66 69 78 20 74 68 65 20 66 69 6c  u prefix the fil
159f0 65 6e 61 6d 65 20 77 69 74 68 20 61 20 70 61 74  ename with a pat
15a00 68 6e 61 6d 65 20 6c 69 6b 65 20 22 2e 2f 22 20  hname like "./" 
15a10 74 6f 0a 2a 2a 20 61 76 6f 69 64 20 61 6d 62 69  to.** avoid ambi
15a20 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  guity..**.** If 
15a30 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20  the filename is 
15a40 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c  an empty string,
15a50 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 20   then a private 
15a60 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d  temporary.** on-
15a70 64 69 73 6b 20 64 61 74 61 62 61 73 65 20 77 69  disk database wi
15a80 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20 20  ll be created.  
15a90 54 68 69 73 20 70 72 69 76 61 74 65 20 64 61 74  This private dat
15aa0 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a  abase will be.**
15ab0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64   automatically d
15ac0 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61  eleted as soon a
15ad0 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  s the database c
15ae0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f  onnection is clo
15af0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  sed..**.** The f
15b00 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
15b10 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
15b20 76 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65  v2() is the name
15b30 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   of the.** [sqli
15b40 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20  te3_vfs] object 
15b50 74 68 61 74 20 64 65 66 69 6e 65 73 20 74 68 65  that defines the
15b60 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
15b70 6d 20 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  m .** interface 
15b80 74 68 61 74 20 74 68 65 20 6e 65 77 20 64 61 74  that the new dat
15b90 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
15ba0 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 49 66   should use.  If
15bb0 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70   the.** fourth p
15bc0 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 4e 55  arameter is a NU
15bd0 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20  LL pointer then 
15be0 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c  the default [sql
15bf0 69 74 65 33 5f 76 66 73 5d 0a 2a 2a 20 6f 62 6a  ite3_vfs].** obj
15c00 65 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a  ect is used..**.
15c10 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 77 69  ** <b>Note to wi
15c20 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e  ndows users:</b>
15c30 20 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75    The encoding u
15c40 73 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65  sed for the file
15c50 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  name argument.**
15c60 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   of [sqlite3_ope
15c70 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  n()] and [sqlite
15c80 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6d 75 73  3_open_v2()] mus
15c90 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20  t be UTF-8, not 
15ca0 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65  whatever.** code
15cb0 70 61 67 65 20 69 73 20 63 75 72 72 65 6e 74 6c  page is currentl
15cc0 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c 65  y defined.  File
15cd0 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67  names containing
15ce0 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a   international.*
15cf0 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d 75 73  * characters mus
15d00 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74  t be converted t
15d10 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74 6f  o UTF-8 prior to
15d20 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69 6e   passing them in
15d30 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f  to.** [sqlite3_o
15d40 70 65 6e 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  pen()] or [sqlit
15d50 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 0a 2a  e3_open_v2()]..*
15d60 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
15d70 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 30 31 7d 20  .**.** {F12701} 
15d80 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  The [sqlite3_ope
15d90 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  n()], [sqlite3_o
15da0 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a  pen16()], and.**
15db0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
15dc0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e  e3_open_v2()] in
15dd0 74 65 72 66 61 63 65 73 20 63 72 65 61 74 65 20  terfaces create 
15de0 61 20 6e 65 77 0a 2a 2a 20 20 20 20 20 20 20 20  a new.**        
15df0 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e    [database conn
15e00 65 63 74 69 6f 6e 5d 20 61 73 73 6f 63 69 61 74  ection] associat
15e10 65 64 20 77 69 74 68 0a 2a 2a 20 20 20 20 20 20  ed with.**      
15e20 20 20 20 20 74 68 65 20 64 61 74 61 62 61 73 65      the database
15e30 20 66 69 6c 65 20 67 69 76 65 6e 20 69 6e 20 74   file given in t
15e40 68 65 69 72 20 66 69 72 73 74 20 70 61 72 61 6d  heir first param
15e50 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  eter..**.** {F12
15e60 37 30 32 7d 20 54 68 65 20 66 69 6c 65 6e 61 6d  702} The filenam
15e70 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e  e argument is in
15e80 74 65 72 70 72 65 74 65 64 20 61 73 20 55 54 46  terpreted as UTF
15e90 2d 38 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  -8.**          f
15ea0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  or [sqlite3_open
15eb0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
15ec0 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 61 6e 64 20  _open_v2()] and 
15ed0 61 73 20 55 54 46 2d 31 36 0a 2a 2a 20 20 20 20  as UTF-16.**    
15ee0 20 20 20 20 20 20 69 6e 20 74 68 65 20 6e 61 74        in the nat
15ef0 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 66  ive byte order f
15f00 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  or [sqlite3_open
15f10 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  16()]..**.** {F1
15f20 32 37 30 33 7d 20 41 20 73 75 63 63 65 73 73 66  2703} A successf
15f30 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  ul invocation of
15f40 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
15f50 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
15f60 31 36 28 29 5d 2c 20 0a 2a 2a 20 20 20 20 20 20  16()], .**      
15f70 20 20 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f      or [sqlite3_
15f80 6f 70 65 6e 5f 76 32 28 29 5d 20 77 72 69 74 65  open_v2()] write
15f90 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
15fa0 20 6e 65 77 0a 2a 2a 20 20 20 20 20 20 20 20 20   new.**         
15fb0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
15fc0 63 74 69 6f 6e 5d 20 69 6e 74 6f 20 2a 70 70 44  ction] into *ppD
15fd0 62 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 30 34  b..**.** {F12704
15fe0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f  } The [sqlite3_o
15ff0 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  pen()], [sqlite3
16000 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a  _open16()], and.
16010 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
16020 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20  ite3_open_v2()] 
16030 69 6e 74 65 72 66 61 63 65 73 20 72 65 74 75 72  interfaces retur
16040 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 75 70  n [SQLITE_OK] up
16050 6f 6e 20 73 75 63 63 65 73 73 2c 0a 2a 2a 20 20  on success,.**  
16060 20 20 20 20 20 20 20 20 6f 72 20 61 6e 20 61 70          or an ap
16070 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72  propriate [error
16080 20 63 6f 64 65 5d 20 6f 6e 20 66 61 69 6c 75 72   code] on failur
16090 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 30 36  e..**.** {F12706
160a0 7d 20 54 68 65 20 64 65 66 61 75 6c 74 20 74 65  } The default te
160b0 78 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20  xt encoding for 
160c0 61 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63  a new database c
160d0 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20  reated using.** 
160e0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
160f0 33 5f 6f 70 65 6e 28 29 5d 20 6f 72 20 5b 73 71  3_open()] or [sq
16100 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
16110 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38 2e 0a   will be UTF-8..
16120 2a 2a 0a 2a 2a 20 7b 46 31 32 37 30 37 7d 20 54  **.** {F12707} T
16130 68 65 20 64 65 66 61 75 6c 74 20 74 65 78 74 20  he default text 
16140 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 61 20 6e  encoding for a n
16150 65 77 20 64 61 74 61 62 61 73 65 20 63 72 65 61  ew database crea
16160 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20  ted using.**    
16170 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f        [sqlite3_o
16180 70 65 6e 31 36 28 29 5d 20 77 69 6c 6c 20 62 65  pen16()] will be
16190 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 7b   UTF-16..**.** {
161a0 46 31 32 37 30 39 7d 20 54 68 65 20 5b 73 71 6c  F12709} The [sql
161b0 69 74 65 33 5f 6f 70 65 6e 28 46 2c 44 29 5d 20  ite3_open(F,D)] 
161c0 69 6e 74 65 72 66 61 63 65 20 69 73 20 65 71 75  interface is equ
161d0 69 76 61 6c 65 6e 74 20 74 6f 0a 2a 2a 20 20 20  ivalent to.**   
161e0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
161f0 6f 70 65 6e 5f 76 32 28 46 2c 44 2c 47 2c 30 29  open_v2(F,D,G,0)
16200 5d 20 77 68 65 72 65 20 74 68 65 20 47 20 70 61  ] where the G pa
16210 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 20 20  rameter is.**   
16220 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 4f         [SQLITE_O
16230 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 7c 5b  PEN_READWRITE]|[
16240 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
16250 54 45 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37  TE]..**.** {F127
16260 31 31 7d 20 49 66 20 74 68 65 20 47 20 70 61 72  11} If the G par
16270 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
16280 65 33 5f 6f 70 65 6e 5f 76 32 28 46 2c 44 2c 47  e3_open_v2(F,D,G
16290 2c 56 29 5d 20 63 6f 6e 74 61 69 6e 73 20 74 68  ,V)] contains th
162a0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 69  e.**          bi
162b0 74 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f  t value [SQLITE_
162c0 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 74  OPEN_READONLY] t
162d0 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
162e0 20 69 73 20 6f 70 65 6e 65 64 0a 2a 2a 20 20 20   is opened.**   
162f0 20 20 20 20 20 20 20 66 6f 72 20 72 65 61 64 69         for readi
16300 6e 67 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b  ng only..**.** {
16310 46 31 32 37 31 32 7d 20 49 66 20 74 68 65 20 47  F12712} If the G
16320 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
16330 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 46  qlite3_open_v2(F
16340 2c 44 2c 47 2c 56 29 5d 20 63 6f 6e 74 61 69 6e  ,D,G,V)] contain
16350 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
16360 20 20 62 69 74 20 76 61 6c 75 65 20 5b 53 51 4c    bit value [SQL
16370 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
16380 54 45 5d 20 74 68 65 6e 20 74 68 65 20 64 61 74  TE] then the dat
16390 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 0a  abase is opened.
163a0 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 61 64  **          read
163b0 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20  ing and writing 
163c0 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20  if possible, or 
163d0 66 6f 72 20 72 65 61 64 69 6e 67 20 6f 6e 6c 79  for reading only
163e0 20 69 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   if the.**      
163f0 20 20 20 20 66 69 6c 65 20 69 73 20 77 72 69 74      file is writ
16400 65 20 70 72 6f 74 65 63 74 65 64 20 62 79 20 74  e protected by t
16410 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
16420 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37  tem..**.** {F127
16430 31 33 7d 20 49 66 20 74 68 65 20 47 20 70 61 72  13} If the G par
16440 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
16450 65 33 5f 6f 70 65 6e 28 76 32 28 46 2c 44 2c 47  e3_open(v2(F,D,G
16460 2c 56 29 5d 20 6f 6d 69 74 73 20 74 68 65 0a 2a  ,V)] omits the.*
16470 2a 20 20 20 20 20 20 20 20 20 20 62 69 74 20 76  *          bit v
16480 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  alue [SQLITE_OPE
16490 4e 5f 43 52 45 41 54 45 5d 20 61 6e 64 20 74 68  N_CREATE] and th
164a0 65 20 64 61 74 61 62 61 73 65 20 64 6f 65 73 20  e database does 
164b0 6e 6f 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  not.**          
164c0 70 72 65 76 69 6f 75 73 6c 79 20 65 78 69 73 74  previously exist
164d0 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65  , an error is re
164e0 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46  turned..**.** {F
164f0 31 32 37 31 34 7d 20 49 66 20 74 68 65 20 47 20  12714} If the G 
16500 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
16510 6c 69 74 65 33 5f 6f 70 65 6e 28 76 32 28 46 2c  lite3_open(v2(F,
16520 44 2c 47 2c 56 29 5d 20 63 6f 6e 74 61 69 6e 73  D,G,V)] contains
16530 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
16540 20 62 69 74 20 76 61 6c 75 65 20 5b 53 51 4c 49   bit value [SQLI
16550 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20  TE_OPEN_CREATE] 
16560 61 6e 64 20 74 68 65 20 64 61 74 61 62 61 73 65  and the database
16570 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 20 20 20   does not.**    
16580 20 20 20 20 20 20 70 72 65 76 69 6f 75 73 6c 79        previously
16590 20 65 78 69 73 74 2c 20 74 68 65 6e 20 61 6e 20   exist, then an 
165a0 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20  attempt is made 
165b0 74 6f 20 63 72 65 61 74 65 20 61 6e 64 0a 2a 2a  to create and.**
165c0 20 20 20 20 20 20 20 20 20 20 69 6e 69 74 69 61            initia
165d0 6c 69 7a 65 20 74 68 65 20 64 61 74 61 62 61 73  lize the databas
165e0 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 31 37  e..**.** {F12717
165f0 7d 20 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d  } If the filenam
16600 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73  e argument to [s
16610 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
16620 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
16630 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  )],.**          
16640 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  or [sqlite3_open
16650 5f 76 32 28 29 5d 20 69 73 20 22 3a 6d 65 6d 6f  _v2()] is ":memo
16660 72 79 3a 22 2c 20 74 68 65 6e 20 61 6e 20 70 72  ry:", then an pr
16670 69 76 61 74 65 2c 0a 2a 2a 20 20 20 20 20 20 20  ivate,.**       
16680 20 20 20 65 70 68 65 6d 65 72 61 6c 2c 20 69 6e     ephemeral, in
16690 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65  -memory database
166a0 20 69 73 20 63 72 65 61 74 65 64 20 66 6f 72 20   is created for 
166b0 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 0a  the connection..
166c0 2a 2a 20 20 20 20 20 20 20 20 20 20 3c 74 6f 64  **          <tod
166d0 6f 3e 49 73 20 53 51 4c 49 54 45 5f 4f 50 45 4e  o>Is SQLITE_OPEN
166e0 5f 43 52 45 41 54 45 7c 53 51 4c 49 54 45 5f 4f  _CREATE|SQLITE_O
166f0 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 72 65  PEN_READWRITE re
16700 71 75 69 72 65 64 0a 2a 2a 20 20 20 20 20 20 20  quired.**       
16710 20 20 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70     in sqlite3_op
16720 65 6e 5f 76 32 28 29 3f 3c 2f 74 6f 64 6f 3e 0a  en_v2()?</todo>.
16730 2a 2a 0a 2a 2a 20 7b 46 31 32 37 31 39 7d 20 49  **.** {F12719} I
16740 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69  f the filename i
16750 73 20 4e 55 4c 4c 20 6f 72 20 61 6e 20 65 6d 70  s NULL or an emp
16760 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20  ty string, then 
16770 61 20 70 72 69 76 61 74 65 2c 0a 2a 2a 20 20 20  a private,.**   
16780 20 20 20 20 20 20 20 65 70 68 65 72 6d 65 72 61         ephermera
16790 6c 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62 61  l on-disk databa
167a0 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61 74  se will be creat
167b0 65 64 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ed..**          
167c0 3c 74 6f 64 6f 3e 49 73 20 53 51 4c 49 54 45 5f  <todo>Is SQLITE_
167d0 4f 50 45 4e 5f 43 52 45 41 54 45 7c 53 51 4c 49  OPEN_CREATE|SQLI
167e0 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
167f0 45 20 72 65 71 75 69 72 65 64 0a 2a 2a 20 20 20  E required.**   
16800 20 20 20 20 20 20 20 69 6e 20 73 71 6c 69 74 65         in sqlite
16810 33 5f 6f 70 65 6e 5f 76 32 28 29 3f 3c 2f 74 6f  3_open_v2()?</to
16820 64 6f 3e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 32  do>.**.** {F1272
16830 31 7d 20 54 68 65 20 5b 64 61 74 61 62 61 73 65  1} The [database
16840 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 63 72 65   connection] cre
16850 61 74 65 64 20 62 79 20 0a 2a 2a 20 20 20 20 20  ated by .**     
16860 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f 70       [sqlite3_op
16870 65 6e 5f 76 32 28 46 2c 44 2c 47 2c 56 29 5d 20  en_v2(F,D,G,V)] 
16880 77 69 6c 6c 20 75 73 65 20 74 68 65 0a 2a 2a 20  will use the.** 
16890 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
168a0 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 64  3_vfs] object id
168b0 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20  entified by the 
168c0 56 20 70 61 72 61 6d 65 74 65 72 2c 20 6f 72 0a  V parameter, or.
168d0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
168e0 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
168f0 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 73 20  _vfs] object is 
16900 56 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  V is a NULL poin
16910 74 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ter..*/.int sqli
16920 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73  te3_open(.  cons
16930 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65  t char *filename
16940 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  ,   /* Database 
16950 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29  filename (UTF-8)
16960 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a   */.  sqlite3 **
16970 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a  ppDb          /*
16980 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20   OUT: SQLite db 
16990 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74  handle */.);.int
169a0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
169b0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66  .  const void *f
169c0 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61  ilename,   /* Da
169d0 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
169e0 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71  (UTF-16) */.  sq
169f0 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20  lite3 **ppDb    
16a00 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
16a10 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
16a20 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
16a30 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73  _open_v2(.  cons
16a40 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65  t char *filename
16a50 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  ,   /* Database 
16a60 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29  filename (UTF-8)
16a70 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a   */.  sqlite3 **
16a80 70 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a  ppDb,         /*
16a90 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20   OUT: SQLite db 
16aa0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20  handle */.  int 
16ab0 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20 20  flags,          
16ac0 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a      /* Flags */.
16ad0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56    const char *zV
16ae0 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d  fs        /* Nam
16af0 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20  e of VFS module 
16b00 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a  to use */.);../*
16b10 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72  .** CAPI3REF: Er
16b20 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65  ror Codes And Me
16b30 73 73 61 67 65 73 20 7b 46 31 32 38 30 30 7d 0a  ssages {F12800}.
16b40 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
16b50 33 5f 65 72 72 63 6f 64 65 28 29 20 69 6e 74 65  3_errcode() inte
16b60 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
16b70 65 20 6e 75 6d 65 72 69 63 0a 2a 2a 20 5b 53 51  e numeric.** [SQ
16b80 4c 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74  LITE_OK | result
16b90 20 63 6f 64 65 5d 20 6f 72 20 5b 53 51 4c 49 54   code] or [SQLIT
16ba0 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 65  E_IOERR_READ | e
16bb0 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
16bc0 6f 64 65 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20  ode].** for the 
16bd0 6d 6f 73 74 20 72 65 63 65 6e 74 20 66 61 69 6c  most recent fail
16be0 65 64 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 49  ed sqlite3_* API
16bf0 20 63 61 6c 6c 20 61 73 73 6f 63 69 61 74 65 64   call associated
16c00 0a 2a 2a 20 77 69 74 68 20 5b 73 71 6c 69 74 65  .** with [sqlite
16c10 33 5d 20 68 61 6e 64 6c 65 20 27 64 62 27 2e 20  3] handle 'db'. 
16c20 49 66 20 61 20 70 72 69 6f 72 20 41 50 49 20 63  If a prior API c
16c30 61 6c 6c 20 66 61 69 6c 65 64 20 62 75 74 20 74  all failed but t
16c40 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e  he.** most recen
16c50 74 20 41 50 49 20 63 61 6c 6c 20 73 75 63 63 65  t API call succe
16c60 65 64 65 64 2c 20 74 68 65 20 72 65 74 75 72 6e  eded, the return
16c70 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69   value from sqli
16c80 74 65 33 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a  te3_errcode().**
16c90 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
16ca0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
16cb0 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71  _errmsg() and sq
16cc0 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29  lite3_errmsg16()
16cd0 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d   return English-
16ce0 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 74  language.** text
16cf0 20 74 68 61 74 20 64 65 73 63 72 69 62 65 73 20   that describes 
16d00 74 68 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69  the error, as ei
16d10 74 68 65 72 20 55 54 46 38 20 6f 72 20 55 54 46  ther UTF8 or UTF
16d20 31 36 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  16 respectively.
16d30 0a 2a 2a 20 4d 65 6d 6f 72 79 20 74 6f 20 68 6f  .** Memory to ho
16d40 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  ld the error mes
16d50 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d  sage string is m
16d60 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c  anaged internall
16d70 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  y..** The applic
16d80 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e  ation does not n
16d90 65 65 64 20 74 6f 20 77 6f 72 72 79 20 77 69 74  eed to worry wit
16da0 68 20 66 72 65 65 69 6e 67 20 74 68 65 20 72 65  h freeing the re
16db0 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72  sult..** However
16dc0 2c 20 74 68 65 20 65 72 72 6f 72 20 73 74 72 69  , the error stri
16dd0 6e 67 20 6d 69 67 68 74 20 62 65 20 6f 76 65 72  ng might be over
16de0 77 72 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c  written or deall
16df0 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20 73 75 62  ocated by.** sub
16e00 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
16e10 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
16e20 74 65 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e  terface function
16e30 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  s..**.** INVARIA
16e40 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 38  NTS:.**.** {F128
16e50 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  01} The [sqlite3
16e60 5f 65 72 72 63 6f 64 65 28 44 29 5d 20 69 6e 74  _errcode(D)] int
16e70 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
16e80 68 65 20 6e 75 6d 65 72 69 63 0a 2a 2a 20 20 20  he numeric.**   
16e90 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 4f         [SQLITE_O
16ea0 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 5d  K | result code]
16eb0 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   or.**          
16ec0 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45  [SQLITE_IOERR_RE
16ed0 41 44 20 7c 20 65 78 74 65 6e 64 65 64 20 72 65  AD | extended re
16ee0 73 75 6c 74 20 63 6f 64 65 5d 0a 2a 2a 20 20 20  sult code].**   
16ef0 20 20 20 20 20 20 20 66 6f 72 20 74 68 65 20 6d         for the m
16f00 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 66 61 69  ost recently fai
16f10 6c 65 64 20 69 6e 74 65 72 66 61 63 65 20 63 61  led interface ca
16f20 6c 6c 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a  ll associated.**
16f30 20 20 20 20 20 20 20 20 20 20 77 69 74 68 20 5b            with [
16f40 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
16f50 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46  ion] D..**.** {F
16f60 31 32 38 30 33 7d 20 54 68 65 20 5b 73 71 6c 69  12803} The [sqli
16f70 74 65 33 5f 65 72 72 6d 73 67 28 44 29 5d 20 61  te3_errmsg(D)] a
16f80 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  nd [sqlite3_errm
16f90 73 67 31 36 28 44 29 5d 0a 2a 2a 20 20 20 20 20  sg16(D)].**     
16fa0 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 20       interfaces 
16fb0 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c  return English-l
16fc0 61 6e 67 75 61 67 65 20 74 65 78 74 20 74 68 61  anguage text tha
16fd0 74 20 64 65 73 63 72 69 62 65 73 0a 2a 2a 20 20  t describes.**  
16fe0 20 20 20 20 20 20 20 20 74 68 65 20 65 72 72 6f          the erro
16ff0 72 20 69 6e 20 74 68 65 20 6d 6f 73 74 6c 79 20  r in the mostly 
17000 72 65 63 65 6e 74 6c 79 20 66 61 69 6c 65 64 20  recently failed 
17010 69 6e 74 65 72 66 61 63 65 20 63 61 6c 6c 2c 0a  interface call,.
17020 2a 2a 20 20 20 20 20 20 20 20 20 20 65 6e 63 6f  **          enco
17030 64 65 64 20 61 73 20 65 69 74 68 65 72 20 55 54  ded as either UT
17040 46 38 20 6f 72 20 55 54 46 31 36 20 72 65 73 70  F8 or UTF16 resp
17050 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ectively..**.** 
17060 7b 46 31 32 38 30 37 7d 20 54 68 65 20 73 74 72  {F12807} The str
17070 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79  ings returned by
17080 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
17090 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
170a0 5f 65 72 72 6d 73 67 31 36 28 29 5d 0a 2a 2a 20  _errmsg16()].** 
170b0 20 20 20 20 20 20 20 20 20 61 72 65 20 76 61 6c           are val
170c0 69 64 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78  id until the nex
170d0 74 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  t SQLite interfa
170e0 63 65 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 7b  ce call..**.** {
170f0 46 31 32 38 30 38 7d 20 43 61 6c 6c 73 20 74 6f  F12808} Calls to
17100 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 74 68   API routines th
17110 61 74 20 64 6f 20 6e 6f 74 20 72 65 74 75 72 6e  at do not return
17120 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a   an error code.*
17130 2a 20 20 20 20 20 20 20 20 20 20 28 65 78 61 6d  *          (exam
17140 70 6c 65 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61  ple: [sqlite3_da
17150 74 61 5f 63 6f 75 6e 74 28 29 5d 29 20 64 6f 20  ta_count()]) do 
17160 6e 6f 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  not.**          
17170 63 68 61 6e 67 65 20 74 68 65 20 65 72 72 6f 72  change the error
17180 20 63 6f 64 65 20 6f 72 20 6d 65 73 73 61 67 65   code or message
17190 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
171a0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
171b0 33 5f 65 72 72 63 6f 64 65 28 29 5d 2c 20 5b 73  3_errcode()], [s
171c0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
171d0 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72  , or [sqlite3_er
171e0 72 6d 73 67 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a  rmsg16()]..**.**
171f0 20 7b 46 31 32 38 30 39 7d 20 49 6e 74 65 72 66   {F12809} Interf
17200 61 63 65 73 20 74 68 61 74 20 61 72 65 20 6e 6f  aces that are no
17210 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  t associated wit
17220 68 20 61 20 73 70 65 63 69 66 69 63 0a 2a 2a 20  h a specific.** 
17230 20 20 20 20 20 20 20 20 20 5b 64 61 74 61 62 61           [databa
17240 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28  se connection] (
17250 65 78 61 6d 70 6c 65 73 3a 0a 2a 2a 20 20 20 20  examples:.**    
17260 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6d        [sqlite3_m
17270 70 72 69 6e 74 66 28 29 5d 20 6f 72 20 5b 73 71  printf()] or [sq
17280 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61  lite3_enable_sha
17290 72 65 64 5f 63 61 63 68 65 28 29 5d 0a 2a 2a 20  red_cache()].** 
172a0 20 20 20 20 20 20 20 20 20 64 6f 20 6e 6f 74 20           do not 
172b0 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65  change the value
172c0 73 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  s returned by.**
172d0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
172e0 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 2c 20 5b  e3_errcode()], [
172f0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
17300 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65  ], or [sqlite3_e
17310 72 72 6d 73 67 31 36 28 29 5d 2e 0a 2a 2f 0a 69  rrmsg16()]..*/.i
17320 6e 74 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  nt sqlite3_errco
17330 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b  de(sqlite3 *db);
17340 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
17350 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69  ite3_errmsg(sqli
17360 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  te3*);.const voi
17370 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  d *sqlite3_errms
17380 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  g16(sqlite3*);..
17390 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
173a0 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f 62  SQL Statement Ob
173b0 6a 65 63 74 20 7b 46 31 33 30 30 30 7d 0a 2a 2a  ject {F13000}.**
173c0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 65 70   KEYWORDS: {prep
173d0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 7d 20  ared statement} 
173e0 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  {prepared statem
173f0 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69  ents}.**.** An i
17400 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
17410 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74  object represent
17420 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74   single SQL stat
17430 65 6d 65 6e 74 73 2e 20 20 54 68 69 73 0a 2a 2a  ements.  This.**
17440 20 6f 62 6a 65 63 74 20 69 73 20 76 61 72 69 6f   object is vario
17450 75 73 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 61 20  usly known as a 
17460 22 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  "prepared statem
17470 65 6e 74 22 20 6f 72 20 61 20 0a 2a 2a 20 22 63  ent" or a .** "c
17480 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 61 74  ompiled SQL stat
17490 65 6d 65 6e 74 22 20 6f 72 20 73 69 6d 70 6c 79  ement" or simply
174a0 20 61 73 20 61 20 22 73 74 61 74 65 6d 65 6e 74   as a "statement
174b0 22 2e 0a 2a 2a 20 0a 2a 2a 20 54 68 65 20 6c 69  "..** .** The li
174c0 66 65 20 6f 66 20 61 20 73 74 61 74 65 6d 65 6e  fe of a statemen
174d0 74 20 6f 62 6a 65 63 74 20 67 6f 65 73 20 73 6f  t object goes so
174e0 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20 74 68 69  mething like thi
174f0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a  s:.**.** <ol>.**
17500 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68 65   <li> Create the
17510 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73   object using [s
17520 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
17530 32 28 29 5d 20 6f 72 20 61 20 72 65 6c 61 74 65  2()] or a relate
17540 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e 63 74 69  d.**      functi
17550 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64  on..** <li> Bind
17560 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73 74 20   values to host 
17570 70 61 72 61 6d 65 74 65 72 73 20 75 73 69 6e 67  parameters using
17580 0a 2a 2a 20 20 20 20 20 20 5b 73 71 6c 69 74 65  .**      [sqlite
17590 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71  3_bind_blob | sq
175a0 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 69 6e 74  lite3_bind_* int
175b0 65 72 66 61 63 65 73 5d 2e 0a 2a 2a 20 3c 6c 69  erfaces]..** <li
175c0 3e 20 52 75 6e 20 74 68 65 20 53 51 4c 20 62 79  > Run the SQL by
175d0 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
175e0 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72  3_step()] one or
175f0 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20   more times..** 
17600 3c 6c 69 3e 20 52 65 73 65 74 20 74 68 65 20 73  <li> Reset the s
17610 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b  tatement using [
17620 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
17630 20 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a   then go back.**
17640 20 20 20 20 20 20 74 6f 20 73 74 65 70 20 32 2e        to step 2.
17650 20 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f    Do this zero o
17660 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a  r more times..**
17670 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 74 68   <li> Destroy th
17680 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b  e object using [
17690 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
176a0 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a  ()]..** </ol>.**
176b0 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 64 6f 63  .** Refer to doc
176c0 75 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e 20 69 6e  umentation on in
176d0 64 69 76 69 64 75 61 6c 20 6d 65 74 68 6f 64 73  dividual methods
176e0 20 61 62 6f 76 65 20 66 6f 72 20 61 64 64 69 74   above for addit
176f0 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61  ional.** informa
17700 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  tion..*/.typedef
17710 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
17720 73 74 6d 74 20 73 71 6c 69 74 65 33 5f 73 74 6d  stmt sqlite3_stm
17730 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  t;../*.** CAPI3R
17740 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d  EF: Run-time Lim
17750 69 74 73 20 7b 46 31 32 37 36 30 7d 0a 2a 2a 0a  its {F12760}.**.
17760 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
17770 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a  e allows the siz
17780 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e  e of various con
17790 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69  structs to be li
177a0 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f  mited.** on a co
177b0 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e  nnection by conn
177c0 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54  ection basis.  T
177d0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
177e0 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61  er is the.** [da
177f0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
17800 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69  n] whose limit i
17810 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71  s to be set or q
17820 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20  ueried.  The.** 
17830 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
17840 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b   is one of the [
17850 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73  limit categories
17860 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a  ] that define a.
17870 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73  ** class of cons
17880 74 72 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a  tructs to be siz
17890 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20  e limited.  The 
178a0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
178b0 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69  is the.** new li
178c0 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e  mit for that con
178d0 73 74 72 75 63 74 2e 20 20 54 68 65 20 66 75 6e  struct.  The fun
178e0 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
178f0 65 20 6f 6c 64 20 6c 69 6d 69 74 2e 0a 2a 2a 0a  e old limit..**.
17900 2a 2a 20 49 66 20 74 68 65 20 6e 65 77 20 6c 69  ** If the new li
17910 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74 69 76  mit is a negativ
17920 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69  e number, the li
17930 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64  mit is unchanged
17940 2e 0a 2a 2a 20 46 6f 72 20 74 68 65 20 6c 69 6d  ..** For the lim
17950 69 74 20 63 61 74 65 67 6f 72 79 20 6f 66 20 53  it category of S
17960 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 58 59 5a 20  QLITE_LIMIT_XYZ 
17970 74 68 65 72 65 20 69 73 20 61 20 68 61 72 64 20  there is a hard 
17980 75 70 70 65 72 0a 2a 2a 20 62 6f 75 6e 64 20 73  upper.** bound s
17990 65 74 20 62 79 20 61 20 63 6f 6d 70 69 6c 65 2d  et by a compile-
179a0 74 69 6d 65 20 43 2d 70 72 65 70 72 6f 63 65 73  time C-preproces
179b0 73 20 6d 61 63 72 6f 20 6e 61 6d 65 64 20 53 51  s macro named SQ
179c0 4c 49 54 45 5f 4d 41 58 5f 58 59 5a 2e 0a 2a 2a  LITE_MAX_XYZ..**
179d0 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20   (The "_LIMIT_" 
179e0 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20 63  in the name is c
179f0 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f  hanged to "_MAX_
17a00 22 2e 29 0a 2a 2a 20 41 74 74 65 6d 70 74 73 20  ".).** Attempts 
17a10 74 6f 20 69 6e 63 72 65 61 73 65 20 61 20 6c 69  to increase a li
17a20 6d 69 74 20 61 62 6f 76 65 20 69 74 73 20 68 61  mit above its ha
17a30 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61  rd upper bound a
17a40 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74  re.** silently t
17a50 72 75 6e 63 61 74 65 64 20 74 6f 20 74 68 65 20  runcated to the 
17a60 68 61 72 64 20 75 70 70 65 72 20 6c 69 6d 69 74  hard upper limit
17a70 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 20 74 69 6d 65  ..**.** Run time
17a80 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e 74 65   limits are inte
17a90 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20  nded for use in 
17aa0 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  applications tha
17ab0 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68  t manage.** both
17ac0 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74 65 72   their own inter
17ad0 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61 6e 64  nal database and
17ae0 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65 73 20   also databases 
17af0 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c  that are control
17b00 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73  led.** by untrus
17b10 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73 6f 75  ted external sou
17b20 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c  rces.  An exampl
17b30 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69  e application mi
17b40 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65 62 62  ght be a.** webb
17b50 72 6f 77 73 65 72 20 74 68 61 74 20 68 61 73 20  rowser that has 
17b60 69 74 73 20 6f 77 6e 20 64 61 74 61 62 61 73 65  its own database
17b70 73 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 68 69  s for storing hi
17b80 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70  story and.** sep
17b90 61 72 61 74 65 20 64 61 74 61 62 61 73 65 73 20  arate databases 
17ba0 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 6a 61  controlled by ja
17bb0 76 61 73 63 72 69 70 74 20 61 70 70 6c 69 63 61  vascript applica
17bc0 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64  tions downloaded
17bd0 0a 2a 2a 20 6f 66 66 20 74 68 65 20 69 6e 74 65  .** off the inte
17be0 72 6e 65 74 2e 20 20 54 68 65 20 69 6e 74 65 72  rnet.  The inter
17bf0 6e 61 6c 20 64 61 74 61 62 61 73 65 73 20 63 61  nal databases ca
17c00 6e 20 62 65 20 67 69 76 65 6e 20 74 68 65 0a 2a  n be given the.*
17c10 2a 20 6c 61 72 67 65 2c 20 64 65 66 61 75 6c 74  * large, default
17c20 20 6c 69 6d 69 74 73 2e 20 20 44 61 74 61 62 61   limits.  Databa
17c30 73 65 73 20 6d 61 6e 61 67 65 64 20 62 79 20 65  ses managed by e
17c40 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 20  xternal sources 
17c50 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20  can.** be given 
17c60 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d  much smaller lim
17c70 69 74 73 20 64 65 73 69 67 6e 65 64 20 74 6f 20  its designed to 
17c80 70 72 65 76 65 6e 74 20 61 20 64 65 6e 69 61 6c  prevent a denial
17c90 20 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a 20 61   of service.** a
17ca0 74 74 61 63 68 2e 20 20 44 65 76 65 6c 6f 70 65  ttach.  Develope
17cb0 72 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 77 61  rs might also wa
17cc0 6e 74 20 74 6f 20 75 73 65 20 74 68 65 20 5b 73  nt to use the [s
17cd0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
17ce0 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65  rizer()].** inte
17cf0 72 66 61 63 65 20 74 6f 20 66 75 72 74 68 65 72  rface to further
17d00 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74   control untrust
17d10 65 64 20 53 51 4c 2e 20 20 54 68 65 20 73 69 7a  ed SQL.  The siz
17d20 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  e of the databas
17d30 65 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20  e.** created by 
17d40 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 63 72  an untrusted scr
17d50 69 70 74 20 63 61 6e 20 62 65 20 63 6f 6e 74 61  ipt can be conta
17d60 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a  ined using the.*
17d70 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e  * [max_page_coun
17d80 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a  t] [PRAGMA]..**.
17d90 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
17da0 65 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 63  e is currently c
17db0 6f 6e 73 69 64 65 72 65 64 20 65 78 70 65 72 69  onsidered experi
17dc0 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 20 73 75  mental and is su
17dd0 62 6a 65 63 74 0a 2a 2a 20 74 6f 20 63 68 61 6e  bject.** to chan
17de0 67 65 20 6f 72 20 72 65 6d 6f 76 61 6c 20 77 69  ge or removal wi
17df0 74 68 6f 75 74 20 70 72 69 6f 72 20 6e 6f 74 69  thout prior noti
17e00 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  ce..**.** INVARI
17e10 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  ANTS:.**.** {F12
17e20 37 36 32 7d 20 41 20 73 75 63 63 65 73 73 66 75  762} A successfu
17e30 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  l call to [sqlit
17e40 65 33 5f 6c 69 6d 69 74 28 44 2c 43 2c 56 29 5d  e3_limit(D,C,V)]
17e50 20 77 68 65 72 65 20 56 20 69 73 0a 2a 2a 20 20   where V is.**  
17e60 20 20 20 20 20 20 20 20 70 6f 73 69 74 69 76 65          positive
17e70 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20   changes the.** 
17e80 20 20 20 20 20 20 20 20 20 6c 69 6d 69 74 20 6f           limit o
17e90 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 63 6f  n the size of co
17ea0 6e 73 74 72 75 63 74 20 43 20 69 6e 20 5b 64 61  nstruct C in [da
17eb0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
17ec0 6e 5d 20 44 0a 2a 2a 20 20 20 20 20 20 20 20 20  n] D.**         
17ed0 20 74 6f 20 74 68 65 20 6c 65 73 73 6f 72 20 6f   to the lessor o
17ee0 66 20 56 20 61 6e 64 20 74 68 65 20 68 61 72 64  f V and the hard
17ef0 20 75 70 70 65 72 20 62 6f 75 6e 64 20 6f 6e 20   upper bound on 
17f00 74 68 65 20 73 69 7a 65 0a 2a 2a 20 20 20 20 20  the size.**     
17f10 20 20 20 20 20 6f 66 20 43 20 74 68 61 74 20 69       of C that i
17f20 73 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65  s set at compile
17f30 2d 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  -time..**.** {F1
17f40 32 37 36 36 7d 20 41 20 73 75 63 63 65 73 73 66  2766} A successf
17f50 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ul call to [sqli
17f60 74 65 33 5f 6c 69 6d 69 74 28 44 2c 43 2c 56 29  te3_limit(D,C,V)
17f70 5d 20 77 68 65 72 65 20 56 20 69 73 20 6e 65 67  ] where V is neg
17f80 61 74 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20  ative.**        
17f90 20 20 6c 65 61 76 65 73 20 74 68 65 20 73 74 61    leaves the sta
17fa0 74 65 20 6f 66 20 5b 64 61 74 61 62 61 73 65 20  te of [database 
17fb0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 75 6e  connection] D un
17fc0 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b  changed..**.** {
17fd0 46 31 32 37 36 39 7d 20 41 20 73 75 63 63 65 73  F12769} A succes
17fe0 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71  sful call to [sq
17ff0 6c 69 74 65 33 5f 6c 69 6d 69 74 28 44 2c 43 2c  lite3_limit(D,C,
18000 56 29 5d 20 72 65 74 75 72 6e 73 20 74 68 65 0a  V)] returns the.
18010 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c 75  **          valu
18020 65 20 6f 66 20 74 68 65 20 6c 69 6d 69 74 20 6f  e of the limit o
18030 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 63 6f  n the size of co
18040 6e 73 74 72 75 63 74 20 43 20 69 6e 0a 2a 2a 20  nstruct C in.** 
18050 20 20 20 20 20 20 20 20 20 69 6e 20 5b 64 61 74           in [dat
18060 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
18070 5d 20 44 20 61 73 20 69 74 20 77 61 73 20 70 72  ] D as it was pr
18080 69 6f 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 2e  ior to the call.
18090 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
180a0 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c 20  limit(sqlite3*, 
180b0 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 56  int id, int newV
180c0 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  al);../*.** CAPI
180d0 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c  3REF: Run-Time L
180e0 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73 20  imit Categories 
180f0 7b 46 31 32 37 39 30 7d 0a 2a 2a 20 4b 45 59 57  {F12790}.** KEYW
18100 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74  ORDS: {limit cat
18110 65 67 6f 72 79 7d 20 7b 6c 69 6d 69 74 20 63 61  egory} {limit ca
18120 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 20 0a 2a 2a  tegories}.** .**
18130 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
18140 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20   define various 
18150 61 73 70 65 63 74 73 20 6f 66 20 61 20 5b 64 61  aspects of a [da
18160 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
18170 6e 5d 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62  n].** that can b
18180 65 20 6c 69 6d 69 74 65 64 20 69 6e 20 73 69 7a  e limited in siz
18190 65 20 62 79 20 63 61 6c 6c 73 20 74 6f 20 5b 73  e by calls to [s
181a0 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e  qlite3_limit()].
181b0 0a 2a 2a 20 54 68 65 20 6d 65 61 6e 69 6e 67 73  .** The meanings
181c0 20 6f 66 20 74 68 65 20 76 61 72 69 6f 75 73 20   of the various 
181d0 6c 69 6d 69 74 73 20 61 72 65 20 61 73 20 66 6f  limits are as fo
181e0 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 64 6c  llows:.**.** <dl
181f0 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  >.** <dt>SQLITE_
18200 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74  LIMIT_LENGTH</dt
18210 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
18220 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79  imum size of any
18230 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20 62 6c  .** string or bl
18240 6f 62 20 6f 72 20 74 61 62 6c 65 20 72 6f 77 2e  ob or table row.
18250 3c 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  <dd>.**.** <dt>S
18260 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f  QLITE_LIMIT_SQL_
18270 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  LENGTH</dt>.** <
18280 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c  dd>The maximum l
18290 65 6e 67 74 68 20 6f 66 20 61 6e 20 53 51 4c 20  ength of an SQL 
182a0 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 0a  statement.</dd>.
182b0 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
182c0 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64  _LIMIT_COLUMN</d
182d0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
182e0 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
182f0 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61 62  columns in a tab
18300 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72  le definition or
18310 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c   in the.** resul
18320 74 20 73 65 74 20 6f 66 20 61 20 53 45 4c 45 43  t set of a SELEC
18330 54 20 6f 72 20 74 68 65 20 6d 61 78 69 6d 75 6d  T or the maximum
18340 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
18350 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a  ns in an index.*
18360 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45 52  * or in an ORDER
18370 20 42 59 20 6f 72 20 47 52 4f 55 50 20 42 59 20   BY or GROUP BY 
18380 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a  clause.</dd>.**.
18390 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49  ** <dt>SQLITE_LI
183a0 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f  MIT_EXPR_DEPTH</
183b0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
183c0 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20  aximum depth of 
183d0 74 68 65 20 70 61 72 73 65 20 74 72 65 65 20 6f  the parse tree o
183e0 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69 6f 6e  n any expression
183f0 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
18400 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f  >SQLITE_LIMIT_CO
18410 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64  MPOUND_SELECT</d
18420 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
18430 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
18440 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f  terms in a compo
18450 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61 74 65  und SELECT state
18460 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ment.</dd>.**.**
18470 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49   <dt>SQLITE_LIMI
18480 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a  T_VDBE_OP</dt>.*
18490 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
184a0 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73 74  m number of inst
184b0 72 75 63 74 69 6f 6e 73 20 69 6e 20 61 20 76 69  ructions in a vi
184c0 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 70 72  rtual machine pr
184d0 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f  ogram.** used to
184e0 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51   implement an SQ
184f0 4c 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64  L statement.</dd
18500 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
18510 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f  TE_LIMIT_FUNCTIO
18520 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  N_ARG</dt>.** <d
18530 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
18540 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
18550 73 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e  s on a function.
18560 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
18570 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54  SQLITE_LIMIT_ATT
18580 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ACHED</dt>.** <d
18590 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
185a0 6d 62 65 72 20 6f 66 20 61 74 74 61 63 68 65 64  mber of attached
185b0 20 64 61 74 61 62 61 73 65 73 2e 3c 2f 64 64 3e   databases.</dd>
185c0 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
185d0 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54  E_LIMIT_LIKE_PAT
185e0 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e  TERN_LENGTH</dt>
185f0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
18600 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74 68  mum length of th
18610 65 20 70 61 74 74 65 72 6e 20 61 72 67 75 6d 65  e pattern argume
18620 6e 74 20 74 6f 20 74 68 65 20 4c 49 4b 45 20 6f  nt to the LIKE o
18630 72 0a 2a 2a 20 47 4c 4f 42 20 6f 70 65 72 61 74  r.** GLOB operat
18640 6f 72 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ors.</dd>.**.** 
18650 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
18660 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52  _VARIABLE_NUMBER
18670 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
18680 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
18690 6f 66 20 76 61 72 69 61 62 6c 65 73 20 69 6e 20  of variables in 
186a0 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
186b0 20 74 68 61 74 20 63 61 6e 0a 2a 2a 20 62 65 20   that can.** be 
186c0 62 6f 75 6e 64 2e 3c 2f 64 64 3e 0a 2a 2a 20 3c  bound.</dd>.** <
186d0 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  /dl>.*/.#define 
186e0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e  SQLITE_LIMIT_LEN
186f0 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20  GTH             
18700 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65         0.#define
18710 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51   SQLITE_LIMIT_SQ
18720 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20  L_LENGTH        
18730 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e          1.#defin
18740 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  e SQLITE_LIMIT_C
18750 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 20 20  OLUMN           
18760 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69           2.#defi
18770 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
18780 45 58 50 52 5f 44 45 50 54 48 20 20 20 20 20 20  EXPR_DEPTH      
18790 20 20 20 20 20 20 20 20 20 20 33 0a 23 64 65 66            3.#def
187a0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
187b0 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54  _COMPOUND_SELECT
187c0 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65             4.#de
187d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
187e0 54 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 20 20  T_VDBE_OP       
187f0 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64              5.#d
18800 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
18810 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20  IT_FUNCTION_ARG 
18820 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23               6.#
18830 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
18840 4d 49 54 5f 41 54 54 41 43 48 45 44 20 20 20 20  MIT_ATTACHED    
18850 20 20 20 20 20 20 20 20 20 20 20 20 20 20 37 0a                7.
18860 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
18870 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52  IMIT_LIKE_PATTER
18880 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 38  N_LENGTH       8
18890 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
188a0 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e  LIMIT_VARIABLE_N
188b0 55 4d 42 45 52 20 20 20 20 20 20 20 20 20 20 20  UMBER           
188c0 39 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  9../*.** CAPI3RE
188d0 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20  F: Compiling An 
188e0 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 7b 46  SQL Statement {F
188f0 31 33 30 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20  13010}.**.** To 
18900 65 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20 71  execute an SQL q
18910 75 65 72 79 2c 20 69 74 20 6d 75 73 74 20 66 69  uery, it must fi
18920 72 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20  rst be compiled 
18930 69 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65  into a byte-code
18940 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e  .** program usin
18950 67 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72  g one of these r
18960 6f 75 74 69 6e 65 73 2e 20 0a 2a 2a 0a 2a 2a 20  outines. .**.** 
18970 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
18980 6e 74 20 22 64 62 22 20 69 73 20 61 6e 20 5b 64  nt "db" is an [d
18990 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
189a0 6f 6e 5d 20 0a 2a 2a 20 6f 62 74 61 69 6e 65 64  on] .** obtained
189b0 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 20 63 61   from a prior ca
189c0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f  ll to [sqlite3_o
189d0 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  pen()], [sqlite3
189e0 5f 6f 70 65 6e 5f 76 32 28 29 5d 0a 2a 2a 20 6f  _open_v2()].** o
189f0 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  r [sqlite3_open1
18a00 36 28 29 5d 2e 20 0a 2a 2a 20 54 68 65 20 73 65  6()]. .** The se
18a10 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 22 7a  cond argument "z
18a20 53 71 6c 22 20 69 73 20 74 68 65 20 73 74 61 74  Sql" is the stat
18a30 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70  ement to be comp
18a40 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a  iled, encoded.**
18a50 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38   as either UTF-8
18a60 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65   or UTF-16.  The
18a70 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
18a80 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  () and sqlite3_p
18a90 72 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69  repare_v2().** i
18aa0 6e 74 65 72 66 61 63 65 73 20 75 73 65 73 20 55  nterfaces uses U
18ab0 54 46 2d 38 20 61 6e 64 20 73 71 6c 69 74 65 33  TF-8 and sqlite3
18ac0 5f 70 72 65 70 61 72 65 31 36 28 29 20 61 6e 64  _prepare16() and
18ad0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
18ae0 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20 55  16_v2().** use U
18af0 54 46 2d 31 36 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a  TF-16. {END}.**.
18b00 2a 2a 20 49 66 20 74 68 65 20 6e 42 79 74 65 20  ** If the nByte 
18b10 61 72 67 75 6d 65 6e 74 20 69 73 20 6c 65 73 73  argument is less
18b20 0a 2a 2a 20 74 68 61 6e 20 7a 65 72 6f 2c 20 74  .** than zero, t
18b30 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 64  hen zSql is read
18b40 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74   up to the first
18b50 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
18b60 2e 0a 2a 2a 20 49 66 20 6e 42 79 74 65 20 69 73  ..** If nByte is
18b70 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74   non-negative, t
18b80 68 65 6e 20 69 74 20 69 73 20 74 68 65 20 6d 61  hen it is the ma
18b90 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
18ba0 0a 2a 2a 20 62 79 74 65 73 20 72 65 61 64 20 66  .** bytes read f
18bb0 72 6f 6d 20 7a 53 71 6c 2e 20 20 57 68 65 6e 20  rom zSql.  When 
18bc0 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67  nByte is non-neg
18bd0 61 74 69 76 65 2c 20 74 68 65 0a 2a 2a 20 7a 53  ative, the.** zS
18be0 71 6c 20 73 74 72 69 6e 67 20 65 6e 64 73 20 61  ql string ends a
18bf0 74 20 65 69 74 68 65 72 20 74 68 65 20 66 69 72  t either the fir
18c00 73 74 20 27 5c 30 30 30 27 20 6f 72 20 27 5c 75  st '\000' or '\u
18c10 30 30 30 30 27 20 63 68 61 72 61 63 74 65 72 20  0000' character 
18c20 6f 72 20 0a 2a 2a 20 74 68 65 20 6e 42 79 74 65  or .** the nByte
18c30 2d 74 68 20 62 79 74 65 2c 20 77 68 69 63 68 65  -th byte, whiche
18c40 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e  ver comes first.
18c50 20 49 66 20 74 68 65 20 63 61 6c 6c 65 72 20 6b   If the caller k
18c60 6e 6f 77 73 0a 2a 2a 20 74 68 61 74 20 74 68 65  nows.** that the
18c70 20 73 75 70 70 6c 69 65 64 20 73 74 72 69 6e 67   supplied string
18c80 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74   is nul-terminat
18c90 65 64 2c 20 74 68 65 6e 20 74 68 65 72 65 20 69  ed, then there i
18ca0 73 20 61 20 73 6d 61 6c 6c 0a 2a 2a 20 70 65 72  s a small.** per
18cb0 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e 74 61  formance advanta
18cc0 67 65 20 74 6f 20 62 65 20 68 61 64 20 62 79 20  ge to be had by 
18cd0 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 74 65  passing an nByte
18ce0 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 20   parameter that 
18cf0 0a 2a 2a 20 69 73 20 65 71 75 61 6c 20 74 6f 20  .** is equal to 
18d00 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
18d10 74 65 73 20 69 6e 20 74 68 65 20 69 6e 70 75 74  tes in the input
18d20 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75   string <i>inclu
18d30 64 69 6e 67 3c 2f 69 3e 20 0a 2a 2a 20 74 68 65  ding</i> .** the
18d40 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 20   nul-terminator 
18d50 62 79 74 65 73 2e 7b 45 4e 44 7d 0a 2a 2a 0a 2a  bytes.{END}.**.*
18d60 2a 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64  * *pzTail is mad
18d70 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68  e to point to th
18d80 65 20 66 69 72 73 74 20 62 79 74 65 20 70 61 73  e first byte pas
18d90 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65  t the end of the
18da0 0a 2a 2a 20 66 69 72 73 74 20 53 51 4c 20 73 74  .** first SQL st
18db0 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e  atement in zSql.
18dc0 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73    These routines
18dd0 20 6f 6e 6c 79 20 63 6f 6d 70 69 6c 65 73 20 74   only compiles t
18de0 68 65 20 66 69 72 73 74 0a 2a 2a 20 73 74 61 74  he first.** stat
18df0 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73  ement in zSql, s
18e00 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65 66  o *pzTail is lef
18e10 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 77 68  t pointing to wh
18e20 61 74 20 72 65 6d 61 69 6e 73 0a 2a 2a 20 75 6e  at remains.** un
18e30 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20  compiled..**.** 
18e40 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66 74 20  *ppStmt is left 
18e50 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f  pointing to a co
18e60 6d 70 69 6c 65 64 20 5b 70 72 65 70 61 72 65 64  mpiled [prepared
18e70 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
18e80 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75   can be.** execu
18e90 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ted using [sqlit
18ea0 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 4f 72 20  e3_step()].  Or 
18eb0 69 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 65  if there is an e
18ec0 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69 73  rror, *ppStmt is
18ed0 0a 2a 2a 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e  .** set to NULL.
18ee0 20 20 49 66 20 74 68 65 20 69 6e 70 75 74 20 74    If the input t
18ef0 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20  ext contains no 
18f00 53 51 4c 20 28 69 66 20 74 68 65 20 69 6e 70 75  SQL (if the inpu
18f10 74 0a 2a 2a 20 69 73 20 61 6e 64 20 65 6d 70 74  t.** is and empt
18f20 79 20 73 74 72 69 6e 67 20 6f 72 20 61 20 63 6f  y string or a co
18f30 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70 70 53  mment) then *ppS
18f40 74 6d 74 20 69 73 20 73 65 74 20 74 6f 20 4e 55  tmt is set to NU
18f50 4c 4c 2e 0a 2a 2a 20 7b 55 31 33 30 31 38 7d 20  LL..** {U13018} 
18f60 54 68 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63  The calling proc
18f70 65 64 75 72 65 20 69 73 20 72 65 73 70 6f 6e 73  edure is respons
18f80 69 62 6c 65 20 66 6f 72 20 64 65 6c 65 74 69 6e  ible for deletin
18f90 67 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65  g the.** compile
18fa0 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a  d SQL statement.
18fb0 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ** using [sqlite
18fc0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66  3_finalize()] af
18fd0 74 65 72 20 69 74 20 68 61 73 20 66 69 6e 69 73  ter it has finis
18fe0 68 65 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 0a  hed with it..**.
18ff0 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73 2c 20 5b  ** On success, [
19000 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65  SQLITE_OK] is re
19010 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69  turned.  Otherwi
19020 73 65 20 61 6e 20 0a 2a 2a 20 5b 65 72 72 6f 72  se an .** [error
19030 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e   code] is return
19040 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ed..**.** The sq
19050 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
19060 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  () and sqlite3_p
19070 72 65 70 61 72 65 31 36 5f 76 32 28 29 20 69 6e  repare16_v2() in
19080 74 65 72 66 61 63 65 73 20 61 72 65 0a 2a 2a 20  terfaces are.** 
19090 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20  recommended for 
190a0 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73  all new programs
190b0 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64 65 72 20  . The two older 
190c0 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 72  interfaces are r
190d0 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62  etained.** for b
190e0 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
190f0 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68 65 69  bility, but thei
19100 72 20 75 73 65 20 69 73 20 64 69 73 63 6f 75 72  r use is discour
19110 61 67 65 64 2e 0a 2a 2a 20 49 6e 20 74 68 65 20  aged..** In the 
19120 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 73 2c  "v2" interfaces,
19130 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
19140 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20  atement.** that 
19150 69 73 20 72 65 74 75 72 6e 65 64 20 28 74 68 65  is returned (the
19160 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20   [sqlite3_stmt] 
19170 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e 73  object) contains
19180 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 0a   a copy of the .
19190 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20  ** original SQL 
191a0 74 65 78 74 2e 20 7b 45 4e 44 7d 20 54 68 69 73  text. {END} This
191b0 20 63 61 75 73 65 73 20 74 68 65 20 5b 73 71 6c   causes the [sql
191c0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e 74  ite3_step()] int
191d0 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68  erface to.** beh
191e0 61 76 65 20 61 20 64 69 66 66 65 72 65 6e 74 6c  ave a differentl
191f0 79 20 69 6e 20 74 77 6f 20 77 61 79 73 3a 0a 2a  y in two ways:.*
19200 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ol>.** <li
19210 3e 0a 2a 2a 20 49 66 20 74 68 65 20 64 61 74 61  >.** If the data
19220 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e  base schema chan
19230 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66 20  ges, instead of 
19240 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54  returning [SQLIT
19250 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74 0a  E_SCHEMA] as it.
19260 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20 74  ** always used t
19270 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73  o do, [sqlite3_s
19280 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f  tep()] will auto
19290 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70  matically recomp
192a0 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73  ile the SQL.** s
192b0 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72 79  tatement and try
192c0 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69 6e   to run it again
192d0 2e 20 20 49 66 20 74 68 65 20 73 63 68 65 6d 61  .  If the schema
192e0 20 68 61 73 20 63 68 61 6e 67 65 64 20 69 6e 0a   has changed in.
192f0 2a 2a 20 61 20 77 61 79 20 74 68 61 74 20 6d 61  ** a way that ma
19300 6b 65 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e  kes the statemen
19310 74 20 6e 6f 20 6c 6f 6e 67 65 72 20 76 61 6c 69  t no longer vali
19320 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  d, [sqlite3_step
19330 28 29 5d 20 77 69 6c 6c 20 73 74 69 6c 6c 0a 2a  ()] will still.*
19340 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  * return [SQLITE
19350 5f 53 43 48 45 4d 41 5d 2e 20 20 42 75 74 20 75  _SCHEMA].  But u
19360 6e 6c 69 6b 65 20 74 68 65 20 6c 65 67 61 63 79  nlike the legacy
19370 20 62 65 68 61 76 69 6f 72 2c 20 0a 2a 2a 20 5b   behavior, .** [
19380 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 69  SQLITE_SCHEMA] i
19390 73 20 6e 6f 77 20 61 20 66 61 74 61 6c 20 65 72  s now a fatal er
193a0 72 6f 72 2e 20 20 43 61 6c 6c 69 6e 67 0a 2a 2a  ror.  Calling.**
193b0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
193c0 65 5f 76 32 28 29 5d 20 61 67 61 69 6e 20 77 69  e_v2()] again wi
193d0 6c 6c 20 6e 6f 74 20 6d 61 6b 65 20 74 68 65 0a  ll not make the.
193e0 2a 2a 20 65 72 72 6f 72 20 67 6f 20 61 77 61 79  ** error go away
193f0 2e 20 20 4e 6f 74 65 3a 20 75 73 65 20 5b 73 71  .  Note: use [sq
19400 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20  lite3_errmsg()] 
19410 74 6f 20 66 69 6e 64 20 74 68 65 20 74 65 78 74  to find the text
19420 0a 2a 2a 20 6f 66 20 74 68 65 20 70 61 72 73 69  .** of the parsi
19430 6e 67 20 65 72 72 6f 72 20 74 68 61 74 20 72 65  ng error that re
19440 73 75 6c 74 73 20 69 6e 20 61 6e 20 5b 53 51 4c  sults in an [SQL
19450 49 54 45 5f 53 43 48 45 4d 41 5d 20 72 65 74 75  ITE_SCHEMA] retu
19460 72 6e 2e 20 7b 45 4e 44 7d 0a 2a 2a 20 3c 2f 6c  rn. {END}.** </l
19470 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a  i>.**.** <li>.**
19480 20 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f   When an error o
19490 63 63 75 72 73 2c 20 0a 2a 2a 20 5b 73 71 6c 69  ccurs, .** [sqli
194a0 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c  te3_step()] will
194b0 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74   return one of t
194c0 68 65 20 64 65 74 61 69 6c 65 64 20 0a 2a 2a 20  he detailed .** 
194d0 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72  [error codes] or
194e0 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72   [extended error
194f0 20 63 6f 64 65 73 5d 2e 20 0a 2a 2a 20 54 68 65   codes]. .** The
19500 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72   legacy behavior
19510 20 77 61 73 20 74 68 61 74 20 5b 73 71 6c 69 74   was that [sqlit
19520 65 33 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c 64  e3_step()] would
19530 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61 20 67   only return a g
19540 65 6e 65 72 69 63 0a 2a 2a 20 5b 53 51 4c 49 54  eneric.** [SQLIT
19550 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c 74 20  E_ERROR] result 
19560 63 6f 64 65 20 61 6e 64 20 79 6f 75 20 77 6f 75  code and you wou
19570 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b 65 20  ld have to make 
19580 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f  a second call to
19590 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
195a0 65 74 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74  et()] in order t
195b0 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64 65 72  o find the under
195c0 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66 20 74  lying cause of t
195d0 68 65 20 70 72 6f 62 6c 65 6d 2e 0a 2a 2a 20 57  he problem..** W
195e0 69 74 68 20 74 68 65 20 22 76 32 22 20 70 72 65  ith the "v2" pre
195f0 70 61 72 65 20 69 6e 74 65 72 66 61 63 65 73 2c  pare interfaces,
19600 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20   the underlying 
19610 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65 20 65  reason for the e
19620 72 72 6f 72 20 69 73 0a 2a 2a 20 72 65 74 75 72  rror is.** retur
19630 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e  ned immediately.
19640 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f  .** </li>.** </o
19650 6c 3e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  l>.**.** INVARIA
19660 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 30  NTS:.**.** {F130
19670 31 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  11} The [sqlite3
19680 5f 70 72 65 70 61 72 65 28 64 62 2c 7a 53 71 6c  _prepare(db,zSql
19690 2c 2e 2e 2e 29 5d 20 61 6e 64 0a 2a 2a 20 20 20  ,...)] and.**   
196a0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
196b0 70 72 65 70 61 72 65 5f 76 32 28 64 62 2c 7a 53  prepare_v2(db,zS
196c0 71 6c 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61  ql,...)] interfa
196d0 63 65 73 20 69 6e 74 65 72 70 72 65 74 20 74 68  ces interpret th
196e0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 65  e.**          te
196f0 78 74 20 69 6e 20 74 68 65 69 72 20 7a 53 71 6c  xt in their zSql
19700 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 55 54   parameter as UT
19710 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 30  F-8..**.** {F130
19720 31 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  12} The [sqlite3
19730 5f 70 72 65 70 61 72 65 31 36 28 64 62 2c 7a 53  _prepare16(db,zS
19740 71 6c 2c 2e 2e 2e 29 5d 20 61 6e 64 0a 2a 2a 20  ql,...)] and.** 
19750 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
19760 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 64  3_prepare16_v2(d
19770 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 69 6e 74  b,zSql,...)] int
19780 65 72 66 61 63 65 73 20 69 6e 74 65 72 70 72 65  erfaces interpre
19790 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  t the.**        
197a0 20 20 74 65 78 74 20 69 6e 20 74 68 65 69 72 20    text in their 
197b0 7a 53 71 6c 20 70 61 72 61 6d 65 74 65 72 20 61  zSql parameter a
197c0 73 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20  s UTF-16 in the 
197d0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
197e0 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 30 31 33  r..**.** {F13013
197f0 7d 20 49 66 20 74 68 65 20 6e 42 79 74 65 20 61  } If the nByte a
19800 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69  rgument to [sqli
19810 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 64  te3_prepare_v2(d
19820 62 2c 7a 53 71 6c 2c 6e 42 79 74 65 2c 2e 2e 2e  b,zSql,nByte,...
19830 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  )].**          a
19840 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 20  nd its variants 
19850 69 73 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72  is less than zer
19860 6f 2c 20 74 68 65 6e 20 53 51 4c 20 74 65 78 74  o, then SQL text
19870 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   is.**          
19880 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 20 69  read from zSql i
19890 73 20 72 65 61 64 20 75 70 20 74 6f 20 74 68 65  s read up to the
198a0 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d   first zero term
198b0 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46  inator..**.** {F
198c0 31 33 30 31 34 7d 20 49 66 20 74 68 65 20 6e 42  13014} If the nB
198d0 79 74 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  yte argument to 
198e0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
198f0 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 6e 42 79 74  _v2(db,zSql,nByt
19900 65 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20  e,...)].**      
19910 20 20 20 20 61 6e 64 20 69 74 73 20 76 61 72 69      and its vari
19920 61 6e 74 73 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  ants is non-nega
19930 74 69 76 65 2c 20 74 68 65 6e 20 61 74 20 6d 6f  tive, then at mo
19940 73 74 20 6e 42 79 74 65 73 20 62 79 74 65 73 0a  st nBytes bytes.
19950 2a 2a 20 20 20 20 20 20 20 20 20 20 53 51 4c 20  **          SQL 
19960 74 65 78 74 20 69 73 20 72 65 61 64 20 66 72 6f  text is read fro
19970 6d 20 7a 53 71 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 46  m zSql..**.** {F
19980 31 33 30 31 35 7d 20 49 6e 20 5b 73 71 6c 69 74  13015} In [sqlit
19990 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 64 62  e3_prepare_v2(db
199a0 2c 7a 53 71 6c 2c 4e 2c 50 2c 70 7a 54 61 69 6c  ,zSql,N,P,pzTail
199b0 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69 61  )] and its varia
199c0 6e 74 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  nts.**          
199d0 69 66 20 74 68 65 20 7a 53 71 6c 20 69 6e 70 75  if the zSql inpu
199e0 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20  t text contains 
199f0 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 53 51  more than one SQ
19a00 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 20  L statement.**  
19a10 20 20 20 20 20 20 20 20 61 6e 64 20 70 7a 54 61          and pzTa
19a20 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20  il is not NULL, 
19a30 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20  then *pzTail is 
19a40 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f  made to point to
19a50 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
19a60 20 66 69 72 73 74 20 62 79 74 65 20 70 61 73 74   first byte past
19a70 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20   the end of the 
19a80 66 69 72 73 74 20 53 51 4c 20 73 74 61 74 65 6d  first SQL statem
19a90 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 0a 2a 2a 20  ent in zSql..** 
19aa0 20 20 20 20 20 20 20 20 20 3c 74 6f 64 6f 3e 57           <todo>W
19ab0 68 61 74 20 64 6f 65 73 20 2a 70 7a 54 61 69 6c  hat does *pzTail
19ac0 20 70 6f 69 6e 74 20 74 6f 20 69 66 20 74 68 65   point to if the
19ad0 72 65 20 69 73 20 6f 6e 65 20 73 74 61 74 65 6d  re is one statem
19ae0 65 6e 74 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a  ent?</todo>.**.*
19af0 2a 20 7b 46 31 33 30 31 36 7d 20 41 20 73 75 63  * {F13016} A suc
19b00 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
19b10 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
19b20 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 4e 2c 70 70  _v2(db,zSql,N,pp
19b30 53 74 6d 74 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20  Stmt,...)].**   
19b40 20 20 20 20 20 20 20 6f 72 20 6f 6e 65 20 6f 66         or one of
19b50 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 77 72   its variants wr
19b60 69 74 65 73 20 69 6e 74 6f 20 2a 70 70 53 74 6d  ites into *ppStm
19b70 74 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  t a pointer to a
19b80 20 6e 65 77 0a 2a 2a 20 20 20 20 20 20 20 20 20   new.**         
19b90 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
19ba0 6d 65 6e 74 5d 20 6f 72 20 61 20 70 6f 69 6e 74  ment] or a point
19bb0 65 72 20 74 6f 20 4e 55 4c 4c 0a 2a 2a 20 20 20  er to NULL.**   
19bc0 20 20 20 20 20 20 20 69 66 20 7a 53 71 6c 20 63         if zSql c
19bd0 6f 6e 74 61 69 6e 73 20 6e 6f 74 68 69 6e 67 20  ontains nothing 
19be0 6f 74 68 65 72 20 74 68 61 6e 20 77 68 69 74 65  other than white
19bf0 73 70 61 63 65 20 6f 72 20 63 6f 6d 6d 65 6e 74  space or comment
19c00 73 2e 20 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 30 31  s. .**.** {F1301
19c10 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  9} The [sqlite3_
19c20 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69 6e  prepare_v2()] in
19c30 74 65 72 66 61 63 65 20 61 6e 64 20 69 74 73 20  terface and its 
19c40 76 61 72 69 61 6e 74 73 20 72 65 74 75 72 6e 0a  variants return.
19c50 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c  **          [SQL
19c60 49 54 45 5f 4f 4b 5d 20 6f 72 20 61 6e 20 61 70  ITE_OK] or an ap
19c70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72  propriate [error
19c80 20 63 6f 64 65 5d 20 75 70 6f 6e 20 66 61 69 6c   code] upon fail
19c90 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 30  ure..**.** {F130
19ca0 32 31 7d 20 42 65 66 6f 72 65 20 5b 73 71 6c 69  21} Before [sqli
19cb0 74 65 33 5f 70 72 65 70 61 72 65 28 64 62 2c 7a  te3_prepare(db,z
19cc0 53 71 6c 2c 6e 42 79 74 65 2c 70 70 53 74 6d 74  Sql,nByte,ppStmt
19cd0 2c 70 7a 54 61 69 6c 29 5d 20 6f 72 20 69 74 73  ,pzTail)] or its
19ce0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61 72  .**          var
19cf0 69 61 6e 74 73 20 72 65 74 75 72 6e 73 20 61 6e  iants returns an
19d00 20 65 72 72 6f 72 20 28 61 6e 79 20 76 61 6c 75   error (any valu
19d10 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  e other than [SQ
19d20 4c 49 54 45 5f 4f 4b 5d 29 0a 2a 2a 20 20 20 20  LITE_OK]).**    
19d30 20 20 20 20 20 20 69 74 20 66 69 72 73 74 20 73        it first s
19d40 65 74 73 20 2a 70 70 53 74 6d 74 20 74 6f 20 4e  ets *ppStmt to N
19d50 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ULL..*/.int sqli
19d60 74 65 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73  te3_prepare(.  s
19d70 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
19d80 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
19d90 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
19da0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c  onst char *zSql,
19db0 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
19dc0 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65  atement, UTF-8 e
19dd0 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
19de0 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
19df0 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
19e00 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
19e10 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
19e20 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
19e30 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
19e40 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
19e50 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a  .  const char **
19e60 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
19e70 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
19e80 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
19e90 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  zSql */.);.int s
19ea0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
19eb0 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  2(.  sqlite3 *db
19ec0 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
19ed0 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
19ee0 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
19ef0 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
19f00 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
19f10 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  TF-8 encoded */.
19f20 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
19f30 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
19f40 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
19f50 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
19f60 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
19f70 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
19f80 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
19f90 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
19fa0 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  har **pzTail    
19fb0 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
19fc0 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
19fd0 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
19fe0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65  .int sqlite3_pre
19ff0 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65  pare16(.  sqlite
1a000 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
1a010 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
1a020 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
1a030 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20  void *zSql,     
1a040 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
1a050 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64  nt, UTF-16 encod
1a060 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
1a070 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
1a080 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
1a090 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
1a0a0 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
1a0b0 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
1a0c0 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
1a0d0 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
1a0e0 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61  onst void **pzTa
1a0f0 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
1a100 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
1a110 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
1a120 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
1a130 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
1a140 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
1a150 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
1a160 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
1a170 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a  .  const void *z
1a180 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
1a190 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
1a1a0 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  -16 encoded */. 
1a1b0 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
1a1c0 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
1a1d0 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
1a1e0 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
1a1f0 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
1a200 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
1a210 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
1a220 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
1a230 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  id **pzTail     
1a240 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
1a250 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
1a260 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
1a270 0a 2f 2a 0a 2a 2a 20 43 41 50 49 52 45 46 3a 20  ./*.** CAPIREF: 
1a280 52 65 74 72 69 65 76 69 6e 67 20 53 74 61 74 65  Retrieving State
1a290 6d 65 6e 74 20 53 51 4c 20 7b 46 31 33 31 30 30  ment SQL {F13100
1a2a0 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  }.**.** This int
1a2b0 65 72 65 66 61 63 65 20 63 61 6e 20 62 65 20 75  ereface can be u
1a2c0 73 65 64 20 74 6f 20 72 65 74 72 69 65 76 65 20  sed to retrieve 
1a2d0 61 20 73 61 76 65 64 20 63 6f 70 79 20 6f 66 20  a saved copy of 
1a2e0 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20  the original.** 
1a2f0 53 51 4c 20 74 65 78 74 20 75 73 65 64 20 74 6f  SQL text used to
1a300 20 63 72 65 61 74 65 20 61 20 5b 70 72 65 70 61   create a [prepa
1a310 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
1a320 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
1a330 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 31 30 31 7d  :.**.** {F13101}
1a340 20 49 66 20 74 68 65 20 5b 70 72 65 70 61 72 65   If the [prepare
1a350 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 70 61 73  d statement] pas
1a360 73 65 64 20 61 73 20 0a 2a 2a 20 20 20 20 20 20  sed as .**      
1a370 20 20 20 20 74 68 65 20 61 6e 20 61 72 67 75 6d      the an argum
1a380 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ent to [sqlite3_
1a390 73 71 6c 28 29 5d 20 77 61 73 20 63 6f 6d 70 69  sql()] was compi
1a3a0 6c 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  led.**          
1a3b0 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20 65  compiled using e
1a3c0 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70  ither [sqlite3_p
1a3d0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 0a  repare_v2()] or.
1a3e0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
1a3f0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
1a400 32 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  2()],.**        
1a410 20 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f    then [sqlite3_
1a420 73 71 6c 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20  sql()] function 
1a430 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
1a440 72 20 74 6f 20 61 0a 2a 2a 20 20 20 20 20 20 20  r to a.**       
1a450 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74     zero-terminat
1a460 65 64 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69  ed string contai
1a470 6e 69 6e 67 20 61 20 55 54 46 2d 38 20 72 65 6e  ning a UTF-8 ren
1a480 64 65 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20  dering.**       
1a490 20 20 20 6f 66 20 74 68 65 20 6f 72 69 67 69 6e     of the origin
1a4a0 61 6c 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  al SQL statement
1a4b0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 31 30 32 7d  ..**.** {F13102}
1a4c0 20 49 66 20 74 68 65 20 5b 70 72 65 70 61 72 65   If the [prepare
1a4d0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 70 61 73  d statement] pas
1a4e0 73 65 64 20 61 73 20 0a 2a 2a 20 20 20 20 20 20  sed as .**      
1a4f0 20 20 20 20 74 68 65 20 61 6e 20 61 72 67 75 6d      the an argum
1a500 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ent to [sqlite3_
1a510 73 71 6c 28 29 5d 20 77 61 73 20 63 6f 6d 70 69  sql()] was compi
1a520 6c 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  led.**          
1a530 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20 65  compiled using e
1a540 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70  ither [sqlite3_p
1a550 72 65 70 61 72 65 28 29 5d 20 6f 72 0a 2a 2a 20  repare()] or.** 
1a560 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
1a570 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c 0a  3_prepare16()],.
1a580 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e  **          then
1a590 20 5b 73 71 6c 69 74 65 33 5f 73 71 6c 28 29 5d   [sqlite3_sql()]
1a5a0 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
1a5b0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
1a5c0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 31 30 33 7d  ..**.** {F13103}
1a5d0 20 54 68 65 20 73 74 72 69 6e 67 20 72 65 74 75   The string retu
1a5e0 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
1a5f0 5f 73 71 6c 28 53 29 5d 20 69 73 20 76 61 6c 69  _sql(S)] is vali
1a600 64 20 75 6e 74 69 6c 20 74 68 65 0a 2a 2a 20 20  d until the.**  
1a610 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65          [prepare
1a620 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69  d statement] S i
1a630 73 20 64 65 6c 65 74 65 64 20 75 73 69 6e 67 20  s deleted using 
1a640 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
1a650 65 28 53 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  e(S)]..*/.const 
1a660 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 71  char *sqlite3_sq
1a670 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  l(sqlite3_stmt *
1a680 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
1a690 41 50 49 33 52 45 46 3a 20 20 44 79 6e 61 6d 69  API3REF:  Dynami
1a6a0 63 61 6c 6c 79 20 54 79 70 65 64 20 56 61 6c 75  cally Typed Valu
1a6b0 65 20 4f 62 6a 65 63 74 20 20 7b 46 31 35 30 30  e Object  {F1500
1a6c0 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  0}.** KEYWORDS: 
1a6d0 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  {protected sqlit
1a6e0 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f  e3_value} {unpro
1a6f0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
1a700 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  alue}.**.** SQLi
1a710 74 65 20 75 73 65 73 20 74 68 65 20 73 71 6c 69  te uses the sqli
1a720 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
1a730 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c   to represent al
1a740 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74  l values.** that
1a750 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69   can be stored i
1a760 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62  n a database tab
1a770 6c 65 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73  le..** SQLite us
1a780 65 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e  es dynamic typin
1a790 67 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73  g for the values
1a7a0 20 69 74 20 73 74 6f 72 65 73 2e 20 20 0a 2a 2a   it stores.  .**
1a7b0 20 56 61 6c 75 65 73 20 73 74 6f 72 65 64 20 69   Values stored i
1a7c0 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  n sqlite3_value 
1a7d0 6f 62 6a 65 63 74 73 20 63 61 6e 20 62 65 0a 2a  objects can be.*
1a7e0 2a 20 62 65 20 69 6e 74 65 67 65 72 73 2c 20 66  * be integers, f
1a7f0 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61  loating point va
1a800 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 42  lues, strings, B
1a810 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a  LOBs, or NULL..*
1a820 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f  *.** An sqlite3_
1a830 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79  value object may
1a840 20 62 65 20 65 69 74 68 65 72 20 22 70 72 6f 74   be either "prot
1a850 65 63 74 65 64 22 20 6f 72 20 22 75 6e 70 72 6f  ected" or "unpro
1a860 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65  tected"..** Some
1a870 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75   interfaces requ
1a880 69 72 65 20 61 20 70 72 6f 74 65 63 74 65 64 20  ire a protected 
1a890 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20  sqlite3_value.  
1a8a0 4f 74 68 65 72 20 69 6e 74 65 72 66 61 63 65 73  Other interfaces
1a8b0 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70 74 20  .** will accept 
1a8c0 65 69 74 68 65 72 20 61 20 70 72 6f 74 65 63 74  either a protect
1a8d0 65 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65  ed or an unprote
1a8e0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
1a8f0 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74  ue..** Every int
1a900 65 72 66 61 63 65 20 74 68 61 74 20 61 63 63 65  erface that acce
1a910 70 74 73 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  pts sqlite3_valu
1a920 65 20 61 72 67 75 6d 65 6e 74 73 20 73 70 65 63  e arguments spec
1a930 69 66 69 65 73 20 0a 2a 2a 20 77 68 65 74 68 65  ifies .** whethe
1a940 72 20 6f 72 20 6e 6f 74 20 69 74 20 72 65 71 75  r or not it requ
1a950 69 72 65 73 20 61 20 70 72 6f 74 65 63 74 65 64  ires a protected
1a960 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a   sqlite3_value..
1a970 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 20  **.** The terms 
1a980 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e 64 20  "protected" and 
1a990 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20 72 65  "unprotected" re
1a9a0 66 65 72 20 74 6f 20 77 68 65 74 68 65 72 20 6f  fer to whether o
1a9b0 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78  r not.** a mutex
1a9c0 20 69 73 20 68 65 6c 64 2e 20 20 41 20 69 6e 74   is held.  A int
1a9d0 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 68  ernal mutex is h
1a9e0 65 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 65 63  eld for a protec
1a9f0 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  ted.** sqlite3_v
1aa00 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 74 20  alue object but 
1aa10 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64  no mutex is held
1aa20 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63   for an unprotec
1aa30 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  ted.** sqlite3_v
1aa40 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 66  alue object.  If
1aa50 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
1aa60 6c 65 64 20 74 6f 20 62 65 20 73 69 6e 67 6c 65  led to be single
1aa70 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 69  -threaded.** (wi
1aa80 74 68 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44  th SQLITE_THREAD
1aa90 53 41 46 45 3d 30 20 61 6e 64 20 77 69 74 68 20  SAFE=0 and with 
1aaa0 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73  [sqlite3_threads
1aab0 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69 6e 67  afe()] returning
1aac0 20 30 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72   0).** then ther
1aad0 65 20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63 74  e is no distinct
1aae0 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 70  ion between.** p
1aaf0 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70  rotected and unp
1ab00 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
1ab10 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 61  _value objects a
1ab20 6e 64 20 74 68 65 79 20 63 61 6e 20 62 65 0a 2a  nd they can be.*
1ab30 2a 20 75 73 65 64 20 69 6e 74 65 72 63 68 61 6e  * used interchan
1ab40 67 61 62 6c 65 2e 20 20 48 6f 77 65 76 65 72 2c  gable.  However,
1ab50 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64   for maximum cod
1ab60 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74  e portability it
1ab70 0a 2a 2a 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64  .** is recommend
1ab80 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74  ed that applicat
1ab90 69 6f 6e 73 20 6d 61 6b 65 20 74 68 65 20 64 69  ions make the di
1aba0 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65  stinction betwee
1abb0 6e 0a 2a 2a 20 62 65 74 77 65 65 6e 20 70 72 6f  n.** between pro
1abc0 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f  tected and unpro
1abd0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
1abe0 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 65 76 65  alue objects eve
1abf0 6e 20 69 66 0a 2a 2a 20 74 68 65 79 20 61 72 65  n if.** they are
1ac00 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 65 64   single threaded
1ac10 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
1ac20 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
1ac30 73 20 74 68 61 74 20 61 72 65 20 70 61 73 73 65  s that are passe
1ac40 64 20 61 73 20 70 61 72 61 6d 65 74 65 72 73 20  d as parameters 
1ac50 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c  into the.** impl
1ac60 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 70  ementation of ap
1ac70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
1ac80 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  d SQL functions 
1ac90 61 72 65 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a  are protected..*
1aca0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61  * The sqlite3_va
1acb0 6c 75 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72  lue object retur
1acc0 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ned by.** [sqlit
1acd0 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28  e3_column_value(
1ace0 29 5d 20 69 73 20 75 6e 70 72 6f 74 65 63 74 65  )] is unprotecte
1acf0 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65  d..** Unprotecte
1ad00 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  d sqlite3_value 
1ad10 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79  objects may only
1ad20 20 62 65 20 75 73 65 64 20 77 69 74 68 0a 2a 2a   be used with.**
1ad30 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
1ad40 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73  _value()] and [s
1ad50 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75  qlite3_bind_valu
1ad60 65 28 29 5d 2e 20 20 41 6c 6c 20 6f 74 68 65 72  e()].  All other
1ad70 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 74  .** interfaces t
1ad80 68 61 74 20 75 73 65 20 73 71 6c 69 74 65 33 5f  hat use sqlite3_
1ad90 76 61 6c 75 65 20 72 65 71 75 69 72 65 20 70 72  value require pr
1ada0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
1adb0 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a  value objects..*
1adc0 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
1add0 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c   Mem sqlite3_val
1ade0 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  ue;../*.** CAPI3
1adf0 52 45 46 3a 20 20 53 51 4c 20 46 75 6e 63 74 69  REF:  SQL Functi
1ae00 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63  on Context Objec
1ae10 74 20 7b 46 31 36 30 30 31 7d 0a 2a 2a 0a 2a 2a  t {F16001}.**.**
1ae20 20 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20   The context in 
1ae30 77 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e  which an SQL fun
1ae40 63 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69  ction executes i
1ae50 73 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a  s stored in an.*
1ae60 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  * sqlite3_contex
1ae70 74 20 6f 62 6a 65 63 74 2e 20 20 41 20 70 6f 69  t object.  A poi
1ae80 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74  nter to an sqlit
1ae90 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 20 6f 62  e3_context.** ob
1aea0 6a 65 63 74 20 69 73 20 61 6c 77 61 79 73 20 66  ject is always f
1aeb0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
1aec0 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  o application-de
1aed0 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
1aee0 6f 6e 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ons..*/.typedef 
1aef0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63  struct sqlite3_c
1af00 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63  ontext sqlite3_c
1af10 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ontext;../*.** C
1af20 41 50 49 33 52 45 46 3a 20 20 42 69 6e 64 69 6e  API3REF:  Bindin
1af30 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70  g Values To Prep
1af40 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73 20  ared Statements 
1af50 7b 46 31 33 35 30 30 7d 0a 2a 2a 0a 2a 2a 20 49  {F13500}.**.** I
1af60 6e 20 74 68 65 20 53 51 4c 20 73 74 72 69 6e 67  n the SQL string
1af70 73 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69  s input to [sqli
1af80 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1af90 5d 20 61 6e 64 20 69 74 73 0a 2a 2a 20 76 61 72  ] and its.** var
1afa0 69 61 6e 74 73 2c 20 6c 69 74 65 72 61 6c 73 20  iants, literals 
1afb0 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65 20 62  may be replace b
1afc0 79 20 61 20 70 61 72 61 6d 65 74 65 72 20 69 6e  y a parameter in
1afd0 20 6f 6e 65 0a 2a 2a 20 6f 66 20 74 68 65 73 65   one.** of these
1afe0 20 66 6f 72 6d 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75   forms:.**.** <u
1aff0 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a  l>.** <li>  ?.**
1b000 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c   <li>  ?NNN.** <
1b010 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69  li>  :VVV.** <li
1b020 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20  >  @VVV.** <li> 
1b030 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a   $VVV.** </ul>.*
1b040 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 70 61 72 61  *.** In the para
1b050 6d 65 74 65 72 20 66 6f 72 6d 73 20 73 68 6f 77  meter forms show
1b060 6e 20 61 62 6f 76 65 20 4e 4e 4e 20 69 73 20 61  n above NNN is a
1b070 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72 61  n integer litera
1b080 6c 2c 0a 2a 2a 20 56 56 56 20 61 6c 70 68 61 2d  l,.** VVV alpha-
1b090 6e 75 6d 65 72 69 63 20 70 61 72 61 6d 65 74 65  numeric paramete
1b0a0 72 20 6e 61 6d 65 2e 0a 2a 2a 20 54 68 65 20 76  r name..** The v
1b0b0 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65 20 70  alues of these p
1b0c0 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73 6f 20  arameters (also 
1b0d0 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 61 72  called "host par
1b0e0 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 0a 2a 2a  ameter names".**
1b0f0 20 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74   or "SQL paramet
1b100 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20  ers").** can be 
1b110 73 65 74 20 75 73 69 6e 67 20 74 68 65 20 73 71  set using the sq
1b120 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
1b130 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20  outines defined 
1b140 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  here..**.** The 
1b150 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
1b160 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  o the sqlite3_bi
1b170 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
1b180 61 6c 77 61 79 73 0a 2a 2a 20 69 73 20 61 20 70  always.** is a p
1b190 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ointer to the [s
1b1a0 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a  qlite3_stmt] obj
1b1b0 65 63 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f  ect returned fro
1b1c0 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  m.** [sqlite3_pr
1b1d0 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69  epare_v2()] or i
1b1e0 74 73 20 76 61 72 69 61 6e 74 73 2e 20 54 68 65  ts variants. The
1b1f0 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d   second.** argum
1b200 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78  ent is the index
1b210 20 6f 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   of the paramete
1b220 72 20 74 6f 20 62 65 20 73 65 74 2e 20 54 68 65  r to be set. The
1b230 0a 2a 2a 20 66 69 72 73 74 20 70 61 72 61 6d 65  .** first parame
1b240 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78  ter has an index
1b250 20 6f 66 20 31 2e 20 20 57 68 65 6e 20 74 68 65   of 1.  When the
1b260 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 70   same named.** p
1b270 61 72 61 6d 65 74 65 72 20 69 73 20 75 73 65 64  arameter is used
1b280 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c   more than once,
1b290 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73   second and subs
1b2a0 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72  equent.** occurr
1b2b0 65 6e 63 65 73 20 68 61 76 65 20 74 68 65 20 73  ences have the s
1b2c0 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68 65  ame index as the
1b2d0 20 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63   first occurrenc
1b2e0 65 2e 20 0a 2a 2a 20 54 68 65 20 69 6e 64 65 78  e. .** The index
1b2f0 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 61 6d   for named param
1b300 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f  eters can be loo
1b310 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74 68 65  ked up using the
1b320 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
1b330 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
1b340 28 29 5d 20 41 50 49 20 69 66 20 64 65 73 69 72  ()] API if desir
1b350 65 64 2e 20 20 54 68 65 20 69 6e 64 65 78 0a 2a  ed.  The index.*
1b360 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72  * for "?NNN" par
1b370 61 6d 65 74 65 72 73 20 69 73 20 74 68 65 20 76  ameters is the v
1b380 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20  alue of NNN..** 
1b390 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75  The NNN value mu
1b3a0 73 74 20 62 65 20 62 65 74 77 65 65 6e 20 31 20  st be between 1 
1b3b0 61 6e 64 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d  and the compile-
1b3c0 74 69 6d 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65  time.** paramete
1b3d0 72 20 53 51 4c 49 54 45 5f 4d 41 58 5f 56 41 52  r SQLITE_MAX_VAR
1b3e0 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20 28 64 65  IABLE_NUMBER (de
1b3f0 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 39  fault value: 999
1b400 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69  )..**.** The thi
1b410 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  rd argument is t
1b420 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69 6e 64  he value to bind
1b430 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65   to the paramete
1b440 72 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 6f 73  r..**.** In thos
1b450 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74 68  e.** routines th
1b460 61 74 20 68 61 76 65 20 61 20 66 6f 75 72 74 68  at have a fourth
1b470 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 76   argument, its v
1b480 61 6c 75 65 20 69 73 20 74 68 65 20 6e 75 6d 62  alue is the numb
1b490 65 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20 69  er of bytes.** i
1b4a0 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e  n the parameter.
1b4b0 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 74    To be clear: t
1b4c0 68 65 20 76 61 6c 75 65 20 69 73 20 74 68 65 20  he value is the 
1b4d0 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74  number of <u>byt
1b4e0 65 73 3c 2f 75 3e 0a 2a 2a 20 69 6e 20 74 68 65  es</u>.** in the
1b4f0 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20   value, not the 
1b500 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63  number of charac
1b510 74 65 72 73 2e 20 0a 2a 2a 20 49 66 20 74 68 65  ters. .** If the
1b520 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
1b530 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  r is negative, t
1b540 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65  he length of the
1b550 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 6e 75   string is.** nu
1b560 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 75 70  mber of bytes up
1b570 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65   to the first ze
1b580 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a  ro terminator..*
1b590 2a 0a 2a 2a 20 54 68 65 20 66 69 66 74 68 20 61  *.** The fifth a
1b5a0 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
1b5b0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 20  e3_bind_blob(), 
1b5c0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
1b5d0 74 28 29 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69  t(), and.** sqli
1b5e0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
1b5f0 29 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f  ) is a destructo
1b600 72 20 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73  r used to dispos
1b610 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72  e of the BLOB or
1b620 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74 65 72  .** string after
1b630 20 53 51 4c 69 74 65 20 68 61 73 20 66 69 6e 69   SQLite has fini
1b640 73 68 65 64 20 77 69 74 68 20 69 74 2e 20 49 66  shed with it. If
1b650 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d   the fifth argum
1b660 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70  ent is.** the sp
1b670 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c  ecial value [SQL
1b680 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65  ITE_STATIC], the
1b690 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73  n SQLite assumes
1b6a0 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66   that the.** inf
1b6b0 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73  ormation is in s
1b6c0 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64  tatic, unmanaged
1b6d0 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20   space and does 
1b6e0 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66  not need to be f
1b6f0 72 65 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20  reed..** If the 
1b700 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68  fifth argument h
1b710 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51  as the value [SQ
1b720 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c  LITE_TRANSIENT],
1b730 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20   then.** SQLite 
1b740 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 72  makes its own pr
1b750 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68  ivate copy of th
1b760 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65  e data immediate
1b770 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68  ly, before.** th
1b780 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
1b790 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
1b7a0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ns..**.** The sq
1b7b0 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62  lite3_bind_zerob
1b7c0 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62 69  lob() routine bi
1b7d0 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65  nds a BLOB of le
1b7e0 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69  ngth N that.** i
1b7f0 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a 65  s filled with ze
1b800 72 6f 73 2e 20 20 41 20 7a 65 72 6f 62 6c 6f 62  ros.  A zeroblob
1b810 20 75 73 65 73 20 61 20 66 69 78 65 64 20 61 6d   uses a fixed am
1b820 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a  ount of memory.*
1b830 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 67  * (just an integ
1b840 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 20 73 69  er to hold it si
1b850 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69 73 20  ze) while it is 
1b860 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64 2e  being processed.
1b870 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72  .** Zeroblobs ar
1b880 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 65  e intended to se
1b890 72 76 65 20 61 73 20 70 6c 61 63 65 2d 68 6f 6c  rve as place-hol
1b8a0 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 77  ders for BLOBs w
1b8b0 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20  hose.** content 
1b8c0 69 73 20 6c 61 74 65 72 20 77 72 69 74 74 65 6e  is later written
1b8d0 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69   using .** [sqli
1b8e0 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20  te3_blob_open | 
1b8f0 69 6e 63 72 65 6d 65 6e 74 20 42 4c 4f 42 20 49  increment BLOB I
1b900 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 20 41 20  /O] routines. A 
1b910 6e 65 67 61 74 69 76 65 0a 2a 2a 20 76 61 6c 75  negative.** valu
1b920 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c  e for the zerobl
1b930 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61 20  ob results in a 
1b940 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42  zero-length BLOB
1b950 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
1b960 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
1b970 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61  tines must be ca
1b980 6c 6c 65 64 20 61 66 74 65 72 0a 2a 2a 20 5b 73  lled after.** [s
1b990 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1b9a0 32 28 29 5d 20 28 61 6e 64 20 69 74 73 20 76 61  2()] (and its va
1b9b0 72 69 61 6e 74 73 29 20 6f 72 20 5b 73 71 6c 69  riants) or [sqli
1b9c0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61 6e 64  te3_reset()] and
1b9d0 0a 2a 2a 20 62 65 66 6f 72 65 20 5b 73 71 6c 69  .** before [sqli
1b9e0 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20  te3_step()]..** 
1b9f0 42 69 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f 74  Bindings are not
1ba00 20 63 6c 65 61 72 65 64 20 62 79 20 74 68 65 20   cleared by the 
1ba10 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
1ba20 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 55 6e  ] routine..** Un
1ba30 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73  bound parameters
1ba40 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64   are interpreted
1ba50 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   as NULL..**.** 
1ba60 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
1ba70 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b  eturn [SQLITE_OK
1ba80 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 20  ] on success or 
1ba90 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 20 69 66  an error code if
1baa0 0a 2a 2a 20 61 6e 79 74 68 69 6e 67 20 67 6f 65  .** anything goe
1bab0 73 20 77 72 6f 6e 67 2e 20 20 5b 53 51 4c 49 54  s wrong.  [SQLIT
1bac0 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75  E_RANGE] is retu
1bad0 72 6e 65 64 20 69 66 20 74 68 65 20 70 61 72 61  rned if the para
1bae0 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69  meter.** index i
1baf0 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20  s out of range. 
1bb00 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20   [SQLITE_NOMEM] 
1bb10 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d  is returned if m
1bb20 61 6c 6c 6f 63 20 66 61 69 6c 73 2e 0a 2a 2a 20  alloc fails..** 
1bb30 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20  [SQLITE_MISUSE] 
1bb40 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e 65  might be returne
1bb50 64 20 69 66 20 74 68 65 73 65 20 72 6f 75 74 69  d if these routi
1bb60 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 6f  nes are called o
1bb70 6e 20 61 0a 2a 2a 20 76 69 72 74 75 61 6c 20 6d  n a.** virtual m
1bb80 61 63 68 69 6e 65 20 74 68 61 74 20 69 73 20 74  achine that is t
1bb90 68 65 20 77 72 6f 6e 67 20 73 74 61 74 65 20 6f  he wrong state o
1bba0 72 20 77 68 69 63 68 20 68 61 73 20 61 6c 72 65  r which has alre
1bbb0 61 64 79 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a  ady been finaliz
1bbc0 65 64 2e 0a 2a 2a 20 44 65 74 65 63 74 69 6f 6e  ed..** Detection
1bbd0 20 6f 66 20 6d 69 73 75 73 65 20 69 73 20 75 6e   of misuse is un
1bbe0 72 65 6c 69 61 62 6c 65 2e 20 20 41 70 70 6c 69  reliable.  Appli
1bbf0 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e  cations should n
1bc00 6f 74 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20  ot depend.** on 
1bc10 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 72 65  SQLITE_MISUSE re
1bc20 74 75 72 6e 73 2e 20 20 53 51 4c 49 54 45 5f 4d  turns.  SQLITE_M
1bc30 49 53 55 53 45 20 69 73 20 69 6e 74 65 6e 64 65  ISUSE is intende
1bc40 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 61 0a  d to indicate a.
1bc50 2a 2a 20 61 20 6c 6f 67 69 63 20 65 72 72 6f 72  ** a logic error
1bc60 20 69 6e 20 74 68 65 20 61 70 70 6c 69 63 61 74   in the applicat
1bc70 69 6f 6e 2e 20 20 46 75 74 75 72 65 20 76 65 72  ion.  Future ver
1bc80 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
1bc90 6d 69 67 68 74 0a 2a 2a 20 70 61 6e 69 63 20 72  might.** panic r
1bca0 61 74 68 65 72 20 74 68 61 6e 20 72 65 74 75 72  ather than retur
1bcb0 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e  n SQLITE_MISUSE.
1bcc0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
1bcd0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
1bce0 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29  arameter_count()
1bcf0 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
1bd00 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
1bd10 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  me()], and.** [s
1bd20 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
1bd30 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
1bd40 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
1bd50 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 30 36 7d  :.**.** {F13506}
1bd60 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72   The [sqlite3_pr
1bd70 65 70 61 72 65 20 7c 20 53 51 4c 20 73 74 61 74  epare | SQL stat
1bd80 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 5d 20  ement compiler] 
1bd90 72 65 63 6f 67 6e 69 7a 65 73 0a 2a 2a 20 20 20  recognizes.**   
1bda0 20 20 20 20 20 20 20 74 6f 6b 65 6e 73 20 6f 66         tokens of
1bdb0 20 74 68 65 20 66 6f 72 6d 73 20 22 3f 22 2c 20   the forms "?", 
1bdc0 22 3f 4e 4e 4e 22 2c 20 22 24 56 56 56 22 2c 20  "?NNN", "$VVV", 
1bdd0 22 3a 56 56 56 22 2c 20 61 6e 64 20 22 40 56 56  ":VVV", and "@VV
1bde0 56 22 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  V".**          a
1bdf0 73 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73  s SQL parameters
1be00 2c 20 77 68 65 72 65 20 4e 4e 4e 20 69 73 20 61  , where NNN is a
1be10 6e 79 20 73 65 71 75 65 6e 63 65 20 6f 66 20 6f  ny sequence of o
1be20 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 20 20  ne or more.**   
1be30 20 20 20 20 20 20 20 64 69 67 69 74 73 20 61 6e         digits an
1be40 64 20 77 68 65 72 65 20 56 56 56 20 69 73 20 61  d where VVV is a
1be50 6e 79 20 73 65 71 75 65 6e 63 65 20 6f 66 20 6f  ny sequence of o
1be60 6e 65 20 6f 72 20 6d 6f 72 65 20 0a 2a 2a 20 20  ne or more .**  
1be70 20 20 20 20 20 20 20 20 61 6c 70 68 61 6e 75 6d          alphanum
1be80 65 72 69 63 20 63 68 61 72 61 63 74 65 72 73 20  eric characters 
1be90 6f 72 20 22 3a 3a 22 20 6f 70 74 69 6f 6e 61 6c  or "::" optional
1bea0 6c 79 20 66 6f 6c 6c 6f 77 65 64 20 62 79 0a 2a  ly followed by.*
1beb0 2a 20 20 20 20 20 20 20 20 20 20 61 20 73 74 72  *          a str
1bec0 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 6e  ing containing n
1bed0 6f 20 73 70 61 63 65 73 20 61 6e 64 20 63 6f 6e  o spaces and con
1bee0 74 61 69 6e 65 64 20 77 69 74 68 69 6e 20 70 61  tained within pa
1bef0 72 65 6e 74 68 65 73 65 73 2e 0a 2a 2a 0a 2a 2a  rentheses..**.**
1bf00 20 7b 46 31 33 35 30 39 7d 20 54 68 65 20 69 6e   {F13509} The in
1bf10 69 74 69 61 6c 20 76 61 6c 75 65 20 6f 66 20 61  itial value of a
1bf20 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  n SQL parameter 
1bf30 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b  is NULL..**.** {
1bf40 46 31 33 35 31 32 7d 20 54 68 65 20 69 6e 64 65  F13512} The inde
1bf50 78 20 6f 66 20 61 6e 20 22 3f 22 20 53 51 4c 20  x of an "?" SQL 
1bf60 70 61 72 61 6d 65 74 65 72 20 69 73 20 6f 6e 65  parameter is one
1bf70 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68 65   larger than the
1bf80 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6c 61 72  .**          lar
1bf90 67 65 73 74 20 69 6e 64 65 78 20 6f 66 20 53 51  gest index of SQ
1bfa0 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  L parameter to t
1bfb0 68 65 20 6c 65 66 74 2c 20 6f 72 20 31 20 69 66  he left, or 1 if
1bfc0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
1bfd0 20 22 3f 22 20 69 73 20 74 68 65 20 6c 65 66 74   "?" is the left
1bfe0 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65 74  most SQL paramet
1bff0 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 31  er..**.** {F1351
1c000 35 7d 20 54 68 65 20 69 6e 64 65 78 20 6f 66 20  5} The index of 
1c010 61 6e 20 22 3f 4e 4e 4e 22 20 53 51 4c 20 70 61  an "?NNN" SQL pa
1c020 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 69  rameter is the i
1c030 6e 74 65 67 65 72 20 4e 4e 4e 2e 0a 2a 2a 0a 2a  nteger NNN..**.*
1c040 2a 20 7b 46 31 33 35 31 38 7d 20 54 68 65 20 69  * {F13518} The i
1c050 6e 64 65 78 20 6f 66 20 61 6e 20 22 3a 56 56 56  ndex of an ":VVV
1c060 22 2c 20 22 24 56 56 56 22 2c 20 6f 72 20 22 40  ", "$VVV", or "@
1c070 56 56 56 22 20 53 51 4c 20 70 61 72 61 6d 65 74  VVV" SQL paramet
1c080 65 72 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20  er is.**        
1c090 20 20 74 68 65 20 73 61 6d 65 20 61 73 20 74 68    the same as th
1c0a0 65 20 69 6e 64 65 78 20 6f 66 20 6c 65 66 74 6d  e index of leftm
1c0b0 6f 73 74 20 6f 63 63 75 72 61 6e 63 65 73 20 6f  ost occurances o
1c0c0 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20  f the same.**   
1c0d0 20 20 20 20 20 20 20 70 61 72 61 6d 65 74 65 72         parameter
1c0e0 2c 20 6f 72 20 6f 6e 65 20 6d 6f 72 65 20 74 68  , or one more th
1c0f0 61 6e 20 74 68 65 20 6c 61 72 67 65 73 74 20 69  an the largest i
1c100 6e 64 65 78 20 6f 76 65 72 20 61 6c 6c 0a 2a 2a  ndex over all.**
1c110 20 20 20 20 20 20 20 20 20 20 70 61 72 61 6d 65            parame
1c120 74 65 72 73 20 74 6f 20 74 68 65 20 6c 65 66 74  ters to the left
1c130 20 69 66 20 74 68 69 73 20 69 73 20 74 68 65 20   if this is the 
1c140 66 69 72 73 74 20 6f 63 63 75 72 72 61 6e 63 65  first occurrance
1c150 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20  .**          of 
1c160 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 2c 20  this parameter, 
1c170 6f 72 20 31 20 69 66 20 74 68 69 73 20 69 73 20  or 1 if this is 
1c180 74 68 65 20 6c 65 66 74 6d 6f 73 74 20 70 61 72  the leftmost par
1c190 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46  ameter..**.** {F
1c1a0 31 33 35 32 31 7d 20 54 68 65 20 5b 73 71 6c 69  13521} The [sqli
1c1b0 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 53 51  te3_prepare | SQ
1c1c0 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70  L statement comp
1c1d0 69 6c 65 72 5d 20 66 61 69 6c 20 77 69 74 68 0a  iler] fail with.
1c1e0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 20 5b  **          an [
1c1f0 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 65 72  SQLITE_RANGE] er
1c200 72 6f 72 20 69 66 20 74 68 65 20 69 6e 64 65 78  ror if the index
1c210 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d   of an SQL param
1c220 65 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  eter.**         
1c230 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 31 20   is less than 1 
1c240 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  or greater than 
1c250 53 51 4c 49 54 45 5f 4d 41 58 5f 56 41 52 49 41  SQLITE_MAX_VARIA
1c260 42 4c 45 5f 4e 55 4d 42 45 52 2e 0a 2a 2a 0a 2a  BLE_NUMBER..**.*
1c270 2a 20 7b 46 31 33 35 32 34 7d 20 43 61 6c 6c 73  * {F13524} Calls
1c280 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e   to [sqlite3_bin
1c290 64 5f 74 65 78 74 20 7c 20 73 71 6c 69 74 65 33  d_text | sqlite3
1c2a0 5f 62 69 6e 64 28 53 2c 4e 2c 56 2c 2e 2e 2e 29  _bind(S,N,V,...)
1c2b0 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 73  ].**          as
1c2c0 73 6f 63 69 61 74 65 20 74 68 65 20 76 61 6c 75  sociate the valu
1c2d0 65 20 56 20 77 69 74 68 20 61 6c 6c 20 53 51 4c  e V with all SQL
1c2e0 20 70 61 72 61 6d 65 74 65 72 73 20 68 61 76 69   parameters havi
1c2f0 6e 67 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20  ng an.**        
1c300 20 20 69 6e 64 65 78 20 6f 66 20 4e 20 69 6e 20    index of N in 
1c310 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
1c320 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a  atement] S..**.*
1c330 2a 20 7b 46 31 33 35 32 37 7d 20 43 61 6c 6c 73  * {F13527} Calls
1c340 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e   to [sqlite3_bin
1c350 64 5f 74 65 78 74 20 7c 20 73 71 6c 69 74 65 33  d_text | sqlite3
1c360 5f 62 69 6e 64 28 53 2c 4e 2c 2e 2e 2e 29 5d 0a  _bind(S,N,...)].
1c370 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 76 65 72  **          over
1c380 72 69 64 65 20 70 72 69 6f 72 20 63 61 6c 6c 73  ride prior calls
1c390 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 76   with the same v
1c3a0 61 6c 75 65 73 20 6f 66 20 53 20 61 6e 64 20 4e  alues of S and N
1c3b0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 33 30 7d  ..**.** {F13530}
1c3c0 20 42 69 6e 64 69 6e 67 73 20 65 73 74 61 62 6c   Bindings establ
1c3d0 69 73 68 65 64 20 62 79 20 5b 73 71 6c 69 74 65  ished by [sqlite
1c3e0 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 73 71  3_bind_text | sq
1c3f0 6c 69 74 65 33 5f 62 69 6e 64 28 53 2c 2e 2e 2e  lite3_bind(S,...
1c400 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70  )].**          p
1c410 65 72 73 69 73 74 20 61 63 72 6f 73 73 20 63 61  ersist across ca
1c420 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
1c430 72 65 73 65 74 28 53 29 5d 2e 0a 2a 2a 0a 2a 2a  reset(S)]..**.**
1c440 20 7b 46 31 33 35 33 33 7d 20 49 6e 20 63 61 6c   {F13533} In cal
1c450 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62  ls to [sqlite3_b
1c460 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c  ind_blob(S,N,V,L
1c470 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  ,D)],.**        
1c480 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f    [sqlite3_bind_
1c490 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d  text(S,N,V,L,D)]
1c4a0 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  , or.**         
1c4b0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74   [sqlite3_bind_t
1c4c0 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29  ext16(S,N,V,L,D)
1c4d0 5d 20 53 51 4c 69 74 65 20 62 69 6e 64 73 20 74  ] SQLite binds t
1c4e0 68 65 20 66 69 72 73 74 20 4c 0a 2a 2a 20 20 20  he first L.**   
1c4f0 20 20 20 20 20 20 20 62 79 74 65 73 20 6f 66 20         bytes of 
1c500 74 68 65 20 62 6c 6f 62 20 6f 72 20 73 74 72 69  the blob or stri
1c510 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79  ng pointed to by
1c520 20 56 2c 20 77 68 65 6e 20 4c 0a 2a 2a 20 20 20   V, when L.**   
1c530 20 20 20 20 20 20 20 69 73 20 6e 6f 6e 2d 6e 65         is non-ne
1c540 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46  gative..**.** {F
1c550 31 33 35 33 36 7d 20 49 6e 20 63 61 6c 6c 73 20  13536} In calls 
1c560 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  to [sqlite3_bind
1c570 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29  _text(S,N,V,L,D)
1c580 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  ] or.**         
1c590 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74   [sqlite3_bind_t
1c5a0 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29  ext16(S,N,V,L,D)
1c5b0 5d 20 53 51 4c 69 74 65 20 62 69 6e 64 73 20 63  ] SQLite binds c
1c5c0 68 61 72 61 63 74 65 72 73 0a 2a 2a 20 20 20 20  haracters.**    
1c5d0 20 20 20 20 20 20 66 72 6f 6d 20 56 20 74 68 72        from V thr
1c5e0 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a  ough the first z
1c5f0 65 72 6f 20 63 68 61 72 61 63 74 65 72 20 77 68  ero character wh
1c600 65 6e 20 4c 20 69 73 20 6e 65 67 61 74 69 76 65  en L is negative
1c610 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 33 39 7d  ..**.** {F13539}
1c620 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71   In calls to [sq
1c630 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
1c640 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20  S,N,V,L,D)],.** 
1c650 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
1c660 33 5f 62 69 6e 64 5f 74 65 78 74 28 53 2c 4e 2c  3_bind_text(S,N,
1c670 56 2c 4c 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20  V,L,D)], or.**  
1c680 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
1c690 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e  _bind_text16(S,N
1c6a0 2c 56 2c 4c 2c 44 29 5d 20 77 68 65 6e 20 44 20  ,V,L,D)] when D 
1c6b0 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 0a 2a  is the special.*
1c6c0 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e 73 74  *          const
1c6d0 61 6e 74 20 5b 53 51 4c 49 54 45 5f 53 54 41 54  ant [SQLITE_STAT
1c6e0 49 43 5d 2c 20 53 51 4c 69 74 65 20 61 73 73 75  IC], SQLite assu
1c6f0 6d 65 73 20 74 68 61 74 20 74 68 65 20 76 61 6c  mes that the val
1c700 75 65 20 56 0a 2a 2a 20 20 20 20 20 20 20 20 20  ue V.**         
1c710 20 69 73 20 68 65 6c 64 20 69 6e 20 73 74 61 74   is held in stat
1c720 69 63 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 61  ic unmanaged spa
1c730 63 65 20 74 68 61 74 20 77 69 6c 6c 20 6e 6f 74  ce that will not
1c740 20 63 68 61 6e 67 65 0a 2a 2a 20 20 20 20 20 20   change.**      
1c750 20 20 20 20 64 75 72 69 6e 67 20 74 68 65 20 6c      during the l
1c760 69 66 65 74 69 6d 65 20 6f 66 20 74 68 65 20 62  ifetime of the b
1c770 69 6e 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46  inding..**.** {F
1c780 31 33 35 34 32 7d 20 49 6e 20 63 61 6c 6c 73 20  13542} In calls 
1c790 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  to [sqlite3_bind
1c7a0 5f 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 2c 44 29  _blob(S,N,V,L,D)
1c7b0 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ],.**          [
1c7c0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
1c7d0 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 20 6f  t(S,N,V,L,D)], o
1c7e0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  r.**          [s
1c7f0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
1c800 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 77  16(S,N,V,L,D)] w
1c810 68 65 6e 20 44 20 69 73 20 74 68 65 20 73 70 65  hen D is the spe
1c820 63 69 61 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20  cial.**         
1c830 20 63 6f 6e 73 74 61 6e 74 20 5b 53 51 4c 49 54   constant [SQLIT
1c840 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68  E_TRANSIENT], th
1c850 65 20 72 6f 75 74 69 6e 65 20 6d 61 6b 65 73 20  e routine makes 
1c860 61 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70  a .**          p
1c870 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 56  rivate copy of V
1c880 20 76 61 6c 75 65 20 62 65 66 6f 72 65 20 69 74   value before it
1c890 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
1c8a0 7b 46 31 33 35 34 35 7d 20 49 6e 20 63 61 6c 6c  {F13545} In call
1c8b0 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69  s to [sqlite3_bi
1c8c0 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 2c  nd_blob(S,N,V,L,
1c8d0 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  D)],.**         
1c8e0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74   [sqlite3_bind_t
1c8f0 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c  ext(S,N,V,L,D)],
1c900 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   or.**          
1c910 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65  [sqlite3_bind_te
1c920 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d  xt16(S,N,V,L,D)]
1c930 20 77 68 65 6e 20 44 20 69 73 20 61 20 70 6f 69   when D is a poi
1c940 6e 74 65 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20  nter to.**      
1c950 20 20 20 20 61 20 66 75 6e 63 74 69 6f 6e 2c 20      a function, 
1c960 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74  SQLite invokes t
1c970 68 61 74 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  hat function to 
1c980 64 65 73 74 72 6f 79 20 74 68 65 0a 2a 2a 20 20  destroy the.**  
1c990 20 20 20 20 20 20 20 20 56 20 76 61 6c 75 65 20          V value 
1c9a0 61 66 74 65 72 20 69 74 20 68 61 73 20 66 69 6e  after it has fin
1c9b0 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 65 20  ished using the 
1c9c0 56 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b  V value..**.** {
1c9d0 46 31 33 35 34 38 7d 20 49 6e 20 63 61 6c 6c 73  F13548} In calls
1c9e0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e   to [sqlite3_bin
1c9f0 64 5f 7a 65 72 6f 62 6c 6f 62 28 53 2c 4e 2c 56  d_zeroblob(S,N,V
1ca00 2c 4c 29 5d 20 74 68 65 20 76 61 6c 75 65 20 62  ,L)] the value b
1ca10 6f 75 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  ound.**         
1ca20 20 69 73 20 61 20 62 6c 6f 62 20 6f 66 20 4c 20   is a blob of L 
1ca30 62 79 74 65 73 2c 20 6f 72 20 61 20 7a 65 72 6f  bytes, or a zero
1ca40 2d 6c 65 6e 67 74 68 20 62 6c 6f 62 20 69 66 20  -length blob if 
1ca50 4c 20 69 73 20 6e 65 67 61 74 69 76 65 2e 0a 2a  L is negative..*
1ca60 2a 0a 2a 2a 20 7b 46 31 33 35 35 31 7d 20 49 6e  *.** {F13551} In
1ca70 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
1ca80 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 53 2c  e3_bind_value(S,
1ca90 4e 2c 56 29 5d 20 74 68 65 20 56 20 61 72 67 75  N,V)] the V argu
1caa0 6d 65 6e 74 20 6d 61 79 0a 2a 2a 20 20 20 20 20  ment may.**     
1cab0 20 20 20 20 20 62 65 20 65 69 74 68 65 72 20 61       be either a
1cac0 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
1cad0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
1cae0 74 20 6f 72 20 61 6e 0a 2a 2a 20 20 20 20 20 20  t or an.**      
1caf0 20 20 20 20 5b 75 6e 70 72 6f 74 65 63 74 65 64      [unprotected
1cb00 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
1cb10 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 69 6e 74 20 73  object..*/.int s
1cb20 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
1cb30 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
1cb40 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  int, const void*
1cb50 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29  , int n, void(*)
1cb60 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71  (void*));.int sq
1cb70 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c  lite3_bind_doubl
1cb80 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
1cb90 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 69   int, double);.i
1cba0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
1cbb0 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  int(sqlite3_stmt
1cbc0 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e  *, int, int);.in
1cbd0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69  t sqlite3_bind_i
1cbe0 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d  nt64(sqlite3_stm
1cbf0 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33  t*, int, sqlite3
1cc00 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73 71 6c  _int64);.int sql
1cc10 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73  ite3_bind_null(s
1cc20 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
1cc30 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  t);.int sqlite3_
1cc40 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74 65  bind_text(sqlite
1cc50 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
1cc60 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 20 6e  nst char*, int n
1cc70 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
1cc80 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
1cc90 69 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69 74  ind_text16(sqlit
1cca0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
1ccb0 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
1ccc0 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
1ccd0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
1cce0 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33  nd_value(sqlite3
1ccf0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
1cd00 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  st sqlite3_value
1cd10 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
1cd20 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71  bind_zeroblob(sq
1cd30 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
1cd40 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a  , int n);../*.**
1cd50 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65   CAPI3REF: Numbe
1cd60 72 20 4f 66 20 53 51 4c 20 50 61 72 61 6d 65 74  r Of SQL Paramet
1cd70 65 72 73 20 7b 46 31 33 36 30 30 7d 0a 2a 2a 0a  ers {F13600}.**.
1cd80 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
1cd90 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 66  can be used to f
1cda0 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ind the number o
1cdb0 66 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73  f SQL parameters
1cdc0 0a 2a 2a 20 69 6e 20 61 20 70 72 65 70 61 72 65  .** in a prepare
1cdd0 64 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 53 51  d statement.  SQ
1cde0 4c 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65  L parameters are
1cdf0 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a   tokens of the.*
1ce00 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e  * form "?", "?NN
1ce10 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41 41  N", ":AAA", "$AA
1ce20 41 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74 68  A", or "@AAA" th
1ce30 61 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20 70  at serve as.** p
1ce40 6c 61 63 65 2d 68 6f 6c 64 65 72 73 20 66 6f 72  lace-holders for
1ce50 20 76 61 6c 75 65 73 20 74 68 61 74 20 61 72 65   values that are
1ce60 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
1ce70 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20  lob | bound].** 
1ce80 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  to the parameter
1ce90 73 20 61 74 20 61 20 6c 61 74 65 72 20 74 69 6d  s at a later tim
1cea0 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  e..**.** This ro
1ceb0 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72  utine actually r
1cec0 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78  eturns the index
1ced0 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20   of the largest 
1cee0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 46 6f  parameter..** Fo
1cef0 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65  r all forms exce
1cf00 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69  pt ?NNN, this wi
1cf10 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f  ll correspond to
1cf20 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
1cf30 2a 20 75 6e 69 71 75 65 20 70 61 72 61 6d 65 74  * unique paramet
1cf40 65 72 73 2e 20 20 49 66 20 70 61 72 61 6d 65 74  ers.  If paramet
1cf50 65 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20  ers of the ?NNN 
1cf60 61 72 65 20 75 73 65 64 2c 20 74 68 65 72 65 20  are used, there 
1cf70 6d 61 79 0a 2a 2a 20 62 65 20 67 61 70 73 20 69  may.** be gaps i
1cf80 6e 20 74 68 65 20 6c 69 73 74 2e 0a 2a 2a 0a 2a  n the list..**.*
1cf90 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
1cfa0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
1cfb0 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a  qlite3_bind()],.
1cfc0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
1cfd0 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
1cfe0 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
1cff0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
1d000 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a  er_index()]..**.
1d010 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
1d020 2a 0a 2a 2a 20 7b 46 31 33 36 30 31 7d 20 54 68  *.** {F13601} Th
1d030 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
1d040 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
1d050 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  S)] interface re
1d060 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20  turns.**        
1d070 20 20 74 68 65 20 6c 61 72 67 65 73 74 20 69 6e    the largest in
1d080 64 65 78 20 6f 66 20 61 6c 6c 20 53 51 4c 20 70  dex of all SQL p
1d090 61 72 61 6d 65 74 65 72 73 20 69 6e 20 74 68 65  arameters in the
1d0a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
1d0b0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1d0c0 5d 20 53 2c 20 6f 72 20 30 20 69 66 20 53 0a 2a  ] S, or 0 if S.*
1d0d0 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e 74 61  *          conta
1d0e0 69 6e 73 20 6e 6f 20 53 51 4c 20 70 61 72 61 6d  ins no SQL param
1d0f0 65 74 65 72 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71  eters..*/.int sq
1d100 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
1d110 65 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74  eter_count(sqlit
1d120 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
1d130 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65  * CAPI3REF: Name
1d140 20 4f 66 20 41 20 48 6f 73 74 20 50 61 72 61 6d   Of A Host Param
1d150 65 74 65 72 20 7b 46 31 33 36 32 30 7d 0a 2a 2a  eter {F13620}.**
1d160 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
1d170 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
1d180 65 72 20 74 6f 20 74 68 65 20 6e 61 6d 65 20 6f  er to the name o
1d190 66 20 74 68 65 20 6e 2d 74 68 0a 2a 2a 20 53 51  f the n-th.** SQ
1d1a0 4c 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 61  L parameter in a
1d1b0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1d1c0 6d 65 6e 74 5d 2e 0a 2a 2a 20 53 51 4c 20 70 61  ment]..** SQL pa
1d1d0 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20  rameters of the 
1d1e0 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22  form "?NNN" or "
1d1f0 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20  :AAA" or "@AAA" 
1d200 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 68 61 76  or "$AAA".** hav
1d210 65 20 61 20 6e 61 6d 65 20 77 68 69 63 68 20 69  e a name which i
1d220 73 20 74 68 65 20 73 74 72 69 6e 67 20 22 3f 4e  s the string "?N
1d230 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72  NN" or ":AAA" or
1d240 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41   "@AAA" or "$AAA
1d250 22 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c  ".** respectivel
1d260 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77  y..** In other w
1d270 6f 72 64 73 2c 20 74 68 65 20 69 6e 69 74 69 61  ords, the initia
1d280 6c 20 22 3a 22 20 6f 72 20 22 24 22 20 6f 72 20  l ":" or "$" or 
1d290 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73  "@" or "?".** is
1d2a0 20 69 6e 63 6c 75 64 65 64 20 61 73 20 70 61 72   included as par
1d2b0 74 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e 0a 2a  t of the name..*
1d2c0 2a 20 50 61 72 61 6d 65 74 65 72 73 20 6f 66 20  * Parameters of 
1d2d0 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 69 74  the form "?" wit
1d2e0 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67  hout a following
1d2f0 20 69 6e 74 65 67 65 72 20 68 61 76 65 20 6e 6f   integer have no
1d300 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   name..**.** The
1d310 20 66 69 72 73 74 20 68 6f 73 74 20 70 61 72 61   first host para
1d320 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64  meter has an ind
1d330 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a  ex of 1, not 0..
1d340 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 76 61 6c  **.** If the val
1d350 75 65 20 6e 20 69 73 20 6f 75 74 20 6f 66 20 72  ue n is out of r
1d360 61 6e 67 65 20 6f 72 20 69 66 20 74 68 65 20 6e  ange or if the n
1d370 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  -th parameter is
1d380 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68  .** nameless, th
1d390 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72  en NULL is retur
1d3a0 6e 65 64 2e 20 20 54 68 65 20 72 65 74 75 72 6e  ned.  The return
1d3b0 65 64 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20  ed string is.** 
1d3c0 61 6c 77 61 79 73 20 69 6e 20 74 68 65 20 55 54  always in the UT
1d3d0 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 65  F-8 encoding eve
1d3e0 6e 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20 70  n if the named p
1d3f0 61 72 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20  arameter was.** 
1d400 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 63 69  originally speci
1d410 66 69 65 64 20 61 73 20 55 54 46 2d 31 36 20 69  fied as UTF-16 i
1d420 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  n [sqlite3_prepa
1d430 72 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  re16()] or.** [s
1d440 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
1d450 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65  _v2()]..**.** Se
1d460 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
1d470 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74  _bind_blob|sqlit
1d480 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b  e3_bind()],.** [
1d490 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
1d4a0 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c  ameter_count()],
1d4b0 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
1d4c0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
1d4d0 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  index()]..**.** 
1d4e0 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
1d4f0 2a 20 7b 46 31 33 36 32 31 7d 20 54 68 65 20 5b  * {F13621} The [
1d500 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
1d510 61 6d 65 74 65 72 5f 6e 61 6d 65 28 53 2c 4e 29  ameter_name(S,N)
1d520 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
1d530 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  rns.**          
1d540 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e  a UTF-8 renderin
1d550 67 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 6f 66  g of the name of
1d560 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74   the SQL paramet
1d570 65 72 20 69 6e 0a 2a 2a 20 20 20 20 20 20 20 20  er in.**        
1d580 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74    [prepared stat
1d590 65 6d 65 6e 74 5d 20 53 20 68 61 76 69 6e 67 20  ement] S having 
1d5a0 69 6e 64 65 78 20 4e 2c 20 6f 72 0a 2a 2a 20 20  index N, or.**  
1d5b0 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 69 66 20          NULL if 
1d5c0 74 68 65 72 65 20 69 73 20 6e 6f 20 53 51 4c 20  there is no SQL 
1d5d0 70 61 72 61 6d 65 74 65 72 20 77 69 74 68 20 69  parameter with i
1d5e0 6e 64 65 78 20 4e 20 6f 72 20 69 66 20 74 68 65  ndex N or if the
1d5f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 61 72  .**          par
1d600 61 6d 65 74 65 72 20 77 69 74 68 20 69 6e 64 65  ameter with inde
1d610 78 20 4e 20 69 73 20 61 6e 20 61 6e 6f 6e 79 6d  x N is an anonym
1d620 6f 75 73 20 70 61 72 61 6d 65 74 65 72 20 22 3f  ous parameter "?
1d630 22 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  "..*/.const char
1d640 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   *sqlite3_bind_p
1d650 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71  arameter_name(sq
1d660 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
1d670 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1d680 45 46 3a 20 49 6e 64 65 78 20 4f 66 20 41 20 50  EF: Index Of A P
1d690 61 72 61 6d 65 74 65 72 20 57 69 74 68 20 41 20  arameter With A 
1d6a0 47 69 76 65 6e 20 4e 61 6d 65 20 7b 46 31 33 36  Given Name {F136
1d6b0 34 30 7d 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e  40}.**.** Return
1d6c0 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e   the index of an
1d6d0 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67   SQL parameter g
1d6e0 69 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20  iven its name.  
1d6f0 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c  The.** index val
1d700 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 73  ue returned is s
1d710 75 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20  uitable for use 
1d720 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a  as the second.**
1d730 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
1d740 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
1d750 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
1d760 2e 20 20 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20  .  A zero.** is 
1d770 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d  returned if no m
1d780 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65  atching paramete
1d790 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 54 68 65  r is found.  The
1d7a0 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61   parameter.** na
1d7b0 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e  me must be given
1d7c0 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69   in UTF-8 even i
1d7d0 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73  f the original s
1d7e0 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20  tatement.** was 
1d7f0 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54  prepared from UT
1d800 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67 20  F-16 text using 
1d810 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1d820 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  16_v2()]..**.** 
1d830 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
1d840 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c  e3_bind_blob|sql
1d850 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a  ite3_bind()],.**
1d860 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
1d870 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29  arameter_count()
1d880 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
1d890 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
1d8a0 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a  r_index()]..**.*
1d8b0 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
1d8c0 0a 2a 2a 20 7b 46 31 33 36 34 31 7d 20 54 68 65  .** {F13641} The
1d8d0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
1d8e0 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 53  arameter_index(S
1d8f0 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  ,N)] interface r
1d900 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20  eturns.**       
1d910 20 20 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20     the index of 
1d920 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 6e  SQL parameter in
1d930 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1d940 6d 65 6e 74 5d 0a 2a 2a 20 20 20 20 20 20 20 20  ment].**        
1d950 20 20 53 20 77 68 6f 73 65 20 6e 61 6d 65 20 6d    S whose name m
1d960 61 74 63 68 65 73 20 74 68 65 20 55 54 46 2d 38  atches the UTF-8
1d970 20 73 74 72 69 6e 67 20 4e 2c 20 6f 72 20 30 20   string N, or 0 
1d980 69 66 20 74 68 65 72 65 20 69 73 0a 2a 2a 20 20  if there is.**  
1d990 20 20 20 20 20 20 20 20 6e 6f 20 6d 61 74 63 68          no match
1d9a0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
1d9b0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
1d9c0 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f 73 74  index(sqlite3_st
1d9d0 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  mt*, const char 
1d9e0 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *zName);../*.** 
1d9f0 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20  CAPI3REF: Reset 
1da00 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20  All Bindings On 
1da10 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
1da20 6d 65 6e 74 20 7b 46 31 33 36 36 30 7d 0a 2a 2a  ment {F13660}.**
1da30 0a 2a 2a 20 43 6f 6e 74 72 61 72 79 20 74 6f 20  .** Contrary to 
1da40 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66  the intuition of
1da50 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f   many, [sqlite3_
1da60 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f  reset()] does no
1da70 74 0a 2a 2a 20 72 65 73 65 74 20 74 68 65 20 5b  t.** reset the [
1da80 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
1da90 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e  b | bindings] on
1daa0 20 61 20 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64   a .** [prepared
1dab0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 55 73   statement].  Us
1dac0 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74  e this routine t
1dad0 6f 0a 2a 2a 20 72 65 73 65 74 20 61 6c 6c 20 68  o.** reset all h
1dae0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 74  ost parameters t
1daf0 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 49 4e  o NULL..**.** IN
1db00 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
1db10 7b 46 31 33 36 36 31 7d 20 54 68 65 20 5b 73 71  {F13661} The [sq
1db20 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64  lite3_clear_bind
1db30 69 6e 67 73 28 53 29 5d 20 69 6e 74 65 72 66 61  ings(S)] interfa
1db40 63 65 20 72 65 73 65 74 73 20 61 6c 6c 0a 2a 2a  ce resets all.**
1db50 20 20 20 20 20 20 20 20 20 20 53 51 4c 20 70 61            SQL pa
1db60 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 73  rameter bindings
1db70 20 69 6e 20 5b 70 72 65 70 61 72 65 64 20 73 74   in [prepared st
1db80 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 20 20  atement] S.**   
1db90 20 20 20 20 20 20 20 62 61 63 6b 20 74 6f 20 4e         back to N
1dba0 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ULL..*/.int sqli
1dbb0 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e  te3_clear_bindin
1dbc0 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  gs(sqlite3_stmt*
1dbd0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1dbe0 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f  EF: Number Of Co
1dbf0 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 6c  lumns In A Resul
1dc00 74 20 53 65 74 20 7b 46 31 33 37 31 30 7d 0a 2a  t Set {F13710}.*
1dc10 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 74 68 65 20  *.** Return the 
1dc20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
1dc30 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20  s in the result 
1dc40 73 65 74 20 72 65 74 75 72 6e 65 64 20 62 79 20  set returned by 
1dc50 74 68 65 20 0a 2a 2a 20 5b 70 72 65 70 61 72 65  the .** [prepare
1dc60 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 54 68  d statement]. Th
1dc70 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  is routine retur
1dc80 6e 73 20 30 0a 2a 2a 20 69 66 20 70 53 74 6d 74  ns 0.** if pStmt
1dc90 20 69 73 20 61 6e 20 53 51 4c 20 73 74 61 74 65   is an SQL state
1dca0 6d 65 6e 74 20 74 68 61 74 20 64 6f 65 73 20 6e  ment that does n
1dcb0 6f 74 20 72 65 74 75 72 6e 20 64 61 74 61 20 28  ot return data (
1dcc0 66 6f 72 20 0a 2a 2a 20 65 78 61 6d 70 6c 65 20  for .** example 
1dcd0 61 6e 20 55 50 44 41 54 45 29 2e 0a 2a 2a 0a 2a  an UPDATE)..**.*
1dce0 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
1dcf0 0a 2a 2a 20 7b 46 31 33 37 31 31 7d 20 54 68 65  .** {F13711} The
1dd00 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
1dd10 5f 63 6f 75 6e 74 28 53 29 5d 20 69 6e 74 65 72  _count(S)] inter
1dd20 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
1dd30 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 20 20   number of.**   
1dd40 20 20 20 20 20 20 20 63 6f 6c 75 6d 6e 73 20 69         columns i
1dd50 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  n the result set
1dd60 20 67 65 6e 65 72 61 74 65 64 20 62 79 20 74 68   generated by th
1dd70 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  e.**          [p
1dd80 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1dd90 74 5d 20 53 2c 20 6f 72 20 30 20 69 66 20 53 20  t] S, or 0 if S 
1dda0 64 6f 65 73 20 6e 6f 74 20 67 65 6e 65 72 61 74  does not generat
1ddb0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20  e.**          a 
1ddc0 72 65 73 75 6c 74 20 73 65 74 2e 0a 2a 2f 0a 69  result set..*/.i
1ddd0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
1dde0 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  n_count(sqlite3_
1ddf0 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
1de00 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
1de10 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41  olumn Names In A
1de20 20 52 65 73 75 6c 74 20 53 65 74 20 7b 46 31 33   Result Set {F13
1de30 37 32 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  720}.**.** These
1de40 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
1de50 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e   the name assign
1de60 65 64 20 74 6f 20 61 20 70 61 72 74 69 63 75 6c  ed to a particul
1de70 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20  ar column.** in 
1de80 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f  the result set o
1de90 66 20 61 20 53 45 4c 45 43 54 20 73 74 61 74 65  f a SELECT state
1dea0 6d 65 6e 74 2e 20 20 54 68 65 20 73 71 6c 69 74  ment.  The sqlit
1deb0 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29  e3_column_name()
1dec0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65  .** interface re
1ded0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
1dee0 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  to a zero-termin
1def0 61 74 65 64 20 55 54 46 38 20 73 74 72 69 6e 67  ated UTF8 string
1df00 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  .** and sqlite3_
1df10 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20  column_name16() 
1df20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
1df30 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d  r to a zero-term
1df40 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 31 36 20  inated.** UTF16 
1df50 73 74 72 69 6e 67 2e 20 20 54 68 65 20 66 69 72  string.  The fir
1df60 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  st parameter is 
1df70 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
1df80 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
1df90 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20   implements the 
1dfa0 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74  SELECT statement
1dfb0 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
1dfc0 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
1dfd0 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20   column number. 
1dfe0 20 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63   The left-most c
1dff0 6f 6c 75 6d 6e 20 69 73 0a 2a 2a 20 6e 75 6d 62  olumn is.** numb
1e000 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  er 0..**.** The 
1e010 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
1e020 70 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64  pointer is valid
1e030 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68   until either th
1e040 65 20 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  e .** [prepared 
1e050 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65  statement] is de
1e060 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69  stroyed by [sqli
1e070 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a  te3_finalize()].
1e080 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  ** or until the 
1e090 6e 65 78 74 20 63 61 6c 6c 20 73 71 6c 69 74 65  next call sqlite
1e0a0 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20  3_column_name() 
1e0b0 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  or sqlite3_colum
1e0c0 6e 5f 6e 61 6d 65 31 36 28 29 0a 2a 2a 20 6f 6e  n_name16().** on
1e0d0 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e   the same column
1e0e0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 73 71 6c 69 74  ..**.** If sqlit
1e0f0 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c  e3_malloc() fail
1e100 73 20 64 75 72 69 6e 67 20 74 68 65 20 70 72 6f  s during the pro
1e110 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68 65  cessing of eithe
1e120 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f  r routine.** (fo
1e130 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e 67  r example during
1e140 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72   a conversion fr
1e150 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46 2d  om UTF-8 to UTF-
1e160 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55  16) then a.** NU
1e170 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65  LL pointer is re
1e180 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  turned..**.** Th
1e190 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65 73 75  e name of a resu
1e1a0 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65  lt column is the
1e1b0 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 22 41   value of the "A
1e1c0 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a  S" clause for.**
1e1d0 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66   that column, if
1e1e0 20 74 68 65 72 65 20 69 73 20 61 6e 20 41 53 20   there is an AS 
1e1f0 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68 65 72  clause.  If ther
1e200 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61 75 73  e is no AS claus
1e210 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e 61  e.** then the na
1e220 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  me of the column
1e230 20 69 73 20 75 6e 73 70 65 63 69 66 69 65 64 20   is unspecified 
1e240 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 20 66  and may change f
1e250 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61  rom.** one relea
1e260 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74 6f 20  se of SQLite to 
1e270 74 68 65 20 6e 65 78 74 2e 0a 2a 2a 0a 2a 2a 20  the next..**.** 
1e280 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
1e290 2a 20 7b 46 31 33 37 32 31 7d 20 41 20 73 75 63  * {F13721} A suc
1e2a0 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69  cessful invocati
1e2b0 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  on of the [sqlit
1e2c0 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 53  e3_column_name(S
1e2d0 2c 4e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ,N)].**         
1e2e0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
1e2f0 6e 73 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 20  ns the name.**  
1e300 20 20 20 20 20 20 20 20 6f 66 20 74 68 65 20 4e          of the N
1e310 74 68 20 63 6f 6c 75 6d 6e 20 28 77 68 65 72 65  th column (where
1e320 20 30 20 69 73 20 74 68 65 20 6c 65 66 74 2d 6d   0 is the left-m
1e330 6f 73 74 20 63 6f 6c 75 6d 6e 29 20 66 6f 72 20  ost column) for 
1e340 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
1e350 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 5b 70  result set of [p
1e360 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1e370 74 5d 20 53 20 61 73 20 61 0a 2a 2a 20 20 20 20  t] S as a.**    
1e380 20 20 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69        zero-termi
1e390 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69  nated UTF-8 stri
1e3a0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 32  ng..**.** {F1372
1e3b0 33 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20  3} A successful 
1e3c0 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68  invocation of th
1e3d0 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
1e3e0 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 0a 2a  n_name16(S,N)].*
1e3f0 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 72  *          inter
1e400 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
1e410 20 6e 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20   name.**        
1e420 20 20 6f 66 20 74 68 65 20 4e 74 68 20 63 6f 6c    of the Nth col
1e430 75 6d 6e 20 28 77 68 65 72 65 20 30 20 69 73 20  umn (where 0 is 
1e440 74 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f  the left-most co
1e450 6c 75 6d 6e 29 20 66 6f 72 20 74 68 65 0a 2a 2a  lumn) for the.**
1e460 20 20 20 20 20 20 20 20 20 20 72 65 73 75 6c 74            result
1e470 20 73 65 74 20 6f 66 20 5b 70 72 65 70 61 72 65   set of [prepare
1e480 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 61  d statement] S a
1e490 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  s a.**          
1e4a0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
1e4b0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e  UTF-16 string in
1e4c0 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
1e4d0 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46   order..**.** {F
1e4e0 31 33 37 32 34 7d 20 54 68 65 20 5b 73 71 6c 69  13724} The [sqli
1e4f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
1e500 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
1e510 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 5d  column_name16()]
1e520 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74  .**          int
1e530 65 72 66 61 63 65 73 20 72 65 74 75 72 6e 20 61  erfaces return a
1e540 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66   NULL pointer if
1e550 20 74 68 65 79 20 61 72 65 20 75 6e 61 62 6c 65   they are unable
1e560 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   to.**          
1e570 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20  allocate memory 
1e580 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  memory to hold t
1e590 68 65 72 65 20 6e 6f 72 6d 61 6c 20 72 65 74 75  here normal retu
1e5a0 72 6e 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 0a 2a  rn strings..**.*
1e5b0 2a 20 7b 46 31 33 37 32 35 7d 20 49 66 20 74 68  * {F13725} If th
1e5c0 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 74 6f  e N parameter to
1e5d0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
1e5e0 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 6f 72 0a 2a  _name(S,N)] or.*
1e5f0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
1e600 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
1e610 36 28 53 2c 4e 29 5d 20 69 73 20 6f 75 74 20 6f  6(S,N)] is out o
1e620 66 20 72 61 6e 67 65 2c 20 74 68 65 6e 20 74 68  f range, then th
1e630 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  e.**          in
1e640 74 65 72 66 61 63 65 73 20 72 65 74 75 72 6e 73  terfaces returns
1e650 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
1e660 0a 2a 2a 20 0a 2a 2a 20 7b 46 31 33 37 32 36 7d  .** .** {F13726}
1e670 20 54 68 65 20 73 74 72 69 6e 67 73 20 72 65 74   The strings ret
1e680 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
1e690 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 53 2c  3_column_name(S,
1e6a0 4e 29 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20  N)] and.**      
1e6b0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c      [sqlite3_col
1e6c0 75 6d 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d  umn_name16(S,N)]
1e6d0 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c   are valid until
1e6e0 20 74 68 65 20 6e 65 78 74 0a 2a 2a 20 20 20 20   the next.**    
1e6f0 20 20 20 20 20 20 63 61 6c 6c 20 74 6f 20 65 69        call to ei
1e700 74 68 65 72 20 72 6f 75 74 69 6e 65 20 77 69 74  ther routine wit
1e710 68 20 74 68 65 20 73 61 6d 65 20 53 20 61 6e 64  h the same S and
1e720 20 4e 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a   N parameters.**
1e730 20 20 20 20 20 20 20 20 20 20 6f 72 20 75 6e 74            or unt
1e740 69 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  il [sqlite3_fina
1e750 6c 69 7a 65 28 53 29 5d 20 69 73 20 63 61 6c 6c  lize(S)] is call
1e760 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 32  ed..**.** {F1372
1e770 37 7d 20 57 68 65 6e 20 61 20 72 65 73 75 6c 74  7} When a result
1e780 20 63 6f 6c 75 6d 6e 20 6f 66 20 61 20 5b 53 45   column of a [SE
1e790 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20  LECT] statement 
1e7a0 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 20 20 20 20  contains.**     
1e7b0 20 20 20 20 20 61 6e 20 41 53 20 63 6c 61 75 73       an AS claus
1e7c0 65 2c 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  e, the name of t
1e7d0 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68  hat column is th
1e7e0 65 20 69 6e 64 65 6e 74 69 66 69 65 72 0a 2a 2a  e indentifier.**
1e7f0 20 20 20 20 20 20 20 20 20 20 74 6f 20 74 68 65            to the
1e800 20 72 69 67 68 74 20 6f 66 20 74 68 65 20 41 53   right of the AS
1e810 20 6b 65 79 77 6f 72 64 2e 0a 2a 2f 0a 63 6f 6e   keyword..*/.con
1e820 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
1e830 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c  _column_name(sql
1e840 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
1e850 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  N);.const void *
1e860 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
1e870 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
1e880 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a  mt*, int N);../*
1e890 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 6f  .** CAPI3REF: So
1e8a0 75 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e 20  urce Of Data In 
1e8b0 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 20 7b  A Query Result {
1e8c0 46 31 33 37 34 30 7d 0a 2a 2a 0a 2a 2a 20 54 68  F13740}.**.** Th
1e8d0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 70 72 6f  ese routines pro
1e8e0 76 69 64 65 20 61 20 6d 65 61 6e 73 20 74 6f 20  vide a means to 
1e8f0 64 65 74 65 72 6d 69 6e 65 20 77 68 61 74 20 63  determine what c
1e900 6f 6c 75 6d 6e 20 6f 66 20 77 68 61 74 0a 2a 2a  olumn of what.**
1e910 20 74 61 62 6c 65 20 69 6e 20 77 68 69 63 68 20   table in which 
1e920 64 61 74 61 62 61 73 65 20 61 20 72 65 73 75 6c  database a resul
1e930 74 20 6f 66 20 61 20 53 45 4c 45 43 54 20 73 74  t of a SELECT st
1e940 61 74 65 6d 65 6e 74 20 63 6f 6d 65 73 20 66 72  atement comes fr
1e950 6f 6d 2e 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20  om..** The name 
1e960 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
1e970 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75  or table or colu
1e980 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 75 72 6e  mn can be return
1e990 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 20  ed as.** either 
1e9a0 61 20 55 54 46 38 20 6f 72 20 55 54 46 31 36 20  a UTF8 or UTF16 
1e9b0 73 74 72 69 6e 67 2e 20 20 54 68 65 20 5f 64 61  string.  The _da
1e9c0 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73  tabase_ routines
1e9d0 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64   return.** the d
1e9e0 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68  atabase name, th
1e9f0 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e  e _table_ routin
1ea00 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 74 61  es return the ta
1ea10 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a  ble name, and.**
1ea20 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75   the origin_ rou
1ea30 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65  tines return the
1ea40 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a   column name..**
1ea50 20 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74   The returned st
1ea60 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75 6e  ring is valid un
1ea70 74 69 6c 0a 2a 2a 20 74 68 65 20 5b 70 72 65 70  til.** the [prep
1ea80 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
1ea90 69 73 20 64 65 73 74 72 6f 79 65 64 20 75 73 69  is destroyed usi
1eaa0 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  ng.** [sqlite3_f
1eab0 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e  inalize()] or un
1eac0 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69 6e 66  til the same inf
1ead0 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 71 75  ormation is requ
1eae0 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69  ested.** again i
1eaf0 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20 65 6e  n a different en
1eb00 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68  coding..**.** Th
1eb10 65 20 6e 61 6d 65 73 20 72 65 74 75 72 6e 65 64  e names returned
1eb20 20 61 72 65 20 74 68 65 20 6f 72 69 67 69 6e 61   are the origina
1eb30 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d  l un-aliased nam
1eb40 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74  es of the.** dat
1eb50 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e  abase, table, an
1eb60 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20  d column..**.** 
1eb70 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
1eb80 6e 74 20 74 6f 20 74 68 65 20 66 6f 6c 6c 6f 77  nt to the follow
1eb90 69 6e 67 20 63 61 6c 6c 73 20 69 73 20 61 20 5b  ing calls is a [
1eba0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1ebb0 6e 74 5d 2e 0a 2a 2a 20 54 68 65 73 65 20 66 75  nt]..** These fu
1ebc0 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 69  nctions return i
1ebd0 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74  nformation about
1ebe0 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
1ebf0 72 65 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20  returned by .** 
1ec00 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 77  the statement, w
1ec10 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65  here N is the se
1ec20 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72  cond function ar
1ec30 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 49 66  gument..**.** If
1ec40 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
1ec50 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20  returned by the 
1ec60 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 6e 20  statement is an 
1ec70 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 6f 72  expression.** or
1ec80 20 73 75 62 71 75 65 72 79 20 61 6e 64 20 69 73   subquery and is
1ec90 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61   not a column va
1eca0 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66  lue, then all of
1ecb0 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
1ecc0 0a 2a 2a 20 72 65 74 75 72 6e 20 4e 55 4c 4c 2e  .** return NULL.
1ecd0 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 20    These routine 
1ece0 6d 69 67 68 74 20 61 6c 73 6f 20 72 65 74 75 72  might also retur
1ecf0 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f  n NULL if a memo
1ed00 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e  ry.** allocation
1ed10 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20   error occurs.  
1ed20 4f 74 68 65 72 77 69 73 65 2c 20 74 68 65 79 20  Otherwise, they 
1ed30 72 65 74 75 72 6e 20 74 68 65 20 0a 2a 2a 20 6e  return the .** n
1ed40 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74 61 63  ame of the attac
1ed50 68 65 64 20 64 61 74 61 62 61 73 65 2c 20 74 61  hed database, ta
1ed60 62 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 74  ble and column t
1ed70 68 61 74 20 71 75 65 72 79 20 72 65 73 75 6c 74  hat query result
1ed80 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65  .** column was e
1ed90 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a  xtracted from..*
1eda0 2a 0a 2a 2a 20 41 73 20 77 69 74 68 20 61 6c 6c  *.** As with all
1edb0 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 41 50   other SQLite AP
1edc0 49 73 2c 20 74 68 6f 73 65 20 70 6f 73 74 66 69  Is, those postfi
1edd0 78 65 64 20 77 69 74 68 20 22 31 36 22 20 72 65  xed with "16" re
1ede0 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65  turn.** UTF-16 e
1edf0 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 73 2c 20  ncoded strings, 
1ee00 74 68 65 20 6f 74 68 65 72 20 66 75 6e 63 74 69  the other functi
1ee10 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 46 2d 38  ons return UTF-8
1ee20 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68  . {END}.**.** Th
1ee30 65 73 65 20 41 50 49 73 20 61 72 65 20 6f 6e 6c  ese APIs are onl
1ee40 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74  y available if t
1ee50 68 65 20 6c 69 62 72 61 72 79 20 77 61 73 20 63  he library was c
1ee60 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65  ompiled with the
1ee70 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 45 4e 41 42   .** SQLITE_ENAB
1ee80 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41  LE_COLUMN_METADA
1ee90 54 41 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20  TA preprocessor 
1eea0 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a  symbol defined..
1eeb0 2a 2a 0a 2a 2a 20 7b 55 31 33 37 35 31 7d 0a 2a  **.** {U13751}.*
1eec0 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65  * If two or more
1eed0 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e   threads call on
1eee0 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65  e or more of the
1eef0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 67 61 69  se routines agai
1ef00 6e 73 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20  nst the same.** 
1ef10 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1ef20 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74  nt and column at
1ef30 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74   the same time t
1ef40 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20  hen the results 
1ef50 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64  are.** undefined
1ef60 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
1ef70 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 34  TS:.**.** {F1374
1ef80 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
1ef90 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
1efa0 6e 61 6d 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72  name(S,N)] inter
1efb0 66 61 63 65 20 72 65 74 75 72 6e 73 20 65 69 74  face returns eit
1efc0 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  her.**          
1efd0 74 68 65 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74  the UTF-8 zero-t
1efe0 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f  erminated name o
1eff0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  f the database f
1f000 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20 0a 2a  rom which the .*
1f010 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 72  *          Nth r
1f020 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20  esult column of 
1f030 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
1f040 65 6e 74 5d 20 53 20 0a 2a 2a 20 20 20 20 20 20  ent] S .**      
1f050 20 20 20 20 69 73 20 65 78 74 72 61 63 74 65 64      is extracted
1f060 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65  , or NULL if the
1f070 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
1f080 6f 66 20 53 20 69 73 20 61 0a 2a 2a 20 20 20 20  of S is a.**    
1f090 20 20 20 20 20 20 67 65 6e 65 72 61 6c 20 65 78        general ex
1f0a0 70 72 65 73 73 69 6f 6e 20 6f 72 20 69 66 20 75  pression or if u
1f0b0 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74  nable to allocat
1f0c0 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20 20 20  e memory.**     
1f0d0 20 20 20 20 20 74 6f 20 73 74 6f 72 65 20 74 68       to store th
1f0e0 65 20 6e 61 6d 65 2e 0a 2a 2a 20 20 20 20 20 20  e name..**      
1f0f0 20 20 20 20 0a 2a 2a 20 7b 46 31 33 37 34 32 7d      .** {F13742}
1f100 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
1f110 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61  lumn_database_na
1f120 6d 65 31 36 28 53 2c 4e 29 5d 20 69 6e 74 65 72  me16(S,N)] inter
1f130 66 61 63 65 20 72 65 74 75 72 6e 73 20 65 69 74  face returns eit
1f140 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  her.**          
1f150 74 68 65 20 55 54 46 2d 31 36 20 6e 61 74 69 76  the UTF-16 nativ
1f160 65 20 62 79 74 65 20 6f 72 64 65 72 0a 2a 2a 20  e byte order.** 
1f170 20 20 20 20 20 20 20 20 20 7a 65 72 6f 2d 74 65           zero-te
1f180 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66  rminated name of
1f190 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 72   the database fr
1f1a0 6f 6d 20 77 68 69 63 68 20 74 68 65 20 0a 2a 2a  om which the .**
1f1b0 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 72 65            Nth re
1f1c0 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 5b  sult column of [
1f1d0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1f1e0 6e 74 5d 20 53 20 0a 2a 2a 20 20 20 20 20 20 20  nt] S .**       
1f1f0 20 20 20 69 73 20 65 78 74 72 61 63 74 65 64 2c     is extracted,
1f200 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20   or NULL if the 
1f210 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f  the Nth column o
1f220 66 20 53 20 69 73 20 61 0a 2a 2a 20 20 20 20 20  f S is a.**     
1f230 20 20 20 20 20 67 65 6e 65 72 61 6c 20 65 78 70       general exp
1f240 72 65 73 73 69 6f 6e 20 6f 72 20 69 66 20 75 6e  ression or if un
1f250 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  able to allocate
1f260 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20 20 20 20   memory.**      
1f270 20 20 20 20 74 6f 20 73 74 6f 72 65 20 74 68 65      to store the
1f280 20 6e 61 6d 65 2e 0a 2a 2a 20 20 20 20 20 20 20   name..**       
1f290 20 20 20 0a 2a 2a 20 7b 46 31 33 37 34 33 7d 20     .** {F13743} 
1f2a0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  The [sqlite3_col
1f2b0 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 53  umn_table_name(S
1f2c0 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  ,N)] interface r
1f2d0 65 74 75 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a  eturns either.**
1f2e0 20 20 20 20 20 20 20 20 20 20 74 68 65 20 55 54            the UT
1f2f0 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  F-8 zero-termina
1f300 74 65 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  ted name of the 
1f310 74 61 62 6c 65 20 66 72 6f 6d 20 77 68 69 63 68  table from which
1f320 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 20 20 20   the .**        
1f330 20 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c    Nth result col
1f340 75 6d 6e 20 6f 66 20 5b 70 72 65 70 61 72 65 64  umn of [prepared
1f350 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 0a 2a   statement] S .*
1f360 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 65 78  *          is ex
1f370 74 72 61 63 74 65 64 2c 20 6f 72 20 4e 55 4c 4c  tracted, or NULL
1f380 20 69 66 20 74 68 65 20 74 68 65 20 4e 74 68 20   if the the Nth 
1f390 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20 61  column of S is a
1f3a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 67 65 6e  .**          gen
1f3b0 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e 20  eral expression 
1f3c0 6f 72 20 69 66 20 75 6e 61 62 6c 65 20 74 6f 20  or if unable to 
1f3d0 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 0a  allocate memory.
1f3e0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 73  **          to s
1f3f0 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a  tore the name..*
1f400 2a 20 20 20 20 20 20 20 20 20 20 0a 2a 2a 20 7b  *          .** {
1f410 46 31 33 37 34 34 7d 20 54 68 65 20 5b 73 71 6c  F13744} The [sql
1f420 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c  ite3_column_tabl
1f430 65 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20 69  e_name16(S,N)] i
1f440 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
1f450 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20   either.**      
1f460 20 20 20 20 74 68 65 20 55 54 46 2d 31 36 20 6e      the UTF-16 n
1f470 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
1f480 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72  .**          zer
1f490 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d  o-terminated nam
1f4a0 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 66  e of the table f
1f4b0 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20 0a 2a  rom which the .*
1f4c0 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 72  *          Nth r
1f4d0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20  esult column of 
1f4e0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
1f4f0 65 6e 74 5d 20 53 20 0a 2a 2a 20 20 20 20 20 20  ent] S .**      
1f500 20 20 20 20 69 73 20 65 78 74 72 61 63 74 65 64      is extracted
1f510 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65  , or NULL if the
1f520 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
1f530 6f 66 20 53 20 69 73 20 61 0a 2a 2a 20 20 20 20  of S is a.**    
1f540 20 20 20 20 20 20 67 65 6e 65 72 61 6c 20 65 78        general ex
1f550 70 72 65 73 73 69 6f 6e 20 6f 72 20 69 66 20 75  pression or if u
1f560 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74  nable to allocat
1f570 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20 20 20  e memory.**     
1f580 20 20 20 20 20 74 6f 20 73 74 6f 72 65 20 74 68       to store th
1f590 65 20 6e 61 6d 65 2e 0a 2a 2a 20 20 20 20 20 20  e name..**      
1f5a0 20 20 20 20 0a 2a 2a 20 7b 46 31 33 37 34 35 7d      .** {F13745}
1f5b0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
1f5c0 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65  lumn_origin_name
1f5d0 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  (S,N)] interface
1f5e0 20 72 65 74 75 72 6e 73 20 65 69 74 68 65 72 0a   returns either.
1f5f0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
1f600 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69  UTF-8 zero-termi
1f610 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66 20 74 68  nated name of th
1f620 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 66  e table column f
1f630 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20 0a 2a  rom which the .*
1f640 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 72  *          Nth r
1f650 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20  esult column of 
1f660 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
1f670 65 6e 74 5d 20 53 20 0a 2a 2a 20 20 20 20 20 20  ent] S .**      
1f680 20 20 20 20 69 73 20 65 78 74 72 61 63 74 65 64      is extracted
1f690 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65  , or NULL if the
1f6a0 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
1f6b0 6f 66 20 53 20 69 73 20 61 0a 2a 2a 20 20 20 20  of S is a.**    
1f6c0 20 20 20 20 20 20 67 65 6e 65 72 61 6c 20 65 78        general ex
1f6d0 70 72 65 73 73 69 6f 6e 20 6f 72 20 69 66 20 75  pression or if u
1f6e0 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74  nable to allocat
1f6f0 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20 20 20  e memory.**     
1f700 20 20 20 20 20 74 6f 20 73 74 6f 72 65 20 74 68       to store th
1f710 65 20 6e 61 6d 65 2e 0a 2a 2a 20 20 20 20 20 20  e name..**      
1f720 20 20 20 20 0a 2a 2a 20 7b 46 31 33 37 34 36 7d      .** {F13746}
1f730 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
1f740 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65  lumn_origin_name
1f750 31 36 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61  16(S,N)] interfa
1f760 63 65 20 72 65 74 75 72 6e 73 20 65 69 74 68 65  ce returns eithe
1f770 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  r.**          th
1f780 65 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20  e UTF-16 native 
1f790 62 79 74 65 20 6f 72 64 65 72 0a 2a 2a 20 20 20  byte order.**   
1f7a0 20 20 20 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d         zero-term
1f7b0 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66 20 74  inated name of t
1f7c0 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20  he table column 
1f7d0 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20 0a  from which the .
1f7e0 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20  **          Nth 
1f7f0 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66  result column of
1f800 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1f810 6d 65 6e 74 5d 20 53 20 0a 2a 2a 20 20 20 20 20  ment] S .**     
1f820 20 20 20 20 20 69 73 20 65 78 74 72 61 63 74 65       is extracte
1f830 64 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68  d, or NULL if th
1f840 65 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  e the Nth column
1f850 20 6f 66 20 53 20 69 73 20 61 0a 2a 2a 20 20 20   of S is a.**   
1f860 20 20 20 20 20 20 20 67 65 6e 65 72 61 6c 20 65         general e
1f870 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 69 66 20  xpression or if 
1f880 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61  unable to alloca
1f890 74 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20 20  te memory.**    
1f8a0 20 20 20 20 20 20 74 6f 20 73 74 6f 72 65 20 74        to store t
1f8b0 68 65 20 6e 61 6d 65 2e 0a 2a 2a 20 20 20 20 20  he name..**     
1f8c0 20 20 20 20 20 0a 2a 2a 20 7b 46 31 33 37 34 38       .** {F13748
1f8d0 7d 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c  } The return val
1f8e0 75 65 73 20 66 72 6f 6d 0a 2a 2a 20 20 20 20 20  ues from.**     
1f8f0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f       [sqlite3_co
1f900 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61  lumn_database_na
1f910 6d 65 7c 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61  me|column metada
1f920 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a  ta interfaces].*
1f930 2a 20 20 20 20 20 20 20 20 20 20 61 72 65 20 76  *          are v
1f940 61 6c 69 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  alid.**         
1f950 20 66 6f 72 20 74 68 65 20 6c 69 66 65 74 69 6d   for the lifetim
1f960 65 20 6f 66 20 74 68 65 20 5b 70 72 65 70 61 72  e of the [prepar
1f970 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a  ed statement].**
1f980 20 20 20 20 20 20 20 20 20 20 6f 72 20 75 6e 74            or unt
1f990 69 6c 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  il the encoding 
1f9a0 69 73 20 63 68 61 6e 67 65 64 20 62 79 20 61 6e  is changed by an
1f9b0 6f 74 68 65 72 20 6d 65 74 61 64 61 74 61 0a 2a  other metadata.*
1f9c0 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 72  *          inter
1f9d0 66 61 63 65 20 63 61 6c 6c 20 66 6f 72 20 74 68  face call for th
1f9e0 65 20 73 61 6d 65 20 70 72 65 70 61 72 65 64 20  e same prepared 
1f9f0 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f  statement and co
1fa00 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49  lumn..**.** LIMI
1fa10 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b  TATIONS:.**.** {
1fa20 55 31 33 37 35 31 7d 20 49 66 20 74 77 6f 20 6f  U13751} If two o
1fa30 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63  r more threads c
1fa40 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a  all one or more.
1fa50 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
1fa60 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61  ite3_column_data
1fa70 62 61 73 65 5f 6e 61 6d 65 7c 63 6f 6c 75 6d 6e  base_name|column
1fa80 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72 66   metadata interf
1fa90 61 63 65 73 5d 0a 2a 2a 20 20 20 20 20 20 20 20  aces].**        
1faa0 20 20 74 68 65 20 73 61 6d 65 20 5b 70 72 65 70    the same [prep
1fab0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
1fac0 61 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  and result colum
1fad0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 74  n.**          at
1fae0 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74   the same time t
1faf0 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20  hen the results 
1fb00 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
1fb10 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
1fb20 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74  lite3_column_dat
1fb30 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74  abase_name(sqlit
1fb40 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
1fb50 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
1fb60 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61  e3_column_databa
1fb70 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  se_name16(sqlite
1fb80 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
1fb90 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
1fba0 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e  3_column_table_n
1fbb0 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
1fbc0 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f  *,int);.const vo
1fbd0 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
1fbe0 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28  mn_table_name16(
1fbf0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
1fc00 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  t);.const char *
1fc10 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f  sqlite3_column_o
1fc20 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74  rigin_name(sqlit
1fc30 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
1fc40 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
1fc50 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e  e3_column_origin
1fc60 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
1fc70 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a  stmt*,int);../*.
1fc80 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 63  ** CAPI3REF: Dec
1fc90 6c 61 72 65 64 20 44 61 74 61 74 79 70 65 20 4f  lared Datatype O
1fca0 66 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74  f A Query Result
1fcb0 20 7b 46 31 33 37 36 30 7d 0a 2a 2a 0a 2a 2a 20   {F13760}.**.** 
1fcc0 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
1fcd0 74 65 72 20 69 73 20 61 20 5b 70 72 65 70 61 72  ter is a [prepar
1fce0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 0a  ed statement]. .
1fcf0 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61 74 65  ** If this state
1fd00 6d 65 6e 74 20 69 73 20 61 20 53 45 4c 45 43 54  ment is a SELECT
1fd10 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74   statement and t
1fd20 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66  he Nth column of
1fd30 20 74 68 65 20 0a 2a 2a 20 72 65 74 75 72 6e 65   the .** returne
1fd40 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  d result set of 
1fd50 74 68 61 74 20 53 45 4c 45 43 54 20 69 73 20 61  that SELECT is a
1fd60 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e   table column (n
1fd70 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73  ot an.** express
1fd80 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 29  ion or subquery)
1fd90 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61 72   then the declar
1fda0 65 64 20 74 79 70 65 20 6f 66 20 74 68 65 20 74  ed type of the t
1fdb0 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69  able.** column i
1fdc0 73 20 72 65 74 75 72 6e 65 64 2e 20 20 49 66 20  s returned.  If 
1fdd0 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f  the Nth column o
1fde0 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
1fdf0 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73   is an.** expres
1fe00 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79  sion or subquery
1fe10 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f  , then a NULL po
1fe20 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65  inter is returne
1fe30 64 2e 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 6e  d..** The return
1fe40 65 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c 77  ed string is alw
1fe50 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  ays UTF-8 encode
1fe60 64 2e 20 20 7b 45 4e 44 7d 20 0a 2a 2a 20 46 6f  d.  {END} .** Fo
1fe70 72 20 65 78 61 6d 70 6c 65 2c 20 69 6e 20 74 68  r example, in th
1fe80 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d  e database schem
1fe90 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20  a:.**.** CREATE 
1fea0 54 41 42 4c 45 20 74 31 28 63 31 20 56 41 52 49  TABLE t1(c1 VARI
1feb0 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 41 6e 64 20  ANT);.**.** And 
1fec0 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74  the following st
1fed0 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 64  atement compiled
1fee0 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63  :.**.** SELECT c
1fef0 31 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74  1 + 1, c1 FROM t
1ff00 31 3b 0a 2a 2a 0a 2a 2a 20 54 68 65 6e 20 74 68  1;.**.** Then th
1ff10 69 73 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64  is routine would
1ff20 20 72 65 74 75 72 6e 20 74 68 65 20 73 74 72 69   return the stri
1ff30 6e 67 20 22 56 41 52 49 41 4e 54 22 20 66 6f 72  ng "VARIANT" for
1ff40 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 72   the second.** r
1ff50 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d  esult column (i=
1ff60 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20  =1), and a NULL 
1ff70 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65 20  pointer for the 
1ff80 66 69 72 73 74 20 72 65 73 75 6c 74 20 63 6f 6c  first result col
1ff90 75 6d 6e 0a 2a 2a 20 28 69 3d 3d 30 29 2e 0a 2a  umn.** (i==0)..*
1ffa0 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73  *.** SQLite uses
1ffb0 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d   dynamic run-tim
1ffc0 65 20 74 79 70 69 6e 67 2e 20 20 53 6f 20 6a 75  e typing.  So ju
1ffd0 73 74 20 62 65 63 61 75 73 65 20 61 20 63 6f 6c  st because a col
1ffe0 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72  umn.** is declar
1fff0 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20  ed to contain a 
20000 70 61 72 74 69 63 75 6c 61 72 20 74 79 70 65 20  particular type 
20010 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68  does not mean th
20020 61 74 20 74 68 65 0a 2a 2a 20 64 61 74 61 20 73  at the.** data s
20030 74 6f 72 65 64 20 69 6e 20 74 68 61 74 20 63 6f  tored in that co
20040 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68 65 20 64  lumn is of the d
20050 65 63 6c 61 72 65 64 20 74 79 70 65 2e 20 20 53  eclared type.  S
20060 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f  QLite is.** stro
20070 6e 67 6c 79 20 74 79 70 65 64 2c 20 62 75 74 20  ngly typed, but 
20080 74 68 65 20 74 79 70 69 6e 67 20 69 73 20 64 79  the typing is dy
20090 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61 74 69 63  namic not static
200a0 2e 20 20 54 79 70 65 0a 2a 2a 20 69 73 20 61 73  .  Type.** is as
200b0 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 69 6e  sociated with in
200c0 64 69 76 69 64 75 61 6c 20 76 61 6c 75 65 73 2c  dividual values,
200d0 20 6e 6f 74 20 77 69 74 68 20 74 68 65 20 63 6f   not with the co
200e0 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64  ntainers.** used
200f0 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20 76   to hold those v
20100 61 6c 75 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  alues..**.** INV
20110 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
20120 46 31 33 37 36 31 7d 20 20 41 20 73 75 63 63 65  F13761}  A succe
20130 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73  ssful call to [s
20140 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65  qlite3_column_de
20150 63 6c 74 79 70 65 28 53 2c 4e 29 5d 0a 2a 2a 20  cltype(S,N)].** 
20160 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e            return
20170 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  s a zero-termina
20180 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67  ted UTF-8 string
20190 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 0a   containing the.
201a0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 68 65  **           the
201b0 20 64 65 63 6c 61 72 65 64 20 64 61 74 61 74 79   declared dataty
201c0 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20  pe of the table 
201d0 63 6f 6c 75 6d 6e 20 74 68 61 74 20 61 70 70 65  column that appe
201e0 61 72 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ars.**          
201f0 20 61 73 20 74 68 65 20 4e 74 68 20 63 6f 6c 75   as the Nth colu
20200 6d 6e 20 28 6e 75 6d 62 65 72 65 64 20 66 72 6f  mn (numbered fro
20210 6d 20 30 29 20 6f 66 20 74 68 65 20 72 65 73 75  m 0) of the resu
20220 6c 74 20 73 65 74 20 74 6f 20 74 68 65 0a 2a 2a  lt set to the.**
20230 20 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70             [prep
20240 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
20250 53 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 36 32  S..**.** {F13762
20260 7d 20 20 41 20 73 75 63 63 65 73 73 66 75 6c 20  }  A successful 
20270 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
20280 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65  _column_decltype
20290 31 36 28 53 2c 4e 29 5d 0a 2a 2a 20 20 20 20 20  16(S,N)].**     
202a0 20 20 20 20 20 20 72 65 74 75 72 6e 73 20 61 20        returns a 
202b0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
202c0 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79  UTF-16 native by
202d0 74 65 20 6f 72 64 65 72 20 73 74 72 69 6e 67 0a  te order string.
202e0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 63 6f 6e  **           con
202f0 74 61 69 6e 69 6e 67 20 74 68 65 20 64 65 63 6c  taining the decl
20300 61 72 65 64 20 64 61 74 61 74 79 70 65 20 6f 66  ared datatype of
20310 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d   the table colum
20320 6e 20 74 68 61 74 20 61 70 70 65 61 72 73 0a 2a  n that appears.*
20330 2a 20 20 20 20 20 20 20 20 20 20 20 61 73 20 74  *           as t
20340 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 28 6e  he Nth column (n
20350 75 6d 62 65 72 65 64 20 66 72 6f 6d 20 30 29 20  umbered from 0) 
20360 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
20370 74 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20  t to the.**     
20380 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20        [prepared 
20390 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2a  statement] S..**
203a0 0a 2a 2a 20 7b 46 31 33 37 36 33 7d 20 20 49 66  .** {F13763}  If
203b0 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20   N is less than 
203c0 30 20 6f 72 20 4e 20 69 73 20 67 72 65 61 74 65  0 or N is greate
203d0 72 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20  r than or equal 
203e0 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  to.**           
203f0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  the number of co
20400 6c 75 6d 6e 73 20 69 6e 20 5b 70 72 65 70 61 72  lumns in [prepar
20410 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a  ed statement] S.
20420 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6f 72 20  **           or 
20430 69 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  if the Nth colum
20440 6e 20 6f 66 20 53 20 69 73 20 61 6e 20 65 78 70  n of S is an exp
20450 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75  ression or subqu
20460 65 72 79 20 72 61 74 68 65 72 0a 2a 2a 20 20 20  ery rather.**   
20470 20 20 20 20 20 20 20 20 74 68 61 6e 20 61 20 74          than a t
20480 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 6f 72 20 69  able column or i
20490 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  f a memory alloc
204a0 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 0a 2a 2a  ation failure.**
204b0 20 20 20 20 20 20 20 20 20 20 20 6f 63 63 75 72             occur
204c0 73 20 64 75 72 69 6e 67 20 65 6e 63 6f 64 69 6e  s during encodin
204d0 67 20 63 6f 6e 76 65 72 73 69 6f 6e 73 2c 20 74  g conversions, t
204e0 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  hen.**          
204f0 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
20500 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79  e3_column_declty
20510 70 65 28 53 2c 4e 29 5d 20 6f 72 0a 2a 2a 20 20  pe(S,N)] or.**  
20520 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
20530 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70  3_column_decltyp
20540 65 31 36 28 53 2c 4e 29 5d 20 72 65 74 75 72 6e  e16(S,N)] return
20550 20 4e 55 4c 4c 2e 0a 2a 2f 0a 63 6f 6e 73 74 20   NULL..*/.const 
20560 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
20570 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71  lumn_decltype(sq
20580 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
20590 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
205a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63  lite3_column_dec
205b0 6c 74 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f  ltype16(sqlite3_
205c0 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 20  stmt*,int);../* 
205d0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 45  .** CAPI3REF:  E
205e0 76 61 6c 75 61 74 65 20 41 6e 20 53 51 4c 20 53  valuate An SQL S
205f0 74 61 74 65 6d 65 6e 74 20 7b 46 31 33 32 30 30  tatement {F13200
20600 7d 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 6e  }.**.** After an
20610 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
20620 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70  ment] has been p
20630 72 65 70 61 72 65 64 20 77 69 74 68 20 61 20 63  repared with a c
20640 61 6c 6c 0a 2a 2a 20 74 6f 20 65 69 74 68 65 72  all.** to either
20650 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
20660 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69  e_v2()] or [sqli
20670 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
20680 28 29 5d 20 6f 72 20 74 6f 20 6f 6e 65 20 6f 66  ()] or to one of
20690 0a 2a 2a 20 74 68 65 20 6c 65 67 61 63 79 20 69  .** the legacy i
206a0 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74  nterfaces [sqlit
206b0 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72  e3_prepare()] or
206c0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
206d0 65 31 36 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20  e16()],.** then 
206e0 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d 75  this function mu
206f0 73 74 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65  st be called one
20700 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74   or more times t
20710 6f 20 65 76 61 6c 75 61 74 65 20 74 68 65 20 0a  o evaluate the .
20720 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a  ** statement..**
20730 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20  .** The details 
20740 6f 66 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  of the behavior 
20750 6f 66 20 74 68 69 73 20 73 71 6c 69 74 65 33 5f  of this sqlite3_
20760 73 74 65 70 28 29 20 69 6e 74 65 72 66 61 63 65  step() interface
20770 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68   depend.** on wh
20780 65 74 68 65 72 20 74 68 65 20 73 74 61 74 65 6d  ether the statem
20790 65 6e 74 20 77 61 73 20 70 72 65 70 61 72 65 64  ent was prepared
207a0 20 75 73 69 6e 67 20 74 68 65 20 6e 65 77 65 72   using the newer
207b0 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 0a   "v2" interface.
207c0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
207d0 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73  are_v2()] and [s
207e0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
207f0 5f 76 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c  _v2()] or the ol
20800 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e  der legacy.** in
20810 74 65 72 66 61 63 65 20 5b 73 71 6c 69 74 65 33  terface [sqlite3
20820 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20  _prepare()] and 
20830 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
20840 31 36 28 29 5d 2e 20 20 54 68 65 20 75 73 65 20  16()].  The use 
20850 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76  of the.** new "v
20860 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  2" interface is 
20870 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20  recommended for 
20880 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  new applications
20890 20 62 75 74 20 74 68 65 20 6c 65 67 61 63 79 0a   but the legacy.
208a0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c  ** interface wil
208b0 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65  l continue to be
208c0 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a   supported..**.*
208d0 2a 20 49 6e 20 74 68 65 20 6c 61 67 61 63 79 20  * In the lagacy 
208e0 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 72  interface, the r
208f0 65 74 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c  eturn value will
20900 20 62 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49   be either [SQLI
20910 54 45 5f 42 55 53 59 5d 2c 20 0a 2a 2a 20 5b 53  TE_BUSY], .** [S
20920 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51  QLITE_DONE], [SQ
20930 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49  LITE_ROW], [SQLI
20940 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53  TE_ERROR], or [S
20950 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a  QLITE_MISUSE]..*
20960 2a 20 57 69 74 68 20 74 68 65 20 22 76 32 22 20  * With the "v2" 
20970 69 6e 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f  interface, any o
20980 66 20 74 68 65 20 6f 74 68 65 72 20 5b 53 51 4c  f the other [SQL
20990 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20  ITE_OK | result 
209a0 63 6f 64 65 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c  code].** or [SQL
209b0 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c  ITE_IOERR_READ |
209c0 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
209d0 20 63 6f 64 65 5d 20 6d 69 67 68 74 20 62 65 20   code] might be 
209e0 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 77  returned as.** w
209f0 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49  ell..**.** [SQLI
20a00 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74  TE_BUSY] means t
20a10 68 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65  hat the database
20a20 20 65 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62   engine was unab
20a30 6c 65 20 74 6f 20 61 63 71 75 69 72 65 20 74 68  le to acquire th
20a40 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f  e.** database lo
20a50 63 6b 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20  cks it needs to 
20a60 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20 49 66 20  do its job.  If 
20a70 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
20a80 20 61 20 43 4f 4d 4d 49 54 0a 2a 2a 20 6f 72 20   a COMMIT.** or 
20a90 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f  occurs outside o
20aa0 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72  f an explicit tr
20ab0 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20  ansaction, then 
20ac0 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20 74 68  you can retry th
20ad0 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20  e.** statement. 
20ae0 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   If the statemen
20af0 74 20 69 73 20 6e 6f 74 20 61 20 43 4f 4d 4d 49  t is not a COMMI
20b00 54 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74  T and occurs wit
20b10 68 69 6e 20 61 0a 2a 2a 20 65 78 70 6c 69 63 69  hin a.** explici
20b20 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68  t transaction th
20b30 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f  en you should ro
20b40 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73  llback the trans
20b50 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a  action before.**
20b60 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a   continuing..**.
20b70 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  ** [SQLITE_DONE]
20b80 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
20b90 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69  statement has fi
20ba0 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67  nished executing
20bb0 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79  .** successfully
20bc0 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  .  sqlite3_step(
20bd0 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  ) should not be 
20be0 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20  called again on 
20bf0 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20  this virtual.** 
20c00 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20  machine without 
20c10 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73  first calling [s
20c20 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
20c30 74 6f 20 72 65 73 65 74 20 74 68 65 20 76 69 72  to reset the vir
20c40 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20  tual.** machine 
20c50 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74  back to its init
20c60 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a  ial state..**.**
20c70 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74   If the SQL stat
20c80 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63  ement being exec
20c90 75 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79  uted returns any
20ca0 20 64 61 74 61 2c 20 74 68 65 6e 20 0a 2a 2a 20   data, then .** 
20cb0 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 69 73 20  [SQLITE_ROW] is 
20cc0 72 65 74 75 72 6e 65 64 20 65 61 63 68 20 74 69  returned each ti
20cd0 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20  me a new row of 
20ce0 64 61 74 61 20 69 73 20 72 65 61 64 79 0a 2a 2a  data is ready.**
20cf0 20 66 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20   for processing 
20d00 62 79 20 74 68 65 20 63 61 6c 6c 65 72 2e 20 54  by the caller. T
20d10 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65  he values may be
20d20 20 61 63 63 65 73 73 65 64 20 75 73 69 6e 67 0a   accessed using.
20d30 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
20d40 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 63 6f 6c  column_int | col
20d50 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74  umn access funct
20d60 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65  ions]..** sqlite
20d70 33 5f 73 74 65 70 28 29 20 69 73 20 63 61 6c 6c  3_step() is call
20d80 65 64 20 61 67 61 69 6e 20 74 6f 20 72 65 74 72  ed again to retr
20d90 69 65 76 65 20 74 68 65 20 6e 65 78 74 20 72 6f  ieve the next ro
20da0 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 20 0a 2a  w of data..** .*
20db0 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  * [SQLITE_ERROR]
20dc0 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20 72 75   means that a ru
20dd0 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 28 73 75  n-time error (su
20de0 63 68 20 61 73 20 61 20 63 6f 6e 73 74 72 61 69  ch as a constrai
20df0 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29  nt.** violation)
20e00 20 68 61 73 20 6f 63 63 75 72 72 65 64 2e 20 20   has occurred.  
20e10 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73  sqlite3_step() s
20e20 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c  hould not be cal
20e30 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20  led again on.** 
20e40 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66  the VM. More inf
20e50 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65 20  ormation may be 
20e60 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67  found by calling
20e70 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
20e80 28 29 5d 2e 0a 2a 2a 20 57 69 74 68 20 74 68 65  ()]..** With the
20e90 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
20ea0 65 2c 20 61 20 6d 6f 72 65 20 73 70 65 63 69 66  e, a more specif
20eb0 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 28 65  ic error code (e
20ec0 78 61 6d 70 6c 65 3a 0a 2a 2a 20 5b 53 51 4c 49  xample:.** [SQLI
20ed0 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b  TE_INTERRUPT], [
20ee0 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20  SQLITE_SCHEMA], 
20ef0 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d  [SQLITE_CORRUPT]
20f00 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a  , and so forth).
20f10 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e  ** can be obtain
20f20 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73  ed by calling [s
20f30 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
20f40 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  on the.** [prepa
20f50 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20  red statement]. 
20f60 20 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74   In the "v2" int
20f70 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d  erface,.** the m
20f80 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72  ore specific err
20f90 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 72  or code is retur
20fa0 6e 65 64 20 64 69 72 65 63 74 6c 79 20 62 79 20  ned directly by 
20fb0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a  sqlite3_step()..
20fc0 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49  **.** [SQLITE_MI
20fd0 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74  SUSE] means that
20fe0 20 74 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e   the this routin
20ff0 65 20 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61  e was called ina
21000 70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a  ppropriately..**
21010 20 50 65 72 68 61 70 73 20 69 74 20 77 61 73 20   Perhaps it was 
21020 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65  called on a [pre
21030 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
21040 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72   that has.** alr
21050 65 61 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74  eady been [sqlit
21060 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69  e3_finalize | fi
21070 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f  nalized] or on o
21080 6e 65 20 74 68 61 74 20 68 61 64 20 0a 2a 2a 20  ne that had .** 
21090 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72  previously retur
210a0 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  ned [SQLITE_ERRO
210b0 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f  R] or [SQLITE_DO
210c0 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c  NE].  Or it coul
210d0 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 61 73 65  d.** be the case
210e0 20 74 68 61 74 20 74 68 65 20 73 61 6d 65 20 64   that the same d
210f0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
21100 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 73 65 64  on is being used
21110 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f   by two or.** mo
21120 72 65 20 74 68 72 65 61 64 73 20 61 74 20 74 68  re threads at th
21130 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e  e same moment in
21140 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e   time..**.** <b>
21150 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 65 20  Goofy Interface 
21160 41 6c 65 72 74 3a 3c 2f 62 3e 0a 2a 2a 20 49 6e  Alert:</b>.** In
21170 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65   the legacy inte
21180 72 66 61 63 65 2c 20 0a 2a 2a 20 74 68 65 20 73  rface, .** the s
21190 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 41 50  qlite3_step() AP
211a0 49 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73  I always returns
211b0 20 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72   a generic error
211c0 20 63 6f 64 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54   code,.** [SQLIT
211d0 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77  E_ERROR], follow
211e0 69 6e 67 20 61 6e 79 20 65 72 72 6f 72 20 6f 74  ing any error ot
211f0 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
21200 5f 42 55 53 59 5d 0a 2a 2a 20 61 6e 64 20 5b 53  _BUSY].** and [S
21210 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20  QLITE_MISUSE].  
21220 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 20 5b 73  You must call [s
21230 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
21240 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  or.** [sqlite3_f
21250 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72  inalize()] in or
21260 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20  der to find one 
21270 6f 66 20 74 68 65 20 73 70 65 63 69 66 69 63 0a  of the specific.
21280 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d  ** [error codes]
21290 20 74 68 61 74 20 62 65 74 74 65 72 20 64 65 73   that better des
212a0 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72  cribes the error
212b0 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68  ..** We admit th
212c0 61 74 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f  at this is a goo
212d0 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20  fy design.  The 
212e0 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e  problem has been
212f0 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74   fixed.** with t
21300 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
21310 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70 61  e.  If you prepa
21320 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53  re all of your S
21330 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
21340 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73   using either [s
21350 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
21360 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  2()] or [sqlite3
21370 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
21380 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74   instead.** of t
21390 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74  he legacy [sqlit
213a0 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e  e3_prepare()] an
213b0 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
213c0 72 65 31 36 28 29 5d 2c 20 74 68 65 6e 20 74 68  re16()], then th
213d0 65 20 0a 2a 2a 20 6d 6f 72 65 20 73 70 65 63 69  e .** more speci
213e0 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73  fic [error codes
213f0 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64 20 64  ] are returned d
21400 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71  irectly.** by sq
21410 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 54  lite3_step().  T
21420 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 22 76  he use of the "v
21430 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  2" interface is 
21440 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a  recommended..**.
21450 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
21460 2a 0a 2a 2a 20 7b 46 31 33 32 30 32 7d 20 20 49  *.** {F13202}  I
21470 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  f [prepared stat
21480 65 6d 65 6e 74 5d 20 53 20 69 73 20 72 65 61 64  ement] S is read
21490 79 20 74 6f 20 62 65 0a 2a 2a 20 20 20 20 20 20  y to be.**      
214a0 20 20 20 20 20 72 75 6e 2c 20 74 68 65 6e 20 5b       run, then [
214b0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
214c0 20 61 64 76 61 6e 63 65 73 20 74 68 61 74 20 70   advances that p
214d0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
214e0 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 75  t.**           u
214f0 6e 74 69 6c 20 74 6f 20 63 6f 6d 70 6c 65 74 69  ntil to completi
21500 6f 6e 20 6f 72 20 75 6e 74 69 6c 20 69 74 20 69  on or until it i
21510 73 20 72 65 61 64 79 20 74 6f 20 72 65 74 75 72  s ready to retur
21520 6e 20 61 6e 6f 74 68 65 72 0a 2a 2a 20 20 20 20  n another.**    
21530 20 20 20 20 20 20 20 72 6f 77 20 6f 66 20 74 68         row of th
21540 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 72 20  e result set or 
21550 61 6e 20 69 6e 74 65 72 72 75 70 74 20 6f 72 20  an interrupt or 
21560 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 6f  run-time error o
21570 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  ccurs..**.** {F1
21580 35 33 30 34 7d 20 20 57 68 65 6e 20 61 20 63 61  5304}  When a ca
21590 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
215a0 74 65 70 28 53 29 5d 20 63 61 75 73 65 73 20 74  tep(S)] causes t
215b0 68 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  he .**          
215c0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
215d0 6d 65 6e 74 5d 20 53 20 74 6f 20 72 75 6e 20 74  ment] S to run t
215e0 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2c 0a 2a 2a  o completion,.**
215f0 20 20 20 20 20 20 20 20 20 20 20 74 68 65 20 66             the f
21600 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
21610 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 0a 2a  [SQLITE_DONE]..*
21620 2a 0a 2a 2a 20 7b 46 31 35 33 30 36 7d 20 20 57  *.** {F15306}  W
21630 68 65 6e 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73  hen a call to [s
21640 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
21650 73 74 6f 70 73 20 62 65 63 61 75 73 65 20 69 74  stops because it
21660 20 69 73 20 72 65 61 64 79 0a 2a 2a 20 20 20 20   is ready.**    
21670 20 20 20 20 20 20 20 74 6f 20 72 65 74 75 72 6e         to return
21680 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 6f 66 20   another row of 
21690 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 2c 20  the result set, 
216a0 69 74 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20  it returns.**   
216b0 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f          [SQLITE_
216c0 52 4f 57 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35  ROW]..**.** {F15
216d0 33 30 38 7d 20 20 49 66 20 61 20 63 61 6c 6c 20  308}  If a call 
216e0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
216f0 28 53 29 5d 20 65 6e 63 6f 75 6e 74 65 72 73 20  (S)] encounters 
21700 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  an.**           
21710 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75  [sqlite3_interru
21720 70 74 7c 69 6e 74 65 72 72 75 70 74 5d 20 6f 72  pt|interrupt] or
21730 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f   a run-time erro
21740 72 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  r,.**           
21750 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70  it returns an ap
21760 70 72 6f 70 72 61 69 74 65 20 65 72 72 6f 72 20  propraite error 
21770 63 6f 64 65 20 74 68 61 74 20 69 73 20 6e 6f 74  code that is not
21780 20 6f 6e 65 20 6f 66 0a 2a 2a 20 20 20 20 20 20   one of.**      
21790 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d       [SQLITE_OK]
217a0 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20  , [SQLITE_ROW], 
217b0 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  or [SQLITE_DONE]
217c0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 33 31 30 7d  ..**.** {F15310}
217d0 20 20 49 66 20 61 6e 20 5b 73 71 6c 69 74 65 33    If an [sqlite3
217e0 5f 69 6e 74 65 72 72 75 70 74 7c 69 6e 74 65 72  _interrupt|inter
217f0 72 75 70 74 5d 20 6f 72 20 72 75 6e 2d 74 69 6d  rupt] or run-tim
21800 65 20 65 72 72 6f 72 0a 2a 2a 20 20 20 20 20 20  e error.**      
21810 20 20 20 20 20 6f 63 63 75 72 73 20 64 75 72 69       occurs duri
21820 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71  ng a call to [sq
21830 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 0a 2a  lite3_step(S)].*
21840 2a 20 20 20 20 20 20 20 20 20 20 20 66 6f 72 20  *           for 
21850 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
21860 65 6d 65 6e 74 5d 20 53 20 63 72 65 61 74 65 64  ement] S created
21870 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20   using.**       
21880 20 20 20 20 6c 65 67 61 63 79 20 69 6e 74 65 72      legacy inter
21890 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70  faces [sqlite3_p
218a0 72 65 70 61 72 65 28 29 5d 20 6f 72 0a 2a 2a 20  repare()] or.** 
218b0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
218c0 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20  e3_prepare16()] 
218d0 74 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f  then the functio
218e0 6e 20 72 65 74 75 72 6e 73 20 65 69 74 68 65 72  n returns either
218f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 53  .**           [S
21900 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 5b 53  QLITE_ERROR], [S
21910 51 4c 49 54 45 5f 42 55 53 59 5d 2c 20 6f 72 20  QLITE_BUSY], or 
21920 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e  [SQLITE_MISUSE].
21930 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
21940 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d  step(sqlite3_stm
21950 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
21960 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20  3REF: Number of 
21970 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 73  columns in a res
21980 75 6c 74 20 73 65 74 20 7b 46 31 33 37 37 30 7d  ult set {F13770}
21990 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 74 68  .**.** Return th
219a0 65 20 6e 75 6d 62 65 72 20 6f 66 20 76 61 6c 75  e number of valu
219b0 65 73 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e  es in the curren
219c0 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73  t row of the res
219d0 75 6c 74 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 49  ult set..**.** I
219e0 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
219f0 20 7b 46 31 33 37 37 31 7d 20 20 41 66 74 65 72   {F13771}  After
21a00 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69   a call to [sqli
21a10 74 65 33 5f 73 74 65 70 28 53 29 5d 20 74 68 61  te3_step(S)] tha
21a20 74 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20  t returns.**    
21a30 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 52         [SQLITE_R
21a40 4f 57 5d 2c 20 74 68 65 20 5b 73 71 6c 69 74 65  OW], the [sqlite
21a50 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 53 29 5d  3_data_count(S)]
21a60 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 20 20 20 20   routine.**     
21a70 20 20 20 20 20 20 77 69 6c 6c 20 72 65 74 75 72        will retur
21a80 6e 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65  n the same value
21a90 20 61 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   as the.**      
21aa0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f       [sqlite3_co
21ab0 6c 75 6d 6e 5f 63 6f 75 6e 74 28 53 29 5d 20 66  lumn_count(S)] f
21ac0 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b  unction..**.** {
21ad0 46 31 33 37 37 32 7d 20 20 41 66 74 65 72 20 5b  F13772}  After [
21ae0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
21af0 20 68 61 73 20 72 65 74 75 72 6e 65 64 20 61 6e   has returned an
21b00 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68  y value other th
21b10 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  an.**           
21b20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20  [SQLITE_ROW] or 
21b30 62 65 66 6f 72 65 20 5b 73 71 6c 69 74 65 33 5f  before [sqlite3_
21b40 73 74 65 70 28 53 29 5d 20 68 61 73 20 62 65 65  step(S)] has bee
21b50 6e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  n .**           
21b60 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 5b 70  called on the [p
21b70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
21b80 74 5d 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20  t] for.**       
21b90 20 20 20 20 74 68 65 20 66 69 72 73 74 20 74 69      the first ti
21ba0 6d 65 20 73 69 6e 63 65 20 69 74 20 77 61 73 20  me since it was 
21bb0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
21bc0 7c 70 72 65 70 61 72 65 64 5d 0a 2a 2a 20 20 20  |prepared].**   
21bd0 20 20 20 20 20 20 20 20 6f 72 20 5b 73 71 6c 69          or [sqli
21be0 74 65 33 5f 72 65 73 65 74 7c 72 65 73 65 74 5d  te3_reset|reset]
21bf0 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64  , the [sqlite3_d
21c00 61 74 61 5f 63 6f 75 6e 74 28 53 29 5d 0a 2a 2a  ata_count(S)].**
21c10 20 20 20 20 20 20 20 20 20 20 20 72 6f 75 74 69             routi
21c20 6e 65 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e  ne returns zero.
21c30 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
21c40 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74  data_count(sqlit
21c50 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
21c60 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
21c70 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61  : Fundamental Da
21c80 74 61 74 79 70 65 73 20 7b 46 31 30 32 36 35 7d  tatypes {F10265}
21c90 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51  .** KEYWORDS: SQ
21ca0 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20  LITE_TEXT.**.** 
21cb0 7b 46 31 30 32 36 36 7d 45 76 65 72 79 20 76 61  {F10266}Every va
21cc0 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20 68 61  lue in SQLite ha
21cd0 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 75  s one of five fu
21ce0 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 79  ndamental dataty
21cf0 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  pes:.**.** <ul>.
21d00 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73  ** <li> 64-bit s
21d10 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a  igned integer.**
21d20 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 45   <li> 64-bit IEE
21d30 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  E floating point
21d40 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20   number.** <li> 
21d50 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42  string.** <li> B
21d60 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c  LOB.** <li> NULL
21d70 0a 2a 2a 20 3c 2f 75 6c 3e 20 7b 45 4e 44 7d 0a  .** </ul> {END}.
21d80 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
21d90 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65 73 20  tants are codes 
21da0 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68 6f 73  for each of thos
21db0 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e  e types..**.** N
21dc0 6f 74 65 20 74 68 61 74 20 74 68 65 20 53 51 4c  ote that the SQL
21dd0 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e  ITE_TEXT constan
21de0 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65 64 20  t was also used 
21df0 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  in SQLite versio
21e00 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d  n 2.** for a com
21e10 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72 65 6e  pletely differen
21e20 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74  t meaning.  Soft
21e30 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 20  ware that links 
21e40 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20  against both.** 
21e50 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32  SQLite version 2
21e60 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73   and SQLite vers
21e70 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 65  ion 3 should use
21e80 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20 6e 6f   SQLITE3_TEXT no
21e90 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 54  t.** SQLITE_TEXT
21ea0 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
21eb0 49 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a 23  ITE_INTEGER  1.#
21ec0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c  define SQLITE_FL
21ed0 4f 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e 65  OAT    2.#define
21ee0 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20   SQLITE_BLOB    
21ef0 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   4.#define SQLIT
21f00 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 66  E_NULL     5.#if
21f10 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a  def SQLITE_TEXT.
21f20 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 54  # undef SQLITE_T
21f30 45 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 69  EXT.#else.# defi
21f40 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 20  ne SQLITE_TEXT  
21f50 20 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 66     3.#endif.#def
21f60 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54  ine SQLITE3_TEXT
21f70 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41       3../*.** CA
21f80 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 73 20  PI3REF: Results 
21f90 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 75  Values From A Qu
21fa0 65 72 79 20 7b 46 31 33 38 30 30 7d 0a 2a 2a 0a  ery {F13800}.**.
21fb0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
21fc0 73 20 66 6f 72 6d 20 74 68 65 20 22 72 65 73 75  s form the "resu
21fd0 6c 74 20 73 65 74 20 71 75 65 72 79 22 20 69 6e  lt set query" in
21fe0 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54  terface..**.** T
21ff0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
22000 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  turn information
22010 20 61 62 6f 75 74 0a 2a 2a 20 61 20 73 69 6e 67   about.** a sing
22020 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  le column of the
22030 20 63 75 72 72 65 6e 74 20 72 65 73 75 6c 74 20   current result 
22040 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e 20  row of a query. 
22050 20 49 6e 20 65 76 65 72 79 0a 2a 2a 20 63 61 73   In every.** cas
22060 65 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  e the first argu
22070 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
22080 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20 5b 70 72  r to the .** [pr
22090 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
220a0 5d 20 74 68 61 74 20 69 73 20 62 65 69 6e 67 0a  ] that is being.
220b0 2a 2a 20 65 76 61 6c 75 61 74 65 64 20 28 74 68  ** evaluated (th
220c0 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  e [sqlite3_stmt*
220d0 5d 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72  ] that was retur
220e0 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71  ned from .** [sq
220f0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
22100 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74  ()] or one of it
22110 73 20 76 61 72 69 61 6e 74 73 29 20 61 6e 64 0a  s variants) and.
22120 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  ** the second ar
22130 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e  gument is the in
22140 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d  dex of the colum
22150 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f  n for which info
22160 72 6d 61 74 69 6f 6e 20 0a 2a 2a 20 73 68 6f 75  rmation .** shou
22170 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20  ld be returned. 
22180 20 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63   The left-most c
22190 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73  olumn of the res
221a0 75 6c 74 20 73 65 74 0a 2a 2a 20 68 61 73 20 61  ult set.** has a
221b0 6e 20 69 6e 64 65 78 20 6f 66 20 30 2e 0a 2a 2a  n index of 0..**
221c0 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73  .** If the SQL s
221d0 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20  tatement is not 
221e0 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20  currently point 
221f0 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20  to a valid row, 
22200 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 74 68 65  or if the.** the
22210 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73   column index is
22220 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74   out of range, t
22230 68 65 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64  he result is und
22240 65 66 69 6e 65 64 2e 20 0a 2a 2a 20 54 68 65 73  efined. .** Thes
22250 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f  e routines may o
22260 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68  nly be called wh
22270 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  en the most rece
22280 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73  nt call to.** [s
22290 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68  qlite3_step()] h
222a0 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c  as returned [SQL
222b0 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69  ITE_ROW] and nei
222c0 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ther.** [sqlite3
222d0 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73  _reset()] nor [s
222e0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
222f0 29 5d 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c  )] has been call
22300 20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a   subsequently..*
22310 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73  * If any of thes
22320 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63  e routines are c
22330 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c  alled after [sql
22340 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
22350 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  .** [sqlite3_fin
22360 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65  alize()] or afte
22370 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  r [sqlite3_step(
22380 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a  )] has returned.
22390 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68  ** something oth
223a0 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
223b0 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74  ROW], the result
223c0 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
223d0 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f  .** If [sqlite3_
223e0 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69  step()] or [sqli
223f0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20  te3_reset()] or 
22400 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
22410 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c  e()].** are call
22420 65 64 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72  ed from a differ
22430 65 6e 74 20 74 68 72 65 61 64 20 77 68 69 6c 65  ent thread while
22440 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f   any of these ro
22450 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65  utines.** are pe
22460 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20  nding, then the 
22470 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
22480 66 69 6e 65 64 2e 20 20 0a 2a 2a 0a 2a 2a 20 54  fined.  .**.** T
22490 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
224a0 6e 5f 74 79 70 65 28 29 20 72 6f 75 74 69 6e 65  n_type() routine
224b0 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51   returns .** [SQ
224c0 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64  LITE_INTEGER | d
224d0 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f  atatype code] fo
224e0 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61  r the initial da
224f0 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68  ta type.** of th
22500 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e  e result column.
22510 20 20 54 68 65 20 72 65 74 75 72 6e 65 64 20 76    The returned v
22520 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b  alue is one of [
22530 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c  SQLITE_INTEGER],
22540 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41  .** [SQLITE_FLOA
22550 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54  T], [SQLITE_TEXT
22560 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d  ], [SQLITE_BLOB]
22570 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c  , or [SQLITE_NUL
22580 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 0a 2a  L].  The value.*
22590 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  * returned by sq
225a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
225b0 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e  e() is only mean
225c0 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74 79 70  ingful if no typ
225d0 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73  e.** conversions
225e0 20 68 61 76 65 20 6f 63 63 75 72 72 65 64 20 61   have occurred a
225f0 73 20 64 65 73 63 72 69 62 65 64 20 62 65 6c 6f  s described belo
22600 77 2e 20 20 41 66 74 65 72 20 61 20 74 79 70 65  w.  After a type
22610 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20   conversion,.** 
22620 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
22630 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
22640 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 75  lumn_type() is u
22650 6e 64 65 66 69 6e 65 64 2e 20 20 46 75 74 75 72  ndefined.  Futur
22660 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66  e.** versions of
22670 20 53 51 4c 69 74 65 20 6d 61 79 20 63 68 61 6e   SQLite may chan
22680 67 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  ge the behavior 
22690 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  of sqlite3_colum
226a0 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c  n_type().** foll
226b0 6f 77 69 6e 67 20 61 20 74 79 70 65 20 63 6f 6e  owing a type con
226c0 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49  version..**.** I
226d0 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
226e0 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20  a BLOB or UTF-8 
226f0 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20  string then the 
22700 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
22710 79 74 65 73 28 29 20 0a 2a 2a 20 72 6f 75 74 69  ytes() .** routi
22720 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ne returns the n
22730 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
22740 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73  n that BLOB or s
22750 74 72 69 6e 67 2e 0a 2a 2a 20 49 66 20 74 68 65  tring..** If the
22760 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46   result is a UTF
22770 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68 65 6e  -16 string, then
22780 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
22790 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72 74 73  bytes() converts
227a0 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74  .** the string t
227b0 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68 65 6e  o UTF-8 and then
227c0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
227d0 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a  ber of bytes..**
227e0 20 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69   If the result i
227f0 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75  s a numeric valu
22800 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  e then sqlite3_c
22810 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 73  olumn_bytes() us
22820 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  es.** [sqlite3_s
22830 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f  nprintf()] to co
22840 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65  nvert that value
22850 20 74 6f 20 61 20 55 54 46 2d 38 20 73 74 72 69   to a UTF-8 stri
22860 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a  ng and returns.*
22870 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
22880 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74  bytes in that st
22890 72 69 6e 67 2e 0a 2a 2a 20 54 68 65 20 76 61 6c  ring..** The val
228a0 75 65 20 72 65 74 75 72 6e 65 64 20 64 6f 65 73  ue returned does
228b0 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 65   not include the
228c0 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
228d0 20 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f   at the end.** o
228e0 66 20 74 68 65 20 73 74 72 69 6e 67 2e 20 20 46  f the string.  F
228f0 6f 72 20 63 6c 61 72 69 74 79 3a 20 74 68 65 20  or clarity: the 
22900 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69  value returned i
22910 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  s the number of.
22920 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  ** bytes in the 
22930 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20  string, not the 
22940 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63  number of charac
22950 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 53 74 72 69  ters..**.** Stri
22960 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ngs returned by 
22970 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
22980 65 78 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ext() and sqlite
22990 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
229a0 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79  ),.** even empty
229b0 20 73 74 72 69 6e 67 73 2c 20 61 72 65 20 61 6c   strings, are al
229c0 77 61 79 73 20 7a 65 72 6f 20 74 65 72 6d 69 6e  ways zero termin
229d0 61 74 65 64 2e 20 20 54 68 65 20 72 65 74 75 72  ated.  The retur
229e0 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20  n.** value from 
229f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
22a00 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a 65 72 6f  lob() for a zero
22a10 2d 6c 65 6e 67 74 68 20 62 6c 6f 62 20 69 73 20  -length blob is 
22a20 61 6e 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20  an arbitrary.** 
22a30 70 6f 69 6e 74 65 72 2c 20 70 6f 73 73 69 62 6c  pointer, possibl
22a40 79 20 65 76 65 6e 20 61 20 4e 55 4c 4c 20 70 6f  y even a NULL po
22a50 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  inter..**.** The
22a60 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
22a70 62 79 74 65 73 31 36 28 29 20 72 6f 75 74 69 6e  bytes16() routin
22a80 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20  e is similar to 
22a90 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
22aa0 79 74 65 73 28 29 0a 2a 2a 20 62 75 74 20 6c 65  ytes().** but le
22ab0 61 76 65 73 20 74 68 65 20 72 65 73 75 6c 74 20  aves the result 
22ac0 69 6e 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74  in UTF-16 in nat
22ad0 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 69  ive byte order i
22ae0 6e 73 74 65 61 64 20 6f 66 20 55 54 46 2d 38 2e  nstead of UTF-8.
22af0 20 20 0a 2a 2a 20 54 68 65 20 7a 65 72 6f 20 74    .** The zero t
22b00 65 72 6d 69 6e 61 74 6f 72 20 69 73 20 6e 6f 74  erminator is not
22b10 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 69   included in thi
22b20 73 20 63 6f 75 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54  s count..**.** T
22b30 68 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  he object return
22b40 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63  ed by [sqlite3_c
22b50 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69  olumn_value()] i
22b60 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65  s an.** [unprote
22b70 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
22b80 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 41 6e 20  ue] object.  An 
22b90 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
22ba0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
22bb0 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  .** may only be 
22bc0 75 73 65 64 20 77 69 74 68 20 5b 73 71 6c 69 74  used with [sqlit
22bd0 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d  e3_bind_value()]
22be0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65   and [sqlite3_re
22bf0 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a  sult_value()]..*
22c00 2a 20 49 66 20 74 68 65 20 5b 75 6e 70 72 6f 74  * If the [unprot
22c10 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
22c20 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72 65 74 75  lue] object retu
22c30 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  rned by.** [sqli
22c40 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
22c50 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 20 61  ()] is used in a
22c60 6e 79 20 6f 74 68 65 72 20 77 61 79 2c 20 69 6e  ny other way, in
22c70 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a  cluding calls.**
22c80 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b   to routines lik
22c90 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  e .** [sqlite3_v
22ca0 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71  alue_int()], [sq
22cb0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
22cc0 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33  ()], or [sqlite3
22cd0 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c  _value_bytes()],
22ce0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68  .** then the beh
22cf0 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e  avior is undefin
22d00 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ed..**.** These 
22d10 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74  routines attempt
22d20 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20   to convert the 
22d30 76 61 6c 75 65 20 77 68 65 72 65 20 61 70 70 72  value where appr
22d40 6f 70 72 69 61 74 65 2e 20 20 46 6f 72 0a 2a 2a  opriate.  For.**
22d50 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65   example, if the
22d60 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73   internal repres
22d70 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41  entation is FLOA
22d80 54 20 61 6e 64 20 61 20 74 65 78 74 20 72 65 73  T and a text res
22d90 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 73  ult.** is reques
22da0 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e  ted, [sqlite3_sn
22db0 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73 65  printf()] is use
22dc0 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20  d internally to 
22dd0 64 6f 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f  do the conversio
22de0 6e 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c  n.** automatical
22df0 6c 79 2e 20 20 54 68 65 20 66 6f 6c 6c 6f 77 69  ly.  The followi
22e00 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73  ng table details
22e10 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73   the conversions
22e20 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 61 70 70   that.** are app
22e30 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lied:.**.** <blo
22e40 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62  ckquote>.** <tab
22e50 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a  le border="1">.*
22e60 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72  * <tr><th> Inter
22e70 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e  nal<br>Type <th>
22e80 20 52 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79   Requested<br>Ty
22e90 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73  pe <th>  Convers
22ea0 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74  ion.**.** <tr><t
22eb0 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
22ec0 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20   INTEGER   <td> 
22ed0 52 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c  Result is 0.** <
22ee0 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20  tr><td>  NULL   
22ef0 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20   <td>  FLOAT    
22f00 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30  <td> Result is 0
22f10 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  .0.** <tr><td>  
22f20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54  NULL    <td>   T
22f30 45 58 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75  EXT    <td> Resu
22f40 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74  lt is NULL point
22f50 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  er.** <tr><td>  
22f60 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42  NULL    <td>   B
22f70 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75  LOB    <td> Resu
22f80 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74  lt is NULL point
22f90 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49  er.** <tr><td> I
22fa0 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 46 4c  NTEGER  <td>  FL
22fb0 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76  OAT    <td> Conv
22fc0 65 72 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 72  ert from integer
22fd0 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72   to float.** <tr
22fe0 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c  ><td> INTEGER  <
22ff0 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
23000 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69  d> ASCII renderi
23010 6e 67 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65  ng of the intege
23020 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e  r.** <tr><td> IN
23030 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 42 4c  TEGER  <td>   BL
23040 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20  OB    <td> Same 
23050 61 73 20 66 6f 72 20 49 4e 54 45 47 45 52 2d 3e  as for INTEGER->
23060 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  TEXT.** <tr><td>
23070 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49    FLOAT   <td> I
23080 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f  NTEGER   <td> Co
23090 6e 76 65 72 74 20 66 72 6f 6d 20 66 6c 6f 61 74  nvert from float
230a0 20 74 6f 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c   to integer.** <
230b0 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  tr><td>  FLOAT  
230c0 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
230d0 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65  <td> ASCII rende
230e0 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61  ring of the floa
230f0 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46  t.** <tr><td>  F
23100 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c  LOAT   <td>   BL
23110 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20  OB    <td> Same 
23120 61 73 20 46 4c 4f 41 54 2d 3e 54 45 58 54 0a 2a  as FLOAT->TEXT.*
23130 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54  * <tr><td>  TEXT
23140 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52      <td> INTEGER
23150 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 69     <td> Use atoi
23160 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ().** <tr><td>  
23170 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c  TEXT    <td>  FL
23180 4f 41 54 20 20 20 20 3c 74 64 3e 20 55 73 65 20  OAT    <td> Use 
23190 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74  atof().** <tr><t
231a0 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  d>  TEXT    <td>
231b0 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
231c0 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72  No change.** <tr
231d0 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c  ><td>  BLOB    <
231e0 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
231f0 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45  d> Convert to TE
23200 58 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f 69  XT then use atoi
23210 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ().** <tr><td>  
23220 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 4c  BLOB    <td>  FL
23230 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76  OAT    <td> Conv
23240 65 72 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e  ert to TEXT then
23250 20 75 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c   use atof().** <
23260 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20  tr><td>  BLOB   
23270 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
23280 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 72 6f 20  <td> Add a zero 
23290 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65  terminator if ne
232a0 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e  eded.** </table>
232b0 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  .** </blockquote
232c0 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c  >.**.** The tabl
232d0 65 20 61 62 6f 76 65 20 6d 61 6b 65 73 20 72 65  e above makes re
232e0 66 65 72 65 6e 63 65 20 74 6f 20 73 74 61 6e 64  ference to stand
232f0 61 72 64 20 43 20 6c 69 62 72 61 72 79 20 66 75  ard C library fu
23300 6e 63 74 69 6f 6e 73 20 61 74 6f 69 28 29 0a 2a  nctions atoi().*
23310 2a 20 61 6e 64 20 61 74 6f 66 28 29 2e 20 20 53  * and atof().  S
23320 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74 20 72  QLite does not r
23330 65 61 6c 6c 79 20 75 73 65 20 74 68 65 73 65 20  eally use these 
23340 66 75 6e 63 74 69 6f 6e 73 2e 20 20 49 74 20 68  functions.  It h
23350 61 73 20 69 74 73 0a 2a 2a 20 6f 6e 20 65 71 75  as its.** on equ
23360 61 76 61 6c 65 6e 74 20 69 6e 74 65 72 6e 61 6c  avalent internal
23370 20 72 6f 75 74 69 6e 65 73 2e 20 20 54 68 65 20   routines.  The 
23380 61 74 6f 69 28 29 20 61 6e 64 20 61 74 6f 66 28  atoi() and atof(
23390 29 20 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 75  ) names are.** u
233a0 73 65 64 20 69 6e 20 74 68 65 20 74 61 62 6c 65  sed in the table
233b0 20 66 6f 72 20 62 72 65 76 69 74 79 20 61 6e 64   for brevity and
233c0 20 62 65 63 61 75 73 65 20 74 68 65 79 20 61 72   because they ar
233d0 65 20 66 61 6d 69 6c 69 61 72 20 74 6f 20 6d 6f  e familiar to mo
233e0 73 74 0a 2a 2a 20 43 20 70 72 6f 67 72 61 6d 6d  st.** C programm
233f0 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  ers..**.** Note 
23400 74 68 61 74 20 77 68 65 6e 20 74 79 70 65 20 63  that when type c
23410 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63 75 72  onversions occur
23420 2c 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72  , pointers retur
23430 6e 65 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20  ned by prior.** 
23440 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
23450 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20  _column_blob(), 
23460 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
23470 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a  ext(), and/or.**
23480 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
23490 74 65 78 74 31 36 28 29 20 6d 61 79 20 62 65 20  text16() may be 
234a0 69 6e 76 61 6c 69 64 61 74 65 64 2e 20 0a 2a 2a  invalidated. .**
234b0 20 54 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   Type conversion
234c0 73 20 61 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e  s and pointer in
234d0 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67 68  validations migh
234e0 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68  t occur.** in th
234f0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65  e following case
23500 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
23510 20 3c 6c 69 3e 3c 70 3e 20 20 54 68 65 20 69 6e   <li><p>  The in
23520 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73  itial content is
23530 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69   a BLOB and sqli
23540 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
23550 29 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  ) .**          o
23560 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  r sqlite3_column
23570 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c  _text16() is cal
23580 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72  led.  A zero-ter
23590 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a  minator might.**
235a0 20 20 20 20 20 20 20 20 20 20 6e 65 65 64 20 74            need t
235b0 6f 20 62 65 20 61 64 64 65 64 20 74 6f 20 74 68  o be added to th
235c0 65 20 73 74 72 69 6e 67 2e 3c 2f 70 3e 3c 2f 6c  e string.</p></l
235d0 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 3c 70 3e  i>.**.** <li><p>
235e0 20 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f    The initial co
235f0 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74  ntent is UTF-8 t
23600 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  ext and sqlite3_
23610 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
23620 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   or.**          
23630 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
23640 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65  ext16() is calle
23650 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20  d.  The content 
23660 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65  must be converte
23670 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f  d.**          to
23680 20 55 54 46 2d 31 36 2e 3c 2f 70 3e 3c 2f 6c 69   UTF-16.</p></li
23690 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 3c 70 3e 20  >.**.** <li><p> 
236a0 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e   The initial con
236b0 74 65 6e 74 20 69 73 20 55 54 46 2d 31 36 20 74  tent is UTF-16 t
236c0 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  ext and sqlite3_
236d0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f  column_bytes() o
236e0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 71  r.**          sq
236f0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
23700 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  t() is called.  
23710 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74  The content must
23720 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a   be converted.**
23730 20 20 20 20 20 20 20 20 20 20 74 6f 20 55 54 46            to UTF
23740 2d 38 2e 3c 2f 70 3e 3c 2f 6c 69 3e 0a 2a 2a 20  -8.</p></li>.** 
23750 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 43 6f 6e 76  </ul>.**.** Conv
23760 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20  ersions between 
23770 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46  UTF-16be and UTF
23780 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73  -16le are always
23790 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61   done in place a
237a0 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76  nd do.** not inv
237b0 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72 20  alidate a prior 
237c0 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20  pointer, though 
237d0 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f  of course the co
237e0 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66  ntent of the buf
237f0 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20  fer.** that the 
23800 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 70 6f  prior pointer po
23810 69 6e 74 73 20 74 6f 20 77 69 6c 6c 20 68 61 76  ints to will hav
23820 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e  e been modified.
23830 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a    Other kinds.**
23840 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61   of conversion a
23850 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65  re done in place
23860 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73 73   when it is poss
23870 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 69  ible, but someti
23880 6d 65 20 69 74 20 69 73 0a 2a 2a 20 6e 6f 74 20  me it is.** not 
23890 70 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e 20  possible and in 
238a0 74 68 6f 73 65 20 63 61 73 65 73 20 70 72 69 6f  those cases prio
238b0 72 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20 69  r pointers are i
238c0 6e 76 61 6c 69 64 61 74 65 64 2e 20 20 0a 2a 2a  nvalidated.  .**
238d0 0a 2a 2a 20 54 68 65 20 73 61 66 65 73 74 20 61  .** The safest a
238e0 6e 64 20 65 61 73 69 65 73 74 20 74 6f 20 72 65  nd easiest to re
238f0 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79 20 69 73  member policy is
23900 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65   to invoke these
23910 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20   routines.** in 
23920 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f  one of the follo
23930 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a  wing ways:.**.**
23940 20 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73    <ul>.**  <li>s
23950 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
23960 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79  xt() followed by
23970 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
23980 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20  bytes()</li>.** 
23990 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c   <li>sqlite3_col
239a0 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f  umn_blob() follo
239b0 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  wed by sqlite3_c
239c0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c  olumn_bytes()</l
239d0 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74  i>.**  <li>sqlit
239e0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
239f0 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73  () followed by s
23a00 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
23a10 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20  tes16()</li>.** 
23a20 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20   </ul>.**.** In 
23a30 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f 75  other words, you
23a40 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c   should call sql
23a50 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
23a60 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  (), sqlite3_colu
23a70 6d 6e 5f 62 6c 6f 62 28 29 2c 0a 2a 2a 20 6f 72  mn_blob(),.** or
23a80 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
23a90 74 65 78 74 31 36 28 29 20 66 69 72 73 74 20 74  text16() first t
23aa0 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65 73 75  o force the resu
23ab0 6c 74 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69  lt into the desi
23ac0 72 65 64 0a 2a 2a 20 66 6f 72 6d 61 74 2c 20 74  red.** format, t
23ad0 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  hen invoke sqlit
23ae0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
23af0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ) or sqlite3_col
23b00 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f  umn_bytes16() to
23b10 0a 2a 2a 20 66 69 6e 64 20 74 68 65 20 73 69 7a  .** find the siz
23b20 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e  e of the result.
23b30 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c    Do not mix cal
23b40 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  l to sqlite3_col
23b50 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a  umn_text() or.**
23b60 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
23b70 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61 6c 6c  blob() with call
23b80 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  s to sqlite3_col
23b90 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2e 20 20  umn_bytes16().  
23ba0 41 6e 64 20 64 6f 20 6e 6f 74 0a 2a 2a 20 6d 69  And do not.** mi
23bb0 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  x calls to sqlit
23bc0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
23bd0 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f  () with calls to
23be0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
23bf0 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 54  bytes()..**.** T
23c00 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75  he pointers retu
23c10 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20 75  rned are valid u
23c20 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e 76  ntil a type conv
23c30 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 73  ersion occurs as
23c40 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61 62  .** described ab
23c50 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73  ove, or until [s
23c60 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f  qlite3_step()] o
23c70 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  r [sqlite3_reset
23c80 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
23c90 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69  e3_finalize()] i
23ca0 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 6d  s called.  The m
23cb0 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73 65 64  emory space used
23cc0 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 73   to hold strings
23cd0 0a 2a 2a 20 61 6e 64 20 62 6c 6f 62 73 20 69 73  .** and blobs is
23ce0 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63   freed automatic
23cf0 61 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74  ally.  Do <b>not
23d00 3c 2f 62 3e 20 70 61 73 73 20 74 68 65 20 70 6f  </b> pass the po
23d10 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 0a  inters returned.
23d20 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
23d30 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c  mn_blob()], [sql
23d40 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
23d50 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 20 0a  ()], etc. into .
23d60 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ** [sqlite3_free
23d70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20  ()]..**.** If a 
23d80 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
23d90 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64  n error occurs d
23da0 75 72 69 6e 67 20 74 68 65 20 65 76 61 6c 75 61  uring the evalua
23db0 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f  tion of any.** o
23dc0 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
23dd0 2c 20 61 20 64 65 66 61 75 6c 74 20 76 61 6c 75  , a default valu
23de0 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  e is returned.  
23df0 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75  The default valu
23e00 65 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 74  e.** is either t
23e10 68 65 20 69 6e 74 65 67 65 72 20 30 2c 20 74 68  he integer 0, th
23e20 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  e floating point
23e30 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20   number 0.0, or 
23e40 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65  a NULL.** pointe
23e50 72 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 63  r.  Subsequent c
23e60 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
23e70 5f 65 72 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c  _errcode()] will
23e80 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49   return.** [SQLI
23e90 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a  TE_NOMEM]..**.**
23ea0 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
23eb0 2a 2a 20 7b 46 31 33 38 30 33 7d 20 54 68 65 20  ** {F13803} The 
23ec0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
23ed0 62 6c 6f 62 28 53 2c 4e 29 5d 20 69 6e 74 65 72  blob(S,N)] inter
23ee0 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68  face converts th
23ef0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74  e.**          Nt
23f00 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20  h column in the 
23f10 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74  current row of t
23f20 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f  he result set fo
23f30 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  r.**          [p
23f40 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
23f50 74 5d 20 53 20 69 6e 74 6f 20 61 20 62 6c 6f 62  t] S into a blob
23f60 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e   and then return
23f70 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  s a.**          
23f80 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 63  pointer to the c
23f90 6f 6e 76 65 72 74 65 64 20 76 61 6c 75 65 2e 0a  onverted value..
23fa0 2a 2a 0a 2a 2a 20 7b 46 31 33 38 30 36 7d 20 54  **.** {F13806} T
23fb0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
23fc0 6d 6e 5f 62 79 74 65 73 28 53 2c 4e 29 5d 20 69  mn_bytes(S,N)] i
23fd0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
23fe0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
23ff0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
24000 20 69 6e 20 74 68 65 20 62 6c 6f 62 20 6f 72 20   in the blob or 
24010 73 74 72 69 6e 67 20 28 65 78 63 6c 75 73 69 76  string (exclusiv
24020 65 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20  e of the.**     
24030 20 20 20 20 20 7a 65 72 6f 20 74 65 72 6d 69 6e       zero termin
24040 61 74 6f 72 20 6f 6e 20 74 68 65 20 73 74 72 69  ator on the stri
24050 6e 67 29 20 74 68 61 74 20 77 61 73 20 72 65 74  ng) that was ret
24060 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20  urned by the.** 
24070 20 20 20 20 20 20 20 20 20 6d 6f 73 74 20 72 65           most re
24080 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  cent call to [sq
24090 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
240a0 62 28 53 2c 4e 29 5d 20 6f 72 0a 2a 2a 20 20 20  b(S,N)] or.**   
240b0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
240c0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 53 2c 4e 29  column_text(S,N)
240d0 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 30 39  ]..**.** {F13809
240e0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
240f0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 53 2c  olumn_bytes16(S,
24100 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  N)] interface re
24110 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20  turns the.**    
24120 20 20 20 20 20 20 6e 75 6d 62 65 72 20 6f 66 20        number of 
24130 62 79 74 65 73 20 69 6e 20 74 68 65 20 73 74 72  bytes in the str
24140 69 6e 67 20 28 65 78 63 6c 75 73 69 76 65 20 6f  ing (exclusive o
24150 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  f the.**        
24160 20 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f    zero terminato
24170 72 20 6f 6e 20 74 68 65 20 73 74 72 69 6e 67 29  r on the string)
24180 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e   that was return
24190 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 20 20 20  ed by the.**    
241a0 20 20 20 20 20 20 6d 6f 73 74 20 72 65 63 65 6e        most recen
241b0 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
241c0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
241d0 28 53 2c 4e 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46  (S,N)]..**.** {F
241e0 31 33 38 31 32 7d 20 54 68 65 20 5b 73 71 6c 69  13812} The [sqli
241f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c  te3_column_doubl
24200 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63  e(S,N)] interfac
24210 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a  e converts the.*
24220 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 63  *          Nth c
24230 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72  olumn in the cur
24240 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20  rent row of the 
24250 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72 0a 2a  result set for.*
24260 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70  *          [prep
24270 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
24280 53 20 69 6e 74 6f 20 61 20 66 6c 6f 61 74 69 6e  S into a floatin
24290 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 61 6e  g point value an
242a0 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  d.**          re
242b0 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 20  turns a copy of 
242c0 74 68 61 74 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a  that value..**.*
242d0 2a 20 7b 46 31 33 38 31 35 7d 20 54 68 65 20 5b  * {F13815} The [
242e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69  sqlite3_column_i
242f0 6e 74 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61  nt(S,N)] interfa
24300 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a  ce converts the.
24310 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20  **          Nth 
24320 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75  column in the cu
24330 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65  rrent row of the
24340 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72 0a   result set for.
24350 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65  **          [pre
24360 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
24370 20 53 20 69 6e 74 6f 20 61 20 36 34 2d 62 69 74   S into a 64-bit
24380 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20   signed integer 
24390 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  and.**          
243a0 72 65 74 75 72 6e 73 20 74 68 65 20 6c 6f 77 65  returns the lowe
243b0 72 20 33 32 20 62 69 74 73 20 6f 66 20 74 68 61  r 32 bits of tha
243c0 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a  t integer..**.**
243d0 20 7b 46 31 33 38 31 38 7d 20 54 68 65 20 5b 73   {F13818} The [s
243e0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e  qlite3_column_in
243f0 74 36 34 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66  t64(S,N)] interf
24400 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65  ace converts the
24410 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68  .**          Nth
24420 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63   column in the c
24430 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68  urrent row of th
24440 65 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72  e result set for
24450 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
24460 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
24470 5d 20 53 20 69 6e 74 6f 20 61 20 36 34 2d 62 69  ] S into a 64-bi
24480 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
24490 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20   and.**         
244a0 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20   returns a copy 
244b0 6f 66 20 74 68 61 74 20 69 6e 74 65 67 65 72 2e  of that integer.
244c0 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 32 31 7d 20  .**.** {F13821} 
244d0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  The [sqlite3_col
244e0 75 6d 6e 5f 74 65 78 74 28 53 2c 4e 29 5d 20 69  umn_text(S,N)] i
244f0 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74  nterface convert
24500 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
24510 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20    Nth column in 
24520 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20  the current row 
24530 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
24540 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  t for.**        
24550 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74    [prepared stat
24560 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20  ement] S into a 
24570 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
24580 55 54 46 2d 38 20 0a 2a 2a 20 20 20 20 20 20 20  UTF-8 .**       
24590 20 20 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65     string and re
245a0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
245b0 74 6f 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a  to that string..
245c0 2a 2a 0a 2a 2a 20 7b 46 31 33 38 32 34 7d 20 54  **.** {F13824} T
245d0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
245e0 6d 6e 5f 74 65 78 74 31 36 28 53 2c 4e 29 5d 20  mn_text16(S,N)] 
245f0 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72  interface conver
24600 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ts the.**       
24610 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e     Nth column in
24620 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77   the current row
24630 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
24640 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20  et for.**       
24650 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61     [prepared sta
24660 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61  tement] S into a
24670 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
24680 20 32 2d 62 79 74 65 0a 2a 2a 20 20 20 20 20 20   2-byte.**      
24690 20 20 20 20 61 6c 69 67 6e 65 64 20 55 54 46 2d      aligned UTF-
246a0 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  16 native byte o
246b0 72 64 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  rder.**         
246c0 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75   string and retu
246d0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
246e0 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a   that string..**
246f0 0a 2a 2a 20 7b 46 31 33 38 32 37 7d 20 54 68 65  .** {F13827} The
24700 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
24710 5f 74 79 70 65 28 53 2c 4e 29 5d 20 69 6e 74 65  _type(S,N)] inte
24720 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a  rface returns.**
24730 20 20 20 20 20 20 20 20 20 20 6f 6e 65 20 6f 66            one of
24740 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2c 20   [SQLITE_NULL], 
24750 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d  [SQLITE_INTEGER]
24760 2c 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d  , [SQLITE_FLOAT]
24770 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53  ,.**          [S
24780 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 6f 72 20  QLITE_TEXT], or 
24790 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 20 61 73  [SQLITE_BLOB] as
247a0 20 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72   appropriate for
247b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
247c0 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74   Nth column in t
247d0 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f  he current row o
247e0 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
247f0 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20   for.**         
24800 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
24810 6d 65 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b  ment] S..**.** {
24820 46 31 33 38 33 30 7d 20 54 68 65 20 5b 73 71 6c  F13830} The [sql
24830 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
24840 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63  e(S,N)] interfac
24850 65 20 72 65 74 75 72 6e 73 20 61 0a 2a 2a 20 20  e returns a.**  
24860 20 20 20 20 20 20 20 20 70 6f 69 6e 74 65 72 20          pointer 
24870 74 6f 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74  to an [unprotect
24880 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
24890 5d 20 6f 62 6a 65 63 74 20 66 6f 72 20 74 68 65  ] object for the
248a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68  .**          Nth
248b0 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63   column in the c
248c0 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68  urrent row of th
248d0 65 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72  e result set for
248e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
248f0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
24900 5d 20 53 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f  ] S..*/.const vo
24910 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
24920 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  mn_blob(sqlite3_
24930 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
24940 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
24950 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74  lumn_bytes(sqlit
24960 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
24970 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ol);.int sqlite3
24980 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
24990 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
249a0 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65  nt iCol);.double
249b0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
249c0 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73  double(sqlite3_s
249d0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
249e0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
249f0 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  umn_int(sqlite3_
24a00 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
24a10 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  ;.sqlite3_int64 
24a20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69  sqlite3_column_i
24a30 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d  nt64(sqlite3_stm
24a40 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63  t*, int iCol);.c
24a50 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68  onst unsigned ch
24a60 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
24a70 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f  mn_text(sqlite3_
24a80 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
24a90 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
24aa0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
24ab0 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t16(sqlite3_stmt
24ac0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e  *, int iCol);.in
24ad0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
24ae0 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74  _type(sqlite3_st
24af0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
24b00 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73  sqlite3_value *s
24b10 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
24b20 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lue(sqlite3_stmt
24b30 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f  *, int iCol);../
24b40 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
24b50 65 73 74 72 6f 79 20 41 20 50 72 65 70 61 72 65  estroy A Prepare
24b60 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65  d Statement Obje
24b70 63 74 20 7b 46 31 33 33 30 30 7d 0a 2a 2a 0a 2a  ct {F13300}.**.*
24b80 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69  * The sqlite3_fi
24b90 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69 6f  nalize() functio
24ba0 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 64  n is called to d
24bb0 65 6c 65 74 65 20 61 20 0a 2a 2a 20 5b 70 72 65  elete a .** [pre
24bc0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
24bd0 2e 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65  . If the stateme
24be0 6e 74 20 77 61 73 0a 2a 2a 20 65 78 65 63 75 74  nt was.** execut
24bf0 65 64 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c  ed successfully,
24c00 20 6f 72 20 6e 6f 74 20 65 78 65 63 75 74 65 64   or not executed
24c10 20 61 74 20 61 6c 6c 2c 20 74 68 65 6e 20 53 51   at all, then SQ
24c20 4c 49 54 45 5f 4f 4b 20 69 73 20 72 65 74 75 72  LITE_OK is retur
24c30 6e 65 64 2e 0a 2a 2a 20 49 66 20 65 78 65 63 75  ned..** If execu
24c40 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 74  tion of the stat
24c50 65 6d 65 6e 74 20 66 61 69 6c 65 64 20 74 68 65  ement failed the
24c60 6e 20 61 6e 20 0a 2a 2a 20 5b 65 72 72 6f 72 20  n an .** [error 
24c70 63 6f 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64  code] or [extend
24c80 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 0a 2a  ed error code].*
24c90 2a 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 0a  * is returned. .
24ca0 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
24cb0 6e 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64  ne can be called
24cc0 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 75   at any point du
24cd0 72 69 6e 67 20 74 68 65 20 65 78 65 63 75 74 69  ring the executi
24ce0 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 70 72  on of the.** [pr
24cf0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
24d00 5d 2e 20 20 49 66 20 74 68 65 20 76 69 72 74 75  ].  If the virtu
24d10 61 6c 20 6d 61 63 68 69 6e 65 20 68 61 73 20 6e  al machine has n
24d20 6f 74 20 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64  ot .** completed
24d30 20 65 78 65 63 75 74 69 6f 6e 20 77 68 65 6e 20   execution when 
24d40 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  this routine is 
24d50 63 61 6c 6c 65 64 2c 20 74 68 61 74 20 69 73 20  called, that is 
24d60 6c 69 6b 65 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65  like.** encounte
24d70 72 69 6e 67 20 61 6e 20 65 72 72 6f 72 20 6f 72  ring an error or
24d80 20 61 6e 20 69 6e 74 65 72 72 75 70 74 2e 20 20   an interrupt.  
24d90 28 53 65 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e  (See [sqlite3_in
24da0 74 65 72 72 75 70 74 28 29 5d 2e 29 20 0a 2a 2a  terrupt()].) .**
24db0 20 49 6e 63 6f 6d 70 6c 65 74 65 20 75 70 64 61   Incomplete upda
24dc0 74 65 73 20 6d 61 79 20 62 65 20 72 6f 6c 6c 65  tes may be rolle
24dd0 64 20 62 61 63 6b 20 61 6e 64 20 74 72 61 6e 73  d back and trans
24de0 61 63 74 69 6f 6e 73 20 63 61 6e 63 65 6c 6c 65  actions cancelle
24df0 64 2c 20 20 0a 2a 2a 20 64 65 70 65 6e 64 69 6e  d,  .** dependin
24e00 67 20 6f 6e 20 74 68 65 20 63 69 72 63 75 6d 73  g on the circums
24e10 74 61 6e 63 65 73 2c 20 61 6e 64 20 74 68 65 20  tances, and the 
24e20 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  .** [error code]
24e30 20 72 65 74 75 72 6e 65 64 20 77 69 6c 6c 20 62   returned will b
24e40 65 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d  e [SQLITE_ABORT]
24e50 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
24e60 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 33 30  TS:.**.** {F1130
24e70 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  2} The [sqlite3_
24e80 66 69 6e 61 6c 69 7a 65 28 53 29 5d 20 69 6e 74  finalize(S)] int
24e90 65 72 66 61 63 65 20 64 65 73 74 72 6f 79 73 20  erface destroys 
24ea0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
24eb0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
24ec0 65 6e 74 5d 20 53 20 61 6e 64 20 72 65 6c 65 61  ent] S and relea
24ed0 73 65 73 20 61 6c 6c 0a 2a 2a 20 20 20 20 20 20  ses all.**      
24ee0 20 20 20 20 6d 65 6d 6f 72 79 20 61 6e 64 20 66      memory and f
24ef0 69 6c 65 20 72 65 73 6f 75 72 63 65 73 20 68 65  ile resources he
24f00 6c 64 20 62 79 20 74 68 61 74 20 6f 62 6a 65 63  ld by that objec
24f10 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 33 30 34  t..**.** {F11304
24f20 7d 20 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65  } If the most re
24f30 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  cent call to [sq
24f40 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66  lite3_step(S)] f
24f50 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  or the.**       
24f60 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61     [prepared sta
24f70 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 75 72 6e  tement] S return
24f80 65 64 20 61 6e 20 65 72 72 6f 72 2c 0a 2a 2a 20  ed an error,.** 
24f90 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 5b 73           then [s
24fa0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
24fb0 53 29 5d 20 72 65 74 75 72 6e 73 20 74 68 61 74  S)] returns that
24fc0 20 73 61 6d 65 20 65 72 72 6f 72 2e 0a 2a 2f 0a   same error..*/.
24fd0 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  int sqlite3_fina
24fe0 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  lize(sqlite3_stm
24ff0 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
25000 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65  * CAPI3REF: Rese
25010 74 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  t A Prepared Sta
25020 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 20 7b 46  tement Object {F
25030 31 33 33 33 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  13330}.**.** The
25040 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29   sqlite3_reset()
25050 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c   function is cal
25060 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61 20 0a  led to reset a .
25070 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
25080 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 2e 0a  tement] object..
25090 2a 2a 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69  ** back to its i
250a0 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65  nitial state, re
250b0 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65  ady to be re-exe
250c0 63 75 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 53 51  cuted..** Any SQ
250d0 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69  L statement vari
250e0 61 62 6c 65 73 20 74 68 61 74 20 68 61 64 20 76  ables that had v
250f0 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74  alues bound to t
25100 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65  hem using.** the
25110 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
25120 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69  lob | sqlite3_bi
25130 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61  nd_*() API] reta
25140 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e  in their values.
25150 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33  .** Use [sqlite3
25160 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28  _clear_bindings(
25170 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20  )] to reset the 
25180 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20  bindings..**.** 
25190 7b 46 31 31 33 33 32 7d 20 54 68 65 20 5b 73 71  {F11332} The [sq
251a0 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
251b0 69 6e 74 65 72 66 61 63 65 20 72 65 73 65 74 73  interface resets
251c0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
251d0 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 20  tatement] S.**  
251e0 20 20 20 20 20 20 20 20 62 61 63 6b 20 74 6f 20          back to 
251f0 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66  the beginning of
25200 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a   its program..**
25210 0a 2a 2a 20 7b 46 31 31 33 33 34 7d 20 49 66 20  .** {F11334} If 
25220 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
25230 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
25240 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 0a 2a  _step(S)] for .*
25250 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70  *          [prep
25260 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
25270 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49  S returned [SQLI
25280 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49  TE_ROW] or [SQLI
25290 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 20 20 20  TE_DONE],.**    
252a0 20 20 20 20 20 20 6f 72 20 69 66 20 5b 73 71 6c        or if [sql
252b0 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61  ite3_step(S)] ha
252c0 73 20 6e 65 76 65 72 20 62 65 66 6f 72 65 20 62  s never before b
252d0 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c  een called on S,
252e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
252f0 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  n [sqlite3_reset
25300 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51  (S)] returns [SQ
25310 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20  LITE_OK]..**.** 
25320 7b 46 31 31 33 33 36 7d 20 49 66 20 74 68 65 20  {F11336} If the 
25330 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c  most recent call
25340 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
25350 70 28 53 29 5d 20 66 6f 72 0a 2a 2a 20 20 20 20  p(S)] for.**    
25360 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20        [prepared 
25370 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64  statement] S ind
25380 69 63 61 74 65 64 20 61 6e 20 65 72 72 6f 72 2c  icated an error,
25390 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20   then.**        
253a0 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74    [sqlite3_reset
253b0 28 53 29 5d 20 72 65 74 75 72 6e 73 20 61 6e 20  (S)] returns an 
253c0 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72  appropriate [err
253d0 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20  or code]..**.** 
253e0 7b 46 31 31 33 33 38 7d 20 54 68 65 20 5b 73 71  {F11338} The [sq
253f0 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
25400 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20 6e  interface does n
25410 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61  ot change the va
25420 6c 75 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  lues.**         
25430 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69 74 65 33   of any [sqlite3
25440 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69  _bind_blob|bindi
25450 6e 67 73 5d 20 6f 6e 20 5b 70 72 65 70 61 72 65  ngs] on [prepare
25460 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a  d statement] S..
25470 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72  */.int sqlite3_r
25480 65 73 65 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  eset(sqlite3_stm
25490 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
254a0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 72 65 61  * CAPI3REF: Crea
254b0 74 65 20 4f 72 20 52 65 64 65 66 69 6e 65 20 53  te Or Redefine S
254c0 51 4c 20 46 75 6e 63 74 69 6f 6e 73 20 7b 46 31  QL Functions {F1
254d0 36 31 30 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  6100}.** KEYWORD
254e0 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65  S: {function cre
254f0 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 20  ation routines} 
25500 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 74 77 6f  .**.** These two
25510 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c   functions (coll
25520 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61  ectively known a
25530 73 0a 2a 2a 20 22 66 75 6e 63 74 69 6f 6e 20 63  s.** "function c
25540 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  reation routines
25550 22 29 20 61 72 65 20 75 73 65 64 20 74 6f 20 61  ") are used to a
25560 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  dd SQL functions
25570 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 0a 2a   or aggregates.*
25580 2a 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65  * or to redefine
25590 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66   the behavior of
255a0 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75   existing SQL fu
255b0 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65  nctions or aggre
255c0 67 61 74 65 73 2e 20 20 54 68 65 0a 2a 2a 20 64  gates.  The.** d
255d0 69 66 66 65 72 65 6e 63 65 20 6f 6e 6c 79 20 62  ifference only b
255e0 65 74 77 65 65 6e 20 74 68 65 20 74 77 6f 20 69  etween the two i
255f0 73 20 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e  s that the secon
25600 64 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65  d parameter, the
25610 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  .** name of the 
25620 28 73 63 61 6c 61 72 29 20 66 75 6e 63 74 69 6f  (scalar) functio
25630 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20  n or aggregate, 
25640 69 73 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54  is encoded in UT
25650 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74  F-8 for.** sqlit
25660 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
25670 6f 6e 28 29 20 61 6e 64 20 55 54 46 2d 31 36 20  on() and UTF-16 
25680 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61  for sqlite3_crea
25690 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 2e  te_function16().
256a0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
256b0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
256c0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
256d0 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68  ection] to which
256e0 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63   the SQL.** func
256f0 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 20 61 64  tion is to be ad
25700 64 65 64 2e 20 20 49 66 20 61 20 73 69 6e 67 6c  ded.  If a singl
25710 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 65  e.** program use
25720 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20  s more than one 
25730 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
25740 74 69 6f 6e 5d 20 69 6e 74 65 72 6e 61 6c 6c 79  tion] internally
25750 2c 20 74 68 65 6e 20 53 51 4c 0a 2a 2a 20 66 75  , then SQL.** fu
25760 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20  nctions must be 
25770 61 64 64 65 64 20 69 6e 64 69 76 69 64 75 61 6c  added individual
25780 6c 79 20 74 6f 20 65 61 63 68 20 5b 64 61 74 61  ly to each [data
25790 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
257a0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f  ..**.** The seco
257b0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
257c0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
257d0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  SQL function to 
257e0 62 65 20 63 72 65 61 74 65 64 0a 2a 2a 20 6f 72  be created.** or
257f0 20 72 65 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54   redefined..** T
25800 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65  he length of the
25810 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 64   name is limited
25820 20 74 6f 20 32 35 35 20 62 79 74 65 73 2c 20 65   to 255 bytes, e
25830 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65 20  xclusive of the 
25840 0a 2a 2a 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  .** zero-termina
25850 74 6f 72 2e 20 20 4e 6f 74 65 20 74 68 61 74 20  tor.  Note that 
25860 74 68 65 20 6e 61 6d 65 20 6c 65 6e 67 74 68 20  the name length 
25870 6c 69 6d 69 74 20 69 73 20 69 6e 20 62 79 74 65  limit is in byte
25880 73 2c 20 6e 6f 74 0a 2a 2a 20 63 68 61 72 61 63  s, not.** charac
25890 74 65 72 73 2e 20 20 41 6e 79 20 61 74 74 65 6d  ters.  Any attem
258a0 70 74 20 74 6f 20 63 72 65 61 74 65 20 61 20 66  pt to create a f
258b0 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c  unction with a l
258c0 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69  onger name.** wi
258d0 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20  ll result in an 
258e0 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 65 72 72  SQLITE_ERROR err
258f0 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68  or..**.** The th
25900 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ird parameter is
25910 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61   the number of a
25920 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68  rguments that th
25930 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  e SQL function o
25940 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74  r.** aggregate t
25950 61 6b 65 73 2e 20 49 66 20 74 68 69 73 20 70 61  akes. If this pa
25960 72 61 6d 65 74 65 72 20 69 73 20 6e 65 67 61 74  rameter is negat
25970 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20 53 51  ive, then the SQ
25980 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a  L function or.**
25990 20 61 67 67 72 65 67 61 74 65 20 6d 61 79 20 74   aggregate may t
259a0 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f  ake any number o
259b0 66 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a  f arguments..**.
259c0 2a 2a 20 54 68 65 20 66 6f 75 72 74 68 20 70 61  ** The fourth pa
259d0 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65  rameter, eTextRe
259e0 70 2c 20 73 70 65 63 69 66 69 65 73 20 77 68 61  p, specifies wha
259f0 74 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54  t .** [SQLITE_UT
25a00 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69  F8 | text encodi
25a10 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e  ng] this SQL fun
25a20 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f  ction prefers fo
25a30 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74  r.** its paramet
25a40 65 72 73 2e 20 20 41 6e 79 20 53 51 4c 20 66 75  ers.  Any SQL fu
25a50 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
25a60 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20  ation should be 
25a70 61 62 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20  able to work.** 
25a80 77 6f 72 6b 20 77 69 74 68 20 55 54 46 2d 38 2c  work with UTF-8,
25a90 20 55 54 46 2d 31 36 6c 65 2c 20 6f 72 20 55 54   UTF-16le, or UT
25aa0 46 2d 31 36 62 65 2e 20 20 42 75 74 20 73 6f 6d  F-16be.  But som
25ab0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
25ac0 73 20 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f 72 65  s may be.** more
25ad0 20 65 66 66 69 63 69 65 6e 74 20 77 69 74 68 20   efficient with 
25ae0 6f 6e 65 20 65 6e 63 6f 64 69 6e 67 20 74 68 61  one encoding tha
25af0 6e 20 61 6e 6f 74 68 65 72 2e 20 20 49 74 20 69  n another.  It i
25b00 73 20 61 6c 6c 6f 77 65 64 20 74 6f 0a 2a 2a 20  s allowed to.** 
25b10 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63  invoke sqlite3_c
25b20 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
25b30 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61   or sqlite3_crea
25b40 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 20  te_function16() 
25b50 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65  multiple.** time
25b60 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20  s with the same 
25b70 66 75 6e 63 74 69 6f 6e 20 62 75 74 20 77 69 74  function but wit
25b80 68 20 64 69 66 66 65 72 65 6e 74 20 76 61 6c 75  h different valu
25b90 65 73 20 6f 66 20 65 54 65 78 74 52 65 70 2e 0a  es of eTextRep..
25ba0 2a 2a 20 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65  ** When multiple
25bb0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
25bc0 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e   of the same fun
25bd0 63 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61  ction are availa
25be0 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77  ble, SQLite.** w
25bf0 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65  ill pick the one
25c00 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74   that involves t
25c10 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20  he least amount 
25c20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69  of data conversi
25c30 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 72 65 20  on..** If there 
25c40 69 73 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c 65  is only a single
25c50 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
25c60 77 68 69 63 68 20 64 6f 65 73 20 6e 6f 74 20 63  which does not c
25c70 61 72 65 20 77 68 61 74 0a 2a 2a 20 74 65 78 74  are what.** text
25c80 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65   encoding is use
25c90 64 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72  d, then the four
25ca0 74 68 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  th argument shou
25cb0 6c 64 20 62 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  ld be.** [SQLITE
25cc0 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  _ANY]..**.** The
25cd0 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72   fifth parameter
25ce0 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 79   is an arbitrary
25cf0 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69   pointer.  The i
25d00 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a  mplementation.**
25d10 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   of the function
25d20 20 63 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73   can gain access
25d30 20 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72   to this pointer
25d40 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
25d50 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e  e3_user_data()].
25d60 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 76 65 6e  .**.** The seven
25d70 74 68 2c 20 65 69 67 68 74 68 20 61 6e 64 20 6e  th, eighth and n
25d80 69 6e 74 68 20 70 61 72 61 6d 65 74 65 72 73 2c  inth parameters,
25d90 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20 61 6e   xFunc, xStep an
25da0 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a  d xFinal, are.**
25db0 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c   pointers to C-l
25dc0 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69 6f 6e  anguage function
25dd0 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  s that implement
25de0 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63   the SQL.** func
25df0 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74  tion or aggregat
25e00 65 2e 20 41 20 73 63 61 6c 61 72 20 53 51 4c 20  e. A scalar SQL 
25e10 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65  function require
25e20 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  s an implementat
25e30 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 20 78 46  ion of.** the xF
25e40 75 6e 63 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c  unc callback onl
25e50 79 2c 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73  y, NULL pointers
25e60 20 73 68 6f 75 6c 64 20 62 65 20 70 61 73 73 65   should be passe
25e70 64 20 61 73 20 74 68 65 20 78 53 74 65 70 0a 2a  d as the xStep.*
25e80 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 70 61 72  * and xFinal par
25e90 61 6d 65 74 65 72 73 2e 20 41 6e 20 61 67 67 72  ameters. An aggr
25ea0 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69  egate SQL functi
25eb0 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69  on requires an i
25ec0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a  mplementation.**
25ed0 20 6f 66 20 78 53 74 65 70 20 61 6e 64 20 78 46   of xStep and xF
25ee0 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 73 68  inal and NULL sh
25ef0 6f 75 6c 64 20 62 65 20 70 61 73 73 65 64 20 66  ould be passed f
25f00 6f 72 20 78 46 75 6e 63 2e 20 54 6f 20 64 65 6c  or xFunc. To del
25f10 65 74 65 20 61 6e 0a 2a 2a 20 65 78 69 73 74 69  ete an.** existi
25f20 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ng SQL function 
25f30 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20 70 61  or aggregate, pa
25f40 73 73 20 4e 55 4c 4c 20 66 6f 72 20 61 6c 6c 20  ss NULL for all 
25f50 74 68 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a  three function.*
25f60 2a 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a  * callback..**.*
25f70 2a 20 49 74 20 69 73 20 70 65 72 6d 69 74 74 65  * It is permitte
25f80 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d 75  d to register mu
25f90 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  ltiple implement
25fa0 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
25fb0 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20  me.** functions 
25fc0 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61  with the same na
25fd0 6d 65 20 62 75 74 20 77 69 74 68 20 65 69 74 68  me but with eith
25fe0 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75 6d  er differing num
25ff0 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d  bers of.** argum
26000 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69 6e  ents or differin
26010 67 20 70 65 72 66 65 72 72 65 64 20 74 65 78 74  g perferred text
26020 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 53 51 4c   encodings.  SQL
26030 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20  ite will use.** 
26040 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
26050 6f 6e 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20  on most closely 
26060 6d 61 74 63 68 65 73 20 74 68 65 20 77 61 79 20  matches the way 
26070 69 6e 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20  in which the.** 
26080 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  SQL function is 
26090 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  used..**.** INVA
260a0 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  RIANTS:.**.** {F
260b0 31 36 31 30 33 7d 20 54 68 65 20 5b 73 71 6c 69  16103} The [sqli
260c0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
260d0 69 6f 6e 31 36 28 29 5d 20 69 6e 74 65 72 66 61  ion16()] interfa
260e0 63 65 20 62 65 68 61 76 65 73 20 65 78 61 63 74  ce behaves exact
260f0 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6c  ly.**          l
26100 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  ike [sqlite3_cre
26110 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20  ate_function()] 
26120 69 6e 20 65 76 65 72 79 20 77 61 79 20 65 78 63  in every way exc
26130 65 70 74 20 74 68 61 74 20 69 74 0a 2a 2a 20 20  ept that it.**  
26140 20 20 20 20 20 20 20 20 69 6e 74 65 72 70 72 65          interpre
26150 74 73 20 74 68 65 20 7a 46 75 6e 63 74 69 6f 6e  ts the zFunction
26160 4e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 61 73  Name argument as
26170 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72  .**          zer
26180 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
26190 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20  -16 native byte 
261a0 6f 72 64 65 72 20 69 6e 73 74 65 61 64 20 6f 66  order instead of
261b0 20 61 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20   as a.**        
261c0 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65    zero-terminate
261d0 64 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b  d UTF-8..**.** {
261e0 46 31 36 31 30 36 7d 20 41 20 73 75 63 63 65 73  F16106} A succes
261f0 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20  sful invocation 
26200 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  of.**          t
26210 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  he [sqlite3_crea
26220 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c  te_function(D,X,
26230 4e 2c 45 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66  N,E,...)] interf
26240 61 63 65 20 72 65 67 69 73 74 65 72 73 0a 2a 2a  ace registers.**
26250 20 20 20 20 20 20 20 20 20 20 6f 72 20 72 65 70            or rep
26260 6c 61 63 65 73 20 63 61 6c 6c 62 61 63 6b 20 66  laces callback f
26270 75 6e 63 74 69 6f 6e 73 20 69 6e 20 5b 64 61 74  unctions in [dat
26280 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
26290 5d 20 44 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ] D.**          
262a0 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  used to implemen
262b0 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  t the SQL functi
262c0 6f 6e 20 6e 61 6d 65 64 20 58 20 77 69 74 68 20  on named X with 
262d0 4e 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20  N parameters.** 
262e0 20 20 20 20 20 20 20 20 20 61 6e 64 20 68 61 76           and hav
262f0 69 6e 67 20 61 20 70 65 72 66 65 72 72 65 64 20  ing a perferred 
26300 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 6f 66  text encoding of
26310 20 45 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 30   E..**.** {F1610
26320 39 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20  9} A successful 
26330 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
26340 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
26350 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c  (D,X,N,E,P,F,S,L
26360 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  )].**          r
26370 65 70 6c 61 63 65 73 20 74 68 65 20 50 2c 20 46  eplaces the P, F
26380 2c 20 53 2c 20 61 6e 64 20 4c 20 76 61 6c 75 65  , S, and L value
26390 73 20 66 72 6f 6d 20 61 6e 79 20 70 72 69 6f 72  s from any prior
263a0 20 63 61 6c 6c 73 20 77 69 74 68 0a 2a 2a 20 20   calls with.**  
263b0 20 20 20 20 20 20 20 20 74 68 65 20 73 61 6d 65          the same
263c0 20 44 2c 20 58 2c 20 4e 2c 20 61 6e 64 20 45 20   D, X, N, and E 
263d0 76 61 6c 75 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46  values..**.** {F
263e0 31 36 31 31 32 7d 20 54 68 65 20 5b 73 71 6c 69  16112} The [sqli
263f0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
26400 69 6f 6e 28 44 2c 58 2c 2e 2e 2e 29 5d 20 69 6e  ion(D,X,...)] in
26410 74 65 72 66 61 63 65 20 66 61 69 6c 73 20 77 69  terface fails wi
26420 74 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  th.**          a
26430 20 72 65 74 75 72 6e 20 63 6f 64 65 20 6f 66 20   return code of 
26440 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69  [SQLITE_ERROR] i
26450 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  f the SQL functi
26460 6f 6e 20 6e 61 6d 65 20 58 20 69 73 0a 2a 2a 20  on name X is.** 
26470 20 20 20 20 20 20 20 20 20 6c 6f 6e 67 65 72 20           longer 
26480 74 68 61 6e 20 32 35 35 20 62 79 74 65 73 20 65  than 255 bytes e
26490 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65 20  xclusive of the 
264a0 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e  zero terminator.
264b0 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 31 38 7d 20  .**.** {F16118} 
264c0 45 69 74 68 65 72 20 46 20 6d 75 73 74 20 62 65  Either F must be
264d0 20 4e 55 4c 4c 20 61 6e 64 20 53 20 61 6e 64 20   NULL and S and 
264e0 4c 20 61 72 65 20 6e 6f 6e 2d 4e 55 4c 4c 20 6f  L are non-NULL o
264f0 72 20 65 6c 73 65 20 46 0a 2a 2a 20 20 20 20 20  r else F.**     
26500 20 20 20 20 20 69 73 20 6e 6f 6e 2d 4e 55 4c 4c       is non-NULL
26510 20 61 6e 64 20 53 20 61 6e 64 20 4c 20 61 72 65   and S and L are
26520 20 4e 55 4c 4c 2c 20 6f 74 68 65 72 77 69 73 65   NULL, otherwise
26530 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
26540 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
26550 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c  ction(D,X,N,E,P,
26560 46 2c 53 2c 4c 29 5d 20 72 65 74 75 72 6e 73 20  F,S,L)] returns 
26570 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 0a  [SQLITE_ERROR]..
26580 2a 2a 0a 2a 2a 20 7b 46 31 36 31 32 31 7d 20 54  **.** {F16121} T
26590 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  he [sqlite3_crea
265a0 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 2e 2e  te_function(D,..
265b0 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 66 61  .)] interface fa
265c0 69 6c 73 20 77 69 74 68 20 61 6e 0a 2a 2a 20 20  ils with an.**  
265d0 20 20 20 20 20 20 20 20 65 72 72 6f 72 20 63 6f          error co
265e0 64 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 42 55  de of [SQLITE_BU
265f0 53 59 5d 20 69 66 20 74 68 65 72 65 20 65 78 69  SY] if there exi
26600 73 74 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  st [prepared sta
26610 74 65 6d 65 6e 74 73 5d 0a 2a 2a 20 20 20 20 20  tements].**     
26620 20 20 20 20 20 61 73 73 6f 63 69 61 74 65 64 20       associated 
26630 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61  with the [databa
26640 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
26650 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 32 34 7d  ..**.** {F16124}
26660 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72   The [sqlite3_cr
26670 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c  eate_function(D,
26680 58 2c 4e 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66  X,N,...)] interf
26690 61 63 65 20 66 61 69 6c 73 20 77 69 74 68 20 61  ace fails with a
266a0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 72  n.**          er
266b0 72 6f 72 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c  ror code of [SQL
266c0 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 70 61  ITE_ERROR] if pa
266d0 72 61 6d 65 74 65 72 20 4e 20 28 73 70 65 63 69  rameter N (speci
266e0 66 79 69 6e 67 20 74 68 65 20 6e 75 6d 62 65 72  fying the number
266f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20  .**          of 
26700 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65  arguments to the
26710 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 62 65   SQL function be
26720 69 6e 67 20 72 65 67 69 73 74 65 72 65 64 29 20  ing registered) 
26730 69 73 20 6c 65 73 73 0a 2a 2a 20 20 20 20 20 20  is less.**      
26740 20 20 20 20 74 68 61 6e 20 2d 31 20 6f 72 20 67      than -1 or g
26750 72 65 61 74 65 72 20 74 68 61 6e 20 31 32 37 2e  reater than 127.
26760 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 32 37 7d 20  .**.** {F16127} 
26770 57 68 65 6e 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65  When N is non-ne
26780 67 61 74 69 76 65 2c 20 74 68 65 20 5b 73 71 6c  gative, the [sql
26790 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
267a0 74 69 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d  tion(D,X,N,...)]
267b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74  .**          int
267c0 65 72 66 61 63 65 20 63 61 75 73 65 73 20 63 61  erface causes ca
267d0 6c 6c 62 61 63 6b 73 20 74 6f 20 62 65 20 69 6e  llbacks to be in
267e0 76 6f 6b 65 64 20 66 6f 72 20 74 68 65 20 53 51  voked for the SQ
267f0 4c 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20  L function.**   
26800 20 20 20 20 20 20 20 6e 61 6d 65 64 20 58 20 77         named X w
26810 68 65 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  hen the number o
26820 66 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  f arguments to t
26830 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
26840 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65  is.**          e
26850 78 61 63 74 6c 79 20 4e 2e 0a 2a 2a 0a 2a 2a 20  xactly N..**.** 
26860 7b 46 31 36 31 33 30 7d 20 57 68 65 6e 20 4e 20  {F16130} When N 
26870 69 73 20 2d 31 2c 20 74 68 65 20 5b 73 71 6c 69  is -1, the [sqli
26880 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
26890 69 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d 0a  ion(D,X,N,...)].
268a0 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65  **          inte
268b0 72 66 61 63 65 20 63 61 75 73 65 73 20 63 61 6c  rface causes cal
268c0 6c 62 61 63 6b 73 20 74 6f 20 62 65 20 69 6e 76  lbacks to be inv
268d0 6f 6b 65 64 20 66 6f 72 20 74 68 65 20 53 51 4c  oked for the SQL
268e0 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20 20   function.**    
268f0 20 20 20 20 20 20 6e 61 6d 65 64 20 58 20 77 69        named X wi
26900 74 68 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66  th any number of
26910 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a   arguments..**.*
26920 2a 20 7b 46 31 36 31 33 33 7d 20 57 68 65 6e 20  * {F16133} When 
26930 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
26940 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
26950 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a  n(D,X,N,...)].**
26960 20 20 20 20 20 20 20 20 20 20 73 70 65 63 69 66            specif
26970 79 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65  y multiple imple
26980 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68  mentations of th
26990 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20  e same function 
269a0 58 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e  X.**          an
269b0 64 20 77 68 65 6e 20 6f 6e 65 20 69 6d 70 6c 65  d when one imple
269c0 6d 65 6e 74 61 74 69 6f 6e 20 68 61 73 20 4e 3e  mentation has N>
269d0 3d 30 20 61 6e 64 20 74 68 65 20 6f 74 68 65 72  =0 and the other
269e0 20 68 61 73 20 4e 3d 28 2d 31 29 0a 2a 2a 20 20   has N=(-1).**  
269f0 20 20 20 20 20 20 20 20 74 68 65 20 69 6d 70 6c          the impl
26a00 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20  ementation with 
26a10 61 20 6e 6f 6e 2d 7a 65 72 6f 20 4e 20 69 73 20  a non-zero N is 
26a20 70 72 65 66 65 72 72 65 64 2e 0a 2a 2a 0a 2a 2a  preferred..**.**
26a30 20 7b 46 31 36 31 33 36 7d 20 57 68 65 6e 20 63   {F16136} When c
26a40 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
26a50 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
26a60 28 44 2c 58 2c 4e 2c 45 2c 2e 2e 2e 29 5d 0a 2a  (D,X,N,E,...)].*
26a70 2a 20 20 20 20 20 20 20 20 20 20 73 70 65 63 69  *          speci
26a80 66 79 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c  fy multiple impl
26a90 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74  ementations of t
26aa0 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e  he same function
26ab0 20 58 20 77 69 74 68 0a 2a 2a 20 20 20 20 20 20   X with.**      
26ac0 20 20 20 20 74 68 65 20 73 61 6d 65 20 6e 75 6d      the same num
26ad0 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73  ber of arguments
26ae0 20 4e 20 62 75 74 20 77 69 74 68 20 64 69 66 66   N but with diff
26af0 65 72 65 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20  erent.**        
26b00 20 20 65 6e 63 6f 64 69 6e 67 73 20 45 2c 20 74    encodings E, t
26b10 68 65 6e 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e  hen the implemen
26b20 74 61 74 69 6f 6e 20 77 68 65 72 65 20 45 20 6d  tation where E m
26b30 61 74 63 68 65 73 20 74 68 65 0a 2a 2a 20 20 20  atches the.**   
26b40 20 20 20 20 20 20 20 64 61 74 61 62 61 73 65 20         database 
26b50 65 6e 63 6f 64 69 6e 67 20 69 73 20 70 72 65 66  encoding is pref
26b60 65 72 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  erred..**.** {F1
26b70 36 31 33 39 7d 20 46 6f 72 20 61 6e 20 61 67 67  6139} For an agg
26b80 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74  regate SQL funct
26b90 69 6f 6e 20 63 72 65 61 74 65 64 20 75 73 69 6e  ion created usin
26ba0 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  g.**          [s
26bb0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
26bc0 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50  nction(D,X,N,E,P
26bd0 2c 30 2c 53 2c 4c 29 5d 20 74 68 65 20 66 69 6e  ,0,S,L)] the fin
26be0 69 61 6c 69 7a 65 72 0a 2a 2a 20 20 20 20 20 20  ializer.**      
26bf0 20 20 20 20 66 75 6e 63 74 69 6f 6e 20 4c 20 77      function L w
26c00 69 6c 6c 20 61 6c 77 61 79 73 20 62 65 20 69 6e  ill always be in
26c10 76 6f 6b 65 64 20 65 78 61 63 74 6c 79 20 6f 6e  voked exactly on
26c20 63 65 20 69 66 20 74 68 65 0a 2a 2a 20 20 20 20  ce if the.**    
26c30 20 20 20 20 20 20 73 74 65 70 20 66 75 6e 63 74        step funct
26c40 69 6f 6e 20 53 20 69 73 20 63 61 6c 6c 65 64 20  ion S is called 
26c50 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  one or more time
26c60 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 34 32  s..**.** {F16142
26c70 7d 20 57 68 65 6e 20 53 51 4c 69 74 65 20 69 6e  } When SQLite in
26c80 76 6f 6b 65 73 20 65 69 74 68 65 72 20 74 68 65  vokes either the
26c90 20 78 46 75 6e 63 20 6f 72 20 78 53 74 65 70 20   xFunc or xStep 
26ca0 66 75 6e 63 74 69 6f 6e 20 6f 66 0a 2a 2a 20 20  function of.**  
26cb0 20 20 20 20 20 20 20 20 61 6e 20 61 70 70 6c 69          an appli
26cc0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
26cd0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61  QL function or a
26ce0 67 67 72 65 67 61 74 65 20 63 72 65 61 74 65 64  ggregate created
26cf0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 79 20  .**          by 
26d00 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
26d10 66 75 6e 63 74 69 6f 6e 28 29 5d 20 6f 72 20 5b  function()] or [
26d20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
26d30 75 6e 63 74 69 6f 6e 31 36 28 29 5d 2c 0a 2a 2a  unction16()],.**
26d40 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 74            then t
26d50 68 65 20 61 72 72 61 79 20 6f 66 20 5b 73 71 6c  he array of [sql
26d60 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
26d70 63 74 73 20 70 61 73 73 65 64 20 61 73 20 74 68  cts passed as th
26d80 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  e.**          th
26d90 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 61 72  ird parameter ar
26da0 65 20 61 6c 77 61 79 73 20 5b 70 72 6f 74 65 63  e always [protec
26db0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
26dc0 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 69  e] objects..*/.i
26dd0 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
26de0 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71  e_function(.  sq
26df0 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e  lite3 *db,.  con
26e00 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69  st char *zFuncti
26e10 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41  onName,.  int nA
26e20 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52  rg,.  int eTextR
26e30 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70  ep,.  void *pApp
26e40 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63  ,.  void (*xFunc
26e50 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
26e60 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
26e70 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
26e80 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33  (*xStep)(sqlite3
26e90 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
26ea0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
26eb0 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29    void (*xFinal)
26ec0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
26ed0 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  *).);.int sqlite
26ee0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
26ef0 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  n16(.  sqlite3 *
26f00 64 62 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64  db,.  const void
26f10 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c   *zFunctionName,
26f20 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69  .  int nArg,.  i
26f30 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76  nt eTextRep,.  v
26f40 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69  oid *pApp,.  voi
26f50 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74  d (*xFunc)(sqlit
26f60 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
26f70 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
26f80 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70  ,.  void (*xStep
26f90 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
26fa0 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
26fb0 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
26fc0 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65  (*xFinal)(sqlite
26fd0 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 0a  3_context*).);..
26fe0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
26ff0 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 20 7b  Text Encodings {
27000 46 31 30 32 36 37 7d 0a 2a 2a 0a 2a 2a 20 54 68  F10267}.**.** Th
27010 65 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 65 66  ese constant def
27020 69 6e 65 20 69 6e 74 65 67 65 72 20 63 6f 64 65  ine integer code
27030 73 20 74 68 61 74 20 72 65 70 72 65 73 65 6e 74  s that represent
27040 20 74 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20   the various.** 
27050 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 20 73  text encodings s
27060 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69  upported by SQLi
27070 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  te..*/.#define S
27080 51 4c 49 54 45 5f 55 54 46 38 20 20 20 20 20 20  QLITE_UTF8      
27090 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
270a0 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 20 20  QLITE_UTF16LE   
270b0 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
270c0 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20 20  QLITE_UTF16BE   
270d0 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
270e0 51 4c 49 54 45 5f 55 54 46 31 36 20 20 20 20 20  QLITE_UTF16     
270f0 20 20 20 20 20 34 20 20 20 20 2f 2a 20 55 73 65       4    /* Use
27100 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
27110 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  er */.#define SQ
27120 4c 49 54 45 5f 41 4e 59 20 20 20 20 20 20 20 20  LITE_ANY        
27130 20 20 20 20 35 20 20 20 20 2f 2a 20 73 71 6c 69      5    /* sqli
27140 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
27150 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  ion only */.#def
27160 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
27170 5f 41 4c 49 47 4e 45 44 20 20 38 20 20 20 20 2f  _ALIGNED  8    /
27180 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  * sqlite3_create
27190 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20  _collation only 
271a0 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
271b0 45 46 3a 20 4f 62 73 6f 6c 65 74 65 20 46 75 6e  EF: Obsolete Fun
271c0 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65  ctions.**.** The
271d0 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65  se functions are
271e0 20 61 6c 6c 20 6e 6f 77 20 6f 62 73 6f 6c 65 74   all now obsolet
271f0 65 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20  e.  In order to 
27200 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b  maintain.** back
27210 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
27220 69 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20 63  ity with older c
27230 6f 64 65 2c 20 77 65 20 63 6f 6e 74 69 6e 75 65  ode, we continue
27240 20 74 6f 20 73 75 70 70 6f 72 74 0a 2a 2a 20 74   to support.** t
27250 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20  hese functions. 
27260 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 64 65   However, new de
27270 76 65 6c 6f 70 6d 65 6e 74 20 70 72 6f 6a 65 63  velopment projec
27280 74 73 20 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a  ts should avoid.
27290 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 74 68  ** the use of th
272a0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20  ese functions.  
272b0 54 6f 20 68 65 6c 70 20 65 6e 63 6f 75 72 61 67  To help encourag
272c0 65 20 70 65 6f 70 6c 65 20 74 6f 20 61 76 6f 69  e people to avoi
272d0 64 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 73 65  d.** using these
272e0 20 66 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20 61   functions, we a
272f0 72 65 20 6e 6f 74 20 67 6f 69 6e 67 20 74 6f 20  re not going to 
27300 74 65 6c 6c 20 79 6f 75 20 77 61 6e 74 20 74 68  tell you want th
27310 65 79 20 64 6f 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ey do..*/.int sq
27320 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
27330 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f  count(sqlite3_co
27340 6e 74 65 78 74 2a 29 3b 0a 69 6e 74 20 73 71 6c  ntext*);.int sql
27350 69 74 65 33 5f 65 78 70 69 72 65 64 28 73 71 6c  ite3_expired(sql
27360 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 69 6e 74  ite3_stmt*);.int
27370 20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 65   sqlite3_transfe
27380 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74  r_bindings(sqlit
27390 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65  e3_stmt*, sqlite
273a0 33 5f 73 74 6d 74 2a 29 3b 0a 69 6e 74 20 73 71  3_stmt*);.int sq
273b0 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63  lite3_global_rec
273c0 6f 76 65 72 28 76 6f 69 64 29 3b 0a 76 6f 69 64  over(void);.void
273d0 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 5f   sqlite3_thread_
273e0 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a 69  cleanup(void);.i
273f0 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  nt sqlite3_memor
27400 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29 28  y_alarm(void(*)(
27410 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e  void*,sqlite3_in
27420 74 36 34 2c 69 6e 74 29 2c 76 6f 69 64 2a 2c 73  t64,int),void*,s
27430 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 0a  qlite3_int64);..
27440 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
27450 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c 20 46 75  Obtaining SQL Fu
27460 6e 63 74 69 6f 6e 20 50 61 72 61 6d 65 74 65 72  nction Parameter
27470 20 56 61 6c 75 65 73 20 7b 46 31 35 31 30 30 7d   Values {F15100}
27480 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e  .**.** The C-lan
27490 67 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61  guage implementa
274a0 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63  tion of SQL func
274b0 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67  tions and aggreg
274c0 61 74 65 73 20 75 73 65 73 0a 2a 2a 20 74 68 69  ates uses.** thi
274d0 73 20 73 65 74 20 6f 66 20 69 6e 74 65 72 66 61  s set of interfa
274e0 63 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 61  ce routines to a
274f0 63 63 65 73 73 20 74 68 65 20 70 61 72 61 6d 65  ccess the parame
27500 74 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a  ter values on.**
27510 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72   the function or
27520 20 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a   aggregate..**.*
27530 2a 20 54 68 65 20 78 46 75 6e 63 20 28 66 6f 72  * The xFunc (for
27540 20 73 63 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e   scalar function
27550 73 29 20 6f 72 20 78 53 74 65 70 20 28 66 6f 72  s) or xStep (for
27560 20 61 67 67 72 65 67 61 74 65 73 29 20 70 61 72   aggregates) par
27570 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73  ameters.** to [s
27580 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
27590 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73  nction()] and [s
275a0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
275b0 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64  nction16()].** d
275c0 65 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20  efine callbacks 
275d0 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74  that implement t
275e0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  he SQL functions
275f0 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e   and aggregates.
27600 0a 2a 2a 20 54 68 65 20 34 74 68 20 70 61 72 61  .** The 4th para
27610 6d 65 74 65 72 20 74 6f 20 74 68 65 73 65 20 63  meter to these c
27620 61 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e 20 61  allbacks is an a
27630 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73  rray of pointers
27640 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65   to.** [protecte
27650 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
27660 20 6f 62 6a 65 63 74 73 2e 20 20 54 68 65 72 65   objects.  There
27670 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33   is one [sqlite3
27680 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66  _value] object f
27690 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61 72 61 6d  or.** each param
276a0 65 74 65 72 20 74 6f 20 74 68 65 20 53 51 4c 20  eter to the SQL 
276b0 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73 65  function.  These
276c0 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73   routines are us
276d0 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74  ed to.** extract
276e0 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 74 68 65   values from the
276f0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
27700 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20   objects..**.** 
27710 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77  These routines w
27720 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70  ork only with [p
27730 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
27740 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e  _value] objects.
27750 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20  .** Any attempt 
27760 74 6f 20 75 73 65 20 74 68 65 73 65 20 72 6f 75  to use these rou
27770 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70  tines on an [unp
27780 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
27790 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63  _value].** objec
277a0 74 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64  t results in und
277b0 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e  efined behavior.
277c0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
277d0 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74 20  tines work just 
277e0 6c 69 6b 65 20 74 68 65 20 63 6f 72 72 65 73 70  like the corresp
277f0 6f 6e 64 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69  onding .** [sqli
27800 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 20  te3_column_blob 
27810 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  | sqlite3_column
27820 5f 2a 20 72 6f 75 74 69 6e 65 73 5d 20 65 78 63  _* routines] exc
27830 65 70 74 20 74 68 61 74 20 0a 2a 2a 20 74 68 65  ept that .** the
27840 73 65 20 72 6f 75 74 69 6e 65 73 20 74 61 6b 65  se routines take
27850 20 61 20 73 69 6e 67 6c 65 20 5b 70 72 6f 74 65   a single [prote
27860 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
27870 75 65 5d 20 6f 62 6a 65 63 74 20 70 6f 69 6e 74  ue] object point
27880 65 72 0a 2a 2a 20 69 6e 73 74 65 61 64 20 6f 66  er.** instead of
27890 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d   an [sqlite3_stm
278a0 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64 20  t*] pointer and 
278b0 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d  an integer colum
278c0 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20  n number..**.** 
278d0 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
278e0 65 5f 74 65 78 74 31 36 28 29 20 69 6e 74 65 72  e_text16() inter
278f0 66 61 63 65 20 65 78 74 72 61 63 74 73 20 61 20  face extracts a 
27900 55 54 46 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20  UTF16 string.** 
27910 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79  in the native by
27920 74 65 2d 6f 72 64 65 72 20 6f 66 20 74 68 65 20  te-order of the 
27930 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20 20 54  host machine.  T
27940 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  he.** sqlite3_va
27950 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29 20 61  lue_text16be() a
27960 6e 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nd sqlite3_value
27970 5f 74 65 78 74 31 36 6c 65 28 29 20 69 6e 74 65  _text16le() inte
27980 72 66 61 63 65 73 0a 2a 2a 20 65 78 74 72 61 63  rfaces.** extrac
27990 74 20 55 54 46 31 36 20 73 74 72 69 6e 67 73 20  t UTF16 strings 
279a0 61 73 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e  as big-endian an
279b0 64 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20  d little-endian 
279c0 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a  respectively..**
279d0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
279e0 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79  value_numeric_ty
279f0 70 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 61  pe() interface a
27a00 74 74 65 6d 70 74 73 20 74 6f 20 61 70 70 6c 79  ttempts to apply
27a10 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 69  .** numeric affi
27a20 6e 69 74 79 20 74 6f 20 74 68 65 20 76 61 6c 75  nity to the valu
27a30 65 2e 20 20 54 68 69 73 20 6d 65 61 6e 73 20 74  e.  This means t
27a40 68 61 74 20 61 6e 20 61 74 74 65 6d 70 74 20 69  hat an attempt i
27a50 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e  s.** made to con
27a60 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 74  vert the value t
27a70 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 20  o an integer or 
27a80 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20  floating point. 
27a90 20 49 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f   If.** such a co
27aa0 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 73  nversion is poss
27ab0 69 62 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f 73  ible without los
27ac0 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  s of information
27ad0 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f   (in other.** wo
27ae0 72 64 73 20 69 66 20 74 68 65 20 76 61 6c 75 65  rds if the value
27af0 20 69 73 20 61 20 73 74 72 69 6e 67 20 74 68 61   is a string tha
27b00 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e  t looks like a n
27b10 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74  umber).** then t
27b20 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73  he conversion is
27b30 20 64 6f 6e 65 2e 20 20 4f 74 68 65 72 77 69 73   done.  Otherwis
27b40 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20  e no conversion 
27b50 6f 63 63 75 72 73 2e 20 20 54 68 65 20 0a 2a 2a  occurs.  The .**
27b60 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52   [SQLITE_INTEGER
27b70 20 7c 20 64 61 74 61 74 79 70 65 5d 20 61 66 74   | datatype] aft
27b80 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73  er conversion is
27b90 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
27ba0 20 50 6c 65 61 73 65 20 70 61 79 20 70 61 72 74   Please pay part
27bb0 69 63 75 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e  icular attention
27bc0 20 74 6f 20 74 68 65 20 66 61 63 74 20 74 68 61   to the fact tha
27bd0 74 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 68  t the pointer th
27be0 61 74 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65  at.** is returne
27bf0 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
27c00 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b  value_blob()], [
27c10 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
27c20 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71  xt()], or.** [sq
27c30 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
27c40 31 36 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76  16()] can be inv
27c50 61 6c 69 64 61 74 65 64 20 62 79 20 61 20 73 75  alidated by a su
27c60 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f  bsequent call to
27c70 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  .** [sqlite3_val
27c80 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71  ue_bytes()], [sq
27c90 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
27ca0 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  s16()], [sqlite3
27cb0 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a  _value_text()],.
27cc0 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76  ** or [sqlite3_v
27cd0 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 20  alue_text16()]. 
27ce0 20 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f   .**.** These ro
27cf0 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63  utines must be c
27d00 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73  alled from the s
27d10 61 6d 65 20 74 68 72 65 61 64 20 61 73 0a 2a 2a  ame thread as.**
27d20 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
27d30 6e 20 74 68 61 74 20 73 75 70 70 6c 69 65 64 20  n that supplied 
27d40 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  the [sqlite3_val
27d50 75 65 2a 5d 20 70 61 72 61 6d 65 74 65 72 73 2e  ue*] parameters.
27d60 0a 2a 2a 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  .**.**.** INVARI
27d70 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 35  ANTS:.**.** {F15
27d80 31 30 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  103} The [sqlite
27d90 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 56 29 5d  3_value_blob(V)]
27da0 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65   interface conve
27db0 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  rts the.**      
27dc0 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73      [protected s
27dd0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
27de0 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20 62 6c  ject V into a bl
27df0 6f 62 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75  ob and then retu
27e00 72 6e 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20  rns a.**        
27e10 20 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65    pointer to the
27e20 20 63 6f 6e 76 65 72 74 65 64 20 76 61 6c 75 65   converted value
27e30 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31 30 36 7d  ..**.** {F15106}
27e40 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   The [sqlite3_va
27e50 6c 75 65 5f 62 79 74 65 73 28 56 29 5d 20 69 6e  lue_bytes(V)] in
27e60 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
27e70 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
27e80 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
27e90 69 6e 20 74 68 65 20 62 6c 6f 62 20 6f 72 20 73  in the blob or s
27ea0 74 72 69 6e 67 20 28 65 78 63 6c 75 73 69 76 65  tring (exclusive
27eb0 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   of the.**      
27ec0 20 20 20 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61      zero termina
27ed0 74 6f 72 20 6f 6e 20 74 68 65 20 73 74 72 69 6e  tor on the strin
27ee0 67 29 20 74 68 61 74 20 77 61 73 20 72 65 74 75  g) that was retu
27ef0 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 20  rned by the.**  
27f00 20 20 20 20 20 20 20 20 6d 6f 73 74 20 72 65 63          most rec
27f10 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ent call to [sql
27f20 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28  ite3_value_blob(
27f30 56 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20  V)] or.**       
27f40 20 20 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75     [sqlite3_valu
27f50 65 5f 74 65 78 74 28 56 29 5d 2e 0a 2a 2a 0a 2a  e_text(V)]..**.*
27f60 2a 20 7b 46 31 35 31 30 39 7d 20 54 68 65 20 5b  * {F15109} The [
27f70 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
27f80 74 65 73 31 36 28 56 29 5d 20 69 6e 74 65 72 66  tes16(V)] interf
27f90 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a  ace returns the.
27fa0 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 75 6d 62  **          numb
27fb0 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
27fc0 68 65 20 73 74 72 69 6e 67 20 28 65 78 63 6c 75  he string (exclu
27fd0 73 69 76 65 20 6f 66 20 74 68 65 0a 2a 2a 20 20  sive of the.**  
27fe0 20 20 20 20 20 20 20 20 7a 65 72 6f 20 74 65 72          zero ter
27ff0 6d 69 6e 61 74 6f 72 20 6f 6e 20 74 68 65 20 73  minator on the s
28000 74 72 69 6e 67 29 20 74 68 61 74 20 77 61 73 20  tring) that was 
28010 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a  returned by the.
28020 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 6f 73 74  **          most
28030 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20   recent call to 
28040 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
28050 65 78 74 31 36 28 56 29 5d 2c 0a 2a 2a 20 20 20  ext16(V)],.**   
28060 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
28070 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 56  value_text16be(V
28080 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  )], or [sqlite3_
28090 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 56  value_text16le(V
280a0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31 31  )]..**.** {F1511
280b0 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  2} The [sqlite3_
280c0 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 56 29 5d  value_double(V)]
280d0 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65   interface conve
280e0 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  rts the.**      
280f0 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73      [protected s
28100 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
28110 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20 66 6c  ject V into a fl
28120 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
28130 75 65 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20  ue and.**       
28140 20 20 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70     returns a cop
28150 79 20 6f 66 20 74 68 61 74 20 76 61 6c 75 65 2e  y of that value.
28160 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31 31 35 7d 20  .**.** {F15115} 
28170 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  The [sqlite3_val
28180 75 65 5f 69 6e 74 28 56 29 5d 20 69 6e 74 65 72  ue_int(V)] inter
28190 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68  face converts th
281a0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  e.**          [p
281b0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
281c0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56  _value] object V
281d0 20 69 6e 74 6f 20 61 20 36 34 2d 62 69 74 20 73   into a 64-bit s
281e0 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e  igned integer an
281f0 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  d.**          re
28200 74 75 72 6e 73 20 74 68 65 20 6c 6f 77 65 72 20  turns the lower 
28210 33 32 20 62 69 74 73 20 6f 66 20 74 68 61 74 20  32 bits of that 
28220 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b  integer..**.** {
28230 46 31 35 31 31 38 7d 20 54 68 65 20 5b 73 71 6c  F15118} The [sql
28240 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34  ite3_value_int64
28250 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  (V)] interface c
28260 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20  onverts the.**  
28270 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74          [protect
28280 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
28290 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20  ] object V into 
282a0 61 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  a 64-bit signed 
282b0 69 6e 74 65 67 65 72 20 61 6e 64 0a 2a 2a 20 20  integer and.**  
282c0 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 73 20          returns 
282d0 61 20 63 6f 70 79 20 6f 66 20 74 68 61 74 20 69  a copy of that i
282e0 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46  nteger..**.** {F
282f0 31 35 31 32 31 7d 20 54 68 65 20 5b 73 71 6c 69  15121} The [sqli
28300 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 56  te3_value_text(V
28310 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e  )] interface con
28320 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20  verts the.**    
28330 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64        [protected
28340 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
28350 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20  object V into a 
28360 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
28370 55 54 46 2d 38 20 0a 2a 2a 20 20 20 20 20 20 20  UTF-8 .**       
28380 20 20 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65     string and re
28390 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
283a0 74 6f 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a  to that string..
283b0 2a 2a 0a 2a 2a 20 7b 46 31 35 31 32 34 7d 20 54  **.** {F15124} T
283c0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
283d0 65 5f 74 65 78 74 31 36 28 56 29 5d 20 69 6e 74  e_text16(V)] int
283e0 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20  erface converts 
283f0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
28400 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
28410 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
28420 20 56 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74   V into a zero-t
28430 65 72 6d 69 6e 61 74 65 64 20 32 2d 62 79 74 65  erminated 2-byte
28440 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c 69  .**          ali
28450 67 6e 65 64 20 55 54 46 2d 31 36 20 6e 61 74 69  gned UTF-16 nati
28460 76 65 20 62 79 74 65 20 6f 72 64 65 72 0a 2a 2a  ve byte order.**
28470 20 20 20 20 20 20 20 20 20 20 73 74 72 69 6e 67            string
28480 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70   and returns a p
28490 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20 73  ointer to that s
284a0 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  tring..**.** {F1
284b0 35 31 32 37 7d 20 54 68 65 20 5b 73 71 6c 69 74  5127} The [sqlit
284c0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62  e3_value_text16b
284d0 65 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20  e(V)] interface 
284e0 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20  converts the.** 
284f0 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63           [protec
28500 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
28510 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f  e] object V into
28520 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
28530 65 64 20 32 2d 62 79 74 65 0a 2a 2a 20 20 20 20  ed 2-byte.**    
28540 20 20 20 20 20 20 61 6c 69 67 6e 65 64 20 55 54        aligned UT
28550 46 2d 31 36 20 62 69 67 2d 65 6e 64 69 61 6e 0a  F-16 big-endian.
28560 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 72 69  **          stri
28570 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61  ng and returns a
28580 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74   pointer to that
28590 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b   string..**.** {
285a0 46 31 35 31 33 30 7d 20 54 68 65 20 5b 73 71 6c  F15130} The [sql
285b0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
285c0 36 6c 65 28 56 29 5d 20 69 6e 74 65 72 66 61 63  6le(V)] interfac
285d0 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a  e converts the.*
285e0 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74  *          [prot
285f0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
28600 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e  lue] object V in
28610 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  to a zero-termin
28620 61 74 65 64 20 32 2d 62 79 74 65 0a 2a 2a 20 20  ated 2-byte.**  
28630 20 20 20 20 20 20 20 20 61 6c 69 67 6e 65 64 20          aligned 
28640 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 2d 65 6e  UTF-16 little-en
28650 64 69 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  dian.**         
28660 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75   string and retu
28670 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
28680 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a   that string..**
28690 0a 2a 2a 20 7b 46 31 35 31 33 33 7d 20 54 68 65  .** {F15133} The
286a0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
286b0 74 79 70 65 28 56 29 5d 20 69 6e 74 65 72 66 61  type(V)] interfa
286c0 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20  ce returns.**   
286d0 20 20 20 20 20 20 20 6f 6e 65 20 6f 66 20 5b 53         one of [S
286e0 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2c 20 5b 53 51  QLITE_NULL], [SQ
286f0 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 20 5b  LITE_INTEGER], [
28700 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 0a 2a  SQLITE_FLOAT],.*
28710 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49  *          [SQLI
28720 54 45 5f 54 45 58 54 5d 2c 20 6f 72 20 5b 53 51  TE_TEXT], or [SQ
28730 4c 49 54 45 5f 42 4c 4f 42 5d 20 61 73 20 61 70  LITE_BLOB] as ap
28740 70 72 6f 70 72 69 61 74 65 20 66 6f 72 0a 2a 2a  propriate for.**
28750 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 73            the [s
28760 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
28770 6a 65 63 74 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 46  ject V..**.** {F
28780 31 35 31 33 36 7d 20 54 68 65 20 5b 73 71 6c 69  15136} The [sqli
28790 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69  te3_value_numeri
287a0 63 5f 74 79 70 65 28 56 29 5d 20 69 6e 74 65 72  c_type(V)] inter
287b0 66 61 63 65 20 63 6f 6e 76 65 72 74 73 0a 2a 2a  face converts.**
287c0 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 70            the [p
287d0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
287e0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56  _value] object V
287f0 20 69 6e 74 6f 20 65 69 74 68 65 72 20 61 6e 20   into either an 
28800 69 6e 74 65 67 65 72 20 6f 72 0a 2a 2a 20 20 20  integer or.**   
28810 20 20 20 20 20 20 20 61 20 66 6c 6f 61 74 69 6e         a floatin
28820 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 69 66  g point value if
28830 20 69 74 20 63 61 6e 20 64 6f 20 73 6f 20 77 69   it can do so wi
28840 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 0a 2a 2a  thout loss of.**
28850 20 20 20 20 20 20 20 20 20 20 69 6e 66 6f 72 6d            inform
28860 61 74 69 6f 6e 2c 20 61 6e 64 20 72 65 74 75 72  ation, and retur
28870 6e 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  ns one of [SQLIT
28880 45 5f 4e 55 4c 4c 5d 2c 0a 2a 2a 20 20 20 20 20  E_NULL],.**     
28890 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 49 4e 54       [SQLITE_INT
288a0 45 47 45 52 5d 2c 20 5b 53 51 4c 49 54 45 5f 46  EGER], [SQLITE_F
288b0 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54  LOAT], [SQLITE_T
288c0 45 58 54 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20  EXT], or.**     
288d0 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 42 4c 4f       [SQLITE_BLO
288e0 42 5d 20 61 73 20 61 70 70 72 6f 70 72 69 61 74  B] as appropriat
288f0 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  e for.**        
28900 20 20 74 68 65 20 5b 70 72 6f 74 65 63 74 65 64    the [protected
28910 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
28920 6f 62 6a 65 63 74 20 56 20 61 66 74 65 72 20 74  object V after t
28930 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 74  he conversion at
28940 74 65 6d 70 74 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  tempt..*/.const 
28950 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61  void *sqlite3_va
28960 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  lue_blob(sqlite3
28970 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
28980 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
28990 73 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  s(sqlite3_value*
289a0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  );.int sqlite3_v
289b0 61 6c 75 65 5f 62 79 74 65 73 31 36 28 73 71 6c  alue_bytes16(sql
289c0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f  ite3_value*);.do
289d0 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  uble sqlite3_val
289e0 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65  ue_double(sqlite
289f0 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
28a00 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74  qlite3_value_int
28a10 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
28a20 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  ;.sqlite3_int64 
28a30 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e  sqlite3_value_in
28a40 74 36 34 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  t64(sqlite3_valu
28a50 65 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67  e*);.const unsig
28a60 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65  ned char *sqlite
28a70 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 73 71 6c  3_value_text(sql
28a80 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f  ite3_value*);.co
28a90 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
28aa0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 73  3_value_text16(s
28ab0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
28ac0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
28ad0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
28ae0 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  le(sqlite3_value
28af0 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  *);.const void *
28b00 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
28b10 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 76  xt16be(sqlite3_v
28b20 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
28b30 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 73  te3_value_type(s
28b40 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
28b50 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
28b60 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 73  e_numeric_type(s
28b70 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
28b80 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
28b90 20 4f 62 74 61 69 6e 20 41 67 67 72 65 67 61 74   Obtain Aggregat
28ba0 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65  e Function Conte
28bb0 78 74 20 7b 46 31 36 32 31 30 7d 0a 2a 2a 0a 2a  xt {F16210}.**.*
28bc0 2a 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  * The implementa
28bd0 74 69 6f 6e 20 6f 66 20 61 67 67 72 65 67 61 74  tion of aggregat
28be0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  e SQL functions 
28bf0 75 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  use this routine
28c00 20 74 6f 20 61 6c 6c 6f 63 61 74 65 0a 2a 2a 20   to allocate.** 
28c10 61 20 73 74 72 75 63 74 75 72 65 20 66 6f 72 20  a structure for 
28c20 73 74 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74  storing their st
28c30 61 74 65 2e 20 20 0a 2a 2a 20 54 68 65 20 66 69  ate.  .** The fi
28c40 72 73 74 20 74 69 6d 65 20 74 68 65 20 73 71 6c  rst time the sql
28c50 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
28c60 6f 6e 74 65 78 74 28 29 20 72 6f 75 74 69 6e 65  ontext() routine
28c70 20 69 73 0a 2a 2a 20 69 73 20 63 61 6c 6c 65 64   is.** is called
28c80 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61   for a particula
28c90 72 20 61 67 67 72 65 67 61 74 65 2c 20 53 51 4c  r aggregate, SQL
28ca0 69 74 65 20 61 6c 6c 6f 63 61 74 65 73 20 6e 42  ite allocates nB
28cb0 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a  ytes of memory.*
28cc0 2a 20 7a 65 72 6f 73 20 74 68 61 74 20 6d 65 6d  * zeros that mem
28cd0 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72 6e 73  ory, and returns
28ce0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74   a pointer to it
28cf0 2e 0a 2a 2a 20 4f 6e 20 73 65 63 6f 6e 64 20 61  ..** On second a
28d00 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  nd subsequent ca
28d10 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 61  lls to sqlite3_a
28d20 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
28d30 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61  ().** for the sa
28d40 6d 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e  me aggregate fun
28d50 63 74 69 6f 6e 20 69 6e 64 65 78 2c 20 74 68 65  ction index, the
28d60 20 73 61 6d 65 20 62 75 66 66 65 72 20 69 73 20   same buffer is 
28d70 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 54 68 65  returned..** The
28d80 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a   implementation.
28d90 2a 2a 20 6f 66 20 74 68 65 20 61 67 67 72 65 67  ** of the aggreg
28da0 61 74 65 20 63 61 6e 20 75 73 65 20 74 68 65 20  ate can use the 
28db0 72 65 74 75 72 6e 65 64 20 62 75 66 66 65 72 20  returned buffer 
28dc0 74 6f 20 61 63 63 75 6d 75 6c 61 74 65 20 64 61  to accumulate da
28dd0 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  ta..**.** SQLite
28de0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66   automatically f
28df0 72 65 65 73 20 74 68 65 20 61 6c 6c 6f 63 61 74  rees the allocat
28e00 65 64 20 62 75 66 66 65 72 20 77 68 65 6e 20 74  ed buffer when t
28e10 68 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20  he aggregate.** 
28e20 71 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e  query concludes.
28e30 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
28e40 20 70 61 72 61 6d 65 74 65 72 20 73 68 6f 75 6c   parameter shoul
28e50 64 20 62 65 20 61 20 63 6f 70 79 20 6f 66 20 74  d be a copy of t
28e60 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  he .** [sqlite3_
28e70 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20 66 75  context | SQL fu
28e80 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20  nction context] 
28e90 74 68 61 74 20 69 73 20 74 68 65 20 66 69 72 73  that is the firs
28ea0 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74  t.** parameter t
28eb0 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  o the callback r
28ec0 6f 75 74 69 6e 65 20 74 68 61 74 20 69 6d 70 6c  outine that impl
28ed0 65 6d 65 6e 74 73 20 74 68 65 20 61 67 67 72 65  ements the aggre
28ee0 67 61 74 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  gate.** function
28ef0 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  ..**.** This rou
28f00 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c  tine must be cal
28f10 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  led from the sam
28f20 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63  e thread in whic
28f30 68 0a 2a 2a 20 74 68 65 20 61 67 67 72 65 67 61  h.** the aggrega
28f40 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  te SQL function 
28f50 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a  is running..**.*
28f60 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
28f70 0a 2a 2a 20 7b 46 31 36 32 31 31 7d 20 54 68 65  .** {F16211} The
28f80 20 66 69 72 73 74 20 69 6e 76 6f 63 61 74 69 6f   first invocatio
28f90 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 61 67  n of [sqlite3_ag
28fa0 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
28fb0 43 2c 4e 29 5d 20 66 6f 72 0a 2a 2a 20 20 20 20  C,N)] for.**    
28fc0 20 20 20 20 20 20 61 20 70 61 72 74 69 63 75 6c        a particul
28fd0 61 72 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 61  ar instance of a
28fe0 6e 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  n aggregate func
28ff0 74 69 6f 6e 20 28 66 6f 72 20 61 20 70 61 72 74  tion (for a part
29000 69 63 75 6c 61 72 0a 2a 2a 20 20 20 20 20 20 20  icular.**       
29010 20 20 20 63 6f 6e 74 65 78 74 20 43 29 20 63 61     context C) ca
29020 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 61  uses SQLite to a
29030 6c 6c 6f 63 61 74 69 6f 6e 20 4e 20 62 79 74 65  llocation N byte
29040 73 20 6f 66 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20  s of memory,.** 
29050 20 20 20 20 20 20 20 20 20 7a 65 72 6f 20 74 68           zero th
29060 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72  at memory, and r
29070 65 74 75 72 6e 20 61 20 70 6f 69 6e 74 65 72 20  eturn a pointer 
29080 74 6f 20 74 68 65 20 61 6c 6c 6f 63 61 74 69 6f  to the allocatio
29090 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ned.**          
290a0 6d 65 6d 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46  memory..**.** {F
290b0 31 36 32 31 33 7d 20 49 66 20 61 20 6d 65 6d 6f  16213} If a memo
290c0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72  ry allocation er
290d0 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e  ror occurs durin
290e0 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  g.**          [s
290f0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
29100 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 5d 20 74  _context(C,N)] t
29110 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  hen the function
29120 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 0a 2a   returns 0..**.*
29130 2a 20 7b 46 31 36 32 31 35 7d 20 53 65 63 6f 6e  * {F16215} Secon
29140 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74  d and subsequent
29150 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 0a   invocations of.
29160 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
29170 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
29180 6f 6e 74 65 78 74 28 43 2c 4e 29 5d 20 66 6f 72  ontext(C,N)] for
29190 20 74 68 65 20 73 61 6d 65 20 63 6f 6e 74 65 78   the same contex
291a0 74 20 70 6f 69 6e 74 65 72 20 43 0a 2a 2a 20 20  t pointer C.**  
291b0 20 20 20 20 20 20 20 20 69 67 6e 6f 72 65 20 74          ignore t
291c0 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 61  he N parameter a
291d0 6e 64 20 72 65 74 75 72 6e 20 61 20 70 6f 69 6e  nd return a poin
291e0 74 65 72 20 74 6f 20 74 68 65 20 73 61 6d 65 0a  ter to the same.
291f0 2a 2a 20 20 20 20 20 20 20 20 20 20 62 6c 6f 63  **          bloc
29200 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 72 65 74 75  k of memory retu
29210 72 6e 65 64 20 62 79 20 74 68 65 20 66 69 72 73  rned by the firs
29220 74 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a  t invocation..**
29230 0a 2a 2a 20 7b 46 31 36 32 31 37 7d 20 54 68 65  .** {F16217} The
29240 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65   memory allocate
29250 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 61 67  d by [sqlite3_ag
29260 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
29270 43 2c 4e 29 5d 20 69 73 0a 2a 2a 20 20 20 20 20  C,N)] is.**     
29280 20 20 20 20 20 61 75 74 6f 6d 61 74 69 63 61 6c       automatical
29290 6c 79 20 66 72 65 65 64 20 6f 6e 20 74 68 65 20  ly freed on the 
292a0 6e 65 78 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  next call to [sq
292b0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a  lite3_reset()].*
292c0 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 5b 73  *          or [s
292d0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
292e0 29 5d 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70  )] for the [prep
292f0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
29300 63 6f 6e 74 61 69 6e 69 6e 67 0a 2a 2a 20 20 20  containing.**   
29310 20 20 20 20 20 20 20 74 68 65 20 61 67 67 72 65         the aggre
29320 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 61 73  gate function as
29330 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 63 6f  sociated with co
29340 6e 74 65 78 74 20 43 2e 0a 2a 2f 0a 76 6f 69 64  ntext C..*/.void
29350 20 2a 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67   *sqlite3_aggreg
29360 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69  ate_context(sqli
29370 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
29380 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a  t nBytes);../*.*
29390 2a 20 43 41 50 49 33 52 45 46 3a 20 55 73 65 72  * CAPI3REF: User
293a0 20 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74 69   Data For Functi
293b0 6f 6e 73 20 7b 46 31 36 32 34 30 7d 0a 2a 2a 0a  ons {F16240}.**.
293c0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75  ** The sqlite3_u
293d0 73 65 72 5f 64 61 74 61 28 29 20 69 6e 74 65 72  ser_data() inter
293e0 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63  face returns a c
293f0 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f  opy of.** the po
29400 69 6e 74 65 72 20 74 68 61 74 20 77 61 73 20 74  inter that was t
29410 68 65 20 70 55 73 65 72 44 61 74 61 20 70 61 72  he pUserData par
29420 61 6d 65 74 65 72 20 28 74 68 65 20 35 74 68 20  ameter (the 5th 
29430 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66  parameter).** of
29440 20 74 68 65 20 74 68 65 20 5b 73 71 6c 69 74 65   the the [sqlite
29450 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
29460 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  n()].** and [sql
29470 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
29480 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e  tion16()] routin
29490 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c  es that original
294a0 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64  ly.** registered
294b0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
294c0 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f   defined functio
294d0 6e 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54  n. {END}.**.** T
294e0 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74  his routine must
294f0 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
29500 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
29510 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20  in which.** the 
29520 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
29530 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ned function is 
29540 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49  running..**.** I
29550 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
29560 20 7b 46 31 36 32 34 33 7d 20 54 68 65 20 5b 73   {F16243} The [s
29570 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61  qlite3_user_data
29580 28 43 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  (C)] interface r
29590 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66  eturns a copy of
295a0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
295b0 20 50 20 70 6f 69 6e 74 65 72 20 66 72 6f 6d 20   P pointer from 
295c0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  the [sqlite3_cre
295d0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58  ate_function(D,X
295e0 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 0a 2a  ,N,E,P,F,S,L)].*
295f0 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 5b 73  *          or [s
29600 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
29610 6e 63 74 69 6f 6e 31 36 28 44 2c 58 2c 4e 2c 45  nction16(D,X,N,E
29620 2c 50 2c 46 2c 53 2c 4c 29 5d 20 63 61 6c 6c 20  ,P,F,S,L)] call 
29630 74 68 61 74 0a 2a 2a 20 20 20 20 20 20 20 20 20  that.**         
29640 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20   registered the 
29650 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 61 73 73  SQL function ass
29660 6f 63 69 61 74 65 64 20 77 69 74 68 20 0a 2a 2a  ociated with .**
29670 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
29680 65 33 5f 63 6f 6e 74 65 78 74 5d 20 43 2e 0a 2a  e3_context] C..*
29690 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
296a0 75 73 65 72 5f 64 61 74 61 28 73 71 6c 69 74 65  user_data(sqlite
296b0 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a  3_context*);../*
296c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61  .** CAPI3REF: Da
296d0 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
296e0 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 20  n For Functions 
296f0 7b 46 31 36 32 35 30 7d 0a 2a 2a 0a 2a 2a 20 54  {F16250}.**.** T
29700 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  he sqlite3_conte
29710 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20 69  xt_db_handle() i
29720 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
29730 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68   a copy of.** th
29740 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  e pointer to the
29750 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
29760 63 74 69 6f 6e 5d 20 28 74 68 65 20 31 73 74 20  ction] (the 1st 
29770 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66  parameter).** of
29780 20 74 68 65 20 74 68 65 20 5b 73 71 6c 69 74 65   the the [sqlite
29790 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
297a0 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  n()].** and [sql
297b0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
297c0 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e  tion16()] routin
297d0 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c  es that original
297e0 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64  ly.** registered
297f0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
29800 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f   defined functio
29810 6e 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  n..**.** INVARIA
29820 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32  NTS:.**.** {F162
29830 35 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  53} The [sqlite3
29840 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64  _context_db_hand
29850 6c 65 28 43 29 5d 20 69 6e 74 65 72 66 61 63 65  le(C)] interface
29860 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20   returns a copy 
29870 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  of the.**       
29880 20 20 20 44 20 70 6f 69 6e 74 65 72 20 66 72 6f     D pointer fro
29890 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  m the [sqlite3_c
298a0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44  reate_function(D
298b0 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d  ,X,N,E,P,F,S,L)]
298c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
298d0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
298e0 66 75 6e 63 74 69 6f 6e 31 36 28 44 2c 58 2c 4e  function16(D,X,N
298f0 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 20 63 61 6c  ,E,P,F,S,L)] cal
29900 6c 20 74 68 61 74 0a 2a 2a 20 20 20 20 20 20 20  l that.**       
29910 20 20 20 72 65 67 69 73 74 65 72 65 64 20 74 68     registered th
29920 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 61  e SQL function a
29930 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 0a  ssociated with .
29940 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
29950 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 43 2e  ite3_context] C.
29960 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c  .*/.sqlite3 *sql
29970 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f  ite3_context_db_
29980 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 63  handle(sqlite3_c
29990 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  ontext*);../*.**
299a0 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74   CAPI3REF: Funct
299b0 69 6f 6e 20 41 75 78 69 6c 69 61 72 79 20 44 61  ion Auxiliary Da
299c0 74 61 20 7b 46 31 36 32 37 30 7d 0a 2a 2a 0a 2a  ta {F16270}.**.*
299d0 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  * The following 
299e0 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61  two functions ma
299f0 79 20 62 65 20 75 73 65 64 20 62 79 20 73 63 61  y be used by sca
29a00 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  lar SQL function
29a10 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74  s to.** associat
29a20 65 20 6d 65 74 61 2d 64 61 74 61 20 77 69 74 68  e meta-data with
29a30 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 73   argument values
29a40 2e 20 49 66 20 74 68 65 20 73 61 6d 65 20 76 61  . If the same va
29a50 6c 75 65 20 69 73 20 70 61 73 73 65 64 20 74 6f  lue is passed to
29a60 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76  .** multiple inv
29a70 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ocations of the 
29a80 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  same SQL functio
29a90 6e 20 64 75 72 69 6e 67 20 71 75 65 72 79 20 65  n during query e
29aa0 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a  xecution, under.
29ab0 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 74  ** some circumst
29ac0 61 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63 69  ances the associ
29ad0 61 74 65 64 20 6d 65 74 61 2d 64 61 74 61 20 6d  ated meta-data m
29ae0 61 79 20 62 65 20 70 72 65 73 65 72 76 65 64 2e  ay be preserved.
29af0 20 54 68 69 73 20 6d 61 79 0a 2a 2a 20 62 65 20   This may.** be 
29b00 75 73 65 64 2c 20 66 6f 72 20 65 78 61 6d 70 6c  used, for exampl
29b10 65 2c 20 74 6f 20 61 64 64 20 61 20 72 65 67 75  e, to add a regu
29b20 6c 61 72 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d  lar-expression m
29b30 61 74 63 68 69 6e 67 20 73 63 61 6c 61 72 0a 2a  atching scalar.*
29b40 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20  * function. The 
29b50 63 6f 6d 70 69 6c 65 64 20 76 65 72 73 69 6f 6e  compiled version
29b60 20 6f 66 20 74 68 65 20 72 65 67 75 6c 61 72 20   of the regular 
29b70 65 78 70 72 65 73 73 69 6f 6e 20 69 73 20 73 74  expression is st
29b80 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61 2d  ored as.** meta-
29b90 64 61 74 61 20 61 73 73 6f 63 69 61 74 65 64 20  data associated 
29ba0 77 69 74 68 20 74 68 65 20 53 51 4c 20 76 61 6c  with the SQL val
29bb0 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  ue passed as the
29bc0 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73   regular express
29bd0 69 6f 6e 0a 2a 2a 20 70 61 74 74 65 72 6e 2e 20  ion.** pattern. 
29be0 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 72 65   The compiled re
29bf0 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e  gular expression
29c00 20 63 61 6e 20 62 65 20 72 65 75 73 65 64 20 6f   can be reused o
29c10 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e  n multiple.** in
29c20 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  vocations of the
29c30 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 73   same function s
29c40 6f 20 74 68 61 74 20 74 68 65 20 6f 72 69 67 69  o that the origi
29c50 6e 61 6c 20 70 61 74 74 65 72 6e 20 73 74 72 69  nal pattern stri
29c60 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 6e  ng.** does not n
29c70 65 65 64 20 74 6f 20 62 65 20 72 65 63 6f 6d 70  eed to be recomp
29c80 69 6c 65 64 20 6f 6e 20 65 61 63 68 20 69 6e 76  iled on each inv
29c90 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  ocation..**.** T
29ca0 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  he sqlite3_get_a
29cb0 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61  uxdata() interfa
29cc0 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
29cd0 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 74 61  nter to the meta
29ce0 2d 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61  -data.** associa
29cf0 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74  ted by the sqlit
29d00 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
29d10 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 74   function with t
29d20 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a  he Nth argument.
29d30 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74 68 65 20  ** value to the 
29d40 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
29d50 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  ned function..**
29d60 20 49 66 20 6e 6f 20 6d 65 74 61 2d 64 61 74 61   If no meta-data
29d70 20 68 61 73 20 62 65 65 6e 20 65 76 65 72 20 62   has been ever b
29d80 65 65 6e 20 73 65 74 20 66 6f 72 20 74 68 65 20  een set for the 
29d90 4e 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  Nth.** argument 
29da0 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 2c  of the function,
29db0 20 6f 72 20 69 66 20 74 68 65 20 63 6f 6f 72 65   or if the coore
29dc0 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f  sponding functio
29dd0 6e 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 68  n parameter.** h
29de0 61 73 20 63 68 61 6e 67 65 64 20 73 69 6e 63 65  as changed since
29df0 20 74 68 65 20 6d 65 74 61 2d 64 61 74 61 20 77   the meta-data w
29e00 61 73 20 73 65 74 2c 20 74 68 65 6e 20 73 71 6c  as set, then sql
29e10 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
29e20 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20  ().** returns a 
29e30 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
29e40 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
29e50 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e  set_auxdata() in
29e60 74 65 72 66 61 63 65 20 73 61 76 65 73 20 74 68  terface saves th
29e70 65 20 6d 65 74 61 2d 64 61 74 61 0a 2a 2a 20 70  e meta-data.** p
29e80 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 69 74 73  ointed to by its
29e90 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 61   3rd parameter a
29ea0 73 20 74 68 65 20 6d 65 74 61 2d 64 61 74 61 20  s the meta-data 
29eb0 66 6f 72 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20  for the N-th.** 
29ec0 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20  argument of the 
29ed0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
29ee0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 20 53  ned function.  S
29ef0 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c  ubsequent.** cal
29f00 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 67 65  ls to sqlite3_ge
29f10 74 5f 61 75 78 64 61 74 61 28 29 20 6d 69 67 68  t_auxdata() migh
29f20 74 20 72 65 74 75 72 6e 20 74 68 69 73 20 64 61  t return this da
29f30 74 61 2c 20 69 66 20 69 74 20 68 61 73 0a 2a 2a  ta, if it has.**
29f40 20 6e 6f 74 20 62 65 65 6e 20 64 65 73 74 72 6f   not been destro
29f50 79 65 64 2e 20 0a 2a 2a 20 49 66 20 69 74 20 69  yed. .** If it i
29f60 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69  s not NULL, SQLi
29f70 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74  te will invoke t
29f80 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 0a 2a  he destructor .*
29f90 2a 20 66 75 6e 63 74 69 6f 6e 20 67 69 76 65 6e  * function given
29fa0 20 62 79 20 74 68 65 20 34 74 68 20 70 61 72 61   by the 4th para
29fb0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
29fc0 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 6f  _set_auxdata() o
29fd0 6e 0a 2a 2a 20 74 68 65 20 6d 65 74 61 2d 64 61  n.** the meta-da
29fe0 74 61 20 77 68 65 6e 20 74 68 65 20 63 6f 72 72  ta when the corr
29ff0 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74 69  esponding functi
2a000 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 63 68 61  on parameter cha
2a010 6e 67 65 73 0a 2a 2a 20 6f 72 20 77 68 65 6e 20  nges.** or when 
2a020 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
2a030 74 20 63 6f 6d 70 6c 65 74 65 73 2c 20 77 68 69  t completes, whi
2a040 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72  chever comes fir
2a050 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  st..**.** SQLite
2a060 20 69 73 20 66 72 65 65 20 74 6f 20 63 61 6c 6c   is free to call
2a070 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
2a080 61 6e 64 20 64 72 6f 70 20 6d 65 74 61 2d 64 61  and drop meta-da
2a090 74 61 20 6f 6e 0a 2a 2a 20 61 6e 79 20 70 61 72  ta on.** any par
2a0a0 61 6d 65 74 65 72 20 6f 66 20 61 6e 79 20 66 75  ameter of any fu
2a0b0 6e 63 74 69 6f 6e 20 61 74 20 61 6e 79 20 74 69  nction at any ti
2a0c0 6d 65 2e 20 20 54 68 65 20 6f 6e 6c 79 20 67 75  me.  The only gu
2a0d0 61 72 61 6e 74 65 65 0a 2a 2a 20 69 73 20 74 68  arantee.** is th
2a0e0 61 74 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  at the destructo
2a0f0 72 20 77 69 6c 6c 20 62 65 20 63 61 6c 6c 65 64  r will be called
2a100 20 62 65 66 6f 72 65 20 74 68 65 20 6d 65 74 61   before the meta
2a110 64 61 74 61 20 69 73 0a 2a 2a 20 64 72 6f 70 70  data is.** dropp
2a120 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 70 72 61  ed..**.** In pra
2a130 63 74 69 63 65 2c 20 6d 65 74 61 2d 64 61 74 61  ctice, meta-data
2a140 20 69 73 20 70 72 65 73 65 72 76 65 64 20 62 65   is preserved be
2a150 74 77 65 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63  tween function c
2a160 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 65 78 70 72  alls for.** expr
2a170 65 73 73 69 6f 6e 73 20 74 68 61 74 20 61 72 65  essions that are
2a180 20 63 6f 6e 73 74 61 6e 74 20 61 74 20 63 6f 6d   constant at com
2a190 70 69 6c 65 20 74 69 6d 65 2e 20 54 68 69 73 20  pile time. This 
2a1a0 69 6e 63 6c 75 64 65 73 20 6c 69 74 65 72 61 6c  includes literal
2a1b0 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64 20 53  .** values and S
2a1c0 51 4c 20 76 61 72 69 61 62 6c 65 73 2e 0a 2a 2a  QL variables..**
2a1d0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
2a1e0 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  es must be calle
2a1f0 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
2a200 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a  thread in which.
2a210 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  ** the SQL funct
2a220 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ion is running..
2a230 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
2a240 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32 37 32 7d  :.**.** {F16272}
2a250 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 67 65   The [sqlite3_ge
2a260 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 29 5d 20  t_auxdata(C,N)] 
2a270 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2a280 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 20  s a pointer.**  
2a290 20 20 20 20 20 20 20 20 74 6f 20 6d 65 74 61 64          to metad
2a2a0 61 74 61 20 61 73 73 6f 63 69 61 74 65 64 20 77  ata associated w
2a2b0 69 74 68 20 74 68 65 20 4e 74 68 20 70 61 72 61  ith the Nth para
2a2c0 6d 65 74 65 72 20 6f 66 20 74 68 65 20 53 51 4c  meter of the SQL
2a2d0 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20 20   function.**    
2a2e0 20 20 20 20 20 20 77 68 6f 73 65 20 63 6f 6e 74        whose cont
2a2f0 65 78 74 20 69 73 20 43 2c 20 6f 72 20 4e 55 4c  ext is C, or NUL
2a300 4c 20 69 66 20 74 68 65 72 65 20 69 73 20 6e 6f  L if there is no
2a310 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63 69   metadata associ
2a320 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  ated.**         
2a330 20 77 69 74 68 20 74 68 61 74 20 70 61 72 61 6d   with that param
2a340 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  eter..**.** {F16
2a350 32 37 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  274} The [sqlite
2a360 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c  3_set_auxdata(C,
2a370 4e 2c 50 2c 44 29 5d 20 69 6e 74 65 72 66 61 63  N,P,D)] interfac
2a380 65 20 61 73 73 69 67 6e 73 20 61 20 6d 65 74 61  e assigns a meta
2a390 64 61 74 61 0a 2a 2a 20 20 20 20 20 20 20 20 20  data.**         
2a3a0 20 70 6f 69 6e 74 65 72 20 50 20 74 6f 20 74 68   pointer P to th
2a3b0 65 20 4e 74 68 20 70 61 72 61 6d 65 74 65 72 20  e Nth parameter 
2a3c0 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  of the SQL funct
2a3d0 69 6f 6e 20 77 69 74 68 20 63 6f 6e 74 65 78 74  ion with context
2a3e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 43 2e 0a  .**          C..
2a3f0 2a 2a 0a 2a 2a 20 7b 46 31 36 32 37 36 7d 20 53  **.** {F16276} S
2a400 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b  QLite will invok
2a410 65 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  e the destructor
2a420 20 44 20 77 69 74 68 20 61 20 73 69 6e 67 6c 65   D with a single
2a430 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 20 20 20   argument.**    
2a440 20 20 20 20 20 20 77 68 69 63 68 20 69 73 20 74        which is t
2a450 68 65 20 6d 65 74 61 64 61 74 61 20 70 6f 69 6e  he metadata poin
2a460 74 65 72 20 50 20 66 6f 6c 6c 6f 77 69 6e 67 20  ter P following 
2a470 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 20 20 20  a call to.**    
2a480 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73        [sqlite3_s
2a490 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50  et_auxdata(C,N,P
2a4a0 2c 44 29 5d 20 77 68 65 6e 20 53 51 4c 69 74 65  ,D)] when SQLite
2a4b0 20 63 65 61 73 65 73 20 74 6f 20 68 6f 6c 64 0a   ceases to hold.
2a4c0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
2a4d0 6d 65 74 61 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20  metadata..**.** 
2a4e0 7b 46 31 36 32 37 37 7d 20 53 51 4c 69 74 65 20  {F16277} SQLite 
2a4f0 63 65 61 73 65 73 20 74 6f 20 68 6f 6c 64 20 6d  ceases to hold m
2a500 65 74 61 64 61 74 61 20 66 6f 72 20 61 6e 20 53  etadata for an S
2a510 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61  QL function para
2a520 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  meter.**        
2a530 20 20 77 68 65 6e 20 74 68 65 20 76 61 6c 75 65    when the value
2a540 20 6f 66 20 74 68 61 74 20 70 61 72 61 6d 65 74   of that paramet
2a550 65 72 20 63 68 61 6e 67 65 73 2e 0a 2a 2a 0a 2a  er changes..**.*
2a560 2a 20 7b 46 31 36 32 37 38 7d 20 57 68 65 6e 20  * {F16278} When 
2a570 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78  [sqlite3_set_aux
2a580 64 61 74 61 28 43 2c 4e 2c 50 2c 44 29 5d 20 69  data(C,N,P,D)] i
2a590 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20 64  s invoked, the d
2a5a0 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 20 20 20  estructor.**    
2a5b0 20 20 20 20 20 20 69 73 20 63 61 6c 6c 65 64 20        is called 
2a5c0 66 6f 72 20 61 6e 79 20 70 72 69 6f 72 20 6d 65  for any prior me
2a5d0 74 61 64 61 74 61 20 61 73 73 6f 63 69 61 74 65  tadata associate
2a5e0 64 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20  d with the same 
2a5f0 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20  function.**     
2a600 20 20 20 20 20 63 6f 6e 74 65 78 74 20 43 20 61       context C a
2a610 6e 64 20 70 61 72 61 6d 65 74 65 72 20 4e 2e 0a  nd parameter N..
2a620 2a 2a 0a 2a 2a 20 7b 46 31 36 32 37 39 7d 20 53  **.** {F16279} S
2a630 51 4c 69 74 65 20 77 69 6c 6c 20 63 61 6c 6c 20  QLite will call 
2a640 64 65 73 74 72 75 63 74 6f 72 73 20 66 6f 72 20  destructors for 
2a650 61 6e 79 20 6d 65 74 61 64 61 74 61 20 69 74 20  any metadata it 
2a660 69 73 20 68 6f 6c 64 69 6e 67 0a 2a 2a 20 20 20  is holding.**   
2a670 20 20 20 20 20 20 20 69 6e 20 61 20 70 61 72 74         in a part
2a680 69 63 75 6c 61 72 20 5b 70 72 65 70 61 72 65 64  icular [prepared
2a690 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 77 68   statement] S wh
2a6a0 65 6e 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20  en either.**    
2a6b0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72        [sqlite3_r
2a6c0 65 73 65 74 28 53 29 5d 20 6f 72 20 5b 73 71 6c  eset(S)] or [sql
2a6d0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29  ite3_finalize(S)
2a6e0 5d 20 69 73 20 63 61 6c 6c 65 64 2e 0a 2a 2f 0a  ] is called..*/.
2a6f0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 67 65  void *sqlite3_ge
2a700 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65  t_auxdata(sqlite
2a710 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20  3_context*, int 
2a720 4e 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  N);.void sqlite3
2a730 5f 73 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c  _set_auxdata(sql
2a740 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
2a750 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69  nt N, void*, voi
2a760 64 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a  d (*)(void*));..
2a770 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2a780 20 43 6f 6e 73 74 61 6e 74 73 20 44 65 66 69 6e   Constants Defin
2a790 69 6e 67 20 53 70 65 63 69 61 6c 20 44 65 73 74  ing Special Dest
2a7a0 72 75 63 74 6f 72 20 42 65 68 61 76 69 6f 72 20  ructor Behavior 
2a7b0 7b 46 31 30 32 38 30 7d 0a 2a 2a 0a 2a 2a 20 54  {F10280}.**.** T
2a7c0 68 65 73 65 20 61 72 65 20 73 70 65 63 69 61 6c  hese are special
2a7d0 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 64   value for the d
2a7e0 65 73 74 72 75 63 74 6f 72 20 74 68 61 74 20 69  estructor that i
2a7f0 73 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 74  s passed in as t
2a800 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75  he.** final argu
2a810 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65 73  ment to routines
2a820 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72   like [sqlite3_r
2a830 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20  esult_blob()].  
2a840 49 66 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  If the destructo
2a850 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73  r.** argument is
2a860 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20   SQLITE_STATIC, 
2a870 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  it means that th
2a880 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65  e content pointe
2a890 72 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a  r is constant.**
2a8a0 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72 20   and will never 
2a8b0 63 68 61 6e 67 65 2e 20 20 49 74 20 64 6f 65 73  change.  It does
2a8c0 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20   not need to be 
2a8d0 64 65 73 74 72 6f 79 65 64 2e 20 20 54 68 65 20  destroyed.  The 
2a8e0 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e 53  .** SQLITE_TRANS
2a8f0 49 45 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e 73  IENT value means
2a900 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e   that the conten
2a910 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 68  t will likely ch
2a920 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e  ange in.** the n
2a930 65 61 72 20 66 75 74 75 72 65 20 61 6e 64 20 74  ear future and t
2a940 68 61 74 20 53 51 4c 69 74 65 20 73 68 6f 75 6c  hat SQLite shoul
2a950 64 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20 70  d make its own p
2a960 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 0a 2a  rivate copy of.*
2a970 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 62 65  * the content be
2a980 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a  fore returning..
2a990 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 64 65  **.** The typede
2a9a0 66 20 69 73 20 6e 65 63 65 73 73 61 72 79 20 74  f is necessary t
2a9b0 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70 72  o work around pr
2a9c0 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72 74 61 69  oblems in certai
2a9d0 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c 65  n.** C++ compile
2a9e0 72 73 2e 20 20 53 65 65 20 74 69 63 6b 65 74 20  rs.  See ticket 
2a9f0 23 32 31 39 31 2e 0a 2a 2f 0a 74 79 70 65 64 65  #2191..*/.typede
2aa00 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33  f void (*sqlite3
2aa10 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65  _destructor_type
2aa20 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e  )(void*);.#defin
2aa30 65 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 20  e SQLITE_STATIC 
2aa40 20 20 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64       ((sqlite3_d
2aa50 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 30  estructor_type)0
2aa60 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
2aa70 5f 54 52 41 4e 53 49 45 4e 54 20 20 20 28 28 73  _TRANSIENT   ((s
2aa80 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f  qlite3_destructo
2aa90 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a  r_type)-1)../*.*
2aaa0 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 74  * CAPI3REF: Sett
2aab0 69 6e 67 20 54 68 65 20 52 65 73 75 6c 74 20 4f  ing The Result O
2aac0 66 20 41 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f  f An SQL Functio
2aad0 6e 20 7b 46 31 36 34 30 30 7d 0a 2a 2a 0a 2a 2a  n {F16400}.**.**
2aae0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
2aaf0 61 72 65 20 75 73 65 64 20 62 79 20 74 68 65 20  are used by the 
2ab00 78 46 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20  xFunc or xFinal 
2ab10 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a  callbacks that.*
2ab20 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20  * implement SQL 
2ab30 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67  functions and ag
2ab40 67 72 65 67 61 74 65 73 2e 20 20 53 65 65 0a 2a  gregates.  See.*
2ab50 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  * [sqlite3_creat
2ab60 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e  e_function()] an
2ab70 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  d [sqlite3_creat
2ab80 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a  e_function16()].
2ab90 2a 2a 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  ** for additiona
2aba0 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  l information..*
2abb0 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74  *.** These funct
2abc0 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79 20 6d  ions work very m
2abd0 75 63 68 20 6c 69 6b 65 20 74 68 65 20 0a 2a 2a  uch like the .**
2abe0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
2abf0 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69  lob | sqlite3_bi
2ac00 6e 64 5f 2a 5d 20 66 61 6d 69 6c 79 20 6f 66 20  nd_*] family of 
2ac10 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 64 0a 2a  functions used.*
2ac20 2a 20 74 6f 20 62 69 6e 64 20 76 61 6c 75 65 73  * to bind values
2ac30 20 74 6f 20 68 6f 73 74 20 70 61 72 61 6d 65 74   to host paramet
2ac40 65 72 73 20 69 6e 20 70 72 65 70 61 72 65 64 20  ers in prepared 
2ac50 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52  statements..** R
2ac60 65 66 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 5b  efer to the.** [
2ac70 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2ac80 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  b | sqlite3_bind
2ac90 5f 2a 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  _* documentation
2aca0 5d 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f  ] for.** additio
2acb0 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  nal information.
2acc0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
2acd0 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29  e3_result_blob()
2ace0 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
2acf0 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a  the result from.
2ad00 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  ** an applicatio
2ad10 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n defined functi
2ad20 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 42 4c 4f  on to be the BLO
2ad30 42 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20  B whose content 
2ad40 69 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f  is pointed.** to
2ad50 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 70   by the second p
2ad60 61 72 61 6d 65 74 65 72 20 61 6e 64 20 77 68 69  arameter and whi
2ad70 63 68 20 69 73 20 4e 20 62 79 74 65 73 20 6c 6f  ch is N bytes lo
2ad80 6e 67 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  ng where N is th
2ad90 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d  e.** third param
2ada0 65 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20 73 71  eter. .** The sq
2adb0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72  lite3_result_zer
2adc0 6f 62 6c 6f 62 28 29 20 69 6e 65 72 66 61 63 65  oblob() inerface
2add0 73 20 73 65 74 20 74 68 65 20 72 65 73 75 6c 74  s set the result
2ade0 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69   of.** the appli
2adf0 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66  cation defined f
2ae00 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20  unction to be a 
2ae10 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e 67 20  BLOB containing 
2ae20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79 74 65  all zero.** byte
2ae30 73 20 61 6e 64 20 4e 20 62 79 74 65 73 20 69 6e  s and N bytes in
2ae40 20 73 69 7a 65 2c 20 77 68 65 72 65 20 4e 20 69   size, where N i
2ae50 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  s the value of t
2ae60 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
2ae70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
2ae80 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c  te3_result_doubl
2ae90 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  e() interface se
2aea0 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 66 72  ts the result fr
2aeb0 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61  om.** an applica
2aec0 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e  tion defined fun
2aed0 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 66 6c  ction to be a fl
2aee0 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
2aef0 75 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20  ue specified.** 
2af00 62 79 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d  by its 2nd argum
2af10 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ent..**.** The s
2af20 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
2af30 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ror() and sqlite
2af40 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
2af50 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  () functions.** 
2af60 63 61 75 73 65 20 74 68 65 20 69 6d 70 6c 65 6d  cause the implem
2af70 65 6e 74 65 64 20 53 51 4c 20 66 75 6e 63 74 69  ented SQL functi
2af80 6f 6e 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65  on to throw an e
2af90 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20 53 51 4c  xception..** SQL
2afa0 69 74 65 20 75 73 65 73 20 74 68 65 20 73 74 72  ite uses the str
2afb0 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  ing pointed to b
2afc0 79 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70 61 72  y the.** 2nd par
2afd0 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65  ameter of sqlite
2afe0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
2aff0 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
2b000 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20  lt_error16().** 
2b010 61 73 20 74 68 65 20 74 65 78 74 20 6f 66 20 61  as the text of a
2b020 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e  n error message.
2b030 20 20 53 51 4c 69 74 65 20 69 6e 74 65 72 70 72    SQLite interpr
2b040 65 74 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a  ets the error.**
2b050 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20   message string 
2b060 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73  from sqlite3_res
2b070 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 73 20 55  ult_error() as U
2b080 54 46 38 2e 20 53 51 4c 69 74 65 0a 2a 2a 20 69  TF8. SQLite.** i
2b090 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 73 74  nterprets the st
2b0a0 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65  ring from sqlite
2b0b0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
2b0c0 28 29 20 61 73 20 55 54 46 31 36 20 69 6e 20 6e  () as UTF16 in n
2b0d0 61 74 69 76 65 0a 2a 2a 20 62 79 74 65 20 6f 72  ative.** byte or
2b0e0 64 65 72 2e 20 20 49 66 20 74 68 65 20 74 68 69  der.  If the thi
2b0f0 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
2b100 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
2b110 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  rror().** or sql
2b120 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
2b130 72 31 36 28 29 20 69 73 20 6e 65 67 61 74 69 76  r16() is negativ
2b140 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61  e then SQLite ta
2b150 6b 65 73 20 61 73 20 74 68 65 20 65 72 72 6f 72  kes as the error
2b160 0a 2a 2a 20 6d 65 73 73 61 67 65 20 61 6c 6c 20  .** message all 
2b170 74 65 78 74 20 75 70 20 74 68 72 6f 75 67 68 20  text up through 
2b180 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63  the first zero c
2b190 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 66 20  haracter..** If 
2b1a0 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
2b1b0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
2b1c0 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72  esult_error() or
2b1d0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75  .** sqlite3_resu
2b1e0 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20  lt_error16() is 
2b1f0 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 74 68 65  non-negative the
2b200 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74  n SQLite takes t
2b210 68 61 74 20 6d 61 6e 79 0a 2a 2a 20 62 79 74 65  hat many.** byte
2b220 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72  s (not character
2b230 73 29 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20  s) from the 2nd 
2b240 70 61 72 61 6d 65 74 65 72 20 61 73 20 74 68 65  parameter as the
2b250 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a   error message..
2b260 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
2b270 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e  esult_error() an
2b280 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
2b290 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 72 6f  _error16().** ro
2b2a0 75 74 69 6e 65 73 20 6d 61 6b 65 20 61 20 63 6f  utines make a co
2b2b0 70 79 20 70 72 69 76 61 74 65 20 63 6f 70 79 20  py private copy 
2b2c0 6f 66 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  of the error mes
2b2d0 73 61 67 65 20 74 65 78 74 20 62 65 66 6f 72 65  sage text before
2b2e0 0a 2a 2a 20 74 68 65 79 20 72 65 74 75 72 6e 2e  .** they return.
2b2f0 20 20 48 65 6e 63 65 2c 20 74 68 65 20 63 61 6c    Hence, the cal
2b300 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61  ling function ca
2b310 6e 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f 72 0a  n deallocate or.
2b320 2a 2a 20 6d 6f 64 69 66 79 20 74 68 65 20 74 65  ** modify the te
2b330 78 74 20 61 66 74 65 72 20 74 68 65 79 20 72 65  xt after they re
2b340 74 75 72 6e 20 77 69 74 68 6f 75 74 20 68 61 72  turn without har
2b350 6d 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  m..** The sqlite
2b360 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63  3_result_error_c
2b370 6f 64 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 63  ode() function c
2b380 68 61 6e 67 65 73 20 74 68 65 20 65 72 72 6f 72  hanges the error
2b390 20 63 6f 64 65 0a 2a 2a 20 72 65 74 75 72 6e 65   code.** returne
2b3a0 64 20 62 79 20 53 51 4c 69 74 65 20 61 73 20 61  d by SQLite as a
2b3b0 20 72 65 73 75 6c 74 20 6f 66 20 61 6e 20 65 72   result of an er
2b3c0 72 6f 72 20 69 6e 20 61 20 66 75 6e 63 74 69 6f  ror in a functio
2b3d0 6e 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 0a  n.  By default,.
2b3e0 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64  ** the error cod
2b3f0 65 20 69 73 20 53 51 4c 49 54 45 5f 45 52 52 4f  e is SQLITE_ERRO
2b400 52 2e 20 20 41 20 73 75 62 73 65 71 75 65 6e 74  R.  A subsequent
2b410 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
2b420 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a  _result_error().
2b430 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ** or sqlite3_re
2b440 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 72  sult_error16() r
2b450 65 73 65 74 73 20 74 68 65 20 65 72 72 6f 72 20  esets the error 
2b460 63 6f 64 65 20 74 6f 20 53 51 4c 49 54 45 5f 45  code to SQLITE_E
2b470 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  RROR..**.** The 
2b480 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
2b490 6f 6f 62 69 67 28 29 20 69 6e 74 65 72 66 61 63  oobig() interfac
2b4a0 65 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 0a  e causes SQLite.
2b4b0 2a 2a 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65  ** to throw an e
2b4c0 72 72 6f 72 20 69 6e 64 69 63 61 74 69 6e 67 20  rror indicating 
2b4d0 74 68 61 74 20 61 20 73 74 72 69 6e 67 20 6f 72  that a string or
2b4e0 20 42 4c 4f 42 20 69 73 20 74 6f 20 6c 6f 6e 67   BLOB is to long
2b4f0 0a 2a 2a 20 74 6f 20 72 65 70 72 65 73 65 6e 74  .** to represent
2b500 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  .  The sqlite3_r
2b510 65 73 75 6c 74 5f 6e 6f 6d 65 6d 28 29 20 69 6e  esult_nomem() in
2b520 74 65 72 66 61 63 65 0a 2a 2a 20 63 61 75 73 65  terface.** cause
2b530 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f  s SQLite to thro
2b540 77 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 69  w an exception i
2b550 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 74  ndicating that t
2b560 68 65 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  he a.** memory a
2b570 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65 64  llocation failed
2b580 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
2b590 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 29  te3_result_int()
2b5a0 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
2b5b0 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
2b5c0 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69  .** of the appli
2b5d0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
2b5e0 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68  unction to be th
2b5f0 65 20 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20  e 32-bit signed 
2b600 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65  integer.** value
2b610 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e   given in the 2n
2b620 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54  d argument..** T
2b630 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
2b640 74 5f 69 6e 74 36 34 28 29 20 69 6e 74 65 72 66  t_int64() interf
2b650 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74  ace sets the ret
2b660 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20  urn value.** of 
2b670 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
2b680 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
2b690 20 74 6f 20 62 65 20 74 68 65 20 36 34 2d 62 69   to be the 64-bi
2b6a0 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
2b6b0 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20  .** value given 
2b6c0 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d  in the 2nd argum
2b6d0 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ent..**.** The s
2b6e0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75  qlite3_result_nu
2b6f0 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  ll() interface s
2b700 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76  ets the return v
2b710 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61  alue.** of the a
2b720 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2b730 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
2b740 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68  e NULL..**.** Th
2b750 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
2b760 5f 74 65 78 74 28 29 2c 20 73 71 6c 69 74 65 33  _text(), sqlite3
2b770 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 29  _result_text16()
2b780 2c 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65  , .** sqlite3_re
2b790 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 29 2c  sult_text16le(),
2b7a0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73   and sqlite3_res
2b7b0 75 6c 74 5f 74 65 78 74 31 36 62 65 28 29 20 69  ult_text16be() i
2b7c0 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 73 65 74  nterfaces.** set
2b7d0 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
2b7e0 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  e of the applica
2b7f0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
2b800 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 61  ction to be.** a
2b810 20 74 65 78 74 20 73 74 72 69 6e 67 20 77 68 69   text string whi
2b820 63 68 20 69 73 20 72 65 70 72 65 73 65 6e 74 65  ch is represente
2b830 64 20 61 73 20 55 54 46 2d 38 2c 20 55 54 46 2d  d as UTF-8, UTF-
2b840 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  16 native byte o
2b850 72 64 65 72 2c 0a 2a 2a 20 55 54 46 2d 31 36 20  rder,.** UTF-16 
2b860 6c 69 74 74 6c 65 20 65 6e 64 69 61 6e 2c 20 6f  little endian, o
2b870 72 20 55 54 46 2d 31 36 20 62 69 67 20 65 6e 64  r UTF-16 big end
2b880 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c  ian, respectivel
2b890 79 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 74 61 6b  y..** SQLite tak
2b8a0 65 73 20 74 68 65 20 74 65 78 74 20 72 65 73 75  es the text resu
2b8b0 6c 74 20 66 72 6f 6d 20 74 68 65 20 61 70 70 6c  lt from the appl
2b8c0 69 63 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20  ication from.** 
2b8d0 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
2b8e0 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  r of the sqlite3
2b8f0 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
2b900 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 49 66 20  terfaces..** If 
2b910 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  the 3rd paramete
2b920 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
2b930 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
2b940 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e  terfaces.** is n
2b950 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 53 51  egative, then SQ
2b960 4c 69 74 65 20 74 61 6b 65 73 20 72 65 73 75 6c  Lite takes resul
2b970 74 20 74 65 78 74 20 66 72 6f 6d 20 74 68 65 20  t text from the 
2b980 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 0a 2a  2nd parameter .*
2b990 2a 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69  * through the fi
2b9a0 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74  rst zero charact
2b9b0 65 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 33 72  er..** If the 3r
2b9c0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
2b9d0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
2b9e0 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
2b9f0 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67  es.** is non-neg
2ba00 61 74 69 76 65 2c 20 74 68 65 6e 20 61 73 20 6d  ative, then as m
2ba10 61 6e 79 20 62 79 74 65 73 20 28 6e 6f 74 20 63  any bytes (not c
2ba20 68 61 72 61 63 74 65 72 73 29 20 6f 66 20 74 68  haracters) of th
2ba30 65 20 74 65 78 74 0a 2a 2a 20 70 6f 69 6e 74 65  e text.** pointe
2ba40 64 20 74 6f 20 62 79 20 74 68 65 20 32 6e 64 20  d to by the 2nd 
2ba50 70 61 72 61 6d 65 74 65 72 20 61 72 65 20 74 61  parameter are ta
2ba60 6b 65 6e 20 61 73 20 74 68 65 20 61 70 70 6c 69  ken as the appli
2ba70 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a  cation-defined.*
2ba80 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 73 75 6c  * function resul
2ba90 74 2e 0a 2a 2a 20 49 66 20 74 68 65 20 34 74 68  t..** If the 4th
2baa0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
2bab0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
2bac0 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
2bad0 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  s.** or sqlite3_
2bae0 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 61  result_blob is a
2baf0 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65   non-NULL pointe
2bb00 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 63  r, then SQLite c
2bb10 61 6c 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75 6e  alls that.** fun
2bb20 63 74 69 6f 6e 20 61 73 20 74 68 65 20 64 65 73  ction as the des
2bb30 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 74  tructor on the t
2bb40 65 78 74 20 6f 72 20 62 6c 6f 62 20 72 65 73 75  ext or blob resu
2bb50 6c 74 20 77 68 65 6e 20 69 74 20 68 61 73 0a 2a  lt when it has.*
2bb60 2a 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67  * finished using
2bb70 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a   that result..**
2bb80 20 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61   If the 4th para
2bb90 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
2bba0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
2bbb0 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  * interfaces.** 
2bbc0 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
2bbd0 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70  t_blob is the sp
2bbe0 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53  ecial constant S
2bbf0 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 74 68  QLITE_STATIC, th
2bc00 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 61 73 73  en.** SQLite ass
2bc10 75 6d 65 73 20 74 68 61 74 20 74 68 65 20 74 65  umes that the te
2bc20 78 74 20 6f 72 20 62 6c 6f 62 20 72 65 73 75 6c  xt or blob resul
2bc30 74 20 69 73 20 63 6f 6e 73 74 61 6e 74 20 73 70  t is constant sp
2bc40 61 63 65 20 61 6e 64 0a 2a 2a 20 64 6f 65 73 20  ace and.** does 
2bc50 6e 6f 74 20 63 6f 70 79 20 74 68 65 20 73 70 61  not copy the spa
2bc60 63 65 20 6f 72 20 63 61 6c 6c 20 61 20 64 65 73  ce or call a des
2bc70 74 72 75 63 74 6f 72 20 77 68 65 6e 20 69 74 20  tructor when it 
2bc80 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20  has.** finished 
2bc90 75 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c  using that resul
2bca0 74 2e 0a 2a 2a 20 49 66 20 74 68 65 20 34 74 68  t..** If the 4th
2bcb0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
2bcc0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
2bcd0 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
2bce0 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  s.** or sqlite3_
2bcf0 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74  result_blob is t
2bd00 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74  he special const
2bd10 61 6e 74 20 53 51 4c 49 54 45 5f 54 52 41 4e 53  ant SQLITE_TRANS
2bd20 49 45 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 51 4c  IENT.** then SQL
2bd30 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79  ite makes a copy
2bd40 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 69   of the result i
2bd50 6e 74 6f 20 73 70 61 63 65 20 6f 62 74 61 69 6e  nto space obtain
2bd60 65 64 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20  ed from.** from 
2bd70 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
2bd80 29 5d 20 62 65 66 6f 72 65 20 69 74 20 72 65 74  )] before it ret
2bd90 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  urns..**.** The 
2bda0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
2bdb0 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65  alue() interface
2bdc0 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74   sets the result
2bdd0 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69   of.** the appli
2bde0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
2bdf0 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20  unction to be a 
2be00 63 6f 70 79 20 74 68 65 0a 2a 2a 20 5b 75 6e 70  copy the.** [unp
2be10 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2be20 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 73  _value] object s
2be30 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
2be40 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20  2nd parameter.  
2be50 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72  The.** sqlite3_r
2be60 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e  esult_value() in
2be70 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20  terface makes a 
2be80 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c  copy of the [sql
2be90 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73  ite3_value].** s
2bea0 6f 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f  o that [sqlite3_
2beb0 76 61 6c 75 65 5d 20 73 70 65 63 69 66 69 65 64  value] specified
2bec0 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65   in the paramete
2bed0 72 20 6d 61 79 20 63 68 61 6e 67 65 20 6f 72 0a  r may change or.
2bee0 2a 2a 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65  ** be deallocate
2bef0 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f  d after sqlite3_
2bf00 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 72  result_value() r
2bf10 65 74 75 72 6e 73 20 77 69 74 68 6f 75 74 20 68  eturns without h
2bf20 61 72 6d 2e 0a 2a 2a 20 41 20 5b 70 72 6f 74 65  arm..** A [prote
2bf30 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2bf40 75 65 5d 20 6f 62 6a 65 63 74 20 6d 61 79 20 61  ue] object may a
2bf50 6c 77 61 79 73 20 62 65 20 75 73 65 64 20 77 68  lways be used wh
2bf60 65 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f  ere an.** [unpro
2bf70 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2bf80 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 69 73 20  alue] object is 
2bf90 72 65 71 75 69 72 65 64 2c 20 73 6f 20 65 69 74  required, so eit
2bfa0 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b  her.** kind of [
2bfb0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2bfc0 62 6a 65 63 74 20 63 61 6e 20 62 65 20 75 73 65  bject can be use
2bfd0 64 20 77 69 74 68 20 74 68 69 73 20 69 6e 74 65  d with this inte
2bfe0 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  rface..**.** If 
2bff0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  these routines a
2c000 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77  re called from w
2c010 69 74 68 69 6e 20 74 68 65 20 64 69 66 66 65 72  ithin the differ
2c020 65 6e 74 20 74 68 72 65 61 64 20 0a 2a 2a 20 74  ent thread .** t
2c030 68 61 6e 20 74 68 65 20 6f 6e 65 20 63 6f 6e 74  han the one cont
2c040 61 69 6e 69 6e 67 20 74 68 65 20 61 70 70 6c 69  aining the appli
2c050 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
2c060 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 72 65 63  unction that rec
2c070 69 65 76 65 64 0a 2a 2a 20 74 68 65 20 5b 73 71  ieved.** the [sq
2c080 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 70  lite3_context] p
2c090 6f 69 6e 74 65 72 2c 20 74 68 65 20 72 65 73 75  ointer, the resu
2c0a0 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
2c0b0 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  d..**.** INVARIA
2c0c0 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34  NTS:.**.** {F164
2c0d0 30 33 7d 20 54 68 65 20 64 65 66 61 75 6c 74 20  03} The default 
2c0e0 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f  return value fro
2c0f0 6d 20 61 6e 79 20 53 51 4c 20 66 75 6e 63 74 69  m any SQL functi
2c100 6f 6e 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  on is NULL..**.*
2c110 2a 20 7b 46 31 36 34 30 36 7d 20 54 68 65 20 5b  * {F16406} The [
2c120 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
2c130 6c 6f 62 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e  lob(C,V,N,D)] in
2c140 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20  terface changes 
2c150 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
2c160 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
2c170 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65  function C to be
2c180 20 61 20 62 6c 6f 62 20 74 68 61 74 20 69 73 20   a blob that is 
2c190 4e 20 62 79 74 65 73 0a 2a 2a 20 20 20 20 20 20  N bytes.**      
2c1a0 20 20 20 20 69 6e 20 6c 65 6e 67 74 68 20 61 6e      in length an
2c1b0 64 20 77 69 74 68 20 63 6f 6e 74 65 6e 74 20 70  d with content p
2c1c0 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 56 2e 0a  ointed to by V..
2c1d0 2a 2a 0a 2a 2a 20 7b 46 31 36 34 30 39 7d 20 54  **.** {F16409} T
2c1e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  he [sqlite3_resu
2c1f0 6c 74 5f 64 6f 75 62 6c 65 28 43 2c 56 29 5d 20  lt_double(C,V)] 
2c200 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65  interface change
2c210 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
2c220 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f    return value o
2c230 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20  f function C to 
2c240 62 65 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20  be the floating 
2c250 70 6f 69 6e 74 20 76 61 6c 75 65 20 56 2e 0a 2a  point value V..*
2c260 2a 0a 2a 2a 20 7b 46 31 36 34 31 32 7d 20 54 68  *.** {F16412} Th
2c270 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  e [sqlite3_resul
2c280 74 5f 65 72 72 6f 72 28 43 2c 56 2c 4e 29 5d 20  t_error(C,V,N)] 
2c290 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65  interface change
2c2a0 73 20 74 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20  s the return.** 
2c2b0 20 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 6f           value o
2c2c0 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20  f function C to 
2c2d0 62 65 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20  be an exception 
2c2e0 77 69 74 68 20 65 72 72 6f 72 20 63 6f 64 65 0a  with error code.
2c2f0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c  **          [SQL
2c300 49 54 45 5f 45 52 52 4f 52 5d 20 61 6e 64 20 61  ITE_ERROR] and a
2c310 20 55 54 46 38 20 65 72 72 6f 72 20 6d 65 73 73   UTF8 error mess
2c320 61 67 65 20 63 6f 70 69 65 64 20 66 72 6f 6d 20  age copied from 
2c330 56 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20 20  V up to the.**  
2c340 20 20 20 20 20 20 20 20 66 69 72 73 74 20 7a 65          first ze
2c350 72 6f 20 62 79 74 65 20 6f 72 20 75 6e 74 69 6c  ro byte or until
2c360 20 4e 20 62 79 74 65 73 20 61 72 65 20 72 65 61   N bytes are rea
2c370 64 20 69 66 20 4e 20 69 73 20 70 6f 73 69 74 69  d if N is positi
2c380 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 31  ve..**.** {F1641
2c390 35 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  5} The [sqlite3_
2c3a0 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 43  result_error16(C
2c3b0 2c 56 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  ,V,N)] interface
2c3c0 20 63 68 61 6e 67 65 73 20 74 68 65 20 72 65 74   changes the ret
2c3d0 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  urn.**          
2c3e0 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f  value of functio
2c3f0 6e 20 43 20 74 6f 20 62 65 20 61 6e 20 65 78 63  n C to be an exc
2c400 65 70 74 69 6f 6e 20 77 69 74 68 20 65 72 72 6f  eption with erro
2c410 72 20 63 6f 64 65 0a 2a 2a 20 20 20 20 20 20 20  r code.**       
2c420 20 20 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52     [SQLITE_ERROR
2c430 5d 20 61 6e 64 20 61 20 55 54 46 31 36 20 6e 61  ] and a UTF16 na
2c440 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
2c450 65 72 72 6f 72 20 6d 65 73 73 61 67 65 0a 2a 2a  error message.**
2c460 20 20 20 20 20 20 20 20 20 20 63 6f 70 69 65 64            copied
2c470 20 66 72 6f 6d 20 56 20 75 70 20 74 6f 20 74 68   from V up to th
2c480 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72  e first zero ter
2c490 6d 69 6e 61 74 6f 72 20 6f 72 20 75 6e 74 69 6c  minator or until
2c4a0 20 4e 20 62 79 74 65 73 0a 2a 2a 20 20 20 20 20   N bytes.**     
2c4b0 20 20 20 20 20 61 72 65 20 72 65 61 64 20 69 66       are read if
2c4c0 20 4e 20 69 73 20 70 6f 73 69 74 69 76 65 2e 0a   N is positive..
2c4d0 2a 2a 0a 2a 2a 20 7b 46 31 36 34 31 38 7d 20 54  **.** {F16418} T
2c4e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  he [sqlite3_resu
2c4f0 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28  lt_error_toobig(
2c500 43 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68  C)] interface ch
2c510 61 6e 67 65 73 20 74 68 65 20 72 65 74 75 72 6e  anges the return
2c520 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c  .**          val
2c530 75 65 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69  ue of the functi
2c540 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e 20 65 78  on C to be an ex
2c550 63 65 70 74 69 6f 6e 20 77 69 74 68 20 65 72 72  ception with err
2c560 6f 72 20 63 6f 64 65 0a 2a 2a 20 20 20 20 20 20  or code.**      
2c570 20 20 20 20 5b 53 51 4c 49 54 45 5f 54 4f 4f 42      [SQLITE_TOOB
2c580 49 47 5d 20 61 6e 64 20 61 6e 20 61 70 70 72 6f  IG] and an appro
2c590 70 72 69 61 74 65 20 65 72 72 6f 72 20 6d 65 73  priate error mes
2c5a0 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  sage..**.** {F16
2c5b0 34 32 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  421} The [sqlite
2c5c0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e  3_result_error_n
2c5d0 6f 6d 65 6d 28 43 29 5d 20 69 6e 74 65 72 66 61  omem(C)] interfa
2c5e0 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 20 72  ce changes the r
2c5f0 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20  eturn.**        
2c600 20 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 66    value of the f
2c610 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20  unction C to be 
2c620 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 77 69 74  an exception wit
2c630 68 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20  h error code.** 
2c640 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45           [SQLITE
2c650 5f 4e 4f 4d 45 4d 5d 20 61 6e 64 20 61 6e 20 61  _NOMEM] and an a
2c660 70 70 72 6f 70 72 69 61 74 65 20 65 72 72 6f 72  ppropriate error
2c670 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20   message..**.** 
2c680 7b 46 31 36 34 32 34 7d 20 54 68 65 20 5b 73 71  {F16424} The [sq
2c690 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
2c6a0 6f 72 5f 63 6f 64 65 28 43 2c 45 29 5d 20 69 6e  or_code(C,E)] in
2c6b0 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20  terface changes 
2c6c0 74 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20  the return.**   
2c6d0 20 20 20 20 20 20 20 76 61 6c 75 65 20 6f 66 20         value of 
2c6e0 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 43 20 74  the function C t
2c6f0 6f 20 62 65 20 61 6e 20 65 78 63 65 70 74 69 6f  o be an exceptio
2c700 6e 20 77 69 74 68 20 65 72 72 6f 72 20 63 6f 64  n with error cod
2c710 65 20 45 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20  e E..**         
2c720 20 54 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   The error messa
2c730 67 65 20 74 65 78 74 20 69 73 20 75 6e 63 68 61  ge text is uncha
2c740 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  nged..**.** {F16
2c750 34 32 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  427} The [sqlite
2c760 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 43 2c 56  3_result_int(C,V
2c770 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61  )] interface cha
2c780 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  nges the.**     
2c790 20 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75       return valu
2c7a0 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20  e of function C 
2c7b0 74 6f 20 62 65 20 74 68 65 20 33 32 2d 62 69 74  to be the 32-bit
2c7c0 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 20 56   integer value V
2c7d0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 33 30 7d  ..**.** {F16430}
2c7e0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   The [sqlite3_re
2c7f0 73 75 6c 74 5f 69 6e 74 36 34 28 43 2c 56 29 5d  sult_int64(C,V)]
2c800 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67   interface chang
2c810 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  es the.**       
2c820 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20     return value 
2c830 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f  of function C to
2c840 20 62 65 20 74 68 65 20 36 34 2d 62 69 74 20 69   be the 64-bit i
2c850 6e 74 65 67 65 72 20 76 61 6c 75 65 20 56 2e 0a  nteger value V..
2c860 2a 2a 0a 2a 2a 20 7b 46 31 36 34 33 33 7d 20 54  **.** {F16433} T
2c870 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  he [sqlite3_resu
2c880 6c 74 5f 6e 75 6c 6c 28 43 29 5d 20 69 6e 74 65  lt_null(C)] inte
2c890 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68  rface changes th
2c8a0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  e.**          re
2c8b0 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75  turn value of fu
2c8c0 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 4e  nction C to be N
2c8d0 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34  ULL..**.** {F164
2c8e0 33 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  36} The [sqlite3
2c8f0 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 43 2c 56  _result_text(C,V
2c900 2c 4e 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65  ,N,D)] interface
2c910 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20   changes the.** 
2c920 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20           return 
2c930 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f  value of functio
2c940 6e 20 43 20 74 6f 20 62 65 20 74 68 65 20 55 54  n C to be the UT
2c950 46 38 20 73 74 72 69 6e 67 0a 2a 2a 20 20 20 20  F8 string.**    
2c960 20 20 20 20 20 20 56 20 75 70 20 74 6f 20 74 68        V up to th
2c970 65 20 66 69 72 73 74 20 7a 65 72 6f 20 69 66 20  e first zero if 
2c980 4e 20 69 73 20 6e 65 67 61 74 69 76 65 0a 2a 2a  N is negative.**
2c990 20 20 20 20 20 20 20 20 20 20 6f 72 20 74 68 65            or the
2c9a0 20 66 69 72 73 74 20 4e 20 62 79 74 65 73 20 6f   first N bytes o
2c9b0 66 20 56 20 69 66 20 4e 20 69 73 20 6e 6f 6e 2d  f V if N is non-
2c9c0 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20  negative..**.** 
2c9d0 7b 46 31 36 34 33 39 7d 20 54 68 65 20 5b 73 71  {F16439} The [sq
2c9e0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
2c9f0 74 31 36 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e  t16(C,V,N,D)] in
2ca00 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20  terface changes 
2ca10 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
2ca20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
2ca30 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65  function C to be
2ca40 20 74 68 65 20 55 54 46 31 36 20 6e 61 74 69 76   the UTF16 nativ
2ca50 65 20 62 79 74 65 20 6f 72 64 65 72 0a 2a 2a 20  e byte order.** 
2ca60 20 20 20 20 20 20 20 20 20 73 74 72 69 6e 67 20           string 
2ca70 56 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73  V up to the firs
2ca80 74 20 7a 65 72 6f 20 69 66 20 4e 20 69 73 0a 2a  t zero if N is.*
2ca90 2a 20 20 20 20 20 20 20 20 20 20 6e 65 67 61 74  *          negat
2caa0 69 76 65 20 6f 72 20 74 68 65 20 66 69 72 73 74  ive or the first
2cab0 20 4e 20 62 79 74 65 73 20 6f 66 20 56 20 69 66   N bytes of V if
2cac0 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69   N is non-negati
2cad0 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 34  ve..**.** {F1644
2cae0 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  2} The [sqlite3_
2caf0 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28  result_text16be(
2cb00 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74 65 72 66  C,V,N,D)] interf
2cb10 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a  ace changes the.
2cb20 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75  **          retu
2cb30 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63  rn value of func
2cb40 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65  tion C to be the
2cb50 20 55 54 46 31 36 20 62 69 67 2d 65 6e 64 69 61   UTF16 big-endia
2cb60 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74  n.**          st
2cb70 72 69 6e 67 20 56 20 75 70 20 74 6f 20 74 68 65  ring V up to the
2cb80 20 66 69 72 73 74 20 7a 65 72 6f 20 69 66 20 4e   first zero if N
2cb90 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   is.**          
2cba0 69 73 20 6e 65 67 61 74 69 76 65 20 6f 72 20 74  is negative or t
2cbb0 68 65 20 66 69 72 73 74 20 4e 20 62 79 74 65 73  he first N bytes
2cbc0 20 6f 72 20 56 20 69 66 20 4e 20 69 73 20 6e 6f   or V if N is no
2cbd0 6e 2d 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a  n-negative..**.*
2cbe0 2a 20 7b 46 31 36 34 34 35 7d 20 54 68 65 20 5b  * {F16445} The [
2cbf0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
2cc00 65 78 74 31 36 6c 65 28 43 2c 56 2c 4e 2c 44 29  ext16le(C,V,N,D)
2cc10 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e  ] interface chan
2cc20 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  ges the.**      
2cc30 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65      return value
2cc40 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74   of function C t
2cc50 6f 20 62 65 20 74 68 65 20 55 54 46 31 36 20 6c  o be the UTF16 l
2cc60 69 74 74 6c 65 2d 65 6e 64 69 61 6e 0a 2a 2a 20  ittle-endian.** 
2cc70 20 20 20 20 20 20 20 20 20 73 74 72 69 6e 67 20           string 
2cc80 56 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73  V up to the firs
2cc90 74 20 7a 65 72 6f 20 69 66 20 4e 20 69 73 0a 2a  t zero if N is.*
2cca0 2a 20 20 20 20 20 20 20 20 20 20 6e 65 67 61 74  *          negat
2ccb0 69 76 65 20 6f 72 20 74 68 65 20 66 69 72 73 74  ive or the first
2ccc0 20 4e 20 62 79 74 65 73 20 6f 66 20 56 20 69 66   N bytes of V if
2ccd0 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69   N is non-negati
2cce0 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 34  ve..**.** {F1644
2ccf0 38 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  8} The [sqlite3_
2cd00 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 43 2c 56  result_value(C,V
2cd10 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61  )] interface cha
2cd20 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  nges the.**     
2cd30 20 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75       return valu
2cd40 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20  e of function C 
2cd50 74 6f 20 62 65 20 5b 75 6e 70 72 6f 74 65 63 74  to be [unprotect
2cd60 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2cd70 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 62  ].**          ob
2cd80 6a 65 63 74 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 46  ject V..**.** {F
2cd90 31 36 34 35 31 7d 20 54 68 65 20 5b 73 71 6c 69  16451} The [sqli
2cda0 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62  te3_result_zerob
2cdb0 6c 6f 62 28 43 2c 4e 29 5d 20 69 6e 74 65 72 66  lob(C,N)] interf
2cdc0 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a  ace changes the.
2cdd0 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75  **          retu
2cde0 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63  rn value of func
2cdf0 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e 20  tion C to be an 
2ce00 4e 2d 62 79 74 65 20 62 6c 6f 62 20 6f 66 20 61  N-byte blob of a
2ce10 6c 6c 20 7a 65 72 6f 73 2e 0a 2a 2a 0a 2a 2a 20  ll zeros..**.** 
2ce20 7b 46 31 36 34 35 34 7d 20 54 68 65 20 5b 73 71  {F16454} The [sq
2ce30 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
2ce40 6f 72 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  or()] and [sqlit
2ce50 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
2ce60 36 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  6()].**         
2ce70 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6b 65   interfaces make
2ce80 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 69 72   a copy of their
2ce90 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
2cea0 74 72 69 6e 67 73 20 62 65 66 6f 72 65 0a 2a 2a  trings before.**
2ceb0 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e            return
2cec0 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34  ing..**.** {F164
2ced0 35 37 7d 20 49 66 20 74 68 65 20 44 20 64 65 73  57} If the D des
2cee0 74 72 75 63 74 6f 72 20 70 61 72 61 6d 65 74 65  tructor paramete
2cef0 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  r to [sqlite3_re
2cf00 73 75 6c 74 5f 62 6c 6f 62 28 43 2c 56 2c 4e 2c  sult_blob(C,V,N,
2cf10 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  D)],.**         
2cf20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
2cf30 5f 74 65 78 74 28 43 2c 56 2c 4e 2c 44 29 5d 2c  _text(C,V,N,D)],
2cf40 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
2cf50 5f 74 65 78 74 31 36 28 43 2c 56 2c 4e 2c 44 29  _text16(C,V,N,D)
2cf60 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ],.**          [
2cf70 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
2cf80 65 78 74 31 36 62 65 28 43 2c 56 2c 4e 2c 44 29  ext16be(C,V,N,D)
2cf90 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  ], or.**        
2cfa0 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c    [sqlite3_resul
2cfb0 74 5f 74 65 78 74 31 36 6c 65 28 43 2c 56 2c 4e  t_text16le(C,V,N
2cfc0 2c 44 29 5d 20 69 73 20 74 68 65 20 63 6f 6e 73  ,D)] is the cons
2cfd0 74 61 6e 74 20 5b 53 51 4c 49 54 45 5f 53 54 41  tant [SQLITE_STA
2cfe0 54 49 43 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  TIC].**         
2cff0 20 74 68 65 6e 20 6e 6f 20 64 65 73 74 72 75 63   then no destruc
2d000 74 6f 72 20 69 73 20 65 76 65 72 20 63 61 6c 6c  tor is ever call
2d010 65 64 20 6f 6e 20 74 68 65 20 70 6f 69 6e 74 65  ed on the pointe
2d020 72 20 56 20 61 6e 64 20 53 51 4c 69 74 65 0a 2a  r V and SQLite.*
2d030 2a 20 20 20 20 20 20 20 20 20 20 61 73 73 75 6d  *          assum
2d040 65 73 20 74 68 61 74 20 56 20 69 73 20 69 6d 6d  es that V is imm
2d050 75 74 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46  utable..**.** {F
2d060 31 36 34 36 30 7d 20 49 66 20 74 68 65 20 44 20  16460} If the D 
2d070 64 65 73 74 72 75 63 74 6f 72 20 70 61 72 61 6d  destructor param
2d080 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
2d090 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 43 2c 56  _result_blob(C,V
2d0a0 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20  ,N,D)],.**      
2d0b0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73      [sqlite3_res
2d0c0 75 6c 74 5f 74 65 78 74 28 43 2c 56 2c 4e 2c 44  ult_text(C,V,N,D
2d0d0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  )], [sqlite3_res
2d0e0 75 6c 74 5f 74 65 78 74 31 36 28 43 2c 56 2c 4e  ult_text16(C,V,N
2d0f0 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  ,D)],.**        
2d100 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c    [sqlite3_resul
2d110 74 5f 74 65 78 74 31 36 62 65 28 43 2c 56 2c 4e  t_text16be(C,V,N
2d120 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20  ,D)], or.**     
2d130 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65       [sqlite3_re
2d140 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 43 2c  sult_text16le(C,
2d150 56 2c 4e 2c 44 29 5d 20 69 73 20 74 68 65 20 63  V,N,D)] is the c
2d160 6f 6e 73 74 61 6e 74 0a 2a 2a 20 20 20 20 20 20  onstant.**      
2d170 20 20 20 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e      [SQLITE_TRAN
2d180 53 49 45 4e 54 5d 20 74 68 65 6e 20 74 68 65 20  SIENT] then the 
2d190 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6b 65 73  interfaces makes
2d1a0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a   a copy of the.*
2d1b0 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e 74 65  *          conte
2d1c0 6e 74 20 6f 66 20 56 20 61 6e 64 20 72 65 74 61  nt of V and reta
2d1d0 69 6e 73 20 74 68 65 20 63 6f 70 79 2e 0a 2a 2a  ins the copy..**
2d1e0 0a 2a 2a 20 7b 46 31 36 34 36 33 7d 20 49 66 20  .** {F16463} If 
2d1f0 74 68 65 20 44 20 64 65 73 74 72 75 63 74 6f 72  the D destructor
2d200 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
2d210 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
2d220 6f 62 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a  ob(C,V,N,D)],.**
2d230 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
2d240 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 43  e3_result_text(C
2d250 2c 56 2c 4e 2c 44 29 5d 2c 20 5b 73 71 6c 69 74  ,V,N,D)], [sqlit
2d260 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
2d270 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20  (C,V,N,D)],.**  
2d280 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
2d290 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65  _result_text16be
2d2a0 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 6f 72 0a 2a  (C,V,N,D)], or.*
2d2b0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
2d2c0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
2d2d0 36 6c 65 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 73  6le(C,V,N,D)] is
2d2e0 20 73 6f 6d 65 20 76 61 6c 75 65 20 6f 74 68 65   some value othe
2d2f0 72 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20 20  r than.**       
2d300 20 20 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 73     the constants
2d310 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d   [SQLITE_STATIC]
2d320 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 54 52 41   and [SQLITE_TRA
2d330 4e 53 49 45 4e 54 5d 20 74 68 65 6e 20 0a 2a 2a  NSIENT] then .**
2d340 20 20 20 20 20 20 20 20 20 20 53 51 4c 69 74 65            SQLite
2d350 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65   will invoke the
2d360 20 64 65 73 74 72 75 63 74 6f 72 20 44 20 77 69   destructor D wi
2d370 74 68 20 56 20 61 73 20 69 74 73 20 6f 6e 6c 79  th V as its only
2d380 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 20 20 20   argument.**    
2d390 20 20 20 20 20 20 77 68 65 6e 20 69 74 20 68 61        when it ha
2d3a0 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20  s finished with 
2d3b0 74 68 65 20 56 20 76 61 6c 75 65 2e 0a 2a 2f 0a  the V value..*/.
2d3c0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
2d3d0 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  ult_blob(sqlite3
2d3e0 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
2d3f0 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69   void*, int, voi
2d400 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f  d(*)(void*));.vo
2d410 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
2d420 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  t_double(sqlite3
2d430 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f 75 62 6c  _context*, doubl
2d440 65 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  e);.void sqlite3
2d450 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 73 71  _result_error(sq
2d460 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
2d470 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74  const char*, int
2d480 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
2d490 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 73  result_error16(s
2d4a0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2d4b0 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
2d4c0 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  t);.void sqlite3
2d4d0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f  _result_error_to
2d4e0 6f 62 69 67 28 73 71 6c 69 74 65 33 5f 63 6f 6e  obig(sqlite3_con
2d4f0 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c  text*);.void sql
2d500 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
2d510 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74 65 33 5f  r_nomem(sqlite3_
2d520 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20  context*);.void 
2d530 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
2d540 72 72 6f 72 5f 63 6f 64 65 28 73 71 6c 69 74 65  rror_code(sqlite
2d550 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29  3_context*, int)
2d560 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
2d570 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69 74 65  esult_int(sqlite
2d580 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29  3_context*, int)
2d590 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
2d5a0 65 73 75 6c 74 5f 69 6e 74 36 34 28 73 71 6c 69  esult_int64(sqli
2d5b0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71  te3_context*, sq
2d5c0 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 76 6f  lite3_int64);.vo
2d5d0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
2d5e0 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 63  t_null(sqlite3_c
2d5f0 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73  ontext*);.void s
2d600 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
2d610 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  xt(sqlite3_conte
2d620 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  xt*, const char*
2d630 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
2d640 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
2d650 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
2d660 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  16(sqlite3_conte
2d670 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
2d680 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
2d690 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
2d6a0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
2d6b0 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  16le(sqlite3_con
2d6c0 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
2d6d0 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28  d*, int,void(*)(
2d6e0 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71  void*));.void sq
2d6f0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
2d700 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 63 6f  t16be(sqlite3_co
2d710 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f  ntext*, const vo
2d720 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29  id*, int,void(*)
2d730 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
2d740 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
2d750 6c 75 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  lue(sqlite3_cont
2d760 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 76 61  ext*, sqlite3_va
2d770 6c 75 65 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69  lue*);.void sqli
2d780 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62  te3_result_zerob
2d790 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  lob(sqlite3_cont
2d7a0 65 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f  ext*, int n);../
2d7b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
2d7c0 65 66 69 6e 65 20 4e 65 77 20 43 6f 6c 6c 61 74  efine New Collat
2d7d0 69 6e 67 20 53 65 71 75 65 6e 63 65 73 20 7b 46  ing Sequences {F
2d7e0 31 36 36 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  16600}.**.** The
2d7f0 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65  se functions are
2d800 20 75 73 65 64 20 74 6f 20 61 64 64 20 6e 65 77   used to add new
2d810 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
2d820 6e 63 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 5b  nces to the.** [
2d830 73 71 6c 69 74 65 33 2a 5d 20 68 61 6e 64 6c 65  sqlite3*] handle
2d840 20 73 70 65 63 69 66 69 65 64 20 61 73 20 74 68   specified as th
2d850 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
2d860 2e 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d  . .**.** The nam
2d870 65 20 6f 66 20 74 68 65 20 6e 65 77 20 63 6f 6c  e of the new col
2d880 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20  lation sequence 
2d890 69 73 20 73 70 65 63 69 66 69 65 64 20 61 73 20  is specified as 
2d8a0 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a  a UTF-8 string.*
2d8b0 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72  * for sqlite3_cr
2d8c0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29  eate_collation()
2d8d0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 72 65   and sqlite3_cre
2d8e0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
2d8f0 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46 2d  ().** and a UTF-
2d900 31 36 20 73 74 72 69 6e 67 20 66 6f 72 20 73 71  16 string for sq
2d910 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
2d920 6c 61 74 69 6f 6e 31 36 28 29 2e 20 49 6e 20 61  lation16(). In a
2d930 6c 6c 20 63 61 73 65 73 0a 2a 2a 20 74 68 65 20  ll cases.** the 
2d940 6e 61 6d 65 20 69 73 20 70 61 73 73 65 64 20 61  name is passed a
2d950 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e  s the second fun
2d960 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a  ction argument..
2d970 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20  **.** The third 
2d980 61 72 67 75 6d 65 6e 74 20 6d 61 79 20 62 65 20  argument may be 
2d990 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e 73 74  one of the const
2d9a0 61 6e 74 73 20 5b 53 51 4c 49 54 45 5f 55 54 46  ants [SQLITE_UTF
2d9b0 38 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55  8],.** [SQLITE_U
2d9c0 54 46 31 36 4c 45 5d 20 6f 72 20 5b 53 51 4c 49  TF16LE] or [SQLI
2d9d0 54 45 5f 55 54 46 31 36 42 45 5d 2c 20 69 6e 64  TE_UTF16BE], ind
2d9e0 69 63 61 74 69 6e 67 20 74 68 61 74 20 74 68 65  icating that the
2d9f0 20 75 73 65 72 2d 73 75 70 70 6c 69 65 64 0a 2a   user-supplied.*
2da00 2a 20 72 6f 75 74 69 6e 65 20 65 78 70 65 63 74  * routine expect
2da10 73 20 74 6f 20 62 65 20 70 61 73 73 65 64 20 70  s to be passed p
2da20 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e  ointers to strin
2da30 67 73 20 65 6e 63 6f 64 65 64 20 75 73 69 6e 67  gs encoded using
2da40 20 55 54 46 2d 38 2c 0a 2a 2a 20 55 54 46 2d 31   UTF-8,.** UTF-1
2da50 36 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20  6 little-endian 
2da60 6f 72 20 55 54 46 2d 31 36 20 62 69 67 2d 65 6e  or UTF-16 big-en
2da70 64 69 61 6e 20 72 65 73 70 65 63 74 69 76 65 6c  dian respectivel
2da80 79 2e 20 54 68 65 0a 2a 2a 20 74 68 69 72 64 20  y. The.** third 
2da90 61 72 67 75 6d 65 6e 74 20 6d 69 67 68 74 20 61  argument might a
2daa0 6c 73 6f 20 62 65 20 5b 53 51 4c 49 54 45 5f 55  lso be [SQLITE_U
2dab0 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 74 6f  TF16_ALIGNED] to
2dac0 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 0a 2a   indicate that.*
2dad0 2a 20 74 68 65 20 72 6f 75 74 69 6e 65 20 65 78  * the routine ex
2dae0 70 65 63 74 73 20 70 6f 69 6e 74 65 72 73 20 74  pects pointers t
2daf0 6f 20 31 36 2d 62 69 74 20 77 6f 72 64 20 61 6c  o 16-bit word al
2db00 69 67 6e 65 64 20 73 74 72 69 6e 67 73 0a 2a 2a  igned strings.**
2db10 20 6f 66 20 55 54 46 31 36 20 69 6e 20 74 68 65   of UTF16 in the
2db20 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
2db30 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20 63  er of the host c
2db40 6f 6d 70 75 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41  omputer..**.** A
2db50 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
2db60 75 73 65 72 20 73 75 70 70 6c 69 65 64 20 72 6f  user supplied ro
2db70 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 70 61  utine must be pa
2db80 73 73 65 64 20 61 73 20 74 68 65 20 66 69 66 74  ssed as the fift
2db90 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20 20  h.** argument.  
2dba0 49 66 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20 74  If it is NULL, t
2dbb0 68 69 73 20 69 73 20 74 68 65 20 73 61 6d 65 20  his is the same 
2dbc0 61 73 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20  as deleting the 
2dbd0 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71  collation.** seq
2dbe0 75 65 6e 63 65 20 28 73 6f 20 74 68 61 74 20 53  uence (so that S
2dbf0 51 4c 69 74 65 20 63 61 6e 6e 6f 74 20 63 61 6c  QLite cannot cal
2dc00 6c 20 69 74 20 61 6e 79 6d 6f 72 65 29 2e 0a 2a  l it anymore)..*
2dc10 2a 20 45 61 63 68 20 74 69 6d 65 20 74 68 65 20  * Each time the 
2dc20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 73  application.** s
2dc30 75 70 70 6c 69 65 64 20 66 75 6e 63 74 69 6f 6e  upplied function
2dc40 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74 20   is invoked, it 
2dc50 69 73 20 70 61 73 73 65 64 20 61 20 63 6f 70 79  is passed a copy
2dc60 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70 61   of the void* pa
2dc70 73 73 65 64 20 61 73 0a 2a 2a 20 74 68 65 20 66  ssed as.** the f
2dc80 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74  ourth argument t
2dc90 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  o sqlite3_create
2dca0 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 6f 72 0a  _collation() or.
2dcb0 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  ** sqlite3_creat
2dcc0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 20  e_collation16() 
2dcd0 61 73 20 69 74 73 20 66 69 72 73 74 20 70 61 72  as its first par
2dce0 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  ameter..**.** Th
2dcf0 65 20 72 65 6d 61 69 6e 69 6e 67 20 61 72 67 75  e remaining argu
2dd00 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 61 70 70  ments to the app
2dd10 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65  lication-supplie
2dd20 64 20 72 6f 75 74 69 6e 65 20 61 72 65 20 74 77  d routine are tw
2dd30 6f 20 73 74 72 69 6e 67 73 2c 0a 2a 2a 20 65 61  o strings,.** ea
2dd40 63 68 20 72 65 70 72 65 73 65 6e 74 65 64 20 62  ch represented b
2dd50 79 20 61 20 28 6c 65 6e 67 74 68 2c 20 64 61 74  y a (length, dat
2dd60 61 29 20 70 61 69 72 20 61 6e 64 20 65 6e 63 6f  a) pair and enco
2dd70 64 65 64 20 69 6e 20 74 68 65 20 65 6e 63 6f 64  ded in the encod
2dd80 69 6e 67 0a 2a 2a 20 74 68 61 74 20 77 61 73 20  ing.** that was 
2dd90 70 61 73 73 65 64 20 61 73 20 74 68 65 20 74 68  passed as the th
2dda0 69 72 64 20 61 72 67 75 6d 65 6e 74 20 77 68 65  ird argument whe
2ddb0 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20  n the collation 
2ddc0 73 65 71 75 65 6e 63 65 20 77 61 73 0a 2a 2a 20  sequence was.** 
2ddd0 72 65 67 69 73 74 65 72 65 64 2e 20 7b 45 4e 44  registered. {END
2dde0 7d 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  } The applicatio
2ddf0 6e 20 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74  n defined collat
2de00 69 6f 6e 20 72 6f 75 74 69 6e 65 20 73 68 6f 75  ion routine shou
2de10 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 6e 65 67  ld.** return neg
2de20 61 74 69 76 65 2c 20 7a 65 72 6f 20 6f 72 20 70  ative, zero or p
2de30 6f 73 69 74 69 76 65 20 69 66 0a 2a 2a 20 74 68  ositive if.** th
2de40 65 20 66 69 72 73 74 20 73 74 72 69 6e 67 20 69  e first string i
2de50 73 20 6c 65 73 73 20 74 68 61 6e 2c 20 65 71 75  s less than, equ
2de60 61 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61 74 65  al to, or greate
2de70 72 20 74 68 61 6e 20 74 68 65 20 73 65 63 6f 6e  r than the secon
2de80 64 0a 2a 2a 20 73 74 72 69 6e 67 2e 20 69 2e 65  d.** string. i.e
2de90 2e 20 28 53 54 52 49 4e 47 31 20 2d 20 53 54 52  . (STRING1 - STR
2dea0 49 4e 47 32 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ING2)..**.** The
2deb0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2dec0 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77  collation_v2() w
2ded0 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65  orks like sqlite
2dee0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
2def0 6f 6e 28 29 0a 2a 2a 20 65 78 63 61 70 74 20 74  on().** excapt t
2df00 68 61 74 20 69 74 20 74 61 6b 65 73 20 61 6e 20  hat it takes an 
2df10 65 78 74 72 61 20 61 72 67 75 6d 65 6e 74 20 77  extra argument w
2df20 68 69 63 68 20 69 73 20 61 20 64 65 73 74 72 75  hich is a destru
2df30 63 74 6f 72 20 66 6f 72 0a 2a 2a 20 74 68 65 20  ctor for.** the 
2df40 63 6f 6c 6c 61 74 69 6f 6e 2e 20 20 54 68 65 20  collation.  The 
2df50 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 63 61  destructor is ca
2df60 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20 63 6f  lled when the co
2df70 6c 6c 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 65  llation is.** de
2df80 73 74 72 6f 79 65 64 20 61 6e 64 20 69 73 20 70  stroyed and is p
2df90 61 73 73 65 64 20 61 20 63 6f 70 79 20 6f 66 20  assed a copy of 
2dfa0 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
2dfb0 65 74 65 72 20 76 6f 69 64 2a 20 70 6f 69 6e 74  eter void* point
2dfc0 65 72 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c  er.** of the sql
2dfd0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
2dfe0 61 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 20 43  ation_v2()..** C
2dff0 6f 6c 6c 61 74 69 6f 6e 73 20 61 72 65 20 64 65  ollations are de
2e000 73 74 72 6f 79 65 64 20 77 68 65 6e 0a 2a 2a 20  stroyed when.** 
2e010 74 68 65 79 20 61 72 65 20 6f 76 65 72 72 69 64  they are overrid
2e020 64 65 6e 20 62 79 20 6c 61 74 65 72 20 63 61 6c  den by later cal
2e030 6c 73 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74  ls to the collat
2e040 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 66 75 6e  ion creation fun
2e050 63 74 69 6f 6e 73 0a 2a 2a 20 6f 72 20 77 68 65  ctions.** or whe
2e060 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 2a 5d  n the [sqlite3*]
2e070 20 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   database handle
2e080 20 69 73 20 63 6c 6f 73 65 64 20 75 73 69 6e 67   is closed using
2e090 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
2e0a0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  )]..**.** INVARI
2e0b0 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  ANTS:.**.** {F16
2e0c0 36 30 33 7d 20 41 20 73 75 63 63 65 73 73 66 75  603} A successfu
2e0d0 6c 20 63 61 6c 6c 20 74 6f 20 74 68 65 0a 2a 2a  l call to the.**
2e0e0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
2e0f0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
2e100 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46  ion_v2(B,X,E,P,F
2e110 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a  ,D)] interface.*
2e120 2a 20 20 20 20 20 20 20 20 20 20 72 65 67 69 73  *          regis
2e130 74 65 72 73 20 66 75 6e 63 74 69 6f 6e 20 46 20  ters function F 
2e140 61 73 20 74 68 65 20 63 6f 6d 70 61 72 69 73 6f  as the compariso
2e150 6e 20 66 75 6e 63 74 69 6f 6e 20 75 73 65 64 20  n function used 
2e160 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  to.**          i
2e170 6d 70 6c 65 6d 65 6e 74 20 63 6f 6c 6c 61 74 69  mplement collati
2e180 6f 6e 20 58 20 6f 6e 20 5b 64 61 74 61 62 61 73  on X on [databas
2e190 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 42 20  e connection] B 
2e1a0 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  for.**          
2e1b0 64 61 74 61 62 61 73 65 73 20 68 61 76 69 6e 67  databases having
2e1c0 20 65 6e 63 6f 64 69 6e 67 20 45 2e 0a 2a 2a 0a   encoding E..**.
2e1d0 2a 2a 20 7b 46 31 36 36 30 34 7d 20 53 51 4c 69  ** {F16604} SQLi
2e1e0 74 65 20 75 6e 64 65 72 73 74 61 6e 64 73 20 74  te understands t
2e1f0 68 65 20 58 20 70 61 72 61 6d 65 74 65 72 20 74  he X parameter t
2e200 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  o.**          [s
2e210 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
2e220 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45  llation_v2(B,X,E
2e230 2c 50 2c 46 2c 44 29 5d 20 61 73 20 61 20 7a 65  ,P,F,D)] as a ze
2e240 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
2e250 20 20 20 20 20 20 20 20 20 20 55 54 46 2d 38 20            UTF-8 
2e260 73 74 72 69 6e 67 20 69 6e 20 77 68 69 63 68 20  string in which 
2e270 63 61 73 65 20 69 73 20 69 67 6e 6f 72 65 64 20  case is ignored 
2e280 66 6f 72 20 41 53 43 49 49 20 63 68 61 72 61 63  for ASCII charac
2e290 74 65 72 73 20 61 6e 64 0a 2a 2a 20 20 20 20 20  ters and.**     
2e2a0 20 20 20 20 20 69 73 20 73 69 67 6e 69 66 69 63       is signific
2e2b0 61 6e 74 20 66 6f 72 20 6e 6f 6e 2d 41 53 43 49  ant for non-ASCI
2e2c0 49 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a  I characters..**
2e2d0 0a 2a 2a 20 7b 46 31 36 36 30 36 7d 20 53 75 63  .** {F16606} Suc
2e2e0 63 65 73 73 69 76 65 20 63 61 6c 6c 73 20 74 6f  cessive calls to
2e2f0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2e300 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c  _collation_v2(B,
2e310 58 2c 45 2c 50 2c 46 2c 44 29 5d 0a 2a 2a 20 20  X,E,P,F,D)].**  
2e320 20 20 20 20 20 20 20 20 77 69 74 68 20 74 68 65          with the
2e330 20 73 61 6d 65 20 76 61 6c 75 65 73 20 66 6f 72   same values for
2e340 20 42 2c 20 58 2c 20 61 6e 64 20 45 2c 20 6f 76   B, X, and E, ov
2e350 65 72 72 69 64 65 20 70 72 69 6f 72 20 76 61 6c  erride prior val
2e360 75 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ues.**          
2e370 6f 66 20 50 2c 20 46 2c 20 61 6e 64 20 44 2e 0a  of P, F, and D..
2e380 2a 2a 0a 2a 2a 20 7b 46 31 36 36 30 39 7d 20 54  **.** {F16609} T
2e390 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 44 20  he destructor D 
2e3a0 69 6e 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  in [sqlite3_crea
2e3b0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
2e3c0 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 0a 2a 2a  B,X,E,P,F,D)].**
2e3d0 20 20 20 20 20 20 20 20 20 20 69 73 20 6e 6f 74            is not
2e3e0 20 4e 55 4c 4c 20 74 68 65 6e 20 69 74 20 69 73   NULL then it is
2e3f0 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 72 67   called with arg
2e400 75 6d 65 6e 74 20 50 20 77 68 65 6e 20 74 68 65  ument P when the
2e410 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6c  .**          col
2e420 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
2e430 69 73 20 64 72 6f 70 70 65 64 20 62 79 20 53 51  is dropped by SQ
2e440 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  Lite..**.** {F16
2e450 36 31 32 7d 20 41 20 63 6f 6c 6c 61 74 69 6e 67  612} A collating
2e460 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 72 6f   function is dro
2e470 70 70 65 64 20 77 68 65 6e 20 69 74 20 69 73 20  pped when it is 
2e480 6f 76 65 72 6c 6f 61 64 65 64 2e 0a 2a 2a 0a 2a  overloaded..**.*
2e490 2a 20 7b 46 31 36 36 31 35 7d 20 41 20 63 6f 6c  * {F16615} A col
2e4a0 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
2e4b0 69 73 20 64 72 6f 70 70 65 64 20 77 68 65 6e 20  is dropped when 
2e4c0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
2e4d0 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20  nection.**      
2e4e0 20 20 20 20 69 73 20 63 6c 6f 73 65 64 20 75 73      is closed us
2e4f0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f  ing [sqlite3_clo
2e500 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  se()]..**.** {F1
2e510 36 36 31 38 7d 20 54 68 65 20 70 6f 69 6e 74 65  6618} The pointe
2e520 72 20 50 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f  r P in [sqlite3_
2e530 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
2e540 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29  _v2(B,X,E,P,F,D)
2e550 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73  ].**          is
2e560 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20   passed through 
2e570 61 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72  as the first par
2e580 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f  ameter to the co
2e590 6d 70 61 72 69 73 6f 6e 0a 2a 2a 20 20 20 20 20  mparison.**     
2e5a0 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 20 46 20       function F 
2e5b0 66 6f 72 20 61 6c 6c 20 73 75 62 73 65 71 75 65  for all subseque
2e5c0 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f  nt invocations o
2e5d0 66 20 46 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36  f F..**.** {F166
2e5e0 32 31 7d 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73  21} A call to [s
2e5f0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
2e600 6c 6c 61 74 69 6f 6e 28 42 2c 58 2c 45 2c 50 2c  llation(B,X,E,P,
2e610 46 29 5d 20 69 73 20 65 78 61 63 74 6c 79 0a 2a  F)] is exactly.*
2e620 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 73  *          the s
2e630 61 6d 65 20 61 73 20 61 20 63 61 6c 6c 20 74 6f  ame as a call to
2e640 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2e650 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d  _collation_v2()]
2e660 20 77 69 74 68 0a 2a 2a 20 20 20 20 20 20 20 20   with.**        
2e670 20 20 74 68 65 20 73 61 6d 65 20 70 61 72 61 6d    the same param
2e680 65 74 65 72 73 20 61 6e 64 20 61 20 4e 55 4c 4c  eters and a NULL
2e690 20 64 65 73 74 72 75 63 74 6f 72 2e 0a 2a 2a 0a   destructor..**.
2e6a0 2a 2a 20 7b 46 31 36 36 32 34 7d 20 46 6f 6c 6c  ** {F16624} Foll
2e6b0 6f 77 69 6e 67 20 61 20 5b 73 71 6c 69 74 65 33  owing a [sqlite3
2e6c0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
2e6d0 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44  n_v2(B,X,E,P,F,D
2e6e0 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  )],.**          
2e6f0 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20  SQLite uses the 
2e700 63 6f 6d 70 61 72 69 73 6f 6e 20 66 75 6e 63 74  comparison funct
2e710 69 6f 6e 20 46 20 66 6f 72 20 61 6c 6c 20 74 65  ion F for all te
2e720 78 74 20 63 6f 6d 70 61 72 69 73 6f 6e 0a 2a 2a  xt comparison.**
2e730 20 20 20 20 20 20 20 20 20 20 6f 70 65 72 61 74            operat
2e740 69 6f 6e 73 20 6f 6e 20 5b 64 61 74 61 62 61 73  ions on [databas
2e750 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 42 20  e connection] B 
2e760 6f 6e 20 74 65 78 74 20 76 61 6c 75 65 73 20 74  on text values t
2e770 68 61 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  hat.**          
2e780 75 73 65 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e  use the collatin
2e790 67 20 73 65 71 75 65 6e 63 65 20 6e 61 6d 65 20  g sequence name 
2e7a0 58 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36 32 37  X..**.** {F16627
2e7b0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
2e7c0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31  reate_collation1
2e7d0 36 28 42 2c 58 2c 45 2c 50 2c 46 29 5d 20 77 6f  6(B,X,E,P,F)] wo
2e7e0 72 6b 73 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20  rks the same.** 
2e7f0 20 20 20 20 20 20 20 20 20 61 73 20 5b 73 71 6c           as [sql
2e800 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
2e810 61 74 69 6f 6e 28 42 2c 58 2c 45 2c 50 2c 46 29  ation(B,X,E,P,F)
2e820 5d 20 65 78 63 65 70 74 20 74 68 61 74 20 74 68  ] except that th
2e830 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f  e.**          co
2e840 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 20 58 20 69  llation name X i
2e850 73 20 75 6e 64 65 72 73 74 6f 6f 64 20 61 73 20  s understood as 
2e860 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65  UTF-16 in native
2e870 20 62 79 74 65 20 6f 72 64 65 72 0a 2a 2a 20 20   byte order.**  
2e880 20 20 20 20 20 20 20 20 69 6e 73 74 65 61 64 20          instead 
2e890 6f 66 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20  of UTF-8..**.** 
2e8a0 7b 46 31 36 36 33 30 7d 20 57 68 65 6e 20 6d 75  {F16630} When mu
2e8b0 6c 74 69 70 6c 65 20 63 6f 6d 70 61 72 69 73 6f  ltiple compariso
2e8c0 6e 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20  n functions are 
2e8d0 61 76 61 69 6c 61 62 6c 65 20 66 6f 72 20 74 68  available for th
2e8e0 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20  e same.**       
2e8f0 20 20 20 63 6f 6c 6c 61 74 69 6e 67 20 73 65 71     collating seq
2e900 75 65 6e 63 65 2c 20 53 51 4c 69 74 65 20 63 68  uence, SQLite ch
2e910 6f 6f 73 65 73 20 74 68 65 20 6f 6e 65 20 77 68  ooses the one wh
2e920 6f 73 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  ose text encodin
2e930 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  g.**          re
2e940 71 75 69 72 65 73 20 74 68 65 20 6c 65 61 73 74  quires the least
2e950 20 61 6d 6f 75 6e 74 20 6f 66 20 63 6f 6e 76 65   amount of conve
2e960 72 73 69 6f 6e 20 66 72 6f 6d 20 74 68 65 20 64  rsion from the d
2e970 65 66 61 75 6c 74 0a 2a 2a 20 20 20 20 20 20 20  efault.**       
2e980 20 20 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67     text encoding
2e990 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
2e9a0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2e9b0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
2e9c0 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  n(.  sqlite3*, .
2e9d0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e    const char *zN
2e9e0 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78  ame, .  int eTex
2e9f0 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a  tRep, .  void*,.
2ea00 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29    int(*xCompare)
2ea10 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
2ea20 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74   void*,int,const
2ea30 20 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73   void*).);.int s
2ea40 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
2ea50 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71  llation_v2(.  sq
2ea60 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74  lite3*, .  const
2ea70 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20   char *zName, . 
2ea80 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a   int eTextRep, .
2ea90 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a    void*,.  int(*
2eaa0 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c  xCompare)(void*,
2eab0 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  int,const void*,
2eac0 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29  int,const void*)
2ead0 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72  ,.  void(*xDestr
2eae0 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e  oy)(void*).);.in
2eaf0 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
2eb00 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a 20 20  _collation16(.  
2eb10 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e  sqlite3*, .  con
2eb20 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
2eb30 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
2eb40 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74   .  void*,.  int
2eb50 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64  (*xCompare)(void
2eb60 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
2eb70 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
2eb80 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  *).);../*.** CAP
2eb90 49 33 52 45 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e  I3REF: Collation
2eba0 20 4e 65 65 64 65 64 20 43 61 6c 6c 62 61 63 6b   Needed Callback
2ebb0 73 20 7b 46 31 36 37 30 30 7d 0a 2a 2a 0a 2a 2a  s {F16700}.**.**
2ebc0 20 54 6f 20 61 76 6f 69 64 20 68 61 76 69 6e 67   To avoid having
2ebd0 20 74 6f 20 72 65 67 69 73 74 65 72 20 61 6c 6c   to register all
2ebe0 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
2ebf0 6e 63 65 73 20 62 65 66 6f 72 65 20 61 20 64 61  nces before a da
2ec00 74 61 62 61 73 65 0a 2a 2a 20 63 61 6e 20 62 65  tabase.** can be
2ec10 20 75 73 65 64 2c 20 61 20 73 69 6e 67 6c 65 20   used, a single 
2ec20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
2ec30 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73 74 65  n may be registe
2ec40 72 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  red with the.** 
2ec50 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  database handle 
2ec60 74 6f 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65  to be called whe
2ec70 6e 65 76 65 72 20 61 6e 20 75 6e 64 65 66 69 6e  never an undefin
2ec80 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  ed collation seq
2ec90 75 65 6e 63 65 20 69 73 0a 2a 2a 20 72 65 71 75  uence is.** requ
2eca0 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  ired..**.** If t
2ecb0 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  he function is r
2ecc0 65 67 69 73 74 65 72 65 64 20 75 73 69 6e 67 20  egistered using 
2ecd0 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  the sqlite3_coll
2ece0 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 41  ation_needed() A
2ecf0 50 49 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69  PI,.** then it i
2ed00 73 20 70 61 73 73 65 64 20 74 68 65 20 6e 61 6d  s passed the nam
2ed10 65 73 20 6f 66 20 75 6e 64 65 66 69 6e 65 64 20  es of undefined 
2ed20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
2ed30 63 65 73 20 61 73 20 73 74 72 69 6e 67 73 0a 2a  ces as strings.*
2ed40 2a 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54 46  * encoded in UTF
2ed50 2d 38 2e 20 7b 46 31 36 37 30 33 7d 20 49 66 20  -8. {F16703} If 
2ed60 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
2ed70 6e 5f 6e 65 65 64 65 64 31 36 28 29 20 69 73 20  n_needed16() is 
2ed80 75 73 65 64 2c 20 74 68 65 20 6e 61 6d 65 73 0a  used, the names.
2ed90 2a 2a 20 61 72 65 20 70 61 73 73 65 64 20 61 73  ** are passed as
2eda0 20 55 54 46 2d 31 36 20 69 6e 20 6d 61 63 68 69   UTF-16 in machi
2edb0 6e 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  ne native byte o
2edc0 72 64 65 72 2e 20 41 20 63 61 6c 6c 20 74 6f 20  rder. A call to 
2edd0 65 69 74 68 65 72 0a 2a 2a 20 66 75 6e 63 74 69  either.** functi
2ede0 6f 6e 20 72 65 70 6c 61 63 65 73 20 61 6e 79 20  on replaces any 
2edf0 65 78 69 73 74 69 6e 67 20 63 61 6c 6c 62 61 63  existing callbac
2ee00 6b 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  k..**.** When th
2ee10 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  e callback is in
2ee20 76 6f 6b 65 64 2c 20 74 68 65 20 66 69 72 73 74  voked, the first
2ee30 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64   argument passed
2ee40 20 69 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66   is a copy.** of
2ee50 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
2ee60 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
2ee70 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
2ee80 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  () or.** sqlite3
2ee90 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
2eea0 64 31 36 28 29 2e 20 20 54 68 65 20 73 65 63 6f  d16().  The seco
2eeb0 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  nd argument is t
2eec0 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 68  he database.** h
2eed0 61 6e 64 6c 65 2e 20 20 54 68 65 20 74 68 69 72  andle.  The thir
2eee0 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e  d argument is on
2eef0 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54 46  e of [SQLITE_UTF
2ef00 38 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55  8],.** [SQLITE_U
2ef10 54 46 31 36 42 45 5d 2c 20 6f 72 20 5b 53 51 4c  TF16BE], or [SQL
2ef20 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20 69 6e  ITE_UTF16LE], in
2ef30 64 69 63 61 74 69 6e 67 20 74 68 65 20 6d 6f 73  dicating the mos
2ef40 74 0a 2a 2a 20 64 65 73 69 72 61 62 6c 65 20 66  t.** desirable f
2ef50 6f 72 6d 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61  orm of the colla
2ef60 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 66 75  tion sequence fu
2ef70 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 64 2e  nction required.
2ef80 0a 2a 2a 20 54 68 65 20 66 6f 75 72 74 68 20 70  .** The fourth p
2ef90 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
2efa0 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 72  name of the.** r
2efb0 65 71 75 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f  equired collatio
2efc0 6e 20 73 65 71 75 65 6e 63 65 2e 0a 2a 2a 0a 2a  n sequence..**.*
2efd0 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66  * The callback f
2efe0 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 72  unction should r
2eff0 65 67 69 73 74 65 72 20 74 68 65 20 64 65 73 69  egister the desi
2f000 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 75 73  red collation us
2f010 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
2f020 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
2f030 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72  ()], [sqlite3_cr
2f040 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36  eate_collation16
2f050 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
2f060 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
2f070 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a  tion_v2()]..**.*
2f080 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
2f090 0a 2a 2a 20 7b 46 31 36 37 30 32 7d 20 41 20 73  .** {F16702} A s
2f0a0 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74  uccessful call t
2f0b0 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  o [sqlite3_colla
2f0c0 74 69 6f 6e 5f 6e 65 65 64 65 64 28 44 2c 50 2c  tion_needed(D,P,
2f0d0 46 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  F)].**          
2f0e0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  or [sqlite3_coll
2f0f0 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 44  ation_needed16(D
2f100 2c 50 2c 46 29 5d 20 63 61 75 73 65 73 0a 2a 2a  ,P,F)] causes.**
2f110 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 64            the [d
2f120 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2f130 6f 6e 5d 20 44 20 74 6f 20 69 6e 76 6f 6b 65 20  on] D to invoke 
2f140 63 61 6c 6c 62 61 63 6b 20 46 20 77 69 74 68 20  callback F with 
2f150 66 69 72 73 74 0a 2a 2a 20 20 20 20 20 20 20 20  first.**        
2f160 20 20 70 61 72 61 6d 65 74 65 72 20 50 20 77 68    parameter P wh
2f170 65 6e 65 76 65 72 20 69 74 20 6e 65 65 64 73 20  enever it needs 
2f180 61 20 63 6f 6d 70 61 72 69 73 6f 6e 20 66 75 6e  a comparison fun
2f190 63 74 69 6f 6e 20 66 6f 72 20 61 0a 2a 2a 20 20  ction for a.**  
2f1a0 20 20 20 20 20 20 20 20 63 6f 6c 6c 61 74 69 6e          collatin
2f1b0 67 20 73 65 71 75 65 6e 63 65 20 74 68 61 74 20  g sequence that 
2f1c0 69 74 20 64 6f 65 73 20 6e 6f 74 20 6b 6e 6f 77  it does not know
2f1d0 20 61 62 6f 75 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46   about..**.** {F
2f1e0 31 36 37 30 34 7d 20 45 61 63 68 20 73 75 63 63  16704} Each succ
2f1f0 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b  essful call to [
2f200 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
2f210 6e 5f 6e 65 65 64 65 64 28 29 5d 20 6f 72 0a 2a  n_needed()] or.*
2f220 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
2f230 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
2f240 65 64 65 64 31 36 28 29 5d 20 6f 76 65 72 72 69  eded16()] overri
2f250 64 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  des the callback
2f260 20 72 65 67 69 73 74 65 72 65 64 0a 2a 2a 20 20   registered.**  
2f270 20 20 20 20 20 20 20 20 6f 6e 20 74 68 65 20 73          on the s
2f280 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ame [database co
2f290 6e 6e 65 63 74 69 6f 6e 5d 20 62 79 20 70 72 69  nnection] by pri
2f2a0 6f 72 20 63 61 6c 6c 73 20 74 6f 20 65 69 74 68  or calls to eith
2f2b0 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  er.**          i
2f2c0 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
2f2d0 7b 46 31 36 37 30 36 7d 20 54 68 65 20 6e 61 6d  {F16706} The nam
2f2e0 65 20 6f 66 20 74 68 65 20 72 65 71 75 65 73 74  e of the request
2f2f0 65 64 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  ed collating fun
2f300 63 74 69 6f 6e 20 70 61 73 73 65 64 20 69 6e 20  ction passed in 
2f310 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
2f320 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
2f330 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
2f340 20 69 6e 20 55 54 46 2d 38 20 69 66 20 74 68 65   in UTF-8 if the
2f350 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20   callback.**    
2f360 20 20 20 20 20 20 77 61 73 20 72 65 67 69 73 74        was regist
2f370 65 72 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  ered using [sqli
2f380 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
2f390 65 64 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 20  eded()] and.**  
2f3a0 20 20 20 20 20 20 20 20 69 73 20 69 6e 20 55 54          is in UT
2f3b0 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65  F-16 native byte
2f3c0 20 6f 72 64 65 72 20 69 66 20 74 68 65 20 63 61   order if the ca
2f3d0 6c 6c 62 61 63 6b 20 77 61 73 0a 2a 2a 20 20 20  llback was.**   
2f3e0 20 20 20 20 20 20 20 72 65 67 69 73 74 65 72 65         registere
2f3f0 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
2f400 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
2f410 64 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 0a 2a  d16()]..**.** .*
2f420 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  /.int sqlite3_co
2f430 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 0a  llation_needed(.
2f440 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76    sqlite3*, .  v
2f450 6f 69 64 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29  oid*, .  void(*)
2f460 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c  (void*,sqlite3*,
2f470 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e  int eTextRep,con
2f480 73 74 20 63 68 61 72 2a 29 0a 29 3b 0a 69 6e 74  st char*).);.int
2f490 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
2f4a0 6f 6e 5f 6e 65 65 64 65 64 31 36 28 0a 20 20 73  on_needed16(.  s
2f4b0 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64  qlite3*, .  void
2f4c0 2a 2c 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69  *,.  void(*)(voi
2f4d0 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20  d*,sqlite3*,int 
2f4e0 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 76  eTextRep,const v
2f4f0 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  oid*).);../*.** 
2f500 53 70 65 63 69 66 79 20 74 68 65 20 6b 65 79 20  Specify the key 
2f510 66 6f 72 20 61 6e 20 65 6e 63 72 79 70 74 65 64  for an encrypted
2f520 20 64 61 74 61 62 61 73 65 2e 20 20 54 68 69 73   database.  This
2f530 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 20   routine should 
2f540 62 65 0a 2a 2a 20 63 61 6c 6c 65 64 20 72 69 67  be.** called rig
2f550 68 74 20 61 66 74 65 72 20 73 71 6c 69 74 65 33  ht after sqlite3
2f560 5f 6f 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 54  _open()..**.** T
2f570 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65  he code to imple
2f580 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20 69 73  ment this API is
2f590 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69   not available i
2f5a0 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c  n the public rel
2f5b0 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74  ease.** of SQLit
2f5c0 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  e..*/.int sqlite
2f5d0 33 5f 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33  3_key(.  sqlite3
2f5e0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
2f5f0 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
2f600 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65  ase to be rekeye
2f610 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  d */.  const voi
2f620 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65  d *pKey, int nKe
2f630 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6b 65 79  y     /* The key
2f640 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68   */.);../*.** Ch
2f650 61 6e 67 65 20 74 68 65 20 6b 65 79 20 6f 6e 20  ange the key on 
2f660 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65  an open database
2f670 2e 20 20 49 66 20 74 68 65 20 63 75 72 72 65 6e  .  If the curren
2f680 74 20 64 61 74 61 62 61 73 65 20 69 73 20 6e 6f  t database is no
2f690 74 0a 2a 2a 20 65 6e 63 72 79 70 74 65 64 2c 20  t.** encrypted, 
2f6a0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c  this routine wil
2f6b0 6c 20 65 6e 63 72 79 70 74 20 69 74 2e 20 20 49  l encrypt it.  I
2f6c0 66 20 70 4e 65 77 3d 3d 30 20 6f 72 20 6e 4e 65  f pNew==0 or nNe
2f6d0 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a 20 64 61 74  w==0, the.** dat
2f6e0 61 62 61 73 65 20 69 73 20 64 65 63 72 79 70 74  abase is decrypt
2f6f0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  ed..**.** The co
2f700 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  de to implement 
2f710 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20  this API is not 
2f720 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65  available in the
2f730 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a   public release.
2f740 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f  ** of SQLite..*/
2f750 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6b  .int sqlite3_rek
2f760 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  ey(.  sqlite3 *d
2f770 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  b,              
2f780 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
2f790 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a   to be rekeyed *
2f7a0 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
2f7b0 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20  pKey, int nKey  
2f7c0 20 20 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b 65     /* The new ke
2f7d0 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  y */.);../*.** C
2f7e0 41 50 49 33 52 45 46 3a 20 20 53 75 73 70 65 6e  API3REF:  Suspen
2f7f0 64 20 45 78 65 63 75 74 69 6f 6e 20 46 6f 72 20  d Execution For 
2f800 41 20 53 68 6f 72 74 20 54 69 6d 65 20 7b 46 31  A Short Time {F1
2f810 30 35 33 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20  0530}.**.** The 
2f820 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 29 20  sqlite3_sleep() 
2f830 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 75 73  function.** caus
2f840 65 73 20 74 68 65 20 63 75 72 72 65 6e 74 20 74  es the current t
2f850 68 72 65 61 64 20 74 6f 20 73 75 73 70 65 6e 64  hread to suspend
2f860 20 65 78 65 63 75 74 69 6f 6e 0a 2a 2a 20 66 6f   execution.** fo
2f870 72 20 61 74 20 6c 65 61 73 74 20 61 20 6e 75 6d  r at least a num
2f880 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f  ber of milliseco
2f890 6e 64 73 20 73 70 65 63 69 66 69 65 64 20 69 6e  nds specified in
2f8a0 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 2e 0a   its parameter..
2f8b0 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70 65  **.** If the ope
2f8c0 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 64 6f  rating system do
2f8d0 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 73  es not support s
2f8e0 6c 65 65 70 20 72 65 71 75 65 73 74 73 20 77 69  leep requests wi
2f8f0 74 68 20 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f  th .** milliseco
2f900 6e 64 20 74 69 6d 65 20 72 65 73 6f 6c 75 74 69  nd time resoluti
2f910 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 74 69 6d  on, then the tim
2f920 65 20 77 69 6c 6c 20 62 65 20 72 6f 75 6e 64 65  e will be rounde
2f930 64 20 75 70 20 74 6f 20 0a 2a 2a 20 74 68 65 20  d up to .** the 
2f940 6e 65 61 72 65 73 74 20 73 65 63 6f 6e 64 2e 20  nearest second. 
2f950 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69  The number of mi
2f960 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c  lliseconds of sl
2f970 65 65 70 20 61 63 74 75 61 6c 6c 79 20 0a 2a 2a  eep actually .**
2f980 20 72 65 71 75 65 73 74 65 64 20 66 72 6f 6d 20   requested from 
2f990 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
2f9a0 73 74 65 6d 20 69 73 20 72 65 74 75 72 6e 65 64  stem is returned
2f9b0 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69  ..**.** SQLite i
2f9c0 6d 70 6c 65 6d 65 6e 74 73 20 74 68 69 73 20 69  mplements this i
2f9d0 6e 74 65 72 66 61 63 65 20 62 79 20 63 61 6c 6c  nterface by call
2f9e0 69 6e 67 20 74 68 65 20 78 53 6c 65 65 70 28 29  ing the xSleep()
2f9f0 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20 74 68  .** method of th
2fa00 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  e default [sqlit
2fa10 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a  e3_vfs] object..
2fa20 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
2fa30 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 35 33 33 7d  :.**.** {F10533}
2fa40 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 6c   The [sqlite3_sl
2fa50 65 65 70 28 4d 29 5d 20 69 6e 74 65 72 66 61 63  eep(M)] interfac
2fa60 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 78 53  e invokes the xS
2fa70 6c 65 65 70 0a 2a 2a 20 20 20 20 20 20 20 20 20  leep.**         
2fa80 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64   method of the d
2fa90 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f  efault [sqlite3_
2faa0 76 66 73 7c 56 46 53 5d 20 69 6e 20 6f 72 64 65  vfs|VFS] in orde
2fab0 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20  r to.**         
2fac0 20 73 75 73 70 65 6e 64 20 65 78 65 63 75 74 69   suspend executi
2fad0 6f 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e  on of the curren
2fae0 74 20 74 68 72 65 61 64 20 66 6f 72 20 61 74 20  t thread for at 
2faf0 6c 65 61 73 74 0a 2a 2a 20 20 20 20 20 20 20 20  least.**        
2fb00 20 20 4d 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73    M milliseconds
2fb10 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 35 33 36 7d  ..**.** {F10536}
2fb20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 6c   The [sqlite3_sl
2fb30 65 65 70 28 4d 29 5d 20 69 6e 74 65 72 66 61 63  eep(M)] interfac
2fb40 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
2fb50 6d 62 65 72 20 6f 66 0a 2a 2a 20 20 20 20 20 20  mber of.**      
2fb60 20 20 20 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73      milliseconds
2fb70 20 6f 66 20 73 6c 65 65 70 20 61 63 74 75 61 6c   of sleep actual
2fb80 6c 79 20 72 65 71 75 65 73 74 65 64 20 6f 66 20  ly requested of 
2fb90 74 68 65 20 6f 70 65 72 61 74 69 6e 67 0a 2a 2a  the operating.**
2fba0 20 20 20 20 20 20 20 20 20 20 73 79 73 74 65 6d            system
2fbb0 2c 20 77 68 69 63 68 20 6d 69 67 68 74 20 62 65  , which might be
2fbc0 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68 65   larger than the
2fbd0 20 70 61 72 61 6d 65 74 65 72 20 4d 2e 0a 2a 2f   parameter M..*/
2fbe0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 6c 65  .int sqlite3_sle
2fbf0 65 70 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ep(int);../*.** 
2fc00 43 41 50 49 33 52 45 46 3a 20 20 4e 61 6d 65 20  CAPI3REF:  Name 
2fc10 4f 66 20 54 68 65 20 46 6f 6c 64 65 72 20 48 6f  Of The Folder Ho
2fc20 6c 64 69 6e 67 20 54 65 6d 70 6f 72 61 72 79 20  lding Temporary 
2fc30 46 69 6c 65 73 20 7b 46 31 30 33 31 30 7d 0a 2a  Files {F10310}.*
2fc40 2a 0a 2a 2a 20 49 66 20 74 68 69 73 20 67 6c 6f  *.** If this glo
2fc50 62 61 6c 20 76 61 72 69 61 62 6c 65 20 69 73 20  bal variable is 
2fc60 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f  made to point to
2fc70 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 68 20   a string which 
2fc80 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f  is.** the name o
2fc90 66 20 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b 61  f a folder (a.ka
2fca0 2e 20 64 69 72 65 63 74 6f 72 79 29 2c 20 74 68  . directory), th
2fcb0 65 6e 20 61 6c 6c 20 74 65 6d 70 6f 72 61 72 79  en all temporary
2fcc0 20 66 69 6c 65 73 0a 2a 2a 20 63 72 65 61 74 65   files.** create
2fcd0 64 20 62 79 20 53 51 4c 69 74 65 20 77 69 6c 6c  d by SQLite will
2fce0 20 62 65 20 70 6c 61 63 65 64 20 69 6e 20 74 68   be placed in th
2fcf0 61 74 20 64 69 72 65 63 74 6f 72 79 2e 20 20 49  at directory.  I
2fd00 66 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a  f this variable.
2fd10 2a 2a 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74  ** is NULL point
2fd20 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  er, then SQLite 
2fd30 64 6f 65 73 20 61 20 73 65 61 72 63 68 20 66 6f  does a search fo
2fd40 72 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65  r an appropriate
2fd50 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 66 69   temporary.** fi
2fd60 6c 65 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a  le directory..**
2fd70 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61  .** It is not sa
2fd80 66 65 20 74 6f 20 6d 6f 64 69 66 79 20 74 68 69  fe to modify thi
2fd90 73 20 76 61 72 69 61 62 6c 65 20 6f 6e 63 65 20  s variable once 
2fda0 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  a database conne
2fdb0 63 74 69 6f 6e 0a 2a 2a 20 68 61 73 20 62 65 65  ction.** has bee
2fdc0 6e 20 6f 70 65 6e 65 64 2e 20 20 49 74 20 69 73  n opened.  It is
2fdd0 20 69 6e 74 65 6e 64 65 64 20 74 68 61 74 20 74   intended that t
2fde0 68 69 73 20 76 61 72 69 61 62 6c 65 20 62 65 20  his variable be 
2fdf0 73 65 74 20 6f 6e 63 65 0a 2a 2a 20 61 73 20 70  set once.** as p
2fe00 61 72 74 20 6f 66 20 70 72 6f 63 65 73 73 20 69  art of process i
2fe10 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e  nitialization an
2fe20 64 20 62 65 66 6f 72 65 20 61 6e 79 20 53 51 4c  d before any SQL
2fe30 69 74 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  ite interface.**
2fe40 20 72 6f 75 74 69 6e 65 73 20 68 61 76 65 20 62   routines have b
2fe50 65 65 6e 20 63 61 6c 6c 20 61 6e 64 20 72 65 6d  een call and rem
2fe60 61 69 6e 20 75 6e 63 68 61 6e 67 65 64 20 74 68  ain unchanged th
2fe70 65 72 65 61 66 74 65 72 2e 0a 2a 2f 0a 53 51 4c  ereafter..*/.SQL
2fe80 49 54 45 5f 45 58 54 45 52 4e 20 63 68 61 72 20  ITE_EXTERN char 
2fe90 2a 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69  *sqlite3_temp_di
2fea0 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20  rectory;../*.** 
2feb0 43 41 50 49 33 52 45 46 3a 20 20 54 65 73 74 20  CAPI3REF:  Test 
2fec0 54 6f 20 53 65 65 20 49 66 20 54 68 65 20 44 61  To See If The Da
2fed0 74 61 62 61 73 65 20 49 73 20 49 6e 20 41 75 74  tabase Is In Aut
2fee0 6f 2d 43 6f 6d 6d 69 74 20 4d 6f 64 65 20 7b 46  o-Commit Mode {F
2fef0 31 32 39 33 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  12930}.**.** The
2ff00 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74   sqlite3_get_aut
2ff10 6f 63 6f 6d 6d 69 74 28 29 20 69 6e 74 65 72 66  ocommit() interf
2ff20 61 63 65 73 20 72 65 74 75 72 6e 73 20 6e 6f 6e  aces returns non
2ff30 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20 7a 65 72 6f  -zero or.** zero
2ff40 20 69 66 20 74 68 65 20 67 69 76 65 6e 20 64 61   if the given da
2ff50 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2ff60 6e 20 69 73 20 6f 72 20 69 73 20 6e 6f 74 20 69  n is or is not i
2ff70 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64  n autocommit mod
2ff80 65 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65  e,.** respective
2ff90 6c 79 2e 20 20 20 41 75 74 6f 63 6f 6d 6d 69 74  ly.   Autocommit
2ffa0 20 6d 6f 64 65 20 69 73 20 6f 6e 0a 2a 2a 20 62   mode is on.** b
2ffb0 79 20 64 65 66 61 75 6c 74 2e 20 20 41 75 74 6f  y default.  Auto
2ffc0 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 64  commit mode is d
2ffd0 69 73 61 62 6c 65 64 20 62 79 20 61 20 5b 42 45  isabled by a [BE
2ffe0 47 49 4e 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a  GIN] statement..
2fff0 2a 2a 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f  ** Autocommit mo
30000 64 65 20 69 73 20 72 65 65 6e 61 62 6c 65 64 20  de is reenabled 
30010 62 79 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72  by a [COMMIT] or
30020 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a   [ROLLBACK]..**.
30030 2a 2a 20 49 66 20 63 65 72 74 61 69 6e 20 6b 69  ** If certain ki
30040 6e 64 73 20 6f 66 20 65 72 72 6f 72 73 20 6f 63  nds of errors oc
30050 63 75 72 20 6f 6e 20 61 20 73 74 61 74 65 6d 65  cur on a stateme
30060 6e 74 20 77 69 74 68 69 6e 20 61 20 6d 75 6c 74  nt within a mult
30070 69 2d 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74  i-statement.** t
30080 72 61 6e 73 61 63 74 69 6f 6e 73 20 28 65 72 72  ransactions (err
30090 6f 72 73 20 69 6e 63 6c 75 64 69 6e 67 20 5b 53  ors including [S
300a0 51 4c 49 54 45 5f 46 55 4c 4c 5d 2c 20 5b 53 51  QLITE_FULL], [SQ
300b0 4c 49 54 45 5f 49 4f 45 52 52 5d 2c 20 0a 2a 2a  LITE_IOERR], .**
300c0 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2c   [SQLITE_NOMEM],
300d0 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 20   [SQLITE_BUSY], 
300e0 61 6e 64 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  and [SQLITE_INTE
300f0 52 52 55 50 54 5d 29 20 74 68 65 6e 20 74 68 65  RRUPT]) then the
30100 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  .** transaction 
30110 6d 69 67 68 74 20 62 65 20 72 6f 6c 6c 65 64 20  might be rolled 
30120 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c  back automatical
30130 6c 79 2e 20 20 54 68 65 20 6f 6e 6c 79 20 77 61  ly.  The only wa
30140 79 20 74 6f 0a 2a 2a 20 66 69 6e 64 20 6f 75 74  y to.** find out
30150 20 69 66 20 53 51 4c 69 74 65 20 61 75 74 6f 6d   if SQLite autom
30160 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20  atically rolled 
30170 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63  back the transac
30180 74 69 6f 6e 20 61 66 74 65 72 0a 2a 2a 20 61 6e  tion after.** an
30190 20 65 72 72 6f 72 20 69 73 20 74 6f 20 75 73 65   error is to use
301a0 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a   this function..
301b0 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
301c0 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 33 31 7d  :.**.** {F12931}
301d0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 67 65   The [sqlite3_ge
301e0 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 44 29 5d  t_autocommit(D)]
301f0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
30200 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 0a 2a  ns non-zero or.*
30210 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 20  *          zero 
30220 69 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  if the [database
30230 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 69   connection] D i
30240 73 20 6f 72 20 69 73 20 6e 6f 74 20 69 6e 20 61  s or is not in a
30250 75 74 6f 63 6f 6d 6d 69 74 0a 2a 2a 20 20 20 20  utocommit.**    
30260 20 20 20 20 20 20 6d 6f 64 65 2c 20 72 65 73 70        mode, resp
30270 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ectively..**.** 
30280 7b 46 31 32 39 33 32 7d 20 41 75 74 6f 63 6f 6d  {F12932} Autocom
30290 6d 69 74 20 6d 6f 64 65 20 69 73 20 6f 6e 20 62  mit mode is on b
302a0 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a  y default..**.**
302b0 20 7b 46 31 32 39 33 33 7d 20 41 75 74 6f 63 6f   {F12933} Autoco
302c0 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 64 69 73  mmit mode is dis
302d0 61 62 6c 65 64 20 62 79 20 61 20 73 75 63 63 65  abled by a succe
302e0 73 73 66 75 6c 20 5b 42 45 47 49 4e 5d 20 73 74  ssful [BEGIN] st
302f0 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b  atement..**.** {
30300 46 31 32 39 33 34 7d 20 41 75 74 6f 63 6f 6d 6d  F12934} Autocomm
30310 69 74 20 6d 6f 64 65 20 69 73 20 65 6e 61 62 6c  it mode is enabl
30320 65 64 20 62 79 20 61 20 73 75 63 63 65 73 73 66  ed by a successf
30330 75 6c 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b  ul [COMMIT] or [
30340 52 4f 4c 4c 42 41 43 4b 5d 0a 2a 2a 20 20 20 20  ROLLBACK].**    
30350 20 20 20 20 20 20 73 74 61 74 65 6d 65 6e 74 2e        statement.
30360 0a 2a 2a 20 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49 54  .** .**.** LIMIT
30370 41 54 49 4f 4e 53 3a 0a 2a 2a 2a 0a 2a 2a 20 7b  ATIONS:.***.** {
30380 55 31 32 39 33 36 7d 20 49 66 20 61 6e 6f 74 68  U12936} If anoth
30390 65 72 20 74 68 72 65 61 64 20 63 68 61 6e 67 65  er thread change
303a0 73 20 74 68 65 20 61 75 74 6f 63 6f 6d 6d 69 74  s the autocommit
303b0 20 73 74 61 74 75 73 20 6f 66 20 74 68 65 20 64   status of the d
303c0 61 74 61 62 61 73 65 0a 2a 2a 20 20 20 20 20 20  atabase.**      
303d0 20 20 20 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77      connection w
303e0 68 69 6c 65 20 74 68 69 73 20 72 6f 75 74 69 6e  hile this routin
303f0 65 20 69 73 20 72 75 6e 6e 69 6e 67 2c 20 74 68  e is running, th
30400 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  en the return va
30410 6c 75 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  lue.**          
30420 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f  is undefined..*/
30430 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74  .int sqlite3_get
30440 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 73 71 6c 69  _autocommit(sqli
30450 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
30460 50 49 33 52 45 46 3a 20 20 46 69 6e 64 20 54 68  PI3REF:  Find Th
30470 65 20 44 61 74 61 62 61 73 65 20 48 61 6e 64 6c  e Database Handl
30480 65 20 4f 66 20 41 20 50 72 65 70 61 72 65 64 20  e Of A Prepared 
30490 53 74 61 74 65 6d 65 6e 74 20 7b 46 31 33 31 32  Statement {F1312
304a0 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  0}.**.** The sql
304b0 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69  ite3_db_handle i
304c0 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 65 74 75  nterface.** retu
304d0 72 6e 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33  rns the [sqlite3
304e0 2a 5d 20 64 61 74 61 62 61 73 65 20 68 61 6e 64  *] database hand
304f0 6c 65 20 74 6f 20 77 68 69 63 68 20 61 0a 2a 2a  le to which a.**
30500 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
30510 6d 65 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e 0a 2a  ment] belongs..*
30520 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20 68  * The database h
30530 61 6e 64 6c 65 20 72 65 74 75 72 6e 65 64 20 62  andle returned b
30540 79 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e  y sqlite3_db_han
30550 64 6c 65 0a 2a 2a 20 69 73 20 74 68 65 20 73 61  dle.** is the sa
30560 6d 65 20 64 61 74 61 62 61 73 65 20 68 61 6e 64  me database hand
30570 6c 65 20 74 68 61 74 20 77 61 73 0a 2a 2a 20 74  le that was.** t
30580 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
30590 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  t to the [sqlite
305a0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
305b0 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 0a  or its variants.
305c0 2a 2a 20 74 68 61 74 20 77 61 73 20 75 73 65 64  ** that was used
305d0 20 74 6f 20 63 72 65 61 74 65 20 74 68 65 20 73   to create the s
305e0 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20  tatement in the 
305f0 66 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2a 0a  first place..**.
30600 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
30610 2a 0a 2a 2a 20 7b 46 31 33 31 32 33 7d 20 54 68  *.** {F13123} Th
30620 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 68 61  e [sqlite3_db_ha
30630 6e 64 6c 65 28 53 29 5d 20 69 6e 74 65 72 66 61  ndle(S)] interfa
30640 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
30650 6e 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  nter.**         
30660 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73   to the [databas
30670 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 73  e connection] as
30680 73 6f 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a  sociated with.**
30690 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61            [prepa
306a0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
306b0 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71  ..*/.sqlite3 *sq
306c0 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 28  lite3_db_handle(
306d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
306e0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
306f0 3a 20 43 6f 6d 6d 69 74 20 41 6e 64 20 52 6f 6c  : Commit And Rol
30700 6c 62 61 63 6b 20 4e 6f 74 69 66 69 63 61 74 69  lback Notificati
30710 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 20 7b 46 31  on Callbacks {F1
30720 32 39 35 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20  2950}.**.** The 
30730 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68  sqlite3_commit_h
30740 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20  ook() interface 
30750 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c  registers a call
30760 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  back.** function
30770 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77   to be invoked w
30780 68 65 6e 65 76 65 72 20 61 20 74 72 61 6e 73 61  henever a transa
30790 63 74 69 6f 6e 20 69 73 20 63 6f 6d 6d 69 74 74  ction is committ
307a0 65 64 2e 0a 2a 2a 20 41 6e 79 20 63 61 6c 6c 62  ed..** Any callb
307b0 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 72 65  ack set by a pre
307c0 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73 71  vious call to sq
307d0 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f  lite3_commit_hoo
307e0 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73  k().** for the s
307f0 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
30800 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72  nection is overr
30810 69 64 64 65 6e 2e 0a 2a 2a 20 54 68 65 20 73 71  idden..** The sq
30820 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68  lite3_rollback_h
30830 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20  ook() interface 
30840 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c  registers a call
30850 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  back.** function
30860 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77   to be invoked w
30870 68 65 6e 65 76 65 72 20 61 20 74 72 61 6e 73 61  henever a transa
30880 63 74 69 6f 6e 20 69 73 20 63 6f 6d 6d 69 74 74  ction is committ
30890 65 64 2e 0a 2a 2a 20 41 6e 79 20 63 61 6c 6c 62  ed..** Any callb
308a0 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 72 65  ack set by a pre
308b0 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73 71  vious call to sq
308c0 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f  lite3_commit_hoo
308d0 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73  k().** for the s
308e0 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
308f0 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72  nection is overr
30900 69 64 64 65 6e 2e 0a 2a 2a 20 54 68 65 20 70 41  idden..** The pA
30910 72 67 20 61 72 67 75 6d 65 6e 74 20 69 73 20 70  rg argument is p
30920 61 73 73 65 64 20 74 68 72 6f 75 67 68 0a 2a 2a  assed through.**
30930 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
30940 2e 20 20 49 66 20 74 68 65 20 63 61 6c 6c 62 61  .  If the callba
30950 63 6b 20 6f 6e 20 61 20 63 6f 6d 6d 69 74 20 68  ck on a commit h
30960 6f 6f 6b 20 66 75 6e 63 74 69 6f 6e 20 0a 2a 2a  ook function .**
30970 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
30980 6f 2c 20 74 68 65 6e 20 74 68 65 20 63 6f 6d 6d  o, then the comm
30990 69 74 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20  it is converted 
309a0 69 6e 74 6f 20 61 20 72 6f 6c 6c 62 61 63 6b 2e  into a rollback.
309b0 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65  .**.** If anothe
309c0 72 20 66 75 6e 63 74 69 6f 6e 20 77 61 73 20 70  r function was p
309d0 72 65 76 69 6f 75 73 6c 79 20 72 65 67 69 73 74  reviously regist
309e0 65 72 65 64 2c 20 69 74 73 0a 2a 2a 20 70 41 72  ered, its.** pAr
309f0 67 20 76 61 6c 75 65 20 69 73 20 72 65 74 75 72  g value is retur
30a00 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20  ned.  Otherwise 
30a10 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64  NULL is returned
30a20 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72  ..**.** Register
30a30 69 6e 67 20 61 20 4e 55 4c 4c 20 66 75 6e 63 74  ing a NULL funct
30a40 69 6f 6e 20 64 69 73 61 62 6c 65 73 20 74 68 65  ion disables the
30a50 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a   callback..**.**
30a60 20 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65   For the purpose
30a70 73 20 6f 66 20 74 68 69 73 20 41 50 49 2c 20 61  s of this API, a
30a80 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20   transaction is 
30a90 73 61 69 64 20 74 6f 20 68 61 76 65 20 62 65 65  said to have bee
30aa0 6e 20 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63  n .** rolled bac
30ab0 6b 20 69 66 20 61 6e 20 65 78 70 6c 69 63 69 74  k if an explicit
30ac0 20 22 52 4f 4c 4c 42 41 43 4b 22 20 73 74 61 74   "ROLLBACK" stat
30ad0 65 6d 65 6e 74 20 69 73 20 65 78 65 63 75 74 65  ement is execute
30ae0 64 2c 20 6f 72 0a 2a 2a 20 61 6e 20 65 72 72 6f  d, or.** an erro
30af0 72 20 6f 72 20 63 6f 6e 73 74 72 61 69 6e 74 20  r or constraint 
30b00 63 61 75 73 65 73 20 61 6e 20 69 6d 70 6c 69 63  causes an implic
30b10 69 74 20 72 6f 6c 6c 62 61 63 6b 20 74 6f 20 6f  it rollback to o
30b20 63 63 75 72 2e 0a 2a 2a 20 54 68 65 20 72 6f 6c  ccur..** The rol
30b30 6c 62 61 63 6b 20 63 61 6c 6c 62 61 63 6b 20 69  lback callback i
30b40 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69 66  s not invoked if
30b50 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69   a transaction i
30b60 73 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c  s.** automatical
30b70 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62  ly rolled back b
30b80 65 63 61 75 73 65 20 74 68 65 20 64 61 74 61 62  ecause the datab
30b90 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
30ba0 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 54 68 65  s closed..** The
30bb0 20 72 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c 62 61   rollback callba
30bc0 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65  ck is not invoke
30bd0 64 20 69 66 20 61 20 74 72 61 6e 73 61 63 74 69  d if a transacti
30be0 6f 6e 20 69 73 0a 2a 2a 20 72 6f 6c 6c 65 64 20  on is.** rolled 
30bf0 62 61 63 6b 20 62 65 63 61 75 73 65 20 61 20 63  back because a c
30c00 6f 6d 6d 69 74 20 63 61 6c 6c 62 61 63 6b 20 72  ommit callback r
30c10 65 74 75 72 6e 65 64 20 6e 6f 6e 2d 7a 65 72 6f  eturned non-zero
30c20 2e 0a 2a 2a 20 3c 74 6f 64 6f 3e 20 43 68 65 63  ..** <todo> Chec
30c30 6b 20 6f 6e 20 74 68 69 73 20 3c 2f 74 6f 64 6f  k on this </todo
30c40 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72  >.**.** These ar
30c50 65 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69  e experimental i
30c60 6e 74 65 72 66 61 63 65 73 20 61 6e 64 20 61 72  nterfaces and ar
30c70 65 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61  e subject to cha
30c80 6e 67 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  nge..**.** INVAR
30c90 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31  IANTS:.**.** {F1
30ca0 32 39 35 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  2951} The [sqlit
30cb0 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44  e3_commit_hook(D
30cc0 2c 46 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 65  ,F,P)] interface
30cd0 20 72 65 67 69 73 74 65 72 73 20 74 68 65 0a 2a   registers the.*
30ce0 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c 62  *          callb
30cf0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 46 20 74  ack function F t
30d00 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74  o be invoked wit
30d10 68 20 61 72 67 75 6d 65 6e 74 20 50 20 77 68 65  h argument P whe
30d20 6e 65 76 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  never.**        
30d30 20 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20    a transaction 
30d40 63 6f 6d 6d 69 74 73 20 6f 6e 20 5b 64 61 74 61  commits on [data
30d50 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
30d60 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 35   D..**.** {F1295
30d70 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  2} The [sqlite3_
30d80 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c 46 2c  commit_hook(D,F,
30d90 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  P)] interface re
30da0 74 75 72 6e 73 20 74 68 65 20 50 0a 2a 2a 20 20  turns the P.**  
30db0 20 20 20 20 20 20 20 20 61 72 67 75 6d 65 6e 74          argument
30dc0 20 66 72 6f 6d 20 74 68 65 20 70 72 65 76 69 6f   from the previo
30dd0 75 73 20 63 61 6c 6c 20 77 69 74 68 20 74 68 65  us call with the
30de0 20 73 61 6d 65 20 0a 2a 2a 20 20 20 20 20 20 20   same .**       
30df0 20 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e     [database con
30e00 6e 65 63 74 69 6f 6e 20 5d 20 44 20 2c 20 6f 72  nection ] D , or
30e10 20 4e 55 4c 4c 20 6f 6e 20 74 68 65 20 66 69 72   NULL on the fir
30e20 73 74 20 63 61 6c 6c 0a 2a 2a 20 20 20 20 20 20  st call.**      
30e30 20 20 20 20 66 6f 72 20 61 20 70 61 72 74 69 63      for a partic
30e40 75 6c 61 72 20 5b 64 61 74 61 62 61 73 65 20 63  ular [database c
30e50 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a  onnection] D..**
30e60 0a 2a 2a 20 7b 46 31 32 39 35 33 7d 20 45 61 63  .** {F12953} Eac
30e70 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  h call to [sqlit
30e80 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29  e3_commit_hook()
30e90 5d 20 6f 76 65 72 77 72 69 74 65 73 20 74 68 65  ] overwrites the
30ea0 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20   callback.**    
30eb0 20 20 20 20 20 20 72 65 67 69 73 74 65 72 65 64        registered
30ec0 20 62 79 20 70 72 69 6f 72 20 63 61 6c 6c 73 2e   by prior calls.
30ed0 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 35 34 7d 20  .**.** {F12954} 
30ee0 49 66 20 74 68 65 20 46 20 61 72 67 75 6d 65 6e  If the F argumen
30ef0 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  t to [sqlite3_co
30f00 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29  mmit_hook(D,F,P)
30f10 5d 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20 20 20 20  ] is NULL.**    
30f20 20 20 20 20 20 20 74 68 65 6e 20 74 68 65 20 63        then the c
30f30 6f 6d 6d 69 74 20 68 6f 6f 6b 20 63 61 6c 6c 62  ommit hook callb
30f40 61 63 6b 20 69 73 20 63 61 6e 63 65 6c 6c 65 64  ack is cancelled
30f50 20 61 6e 64 20 6e 6f 20 63 61 6c 6c 62 61 63 6b   and no callback
30f60 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20  .**          is 
30f70 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 61 20 74  invoked when a t
30f80 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6d 6d 69  ransaction commi
30f90 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 35  ts..**.** {F1295
30fa0 35 7d 20 49 66 20 74 68 65 20 63 6f 6d 6d 69 74  5} If the commit
30fb0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
30fc0 73 20 6e 6f 6e 2d 7a 65 72 6f 20 74 68 65 6e 20  s non-zero then 
30fd0 74 68 65 20 63 6f 6d 6d 69 74 20 69 73 0a 2a 2a  the commit is.**
30fe0 20 20 20 20 20 20 20 20 20 20 63 6f 6e 76 65 72            conver
30ff0 74 65 64 20 69 6e 74 6f 20 61 20 72 6f 6c 6c 62  ted into a rollb
31000 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39  ack..**.** {F129
31010 36 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  61} The [sqlite3
31020 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44  _rollback_hook(D
31030 2c 46 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 65  ,F,P)] interface
31040 20 72 65 67 69 73 74 65 72 73 20 74 68 65 0a 2a   registers the.*
31050 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c 62  *          callb
31060 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 46 20 74  ack function F t
31070 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74  o be invoked wit
31080 68 20 61 72 67 75 6d 65 6e 74 20 50 20 77 68 65  h argument P whe
31090 6e 65 76 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  never.**        
310a0 20 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20    a transaction 
310b0 72 6f 6c 6c 73 20 62 61 63 6b 20 6f 6e 20 5b 64  rolls back on [d
310c0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
310d0 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  on] D..**.** {F1
310e0 32 39 36 32 7d 20 54 68 65 20 5b 73 71 6c 69 74  2962} The [sqlit
310f0 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b  e3_rollback_hook
31100 28 44 2c 46 2c 50 29 5d 20 69 6e 74 65 72 66 61  (D,F,P)] interfa
31110 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 50  ce returns the P
31120 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 72 67  .**          arg
31130 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68 65 20 70  ument from the p
31140 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 77 69 74  revious call wit
31150 68 20 74 68 65 20 73 61 6d 65 20 0a 2a 2a 20 20  h the same .**  
31160 20 20 20 20 20 20 20 20 5b 64 61 74 61 62 61 73          [databas
31170 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 5d 20 44  e connection ] D
31180 20 2c 20 6f 72 20 4e 55 4c 4c 20 6f 6e 20 74 68   , or NULL on th
31190 65 20 66 69 72 73 74 20 63 61 6c 6c 0a 2a 2a 20  e first call.** 
311a0 20 20 20 20 20 20 20 20 20 66 6f 72 20 61 20 70           for a p
311b0 61 72 74 69 63 75 6c 61 72 20 5b 64 61 74 61 62  articular [datab
311c0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
311d0 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 36 33  D..**.** {F12963
311e0 7d 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 5b  } Each call to [
311f0 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b  sqlite3_rollback
31200 5f 68 6f 6f 6b 28 29 5d 20 6f 76 65 72 77 72 69  _hook()] overwri
31210 74 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  tes the callback
31220 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 67  .**          reg
31230 69 73 74 65 72 65 64 20 62 79 20 70 72 69 6f 72  istered by prior
31240 20 63 61 6c 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46   calls..**.** {F
31250 31 32 39 36 34 7d 20 49 66 20 74 68 65 20 46 20  12964} If the F 
31260 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c  argument to [sql
31270 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f  ite3_rollback_ho
31280 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 73 20 4e 55  ok(D,F,P)] is NU
31290 4c 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  LL.**          t
312a0 68 65 6e 20 74 68 65 20 72 6f 6c 6c 62 61 63 6b  hen the rollback
312b0 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 69   hook callback i
312c0 73 20 63 61 6e 63 65 6c 6c 65 64 20 61 6e 64 20  s cancelled and 
312d0 6e 6f 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20  no callback.**  
312e0 20 20 20 20 20 20 20 20 69 73 20 69 6e 76 6f 6b          is invok
312f0 65 64 20 77 68 65 6e 20 61 20 74 72 61 6e 73 61  ed when a transa
31300 63 74 69 6f 6e 20 72 6f 6c 6c 73 20 62 61 63 6b  ction rolls back
31310 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
31320 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 73  e3_commit_hook(s
31330 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28  qlite3*, int(*)(
31340 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a  void*), void*);.
31350 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 6f  void *sqlite3_ro
31360 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 73 71 6c 69  llback_hook(sqli
31370 74 65 33 2a 2c 20 76 6f 69 64 28 2a 29 28 76 6f  te3*, void(*)(vo
31380 69 64 20 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a  id *), void*);..
31390 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
313a0 44 61 74 61 20 43 68 61 6e 67 65 20 4e 6f 74 69  Data Change Noti
313b0 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63  fication Callbac
313c0 6b 73 20 7b 46 31 32 39 37 30 7d 0a 2a 2a 0a 2a  ks {F12970}.**.*
313d0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 70  * The sqlite3_up
313e0 64 61 74 65 5f 68 6f 6f 6b 28 29 20 69 6e 74 65  date_hook() inte
313f0 72 66 61 63 65 0a 2a 2a 20 72 65 67 69 73 74 65  rface.** registe
31400 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  rs a callback fu
31410 6e 63 74 69 6f 6e 20 77 69 74 68 20 74 68 65 20  nction with the 
31420 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
31430 69 6f 6e 20 69 64 65 6e 74 69 66 69 65 64 20 62  ion identified b
31440 79 20 74 68 65 20 0a 2a 2a 20 66 69 72 73 74 20  y the .** first 
31450 61 72 67 75 6d 65 6e 74 20 74 6f 20 62 65 20 69  argument to be i
31460 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20  nvoked whenever 
31470 61 20 72 6f 77 20 69 73 20 75 70 64 61 74 65 64  a row is updated
31480 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65  , inserted or de
31490 6c 65 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 63 61  leted..** Any ca
314a0 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61 20  llback set by a 
314b0 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f  previous call to
314c0 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 66   this function f
314d0 6f 72 20 74 68 65 20 73 61 6d 65 20 0a 2a 2a 20  or the same .** 
314e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
314f0 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65  ion is overridde
31500 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63  n..**.** The sec
31510 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
31520 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
31530 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 69 6e 76   function to inv
31540 6f 6b 65 20 77 68 65 6e 20 61 20 0a 2a 2a 20 72  oke when a .** r
31550 6f 77 20 69 73 20 75 70 64 61 74 65 64 2c 20 69  ow is updated, i
31560 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74  nserted or delet
31570 65 64 2e 20 0a 2a 2a 20 54 68 65 20 66 69 72 73  ed. .** The firs
31580 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
31590 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 0a 2a 2a  e callback is.**
315a0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74   a copy of the t
315b0 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  hird argument to
315c0 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f   sqlite3_update_
315d0 68 6f 6f 6b 28 29 2e 0a 2a 2a 20 54 68 65 20 73  hook()..** The s
315e0 65 63 6f 6e 64 20 63 61 6c 6c 62 61 63 6b 20 0a  econd callback .
315f0 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f  ** argument is o
31600 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e  ne of [SQLITE_IN
31610 53 45 52 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 44  SERT], [SQLITE_D
31620 45 4c 45 54 45 5d 20 6f 72 20 5b 53 51 4c 49 54  ELETE] or [SQLIT
31630 45 5f 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 64 65  E_UPDATE],.** de
31640 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f  pending on the o
31650 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20 63 61  peration that ca
31660 75 73 65 64 20 74 68 65 20 63 61 6c 6c 62 61 63  used the callbac
31670 6b 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 2e  k to be invoked.
31680 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20 61 6e  .** The third an
31690 64 20 0a 2a 2a 20 66 6f 75 72 74 68 20 61 72 67  d .** fourth arg
316a0 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 63 61  uments to the ca
316b0 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 20 70  llback contain p
316c0 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20 64  ointers to the d
316d0 61 74 61 62 61 73 65 20 61 6e 64 20 0a 2a 2a 20  atabase and .** 
316e0 74 61 62 6c 65 20 6e 61 6d 65 20 63 6f 6e 74 61  table name conta
316f0 69 6e 69 6e 67 20 74 68 65 20 61 66 66 65 63 74  ining the affect
31700 65 64 20 72 6f 77 2e 0a 2a 2a 20 54 68 65 20 66  ed row..** The f
31710 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 70 61  inal callback pa
31720 72 61 6d 65 74 65 72 20 69 73 20 0a 2a 2a 20 74  rameter is .** t
31730 68 65 20 72 6f 77 69 64 20 6f 66 20 74 68 65 20  he rowid of the 
31740 72 6f 77 2e 0a 2a 2a 20 49 6e 20 74 68 65 20 63  row..** In the c
31750 61 73 65 20 6f 66 20 61 6e 20 75 70 64 61 74 65  ase of an update
31760 2c 20 74 68 69 73 20 69 73 20 74 68 65 20 72 6f  , this is the ro
31770 77 69 64 20 61 66 74 65 72 20 0a 2a 2a 20 74 68  wid after .** th
31780 65 20 75 70 64 61 74 65 20 74 61 6b 65 73 20 70  e update takes p
31790 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  lace..**.** The 
317a0 75 70 64 61 74 65 20 68 6f 6f 6b 20 69 73 20 6e  update hook is n
317b0 6f 74 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20  ot invoked when 
317c0 69 6e 74 65 72 6e 61 6c 20 73 79 73 74 65 6d 20  internal system 
317d0 74 61 62 6c 65 73 20 61 72 65 0a 2a 2a 20 6d 6f  tables are.** mo
317e0 64 69 66 69 65 64 20 28 69 2e 65 2e 20 73 71 6c  dified (i.e. sql
317f0 69 74 65 5f 6d 61 73 74 65 72 20 61 6e 64 20 73  ite_master and s
31800 71 6c 69 74 65 5f 73 65 71 75 65 6e 63 65 29 2e  qlite_sequence).
31810 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65  .**.** If anothe
31820 72 20 66 75 6e 63 74 69 6f 6e 20 77 61 73 20 70  r function was p
31830 72 65 76 69 6f 75 73 6c 79 20 72 65 67 69 73 74  reviously regist
31840 65 72 65 64 2c 20 69 74 73 20 70 41 72 67 20 76  ered, its pArg v
31850 61 6c 75 65 0a 2a 2a 20 69 73 20 72 65 74 75 72  alue.** is retur
31860 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20  ned.  Otherwise 
31870 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64  NULL is returned
31880 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
31890 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 37  TS:.**.** {F1297
318a0 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
318b0 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44 2c 46 2c  update_hook(D,F,
318c0 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 61  P)] interface ca
318d0 75 73 65 73 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  uses callback.**
318e0 20 20 20 20 20 20 20 20 20 20 66 75 6e 63 74 69            functi
318f0 6f 6e 20 46 20 74 6f 20 62 65 20 69 6e 76 6f 6b  on F to be invok
31900 65 64 20 77 69 74 68 20 66 69 72 73 74 20 70 61  ed with first pa
31910 72 61 6d 65 74 65 72 20 50 20 77 68 65 6e 65 76  rameter P whenev
31920 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  er.**          a
31930 20 74 61 62 6c 65 20 72 6f 77 20 69 73 20 6d 6f   table row is mo
31940 64 69 66 69 65 64 2c 20 69 6e 73 65 72 74 65 64  dified, inserted
31950 2c 20 6f 72 20 64 65 6c 65 74 65 64 20 6f 6e 0a  , or deleted on.
31960 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61 74  **          [dat
31970 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
31980 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39  ] D..**.** {F129
31990 37 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  73} The [sqlite3
319a0 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44 2c 46  _update_hook(D,F
319b0 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  ,P)] interface r
319c0 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65  eturns the value
319d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20  .**          of 
319e0 50 20 66 6f 72 20 74 68 65 20 70 72 65 76 69 6f  P for the previo
319f0 75 73 20 63 61 6c 6c 20 6f 6e 20 74 68 65 20 73  us call on the s
31a00 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ame [database co
31a10 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 0a 2a 2a 20  nnection] D,.** 
31a20 20 20 20 20 20 20 20 20 20 6f 72 20 4e 55 4c 4c           or NULL
31a30 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 63   for the first c
31a40 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39  all..**.** {F129
31a50 37 35 7d 20 49 66 20 74 68 65 20 75 70 64 61 74  75} If the updat
31a60 65 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20  e hook callback 
31a70 46 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 75 70  F in [sqlite3_up
31a80 64 61 74 65 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29  date_hook(D,F,P)
31a90 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73  ].**          is
31aa0 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 6e   NULL then the n
31ab0 6f 20 75 70 64 61 74 65 20 63 61 6c 6c 62 61 63  o update callbac
31ac0 6b 73 20 61 72 65 20 6d 61 64 65 2e 0a 2a 2a 0a  ks are made..**.
31ad0 2a 2a 20 7b 46 31 32 39 37 37 7d 20 45 61 63 68  ** {F12977} Each
31ae0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
31af0 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44 2c  3_update_hook(D,
31b00 46 2c 50 29 5d 20 6f 76 65 72 72 69 64 65 73 20  F,P)] overrides 
31b10 70 72 69 6f 72 20 63 61 6c 6c 73 0a 2a 2a 20 20  prior calls.**  
31b20 20 20 20 20 20 20 20 20 74 6f 20 74 68 65 20 73          to the s
31b30 61 6d 65 20 69 6e 74 65 72 66 61 63 65 20 6f 6e  ame interface on
31b40 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62   the same [datab
31b50 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
31b60 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 37 39  D..**.** {F12979
31b70 7d 20 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f  } The update hoo
31b80 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f  k callback is no
31b90 74 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 69  t invoked when i
31ba0 6e 74 65 72 6e 61 6c 20 73 79 73 74 65 6d 0a 2a  nternal system.*
31bb0 2a 20 20 20 20 20 20 20 20 20 20 74 61 62 6c 65  *          table
31bc0 73 20 73 75 63 68 20 61 73 20 73 71 6c 69 74 65  s such as sqlite
31bd0 5f 6d 61 73 74 65 72 20 61 6e 64 20 73 71 6c 69  _master and sqli
31be0 74 65 5f 73 65 71 75 65 6e 63 65 20 61 72 65 20  te_sequence are 
31bf0 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20  modified..**.** 
31c00 7b 46 31 32 39 38 31 7d 20 54 68 65 20 73 65 63  {F12981} The sec
31c10 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
31c20 20 74 68 65 20 75 70 64 61 74 65 20 63 61 6c 6c   the update call
31c30 62 61 63 6b 20 0a 2a 2a 20 20 20 20 20 20 20 20  back .**        
31c40 20 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c    is one of [SQL
31c50 49 54 45 5f 49 4e 53 45 52 54 5d 2c 20 5b 53 51  ITE_INSERT], [SQ
31c60 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 6f 72 20  LITE_DELETE] or 
31c70 5b 53 51 4c 49 54 45 5f 55 50 44 41 54 45 5d 2c  [SQLITE_UPDATE],
31c80 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65 70  .**          dep
31c90 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 70  ending on the op
31ca0 65 72 61 74 69 6f 6e 20 74 68 61 74 20 63 61 75  eration that cau
31cb0 73 65 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  sed the callback
31cc0 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 2e 0a   to be invoked..
31cd0 2a 2a 0a 2a 2a 20 7b 46 31 32 39 38 33 7d 20 54  **.** {F12983} T
31ce0 68 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75  he third and fou
31cf0 72 74 68 20 61 72 67 75 6d 65 6e 74 73 20 74 6f  rth arguments to
31d00 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f   the callback co
31d10 6e 74 61 69 6e 20 70 6f 69 6e 74 65 72 73 0a 2a  ntain pointers.*
31d20 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 7a 65  *          to ze
31d30 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
31d40 46 2d 38 20 73 74 72 69 6e 67 73 20 77 68 69 63  F-8 strings whic
31d50 68 20 61 72 65 20 74 68 65 20 6e 61 6d 65 73 20  h are the names 
31d60 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  of the.**       
31d70 20 20 20 64 61 74 61 62 61 73 65 20 61 6e 64 20     database and 
31d80 74 61 62 6c 65 20 74 68 61 74 20 69 73 20 62 65  table that is be
31d90 69 6e 67 20 75 70 64 61 74 65 64 2e 0a 0a 2a 2a  ing updated...**
31da0 20 7b 46 31 32 39 38 35 7d 20 54 68 65 20 66 69   {F12985} The fi
31db0 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 70 61 72  nal callback par
31dc0 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 72 6f  ameter is the ro
31dd0 77 69 64 20 6f 66 20 74 68 65 20 72 6f 77 20 61  wid of the row a
31de0 66 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  fter.**         
31df0 20 74 68 65 20 63 68 61 6e 67 65 20 6f 63 63 75   the change occu
31e00 72 73 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c  rs..*/.void *sql
31e10 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b  ite3_update_hook
31e20 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
31e30 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 2c   void(*)(void *,
31e40 69 6e 74 20 2c 63 68 61 72 20 63 6f 6e 73 74 20  int ,char const 
31e50 2a 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 73  *,char const *,s
31e60 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 2c 0a 20  qlite3_int64),. 
31e70 20 76 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a   void*.);../*.**
31e80 20 43 41 50 49 33 52 45 46 3a 20 20 45 6e 61 62   CAPI3REF:  Enab
31e90 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 53 68  le Or Disable Sh
31ea0 61 72 65 64 20 50 61 67 65 72 20 43 61 63 68 65  ared Pager Cache
31eb0 20 7b 46 31 30 33 33 30 7d 0a 2a 2a 0a 2a 2a 20   {F10330}.**.** 
31ec0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 65 6e 61  This routine ena
31ed0 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73  bles or disables
31ee0 20 74 68 65 20 73 68 61 72 69 6e 67 20 6f 66 20   the sharing of 
31ef0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 61 63  the database cac
31f00 68 65 0a 2a 2a 20 61 6e 64 20 73 63 68 65 6d 61  he.** and schema
31f10 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73   data structures
31f20 20 62 65 74 77 65 65 6e 20 63 6f 6e 6e 65 63 74   between connect
31f30 69 6f 6e 73 20 74 6f 20 74 68 65 20 73 61 6d 65  ions to the same
31f40 20 64 61 74 61 62 61 73 65 2e 0a 2a 2a 20 53 68   database..** Sh
31f50 61 72 69 6e 67 20 69 73 20 65 6e 61 62 6c 65 64  aring is enabled
31f60 20 69 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74   if the argument
31f70 20 69 73 20 74 72 75 65 20 61 6e 64 20 64 69 73   is true and dis
31f80 61 62 6c 65 64 20 69 66 20 74 68 65 20 61 72 67  abled if the arg
31f90 75 6d 65 6e 74 0a 2a 2a 20 69 73 20 66 61 6c 73  ument.** is fals
31fa0 65 2e 0a 2a 2a 0a 2a 2a 20 43 61 63 68 65 20 73  e..**.** Cache s
31fb0 68 61 72 69 6e 67 20 69 73 20 65 6e 61 62 6c 65  haring is enable
31fc0 64 20 61 6e 64 20 64 69 73 61 62 6c 65 64 0a 2a  d and disabled.*
31fd0 2a 20 66 6f 72 20 61 6e 20 65 6e 74 69 72 65 20  * for an entire 
31fe0 70 72 6f 63 65 73 73 2e 20 7b 45 4e 44 7d 20 54  process. {END} T
31ff0 68 69 73 20 69 73 20 61 20 63 68 61 6e 67 65 20  his is a change 
32000 61 73 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72  as of SQLite ver
32010 73 69 6f 6e 20 33 2e 35 2e 30 2e 0a 2a 2a 20 49  sion 3.5.0..** I
32020 6e 20 70 72 69 6f 72 20 76 65 72 73 69 6f 6e 73  n prior versions
32030 20 6f 66 20 53 51 4c 69 74 65 2c 20 73 68 61 72   of SQLite, shar
32040 69 6e 67 20 77 61 73 0a 2a 2a 20 65 6e 61 62 6c  ing was.** enabl
32050 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 20 66  ed or disabled f
32060 6f 72 20 65 61 63 68 20 74 68 72 65 61 64 20 73  or each thread s
32070 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a  eparately..**.**
32080 20 54 68 65 20 63 61 63 68 65 20 73 68 61 72 69   The cache shari
32090 6e 67 20 6d 6f 64 65 20 73 65 74 20 62 79 20 74  ng mode set by t
320a0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 65 66  his interface ef
320b0 66 65 63 74 73 20 61 6c 6c 20 73 75 62 73 65 71  fects all subseq
320c0 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f  uent.** calls to
320d0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
320e0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
320f0 5f 76 32 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c  _v2()], and [sql
32100 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a  ite3_open16()]..
32110 2a 2a 20 45 78 69 73 74 69 6e 67 20 64 61 74 61  ** Existing data
32120 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
32130 20 63 6f 6e 74 69 6e 75 65 20 75 73 65 20 74 68   continue use th
32140 65 20 73 68 61 72 69 6e 67 20 6d 6f 64 65 0a 2a  e sharing mode.*
32150 2a 20 74 68 61 74 20 77 61 73 20 69 6e 20 65 66  * that was in ef
32160 66 65 63 74 20 61 74 20 74 68 65 20 74 69 6d 65  fect at the time
32170 20 74 68 65 79 20 77 65 72 65 20 6f 70 65 6e 65   they were opene
32180 64 2e 0a 2a 2a 0a 2a 2a 20 56 69 72 74 75 61 6c  d..**.** Virtual
32190 20 74 61 62 6c 65 73 20 63 61 6e 6e 6f 74 20 62   tables cannot b
321a0 65 20 75 73 65 64 20 77 69 74 68 20 61 20 73 68  e used with a sh
321b0 61 72 65 64 20 63 61 63 68 65 2e 20 20 20 57 68  ared cache.   Wh
321c0 65 6e 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63  en shared.** cac
321d0 68 65 20 69 73 20 65 6e 61 62 6c 65 64 2c 20 74  he is enabled, t
321e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  he [sqlite3_crea
321f0 74 65 5f 6d 6f 64 75 6c 65 28 29 5d 20 41 50 49  te_module()] API
32200 20 75 73 65 64 20 74 6f 20 72 65 67 69 73 74 65   used to registe
32210 72 0a 2a 2a 20 76 69 72 74 75 61 6c 20 74 61 62  r.** virtual tab
32220 6c 65 73 20 77 69 6c 6c 20 61 6c 77 61 79 73 20  les will always 
32230 72 65 74 75 72 6e 20 61 6e 20 65 72 72 6f 72 2e  return an error.
32240 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
32250 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ine returns [SQL
32260 49 54 45 5f 4f 4b 5d 20 69 66 20 73 68 61 72 65  ITE_OK] if share
32270 64 20 63 61 63 68 65 20 77 61 73 0a 2a 2a 20 65  d cache was.** e
32280 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c  nabled or disabl
32290 65 64 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e  ed successfully.
322a0 20 20 41 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65    An [error code
322b0 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64  ].** is returned
322c0 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a   otherwise..**.*
322d0 2a 20 53 68 61 72 65 64 20 63 61 63 68 65 20 69  * Shared cache i
322e0 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65  s disabled by de
322f0 66 61 75 6c 74 2e 20 42 75 74 20 74 68 69 73 20  fault. But this 
32300 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69 6e 0a  might change in.
32310 2a 2a 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  ** future releas
32320 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41  es of SQLite.  A
32330 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
32340 20 63 61 72 65 20 61 62 6f 75 74 20 73 68 61 72   care about shar
32350 65 64 0a 2a 2a 20 63 61 63 68 65 20 73 65 74 74  ed.** cache sett
32360 69 6e 67 20 73 68 6f 75 6c 64 20 73 65 74 20 69  ing should set i
32370 74 20 65 78 70 6c 69 63 69 74 6c 79 2e 0a 2a 2a  t explicitly..**
32380 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
32390 2a 2a 20 0a 2a 2a 20 7b 46 31 30 33 33 31 7d 20  ** .** {F10331} 
323a0 41 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e 76  A successful inv
323b0 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69  ocation of [sqli
323c0 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65  te3_enable_share
323d0 64 5f 63 61 63 68 65 28 42 29 5d 0a 2a 2a 20 20  d_cache(B)].**  
323e0 20 20 20 20 20 20 20 20 77 69 6c 6c 20 65 6e 61          will ena
323f0 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 73  ble or disable s
32400 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65  hared cache mode
32410 20 66 6f 72 20 61 6e 79 20 73 75 62 73 65 71 75   for any subsequ
32420 65 6e 74 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20  ently.**        
32430 20 20 63 72 65 61 74 65 64 20 5b 64 61 74 61 62    created [datab
32440 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
32450 69 6e 20 74 68 65 20 73 61 6d 65 20 70 72 6f 63  in the same proc
32460 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 33  ess..**.** {F103
32470 33 36 7d 20 57 68 65 6e 20 73 68 61 72 65 64 20  36} When shared 
32480 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64  cache is enabled
32490 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  , the [sqlite3_c
324a0 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 5d 0a  reate_module()].
324b0 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65  **          inte
324c0 72 66 61 63 65 20 77 69 6c 6c 20 61 6c 77 61 79  rface will alway
324d0 73 20 72 65 74 75 72 6e 20 61 6e 20 65 72 72 6f  s return an erro
324e0 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 33 33 37  r..**.** {F10337
324f0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65  } The [sqlite3_e
32500 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63  nable_shared_cac
32510 68 65 28 42 29 5d 20 69 6e 74 65 72 66 61 63 65  he(B)] interface
32520 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20   returns.**     
32530 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d       [SQLITE_OK]
32540 20 69 66 20 73 68 61 72 65 64 20 63 61 63 68 65   if shared cache
32550 20 77 61 73 20 65 6e 61 62 6c 65 64 20 6f 72 20   was enabled or 
32560 64 69 73 61 62 6c 65 64 20 73 75 63 63 65 73 73  disabled success
32570 66 75 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  fully..**.** {F1
32580 30 33 33 39 7d 20 53 68 61 72 65 64 20 63 61 63  0339} Shared cac
32590 68 65 20 69 73 20 64 69 73 61 62 6c 65 64 20 62  he is disabled b
325a0 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2f 0a 69 6e  y default..*/.in
325b0 74 20 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65  t sqlite3_enable
325c0 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28 69 6e  _shared_cache(in
325d0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
325e0 52 45 46 3a 20 20 41 74 74 65 6d 70 74 20 54 6f  REF:  Attempt To
325f0 20 46 72 65 65 20 48 65 61 70 20 4d 65 6d 6f 72   Free Heap Memor
32600 79 20 7b 46 31 37 33 34 30 7d 0a 2a 2a 0a 2a 2a  y {F17340}.**.**
32610 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 6c   The sqlite3_rel
32620 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 69 6e  ease_memory() in
32630 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73  terface attempts
32640 20 74 6f 0a 2a 2a 20 66 72 65 65 20 4e 20 62 79   to.** free N by
32650 74 65 73 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f  tes of heap memo
32660 72 79 20 62 79 20 64 65 61 6c 6c 6f 63 61 74 69  ry by deallocati
32670 6e 67 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c  ng non-essential
32680 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
32690 61 74 69 6f 6e 73 20 68 65 6c 64 20 62 79 20 74  ations held by t
326a0 68 65 20 64 61 74 61 62 61 73 65 20 6c 61 62 72  he database labr
326b0 61 72 79 2e 20 7b 45 4e 44 7d 20 20 4d 65 6d 6f  ary. {END}  Memo
326c0 72 79 20 75 73 65 64 0a 2a 2a 20 74 6f 20 63 61  ry used.** to ca
326d0 63 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67  che database pag
326e0 65 73 20 74 6f 20 69 6d 70 72 6f 76 65 20 70 65  es to improve pe
326f0 72 66 6f 72 6d 61 6e 63 65 20 69 73 20 61 6e 20  rformance is an 
32700 65 78 61 6d 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6f  example of.** no
32710 6e 2d 65 73 73 65 6e 74 69 61 6c 20 6d 65 6d 6f  n-essential memo
32720 72 79 2e 20 20 53 71 6c 69 74 65 33 5f 72 65 6c  ry.  Sqlite3_rel
32730 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 72 65  ease_memory() re
32740 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d  turns.** the num
32750 62 65 72 20 6f 66 20 62 79 74 65 73 20 61 63 74  ber of bytes act
32760 75 61 6c 6c 79 20 66 72 65 65 64 2c 20 77 68 69  ually freed, whi
32770 63 68 20 6d 69 67 68 74 20 62 65 20 6d 6f 72 65  ch might be more
32780 20 6f 72 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e   or less.** than
32790 20 74 68 65 20 61 6d 6f 75 6e 74 20 72 65 71 75   the amount requ
327a0 65 73 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  ested..**.** INV
327b0 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
327c0 46 31 37 33 34 31 7d 20 54 68 65 20 5b 73 71 6c  F17341} The [sql
327d0 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d  ite3_release_mem
327e0 6f 72 79 28 4e 29 5d 20 69 6e 74 65 72 66 61 63  ory(N)] interfac
327f0 65 20 61 74 74 65 6d 70 74 73 20 74 6f 0a 2a 2a  e attempts to.**
32800 20 20 20 20 20 20 20 20 20 20 66 72 65 65 20 4e            free N
32810 20 62 79 74 65 73 20 6f 66 20 68 65 61 70 20 6d   bytes of heap m
32820 65 6d 6f 72 79 20 62 79 20 64 65 61 6c 6c 6f 63  emory by dealloc
32830 61 74 69 6e 67 20 6e 6f 6e 2d 65 73 73 65 6e 74  ating non-essent
32840 69 61 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ial.**          
32850 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
32860 6e 73 20 68 65 6c 64 20 62 79 20 74 68 65 20 64  ns held by the d
32870 61 74 61 62 61 73 65 20 6c 61 62 72 61 72 79 2e  atabase labrary.
32880 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 33 34 32 7d 20  .**.** {F16342} 
32890 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c  The [sqlite3_rel
328a0 65 61 73 65 5f 6d 65 6d 6f 72 79 28 4e 29 5d 20  ease_memory(N)] 
328b0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
328c0 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  er.**          o
328d0 66 20 62 79 74 65 73 20 61 63 74 75 61 6c 6c 79  f bytes actually
328e0 20 66 72 65 65 64 2c 20 77 68 69 63 68 20 6d 69   freed, which mi
328f0 67 68 74 20 62 65 20 6d 6f 72 65 20 6f 72 20 6c  ght be more or l
32900 65 73 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ess.**          
32910 74 68 61 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20  than the amount 
32920 72 65 71 75 65 73 74 65 64 2e 0a 2a 2f 0a 69 6e  requested..*/.in
32930 74 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73  t sqlite3_releas
32940 65 5f 6d 65 6d 6f 72 79 28 69 6e 74 29 3b 0a 0a  e_memory(int);..
32950 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
32960 20 49 6d 70 6f 73 65 20 41 20 4c 69 6d 69 74 20   Impose A Limit 
32970 4f 6e 20 48 65 61 70 20 53 69 7a 65 20 7b 46 31  On Heap Size {F1
32980 37 33 35 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20  7350}.**.** The 
32990 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61  sqlite3_soft_hea
329a0 70 5f 6c 69 6d 69 74 28 29 20 69 6e 74 65 72 66  p_limit() interf
329b0 61 63 65 0a 2a 2a 20 70 6c 61 63 65 73 20 61 20  ace.** places a 
329c0 22 73 6f 66 74 22 20 6c 69 6d 69 74 20 6f 6e 20  "soft" limit on 
329d0 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 68 65  the amount of he
329e0 61 70 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 6d  ap memory that m
329f0 61 79 20 62 65 20 61 6c 6c 6f 63 61 74 65 64 0a  ay be allocated.
32a00 2a 2a 20 62 79 20 53 51 4c 69 74 65 2e 20 49 66  ** by SQLite. If
32a10 20 61 6e 20 69 6e 74 65 72 6e 61 6c 20 61 6c 6c   an internal all
32a20 6f 63 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65  ocation is reque
32a30 73 74 65 64 20 0a 2a 2a 20 74 68 61 74 20 77 6f  sted .** that wo
32a40 75 6c 64 20 65 78 63 65 65 64 20 74 68 65 20 73  uld exceed the s
32a50 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 2c 20  oft heap limit, 
32a60 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65  [sqlite3_release
32a70 5f 6d 65 6d 6f 72 79 28 29 5d 20 69 73 0a 2a 2a  _memory()] is.**
32a80 20 69 6e 76 6f 6b 65 64 20 6f 6e 65 20 6f 72 20   invoked one or 
32a90 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 66 72  more times to fr
32aa0 65 65 20 75 70 20 73 6f 6d 65 20 73 70 61 63 65  ee up some space
32ab0 20 62 65 66 6f 72 65 20 74 68 65 20 61 6c 6c 6f   before the allo
32ac0 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6d 61 64  cation.** is mad
32ad0 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 6d  e..**.** The lim
32ae0 69 74 20 69 73 20 63 61 6c 6c 65 64 20 22 73 6f  it is called "so
32af0 66 74 22 2c 20 62 65 63 61 75 73 65 20 69 66 0a  ft", because if.
32b00 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65  ** [sqlite3_rele
32b10 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 63 61  ase_memory()] ca
32b20 6e 6e 6f 74 0a 2a 2a 20 66 72 65 65 20 73 75 66  nnot.** free suf
32b30 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 74  ficient memory t
32b40 6f 20 70 72 65 76 65 6e 74 20 74 68 65 20 6c 69  o prevent the li
32b50 6d 69 74 20 66 72 6f 6d 20 62 65 69 6e 67 20 65  mit from being e
32b60 78 63 65 65 64 65 64 2c 0a 2a 2a 20 74 68 65 20  xceeded,.** the 
32b70 6d 65 6d 6f 72 79 20 69 73 20 61 6c 6c 6f 63 61  memory is alloca
32b80 74 65 64 20 61 6e 79 77 61 79 20 61 6e 64 20 74  ted anyway and t
32b90 68 65 20 63 75 72 72 65 6e 74 20 6f 70 65 72 61  he current opera
32ba0 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 2e 0a 2a  tion proceeds..*
32bb0 2a 0a 2a 2a 20 41 20 6e 65 67 61 74 69 76 65 20  *.** A negative 
32bc0 6f 72 20 7a 65 72 6f 20 76 61 6c 75 65 20 66 6f  or zero value fo
32bd0 72 20 4e 20 6d 65 61 6e 73 20 74 68 61 74 20 74  r N means that t
32be0 68 65 72 65 20 69 73 20 6e 6f 20 73 6f 66 74 20  here is no soft 
32bf0 68 65 61 70 20 6c 69 6d 69 74 20 61 6e 64 0a 2a  heap limit and.*
32c00 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61  * [sqlite3_relea
32c10 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 77 69 6c  se_memory()] wil
32c20 6c 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64  l only be called
32c30 20 77 68 65 6e 20 6d 65 6d 6f 72 79 20 69 73 20   when memory is 
32c40 65 78 68 61 75 73 74 65 64 2e 0a 2a 2a 20 54 68  exhausted..** Th
32c50 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20  e default value 
32c60 66 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65 61  for the soft hea
32c70 70 20 6c 69 6d 69 74 20 69 73 20 7a 65 72 6f 2e  p limit is zero.
32c80 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61  .**.** SQLite ma
32c90 6b 65 73 20 61 20 62 65 73 74 20 65 66 66 6f 72  kes a best effor
32ca0 74 20 74 6f 20 68 6f 6e 6f 72 20 74 68 65 20 73  t to honor the s
32cb0 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 2e 20  oft heap limit. 
32cc0 20 0a 2a 2a 20 42 75 74 20 69 66 20 74 68 65 20   .** But if the 
32cd0 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20  soft heap limit 
32ce0 63 61 6e 6e 6f 74 20 68 6f 6e 6f 72 65 64 2c 20  cannot honored, 
32cf0 65 78 65 63 75 74 69 6f 6e 20 77 69 6c 6c 0a 2a  execution will.*
32d00 2a 20 63 6f 6e 74 69 6e 75 65 20 77 69 74 68 6f  * continue witho
32d10 75 74 20 65 72 72 6f 72 20 6f 72 20 6e 6f 74 69  ut error or noti
32d20 66 69 63 61 74 69 6f 6e 2e 20 20 54 68 69 73 20  fication.  This 
32d30 69 73 20 77 68 79 20 74 68 65 20 6c 69 6d 69 74  is why the limit
32d40 20 69 73 20 0a 2a 2a 20 63 61 6c 6c 65 64 20 61   is .** called a
32d50 20 22 73 6f 66 74 22 20 6c 69 6d 69 74 2e 20 20   "soft" limit.  
32d60 49 74 20 69 73 20 61 64 76 69 73 6f 72 79 20 6f  It is advisory o
32d70 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72  nly..**.** Prior
32d80 20 74 6f 20 53 51 4c 69 74 65 20 76 65 72 73 69   to SQLite versi
32d90 6f 6e 20 33 2e 35 2e 30 2c 20 74 68 69 73 20 72  on 3.5.0, this r
32da0 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 63 6f 6e 73  outine only cons
32db0 74 72 61 69 6e 65 64 20 74 68 65 20 6d 65 6d 6f  trained the memo
32dc0 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 64 20  ry.** allocated 
32dd0 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65  by a single thre
32de0 61 64 20 2d 20 74 68 65 20 73 61 6d 65 20 74 68  ad - the same th
32df0 72 65 61 64 20 69 6e 20 77 68 69 63 68 20 74 68  read in which th
32e00 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 75  is routine.** ru
32e10 6e 73 2e 20 20 42 65 67 69 6e 6e 69 6e 67 20 77  ns.  Beginning w
32e20 69 74 68 20 53 51 4c 69 74 65 20 76 65 72 73 69  ith SQLite versi
32e30 6f 6e 20 33 2e 35 2e 30 2c 20 74 68 65 20 73 6f  on 3.5.0, the so
32e40 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73  ft heap limit is
32e50 0a 2a 2a 20 61 70 70 6c 69 65 64 20 74 6f 20 61  .** applied to a
32e60 6c 6c 20 74 68 72 65 61 64 73 2e 20 54 68 65 20  ll threads. The 
32e70 76 61 6c 75 65 20 73 70 65 63 69 66 69 65 64 20  value specified 
32e80 66 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65 61  for the soft hea
32e90 70 20 6c 69 6d 69 74 0a 2a 2a 20 69 73 20 61 6e  p limit.** is an
32ea0 20 75 70 70 65 72 20 62 6f 75 6e 64 20 6f 6e 20   upper bound on 
32eb0 74 68 65 20 74 6f 74 61 6c 20 6d 65 6d 6f 72 79  the total memory
32ec0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20   allocation for 
32ed0 61 6c 6c 20 74 68 72 65 61 64 73 2e 20 49 6e 0a  all threads. In.
32ee0 2a 2a 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30  ** version 3.5.0
32ef0 20 74 68 65 72 65 20 69 73 20 6e 6f 20 6d 65 63   there is no mec
32f00 68 61 6e 69 73 6d 20 66 6f 72 20 6c 69 6d 69 74  hanism for limit
32f10 69 6e 67 20 74 68 65 20 68 65 61 70 20 75 73 61  ing the heap usa
32f20 67 65 20 66 6f 72 0a 2a 2a 20 69 6e 64 69 76 69  ge for.** indivi
32f30 64 75 61 6c 20 74 68 72 65 61 64 73 2e 0a 2a 2a  dual threads..**
32f40 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
32f50 2a 2a 0a 2a 2a 20 7b 46 31 36 33 35 31 7d 20 54  **.** {F16351} T
32f60 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74  he [sqlite3_soft
32f70 5f 68 65 61 70 5f 6c 69 6d 69 74 28 4e 29 5d 20  _heap_limit(N)] 
32f80 69 6e 74 65 72 66 61 63 65 20 70 6c 61 63 65 73  interface places
32f90 20 61 20 73 6f 66 74 20 6c 69 6d 69 74 0a 2a 2a   a soft limit.**
32fa0 20 20 20 20 20 20 20 20 20 20 6f 66 20 4e 20 62            of N b
32fb0 79 74 65 73 20 6f 6e 20 74 68 65 20 61 6d 6f 75  ytes on the amou
32fc0 6e 74 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72  nt of heap memor
32fd0 79 20 74 68 61 74 20 6d 61 79 20 62 65 20 61 6c  y that may be al
32fe0 6c 6f 63 61 74 65 64 0a 2a 2a 20 20 20 20 20 20  located.**      
32ff0 20 20 20 20 75 73 69 6e 67 20 5b 73 71 6c 69 74      using [sqlit
33000 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20  e3_malloc()] or 
33010 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
33020 28 29 5d 20 61 74 20 61 6e 79 20 70 6f 69 6e 74  ()] at any point
33030 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20  .**          in 
33040 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  time..**.** {F16
33050 33 35 32 7d 20 49 66 20 61 20 63 61 6c 6c 20 74  352} If a call t
33060 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  o [sqlite3_mallo
33070 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  c()] or [sqlite3
33080 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 77 6f 75 6c  _realloc()] woul
33090 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61  d.**          ca
330a0 75 73 65 20 74 68 65 20 74 6f 74 61 6c 20 61 6d  use the total am
330b0 6f 75 6e 74 20 6f 66 20 61 6c 6c 6f 63 61 74 65  ount of allocate
330c0 64 20 6d 65 6d 6f 72 79 20 74 6f 20 65 78 63 65  d memory to exce
330d0 65 64 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ed the.**       
330e0 20 20 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d     soft heap lim
330f0 69 74 2c 20 74 68 65 6e 20 5b 73 71 6c 69 74 65  it, then [sqlite
33100 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79  3_release_memory
33110 28 29 5d 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a  ()] is invoked.*
33120 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 61 6e  *          in an
33130 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 64 75   attempt to redu
33140 63 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 75 73  ce the memory us
33150 61 67 65 20 70 72 69 6f 72 20 74 6f 20 70 72 6f  age prior to pro
33160 63 65 65 64 69 6e 67 0a 2a 2a 20 20 20 20 20 20  ceeding.**      
33170 20 20 20 20 77 69 74 68 20 74 68 65 20 6d 65 6d      with the mem
33180 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61  ory allocation a
33190 74 74 65 6d 70 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46  ttempt..**.** {F
331a0 31 36 33 35 33 7d 20 43 61 6c 6c 73 20 74 6f 20  16353} Calls to 
331b0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
331c0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
331d0 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 74  ealloc()] that t
331e0 72 69 67 67 65 72 0a 2a 2a 20 20 20 20 20 20 20  rigger.**       
331f0 20 20 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72     attempts to r
33200 65 64 75 63 65 20 6d 65 6d 6f 72 79 20 75 73 61  educe memory usa
33210 67 65 20 74 68 72 6f 75 67 68 20 74 68 65 20 73  ge through the s
33220 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 0a 2a  oft heap limit.*
33230 2a 20 20 20 20 20 20 20 20 20 20 6d 65 63 68 61  *          mecha
33240 6e 69 73 6d 20 63 6f 6e 74 69 6e 75 65 20 65 76  nism continue ev
33250 65 6e 20 69 66 20 74 68 65 20 61 74 74 65 6d 70  en if the attemp
33260 74 20 74 6f 20 72 65 64 75 63 65 20 6d 65 6d 6f  t to reduce memo
33270 72 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 75  ry.**          u
33280 73 61 67 65 20 69 73 20 75 6e 73 75 63 63 65 73  sage is unsucces
33290 73 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  sful..**.** {F16
332a0 33 35 34 7d 20 41 20 6e 65 67 61 74 69 76 65 20  354} A negative 
332b0 6f 72 20 7a 65 72 6f 20 76 61 6c 75 65 20 66 6f  or zero value fo
332c0 72 20 4e 20 69 6e 20 61 20 63 61 6c 6c 20 74 6f  r N in a call to
332d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
332e0 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f  lite3_soft_heap_
332f0 6c 69 6d 69 74 28 4e 29 5d 20 6d 65 61 6e 73 20  limit(N)] means 
33300 74 68 61 74 20 74 68 65 72 65 20 69 73 20 6e 6f  that there is no
33310 20 73 6f 66 74 0a 2a 2a 20 20 20 20 20 20 20 20   soft.**        
33320 20 20 68 65 61 70 20 6c 69 6d 69 74 20 61 6e 64    heap limit and
33330 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73   [sqlite3_releas
33340 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 77 69 6c 6c  e_memory()] will
33350 20 6f 6e 6c 79 20 62 65 0a 2a 2a 20 20 20 20 20   only be.**     
33360 20 20 20 20 20 63 61 6c 6c 65 64 20 77 68 65 6e       called when
33370 20 6d 65 6d 6f 72 79 20 69 73 20 63 6f 6d 70 6c   memory is compl
33380 65 74 65 6c 79 20 65 78 68 61 75 73 74 65 64 2e  etely exhausted.
33390 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 33 35 35 7d 20  .**.** {F16355} 
333a0 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75  The default valu
333b0 65 20 66 6f 72 20 74 68 65 20 73 6f 66 74 20 68  e for the soft h
333c0 65 61 70 20 6c 69 6d 69 74 20 69 73 20 7a 65 72  eap limit is zer
333d0 6f 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 33 35 38  o..**.** {F16358
333e0 7d 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 5b  } Each call to [
333f0 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61  sqlite3_soft_hea
33400 70 5f 6c 69 6d 69 74 28 4e 29 5d 20 6f 76 65 72  p_limit(N)] over
33410 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 20 20 20  rides the.**    
33420 20 20 20 20 20 20 76 61 6c 75 65 73 20 73 65 74        values set
33430 20 62 79 20 61 6c 6c 20 70 72 69 6f 72 20 63 61   by all prior ca
33440 6c 6c 73 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  lls..*/.void sql
33450 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c  ite3_soft_heap_l
33460 69 6d 69 74 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  imit(int);../*.*
33470 2a 20 43 41 50 49 33 52 45 46 3a 20 20 45 78 74  * CAPI3REF:  Ext
33480 72 61 63 74 20 4d 65 74 61 64 61 74 61 20 41 62  ract Metadata Ab
33490 6f 75 74 20 41 20 43 6f 6c 75 6d 6e 20 4f 66 20  out A Column Of 
334a0 41 20 54 61 62 6c 65 20 7b 46 31 32 38 35 30 7d  A Table {F12850}
334b0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
334c0 69 6e 65 0a 2a 2a 20 72 65 74 75 72 6e 73 20 6d  ine.** returns m
334d0 65 74 61 2d 64 61 74 61 20 61 62 6f 75 74 20 61  eta-data about a
334e0 20 73 70 65 63 69 66 69 63 20 63 6f 6c 75 6d 6e   specific column
334f0 20 6f 66 20 61 20 73 70 65 63 69 66 69 63 20 64   of a specific d
33500 61 74 61 62 61 73 65 0a 2a 2a 20 74 61 62 6c 65  atabase.** table
33510 20 61 63 63 65 73 73 69 62 6c 65 20 75 73 69 6e   accessible usin
33520 67 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  g the connection
33530 20 68 61 6e 64 6c 65 20 70 61 73 73 65 64 20 61   handle passed a
33540 73 20 74 68 65 20 66 69 72 73 74 20 66 75 6e 63  s the first func
33550 74 69 6f 6e 20 0a 2a 2a 20 61 72 67 75 6d 65 6e  tion .** argumen
33560 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6c  t..**.** The col
33570 75 6d 6e 20 69 73 20 69 64 65 6e 74 69 66 69 65  umn is identifie
33580 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 2c  d by the second,
33590 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74   third and fourt
335a0 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  h parameters to 
335b0 0a 2a 2a 20 74 68 69 73 20 66 75 6e 63 74 69 6f  .** this functio
335c0 6e 2e 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  n. The second pa
335d0 72 61 6d 65 74 65 72 20 69 73 20 65 69 74 68 65  rameter is eithe
335e0 72 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  r the name of th
335f0 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 28 69  e database.** (i
33600 2e 65 2e 20 22 6d 61 69 6e 22 2c 20 22 74 65 6d  .e. "main", "tem
33610 70 22 20 6f 72 20 61 6e 20 61 74 74 61 63 68 65  p" or an attache
33620 64 20 64 61 74 61 62 61 73 65 29 20 63 6f 6e 74  d database) cont
33630 61 69 6e 69 6e 67 20 74 68 65 20 73 70 65 63 69  aining the speci
33640 66 69 65 64 0a 2a 2a 20 74 61 62 6c 65 20 6f 72  fied.** table or
33650 20 4e 55 4c 4c 2e 20 49 66 20 69 74 20 69 73 20   NULL. If it is 
33660 4e 55 4c 4c 2c 20 74 68 65 6e 20 61 6c 6c 20 61  NULL, then all a
33670 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65  ttached database
33680 73 20 61 72 65 20 73 65 61 72 63 68 65 64 0a 2a  s are searched.*
33690 2a 20 66 6f 72 20 74 68 65 20 74 61 62 6c 65 20  * for the table 
336a0 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20 61  using the same a
336b0 6c 67 6f 72 69 74 68 6d 20 61 73 20 74 68 65 20  lgorithm as the 
336c0 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20  database engine 
336d0 75 73 65 73 20 74 6f 20 0a 2a 2a 20 72 65 73 6f  uses to .** reso
336e0 6c 76 65 20 75 6e 71 75 61 6c 69 66 69 65 64 20  lve unqualified 
336f0 74 61 62 6c 65 20 72 65 66 65 72 65 6e 63 65 73  table references
33700 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72  ..**.** The thir
33710 64 20 61 6e 64 20 66 6f 75 72 74 68 20 70 61 72  d and fourth par
33720 61 6d 65 74 65 72 73 20 74 6f 20 74 68 69 73 20  ameters to this 
33730 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 74 68 65  function are the
33740 20 74 61 62 6c 65 20 61 6e 64 20 63 6f 6c 75 6d   table and colum
33750 6e 20 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20 74 68  n .** name of th
33760 65 20 64 65 73 69 72 65 64 20 63 6f 6c 75 6d 6e  e desired column
33770 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20  , respectively. 
33780 4e 65 69 74 68 65 72 20 6f 66 20 74 68 65 73 65  Neither of these
33790 20 70 61 72 61 6d 65 74 65 72 73 20 0a 2a 2a 20   parameters .** 
337a0 6d 61 79 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a  may be NULL..**.
337b0 2a 2a 20 4d 65 74 61 20 69 6e 66 6f 72 6d 61 74  ** Meta informat
337c0 69 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 64 20  ion is returned 
337d0 62 79 20 77 72 69 74 69 6e 67 20 74 6f 20 74 68  by writing to th
337e0 65 20 6d 65 6d 6f 72 79 20 6c 6f 63 61 74 69 6f  e memory locatio
337f0 6e 73 20 70 61 73 73 65 64 20 61 73 0a 2a 2a 20  ns passed as.** 
33800 74 68 65 20 35 74 68 20 61 6e 64 20 73 75 62 73  the 5th and subs
33810 65 71 75 65 6e 74 20 70 61 72 61 6d 65 74 65 72  equent parameter
33820 73 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69  s to this functi
33830 6f 6e 2e 20 41 6e 79 20 6f 66 20 74 68 65 73 65  on. Any of these
33840 20 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 6d   .** arguments m
33850 61 79 20 62 65 20 4e 55 4c 4c 2c 20 69 6e 20 77  ay be NULL, in w
33860 68 69 63 68 20 63 61 73 65 20 74 68 65 20 63 6f  hich case the co
33870 72 72 65 73 70 6f 6e 64 69 6e 67 20 65 6c 65 6d  rresponding elem
33880 65 6e 74 20 6f 66 20 6d 65 74 61 20 0a 2a 2a 20  ent of meta .** 
33890 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 6f  information is o
338a0 6d 6d 69 74 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  mmitted..**.** <
338b0 70 72 65 3e 0a 2a 2a 20 50 61 72 61 6d 65 74 65  pre>.** Paramete
338c0 72 20 20 20 20 20 4f 75 74 70 75 74 20 54 79 70  r     Output Typ
338d0 65 20 20 20 20 20 20 44 65 73 63 72 69 70 74 69  e      Descripti
338e0 6f 6e 0a 2a 2a 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  on.** ----------
338f0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
33900 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 0a 2a 2a 20  ---------.**.** 
33910 20 20 35 74 68 20 20 20 20 20 20 20 20 20 63 6f    5th         co
33920 6e 73 74 20 63 68 61 72 2a 20 20 20 20 20 20 44  nst char*      D
33930 61 74 61 20 74 79 70 65 0a 2a 2a 20 20 20 36 74  ata type.**   6t
33940 68 20 20 20 20 20 20 20 20 20 63 6f 6e 73 74 20  h         const 
33950 63 68 61 72 2a 20 20 20 20 20 20 4e 61 6d 65 20  char*      Name 
33960 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 63  of the default c
33970 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
33980 65 20 0a 2a 2a 20 20 20 37 74 68 20 20 20 20 20  e .**   7th     
33990 20 20 20 20 69 6e 74 20 20 20 20 20 20 20 20 20      int         
339a0 20 20 20 20 20 54 72 75 65 20 69 66 20 74 68 65       True if the
339b0 20 63 6f 6c 75 6d 6e 20 68 61 73 20 61 20 4e 4f   column has a NO
339c0 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69 6e  T NULL constrain
339d0 74 0a 2a 2a 20 20 20 38 74 68 20 20 20 20 20 20  t.**   8th      
339e0 20 20 20 69 6e 74 20 20 20 20 20 20 20 20 20 20     int          
339f0 20 20 20 20 54 72 75 65 20 69 66 20 74 68 65 20      True if the 
33a00 63 6f 6c 75 6d 6e 20 69 73 20 70 61 72 74 20 6f  column is part o
33a10 66 20 74 68 65 20 50 52 49 4d 41 52 59 20 4b 45  f the PRIMARY KE
33a20 59 0a 2a 2a 20 20 20 39 74 68 20 20 20 20 20 20  Y.**   9th      
33a30 20 20 20 69 6e 74 20 20 20 20 20 20 20 20 20 20     int          
33a40 20 20 20 20 54 72 75 65 20 69 66 20 74 68 65 20      True if the 
33a50 63 6f 6c 75 6d 6e 20 69 73 20 41 55 54 4f 49 4e  column is AUTOIN
33a60 43 52 45 4d 45 4e 54 0a 2a 2a 20 3c 2f 70 72 65  CREMENT.** </pre
33a70 3e 0a 2a 2a 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d  >.**.**.** The m
33a80 65 6d 6f 72 79 20 70 6f 69 6e 74 65 64 20 74 6f  emory pointed to
33a90 20 62 79 20 74 68 65 20 63 68 61 72 61 63 74 65   by the characte
33aa0 72 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72  r pointers retur
33ab0 6e 65 64 20 66 6f 72 20 74 68 65 20 0a 2a 2a 20  ned for the .** 
33ac0 64 65 63 6c 61 72 61 74 69 6f 6e 20 74 79 70 65  declaration type
33ad0 20 61 6e 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73   and collation s
33ae0 65 71 75 65 6e 63 65 20 69 73 20 76 61 6c 69 64  equence is valid
33af0 20 6f 6e 6c 79 20 75 6e 74 69 6c 20 74 68 65 20   only until the 
33b00 6e 65 78 74 20 0a 2a 2a 20 63 61 6c 6c 20 74 6f  next .** call to
33b10 20 61 6e 79 20 73 71 6c 69 74 65 20 41 50 49 20   any sqlite API 
33b20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  function..**.** 
33b30 49 66 20 74 68 65 20 73 70 65 63 69 66 69 65 64  If the specified
33b40 20 74 61 62 6c 65 20 69 73 20 61 63 74 75 61 6c   table is actual
33b50 6c 79 20 61 20 76 69 65 77 2c 20 74 68 65 6e 20  ly a view, then 
33b60 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  an error is retu
33b70 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  rned..**.** If t
33b80 68 65 20 73 70 65 63 69 66 69 65 64 20 63 6f 6c  he specified col
33b90 75 6d 6e 20 69 73 20 22 72 6f 77 69 64 22 2c 20  umn is "rowid", 
33ba0 22 6f 69 64 22 20 6f 72 20 22 5f 72 6f 77 69 64  "oid" or "_rowid
33bb0 5f 22 20 61 6e 64 20 61 6e 20 0a 2a 2a 20 49 4e  _" and an .** IN
33bc0 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45  TEGER PRIMARY KE
33bd0 59 20 63 6f 6c 75 6d 6e 20 68 61 73 20 62 65 65  Y column has bee
33be0 6e 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63  n explicitly dec
33bf0 6c 61 72 65 64 2c 20 74 68 65 6e 20 74 68 65 20  lared, then the 
33c00 6f 75 74 70 75 74 20 0a 2a 2a 20 70 61 72 61 6d  output .** param
33c10 65 74 65 72 73 20 61 72 65 20 73 65 74 20 66 6f  eters are set fo
33c20 72 20 74 68 65 20 65 78 70 6c 69 63 69 74 6c 79  r the explicitly
33c30 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e   declared column
33c40 2e 20 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f  . If there is no
33c50 0a 2a 2a 20 65 78 70 6c 69 63 69 74 6c 79 20 64  .** explicitly d
33c60 65 63 6c 61 72 65 64 20 49 50 4b 20 63 6f 6c 75  eclared IPK colu
33c70 6d 6e 2c 20 74 68 65 6e 20 74 68 65 20 6f 75 74  mn, then the out
33c80 70 75 74 20 70 61 72 61 6d 65 74 65 72 73 20 61  put parameters a
33c90 72 65 20 73 65 74 20 61 73 20 0a 2a 2a 20 66 6f  re set as .** fo
33ca0 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72  llows:.**.** <pr
33cb0 65 3e 0a 2a 2a 20 20 20 20 20 64 61 74 61 20 74  e>.**     data t
33cc0 79 70 65 3a 20 22 49 4e 54 45 47 45 52 22 0a 2a  ype: "INTEGER".*
33cd0 2a 20 20 20 20 20 63 6f 6c 6c 61 74 69 6f 6e 20  *     collation 
33ce0 73 65 71 75 65 6e 63 65 3a 20 22 42 49 4e 41 52  sequence: "BINAR
33cf0 59 22 0a 2a 2a 20 20 20 20 20 6e 6f 74 20 6e 75  Y".**     not nu
33d00 6c 6c 3a 20 30 0a 2a 2a 20 20 20 20 20 70 72 69  ll: 0.**     pri
33d10 6d 61 72 79 20 6b 65 79 3a 20 31 0a 2a 2a 20 20  mary key: 1.**  
33d20 20 20 20 61 75 74 6f 20 69 6e 63 72 65 6d 65 6e     auto incremen
33d30 74 3a 20 30 0a 2a 2a 20 3c 2f 70 72 65 3e 0a 2a  t: 0.** </pre>.*
33d40 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69  *.** This functi
33d50 6f 6e 20 6d 61 79 20 6c 6f 61 64 20 6f 6e 65 20  on may load one 
33d60 6f 72 20 6d 6f 72 65 20 73 63 68 65 6d 61 73 20  or more schemas 
33d70 66 72 6f 6d 20 64 61 74 61 62 61 73 65 20 66 69  from database fi
33d80 6c 65 73 2e 20 49 66 20 61 6e 0a 2a 2a 20 65 72  les. If an.** er
33d90 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e  ror occurs durin
33da0 67 20 74 68 69 73 20 70 72 6f 63 65 73 73 2c 20  g this process, 
33db0 6f 72 20 69 66 20 74 68 65 20 72 65 71 75 65 73  or if the reques
33dc0 74 65 64 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c  ted table or col
33dd0 75 6d 6e 0a 2a 2a 20 63 61 6e 6e 6f 74 20 62 65  umn.** cannot be
33de0 20 66 6f 75 6e 64 2c 20 61 6e 20 53 51 4c 49 54   found, an SQLIT
33df0 45 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20  E error code is 
33e00 72 65 74 75 72 6e 65 64 20 61 6e 64 20 61 6e 20  returned and an 
33e10 65 72 72 6f 72 20 6d 65 73 73 61 67 65 0a 2a 2a  error message.**
33e20 20 6c 65 66 74 20 69 6e 20 74 68 65 20 64 61 74   left in the dat
33e30 61 62 61 73 65 20 68 61 6e 64 6c 65 20 28 74 6f  abase handle (to
33e40 20 62 65 20 72 65 74 72 69 65 76 65 64 20 75 73   be retrieved us
33e50 69 6e 67 20 73 71 6c 69 74 65 33 5f 65 72 72 6d  ing sqlite3_errm
33e60 73 67 28 29 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  sg())..**.** Thi
33e70 73 20 41 50 49 20 69 73 20 6f 6e 6c 79 20 61 76  s API is only av
33e80 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c  ailable if the l
33e90 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69  ibrary was compi
33ea0 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  led with the.** 
33eb0 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f  SQLITE_ENABLE_CO
33ec0 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 20 70 72  LUMN_METADATA pr
33ed0 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f  eprocessor symbo
33ee0 6c 20 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e  l defined..*/.in
33ef0 74 20 73 71 6c 69 74 65 33 5f 74 61 62 6c 65 5f  t sqlite3_table_
33f00 63 6f 6c 75 6d 6e 5f 6d 65 74 61 64 61 74 61 28  column_metadata(
33f10 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
33f20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
33f30 2a 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 68 61 6e  * Connection han
33f40 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
33f50 68 61 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 20 20  har *zDbName,   
33f60 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
33f70 20 6e 61 6d 65 20 6f 72 20 4e 55 4c 4c 20 2a 2f   name or NULL */
33f80 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
33f90 54 61 62 6c 65 4e 61 6d 65 2c 20 20 20 20 20 2f  TableName,     /
33fa0 2a 20 54 61 62 6c 65 20 6e 61 6d 65 20 2a 2f 0a  * Table name */.
33fb0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 43    const char *zC
33fc0 6f 6c 75 6d 6e 4e 61 6d 65 2c 20 20 20 20 2f 2a  olumnName,    /*
33fd0 20 43 6f 6c 75 6d 6e 20 6e 61 6d 65 20 2a 2f 0a   Column name */.
33fe0 20 20 63 68 61 72 20 63 6f 6e 73 74 20 2a 2a 70    char const **p
33ff0 7a 44 61 74 61 54 79 70 65 2c 20 20 20 20 2f 2a  zDataType,    /*
34000 20 4f 55 54 50 55 54 3a 20 44 65 63 6c 61 72 65   OUTPUT: Declare
34010 64 20 64 61 74 61 20 74 79 70 65 20 2a 2f 0a 20  d data type */. 
34020 20 63 68 61 72 20 63 6f 6e 73 74 20 2a 2a 70 7a   char const **pz
34030 43 6f 6c 6c 53 65 71 2c 20 20 20 20 20 2f 2a 20  CollSeq,     /* 
34040 4f 55 54 50 55 54 3a 20 43 6f 6c 6c 61 74 69 6f  OUTPUT: Collatio
34050 6e 20 73 65 71 75 65 6e 63 65 20 6e 61 6d 65 20  n sequence name 
34060 2a 2f 0a 20 20 69 6e 74 20 2a 70 4e 6f 74 4e 75  */.  int *pNotNu
34070 6c 6c 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  ll,             
34080 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65   /* OUTPUT: True
34090 20 69 66 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e   if NOT NULL con
340a0 73 74 72 61 69 6e 74 20 65 78 69 73 74 73 20 2a  straint exists *
340b0 2f 0a 20 20 69 6e 74 20 2a 70 50 72 69 6d 61 72  /.  int *pPrimar
340c0 79 4b 65 79 2c 20 20 20 20 20 20 20 20 20 20 20  yKey,           
340d0 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65 20  /* OUTPUT: True 
340e0 69 66 20 63 6f 6c 75 6d 6e 20 70 61 72 74 20 6f  if column part o
340f0 66 20 50 4b 20 2a 2f 0a 20 20 69 6e 74 20 2a 70  f PK */.  int *p
34100 41 75 74 6f 69 6e 63 20 20 20 20 20 20 20 20 20  Autoinc         
34110 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a        /* OUTPUT:
34120 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20   True if column 
34130 69 73 20 61 75 74 6f 2d 69 6e 63 72 65 6d 65 6e  is auto-incremen
34140 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  t */.);../*.** C
34150 41 50 49 33 52 45 46 3a 20 4c 6f 61 64 20 41 6e  API3REF: Load An
34160 20 45 78 74 65 6e 73 69 6f 6e 20 7b 46 31 32 36   Extension {F126
34170 30 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36 30  00}.**.** {F1260
34180 31 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6c  1} The sqlite3_l
34190 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20  oad_extension() 
341a0 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 61 74 74  interface.** att
341b0 65 6d 70 74 73 20 74 6f 20 6c 6f 61 64 20 61 6e  empts to load an
341c0 20 53 51 4c 69 74 65 20 65 78 74 65 6e 73 69 6f   SQLite extensio
341d0 6e 20 6c 69 62 72 61 72 79 20 63 6f 6e 74 61 69  n library contai
341e0 6e 65 64 20 69 6e 20 74 68 65 20 66 69 6c 65 0a  ned in the file.
341f0 2a 2a 20 7a 46 69 6c 65 2e 20 7b 46 31 32 36 30  ** zFile. {F1260
34200 32 7d 20 54 68 65 20 65 6e 74 72 79 20 70 6f 69  2} The entry poi
34210 6e 74 20 69 73 20 7a 50 72 6f 63 2e 20 7b 46 31  nt is zProc. {F1
34220 32 36 30 33 7d 20 7a 50 72 6f 63 20 6d 61 79 20  2603} zProc may 
34230 62 65 20 30 0a 2a 2a 20 69 6e 20 77 68 69 63 68  be 0.** in which
34240 20 63 61 73 65 20 74 68 65 20 6e 61 6d 65 20 6f   case the name o
34250 66 20 74 68 65 20 65 6e 74 72 79 20 70 6f 69 6e  f the entry poin
34260 74 20 64 65 66 61 75 6c 74 73 0a 2a 2a 20 74 6f  t defaults.** to
34270 20 22 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 73   "sqlite3_extens
34280 69 6f 6e 5f 69 6e 69 74 22 2e 0a 2a 2a 0a 2a 2a  ion_init"..**.**
34290 20 7b 46 31 32 36 30 34 7d 20 54 68 65 20 73 71   {F12604} The sq
342a0 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e  lite3_load_exten
342b0 73 69 6f 6e 28 29 20 69 6e 74 65 72 66 61 63 65  sion() interface
342c0 20 73 68 61 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e   shall.** return
342d0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20   [SQLITE_OK] on 
342e0 73 75 63 63 65 73 73 20 61 6e 64 20 5b 53 51 4c  success and [SQL
342f0 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 73 6f  ITE_ERROR] if so
34300 6d 65 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f  mething goes wro
34310 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36 30  ng..**.** {F1260
34320 35 7d 0a 2a 2a 20 49 66 20 61 6e 20 65 72 72 6f  5}.** If an erro
34330 72 20 6f 63 63 75 72 73 20 61 6e 64 20 70 7a 45  r occurs and pzE
34340 72 72 4d 73 67 20 69 73 20 6e 6f 74 20 30 2c 20  rrMsg is not 0, 
34350 74 68 65 6e 20 74 68 65 0a 2a 2a 20 73 71 6c 69  then the.** sqli
34360 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69  te3_load_extensi
34370 6f 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  on() interface s
34380 68 61 6c 6c 20 61 74 74 65 6d 70 74 20 74 6f 20  hall attempt to 
34390 66 69 6c 6c 20 2a 70 7a 45 72 72 4d 73 67 20 77  fill *pzErrMsg w
343a0 69 74 68 20 0a 2a 2a 20 65 72 72 6f 72 20 6d 65  ith .** error me
343b0 73 73 61 67 65 20 74 65 78 74 20 73 74 6f 72 65  ssage text store
343c0 64 20 69 6e 20 6d 65 6d 6f 72 79 20 6f 62 74 61  d in memory obta
343d0 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
343e0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a  e3_malloc()]..**
343f0 20 7b 45 4e 44 7d 20 20 54 68 65 20 63 61 6c 6c   {END}  The call
34400 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f  ing function sho
34410 75 6c 64 20 66 72 65 65 20 74 68 69 73 20 6d 65  uld free this me
34420 6d 6f 72 79 0a 2a 2a 20 62 79 20 63 61 6c 6c 69  mory.** by calli
34430 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ng [sqlite3_free
34440 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36  ()]..**.** {F126
34450 30 36 7d 0a 2a 2a 20 45 78 74 65 6e 73 69 6f 6e  06}.** Extension
34460 20 6c 6f 61 64 69 6e 67 20 6d 75 73 74 20 62 65   loading must be
34470 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 20 5b   enabled using [
34480 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c  sqlite3_enable_l
34490 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d  oad_extension()]
344a0 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63 61 6c  .** prior to cal
344b0 6c 69 6e 67 20 74 68 69 73 20 41 50 49 20 6f 72  ling this API or
344c0 20 61 6e 20 65 72 72 6f 72 20 77 69 6c 6c 20 62   an error will b
344d0 65 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2f 0a 69  e returned..*/.i
344e0 6e 74 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f  nt sqlite3_load_
344f0 65 78 74 65 6e 73 69 6f 6e 28 0a 20 20 73 71 6c  extension(.  sql
34500 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
34510 20 20 20 2f 2a 20 4c 6f 61 64 20 74 68 65 20 65     /* Load the e
34520 78 74 65 6e 73 69 6f 6e 20 69 6e 74 6f 20 74 68  xtension into th
34530 69 73 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  is database conn
34540 65 63 74 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73  ection */.  cons
34550 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 20  t char *zFile,  
34560 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65    /* Name of the
34570 20 73 68 61 72 65 64 20 6c 69 62 72 61 72 79 20   shared library 
34580 63 6f 6e 74 61 69 6e 69 6e 67 20 65 78 74 65 6e  containing exten
34590 73 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  sion */.  const 
345a0 63 68 61 72 20 2a 7a 50 72 6f 63 2c 20 20 20 20  char *zProc,    
345b0 2f 2a 20 45 6e 74 72 79 20 70 6f 69 6e 74 2e 20  /* Entry point. 
345c0 20 44 65 72 69 76 65 64 20 66 72 6f 6d 20 7a 46   Derived from zF
345d0 69 6c 65 20 69 66 20 30 20 2a 2f 0a 20 20 63 68  ile if 0 */.  ch
345e0 61 72 20 2a 2a 70 7a 45 72 72 4d 73 67 20 20 20  ar **pzErrMsg   
345f0 20 20 20 20 2f 2a 20 50 75 74 20 65 72 72 6f 72      /* Put error
34600 20 6d 65 73 73 61 67 65 20 68 65 72 65 20 69 66   message here if
34610 20 6e 6f 74 20 30 20 2a 2f 0a 29 3b 0a 0a 2f 2a   not 0 */.);../*
34620 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 45  .** CAPI3REF:  E
34630 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65  nable Or Disable
34640 20 45 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69   Extension Loadi
34650 6e 67 20 7b 46 31 32 36 32 30 7d 0a 2a 2a 0a 2a  ng {F12620}.**.*
34660 2a 20 53 6f 20 61 73 20 6e 6f 74 20 74 6f 20 6f  * So as not to o
34670 70 65 6e 20 73 65 63 75 72 69 74 79 20 68 6f 6c  pen security hol
34680 65 73 20 69 6e 20 6f 6c 64 65 72 20 61 70 70 6c  es in older appl
34690 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 61 72  ications that ar
346a0 65 0a 2a 2a 20 75 6e 70 72 65 70 61 72 65 64 20  e.** unprepared 
346b0 74 6f 20 64 65 61 6c 20 77 69 74 68 20 65 78 74  to deal with ext
346c0 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 2c 20  ension loading, 
346d0 61 6e 64 20 61 73 20 61 20 6d 65 61 6e 73 20 6f  and as a means o
346e0 66 20 64 69 73 61 62 6c 69 6e 67 0a 2a 2a 20 65  f disabling.** e
346f0 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67  xtension loading
34700 20 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69 6e   while evaluatin
34710 67 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53  g user-entered S
34720 51 4c 2c 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  QL, the followin
34730 67 0a 2a 2a 20 41 50 49 20 69 73 20 70 72 6f 76  g.** API is prov
34740 69 64 65 64 20 74 6f 20 74 75 72 6e 20 74 68 65  ided to turn the
34750 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65   [sqlite3_load_e
34760 78 74 65 6e 73 69 6f 6e 28 29 5d 20 6d 65 63 68  xtension()] mech
34770 61 6e 69 73 6d 20 6f 6e 20 61 6e 64 0a 2a 2a 20  anism on and.** 
34780 6f 66 66 2e 20 20 7b 46 31 32 36 32 32 7d 20 49  off.  {F12622} I
34790 74 20 69 73 20 6f 66 66 20 62 79 20 64 65 66 61  t is off by defa
347a0 75 6c 74 2e 20 7b 45 4e 44 7d 20 53 65 65 20 74  ult. {END} See t
347b0 69 63 6b 65 74 20 23 31 38 36 33 2e 0a 2a 2a 0a  icket #1863..**.
347c0 2a 2a 20 7b 46 31 32 36 32 31 7d 20 43 61 6c 6c  ** {F12621} Call
347d0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 6e 61   the sqlite3_ena
347e0 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69  ble_load_extensi
347f0 6f 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a 20  on() routine.** 
34800 77 69 74 68 20 6f 6e 6f 66 66 3d 3d 31 20 74 6f  with onoff==1 to
34810 20 74 75 72 6e 20 65 78 74 65 6e 73 69 6f 6e 20   turn extension 
34820 6c 6f 61 64 69 6e 67 20 6f 6e 0a 2a 2a 20 61 6e  loading on.** an
34830 64 20 63 61 6c 6c 20 69 74 20 77 69 74 68 20 6f  d call it with o
34840 6e 6f 66 66 3d 3d 30 20 74 6f 20 74 75 72 6e 20  noff==0 to turn 
34850 69 74 20 62 61 63 6b 20 6f 66 66 20 61 67 61 69  it back off agai
34860 6e 2e 20 7b 45 4e 44 7d 0a 2a 2f 0a 69 6e 74 20  n. {END}.*/.int 
34870 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c  sqlite3_enable_l
34880 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 73 71  oad_extension(sq
34890 6c 69 74 65 33 20 2a 64 62 2c 20 69 6e 74 20 6f  lite3 *db, int o
348a0 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  noff);../*.** CA
348b0 50 49 33 52 45 46 3a 20 4d 61 6b 65 20 41 72 72  PI3REF: Make Arr
348c0 61 6e 67 65 6d 65 6e 74 73 20 54 6f 20 41 75 74  angements To Aut
348d0 6f 6d 61 74 69 63 61 6c 6c 79 20 4c 6f 61 64 20  omatically Load 
348e0 41 6e 20 45 78 74 65 6e 73 69 6f 6e 20 7b 46 31  An Extension {F1
348f0 32 36 34 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  2640}.**.** {F12
34900 36 34 31 7d 20 54 68 69 73 20 66 75 6e 63 74 69  641} This functi
34910 6f 6e 0a 2a 2a 20 72 65 67 69 73 74 65 72 73 20  on.** registers 
34920 61 6e 20 65 78 74 65 6e 73 69 6f 6e 20 65 6e 74  an extension ent
34930 72 79 20 70 6f 69 6e 74 20 74 68 61 74 20 69 73  ry point that is
34940 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69   automatically i
34950 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 65 76  nvoked.** whenev
34960 65 72 20 61 20 6e 65 77 20 64 61 74 61 62 61 73  er a new databas
34970 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
34980 6f 70 65 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20  opened using.** 
34990 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
349a0 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  , [sqlite3_open1
349b0 36 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65  6()], or [sqlite
349c0 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 7b 45  3_open_v2()]. {E
349d0 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 41  ND}.**.** This A
349e0 50 49 20 63 61 6e 20 62 65 20 69 6e 76 6f 6b 65  PI can be invoke
349f0 64 20 61 74 20 70 72 6f 67 72 61 6d 20 73 74 61  d at program sta
34a00 72 74 75 70 20 69 6e 20 6f 72 64 65 72 20 74 6f  rtup in order to
34a10 20 72 65 67 69 73 74 65 72 0a 2a 2a 20 6f 6e 65   register.** one
34a20 20 6f 72 20 6d 6f 72 65 20 73 74 61 74 69 63 61   or more statica
34a30 6c 6c 79 20 6c 69 6e 6b 65 64 20 65 78 74 65 6e  lly linked exten
34a40 73 69 6f 6e 73 20 74 68 61 74 20 77 69 6c 6c 20  sions that will 
34a50 62 65 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20  be available.** 
34a60 74 6f 20 61 6c 6c 20 6e 65 77 20 64 61 74 61 62  to all new datab
34a70 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e  ase connections.
34a80 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36 34 32 7d 20  .**.** {F12642} 
34a90 44 75 70 6c 69 63 61 74 65 20 65 78 74 65 6e 73  Duplicate extens
34aa0 69 6f 6e 73 20 61 72 65 20 64 65 74 65 63 74 65  ions are detecte
34ab0 64 20 73 6f 20 63 61 6c 6c 69 6e 67 20 74 68 69  d so calling thi
34ac0 73 20 72 6f 75 74 69 6e 65 20 6d 75 6c 74 69 70  s routine multip
34ad0 6c 65 0a 2a 2a 20 74 69 6d 65 73 20 77 69 74 68  le.** times with
34ae0 20 74 68 65 20 73 61 6d 65 20 65 78 74 65 6e 73   the same extens
34af0 69 6f 6e 20 69 73 20 68 61 72 6d 6c 65 73 73 2e  ion is harmless.
34b00 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36 34 33 7d 20  .**.** {F12643} 
34b10 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f  This routine sto
34b20 72 65 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  res a pointer to
34b30 20 74 68 65 20 65 78 74 65 6e 73 69 6f 6e 20 69   the extension i
34b40 6e 20 61 6e 20 61 72 72 61 79 0a 2a 2a 20 74 68  n an array.** th
34b50 61 74 20 69 73 20 6f 62 74 61 69 6e 65 64 20 66  at is obtained f
34b60 72 6f 6d 20 73 71 6c 69 74 65 5f 6d 61 6c 6c 6f  rom sqlite_mallo
34b70 63 28 29 2e 20 7b 45 4e 44 7d 20 49 66 20 79 6f  c(). {END} If yo
34b80 75 20 72 75 6e 20 61 20 6d 65 6d 6f 72 79 20 6c  u run a memory l
34b90 65 61 6b 0a 2a 2a 20 63 68 65 63 6b 65 72 20 6f  eak.** checker o
34ba0 6e 20 79 6f 75 72 20 70 72 6f 67 72 61 6d 20 61  n your program a
34bb0 6e 64 20 69 74 20 72 65 70 6f 72 74 73 20 61 20  nd it reports a 
34bc0 6c 65 61 6b 20 62 65 63 61 75 73 65 20 6f 66 20  leak because of 
34bd0 74 68 69 73 0a 2a 2a 20 61 72 72 61 79 2c 20 74  this.** array, t
34be0 68 65 6e 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69  hen invoke [sqli
34bf0 74 65 33 5f 72 65 73 65 74 5f 61 75 74 6f 5f 65  te3_reset_auto_e
34c00 78 74 65 6e 73 69 6f 6e 28 29 5d 20 70 72 69 6f  xtension()] prio
34c10 72 0a 2a 2a 20 74 6f 20 73 68 75 74 64 6f 77 6e  r.** to shutdown
34c20 20 74 6f 20 66 72 65 65 20 74 68 65 20 6d 65 6d   to free the mem
34c30 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36  ory..**.** {F126
34c40 34 34 7d 20 41 75 74 6f 6d 61 74 69 63 20 65 78  44} Automatic ex
34c50 74 65 6e 73 69 6f 6e 73 20 61 70 70 6c 79 20 61  tensions apply a
34c60 63 72 6f 73 73 20 61 6c 6c 20 74 68 72 65 61 64  cross all thread
34c70 73 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54  s. {END}.**.** T
34c80 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73  his interface is
34c90 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e   experimental an
34ca0 64 20 69 73 20 73 75 62 6a 65 63 74 20 74 6f 20  d is subject to 
34cb0 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 72 65 6d  change or.** rem
34cc0 6f 76 61 6c 20 69 6e 20 66 75 74 75 72 65 20 72  oval in future r
34cd0 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
34ce0 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  e..*/.int sqlite
34cf0 33 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e  3_auto_extension
34d00 28 76 6f 69 64 20 2a 78 45 6e 74 72 79 50 6f 69  (void *xEntryPoi
34d10 6e 74 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  nt);.../*.** CAP
34d20 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 75 74  I3REF: Reset Aut
34d30 6f 6d 61 74 69 63 20 45 78 74 65 6e 73 69 6f 6e  omatic Extension
34d40 20 4c 6f 61 64 69 6e 67 20 7b 46 31 32 36 36 30   Loading {F12660
34d50 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36 36 31 7d  }.**.** {F12661}
34d60 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 64   This function d
34d70 69 73 61 62 6c 65 73 20 61 6c 6c 20 70 72 65 76  isables all prev
34d80 69 6f 75 73 6c 79 20 72 65 67 69 73 74 65 72 65  iously registere
34d90 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 20 65  d.** automatic e
34da0 78 74 65 6e 73 69 6f 6e 73 2e 20 7b 45 4e 44 7d  xtensions. {END}
34db0 20 20 54 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e    This.** routin
34dc0 65 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66  e undoes the eff
34dd0 65 63 74 20 6f 66 20 61 6c 6c 20 70 72 69 6f 72  ect of all prior
34de0 20 5b 73 71 6c 69 74 65 33 5f 61 75 74 6f 5f 65   [sqlite3_auto_e
34df0 78 74 65 6e 73 69 6f 6e 28 29 5d 0a 2a 2a 20 63  xtension()].** c
34e00 61 6c 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  alls..**.** {F12
34e10 36 36 32 7d 20 54 68 69 73 20 63 61 6c 6c 20 64  662} This call d
34e20 69 73 61 62 6c 65 64 20 61 75 74 6f 6d 61 74 69  isabled automati
34e30 63 20 65 78 74 65 6e 73 69 6f 6e 73 20 69 6e 20  c extensions in 
34e40 61 6c 6c 20 74 68 72 65 61 64 73 2e 20 7b 45 4e  all threads. {EN
34e50 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  D}.**.** This in
34e60 74 65 72 66 61 63 65 20 69 73 20 65 78 70 65 72  terface is exper
34e70 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 20 73  imental and is s
34e80 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65  ubject to change
34e90 20 6f 72 0a 2a 2a 20 72 65 6d 6f 76 61 6c 20 69   or.** removal i
34ea0 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
34eb0 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  s of SQLite..*/.
34ec0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
34ed0 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f  et_auto_extensio
34ee0 6e 28 76 6f 69 64 29 3b 0a 0a 0a 2f 2a 0a 2a 2a  n(void);.../*.**
34ef0 2a 2a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41  **** EXPERIMENTA
34f00 4c 20 2d 20 73 75 62 6a 65 63 74 20 74 6f 20 63  L - subject to c
34f10 68 61 6e 67 65 20 77 69 74 68 6f 75 74 20 6e 6f  hange without no
34f20 74 69 63 65 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  tice ***********
34f30 2a 2a 2a 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e  ***.**.** The in
34f40 74 65 72 66 61 63 65 20 74 6f 20 74 68 65 20 76  terface to the v
34f50 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63  irtual-table mec
34f60 68 61 6e 69 73 6d 20 69 73 20 63 75 72 72 65 6e  hanism is curren
34f70 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 64 0a 2a  tly considered.*
34f80 2a 20 74 6f 20 62 65 20 65 78 70 65 72 69 6d 65  * to be experime
34f90 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e 74 65 72  ntal.  The inter
34fa0 66 61 63 65 20 6d 69 67 68 74 20 63 68 61 6e 67  face might chang
34fb0 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74 69 62 6c  e in incompatibl
34fc0 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66 20 74 68  e ways..** If th
34fd0 69 73 20 69 73 20 61 20 70 72 6f 62 6c 65 6d 20  is is a problem 
34fe0 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e 6f 74 20  for you, do not 
34ff0 75 73 65 20 74 68 65 20 69 6e 74 65 72 66 61 63  use the interfac
35000 65 20 61 74 20 74 68 69 73 20 74 69 6d 65 2e 0a  e at this time..
35010 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 76  **.** When the v
35020 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63  irtual-table mec
35030 68 61 6e 69 73 6d 20 73 74 61 62 6c 69 7a 65 73  hanism stablizes
35040 2c 20 77 65 20 77 69 6c 6c 20 64 65 63 6c 61 72  , we will declar
35050 65 20 74 68 65 0a 2a 2a 20 69 6e 74 65 72 66 61  e the.** interfa
35060 63 65 20 66 69 78 65 64 2c 20 73 75 70 70 6f 72  ce fixed, suppor
35070 74 20 69 74 20 69 6e 64 65 66 69 6e 69 74 65 6c  t it indefinitel
35080 79 2c 20 61 6e 64 20 72 65 6d 6f 76 65 20 74 68  y, and remove th
35090 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2f 0a 0a  is comment..*/..
350a0 2f 2a 0a 2a 2a 20 53 74 72 75 63 74 75 72 65 73  /*.** Structures
350b0 20 75 73 65 64 20 62 79 20 74 68 65 20 76 69 72   used by the vir
350c0 74 75 61 6c 20 74 61 62 6c 65 20 69 6e 74 65 72  tual table inter
350d0 66 61 63 65 0a 2a 2f 0a 74 79 70 65 64 65 66 20  face.*/.typedef 
350e0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
350f0 74 61 62 20 73 71 6c 69 74 65 33 5f 76 74 61 62  tab sqlite3_vtab
35100 3b 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  ;.typedef struct
35110 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69   sqlite3_index_i
35120 6e 66 6f 20 73 71 6c 69 74 65 33 5f 69 6e 64 65  nfo sqlite3_inde
35130 78 5f 69 6e 66 6f 3b 0a 74 79 70 65 64 65 66 20  x_info;.typedef 
35140 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
35150 74 61 62 5f 63 75 72 73 6f 72 20 73 71 6c 69 74  tab_cursor sqlit
35160 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 3b 0a  e3_vtab_cursor;.
35170 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
35180 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 73 71  qlite3_module sq
35190 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 3b 0a 0a 2f  lite3_module;../
351a0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56  *.** CAPI3REF: V
351b0 69 72 74 75 61 6c 20 54 61 62 6c 65 20 4f 62 6a  irtual Table Obj
351c0 65 63 74 20 7b 46 31 38 30 30 30 7d 0a 2a 2a 20  ect {F18000}.** 
351d0 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65  KEYWORDS: sqlite
351e0 33 5f 6d 6f 64 75 6c 65 0a 2a 2a 0a 2a 2a 20 41  3_module.**.** A
351f0 20 6d 6f 64 75 6c 65 20 69 73 20 61 20 63 6c 61   module is a cla
35200 73 73 20 6f 66 20 76 69 72 74 75 61 6c 20 74 61  ss of virtual ta
35210 62 6c 65 73 2e 20 20 45 61 63 68 20 6d 6f 64 75  bles.  Each modu
35220 6c 65 20 69 73 20 64 65 66 69 6e 65 64 0a 2a 2a  le is defined.**
35230 20 62 79 20 61 6e 20 69 6e 73 74 61 6e 63 65 20   by an instance 
35240 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
35250 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 69   structure.  Thi
35260 73 20 73 74 72 75 63 74 75 72 65 20 63 6f 6e 73  s structure cons
35270 69 73 74 73 0a 2a 2a 20 6d 6f 73 74 6c 79 20 6f  ists.** mostly o
35280 66 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 74 68  f methods for th
35290 65 20 6d 6f 64 75 6c 65 2e 0a 2a 2f 0a 73 74 72  e module..*/.str
352a0 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75  uct sqlite3_modu
352b0 6c 65 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73  le {.  int iVers
352c0 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 72  ion;.  int (*xCr
352d0 65 61 74 65 29 28 73 71 6c 69 74 65 33 2a 2c 20  eate)(sqlite3*, 
352e0 76 6f 69 64 20 2a 70 41 75 78 2c 0a 20 20 20 20  void *pAux,.    
352f0 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 61             int a
35300 72 67 63 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  rgc, const char 
35310 2a 63 6f 6e 73 74 2a 61 72 67 76 2c 0a 20 20 20  *const*argv,.   
35320 20 20 20 20 20 20 20 20 20 20 20 20 73 71 6c 69              sqli
35330 74 65 33 5f 76 74 61 62 20 2a 2a 70 70 56 54 61  te3_vtab **ppVTa
35340 62 2c 20 63 68 61 72 2a 2a 29 3b 0a 20 20 69 6e  b, char**);.  in
35350 74 20 28 2a 78 43 6f 6e 6e 65 63 74 29 28 73 71  t (*xConnect)(sq
35360 6c 69 74 65 33 2a 2c 20 76 6f 69 64 20 2a 70 41  lite3*, void *pA
35370 75 78 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  ux,.            
35380 20 20 20 69 6e 74 20 61 72 67 63 2c 20 63 6f 6e     int argc, con
35390 73 74 20 63 68 61 72 20 2a 63 6f 6e 73 74 2a 61  st char *const*a
353a0 72 67 76 2c 0a 20 20 20 20 20 20 20 20 20 20 20  rgv,.           
353b0 20 20 20 20 73 71 6c 69 74 65 33 5f 76 74 61 62      sqlite3_vtab
353c0 20 2a 2a 70 70 56 54 61 62 2c 20 63 68 61 72 2a   **ppVTab, char*
353d0 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 42 65 73  *);.  int (*xBes
353e0 74 49 6e 64 65 78 29 28 73 71 6c 69 74 65 33 5f  tIndex)(sqlite3_
353f0 76 74 61 62 20 2a 70 56 54 61 62 2c 20 73 71 6c  vtab *pVTab, sql
35400 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 2a  ite3_index_info*
35410 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 69 73 63  );.  int (*xDisc
35420 6f 6e 6e 65 63 74 29 28 73 71 6c 69 74 65 33 5f  onnect)(sqlite3_
35430 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20  vtab *pVTab);.  
35440 69 6e 74 20 28 2a 78 44 65 73 74 72 6f 79 29 28  int (*xDestroy)(
35450 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56  sqlite3_vtab *pV
35460 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4f  Tab);.  int (*xO
35470 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61  pen)(sqlite3_vta
35480 62 20 2a 70 56 54 61 62 2c 20 73 71 6c 69 74 65  b *pVTab, sqlite
35490 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 2a 2a  3_vtab_cursor **
354a0 70 70 43 75 72 73 6f 72 29 3b 0a 20 20 69 6e 74  ppCursor);.  int
354b0 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74   (*xClose)(sqlit
354c0 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 29  e3_vtab_cursor*)
354d0 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 74 65  ;.  int (*xFilte
354e0 72 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  r)(sqlite3_vtab_
354f0 63 75 72 73 6f 72 2a 2c 20 69 6e 74 20 69 64 78  cursor*, int idx
35500 4e 75 6d 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  Num, const char 
35510 2a 69 64 78 53 74 72 2c 0a 20 20 20 20 20 20 20  *idxStr,.       
35520 20 20 20 20 20 20 20 20 20 69 6e 74 20 61 72 67           int arg
35530 63 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  c, sqlite3_value
35540 20 2a 2a 61 72 67 76 29 3b 0a 20 20 69 6e 74 20   **argv);.  int 
35550 28 2a 78 4e 65 78 74 29 28 73 71 6c 69 74 65 33  (*xNext)(sqlite3
35560 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a  _vtab_cursor*);.
35570 20 20 69 6e 74 20 28 2a 78 45 6f 66 29 28 73 71    int (*xEof)(sq
35580 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f  lite3_vtab_curso
35590 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f  r*);.  int (*xCo
355a0 6c 75 6d 6e 29 28 73 71 6c 69 74 65 33 5f 76 74  lumn)(sqlite3_vt
355b0 61 62 5f 63 75 72 73 6f 72 2a 2c 20 73 71 6c 69  ab_cursor*, sqli
355c0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
355d0 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 6f 77  t);.  int (*xRow
355e0 69 64 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  id)(sqlite3_vtab
355f0 5f 63 75 72 73 6f 72 2a 2c 20 73 71 6c 69 74 65  _cursor*, sqlite
35600 33 5f 69 6e 74 36 34 20 2a 70 52 6f 77 69 64 29  3_int64 *pRowid)
35610 3b 0a 20 20 69 6e 74 20 28 2a 78 55 70 64 61 74  ;.  int (*xUpdat
35620 65 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20  e)(sqlite3_vtab 
35630 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f  *, int, sqlite3_
35640 76 61 6c 75 65 20 2a 2a 2c 20 73 71 6c 69 74 65  value **, sqlite
35650 33 5f 69 6e 74 36 34 20 2a 29 3b 0a 20 20 69 6e  3_int64 *);.  in
35660 74 20 28 2a 78 42 65 67 69 6e 29 28 73 71 6c 69  t (*xBegin)(sqli
35670 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29  te3_vtab *pVTab)
35680 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29  ;.  int (*xSync)
35690 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70  (sqlite3_vtab *p
356a0 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78  VTab);.  int (*x
356b0 43 6f 6d 6d 69 74 29 28 73 71 6c 69 74 65 33 5f  Commit)(sqlite3_
356c0 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20  vtab *pVTab);.  
356d0 69 6e 74 20 28 2a 78 52 6f 6c 6c 62 61 63 6b 29  int (*xRollback)
356e0 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70  (sqlite3_vtab *p
356f0 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78  VTab);.  int (*x
35700 46 69 6e 64 46 75 6e 63 74 69 6f 6e 29 28 73 71  FindFunction)(sq
35710 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74 61  lite3_vtab *pVta
35720 62 2c 20 69 6e 74 20 6e 41 72 67 2c 20 63 6f 6e  b, int nArg, con
35730 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 0a  st char *zName,.
35740 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
35750 20 20 20 20 20 20 20 76 6f 69 64 20 28 2a 2a 70         void (**p
35760 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63  xFunc)(sqlite3_c
35770 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
35780 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
35790 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
357a0 20 20 20 20 20 76 6f 69 64 20 2a 2a 70 70 41 72       void **ppAr
357b0 67 29 3b 0a 0a 20 20 69 6e 74 20 28 2a 78 52 65  g);..  int (*xRe
357c0 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 74  name)(sqlite3_vt
357d0 61 62 20 2a 70 56 74 61 62 2c 20 63 6f 6e 73 74  ab *pVtab, const
357e0 20 63 68 61 72 20 2a 7a 4e 65 77 29 3b 0a 7d 3b   char *zNew);.};
357f0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
35800 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20  : Virtual Table 
35810 49 6e 64 65 78 69 6e 67 20 49 6e 66 6f 72 6d 61  Indexing Informa
35820 74 69 6f 6e 20 7b 46 31 38 31 30 30 7d 0a 2a 2a  tion {F18100}.**
35830 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74   KEYWORDS: sqlit
35840 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 0a 2a 2a  e3_index_info.**
35850 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
35860 69 6e 64 65 78 5f 69 6e 66 6f 20 73 74 72 75 63  index_info struc
35870 74 75 72 65 20 61 6e 64 20 69 74 73 20 73 75 62  ture and its sub
35880 73 74 72 75 63 74 75 72 65 73 20 69 73 20 75 73  structures is us
35890 65 64 20 74 6f 0a 2a 2a 20 70 61 73 73 20 69 6e  ed to.** pass in
358a0 66 6f 72 6d 61 74 69 6f 6e 20 69 6e 74 6f 20 61  formation into a
358b0 6e 64 20 72 65 63 65 69 76 65 20 74 68 65 20 72  nd receive the r
358c0 65 70 6c 79 20 66 72 6f 6d 20 74 68 65 20 78 42  eply from the xB
358d0 65 73 74 49 6e 64 65 78 0a 2a 2a 20 6d 65 74 68  estIndex.** meth
358e0 6f 64 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33  od of an sqlite3
358f0 5f 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 66 69  _module.  The fi
35900 65 6c 64 73 20 75 6e 64 65 72 20 2a 2a 49 6e 70  elds under **Inp
35910 75 74 73 2a 2a 20 61 72 65 20 74 68 65 0a 2a 2a  uts** are the.**
35920 20 69 6e 70 75 74 73 20 74 6f 20 78 42 65 73 74   inputs to xBest
35930 49 6e 64 65 78 20 61 6e 64 20 61 72 65 20 72 65  Index and are re
35940 61 64 2d 6f 6e 6c 79 2e 20 20 78 42 65 73 74 49  ad-only.  xBestI
35950 6e 64 65 78 20 69 6e 73 65 72 74 73 20 69 74 73  ndex inserts its
35960 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f  .** results into
35970 20 74 68 65 20 2a 2a 4f 75 74 70 75 74 73 2a 2a   the **Outputs**
35980 20 66 69 65 6c 64 73 2e 0a 2a 2a 0a 2a 2a 20 54   fields..**.** T
35990 68 65 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d  he aConstraint[]
359a0 20 61 72 72 61 79 20 72 65 63 6f 72 64 73 20 57   array records W
359b0 48 45 52 45 20 63 6c 61 75 73 65 20 63 6f 6e 73  HERE clause cons
359c0 74 72 61 69 6e 74 73 20 6f 66 20 74 68 65 0a 2a  traints of the.*
359d0 2a 20 66 6f 72 6d 3a 0a 2a 2a 0a 2a 2a 20 20 20  * form:.**.**   
359e0 20 20 20 20 20 20 63 6f 6c 75 6d 6e 20 4f 50 20        column OP 
359f0 65 78 70 72 0a 2a 2a 0a 2a 2a 20 57 68 65 72 65  expr.**.** Where
35a00 20 4f 50 20 69 73 20 3d 2c 20 26 6c 74 3b 2c 20   OP is =, &lt;, 
35a10 26 6c 74 3b 3d 2c 20 26 67 74 3b 2c 20 6f 72 20  &lt;=, &gt;, or 
35a20 26 67 74 3b 3d 2e 20 20 0a 2a 2a 20 54 68 65 20  &gt;=.  .** The 
35a30 70 61 72 74 69 63 75 6c 61 72 20 6f 70 65 72 61  particular opera
35a40 74 6f 72 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a  tor is stored.**
35a50 20 69 6e 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b   in aConstraint[
35a60 5d 2e 6f 70 2e 20 20 54 68 65 20 69 6e 64 65 78  ].op.  The index
35a70 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69   of the column i
35a80 73 20 73 74 6f 72 65 64 20 69 6e 20 0a 2a 2a 20  s stored in .** 
35a90 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 69 43  aConstraint[].iC
35aa0 6f 6c 75 6d 6e 2e 20 20 61 43 6f 6e 73 74 72 61  olumn.  aConstra
35ab0 69 6e 74 5b 5d 2e 75 73 61 62 6c 65 20 69 73 20  int[].usable is 
35ac0 54 52 55 45 20 69 66 20 74 68 65 0a 2a 2a 20 65  TRUE if the.** e
35ad0 78 70 72 20 6f 6e 20 74 68 65 20 72 69 67 68 74  xpr on the right
35ae0 2d 68 61 6e 64 20 73 69 64 65 20 63 61 6e 20 62  -hand side can b
35af0 65 20 65 76 61 6c 75 61 74 65 64 20 28 61 6e 64  e evaluated (and
35b00 20 74 68 75 73 20 74 68 65 20 63 6f 6e 73 74 72   thus the constr
35b10 61 69 6e 74 0a 2a 2a 20 69 73 20 75 73 61 62 6c  aint.** is usabl
35b20 65 29 20 61 6e 64 20 66 61 6c 73 65 20 69 66 20  e) and false if 
35b30 69 74 20 63 61 6e 6e 6f 74 2e 0a 2a 2a 0a 2a 2a  it cannot..**.**
35b40 20 54 68 65 20 6f 70 74 69 6d 69 7a 65 72 20 61   The optimizer a
35b50 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 76  utomatically inv
35b60 65 72 74 73 20 74 65 72 6d 73 20 6f 66 20 74 68  erts terms of th
35b70 65 20 66 6f 72 6d 20 22 65 78 70 72 20 4f 50 20  e form "expr OP 
35b80 63 6f 6c 75 6d 6e 22 0a 2a 2a 20 61 6e 64 20 6d  column".** and m
35b90 61 6b 65 73 20 6f 74 68 65 72 20 73 69 6d 70 6c  akes other simpl
35ba0 69 66 69 63 61 74 69 6f 6e 73 20 74 6f 20 74 68  ifications to th
35bb0 65 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 69  e WHERE clause i
35bc0 6e 20 61 6e 20 61 74 74 65 6d 70 74 20 74 6f 0a  n an attempt to.
35bd0 2a 2a 20 67 65 74 20 61 73 20 6d 61 6e 79 20 57  ** get as many W
35be0 48 45 52 45 20 63 6c 61 75 73 65 20 74 65 72 6d  HERE clause term
35bf0 73 20 69 6e 74 6f 20 74 68 65 20 66 6f 72 6d 20  s into the form 
35c00 73 68 6f 77 6e 20 61 62 6f 76 65 20 61 73 20 70  shown above as p
35c10 6f 73 73 69 62 6c 65 2e 0a 2a 2a 20 54 68 65 20  ossible..** The 
35c20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 61 72  aConstraint[] ar
35c30 72 61 79 20 6f 6e 6c 79 20 72 65 70 6f 72 74 73  ray only reports
35c40 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 74 65   WHERE clause te
35c50 72 6d 73 20 69 6e 20 74 68 65 20 63 6f 72 72 65  rms in the corre
35c60 63 74 0a 2a 2a 20 66 6f 72 6d 20 74 68 61 74 20  ct.** form that 
35c70 72 65 66 65 72 20 74 6f 20 74 68 65 20 70 61 72  refer to the par
35c80 74 69 63 75 6c 61 72 20 76 69 72 74 75 61 6c 20  ticular virtual 
35c90 74 61 62 6c 65 20 62 65 69 6e 67 20 71 75 65 72  table being quer
35ca0 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 66 6f 72  ied..**.** Infor
35cb0 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65  mation about the
35cc0 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 65   ORDER BY clause
35cd0 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61 4f   is stored in aO
35ce0 72 64 65 72 42 79 5b 5d 2e 0a 2a 2a 20 45 61 63  rderBy[]..** Eac
35cf0 68 20 74 65 72 6d 20 6f 66 20 61 4f 72 64 65 72  h term of aOrder
35d00 42 79 20 72 65 63 6f 72 64 73 20 61 20 63 6f 6c  By records a col
35d10 75 6d 6e 20 6f 66 20 74 68 65 20 4f 52 44 45 52  umn of the ORDER
35d20 20 42 59 20 63 6c 61 75 73 65 2e 0a 2a 2a 0a 2a   BY clause..**.*
35d30 2a 20 54 68 65 20 78 42 65 73 74 49 6e 64 65 78  * The xBestIndex
35d40 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 66 69 6c   method must fil
35d50 6c 20 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61  l aConstraintUsa
35d60 67 65 5b 5d 20 77 69 74 68 20 69 6e 66 6f 72 6d  ge[] with inform
35d70 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 77  ation.** about w
35d80 68 61 74 20 70 61 72 61 6d 65 74 65 72 73 20 74  hat parameters t
35d90 6f 20 70 61 73 73 20 74 6f 20 78 46 69 6c 74 65  o pass to xFilte
35da0 72 2e 20 20 49 66 20 61 72 67 76 49 6e 64 65 78  r.  If argvIndex
35db0 3e 30 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 72  >0 then.** the r
35dc0 69 67 68 74 2d 68 61 6e 64 20 73 69 64 65 20 6f  ight-hand side o
35dd0 66 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  f the correspond
35de0 69 6e 67 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b  ing aConstraint[
35df0 5d 20 69 73 20 65 76 61 6c 75 61 74 65 64 0a 2a  ] is evaluated.*
35e00 2a 20 61 6e 64 20 62 65 63 6f 6d 65 73 20 74 68  * and becomes th
35e10 65 20 61 72 67 76 49 6e 64 65 78 2d 74 68 20 65  e argvIndex-th e
35e20 6e 74 72 79 20 69 6e 20 61 72 67 76 2e 20 20 49  ntry in argv.  I
35e30 66 20 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61  f aConstraintUsa
35e40 67 65 5b 5d 2e 6f 6d 69 74 0a 2a 2a 20 69 73 20  ge[].omit.** is 
35e50 74 72 75 65 2c 20 74 68 65 6e 20 74 68 65 20 63  true, then the c
35e60 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 61 73 73  onstraint is ass
35e70 75 6d 65 64 20 74 6f 20 62 65 20 66 75 6c 6c 79  umed to be fully
35e80 20 68 61 6e 64 6c 65 64 20 62 79 20 74 68 65 0a   handled by the.
35e90 2a 2a 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  ** virtual table
35ea0 20 61 6e 64 20 69 73 20 6e 6f 74 20 63 68 65 63   and is not chec
35eb0 6b 65 64 20 61 67 61 69 6e 20 62 79 20 53 51 4c  ked again by SQL
35ec0 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69  ite..**.** The i
35ed0 64 78 4e 75 6d 20 61 6e 64 20 69 64 78 50 74 72  dxNum and idxPtr
35ee0 20 76 61 6c 75 65 73 20 61 72 65 20 72 65 63 6f   values are reco
35ef0 72 64 65 64 20 61 6e 64 20 70 61 73 73 65 64 20  rded and passed 
35f00 69 6e 74 6f 20 78 46 69 6c 74 65 72 2e 0a 2a 2a  into xFilter..**
35f10 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
35f20 69 73 20 75 73 65 64 20 74 6f 20 66 72 65 65 20  is used to free 
35f30 69 64 78 50 74 72 20 69 66 20 6e 65 65 64 54 6f  idxPtr if needTo
35f40 46 72 65 65 49 64 78 50 74 72 20 69 73 20 74 72  FreeIdxPtr is tr
35f50 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 72  ue..**.** The or
35f60 64 65 72 42 79 43 6f 6e 73 75 6d 65 64 20 6d 65  derByConsumed me
35f70 61 6e 73 20 74 68 61 74 20 6f 75 74 70 75 74 20  ans that output 
35f80 66 72 6f 6d 20 78 46 69 6c 74 65 72 20 77 69 6c  from xFilter wil
35f90 6c 20 6f 63 63 75 72 20 69 6e 0a 2a 2a 20 74 68  l occur in.** th
35fa0 65 20 63 6f 72 72 65 63 74 20 6f 72 64 65 72 20  e correct order 
35fb0 74 6f 20 73 61 74 69 73 66 79 20 74 68 65 20 4f  to satisfy the O
35fc0 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 20 73  RDER BY clause s
35fd0 6f 20 74 68 61 74 20 6e 6f 20 73 65 70 61 72 61  o that no separa
35fe0 74 65 0a 2a 2a 20 73 6f 72 74 69 6e 67 20 73 74  te.** sorting st
35ff0 65 70 20 69 73 20 72 65 71 75 69 72 65 64 2e 0a  ep is required..
36000 2a 2a 0a 2a 2a 20 54 68 65 20 65 73 74 69 6d 61  **.** The estima
36010 74 65 64 43 6f 73 74 20 76 61 6c 75 65 20 69 73  tedCost value is
36020 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20   an estimate of 
36030 74 68 65 20 63 6f 73 74 20 6f 66 20 64 6f 69 6e  the cost of doin
36040 67 20 74 68 65 0a 2a 2a 20 70 61 72 74 69 63 75  g the.** particu
36050 6c 61 72 20 6c 6f 6f 6b 75 70 2e 20 20 41 20 66  lar lookup.  A f
36060 75 6c 6c 20 73 63 61 6e 20 6f 66 20 61 20 74 61  ull scan of a ta
36070 62 6c 65 20 77 69 74 68 20 4e 20 65 6e 74 72 69  ble with N entri
36080 65 73 20 73 68 6f 75 6c 64 20 68 61 76 65 0a 2a  es should have.*
36090 2a 20 61 20 63 6f 73 74 20 6f 66 20 4e 2e 20 20  * a cost of N.  
360a0 41 20 62 69 6e 61 72 79 20 73 65 61 72 63 68 20  A binary search 
360b0 6f 66 20 61 20 74 61 62 6c 65 20 6f 66 20 4e 20  of a table of N 
360c0 65 6e 74 72 69 65 73 20 73 68 6f 75 6c 64 20 68  entries should h
360d0 61 76 65 20 61 0a 2a 2a 20 63 6f 73 74 20 6f 66  ave a.** cost of
360e0 20 61 70 70 72 6f 78 69 6d 61 74 65 6c 79 20 6c   approximately l
360f0 6f 67 28 4e 29 2e 0a 2a 2f 0a 73 74 72 75 63 74  og(N)..*/.struct
36100 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69   sqlite3_index_i
36110 6e 66 6f 20 7b 0a 20 20 2f 2a 20 49 6e 70 75 74  nfo {.  /* Input
36120 73 20 2a 2f 0a 20 20 69 6e 74 20 6e 43 6f 6e 73  s */.  int nCons
36130 74 72 61 69 6e 74 3b 20 20 20 20 20 20 20 20 20  traint;         
36140 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 65    /* Number of e
36150 6e 74 72 69 65 73 20 69 6e 20 61 43 6f 6e 73 74  ntries in aConst
36160 72 61 69 6e 74 20 2a 2f 0a 20 20 73 74 72 75 63  raint */.  struc
36170 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f  t sqlite3_index_
36180 63 6f 6e 73 74 72 61 69 6e 74 20 7b 0a 20 20 20  constraint {.   
36190 20 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 20    int iColumn;  
361a0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43              /* C
361b0 6f 6c 75 6d 6e 20 6f 6e 20 6c 65 66 74 2d 68 61  olumn on left-ha
361c0 6e 64 20 73 69 64 65 20 6f 66 20 63 6f 6e 73 74  nd side of const
361d0 72 61 69 6e 74 20 2a 2f 0a 20 20 20 20 20 75 6e  raint */.     un
361e0 73 69 67 6e 65 64 20 63 68 61 72 20 6f 70 3b 20  signed char op; 
361f0 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e 73 74          /* Const
36200 72 61 69 6e 74 20 6f 70 65 72 61 74 6f 72 20 2a  raint operator *
36210 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 64 20  /.     unsigned 
36220 63 68 61 72 20 75 73 61 62 6c 65 3b 20 20 20 20  char usable;    
36230 20 2f 2a 20 54 72 75 65 20 69 66 20 74 68 69 73   /* True if this
36240 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 75   constraint is u
36250 73 61 62 6c 65 20 2a 2f 0a 20 20 20 20 20 69 6e  sable */.     in
36260 74 20 69 54 65 72 6d 4f 66 66 73 65 74 3b 20 20  t iTermOffset;  
36270 20 20 20 20 20 20 20 20 2f 2a 20 55 73 65 64 20          /* Used 
36280 69 6e 74 65 72 6e 61 6c 6c 79 20 2d 20 78 42 65  internally - xBe
36290 73 74 49 6e 64 65 78 20 73 68 6f 75 6c 64 20 69  stIndex should i
362a0 67 6e 6f 72 65 20 2a 2f 0a 20 20 7d 20 2a 61 43  gnore */.  } *aC
362b0 6f 6e 73 74 72 61 69 6e 74 3b 20 20 20 20 20 20  onstraint;      
362c0 20 20 20 20 20 20 2f 2a 20 54 61 62 6c 65 20 6f        /* Table o
362d0 66 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 63  f WHERE clause c
362e0 6f 6e 73 74 72 61 69 6e 74 73 20 2a 2f 0a 20 20  onstraints */.  
362f0 69 6e 74 20 6e 4f 72 64 65 72 42 79 3b 20 20 20  int nOrderBy;   
36300 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75             /* Nu
36310 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e  mber of terms in
36320 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c   the ORDER BY cl
36330 61 75 73 65 20 2a 2f 0a 20 20 73 74 72 75 63 74  ause */.  struct
36340 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 6f   sqlite3_index_o
36350 72 64 65 72 62 79 20 7b 0a 20 20 20 20 20 69 6e  rderby {.     in
36360 74 20 69 43 6f 6c 75 6d 6e 3b 20 20 20 20 20 20  t iColumn;      
36370 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6c 75 6d          /* Colum
36380 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a 20 20 20 20  n number */.    
36390 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 64   unsigned char d
363a0 65 73 63 3b 20 20 20 20 20 20 20 2f 2a 20 54 72  esc;       /* Tr
363b0 75 65 20 66 6f 72 20 44 45 53 43 2e 20 20 46 61  ue for DESC.  Fa
363c0 6c 73 65 20 66 6f 72 20 41 53 43 2e 20 2a 2f 0a  lse for ASC. */.
363d0 20 20 7d 20 2a 61 4f 72 64 65 72 42 79 3b 20 20    } *aOrderBy;  
363e0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
363f0 54 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61  The ORDER BY cla
36400 75 73 65 20 2a 2f 0a 0a 20 20 2f 2a 20 4f 75 74  use */..  /* Out
36410 70 75 74 73 20 2a 2f 0a 20 20 73 74 72 75 63 74  puts */.  struct
36420 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 63   sqlite3_index_c
36430 6f 6e 73 74 72 61 69 6e 74 5f 75 73 61 67 65 20  onstraint_usage 
36440 7b 0a 20 20 20 20 69 6e 74 20 61 72 67 76 49 6e  {.    int argvIn
36450 64 65 78 3b 20 20 20 20 20 20 20 20 20 20 20 2f  dex;           /
36460 2a 20 69 66 20 3e 30 2c 20 63 6f 6e 73 74 72 61  * if >0, constra
36470 69 6e 74 20 69 73 20 70 61 72 74 20 6f 66 20 61  int is part of a
36480 72 67 76 20 74 6f 20 78 46 69 6c 74 65 72 20 2a  rgv to xFilter *
36490 2f 0a 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63  /.    unsigned c
364a0 68 61 72 20 6f 6d 69 74 3b 20 20 20 20 20 20 2f  har omit;      /
364b0 2a 20 44 6f 20 6e 6f 74 20 63 6f 64 65 20 61 20  * Do not code a 
364c0 74 65 73 74 20 66 6f 72 20 74 68 69 73 20 63 6f  test for this co
364d0 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 7d 20  nstraint */.  } 
364e0 2a 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 67  *aConstraintUsag
364f0 65 3b 0a 20 20 69 6e 74 20 69 64 78 4e 75 6d 3b  e;.  int idxNum;
36500 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
36510 2f 2a 20 4e 75 6d 62 65 72 20 75 73 65 64 20 74  /* Number used t
36520 6f 20 69 64 65 6e 74 69 66 79 20 74 68 65 20 69  o identify the i
36530 6e 64 65 78 20 2a 2f 0a 20 20 63 68 61 72 20 2a  ndex */.  char *
36540 69 64 78 53 74 72 3b 20 20 20 20 20 20 20 20 20  idxStr;         
36550 20 20 20 20 20 2f 2a 20 53 74 72 69 6e 67 2c 20       /* String, 
36560 70 6f 73 73 69 62 6c 79 20 6f 62 74 61 69 6e 65  possibly obtaine
36570 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d  d from sqlite3_m
36580 61 6c 6c 6f 63 20 2a 2f 0a 20 20 69 6e 74 20 6e  alloc */.  int n
36590 65 65 64 54 6f 46 72 65 65 49 64 78 53 74 72 3b  eedToFreeIdxStr;
365a0 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 69 64        /* Free id
365b0 78 53 74 72 20 75 73 69 6e 67 20 73 71 6c 69 74  xStr using sqlit
365c0 65 33 5f 66 72 65 65 28 29 20 69 66 20 74 72 75  e3_free() if tru
365d0 65 20 2a 2f 0a 20 20 69 6e 74 20 6f 72 64 65 72  e */.  int order
365e0 42 79 43 6f 6e 73 75 6d 65 64 3b 20 20 20 20 20  ByConsumed;     
365f0 20 20 2f 2a 20 54 72 75 65 20 69 66 20 6f 75 74    /* True if out
36600 70 75 74 20 69 73 20 61 6c 72 65 61 64 79 20 6f  put is already o
36610 72 64 65 72 65 64 20 2a 2f 0a 20 20 64 6f 75 62  rdered */.  doub
36620 6c 65 20 65 73 74 69 6d 61 74 65 64 43 6f 73 74  le estimatedCost
36630 3b 20 20 20 20 20 20 2f 2a 20 45 73 74 69 6d 61  ;      /* Estima
36640 74 65 64 20 63 6f 73 74 20 6f 66 20 75 73 69 6e  ted cost of usin
36650 67 20 74 68 69 73 20 69 6e 64 65 78 20 2a 2f 0a  g this index */.
36660 7d 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  };.#define SQLIT
36670 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49  E_INDEX_CONSTRAI
36680 4e 54 5f 45 51 20 20 20 20 32 0a 23 64 65 66 69  NT_EQ    2.#defi
36690 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f  ne SQLITE_INDEX_
366a0 43 4f 4e 53 54 52 41 49 4e 54 5f 47 54 20 20 20  CONSTRAINT_GT   
366b0 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   4.#define SQLIT
366c0 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49  E_INDEX_CONSTRAI
366d0 4e 54 5f 4c 45 20 20 20 20 38 0a 23 64 65 66 69  NT_LE    8.#defi
366e0 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f  ne SQLITE_INDEX_
366f0 43 4f 4e 53 54 52 41 49 4e 54 5f 4c 54 20 20 20  CONSTRAINT_LT   
36700 20 31 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   16.#define SQLI
36710 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41  TE_INDEX_CONSTRA
36720 49 4e 54 5f 47 45 20 20 20 20 33 32 0a 23 64 65  INT_GE    32.#de
36730 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45  fine SQLITE_INDE
36740 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4d 41 54  X_CONSTRAINT_MAT
36750 43 48 20 36 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  CH 64../*.** CAP
36760 49 33 52 45 46 3a 20 52 65 67 69 73 74 65 72 20  I3REF: Register 
36770 41 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20  A Virtual Table 
36780 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 7b  Implementation {
36790 46 31 38 32 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68  F18200}.**.** Th
367a0 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73  is routine is us
367b0 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 61  ed to register a
367c0 20 6e 65 77 20 6d 6f 64 75 6c 65 20 6e 61 6d 65   new module name
367d0 20 77 69 74 68 20 61 6e 20 53 51 4c 69 74 65 0a   with an SQLite.
367e0 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  ** connection.  
367f0 4d 6f 64 75 6c 65 20 6e 61 6d 65 73 20 6d 75 73  Module names mus
36800 74 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20  t be registered 
36810 62 65 66 6f 72 65 20 63 72 65 61 74 69 6e 67 20  before creating 
36820 6e 65 77 0a 2a 2a 20 76 69 72 74 75 61 6c 20 74  new.** virtual t
36830 61 62 6c 65 73 20 6f 6e 20 74 68 65 20 6d 6f 64  ables on the mod
36840 75 6c 65 2c 20 6f 72 20 62 65 66 6f 72 65 20 75  ule, or before u
36850 73 69 6e 67 20 70 72 65 65 78 69 73 74 69 6e 67  sing preexisting
36860 20 76 69 72 74 75 61 6c 0a 2a 2a 20 74 61 62 6c   virtual.** tabl
36870 65 73 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65  es of the module
36880 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
36890 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 0a  _create_module(.
368a0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
368b0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
368c0 53 51 4c 69 74 65 20 63 6f 6e 6e 65 63 74 69 6f  SQLite connectio
368d0 6e 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d 6f  n to register mo
368e0 64 75 6c 65 20 77 69 74 68 20 2a 2f 0a 20 20 63  dule with */.  c
368f0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
36900 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d  ,         /* Nam
36910 65 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20  e of the module 
36920 2a 2f 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69 74  */.  const sqlit
36930 65 33 5f 6d 6f 64 75 6c 65 20 2a 2c 20 20 20 20  e3_module *,    
36940 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 74  /* Methods for t
36950 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 76  he module */.  v
36960 6f 69 64 20 2a 20 20 20 20 20 20 20 20 20 20 20  oid *           
36970 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6c 69            /* Cli
36980 65 6e 74 20 64 61 74 61 20 66 6f 72 20 78 43 72  ent data for xCr
36990 65 61 74 65 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f  eate/xConnect */
369a0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
369b0 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 41 20  REF: Register A 
369c0 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 49 6d  Virtual Table Im
369d0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 7b 46 31  plementation {F1
369e0 38 32 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73  8210}.**.** This
369f0 20 72 6f 75 74 69 6e 65 20 69 73 20 69 64 65 6e   routine is iden
36a00 74 69 63 61 6c 20 74 6f 20 74 68 65 20 73 71 6c  tical to the sql
36a10 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75  ite3_create_modu
36a20 6c 65 28 29 20 6d 65 74 68 6f 64 20 61 62 6f 76  le() method abov
36a30 65 2c 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61  e,.** except tha
36a40 74 20 69 74 20 61 6c 6c 6f 77 73 20 61 20 64 65  t it allows a de
36a50 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f  structor functio
36a60 6e 20 74 6f 20 62 65 20 73 70 65 63 69 66 69 65  n to be specifie
36a70 64 2e 20 49 74 20 69 73 0a 2a 2a 20 65 76 65 6e  d. It is.** even
36a80 20 6d 6f 72 65 20 65 78 70 65 72 69 6d 65 6e 74   more experiment
36a90 61 6c 20 74 68 61 6e 20 74 68 65 20 72 65 73 74  al than the rest
36aa0 20 6f 66 20 74 68 65 20 76 69 72 74 75 61 6c 20   of the virtual 
36ab0 74 61 62 6c 65 73 20 41 50 49 2e 0a 2a 2f 0a 69  tables API..*/.i
36ac0 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
36ad0 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 0a 20 20 73  e_module_v2(.  s
36ae0 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
36af0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c            /* SQL
36b00 69 74 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ite connection t
36b10 6f 20 72 65 67 69 73 74 65 72 20 6d 6f 64 75 6c  o register modul
36b20 65 20 77 69 74 68 20 2a 2f 0a 20 20 63 6f 6e 73  e with */.  cons
36b30 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 20  t char *zName,  
36b40 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f         /* Name o
36b50 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a  f the module */.
36b60 20 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f    const sqlite3_
36b70 6d 6f 64 75 6c 65 20 2a 2c 20 20 20 20 2f 2a 20  module *,    /* 
36b80 4d 65 74 68 6f 64 73 20 66 6f 72 20 74 68 65 20  Methods for the 
36b90 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 76 6f 69 64  module */.  void
36ba0 20 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20 20   *,             
36bb0 20 20 20 20 20 20 20 2f 2a 20 43 6c 69 65 6e 74         /* Client
36bc0 20 64 61 74 61 20 66 6f 72 20 78 43 72 65 61 74   data for xCreat
36bd0 65 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a 20 20  e/xConnect */.  
36be0 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28  void(*xDestroy)(
36bf0 76 6f 69 64 2a 29 20 20 20 20 20 2f 2a 20 4d 6f  void*)     /* Mo
36c00 64 75 6c 65 20 64 65 73 74 72 75 63 74 6f 72 20  dule destructor 
36c10 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 29 3b 0a 0a  function */.);..
36c20 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
36c30 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 49 6e  Virtual Table In
36c40 73 74 61 6e 63 65 20 4f 62 6a 65 63 74 20 7b 46  stance Object {F
36c50 31 38 30 31 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52  18010}.** KEYWOR
36c60 44 53 3a 20 73 71 6c 69 74 65 33 5f 76 74 61 62  DS: sqlite3_vtab
36c70 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 6d 6f 64  .**.** Every mod
36c80 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ule implementati
36c90 6f 6e 20 75 73 65 73 20 61 20 73 75 62 63 6c 61  on uses a subcla
36ca0 73 73 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ss of the follow
36cb0 69 6e 67 20 73 74 72 75 63 74 75 72 65 0a 2a 2a  ing structure.**
36cc0 20 74 6f 20 64 65 73 63 72 69 62 65 20 61 20 70   to describe a p
36cd0 61 72 74 69 63 75 6c 61 72 20 69 6e 73 74 61 6e  articular instan
36ce0 63 65 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65  ce of the module
36cf0 2e 20 20 45 61 63 68 20 73 75 62 63 6c 61 73 73  .  Each subclass
36d00 20 77 69 6c 6c 0a 2a 2a 20 62 65 20 74 61 69 6c   will.** be tail
36d10 6f 72 65 64 20 74 6f 20 74 68 65 20 73 70 65 63  ored to the spec
36d20 69 66 69 63 20 6e 65 65 64 73 20 6f 66 20 74 68  ific needs of th
36d30 65 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65  e module impleme
36d40 6e 74 61 74 69 6f 6e 2e 20 20 20 54 68 65 0a 2a  ntation.   The.*
36d50 2a 20 70 75 72 70 6f 73 65 20 6f 66 20 74 68 69  * purpose of thi
36d60 73 20 73 75 70 65 72 63 6c 61 73 73 20 69 73 20  s superclass is 
36d70 74 6f 20 64 65 66 69 6e 65 20 63 65 72 74 61 69  to define certai
36d80 6e 20 66 69 65 6c 64 73 20 74 68 61 74 20 61 72  n fields that ar
36d90 65 20 63 6f 6d 6d 6f 6e 0a 2a 2a 20 74 6f 20 61  e common.** to a
36da0 6c 6c 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d  ll module implem
36db0 65 6e 74 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  entations..**.**
36dc0 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20   Virtual tables 
36dd0 6d 65 74 68 6f 64 73 20 63 61 6e 20 73 65 74 20  methods can set 
36de0 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
36df0 20 62 79 20 61 73 73 69 67 6e 69 6e 67 20 61 0a   by assigning a.
36e00 2a 2a 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e  ** string obtain
36e10 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ed from sqlite3_
36e20 6d 70 72 69 6e 74 66 28 29 20 74 6f 20 7a 45 72  mprintf() to zEr
36e30 72 4d 73 67 2e 20 20 54 68 65 20 6d 65 74 68 6f  rMsg.  The metho
36e40 64 20 73 68 6f 75 6c 64 0a 2a 2a 20 74 61 6b 65  d should.** take
36e50 20 63 61 72 65 20 74 68 61 74 20 61 6e 79 20 70   care that any p
36e60 72 69 6f 72 20 73 74 72 69 6e 67 20 69 73 20 66  rior string is f
36e70 72 65 65 64 20 62 79 20 61 20 63 61 6c 6c 20 74  reed by a call t
36e80 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  o sqlite3_free()
36e90 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 61 73 73  .** prior to ass
36ea0 69 67 6e 69 6e 67 20 61 20 6e 65 77 20 73 74 72  igning a new str
36eb0 69 6e 67 20 74 6f 20 7a 45 72 72 4d 73 67 2e 20  ing to zErrMsg. 
36ec0 20 41 66 74 65 72 20 74 68 65 20 65 72 72 6f 72   After the error
36ed0 20 6d 65 73 73 61 67 65 0a 2a 2a 20 69 73 20 64   message.** is d
36ee0 65 6c 69 76 65 72 65 64 20 75 70 20 74 6f 20 74  elivered up to t
36ef0 68 65 20 63 6c 69 65 6e 74 20 61 70 70 6c 69 63  he client applic
36f00 61 74 69 6f 6e 2c 20 74 68 65 20 73 74 72 69 6e  ation, the strin
36f10 67 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61  g will be automa
36f20 74 69 63 61 6c 6c 79 0a 2a 2a 20 66 72 65 65 64  tically.** freed
36f30 20 62 79 20 73 71 6c 69 74 65 33 5f 66 72 65 65   by sqlite3_free
36f40 28 29 20 61 6e 64 20 74 68 65 20 7a 45 72 72 4d  () and the zErrM
36f50 73 67 20 66 69 65 6c 64 20 77 69 6c 6c 20 62 65  sg field will be
36f60 20 7a 65 72 6f 65 64 2e 20 20 4e 6f 74 65 0a 2a   zeroed.  Note.*
36f70 2a 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f 6d  * that sqlite3_m
36f80 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c  printf() and sql
36f90 69 74 65 33 5f 66 72 65 65 28 29 20 61 72 65 20  ite3_free() are 
36fa0 75 73 65 64 20 6f 6e 20 74 68 65 20 7a 45 72 72  used on the zErr
36fb0 4d 73 67 20 66 69 65 6c 64 0a 2a 2a 20 73 69 6e  Msg field.** sin
36fc0 63 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  ce virtual table
36fd0 73 20 61 72 65 20 63 6f 6d 6d 6f 6e 6c 79 20 69  s are commonly i
36fe0 6d 70 6c 65 6d 65 6e 74 65 64 20 69 6e 20 6c 6f  mplemented in lo
36ff0 61 64 61 62 6c 65 20 65 78 74 65 6e 73 69 6f 6e  adable extension
37000 73 20 77 68 69 63 68 0a 2a 2a 20 64 6f 20 6e 6f  s which.** do no
37010 74 20 68 61 76 65 20 61 63 63 65 73 73 20 74 6f  t have access to
37020 20 73 71 6c 69 74 65 33 4d 50 72 69 6e 74 66 28   sqlite3MPrintf(
37030 29 20 6f 72 20 73 71 6c 69 74 65 33 46 72 65 65  ) or sqlite3Free
37040 28 29 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71  ()..*/.struct sq
37050 6c 69 74 65 33 5f 76 74 61 62 20 7b 0a 20 20 63  lite3_vtab {.  c
37060 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64  onst sqlite3_mod
37070 75 6c 65 20 2a 70 4d 6f 64 75 6c 65 3b 20 20 2f  ule *pModule;  /
37080 2a 20 54 68 65 20 6d 6f 64 75 6c 65 20 66 6f 72  * The module for
37090 20 74 68 69 73 20 76 69 72 74 75 61 6c 20 74 61   this virtual ta
370a0 62 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6e 52 65  ble */.  int nRe
370b0 66 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  f;              
370c0 20 20 20 20 20 20 20 20 20 2f 2a 20 55 73 65 64           /* Used
370d0 20 69 6e 74 65 72 6e 61 6c 6c 79 20 2a 2f 0a 20   internally */. 
370e0 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 3b 20   char *zErrMsg; 
370f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
37100 20 2f 2a 20 45 72 72 6f 72 20 6d 65 73 73 61 67   /* Error messag
37110 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d  e from sqlite3_m
37120 70 72 69 6e 74 66 28 29 20 2a 2f 0a 20 20 2f 2a  printf() */.  /*
37130 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69   Virtual table i
37140 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77  mplementations w
37150 69 6c 6c 20 74 79 70 69 63 61 6c 6c 79 20 61 64  ill typically ad
37160 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65  d additional fie
37170 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  lds */.};../*.**
37180 20 43 41 50 49 33 52 45 46 3a 20 56 69 72 74 75   CAPI3REF: Virtu
37190 61 6c 20 54 61 62 6c 65 20 43 75 72 73 6f 72 20  al Table Cursor 
371a0 4f 62 6a 65 63 74 20 20 7b 46 31 38 30 32 30 7d  Object  {F18020}
371b0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71  .** KEYWORDS: sq
371c0 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f  lite3_vtab_curso
371d0 72 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 6d 6f  r.**.** Every mo
371e0 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  dule implementat
371f0 69 6f 6e 20 75 73 65 73 20 61 20 73 75 62 63 6c  ion uses a subcl
37200 61 73 73 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f  ass of the follo
37210 77 69 6e 67 20 73 74 72 75 63 74 75 72 65 0a 2a  wing structure.*
37220 2a 20 74 6f 20 64 65 73 63 72 69 62 65 20 63 75  * to describe cu
37230 72 73 6f 72 73 20 74 68 61 74 20 70 6f 69 6e 74  rsors that point
37240 20 69 6e 74 6f 20 74 68 65 20 76 69 72 74 75 61   into the virtua
37250 6c 20 74 61 62 6c 65 20 61 6e 64 20 61 72 65 20  l table and are 
37260 75 73 65 64 0a 2a 2a 20 74 6f 20 6c 6f 6f 70 20  used.** to loop 
37270 74 68 72 6f 75 67 68 20 74 68 65 20 76 69 72 74  through the virt
37280 75 61 6c 20 74 61 62 6c 65 2e 20 20 43 75 72 73  ual table.  Curs
37290 6f 72 73 20 61 72 65 20 63 72 65 61 74 65 64 20  ors are created 
372a0 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 78 4f 70  using the.** xOp
372b0 65 6e 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65  en method of the
372c0 20 6d 6f 64 75 6c 65 2e 20 20 45 61 63 68 20 6d   module.  Each m
372d0 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  odule implementa
372e0 74 69 6f 6e 20 77 69 6c 6c 20 64 65 66 69 6e 65  tion will define
372f0 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  .** the content 
37300 6f 66 20 61 20 63 75 72 73 6f 72 20 73 74 72 75  of a cursor stru
37310 63 74 75 72 65 20 74 6f 20 73 75 69 74 20 69 74  cture to suit it
37320 73 20 6f 77 6e 20 6e 65 65 64 73 2e 0a 2a 2a 0a  s own needs..**.
37330 2a 2a 20 54 68 69 73 20 73 75 70 65 72 63 6c 61  ** This supercla
37340 73 73 20 65 78 69 73 74 73 20 69 6e 20 6f 72 64  ss exists in ord
37350 65 72 20 74 6f 20 64 65 66 69 6e 65 20 66 69 65  er to define fie
37360 6c 64 73 20 6f 66 20 74 68 65 20 63 75 72 73 6f  lds of the curso
37370 72 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 63 6f  r that.** are co
37380 6d 6d 6f 6e 20 74 6f 20 61 6c 6c 20 69 6d 70 6c  mmon to all impl
37390 65 6d 65 6e 74 61 74 69 6f 6e 73 2e 0a 2a 2f 0a  ementations..*/.
373a0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
373b0 74 61 62 5f 63 75 72 73 6f 72 20 7b 0a 20 20 73  tab_cursor {.  s
373c0 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74  qlite3_vtab *pVt
373d0 61 62 3b 20 20 20 20 20 20 2f 2a 20 56 69 72 74  ab;      /* Virt
373e0 75 61 6c 20 74 61 62 6c 65 20 6f 66 20 74 68 69  ual table of thi
373f0 73 20 63 75 72 73 6f 72 20 2a 2f 0a 20 20 2f 2a  s cursor */.  /*
37400 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69   Virtual table i
37410 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77  mplementations w
37420 69 6c 6c 20 74 79 70 69 63 61 6c 6c 79 20 61 64  ill typically ad
37430 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65  d additional fie
37440 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  lds */.};../*.**
37450 20 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61   CAPI3REF: Decla
37460 72 65 20 54 68 65 20 53 63 68 65 6d 61 20 4f 66  re The Schema Of
37470 20 41 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65   A Virtual Table
37480 20 7b 46 31 38 32 38 30 7d 0a 2a 2a 0a 2a 2a 20   {F18280}.**.** 
37490 54 68 65 20 78 43 72 65 61 74 65 20 61 6e 64 20  The xCreate and 
374a0 78 43 6f 6e 6e 65 63 74 20 6d 65 74 68 6f 64 73  xConnect methods
374b0 20 6f 66 20 61 20 6d 6f 64 75 6c 65 20 75 73 65   of a module use
374c0 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 41   the following A
374d0 50 49 0a 2a 2a 20 74 6f 20 64 65 63 6c 61 72 65  PI.** to declare
374e0 20 74 68 65 20 66 6f 72 6d 61 74 20 28 74 68 65   the format (the
374f0 20 6e 61 6d 65 73 20 61 6e 64 20 64 61 74 61 74   names and datat
37500 79 70 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75  ypes of the colu
37510 6d 6e 73 29 20 6f 66 0a 2a 2a 20 74 68 65 20 76  mns) of.** the v
37520 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 74 68  irtual tables th
37530 65 79 20 69 6d 70 6c 65 6d 65 6e 74 2e 0a 2a 2f  ey implement..*/
37540 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 65 63  .int sqlite3_dec
37550 6c 61 72 65 5f 76 74 61 62 28 73 71 6c 69 74 65  lare_vtab(sqlite
37560 33 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  3*, const char *
37570 7a 43 72 65 61 74 65 54 61 62 6c 65 29 3b 0a 0a  zCreateTable);..
37580 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
37590 4f 76 65 72 6c 6f 61 64 20 41 20 46 75 6e 63 74  Overload A Funct
375a0 69 6f 6e 20 46 6f 72 20 41 20 56 69 72 74 75 61  ion For A Virtua
375b0 6c 20 54 61 62 6c 65 20 7b 46 31 38 33 30 30 7d  l Table {F18300}
375c0 0a 2a 2a 0a 2a 2a 20 56 69 72 74 75 61 6c 20 74  .**.** Virtual t
375d0 61 62 6c 65 73 20 63 61 6e 20 70 72 6f 76 69 64  ables can provid
375e0 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20 69 6d  e alternative im
375f0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66  plementations of
37600 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 75 73   functions.** us
37610 69 6e 67 20 74 68 65 20 78 46 69 6e 64 46 75 6e  ing the xFindFun
37620 63 74 69 6f 6e 20 6d 65 74 68 6f 64 2e 20 20 42  ction method.  B
37630 75 74 20 67 6c 6f 62 61 6c 20 76 65 72 73 69 6f  ut global versio
37640 6e 73 20 6f 66 20 74 68 6f 73 65 20 66 75 6e 63  ns of those func
37650 74 69 6f 6e 73 0a 2a 2a 20 6d 75 73 74 20 65 78  tions.** must ex
37660 69 73 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ist in order to 
37670 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 2e 0a 2a  be overloaded..*
37680 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49 20 6d 61  *.** This API ma
37690 6b 65 73 20 73 75 72 65 20 61 20 67 6c 6f 62 61  kes sure a globa
376a0 6c 20 76 65 72 73 69 6f 6e 20 6f 66 20 61 20 66  l version of a f
376b0 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 70  unction with a p
376c0 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 6e 61 6d  articular.** nam
376d0 65 20 61 6e 64 20 6e 75 6d 62 65 72 20 6f 66 20  e and number of 
376e0 70 61 72 61 6d 65 74 65 72 73 20 65 78 69 73 74  parameters exist
376f0 73 2e 20 20 49 66 20 6e 6f 20 73 75 63 68 20 66  s.  If no such f
37700 75 6e 63 74 69 6f 6e 20 65 78 69 73 74 73 0a 2a  unction exists.*
37710 2a 20 62 65 66 6f 72 65 20 74 68 69 73 20 41 50  * before this AP
37720 49 20 69 73 20 63 61 6c 6c 65 64 2c 20 61 20 6e  I is called, a n
37730 65 77 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63  ew function is c
37740 72 65 61 74 65 64 2e 20 20 54 68 65 20 69 6d 70  reated.  The imp
37750 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f  lementation.** o
37760 66 20 74 68 65 20 6e 65 77 20 66 75 6e 63 74 69  f the new functi
37770 6f 6e 20 61 6c 77 61 79 73 20 63 61 75 73 65 73  on always causes
37780 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 74 6f   an exception to
37790 20 62 65 20 74 68 72 6f 77 6e 2e 20 20 53 6f 0a   be thrown.  So.
377a0 2a 2a 20 74 68 65 20 6e 65 77 20 66 75 6e 63 74  ** the new funct
377b0 69 6f 6e 20 69 73 20 6e 6f 74 20 67 6f 6f 64 20  ion is not good 
377c0 66 6f 72 20 61 6e 79 74 68 69 6e 67 20 62 79 20  for anything by 
377d0 69 74 73 65 6c 66 2e 20 20 49 74 73 20 6f 6e 6c  itself.  Its onl
377e0 79 0a 2a 2a 20 70 75 72 70 6f 73 65 20 69 73 20  y.** purpose is 
377f0 74 6f 20 62 65 20 61 20 70 6c 61 63 65 2d 68 6f  to be a place-ho
37800 6c 64 65 72 20 66 75 6e 63 74 69 6f 6e 20 74 68  lder function th
37810 61 74 20 63 61 6e 20 62 65 20 6f 76 65 72 6c 6f  at can be overlo
37820 61 64 65 64 0a 2a 2a 20 62 79 20 76 69 72 74 75  aded.** by virtu
37830 61 6c 20 74 61 62 6c 65 73 2e 0a 2a 2a 0a 2a 2a  al tables..**.**
37840 20 54 68 69 73 20 41 50 49 20 73 68 6f 75 6c 64   This API should
37850 20 62 65 20 63 6f 6e 73 69 64 65 72 65 64 20 70   be considered p
37860 61 72 74 20 6f 66 20 74 68 65 20 76 69 72 74 75  art of the virtu
37870 61 6c 20 74 61 62 6c 65 20 69 6e 74 65 72 66 61  al table interfa
37880 63 65 2c 0a 2a 2a 20 77 68 69 63 68 20 69 73 20  ce,.** which is 
37890 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64  experimental and
378a0 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e   subject to chan
378b0 67 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ge..*/.int sqlit
378c0 65 33 5f 6f 76 65 72 6c 6f 61 64 5f 66 75 6e 63  e3_overload_func
378d0 74 69 6f 6e 28 73 71 6c 69 74 65 33 2a 2c 20 63  tion(sqlite3*, c
378e0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63  onst char *zFunc
378f0 4e 61 6d 65 2c 20 69 6e 74 20 6e 41 72 67 29 3b  Name, int nArg);
37900 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65  ../*.** The inte
37910 72 66 61 63 65 20 74 6f 20 74 68 65 20 76 69 72  rface to the vir
37920 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61  tual-table mecha
37930 6e 69 73 6d 20 64 65 66 69 6e 65 64 20 61 62 6f  nism defined abo
37940 76 65 20 28 62 61 63 6b 20 75 70 0a 2a 2a 20 74  ve (back up.** t
37950 6f 20 61 20 63 6f 6d 6d 65 6e 74 20 72 65 6d 61  o a comment rema
37960 72 6b 61 62 6c 79 20 73 69 6d 69 6c 61 72 20 74  rkably similar t
37970 6f 20 74 68 69 73 20 6f 6e 65 29 20 69 73 20 63  o this one) is c
37980 75 72 72 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65  urrently conside
37990 72 65 64 0a 2a 2a 20 74 6f 20 62 65 20 65 78 70  red.** to be exp
379a0 65 72 69 6d 65 6e 74 61 6c 2e 20 20 54 68 65 20  erimental.  The 
379b0 69 6e 74 65 72 66 61 63 65 20 6d 69 67 68 74 20  interface might 
379c0 63 68 61 6e 67 65 20 69 6e 20 69 6e 63 6f 6d 70  change in incomp
379d0 61 74 69 62 6c 65 20 77 61 79 73 2e 0a 2a 2a 20  atible ways..** 
379e0 49 66 20 74 68 69 73 20 69 73 20 61 20 70 72 6f  If this is a pro
379f0 62 6c 65 6d 20 66 6f 72 20 79 6f 75 2c 20 64 6f  blem for you, do
37a00 20 6e 6f 74 20 75 73 65 20 74 68 65 20 69 6e 74   not use the int
37a10 65 72 66 61 63 65 20 61 74 20 74 68 69 73 20 74  erface at this t
37a20 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  ime..**.** When 
37a30 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c  the virtual-tabl
37a40 65 20 6d 65 63 68 61 6e 69 73 6d 20 73 74 61 62  e mechanism stab
37a50 69 6c 69 7a 65 73 2c 20 77 65 20 77 69 6c 6c 20  ilizes, we will 
37a60 64 65 63 6c 61 72 65 20 74 68 65 0a 2a 2a 20 69  declare the.** i
37a70 6e 74 65 72 66 61 63 65 20 66 69 78 65 64 2c 20  nterface fixed, 
37a80 73 75 70 70 6f 72 74 20 69 74 20 69 6e 64 65 66  support it indef
37a90 69 6e 69 74 65 6c 79 2c 20 61 6e 64 20 72 65 6d  initely, and rem
37aa0 6f 76 65 20 74 68 69 73 20 63 6f 6d 6d 65 6e 74  ove this comment
37ab0 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 20 45 58 50 45  ..**.****** EXPE
37ac0 52 49 4d 45 4e 54 41 4c 20 2d 20 73 75 62 6a 65  RIMENTAL - subje
37ad0 63 74 20 74 6f 20 63 68 61 6e 67 65 20 77 69 74  ct to change wit
37ae0 68 6f 75 74 20 6e 6f 74 69 63 65 20 2a 2a 2a 2a  hout notice ****
37af0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2f 0a 0a 2f  **********.*/../
37b00 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41  *.** CAPI3REF: A
37b10 20 48 61 6e 64 6c 65 20 54 6f 20 41 6e 20 4f 70   Handle To An Op
37b20 65 6e 20 42 4c 4f 42 20 7b 46 31 37 38 30 30 7d  en BLOB {F17800}
37b30 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e  .**.** An instan
37b40 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
37b50 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20  t represents an 
37b60 6f 70 65 6e 20 42 4c 4f 42 20 6f 6e 20 77 68 69  open BLOB on whi
37b70 63 68 0a 2a 2a 20 69 6e 63 72 65 6d 65 6e 74 61  ch.** incrementa
37b80 6c 20 49 2f 4f 20 63 61 6e 20 62 65 20 70 72 65  l I/O can be pre
37b90 66 6f 72 6d 65 64 2e 0a 2a 2a 20 4f 62 6a 65 63  formed..** Objec
37ba0 74 73 20 6f 66 20 74 68 69 73 20 74 79 70 65 20  ts of this type 
37bb0 61 72 65 20 63 72 65 61 74 65 64 20 62 79 0a 2a  are created by.*
37bc0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  * [sqlite3_blob_
37bd0 6f 70 65 6e 28 29 5d 20 61 6e 64 20 64 65 73 74  open()] and dest
37be0 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65  royed by [sqlite
37bf0 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e  3_blob_close()].
37c00 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
37c10 5f 62 6c 6f 62 5f 72 65 61 64 28 29 5d 20 61 6e  _blob_read()] an
37c20 64 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  d [sqlite3_blob_
37c30 77 72 69 74 65 28 29 5d 20 69 6e 74 65 72 66 61  write()] interfa
37c40 63 65 73 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73  ces.** can be us
37c50 65 64 20 74 6f 20 72 65 61 64 20 6f 72 20 77 72  ed to read or wr
37c60 69 74 65 20 73 6d 61 6c 6c 20 73 75 62 73 65 63  ite small subsec
37c70 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 62 6c 6f  tions of the blo
37c80 62 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  b..** The [sqlit
37c90 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28 29 5d  e3_blob_bytes()]
37ca0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
37cb0 6e 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  ns the size of t
37cc0 68 65 0a 2a 2a 20 62 6c 6f 62 20 69 6e 20 62 79  he.** blob in by
37cd0 74 65 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  tes..*/.typedef 
37ce0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 62  struct sqlite3_b
37cf0 6c 6f 62 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62  lob sqlite3_blob
37d00 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
37d10 46 3a 20 4f 70 65 6e 20 41 20 42 4c 4f 42 20 46  F: Open A BLOB F
37d20 6f 72 20 49 6e 63 72 65 6d 65 6e 74 61 6c 20 49  or Incremental I
37d30 2f 4f 20 7b 46 31 37 38 31 30 7d 0a 2a 2a 0a 2a  /O {F17810}.**.*
37d40 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65  * This interface
37d50 73 20 6f 70 65 6e 73 20 61 20 68 61 6e 64 6c 65  s opens a handle
37d60 20 74 6f 20 74 68 65 20 62 6c 6f 62 20 6c 6f 63   to the blob loc
37d70 61 74 65 64 0a 2a 2a 20 69 6e 20 72 6f 77 20 69  ated.** in row i
37d80 52 6f 77 2c 20 63 6f 6c 75 6d 6e 20 7a 43 6f 6c  Row, column zCol
37d90 75 6d 6e 2c 20 74 61 62 6c 65 20 7a 54 61 62 6c  umn, table zTabl
37da0 65 20 69 6e 20 64 61 74 61 62 61 73 65 20 7a 44  e in database zD
37db0 62 3b 0a 2a 2a 20 69 6e 20 6f 74 68 65 72 20 77  b;.** in other w
37dc0 6f 72 64 73 2c 20 20 74 68 65 20 73 61 6d 65 20  ords,  the same 
37dd0 62 6c 6f 62 20 74 68 61 74 20 77 6f 75 6c 64 20  blob that would 
37de0 62 65 20 73 65 6c 65 63 74 65 64 20 62 79 3a 0a  be selected by:.
37df0 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20  **.** <pre>.**  
37e00 20 20 20 53 45 4c 45 43 54 20 7a 43 6f 6c 75 6d     SELECT zColum
37e10 6e 20 46 52 4f 4d 20 7a 44 62 2e 7a 54 61 62 6c  n FROM zDb.zTabl
37e20 65 20 57 48 45 52 45 20 72 6f 77 69 64 20 3d 20  e WHERE rowid = 
37e30 69 52 6f 77 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 20  iRow;.** </pre> 
37e40 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 49 66 20 74  {END}.**.** If t
37e50 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74  he flags paramet
37e60 65 72 20 69 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  er is non-zero, 
37e70 74 68 65 20 62 6c 6f 62 20 69 73 20 6f 70 65 6e  the blob is open
37e80 65 64 20 66 6f 72 20 0a 2a 2a 20 72 65 61 64 20  ed for .** read 
37e90 61 6e 64 20 77 72 69 74 65 20 61 63 63 65 73 73  and write access
37ea0 2e 20 49 66 20 69 74 20 69 73 20 7a 65 72 6f 2c  . If it is zero,
37eb0 20 74 68 65 20 62 6c 6f 62 20 69 73 20 6f 70 65   the blob is ope
37ec0 6e 65 64 20 66 6f 72 20 72 65 61 64 20 0a 2a 2a  ned for read .**
37ed0 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 4e   access..**.** N
37ee0 6f 74 65 20 74 68 61 74 20 74 68 65 20 64 61 74  ote that the dat
37ef0 61 62 61 73 65 20 6e 61 6d 65 20 69 73 20 6e 6f  abase name is no
37f00 74 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 74  t the filename t
37f10 68 61 74 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20  hat contains.** 
37f20 74 68 65 20 64 61 74 61 62 61 73 65 20 62 75 74  the database but
37f30 20 72 61 74 68 65 72 20 74 68 65 20 73 79 6d 62   rather the symb
37f40 6f 6c 69 63 20 6e 61 6d 65 20 6f 66 20 74 68 65  olic name of the
37f50 20 64 61 74 61 62 61 73 65 20 74 68 61 74 0a 2a   database that.*
37f60 2a 20 69 73 20 61 73 73 69 67 6e 65 64 20 77 68  * is assigned wh
37f70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
37f80 69 73 20 63 6f 6e 6e 65 63 74 65 64 20 75 73 69  is connected usi
37f90 6e 67 20 5b 41 54 54 41 43 48 5d 2e 0a 2a 2a 20  ng [ATTACH]..** 
37fa0 46 6f 72 20 74 68 65 20 6d 61 69 6e 20 64 61 74  For the main dat
37fb0 61 62 61 73 65 20 66 69 6c 65 2c 20 74 68 65 20  abase file, the 
37fc0 64 61 74 61 62 61 73 65 20 6e 61 6d 65 20 69 73  database name is
37fd0 20 22 6d 61 69 6e 22 2e 20 20 46 6f 72 0a 2a 2a   "main".  For.**
37fe0 20 54 45 4d 50 20 74 61 62 6c 65 73 2c 20 74 68   TEMP tables, th
37ff0 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 20  e database name 
38000 69 73 20 22 74 65 6d 70 22 2e 0a 2a 2a 0a 2a 2a  is "temp"..**.**
38010 20 4f 6e 20 73 75 63 63 65 73 73 2c 20 5b 53 51   On success, [SQ
38020 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75  LITE_OK] is retu
38030 72 6e 65 64 20 61 6e 64 20 74 68 65 20 6e 65 77  rned and the new
38040 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c   .** [sqlite3_bl
38050 6f 62 20 7c 20 62 6c 6f 62 20 68 61 6e 64 6c 65  ob | blob handle
38060 5d 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20  ] is written to 
38070 2a 70 70 42 6c 6f 62 2e 20 0a 2a 2a 20 4f 74 68  *ppBlob. .** Oth
38080 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20  erwise an error 
38090 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64  code is returned
380a0 20 61 6e 64 20 0a 2a 2a 20 61 6e 79 20 76 61 6c   and .** any val
380b0 75 65 20 77 72 69 74 74 65 6e 20 74 6f 20 2a 70  ue written to *p
380c0 70 42 6c 6f 62 20 73 68 6f 75 6c 64 20 6e 6f 74  pBlob should not
380d0 20 62 65 20 75 73 65 64 20 62 79 20 74 68 65 20   be used by the 
380e0 63 61 6c 6c 65 72 2e 0a 2a 2a 20 54 68 69 73 20  caller..** This 
380f0 66 75 6e 63 74 69 6f 6e 20 73 65 74 73 20 74 68  function sets th
38100 65 20 64 61 74 61 62 61 73 65 2d 68 61 6e 64 6c  e database-handl
38110 65 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64  e error code and
38120 20 6d 65 73 73 61 67 65 0a 2a 2a 20 61 63 63 65   message.** acce
38130 73 73 69 62 6c 65 20 76 69 61 20 5b 73 71 6c 69  ssible via [sqli
38140 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 61  te3_errcode()] a
38150 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  nd [sqlite3_errm
38160 73 67 28 29 5d 2e 0a 2a 2a 20 0a 2a 2a 20 49 4e  sg()]..** .** IN
38170 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
38180 7b 46 31 37 38 31 33 7d 20 41 20 73 75 63 63 65  {F17813} A succe
38190 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e  ssful invocation
381a0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
381b0 5f 62 6c 6f 62 5f 6f 70 65 6e 28 44 2c 42 2c 54  _blob_open(D,B,T
381c0 2c 43 2c 52 2c 46 2c 50 29 5d 0a 2a 2a 20 20 20  ,C,R,F,P)].**   
381d0 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65         interface
381e0 20 6f 70 65 6e 73 20 61 6e 20 5b 73 71 6c 69 74   opens an [sqlit
381f0 65 33 5f 62 6c 6f 62 5d 20 6f 62 6a 65 63 74 20  e3_blob] object 
38200 50 20 6f 6e 20 74 68 65 20 62 6c 6f 62 0a 2a 2a  P on the blob.**
38210 20 20 20 20 20 20 20 20 20 20 69 6e 20 63 6f 6c            in col
38220 75 6d 6e 20 43 20 6f 66 20 74 61 62 6c 65 20 54  umn C of table T
38230 20 69 6e 20 64 61 74 61 62 61 73 65 20 42 20 6f   in database B o
38240 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
38250 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a  ection] D..**.**
38260 20 7b 46 31 37 38 31 34 7d 20 41 20 73 75 63 63   {F17814} A succ
38270 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f  essful invocatio
38280 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 62 6c  n of [sqlite3_bl
38290 6f 62 5f 6f 70 65 6e 28 44 2c 2e 2e 2e 29 5d 20  ob_open(D,...)] 
382a0 73 74 61 72 74 73 0a 2a 2a 20 20 20 20 20 20 20  starts.**       
382b0 20 20 20 61 20 6e 65 77 20 74 72 61 6e 73 61 63     a new transac
382c0 74 69 6f 6e 20 6f 6e 20 5b 64 61 74 61 62 61 73  tion on [databas
382d0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20  e connection] D 
382e0 69 66 20 74 68 61 74 20 63 6f 6e 6e 65 63 74 69  if that connecti
382f0 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  on.**          i
38300 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 69 6e  s not already in
38310 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 0a   a transaction..
38320 2a 2a 0a 2a 2a 20 7b 46 31 37 38 31 36 7d 20 54  **.** {F17816} T
38330 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  he [sqlite3_blob
38340 5f 6f 70 65 6e 28 44 2c 42 2c 54 2c 43 2c 52 2c  _open(D,B,T,C,R,
38350 46 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20  F,P)] interface 
38360 6f 70 65 6e 73 20 74 68 65 20 62 6c 6f 62 0a 2a  opens the blob.*
38370 2a 20 20 20 20 20 20 20 20 20 20 66 6f 72 20 72  *          for r
38380 65 61 64 20 61 6e 64 20 77 72 69 74 65 20 61 63  ead and write ac
38390 63 65 73 73 20 69 66 20 61 6e 64 20 6f 6e 6c 79  cess if and only
383a0 20 69 66 20 74 68 65 20 46 20 70 61 72 61 6d 65   if the F parame
383b0 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ter.**          
383c0 69 73 20 6e 6f 6e 2d 7a 65 72 6f 2e 0a 2a 2a 0a  is non-zero..**.
383d0 2a 2a 20 7b 46 31 37 38 31 39 7d 20 54 68 65 20  ** {F17819} The 
383e0 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70  [sqlite3_blob_op
383f0 65 6e 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  en()] interface 
38400 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
38410 4f 4b 5d 20 6f 6e 20 0a 2a 2a 20 20 20 20 20 20  OK] on .**      
38420 20 20 20 20 73 75 63 63 65 73 73 20 61 6e 64 20      success and 
38430 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b  an appropriate [
38440 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 6e 20 66  error code] on f
38450 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46  ailure..**.** {F
38460 31 37 38 32 31 7d 20 49 66 20 61 6e 20 65 72 72  17821} If an err
38470 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67  or occurs during
38480 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 5b   evaluation of [
38490 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65  sqlite3_blob_ope
384a0 6e 28 44 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20  n(D,...)].**    
384b0 20 20 20 20 20 20 74 68 65 6e 20 73 75 62 73 65        then subse
384c0 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b  quent calls to [
384d0 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
384e0 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  D)],.**         
384f0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
38500 28 44 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  (D)], and [sqlit
38510 65 33 5f 65 72 72 6d 73 67 31 36 28 44 29 5d 20  e3_errmsg16(D)] 
38520 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 20  will return.**  
38530 20 20 20 20 20 20 20 20 69 6e 66 6f 72 6d 61 74          informat
38540 69 6f 6e 20 61 70 70 72 6f 70 72 61 74 65 20 66  ion approprate f
38550 6f 72 20 74 68 61 74 20 65 72 72 6f 72 2e 0a 2a  or that error..*
38560 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c  /.int sqlite3_bl
38570 6f 62 5f 6f 70 65 6e 28 0a 20 20 73 71 6c 69 74  ob_open(.  sqlit
38580 65 33 2a 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61  e3*,.  const cha
38590 72 20 2a 7a 44 62 2c 0a 20 20 63 6f 6e 73 74 20  r *zDb,.  const 
385a0 63 68 61 72 20 2a 7a 54 61 62 6c 65 2c 0a 20 20  char *zTable,.  
385b0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 43 6f 6c  const char *zCol
385c0 75 6d 6e 2c 0a 20 20 73 71 6c 69 74 65 33 5f 69  umn,.  sqlite3_i
385d0 6e 74 36 34 20 69 52 6f 77 2c 0a 20 20 69 6e 74  nt64 iRow,.  int
385e0 20 66 6c 61 67 73 2c 0a 20 20 73 71 6c 69 74 65   flags,.  sqlite
385f0 33 5f 62 6c 6f 62 20 2a 2a 70 70 42 6c 6f 62 0a  3_blob **ppBlob.
38600 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
38610 45 46 3a 20 20 43 6c 6f 73 65 20 41 20 42 4c 4f  EF:  Close A BLO
38620 42 20 48 61 6e 64 6c 65 20 7b 46 31 37 38 33 30  B Handle {F17830
38630 7d 0a 2a 2a 0a 2a 2a 20 43 6c 6f 73 65 20 61 6e  }.**.** Close an
38640 20 6f 70 65 6e 20 5b 73 71 6c 69 74 65 33 5f 62   open [sqlite3_b
38650 6c 6f 62 20 7c 20 62 6c 6f 62 20 68 61 6e 64 6c  lob | blob handl
38660 65 5d 2e 0a 2a 2a 0a 2a 2a 20 43 6c 6f 73 69 6e  e]..**.** Closin
38670 67 20 61 20 42 4c 4f 42 20 73 68 61 6c 6c 20 63  g a BLOB shall c
38680 61 75 73 65 20 74 68 65 20 63 75 72 72 65 6e 74  ause the current
38690 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20   transaction to 
386a0 63 6f 6d 6d 69 74 0a 2a 2a 20 69 66 20 74 68 65  commit.** if the
386b0 72 65 20 61 72 65 20 6e 6f 20 6f 74 68 65 72 20  re are no other 
386c0 42 4c 4f 42 73 2c 20 6e 6f 20 70 65 6e 64 69 6e  BLOBs, no pendin
386d0 67 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  g prepared state
386e0 6d 65 6e 74 73 2c 20 61 6e 64 20 74 68 65 0a 2a  ments, and the.*
386f0 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
38700 63 74 69 6f 6e 20 69 73 20 69 6e 20 61 75 74 6f  ction is in auto
38710 63 6f 6d 6d 69 74 20 6d 6f 64 65 2e 0a 2a 2a 20  commit mode..** 
38720 49 66 20 61 6e 79 20 77 72 69 74 65 73 20 77 65  If any writes we
38730 72 65 20 6d 61 64 65 20 74 6f 20 74 68 65 20 42  re made to the B
38740 4c 4f 42 2c 20 74 68 65 79 20 6d 69 67 68 74 20  LOB, they might 
38750 62 65 20 68 65 6c 64 20 69 6e 20 63 61 63 68 65  be held in cache
38760 0a 2a 2a 20 75 6e 74 69 6c 20 74 68 65 20 63 6c  .** until the cl
38770 6f 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 66  ose operation if
38780 20 74 68 65 79 20 77 69 6c 6c 20 66 69 74 2e 20   they will fit. 
38790 7b 45 4e 44 7d 0a 2a 2a 20 43 6c 6f 73 69 6e 67  {END}.** Closing
387a0 20 74 68 65 20 42 4c 4f 42 20 6f 66 74 65 6e 20   the BLOB often 
387b0 66 6f 72 63 65 73 20 74 68 65 20 63 68 61 6e 67  forces the chang
387c0 65 73 0a 2a 2a 20 6f 75 74 20 74 6f 20 64 69 73  es.** out to dis
387d0 6b 20 61 6e 64 20 73 6f 20 69 66 20 61 6e 79 20  k and so if any 
387e0 49 2f 4f 20 65 72 72 6f 72 73 20 6f 63 63 75 72  I/O errors occur
387f0 2c 20 74 68 65 79 20 77 69 6c 6c 20 6c 69 6b 65  , they will like
38800 6c 79 20 6f 63 63 75 72 0a 2a 2a 20 61 74 20 74  ly occur.** at t
38810 68 65 20 74 69 6d 65 20 77 68 65 6e 20 74 68 65  he time when the
38820 20 42 4c 4f 42 20 69 73 20 63 6c 6f 73 65 64 2e   BLOB is closed.
38830 20 20 7b 46 31 37 38 33 33 7d 20 41 6e 79 20 65    {F17833} Any e
38840 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72  rrors that occur
38850 20 64 75 72 69 6e 67 0a 2a 2a 20 63 6c 6f 73 69   during.** closi
38860 6e 67 20 61 72 65 20 72 65 70 6f 72 74 65 64 20  ng are reported 
38870 61 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 72 65  as a non-zero re
38880 74 75 72 6e 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a  turn value..**.*
38890 2a 20 54 68 65 20 42 4c 4f 42 20 69 73 20 63 6c  * The BLOB is cl
388a0 6f 73 65 64 20 75 6e 63 6f 6e 64 69 74 69 6f 6e  osed uncondition
388b0 61 6c 6c 79 2e 20 20 45 76 65 6e 20 69 66 20 74  ally.  Even if t
388c0 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75  his routine retu
388d0 72 6e 73 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20  rns.** an error 
388e0 63 6f 64 65 2c 20 74 68 65 20 42 4c 4f 42 20 69  code, the BLOB i
388f0 73 20 73 74 69 6c 6c 20 63 6c 6f 73 65 64 2e 0a  s still closed..
38900 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
38910 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 38 33 33 7d  :.**.** {F17833}
38920 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c   The [sqlite3_bl
38930 6f 62 5f 63 6c 6f 73 65 28 50 29 5d 20 69 6e 74  ob_close(P)] int
38940 65 72 66 61 63 65 20 63 6c 6f 73 65 73 20 61 6e  erface closes an
38950 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
38960 6c 69 74 65 33 5f 62 6c 6f 62 5d 20 6f 62 6a 65  lite3_blob] obje
38970 63 74 20 50 20 70 72 65 76 69 6f 7