/ Hex Artifact Content
Login

Artifact 487f5490a9677ef0c105c21a9595bb587be1da6a:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 20 0a 2a 2a 20 74 6f  e changes .** to
0390: 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e   experimental in
03a0: 74 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73  terfaces but res
03b0: 65 72 76 65 20 74 6f 20 6d 61 6b 65 20 6d 69 6e  erve to make min
03c0: 6f 72 20 63 68 61 6e 67 65 73 20 69 66 0a 2a 2a  or changes if.**
03d0: 20 65 78 70 65 72 69 65 6e 63 65 20 66 72 6f 6d   experience from
03e0: 20 75 73 65 20 22 69 6e 20 74 68 65 20 77 69 6c   use "in the wil
03f0: 64 22 20 73 75 67 67 65 73 74 20 73 75 63 68 20  d" suggest such 
0400: 63 68 61 6e 67 65 73 20 61 72 65 20 70 72 75 64  changes are prud
0410: 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f  ent..**.** The o
0420: 66 66 69 63 69 61 6c 20 43 2d 6c 61 6e 67 75 61  fficial C-langua
0430: 67 65 20 41 50 49 20 64 6f 63 75 6d 65 6e 74 61  ge API documenta
0440: 74 69 6f 6e 20 66 6f 72 20 53 51 4c 69 74 65 20  tion for SQLite 
0450: 69 73 20 64 65 72 69 76 65 64 0a 2a 2a 20 66 72  is derived.** fr
0460: 6f 6d 20 63 6f 6d 6d 65 6e 74 73 20 69 6e 20 74  om comments in t
0470: 68 69 73 20 66 69 6c 65 2e 20 20 54 68 69 73 20  his file.  This 
0480: 66 69 6c 65 20 69 73 20 74 68 65 20 61 75 74 68  file is the auth
0490: 6f 72 69 74 61 74 69 76 65 20 73 6f 75 72 63 65  oritative source
04a0: 0a 2a 2a 20 6f 6e 20 68 6f 77 20 53 51 4c 69 74  .** on how SQLit
04b0: 65 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  e interfaces are
04c0: 20 73 75 70 70 6f 73 65 20 74 6f 20 6f 70 65 72   suppose to oper
04d0: 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e  ate..**.** The n
04e0: 61 6d 65 20 6f 66 20 74 68 69 73 20 66 69 6c 65  ame of this file
04f0: 20 75 6e 64 65 72 20 63 6f 6e 66 69 67 75 72 61   under configura
0500: 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 20  tion management 
0510: 69 73 20 22 73 71 6c 69 74 65 2e 68 2e 69 6e 22  is "sqlite.h.in"
0520: 2e 0a 2a 2a 20 54 68 65 20 6d 61 6b 65 66 69 6c  ..** The makefil
0530: 65 20 6d 61 6b 65 73 20 73 6f 6d 65 20 6d 69 6e  e makes some min
0540: 6f 72 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  or changes to th
0550: 69 73 20 66 69 6c 65 20 28 73 75 63 68 20 61 73  is file (such as
0560: 20 69 6e 73 65 72 74 69 6e 67 0a 2a 2a 20 74 68   inserting.** th
0570: 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72  e version number
0580: 29 20 61 6e 64 20 63 68 61 6e 67 65 73 20 69 74  ) and changes it
0590: 73 20 6e 61 6d 65 20 74 6f 20 22 73 71 6c 69 74  s name to "sqlit
05a0: 65 33 2e 68 22 20 61 73 0a 2a 2a 20 70 61 72 74  e3.h" as.** part
05b0: 20 6f 66 20 74 68 65 20 62 75 69 6c 64 20 70 72   of the build pr
05c0: 6f 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 40 28 23  ocess..**.** @(#
05d0: 29 20 24 49 64 3a 20 73 71 6c 69 74 65 2e 68 2e  ) $Id: sqlite.h.
05e0: 69 6e 2c 76 20 31 2e 33 32 36 20 32 30 30 38 2f  in,v 1.326 2008/
05f0: 30 36 2f 31 33 20 31 38 3a 32 34 3a 32 37 20 64  06/13 18:24:27 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 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1680: 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  : Database Conne
1690: 63 74 69 6f 6e 20 48 61 6e 64 6c 65 20 7b 46 31  ction Handle {F1
16a0: 32 30 30 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  2000}.** KEYWORD
16b0: 53 3a 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e  S: {database con
16c0: 6e 65 63 74 69 6f 6e 7d 20 7b 64 61 74 61 62 61  nection} {databa
16d0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d 0a  se connections}.
16e0: 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20  **.** Each open 
16f0: 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20  SQLite database 
1700: 69 73 20 72 65 70 72 65 73 65 6e 74 65 64 20 62  is represented b
1710: 79 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  y pointer to an 
1720: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 0a  instance of the.
1730: 2a 2a 20 6f 70 61 71 75 65 20 73 74 72 75 63 74  ** opaque struct
1740: 75 72 65 20 6e 61 6d 65 64 20 22 73 71 6c 69 74  ure named "sqlit
1750: 65 33 22 2e 20 20 49 74 20 69 73 20 75 73 65 66  e3".  It is usef
1760: 75 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61  ul to think of a
1770: 6e 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69  n sqlite3.** poi
1780: 6e 74 65 72 20 61 73 20 61 6e 20 6f 62 6a 65 63  nter as an objec
1790: 74 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  t.  The [sqlite3
17a0: 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
17b0: 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e  e3_open16()], an
17c0: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70  d.** [sqlite3_op
17d0: 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61  en_v2()] interfa
17e0: 63 65 73 20 61 72 65 20 69 74 73 20 63 6f 6e 73  ces are its cons
17f0: 74 72 75 63 74 6f 72 73 0a 2a 2a 20 61 6e 64 20  tructors.** and 
1800: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29  [sqlite3_close()
1810: 5d 20 69 73 20 69 74 73 20 64 65 73 74 72 75 63  ] is its destruc
1820: 74 6f 72 2e 20 20 54 68 65 72 65 20 61 72 65 20  tor.  There are 
1830: 6d 61 6e 79 20 6f 74 68 65 72 20 69 6e 74 65 72  many other inter
1840: 66 61 63 65 73 0a 2a 2a 20 28 73 75 63 68 20 61  faces.** (such a
1850: 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  s [sqlite3_prepa
1860: 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74  re_v2()], [sqlit
1870: 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
1880: 6f 6e 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  on()], and.** [s
1890: 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65  qlite3_busy_time
18a0: 6f 75 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20 62  out()] to name b
18b0: 75 74 20 74 68 72 65 65 29 20 74 68 61 74 20 61  ut three) that a
18c0: 72 65 20 6d 65 74 68 6f 64 73 20 6f 6e 20 74 68  re methods on th
18d0: 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 2e 0a 2a 2f  is.** object..*/
18e0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
18f0: 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65 33 3b  sqlite3 sqlite3;
1900: 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
1910: 46 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67 65  F: 64-Bit Intege
1920: 72 20 54 79 70 65 73 20 7b 46 31 30 32 30 30 7d  r Types {F10200}
1930: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71  .** KEYWORDS: sq
1940: 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69 74  lite_int64 sqlit
1950: 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a 20 42  e_uint64.**.** B
1960: 65 63 61 75 73 65 20 74 68 65 72 65 20 69 73 20  ecause there is 
1970: 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66 6f 72  no cross-platfor
1980: 6d 20 77 61 79 20 74 6f 20 73 70 65 63 69 66 79  m way to specify
1990: 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20   64-bit integer 
19a0: 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74 65 20  types.** SQLite 
19b0: 69 6e 63 6c 75 64 65 73 20 74 79 70 65 64 65 66  includes typedef
19c0: 73 20 66 6f 72 20 36 34 2d 62 69 74 20 73 69 67  s for 64-bit sig
19d0: 6e 65 64 20 61 6e 64 20 75 6e 73 69 67 6e 65 64  ned and unsigned
19e0: 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a 2a 2a   integers..**.**
19f0: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74   The sqlite3_int
1a00: 36 34 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 75  64 and sqlite3_u
1a10: 69 6e 74 36 34 20 61 72 65 20 74 68 65 20 70 72  int64 are the pr
1a20: 65 66 65 72 72 65 64 20 74 79 70 65 0a 2a 2a 20  eferred type.** 
1a30: 64 65 66 69 6e 69 74 69 6f 6e 73 2e 20 20 54 68  definitions.  Th
1a40: 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 61  e sqlite_int64 a
1a50: 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  nd sqlite_uint64
1a60: 20 74 79 70 65 73 20 61 72 65 0a 2a 2a 20 73 75   types are.** su
1a70: 70 70 6f 72 74 65 64 20 66 6f 72 20 62 61 63 6b  pported for back
1a80: 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
1a90: 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ity only..**.** 
1aa0: 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
1ab0: 2a 20 7b 46 31 30 32 30 31 7d 20 54 68 65 20 5b  * {F10201} The [
1ac0: 73 71 6c 69 74 65 5f 69 6e 74 36 34 5d 20 61 6e  sqlite_int64] an
1ad0: 64 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  d [sqlite3_int64
1ae0: 5d 20 74 79 70 65 73 20 73 70 65 63 69 66 79 20  ] types specify 
1af0: 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 36 34  a.**          64
1b00: 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
1b10: 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 32  ger..**.** {F102
1b20: 30 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 5f  02} The [sqlite_
1b30: 75 69 6e 74 36 34 5d 20 61 6e 64 20 5b 73 71 6c  uint64] and [sql
1b40: 69 74 65 33 5f 75 69 6e 74 36 34 5d 20 74 79 70  ite3_uint64] typ
1b50: 65 73 20 73 70 65 63 69 66 79 0a 2a 2a 20 20 20  es specify.**   
1b60: 20 20 20 20 20 20 20 61 20 36 34 2d 62 69 74 20         a 64-bit 
1b70: 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  unsigned integer
1b80: 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49  ..*/.#ifdef SQLI
1b90: 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 0a 20 20  TE_INT64_TYPE.  
1ba0: 74 79 70 65 64 65 66 20 53 51 4c 49 54 45 5f 49  typedef SQLITE_I
1bb0: 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74 65  NT64_TYPE sqlite
1bc0: 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65  _int64;.  typede
1bd0: 66 20 75 6e 73 69 67 6e 65 64 20 53 51 4c 49 54  f unsigned SQLIT
1be0: 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c  E_INT64_TYPE sql
1bf0: 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 69  ite_uint64;.#eli
1c00: 66 20 64 65 66 69 6e 65 64 28 5f 4d 53 43 5f 56  f defined(_MSC_V
1c10: 45 52 29 20 7c 7c 20 64 65 66 69 6e 65 64 28 5f  ER) || defined(_
1c20: 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a 20 20 74  _BORLANDC__).  t
1c30: 79 70 65 64 65 66 20 5f 5f 69 6e 74 36 34 20 73  ypedef __int64 s
1c40: 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74  qlite_int64;.  t
1c50: 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20  ypedef unsigned 
1c60: 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 75  __int64 sqlite_u
1c70: 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a 20 20 74  int64;.#else.  t
1c80: 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c 6f 6e 67  ypedef long long
1c90: 20 69 6e 74 20 73 71 6c 69 74 65 5f 69 6e 74 36   int sqlite_int6
1ca0: 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73  4;.  typedef uns
1cb0: 69 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f 6e 67 20  igned long long 
1cc0: 69 6e 74 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  int sqlite_uint6
1cd0: 34 3b 0a 23 65 6e 64 69 66 0a 74 79 70 65 64 65  4;.#endif.typede
1ce0: 66 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73  f sqlite_int64 s
1cf0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 3b 0a 74 79  qlite3_int64;.ty
1d00: 70 65 64 65 66 20 73 71 6c 69 74 65 5f 75 69 6e  pedef sqlite_uin
1d10: 74 36 34 20 73 71 6c 69 74 65 33 5f 75 69 6e 74  t64 sqlite3_uint
1d20: 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66 20 63 6f  64;../*.** If co
1d30: 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61 20 70 72  mpiling for a pr
1d40: 6f 63 65 73 73 6f 72 20 74 68 61 74 20 6c 61 63  ocessor that lac
1d50: 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  ks floating poin
1d60: 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a 20 73 75  t support,.** su
1d70: 62 73 74 69 74 75 74 65 20 69 6e 74 65 67 65 72  bstitute integer
1d80: 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67 2d 70 6f   for floating-po
1d90: 69 6e 74 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  int.*/.#ifdef SQ
1da0: 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f 41 54 49  LITE_OMIT_FLOATI
1db0: 4e 47 5f 50 4f 49 4e 54 0a 23 20 64 65 66 69 6e  NG_POINT.# defin
1dc0: 65 20 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33  e double sqlite3
1dd0: 5f 69 6e 74 36 34 0a 23 65 6e 64 69 66 0a 0a 2f  _int64.#endif../
1de0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
1df0: 6c 6f 73 69 6e 67 20 41 20 44 61 74 61 62 61 73  losing A Databas
1e00: 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 7b 46 31  e Connection {F1
1e10: 32 30 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73  2010}.**.** This
1e20: 20 72 6f 75 74 69 6e 65 20 69 73 20 74 68 65 20   routine is the 
1e30: 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74  destructor for t
1e40: 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a  he [sqlite3] obj
1e50: 65 63 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 41 70 70  ect.  .**.** App
1e60: 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  lications should
1e70: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
1e80: 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61  ze | finalize] a
1e90: 6c 6c 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  ll.** [prepared 
1ea0: 73 74 61 74 65 6d 65 6e 74 73 5d 20 61 6e 64 0a  statements] and.
1eb0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  ** [sqlite3_blob
1ec0: 5f 63 6c 6f 73 65 20 7c 20 63 6c 6f 73 65 5d 20  _close | close] 
1ed0: 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  all [sqlite3_blo
1ee0: 62 20 7c 20 42 4c 4f 42 73 5d 20 0a 2a 2a 20 61  b | BLOBs] .** a
1ef0: 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
1f00: 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a  he [sqlite3] obj
1f10: 65 63 74 20 70 72 69 6f 72 0a 2a 2a 20 74 6f 20  ect prior.** to 
1f20: 61 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 63 6c  attempting to cl
1f30: 6f 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ose the [sqlite3
1f40: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20  ] object..**.** 
1f50: 3c 74 6f 64 6f 3e 57 68 61 74 20 68 61 70 70 65  <todo>What happe
1f60: 6e 73 20 74 6f 20 70 65 6e 64 69 6e 67 20 74 72  ns to pending tr
1f70: 61 6e 73 61 63 74 69 6f 6e 73 3f 20 20 41 72 65  ansactions?  Are
1f80: 20 74 68 65 79 0a 2a 2a 20 72 6f 6c 6c 65 64 20   they.** rolled 
1f90: 62 61 63 6b 2c 20 6f 72 20 61 62 61 6e 64 6f 6e  back, or abandon
1fa0: 65 64 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a  ed?</todo>.**.**
1fb0: 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
1fc0: 2a 2a 20 7b 46 31 32 30 31 31 7d 20 54 68 65 20  ** {F12011} The 
1fd0: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29  [sqlite3_close()
1fe0: 5d 20 69 6e 74 65 72 66 61 63 65 20 64 65 73 74  ] interface dest
1ff0: 72 6f 79 73 20 61 6e 20 5b 73 71 6c 69 74 65 33  roys an [sqlite3
2000: 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 20 20 20 20  ] object.**     
2010: 20 20 20 20 20 61 6c 6c 6f 63 61 74 65 64 20 62       allocated b
2020: 79 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74  y a prior call t
2030: 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  o [sqlite3_open(
2040: 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  )],.**          
2050: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
2060: 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  )], or [sqlite3_
2070: 6f 70 65 6e 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a  open_v2()]..**.*
2080: 2a 20 7b 46 31 32 30 31 32 7d 20 54 68 65 20 5b  * {F12012} The [
2090: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d  sqlite3_close()]
20a0: 20 66 75 6e 63 74 69 6f 6e 20 72 65 6c 65 61 73   function releas
20b0: 65 73 20 61 6c 6c 20 6d 65 6d 6f 72 79 20 75 73  es all memory us
20c0: 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 20 20 20  ed by the.**    
20d0: 20 20 20 20 20 20 63 6f 6e 6e 65 63 74 69 6f 6e        connection
20e0: 20 61 6e 64 20 63 6c 6f 73 65 73 20 61 6c 6c 20   and closes all 
20f0: 6f 70 65 6e 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a  open files..**.*
2100: 2a 20 7b 46 31 32 30 31 33 7d 20 49 66 20 74 68  * {F12013} If th
2110: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
2120: 63 74 69 6f 6e 20 63 6f 6e 74 61 69 6e 73 0a 2a  ction contains.*
2130: 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70  *          [prep
2140: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
2150: 20 74 68 61 74 20 68 61 76 65 20 6e 6f 74 20 62   that have not b
2160: 65 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  een.**          
2170: 66 69 6e 61 6c 69 7a 65 64 20 62 79 20 5b 73 71  finalized by [sq
2180: 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
2190: 5d 2c 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33  ], then [sqlite3
21a0: 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 20 20 20  _close()].**    
21b0: 20 20 20 20 20 20 72 65 74 75 72 6e 73 20 5b 53        returns [S
21c0: 51 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 20  QLITE_BUSY] and 
21d0: 6c 65 61 76 65 73 20 74 68 65 20 63 6f 6e 6e 65  leaves the conne
21e0: 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2a 0a 2a  ction open..**.*
21f0: 2a 20 7b 46 31 32 30 31 34 7d 20 47 69 76 69 6e  * {F12014} Givin
2200: 67 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28  g sqlite3_close(
2210: 29 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  ) a NULL pointer
2220: 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e   is a harmless n
2230: 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49  o-op..**.** LIMI
2240: 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b  TATIONS:.**.** {
2250: 55 31 32 30 31 35 7d 20 54 68 65 20 70 61 72 61  U12015} The para
2260: 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
2270: 33 5f 63 6c 6f 73 65 28 29 5d 20 6d 75 73 74 20  3_close()] must 
2280: 62 65 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20  be an [sqlite3] 
2290: 6f 62 6a 65 63 74 0a 2a 2a 20 20 20 20 20 20 20  object.**       
22a0: 20 20 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69     pointer previ
22b0: 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66  ously obtained f
22c0: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  rom [sqlite3_ope
22d0: 6e 28 29 5d 20 6f 72 20 74 68 65 20 0a 2a 2a 20  n()] or the .** 
22e0: 20 20 20 20 20 20 20 20 20 65 71 75 69 76 61 6c           equival
22f0: 65 6e 74 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a  ent, or NULL..**
2300: 0a 2a 2a 20 7b 55 31 32 30 31 36 7d 20 54 68 65  .** {U12016} The
2310: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
2320: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20  qlite3_close()] 
2330: 6d 75 73 74 20 6e 6f 74 20 68 61 76 65 20 62 65  must not have be
2340: 65 6e 20 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a  en previously.**
2350: 20 20 20 20 20 20 20 20 20 20 63 6c 6f 73 65 64            closed
2360: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2370: 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 20 2a  _close(sqlite3 *
2380: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79  );../*.** The ty
2390: 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 63  pe for a callbac
23a0: 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54  k function..** T
23b0: 68 69 73 20 69 73 20 6c 65 67 61 63 79 20 61 6e  his is legacy an
23c0: 64 20 64 65 70 72 65 63 61 74 65 64 2e 20 20 49  d deprecated.  I
23d0: 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66 6f  t is included fo
23e0: 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20  r historical.** 
23f0: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61 6e  compatibility an
2400: 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e  d is not documen
2410: 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ted..*/.typedef 
2420: 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63 61  int (*sqlite3_ca
2430: 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e  llback)(void*,in
2440: 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a  t,char**, char**
2450: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2460: 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75 65  EF: One-Step Que
2470: 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e 74  ry Execution Int
2480: 65 72 66 61 63 65 20 7b 46 31 32 31 30 30 7d 0a  erface {F12100}.
2490: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
24a0: 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61  3_exec() interfa
24b0: 63 65 20 69 73 20 61 20 63 6f 6e 76 65 6e 69 65  ce is a convenie
24c0: 6e 74 20 77 61 79 20 6f 66 20 72 75 6e 6e 69 6e  nt way of runnin
24d0: 67 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  g.** one or more
24e0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
24f0: 77 69 74 68 6f 75 74 20 61 20 6c 6f 74 20 6f 66  without a lot of
2500: 20 43 20 63 6f 64 65 2e 20 20 54 68 65 0a 2a 2a   C code.  The.**
2510: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
2520: 61 72 65 20 70 61 73 73 65 64 20 69 6e 20 61 73  are passed in as
2530: 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
2540: 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69  meter to.** sqli
2550: 74 65 33 5f 65 78 65 63 28 29 2e 20 20 54 68 65  te3_exec().  The
2560: 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20   statements are 
2570: 65 76 61 6c 75 61 74 65 64 20 6f 6e 65 20 62 79  evaluated one by
2580: 20 6f 6e 65 0a 2a 2a 20 75 6e 74 69 6c 20 65 69   one.** until ei
2590: 74 68 65 72 20 61 6e 20 65 72 72 6f 72 20 6f 72  ther an error or
25a0: 20 61 6e 20 69 6e 74 65 72 72 75 70 74 20 69 73   an interrupt is
25b0: 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 6f 72 0a   encountered or.
25c0: 2a 2a 20 75 6e 74 69 6c 20 74 68 65 79 20 61 72  ** until they ar
25d0: 65 20 61 6c 6c 20 64 6f 6e 65 2e 20 20 54 68 65  e all done.  The
25e0: 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 69   3rd parameter i
25f0: 73 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 0a 2a 2a  s an optional.**
2600: 20 63 61 6c 6c 62 61 63 6b 20 74 68 61 74 20 69   callback that i
2610: 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 65 20 66  s invoked once f
2620: 6f 72 20 65 61 63 68 20 72 6f 77 20 6f 66 20 61  or each row of a
2630: 6e 79 20 71 75 65 72 79 20 72 65 73 75 6c 74 73  ny query results
2640: 0a 2a 2a 20 70 72 6f 64 75 63 65 64 20 62 79 20  .** produced by 
2650: 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
2660: 74 73 2e 20 20 54 68 65 20 35 74 68 20 70 61 72  ts.  The 5th par
2670: 61 6d 65 74 65 72 20 74 65 6c 6c 73 20 77 68 65  ameter tells whe
2680: 72 65 0a 2a 2a 20 74 6f 20 77 72 69 74 65 20 61  re.** to write a
2690: 6e 79 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  ny error message
26a0: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 65 72 72  s..**.** The err
26b0: 6f 72 20 6d 65 73 73 61 67 65 20 70 61 73 73 65  or message passe
26c0: 64 20 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74  d back through t
26d0: 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
26e0: 20 69 73 20 68 65 6c 64 0a 2a 2a 20 69 6e 20 6d   is held.** in m
26f0: 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
2700: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
2710: 6c 6f 63 28 29 5d 2e 20 20 54 6f 20 61 76 6f 69  loc()].  To avoi
2720: 64 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 2c  d a memory leak,
2730: 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 69 6e 67 20  .** the calling 
2740: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
2750: 6c 64 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33  ld call [sqlite3
2760: 5f 66 72 65 65 28 29 5d 20 6f 6e 20 61 6e 79 20  _free()] on any 
2770: 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65  error.** message
2780: 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f 75 67   returned throug
2790: 68 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65  h the 5th parame
27a0: 74 65 72 20 77 68 65 6e 20 69 74 20 68 61 73 20  ter when it has 
27b0: 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 0a 2a  finished using.*
27c0: 2a 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  * the error mess
27d0: 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  age..**.** If th
27e0: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
27f0: 69 6e 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  in the 2nd param
2800: 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 6f 72 20  eter is NULL or 
2810: 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 0a  an empty string.
2820: 2a 2a 20 6f 72 20 61 20 73 74 72 69 6e 67 20 63  ** or a string c
2830: 6f 6e 74 61 69 6e 69 6e 67 20 6f 6e 6c 79 20 77  ontaining only w
2840: 68 69 74 65 73 70 61 63 65 20 61 6e 64 20 63 6f  hitespace and co
2850: 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20 53 51 4c  mments, then SQL
2860: 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 61  .** statements a
2870: 72 65 20 65 76 61 6c 75 61 74 65 64 20 61 6e 64  re evaluated and
2880: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
2890: 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a   unchanged..**.*
28a0: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78  * The sqlite3_ex
28b0: 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  ec() interface i
28c0: 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 69 6e  s implemented in
28d0: 20 74 65 72 6d 73 20 6f 66 0a 2a 2a 20 5b 73 71   terms of.** [sq
28e0: 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
28f0: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74  ()], [sqlite3_st
2900: 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  ep()], and [sqli
2910: 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e  te3_finalize()].
2920: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
2930: 65 78 65 63 28 29 20 72 6f 75 74 69 6e 65 20 64  exec() routine d
2940: 6f 65 73 20 6e 6f 74 68 69 6e 67 20 74 6f 20 74  oes nothing to t
2950: 68 65 20 64 61 74 61 62 61 73 65 20 74 68 61 74  he database that
2960: 20 63 61 6e 6e 6f 74 20 62 65 20 64 6f 6e 65 0a   cannot be done.
2970: 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70  ** by [sqlite3_p
2980: 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73  repare_v2()], [s
2990: 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20  qlite3_step()], 
29a0: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  and [sqlite3_fin
29b0: 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  alize()]..**.** 
29c0: 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 20 0a  INVARIANTS:.** .
29d0: 2a 2a 20 7b 46 31 32 31 30 31 7d 20 41 20 73 75  ** {F12101} A su
29e0: 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74  ccessful invocat
29f0: 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ion of [sqlite3_
2a00: 65 78 65 63 28 44 2c 53 2c 43 2c 41 2c 45 29 5d  exec(D,S,C,A,E)]
2a10: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 68 61  .**          sha
2a20: 6c 6c 20 65 76 61 6c 75 61 74 65 20 61 6c 6c 20  ll evaluate all 
2a30: 6f 66 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63  of the UTF-8 enc
2a40: 6f 64 65 64 2c 20 73 65 6d 69 63 6f 6c 6f 6e 2d  oded, semicolon-
2a50: 73 65 70 61 72 61 74 65 64 2c 0a 2a 2a 20 20 20  separated,.**   
2a60: 20 20 20 20 20 20 20 53 51 4c 20 73 74 61 74 65         SQL state
2a70: 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72  ments in the zer
2a80: 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72  o-terminated str
2a90: 69 6e 67 20 53 20 77 69 74 68 69 6e 20 74 68 65  ing S within the
2aa0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e  .**          con
2ab0: 74 65 78 74 20 6f 66 20 74 68 65 20 44 20 5b 64  text of the D [d
2ac0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2ad0: 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31  on]..**.** {F121
2ae0: 30 32 7d 20 49 66 20 74 68 65 20 53 20 70 61 72  02} If the S par
2af0: 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
2b00: 65 33 5f 65 78 65 63 28 44 2c 53 2c 43 2c 41 2c  e3_exec(D,S,C,A,
2b10: 45 29 5d 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e  E)] is NULL then
2b20: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
2b30: 20 61 63 74 69 6f 6e 73 20 6f 66 20 74 68 65 20   actions of the 
2b40: 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20  interface shall 
2b50: 62 65 20 74 68 65 20 73 61 6d 65 20 61 73 20 69  be the same as i
2b60: 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  f the.**        
2b70: 20 20 53 20 70 61 72 61 6d 65 74 65 72 20 77 68    S parameter wh
2b80: 65 72 65 20 61 6e 20 65 6d 70 74 79 20 73 74 72  ere an empty str
2b90: 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31  ing..**.** {F121
2ba0: 30 34 7d 20 54 68 65 20 72 65 74 75 72 6e 20 76  04} The return v
2bb0: 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33  alue of [sqlite3
2bc0: 5f 65 78 65 63 28 29 5d 20 73 68 61 6c 6c 20 62  _exec()] shall b
2bd0: 65 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66  e [SQLITE_OK] if
2be0: 20 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20   all.**         
2bf0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
2c00: 72 75 6e 20 73 75 63 63 65 73 73 66 75 6c 6c 79  run successfully
2c10: 20 61 6e 64 20 74 6f 20 63 6f 6d 70 6c 65 74 69   and to completi
2c20: 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31 30  on..**.** {F1210
2c30: 35 7d 20 54 68 65 20 72 65 74 75 72 6e 20 76 61  5} The return va
2c40: 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  lue of [sqlite3_
2c50: 65 78 65 63 28 29 5d 20 73 68 61 6c 6c 20 62 65  exec()] shall be
2c60: 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20   an appropriate 
2c70: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 6f 6e  .**          non
2c80: 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64  -zero [error cod
2c90: 65 5d 20 69 66 20 61 6e 79 20 53 51 4c 20 73 74  e] if any SQL st
2ca0: 61 74 65 6d 65 6e 74 20 66 61 69 6c 73 2e 0a 2a  atement fails..*
2cb0: 2a 0a 2a 2a 20 7b 46 31 32 31 30 37 7d 20 49 66  *.** {F12107} If
2cc0: 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20   one or more of 
2cd0: 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
2ce0: 74 73 20 68 61 6e 64 65 64 20 74 6f 20 5b 73 71  ts handed to [sq
2cf0: 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 0a 2a 2a  lite3_exec()].**
2d00: 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e            return
2d10: 20 72 65 73 75 6c 74 73 20 61 6e 64 20 74 68 65   results and the
2d20: 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 69   3rd parameter i
2d30: 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e  s not NULL, then
2d40: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
2d50: 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
2d60: 6f 6e 20 73 70 65 63 69 66 69 65 64 20 62 79 20  on specified by 
2d70: 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  the 3rd paramete
2d80: 72 20 73 68 61 6c 6c 20 62 65 0a 2a 2a 20 20 20  r shall be.**   
2d90: 20 20 20 20 20 20 20 69 6e 76 6f 6b 65 64 20 6f         invoked o
2da0: 6e 63 65 20 66 6f 72 20 65 61 63 68 20 72 6f 77  nce for each row
2db0: 20 6f 66 20 72 65 73 75 6c 74 2e 0a 2a 2a 0a 2a   of result..**.*
2dc0: 2a 20 7b 46 31 32 31 31 30 7d 20 49 66 20 74 68  * {F12110} If th
2dd0: 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
2de0: 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 76 61  ns a non-zero va
2df0: 6c 75 65 20 74 68 65 6e 20 5b 73 71 6c 69 74 65  lue then [sqlite
2e00: 33 5f 65 78 65 63 28 29 5d 0a 2a 2a 20 20 20 20  3_exec()].**    
2e10: 20 20 20 20 20 20 73 68 61 6c 6c 20 61 62 6f 72        shall abor
2e20: 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  t the SQL statem
2e30: 65 6e 74 20 69 74 20 69 73 20 63 75 72 72 65 6e  ent it is curren
2e40: 74 6c 79 20 65 76 61 6c 75 61 74 69 6e 67 2c 0a  tly evaluating,.
2e50: 2a 2a 20 20 20 20 20 20 20 20 20 20 73 6b 69 70  **          skip
2e60: 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20   all subsequent 
2e70: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2c 20  SQL statements, 
2e80: 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  and return [SQLI
2e90: 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a  TE_ABORT]..**.**
2ea0: 20 7b 46 31 32 31 31 33 7d 20 54 68 65 20 5b 73   {F12113} The [s
2eb0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 72  qlite3_exec()] r
2ec0: 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20 70 61 73  outine shall pas
2ed0: 73 20 69 74 73 20 34 74 68 20 70 61 72 61 6d 65  s its 4th parame
2ee0: 74 65 72 20 74 68 72 6f 75 67 68 0a 2a 2a 20 20  ter through.**  
2ef0: 20 20 20 20 20 20 20 20 61 73 20 74 68 65 20 31          as the 1
2f00: 73 74 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  st parameter of 
2f10: 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  the callback..**
2f20: 0a 2a 2a 20 7b 46 31 32 31 31 36 7d 20 54 68 65  .** {F12116} The
2f30: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
2f40: 5d 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 74  ] routine sets t
2f50: 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
2f60: 20 6f 66 20 69 74 73 0a 2a 2a 20 20 20 20 20 20   of its.**      
2f70: 20 20 20 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20      callback to 
2f80: 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  be the number of
2f90: 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20   columns in the 
2fa0: 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 0a 2a  current row of.*
2fb0: 2a 20 20 20 20 20 20 20 20 20 20 72 65 73 75 6c  *          resul
2fc0: 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31 31 39  t..**.** {F12119
2fd0: 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65  } The [sqlite3_e
2fe0: 78 65 63 28 29 5d 20 72 6f 75 74 69 6e 65 20 73  xec()] routine s
2ff0: 65 74 73 20 74 68 65 20 33 72 64 20 70 61 72 61  ets the 3rd para
3000: 6d 65 74 65 72 20 6f 66 20 69 74 73 20 0a 2a 2a  meter of its .**
3010: 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c 62 61            callba
3020: 63 6b 20 74 6f 20 62 65 20 61 6e 20 61 72 72 61  ck to be an arra
3030: 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f  y of pointers to
3040: 20 73 74 72 69 6e 67 73 20 68 6f 6c 64 69 6e 67   strings holding
3050: 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
3060: 20 76 61 6c 75 65 73 20 66 6f 72 20 65 61 63 68   values for each
3070: 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63   column in the c
3080: 75 72 72 65 6e 74 20 72 65 73 75 6c 74 20 73 65  urrent result se
3090: 74 20 72 6f 77 20 61 73 0a 2a 2a 20 20 20 20 20  t row as.**     
30a0: 20 20 20 20 20 6f 62 74 61 69 6e 65 64 20 66 72       obtained fr
30b0: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  om [sqlite3_colu
30c0: 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a  mn_text()]..**.*
30d0: 2a 20 7b 46 31 32 31 32 32 7d 20 54 68 65 20 5b  * {F12122} The [
30e0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20  sqlite3_exec()] 
30f0: 72 6f 75 74 69 6e 65 20 73 65 74 73 20 74 68 65  routine sets the
3100: 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f   4th parameter o
3110: 66 20 69 74 73 0a 2a 2a 20 20 20 20 20 20 20 20  f its.**        
3120: 20 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 62 65    callback to be
3130: 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
3140: 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73  nters to strings
3150: 20 68 6f 6c 64 69 6e 67 20 74 68 65 0a 2a 2a 20   holding the.** 
3160: 20 20 20 20 20 20 20 20 20 6e 61 6d 65 73 20 6f           names o
3170: 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73  f result columns
3180: 20 61 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f   as obtained fro
3190: 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  m [sqlite3_colum
31a0: 6e 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  n_name()]..**.**
31b0: 20 7b 46 31 32 31 32 35 7d 20 49 66 20 74 68 65   {F12125} If the
31c0: 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
31d0: 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  o [sqlite3_exec(
31e0: 29 5d 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 0a  )] is NULL then.
31f0: 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
3200: 69 74 65 33 5f 65 78 65 63 28 29 5d 20 6e 65 76  ite3_exec()] nev
3210: 65 72 20 69 6e 76 6f 6b 65 73 20 61 20 63 61 6c  er invokes a cal
3220: 6c 62 61 63 6b 2e 20 20 41 6c 6c 20 71 75 65 72  lback.  All quer
3230: 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  y.**          re
3240: 73 75 6c 74 73 20 61 72 65 20 73 69 6c 65 6e 74  sults are silent
3250: 6c 79 20 64 69 73 63 61 72 64 65 64 2e 0a 2a 2a  ly discarded..**
3260: 0a 2a 2a 20 7b 46 31 32 31 33 31 7d 20 49 66 20  .** {F12131} If 
3270: 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  an error occurs 
3280: 77 68 69 6c 65 20 70 61 72 73 69 6e 67 20 6f 72  while parsing or
3290: 20 65 76 61 6c 75 61 74 69 6e 67 20 61 6e 79 20   evaluating any 
32a0: 6f 66 20 74 68 65 20 53 51 4c 0a 2a 2a 20 20 20  of the SQL.**   
32b0: 20 20 20 20 20 20 20 68 61 6e 64 65 64 20 69 6e         handed in
32c0: 20 74 68 65 20 53 20 70 61 72 61 6d 65 74 65 72   the S parameter
32d0: 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 65 78 65   of [sqlite3_exe
32e0: 63 28 44 2c 53 2c 43 2c 41 2c 45 29 5d 20 61 6e  c(D,S,C,A,E)] an
32f0: 64 20 69 66 0a 2a 2a 20 20 20 20 20 20 20 20 20  d if.**         
3300: 20 74 68 65 20 45 20 70 61 72 61 6d 65 74 65 72   the E parameter
3310: 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68   is not NULL, th
3320: 65 6e 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  en [sqlite3_exec
3330: 28 29 5d 20 73 68 61 6c 6c 20 73 74 6f 72 65 0a  ()] shall store.
3340: 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 2a  **          in *
3350: 45 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65  E an appropriate
3360: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 77   error message w
3370: 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f  ritten into memo
3380: 72 79 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 20  ry obtained.**  
3390: 20 20 20 20 20 20 20 20 66 72 6f 6d 20 5b 73 71          from [sq
33a0: 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e  lite3_malloc()].
33b0: 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31 33 34 7d 20  .**.** {F12134} 
33c0: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  The [sqlite3_exe
33d0: 63 28 44 2c 53 2c 43 2c 41 2c 45 29 5d 20 72 6f  c(D,S,C,A,E)] ro
33e0: 75 74 69 6e 65 20 73 68 61 6c 6c 20 73 65 74 20  utine shall set 
33f0: 74 68 65 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20  the value of.** 
3400: 20 20 20 20 20 20 20 20 20 2a 45 20 74 6f 20 4e           *E to N
3410: 55 4c 4c 20 69 66 20 45 20 69 73 20 6e 6f 74 20  ULL if E is not 
3420: 4e 55 4c 4c 20 61 6e 64 20 74 68 65 72 65 20 61  NULL and there a
3430: 72 65 20 6e 6f 20 65 72 72 6f 72 73 2e 0a 2a 2a  re no errors..**
3440: 0a 2a 2a 20 7b 46 31 32 31 33 37 7d 20 54 68 65  .** {F12137} The
3450: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 44   [sqlite3_exec(D
3460: 2c 53 2c 43 2c 41 2c 45 29 5d 20 66 75 6e 63 74  ,S,C,A,E)] funct
3470: 69 6f 6e 20 73 68 61 6c 6c 20 73 65 74 20 74 68  ion shall set th
3480: 65 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20  e error code.** 
3490: 20 20 20 20 20 20 20 20 20 61 6e 64 20 6d 65 73           and mes
34a0: 73 61 67 65 20 61 63 63 65 73 73 69 62 6c 65 20  sage accessible 
34b0: 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  via [sqlite3_err
34c0: 63 6f 64 65 28 29 5d 2c 0a 2a 2a 20 20 20 20 20  code()],.**     
34d0: 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 65 72       [sqlite3_er
34e0: 72 6d 73 67 28 29 5d 2c 20 61 6e 64 20 5b 73 71  rmsg()], and [sq
34f0: 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29  lite3_errmsg16()
3500: 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31 33 38  ]..**.** {F12138
3510: 7d 20 49 66 20 74 68 65 20 53 20 70 61 72 61 6d  } If the S param
3520: 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
3530: 5f 65 78 65 63 28 44 2c 53 2c 43 2c 41 2c 45 29  _exec(D,S,C,A,E)
3540: 5d 20 69 73 20 61 20 6e 75 6c 6c 20 6f 72 20 65  ] is a null or e
3550: 6d 70 74 79 0a 2a 2a 20 20 20 20 20 20 20 20 20  mpty.**         
3560: 20 73 74 72 69 6e 67 20 6f 72 20 63 6f 6e 74 61   string or conta
3570: 69 6e 73 20 6e 6f 74 68 69 6e 67 20 6f 74 68 65  ins nothing othe
3580: 72 20 74 68 61 6e 20 77 68 69 74 65 73 70 61 63  r than whitespac
3590: 65 2c 20 63 6f 6d 6d 65 6e 74 73 2c 20 61 6e 64  e, comments, and
35a0: 2f 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  /or.**          
35b0: 73 65 6d 69 63 6f 6c 6f 6e 73 2c 20 74 68 65 6e  semicolons, then
35c0: 20 72 65 73 75 6c 74 73 20 6f 66 20 5b 73 71 6c   results of [sql
35d0: 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 2c  ite3_errcode()],
35e0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
35f0: 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2c  lite3_errmsg()],
3600: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 72   and [sqlite3_er
3610: 72 6d 73 67 31 36 28 29 5d 0a 2a 2a 20 20 20 20  rmsg16()].**    
3620: 20 20 20 20 20 20 73 68 61 6c 6c 20 72 65 73 65        shall rese
3630: 74 20 74 6f 20 69 6e 64 69 63 61 74 65 20 6e 6f  t to indicate no
3640: 20 65 72 72 6f 72 73 2e 0a 2a 2a 0a 2a 2a 20 4c   errors..**.** L
3650: 49 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a  IMITATIONS:.**.*
3660: 2a 20 7b 55 31 32 31 34 31 7d 20 54 68 65 20 66  * {U12141} The f
3670: 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
3680: 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  o [sqlite3_exec(
3690: 29 5d 20 6d 75 73 74 20 62 65 20 61 6e 20 76 61  )] must be an va
36a0: 6c 69 64 20 61 6e 64 20 6f 70 65 6e 0a 2a 2a 20  lid and open.** 
36b0: 20 20 20 20 20 20 20 20 20 5b 64 61 74 61 62 61           [databa
36c0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a  se connection]..
36d0: 2a 2a 0a 2a 2a 20 7b 55 31 32 31 34 32 7d 20 54  **.** {U12142} T
36e0: 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
36f0: 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  ection must not 
3700: 62 65 20 63 6c 6f 73 65 64 20 77 68 69 6c 65 0a  be closed while.
3710: 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
3720: 69 74 65 33 5f 65 78 65 63 28 29 5d 20 69 73 20  ite3_exec()] is 
3730: 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 0a 2a 2a 20  running..** .** 
3740: 7b 55 31 32 31 34 33 7d 20 54 68 65 20 63 61 6c  {U12143} The cal
3750: 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 73 68  ling function sh
3760: 6f 75 6c 64 20 75 73 65 20 5b 73 71 6c 69 74 65  ould use [sqlite
3770: 33 5f 66 72 65 65 28 29 5d 20 74 6f 20 66 72 65  3_free()] to fre
3780: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  e.**          th
3790: 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 2a 65  e memory that *e
37a0: 72 72 6d 73 67 20 69 73 20 6c 65 66 74 20 70 6f  rrmsg is left po
37b0: 69 6e 74 69 6e 67 20 61 74 20 6f 6e 63 65 20 74  inting at once t
37c0: 68 65 20 65 72 72 6f 72 0a 2a 2a 20 20 20 20 20  he error.**     
37d0: 20 20 20 20 20 6d 65 73 73 61 67 65 20 69 73 20       message is 
37e0: 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64  no longer needed
37f0: 2e 0a 2a 2a 0a 2a 2a 20 7b 55 31 32 31 34 35 7d  ..**.** {U12145}
3800: 20 54 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   The SQL stateme
3810: 6e 74 20 74 65 78 74 20 69 6e 20 74 68 65 20 32  nt text in the 2
3820: 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
3830: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
3840: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 75 73  .**          mus
3850: 74 20 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67  t remain unchang
3860: 65 64 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65  ed while [sqlite
3870: 33 5f 65 78 65 63 28 29 5d 20 69 73 20 72 75 6e  3_exec()] is run
3880: 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ning..*/.int sql
3890: 69 74 65 33 5f 65 78 65 63 28 0a 20 20 73 71 6c  ite3_exec(.  sql
38a0: 69 74 65 33 2a 2c 20 20 20 20 20 20 20 20 20 20  ite3*,          
38b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
38c0: 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70          /* An op
38d0: 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20  en database */. 
38e0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c   const char *sql
38f0: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
3900: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53              /* S
3910: 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74  QL to be evaluat
3920: 65 64 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 63 61  ed */.  int (*ca
3930: 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e  llback)(void*,in
3940: 74 2c 63 68 61 72 2a 2a 2c 63 68 61 72 2a 2a 29  t,char**,char**)
3950: 2c 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 66  ,  /* Callback f
3960: 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69  unction */.  voi
3970: 64 20 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20  d *,            
3980: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3990: 20 20 20 20 20 20 20 20 2f 2a 20 31 73 74 20 61          /* 1st a
39a0: 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 62  rgument to callb
39b0: 61 63 6b 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a  ack */.  char **
39c0: 65 72 72 6d 73 67 20 20 20 20 20 20 20 20 20 20  errmsg          
39d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
39e0: 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67      /* Error msg
39f0: 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
3a00: 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
3a10: 52 45 46 3a 20 52 65 73 75 6c 74 20 43 6f 64 65  REF: Result Code
3a20: 73 20 7b 46 31 30 32 31 30 7d 0a 2a 2a 20 4b 45  s {F10210}.** KE
3a30: 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 4f  YWORDS: SQLITE_O
3a40: 4b 20 7b 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b  K {error code} {
3a50: 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 0a  error codes}.**.
3a60: 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74 65 20 66  ** Many SQLite f
3a70: 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20  unctions return 
3a80: 61 6e 20 69 6e 74 65 67 65 72 20 72 65 73 75 6c  an integer resul
3a90: 74 20 63 6f 64 65 20 66 72 6f 6d 20 74 68 65 20  t code from the 
3aa0: 73 65 74 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72  set shown.** her
3ab0: 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e  e in order to in
3ac0: 64 69 63 61 74 65 73 20 73 75 63 63 65 73 73 20  dicates success 
3ad0: 6f 72 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a  or failure..**.*
3ae0: 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c  * See also: [SQL
3af0: 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c  ITE_IOERR_READ |
3b00: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
3b10: 20 63 6f 64 65 73 5d 0a 2a 2f 0a 23 64 65 66 69   codes].*/.#defi
3b20: 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20  ne SQLITE_OK    
3b30: 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 53 75         0   /* Su
3b40: 63 63 65 73 73 66 75 6c 20 72 65 73 75 6c 74 20  ccessful result 
3b50: 2a 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d  */./* beginning-
3b60: 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a  of-error-codes *
3b70: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3b80: 5f 45 52 52 4f 52 20 20 20 20 20 20 20 20 31 20  _ERROR        1 
3b90: 20 20 2f 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f    /* SQL error o
3ba0: 72 20 6d 69 73 73 69 6e 67 20 64 61 74 61 62 61  r missing databa
3bb0: 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  se */.#define SQ
3bc0: 4c 49 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20  LITE_INTERNAL   
3bd0: 20 20 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61    2   /* Interna
3be0: 6c 20 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e  l logic error in
3bf0: 20 53 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69   SQLite */.#defi
3c00: 6e 65 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20  ne SQLITE_PERM  
3c10: 20 20 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63         3   /* Ac
3c20: 63 65 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20  cess permission 
3c30: 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e  denied */.#defin
3c40: 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20  e SQLITE_ABORT  
3c50: 20 20 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c        4   /* Cal
3c60: 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65  lback routine re
3c70: 71 75 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74  quested an abort
3c80: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
3c90: 54 45 5f 42 55 53 59 20 20 20 20 20 20 20 20 20  TE_BUSY         
3ca0: 35 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62  5   /* The datab
3cb0: 61 73 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b  ase file is lock
3cc0: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
3cd0: 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20  LITE_LOCKED     
3ce0: 20 20 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65    6   /* A table
3cf0: 20 69 6e 20 74 68 65 20 64 61 74 61 62 61 73 65   in the database
3d00: 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64   is locked */.#d
3d10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d  efine SQLITE_NOM
3d20: 45 4d 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a  EM        7   /*
3d30: 20 41 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c   A malloc() fail
3d40: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
3d50: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20  LITE_READONLY   
3d60: 20 20 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74    8   /* Attempt
3d70: 20 74 6f 20 77 72 69 74 65 20 61 20 72 65 61 64   to write a read
3d80: 6f 6e 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f  only database */
3d90: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3da0: 49 4e 54 45 52 52 55 50 54 20 20 20 20 39 20 20  INTERRUPT    9  
3db0: 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65   /* Operation te
3dc0: 72 6d 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69  rminated by sqli
3dd0: 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2a  te3_interrupt()*
3de0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3df0: 5f 49 4f 45 52 52 20 20 20 20 20 20 20 31 30 20  _IOERR       10 
3e00: 20 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f    /* Some kind o
3e10: 66 20 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72  f disk I/O error
3e20: 20 6f 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65   occurred */.#de
3e30: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52  fine SQLITE_CORR
3e40: 55 50 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20  UPT     11   /* 
3e50: 54 68 65 20 64 61 74 61 62 61 73 65 20 64 69 73  The database dis
3e60: 6b 20 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f  k image is malfo
3e70: 72 6d 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rmed */.#define 
3e80: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20  SQLITE_NOTFOUND 
3e90: 20 20 20 31 32 20 20 20 2f 2a 20 4e 4f 54 20 55     12   /* NOT U
3ea0: 53 45 44 2e 20 54 61 62 6c 65 20 6f 72 20 72 65  SED. Table or re
3eb0: 63 6f 72 64 20 6e 6f 74 20 66 6f 75 6e 64 20 2a  cord not found *
3ec0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3ed0: 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 31 33 20  _FULL        13 
3ee0: 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66    /* Insertion f
3ef0: 61 69 6c 65 64 20 62 65 63 61 75 73 65 20 64 61  ailed because da
3f00: 74 61 62 61 73 65 20 69 73 20 66 75 6c 6c 20 2a  tabase is full *
3f10: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3f20: 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 34 20  _CANTOPEN    14 
3f30: 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f    /* Unable to o
3f40: 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  pen the database
3f50: 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65   file */.#define
3f60: 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c   SQLITE_PROTOCOL
3f70: 20 20 20 20 31 35 20 20 20 2f 2a 20 4e 4f 54 20      15   /* NOT 
3f80: 55 53 45 44 2e 20 44 61 74 61 62 61 73 65 20 6c  USED. Database l
3f90: 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65 72 72  ock protocol err
3fa0: 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  or */.#define SQ
3fb0: 4c 49 54 45 5f 45 4d 50 54 59 20 20 20 20 20 20  LITE_EMPTY      
3fc0: 20 31 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73   16   /* Databas
3fd0: 65 20 69 73 20 65 6d 70 74 79 20 2a 2f 0a 23 64  e is empty */.#d
3fe0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 43 48  efine SQLITE_SCH
3ff0: 45 4d 41 20 20 20 20 20 20 31 37 20 20 20 2f 2a  EMA      17   /*
4000: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 73 63   The database sc
4010: 68 65 6d 61 20 63 68 61 6e 67 65 64 20 2a 2f 0a  hema changed */.
4020: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
4030: 4f 4f 42 49 47 20 20 20 20 20 20 31 38 20 20 20  OOBIG      18   
4040: 2f 2a 20 53 74 72 69 6e 67 20 6f 72 20 42 4c 4f  /* String or BLO
4050: 42 20 65 78 63 65 65 64 73 20 73 69 7a 65 20 6c  B exceeds size l
4060: 69 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20  imit */.#define 
4070: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
4080: 54 20 20 31 39 20 20 20 2f 2a 20 41 62 6f 72 74  T  19   /* Abort
4090: 20 64 75 65 20 74 6f 20 63 6f 6e 73 74 72 61 69   due to constrai
40a0: 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a  nt violation */.
40b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d  #define SQLITE_M
40c0: 49 53 4d 41 54 43 48 20 20 20 20 32 30 20 20 20  ISMATCH    20   
40d0: 2f 2a 20 44 61 74 61 20 74 79 70 65 20 6d 69 73  /* Data type mis
40e0: 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66 69 6e 65  match */.#define
40f0: 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 20   SQLITE_MISUSE  
4100: 20 20 20 20 32 31 20 20 20 2f 2a 20 4c 69 62 72      21   /* Libr
4110: 61 72 79 20 75 73 65 64 20 69 6e 63 6f 72 72 65  ary used incorre
4120: 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ctly */.#define 
4130: 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20 20 20  SQLITE_NOLFS    
4140: 20 20 20 32 32 20 20 20 2f 2a 20 55 73 65 73 20     22   /* Uses 
4150: 4f 53 20 66 65 61 74 75 72 65 73 20 6e 6f 74 20  OS features not 
4160: 73 75 70 70 6f 72 74 65 64 20 6f 6e 20 68 6f 73  supported on hos
4170: 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
4180: 49 54 45 5f 41 55 54 48 20 20 20 20 20 20 20 20  ITE_AUTH        
4190: 32 33 20 20 20 2f 2a 20 41 75 74 68 6f 72 69 7a  23   /* Authoriz
41a0: 61 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a  ation denied */.
41b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
41c0: 4f 52 4d 41 54 20 20 20 20 20 20 32 34 20 20 20  ORMAT      24   
41d0: 2f 2a 20 41 75 78 69 6c 69 61 72 79 20 64 61 74  /* Auxiliary dat
41e0: 61 62 61 73 65 20 66 6f 72 6d 61 74 20 65 72 72  abase format err
41f0: 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  or */.#define SQ
4200: 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20 20 20  LITE_RANGE      
4210: 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70 61 72   25   /* 2nd par
4220: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
4230: 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20 72 61  3_bind out of ra
4240: 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nge */.#define S
4250: 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20 20 20  QLITE_NOTADB    
4260: 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65 20 6f    26   /* File o
4270: 70 65 6e 65 64 20 74 68 61 74 20 69 73 20 6e 6f  pened that is no
4280: 74 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c  t a database fil
4290: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
42a0: 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20 20 20  ITE_ROW         
42b0: 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f  100  /* sqlite3_
42c0: 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f 74 68  step() has anoth
42d0: 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a 2f 0a  er row ready */.
42e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
42f0: 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31 20 20  ONE        101  
4300: 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  /* sqlite3_step(
4310: 29 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 65  ) has finished e
4320: 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65  xecuting */./* e
4330: 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65  nd-of-error-code
4340: 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  s */../*.** CAPI
4350: 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64 20 52  3REF: Extended R
4360: 65 73 75 6c 74 20 43 6f 64 65 73 20 7b 46 31 30  esult Codes {F10
4370: 32 32 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  220}.** KEYWORDS
4380: 3a 20 7b 65 78 74 65 6e 64 65 64 20 65 72 72 6f  : {extended erro
4390: 72 20 63 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65  r code} {extende
43a0: 64 20 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a  d error codes}.*
43b0: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74  * KEYWORDS: {ext
43c0: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
43d0: 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74 73  es}.**.** In its
43e0: 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75   default configu
43f0: 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 41  ration, SQLite A
4400: 50 49 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  PI routines retu
4410: 72 6e 20 6f 6e 65 20 6f 66 20 32 36 20 69 6e 74  rn one of 26 int
4420: 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  eger.** [SQLITE_
4430: 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65  OK | result code
4440: 73 5d 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78  s].  However, ex
4450: 70 65 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f  perience has sho
4460: 77 6e 20 74 68 61 74 0a 2a 2a 20 6d 61 6e 79 20  wn that.** many 
4470: 6f 66 20 74 68 65 73 65 20 72 65 73 75 6c 74 20  of these result 
4480: 63 6f 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f  codes are too co
4490: 75 72 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54  urse-grained.  T
44a0: 68 65 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69  hey do not provi
44b0: 64 65 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e  de as.** much in
44c0: 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20  formation about 
44d0: 70 72 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f 67  problems as prog
44e0: 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c 69  rammers might li
44f0: 6b 65 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72  ke.  In an effor
4500: 74 20 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20  t to.** address 
4510: 74 68 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73  this, newer vers
4520: 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28  ions of SQLite (
4530: 76 65 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e  version 3.3.8 an
4540: 64 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 65  d later) include
4550: 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 20  .** support for 
4560: 61 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c  additional resul
4570: 74 20 63 6f 64 65 73 20 74 68 61 74 20 70 72 6f  t codes that pro
4580: 76 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c  vide more detail
4590: 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a  ed information.*
45a0: 2a 20 61 62 6f 75 74 20 65 72 72 6f 72 73 2e 20  * about errors. 
45b0: 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73  The extended res
45c0: 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 65 6e  ult codes are en
45d0: 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65  abled or disable
45e0: 64 0a 2a 2a 20 66 6f 72 20 65 61 63 68 20 64 61  d.** for each da
45f0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
4600: 6e 20 75 73 69 6e 67 20 74 68 65 20 5b 73 71 6c  n using the [sql
4610: 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65  ite3_extended_re
4620: 73 75 6c 74 5f 63 6f 64 65 73 28 29 5d 0a 2a 2a  sult_codes()].**
4630: 20 41 50 49 2e 0a 2a 2a 20 0a 2a 2a 20 53 6f 6d   API..** .** Som
4640: 65 20 6f 66 20 74 68 65 20 61 76 61 69 6c 61 62  e of the availab
4650: 6c 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  le extended resu
4660: 6c 74 20 63 6f 64 65 73 20 61 72 65 20 6c 69 73  lt codes are lis
4670: 74 65 64 20 68 65 72 65 2e 0a 2a 2a 20 4f 6e 65  ted here..** One
4680: 20 6d 61 79 20 65 78 70 65 63 74 20 74 68 65 20   may expect the 
4690: 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 65 6e 64  number of extend
46a0: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ed result codes 
46b0: 77 69 6c 6c 20 62 65 20 65 78 70 61 6e 64 0a 2a  will be expand.*
46c0: 2a 20 6f 76 65 72 20 74 69 6d 65 2e 20 20 53 6f  * over time.  So
46d0: 66 74 77 61 72 65 20 74 68 61 74 20 75 73 65 73  ftware that uses
46e0: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
46f0: 20 63 6f 64 65 73 20 73 68 6f 75 6c 64 20 65 78   codes should ex
4700: 70 65 63 74 0a 2a 2a 20 74 6f 20 73 65 65 20 6e  pect.** to see n
4710: 65 77 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ew result codes 
4720: 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
4730: 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  es of SQLite..**
4740: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 4f  .** The SQLITE_O
4750: 4b 20 72 65 73 75 6c 74 20 63 6f 64 65 20 77 69  K result code wi
4760: 6c 6c 20 6e 65 76 65 72 20 62 65 20 65 78 74 65  ll never be exte
4770: 6e 64 65 64 2e 20 20 49 74 20 77 69 6c 6c 20 61  nded.  It will a
4780: 6c 77 61 79 73 0a 2a 2a 20 62 65 20 65 78 61 63  lways.** be exac
4790: 74 6c 79 20 7a 65 72 6f 2e 0a 2a 2a 20 0a 2a 2a  tly zero..** .**
47a0: 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
47b0: 2a 2a 20 7b 46 31 30 32 32 33 7d 20 54 68 65 20  ** {F10223} The 
47c0: 73 79 6d 62 6f 6c 69 63 20 6e 61 6d 65 20 66 6f  symbolic name fo
47d0: 72 20 61 6e 20 65 78 74 65 6e 64 65 64 20 72 65  r an extended re
47e0: 73 75 6c 74 20 63 6f 64 65 20 61 6c 77 61 79 73  sult code always
47f0: 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 20 20 20   contains.**    
4800: 20 20 20 20 20 20 61 20 72 65 6c 61 74 65 64 20        a related 
4810: 70 72 69 6d 61 72 79 20 72 65 73 75 6c 74 20 63  primary result c
4820: 6f 64 65 20 61 73 20 61 20 70 72 65 66 69 78 2e  ode as a prefix.
4830: 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 32 32 34 7d 20  .**.** {F10224} 
4840: 50 72 69 6d 61 72 79 20 72 65 73 75 6c 74 20 63  Primary result c
4850: 6f 64 65 20 6e 61 6d 65 73 20 63 6f 6e 74 61 69  ode names contai
4860: 6e 20 61 20 73 69 6e 67 6c 65 20 22 5f 22 20 63  n a single "_" c
4870: 68 61 72 61 63 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  haracter..**.** 
4880: 7b 46 31 30 32 32 35 7d 20 45 78 74 65 6e 64 65  {F10225} Extende
4890: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 20 6e 61  d result code na
48a0: 6d 65 73 20 63 6f 6e 74 61 69 6e 20 74 77 6f 20  mes contain two 
48b0: 6f 72 20 6d 6f 72 65 20 22 5f 22 20 63 68 61 72  or more "_" char
48c0: 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46  acters..**.** {F
48d0: 31 30 32 32 36 7d 20 54 68 65 20 6e 75 6d 65 72  10226} The numer
48e0: 69 63 20 76 61 6c 75 65 20 6f 66 20 61 6e 20 65  ic value of an e
48f0: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
4900: 6f 64 65 20 63 6f 6e 74 61 69 6e 73 20 74 68 65  ode contains the
4910: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 75 6d  .**          num
4920: 65 72 69 63 20 76 61 6c 75 65 20 6f 66 20 69 74  eric value of it
4930: 73 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  s corresponding 
4940: 70 72 69 6d 61 72 79 20 72 65 73 75 6c 74 20 63  primary result c
4950: 6f 64 65 20 69 6e 0a 2a 2a 20 20 20 20 20 20 20  ode in.**       
4960: 20 20 20 69 74 73 20 6c 65 61 73 74 20 73 69 67     its least sig
4970: 6e 69 66 69 63 61 6e 74 20 38 20 62 69 74 73 2e  nificant 8 bits.
4980: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
4990: 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20 20  TE_IOERR_READ   
49a0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
49b0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c 38  TE_IOERR | (1<<8
49c0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
49d0: 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45  E_IOERR_SHORT_RE
49e0: 41 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  AD        (SQLIT
49f0: 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38 29  E_IOERR | (2<<8)
4a00: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
4a10: 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20 20  _IOERR_WRITE    
4a20: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
4a30: 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29 29  _IOERR | (3<<8))
4a40: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4a50: 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20 20  IOERR_FSYNC     
4a60: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
4a70: 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a  IOERR | (4<<8)).
4a80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4a90: 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20 20  OERR_DIR_FSYNC  
4aa0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
4ab0: 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a 23  OERR | (5<<8)).#
4ac0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
4ad0: 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20 20  ERR_TRUNCATE    
4ae0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
4af0: 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64  ERR | (6<<8)).#d
4b00: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4b10: 52 52 5f 46 53 54 41 54 20 20 20 20 20 20 20 20  RR_FSTAT        
4b20: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4b30: 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65  RR | (7<<8)).#de
4b40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4b50: 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20  R_UNLOCK        
4b60: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4b70: 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 66  R | (8<<8)).#def
4b80: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4b90: 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  _RDLOCK         
4ba0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
4bb0: 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69   | (9<<8)).#defi
4bc0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
4bd0: 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20  DELETE          
4be0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
4bf0: 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69  | (10<<8)).#defi
4c00: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
4c10: 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20 20  BLOCKED         
4c20: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
4c30: 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66 69  | (11<<8)).#defi
4c40: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
4c50: 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20 20  NOMEM           
4c60: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
4c70: 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66 69  | (12<<8)).#defi
4c80: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
4c90: 41 43 43 45 53 53 20 20 20 20 20 20 20 20 20 20  ACCESS          
4ca0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
4cb0: 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66 69  | (13<<8)).#defi
4cc0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
4cd0: 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f 43  CHECKRESERVEDLOC
4ce0: 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20  K (SQLITE_IOERR 
4cf0: 7c 20 28 31 34 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a  | (14<<8))../*.*
4d00: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67  * CAPI3REF: Flag
4d10: 73 20 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20  s For File Open 
4d20: 4f 70 65 72 61 74 69 6f 6e 73 20 7b 46 31 30 32  Operations {F102
4d30: 33 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  30}.**.** These 
4d40: 62 69 74 20 76 61 6c 75 65 73 20 61 72 65 20 69  bit values are i
4d50: 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20  ntended for use 
4d60: 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20 70 61  in the.** 3rd pa
4d70: 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b  rameter to the [
4d80: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
4d90: 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64  )] interface and
4da0: 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74 68 20 70  .** in the 4th p
4db0: 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
4dc0: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6f 66 20  xOpen method of 
4dd0: 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
4de0: 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a  vfs] object..*/.
4df0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
4e00: 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20  PEN_READONLY    
4e10: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31 0a       0x00000001.
4e20: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
4e30: 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 20 20  PEN_READWRITE   
4e40: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32 0a       0x00000002.
4e50: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
4e60: 50 45 4e 5f 43 52 45 41 54 45 20 20 20 20 20 20  PEN_CREATE      
4e70: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34 0a       0x00000004.
4e80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
4e90: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
4ea0: 45 20 20 20 20 30 78 30 30 30 30 30 30 30 38 0a  E    0x00000008.
4eb0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
4ec0: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 20 20  PEN_EXCLUSIVE   
4ed0: 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0a       0x00000010.
4ee0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
4ef0: 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20 20  PEN_MAIN_DB     
4f00: 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30 0a       0x00000100.
4f10: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
4f20: 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20 20  PEN_TEMP_DB     
4f30: 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30 0a       0x00000200.
4f40: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
4f50: 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42  PEN_TRANSIENT_DB
4f60: 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30 0a       0x00000400.
4f70: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
4f80: 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c  PEN_MAIN_JOURNAL
4f90: 20 20 20 20 20 30 78 30 30 30 30 30 38 30 30 0a       0x00000800.
4fa0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
4fb0: 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c  PEN_TEMP_JOURNAL
4fc0: 20 20 20 20 20 30 78 30 30 30 30 31 30 30 30 0a       0x00001000.
4fd0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
4fe0: 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 20  PEN_SUBJOURNAL  
4ff0: 20 20 20 20 20 30 78 30 30 30 30 32 30 30 30 0a       0x00002000.
5000: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5010: 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e  PEN_MASTER_JOURN
5020: 41 4c 20 20 20 30 78 30 30 30 30 34 30 30 30 0a  AL   0x00004000.
5030: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
5040: 20 44 65 76 69 63 65 20 43 68 61 72 61 63 74 65   Device Characte
5050: 72 69 73 74 69 63 73 20 7b 46 31 30 32 34 30 7d  ristics {F10240}
5060: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69  .**.** The xDevi
5070: 63 65 43 61 70 61 62 69 6c 69 74 69 65 73 20 6d  ceCapabilities m
5080: 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71  ethod of the [sq
5090: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
50a0: 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75  ].** object retu
50b0: 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77  rns an integer w
50c0: 68 69 63 68 20 69 73 20 61 20 76 65 63 74 6f 72  hich is a vector
50d0: 20 6f 66 20 74 68 65 20 74 68 65 73 65 0a 2a 2a   of the these.**
50e0: 20 62 69 74 20 76 61 6c 75 65 73 20 65 78 70 72   bit values expr
50f0: 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61  essing I/O chara
5100: 63 74 65 72 69 73 74 69 63 73 20 6f 66 20 74 68  cteristics of th
5110: 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a  e mass storage.*
5120: 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 68 6f  * device that ho
5130: 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74 68 61  lds the file tha
5140: 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69  t the [sqlite3_i
5150: 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65  o_methods].** re
5160: 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54  fers to..**.** T
5170: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
5180: 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20  ATOMIC property 
5190: 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77  means that all w
51a0: 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20  rites of.** any 
51b0: 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e  size are atomic.
51c0: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
51d0: 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c  AP_ATOMICnnn val
51e0: 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74  ues.** mean that
51f0: 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b   writes of block
5200: 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62  s that are nnn b
5210: 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64  ytes in size and
5220: 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20  .** are aligned 
5230: 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68  to an address wh
5240: 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ich is an intege
5250: 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a  r multiple of.**
5260: 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e   nnn are atomic.
5270: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
5280: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76  AP_SAFE_APPEND v
5290: 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68  alue means.** th
52a0: 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20  at when data is 
52b0: 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69  appended to a fi
52c0: 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20  le, the data is 
52d0: 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73  appended.** firs
52e0: 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20  t then the size 
52f0: 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65  of the file is e
5300: 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74  xtended, never t
5310: 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20  he other.** way 
5320: 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c  around.  The SQL
5330: 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e  ITE_IOCAP_SEQUEN
5340: 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65  TIAL property me
5350: 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f  ans that.** info
5360: 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74  rmation is writt
5370: 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68  en to disk in th
5380: 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20  e same order as 
5390: 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69  calls.** to xWri
53a0: 74 65 28 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  te()..*/.#define
53b0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
53c0: 4f 4d 49 43 20 20 20 20 20 20 20 20 20 20 30 78  OMIC          0x
53d0: 30 30 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65  00000001.#define
53e0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
53f0: 4f 4d 49 43 35 31 32 20 20 20 20 20 20 20 30 78  OMIC512       0x
5400: 30 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65  00000002.#define
5410: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
5420: 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20 30 78  OMIC1K        0x
5430: 30 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65  00000004.#define
5440: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
5450: 4f 4d 49 43 32 4b 20 20 20 20 20 20 20 20 30 78  OMIC2K        0x
5460: 30 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65  00000008.#define
5470: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
5480: 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 20 30 78  OMIC4K        0x
5490: 30 30 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65  00000010.#define
54a0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
54b0: 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20 30 78  OMIC8K        0x
54c0: 30 30 30 30 30 30 32 30 0a 23 64 65 66 69 6e 65  00000020.#define
54d0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
54e0: 4f 4d 49 43 31 36 4b 20 20 20 20 20 20 20 30 78  OMIC16K       0x
54f0: 30 30 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65  00000040.#define
5500: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
5510: 4f 4d 49 43 33 32 4b 20 20 20 20 20 20 20 30 78  OMIC32K       0x
5520: 30 30 30 30 30 30 38 30 0a 23 64 65 66 69 6e 65  00000080.#define
5530: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
5540: 4f 4d 49 43 36 34 4b 20 20 20 20 20 20 20 30 78  OMIC64K       0x
5550: 30 30 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65  00000100.#define
5560: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41   SQLITE_IOCAP_SA
5570: 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20 30 78  FE_APPEND     0x
5580: 30 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65  00000200.#define
5590: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45   SQLITE_IOCAP_SE
55a0: 51 55 45 4e 54 49 41 4c 20 20 20 20 20 20 30 78  QUENTIAL      0x
55b0: 30 30 30 30 30 34 30 30 0a 0a 2f 2a 0a 2a 2a 20  00000400../*.** 
55c0: 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c  CAPI3REF: File L
55d0: 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 20 7b 46  ocking Levels {F
55e0: 31 30 32 35 30 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c  10250}.**.** SQL
55f0: 69 74 65 20 75 73 65 73 20 6f 6e 65 20 6f 66 20  ite uses one of 
5600: 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61  these integer va
5610: 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f  lues as the seco
5620: 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74  nd.** argument t
5630: 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b 65 73  o calls it makes
5640: 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28 29 20   to the xLock() 
5650: 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 6d 65  and xUnlock() me
5660: 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b  thods.** of an [
5670: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
5680: 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23  ds] object..*/.#
5690: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
56a0: 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20 20 20  CK_NONE         
56b0: 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   0.#define SQLIT
56c0: 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20 20 20  E_LOCK_SHARED   
56d0: 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
56e0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52  QLITE_LOCK_RESER
56f0: 56 45 44 20 20 20 20 20 20 32 0a 23 64 65 66 69  VED      2.#defi
5700: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50  ne SQLITE_LOCK_P
5710: 45 4e 44 49 4e 47 20 20 20 20 20 20 20 33 0a 23  ENDING       3.#
5720: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
5730: 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20  CK_EXCLUSIVE    
5740: 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52   4../*.** CAPI3R
5750: 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a 61 74  EF: Synchronizat
5760: 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 73 20 7b  ion Type Flags {
5770: 46 31 30 32 36 30 7d 0a 2a 2a 0a 2a 2a 20 57 68  F10260}.**.** Wh
5780: 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65  en SQLite invoke
5790: 73 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65  s the xSync() me
57a0: 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73  thod of an.** [s
57b0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
57c0: 73 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65  s] object it use
57d0: 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20  s a combination 
57e0: 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65  of.** these inte
57f0: 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68  ger values as th
5800: 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
5810: 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  t..**.** When th
5820: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41  e SQLITE_SYNC_DA
5830: 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75  TAONLY flag is u
5840: 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68  sed, it means th
5850: 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f  at the.** sync o
5860: 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65  peration only ne
5870: 65 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74  eds to flush dat
5880: 61 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67  a to mass storag
5890: 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66  e.  Inode.** inf
58a0: 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f  ormation need no
58b0: 74 20 62 65 20 66 6c 75 73 68 65 64 2e 20 54 68  t be flushed. Th
58c0: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f  e SQLITE_SYNC_NO
58d0: 52 4d 41 4c 20 66 6c 61 67 20 6d 65 61 6e 73 20  RMAL flag means 
58e0: 0a 2a 2a 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61  .** to use norma
58f0: 6c 20 66 73 79 6e 63 28 29 20 73 65 6d 61 6e 74  l fsync() semant
5900: 69 63 73 2e 20 54 68 65 20 53 51 4c 49 54 45 5f  ics. The SQLITE_
5910: 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 20 6d  SYNC_FULL flag m
5920: 65 61 6e 73 20 0a 2a 2a 20 74 6f 20 75 73 65 20  eans .** to use 
5930: 4d 61 63 20 4f 53 2d 58 20 73 74 79 6c 65 20 66  Mac OS-X style f
5940: 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20  ullsync instead 
5950: 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2f 0a 23  of fsync()..*/.#
5960: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59  define SQLITE_SY
5970: 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20  NC_NORMAL       
5980: 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e 65   0x00002.#define
5990: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
59a0: 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  L          0x000
59b0: 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  03.#define SQLIT
59c0: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20  E_SYNC_DATAONLY 
59d0: 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a 0a 2f       0x00010.../
59e0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
59f0: 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e  S Interface Open
5a00: 20 46 69 6c 65 20 48 61 6e 64 6c 65 20 7b 46 31   File Handle {F1
5a10: 31 31 31 30 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b  1110}.**.** An [
5a20: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
5a30: 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20  ject represents 
5a40: 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20  an open file in 
5a50: 74 68 65 20 4f 53 0a 2a 2a 20 69 6e 74 65 72 66  the OS.** interf
5a60: 61 63 65 20 6c 61 79 65 72 2e 20 20 49 6e 64 69  ace layer.  Indi
5a70: 76 69 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66  vidual OS interf
5a80: 61 63 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ace implementati
5a90: 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74  ons will.** want
5aa0: 20 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68 69   to subclass thi
5ab0: 73 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70 65  s object by appe
5ac0: 6e 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c  nding additional
5ad0: 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74   fields.** for t
5ae0: 68 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20 54  heir own use.  T
5af0: 68 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74 72  he pMethods entr
5b00: 79 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  y is a pointer t
5b10: 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  o an.** [sqlite3
5b20: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
5b30: 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73  ect that defines
5b40: 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65 72   methods for per
5b50: 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f  forming.** I/O o
5b60: 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65  perations on the
5b70: 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74   open file..*/.t
5b80: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
5b90: 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69 74  lite3_file sqlit
5ba0: 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74 20  e3_file;.struct 
5bb0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20  sqlite3_file {. 
5bc0: 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71   const struct sq
5bd0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
5be0: 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20   *pMethods;  /* 
5bf0: 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f  Methods for an o
5c00: 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a  pen file */.};..
5c10: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
5c20: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 46 69 6c  OS Interface Fil
5c30: 65 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f 64  e Virtual Method
5c40: 73 20 4f 62 6a 65 63 74 20 7b 46 31 31 31 32 30  s Object {F11120
5c50: 7d 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69  }.**.** Every fi
5c60: 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74 68 65  le opened by the
5c70: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78   [sqlite3_vfs] x
5c80: 4f 70 65 6e 20 6d 65 74 68 6f 64 20 63 6f 6e 74  Open method cont
5c90: 61 69 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  ains a pointer t
5ca0: 6f 0a 2a 2a 20 61 6e 20 69 6e 73 74 61 6e 63 65  o.** an instance
5cb0: 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 2e   of this object.
5cc0: 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 64 65    This object de
5cd0: 66 69 6e 65 73 20 74 68 65 0a 2a 2a 20 6d 65 74  fines the.** met
5ce0: 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 72  hods used to per
5cf0: 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65  form various ope
5d00: 72 61 74 69 6f 6e 73 20 61 67 61 69 6e 73 74 20  rations against 
5d10: 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a  the open file..*
5d20: 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61  *.** The flags a
5d30: 72 67 75 6d 65 6e 74 20 74 6f 20 78 53 79 6e 63  rgument to xSync
5d40: 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66 20 5b   may be one of [
5d50: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d  SQLITE_SYNC_NORM
5d60: 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54  AL] or.** [SQLIT
5d70: 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54  E_SYNC_FULL].  T
5d80: 68 65 20 66 69 72 73 74 20 63 68 6f 69 63 65 20  he first choice 
5d90: 69 73 20 74 68 65 20 6e 6f 72 6d 61 6c 20 66 73  is the normal fs
5da0: 79 6e 63 28 29 2e 0a 2a 20 20 54 68 65 20 73 65  ync()..*  The se
5db0: 63 6f 6e 64 20 63 68 6f 69 63 65 20 69 73 20 61  cond choice is a
5dc0: 6e 0a 2a 2a 20 4f 53 2d 58 20 73 74 79 6c 65 20  n.** OS-X style 
5dd0: 66 75 6c 6c 73 79 6e 63 2e 20 20 54 68 65 20 53  fullsync.  The S
5de0: 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 20  QLITE_SYNC_DATA 
5df0: 66 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64  flag may be ORed
5e00: 20 69 6e 20 74 6f 0a 2a 2a 20 69 6e 64 69 63 61   in to.** indica
5e10: 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74 68 65  te that only the
5e20: 20 64 61 74 61 20 6f 66 20 74 68 65 20 66 69 6c   data of the fil
5e30: 65 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e  e and not its in
5e40: 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65 0a  ode needs to be.
5e50: 2a 2a 20 73 79 6e 63 65 64 2e 0a 2a 2a 20 0a 2a  ** synced..** .*
5e60: 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20 76 61  * The integer va
5e70: 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20  lues to xLock() 
5e80: 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72  and xUnlock() ar
5e90: 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e  e one of.** <ul>
5ea0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
5eb0: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20  _LOCK_NONE],.** 
5ec0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
5ed0: 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c  K_SHARED],.** <l
5ee0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
5ef0: 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c  RESERVED],.** <l
5f00: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
5f10: 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20  PENDING], or.** 
5f20: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
5f30: 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a  K_EXCLUSIVE]..**
5f40: 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28   </ul>.** xLock(
5f50: 29 20 69 6e 63 72 65 61 73 65 73 20 74 68 65 20  ) increases the 
5f60: 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20  lock. xUnlock() 
5f70: 64 65 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f  decreases the lo
5f80: 63 6b 2e 20 20 0a 2a 2a 20 54 68 65 20 78 43 68  ck.  .** The xCh
5f90: 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28  eckReservedLock(
5fa0: 29 20 6d 65 74 68 6f 64 20 6c 6f 6f 6b 73 0a 2a  ) method looks.*
5fb0: 2a 20 74 6f 20 73 65 65 20 69 66 20 61 6e 79 20  * to see if any 
5fc0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
5fd0: 69 6f 6e 2c 20 65 69 74 68 65 72 20 69 6e 20 74  ion, either in t
5fe0: 68 69 73 0a 2a 2a 20 70 72 6f 63 65 73 73 20 6f  his.** process o
5ff0: 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65 72 20  r in some other 
6000: 70 72 6f 63 65 73 73 2c 20 69 73 20 68 6f 6c 64  process, is hold
6010: 69 6e 67 20 61 6e 20 52 45 53 45 52 56 45 44 2c  ing an RESERVED,
6020: 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72 20  .** PENDING, or 
6030: 45 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20 6f  EXCLUSIVE lock o
6040: 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 49 74 20  n the file.  It 
6050: 72 65 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a 20  returns true.** 
6060: 69 66 20 73 75 63 68 20 61 20 6c 6f 63 6b 20 65  if such a lock e
6070: 78 69 73 74 73 20 61 6e 64 20 66 61 6c 73 65 20  xists and false 
6080: 69 66 20 6e 6f 74 2e 0a 2a 2a 20 0a 2a 2a 20 54  if not..** .** T
6090: 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28  he xFileControl(
60a0: 29 20 6d 65 74 68 6f 64 20 69 73 20 61 20 67 65  ) method is a ge
60b0: 6e 65 72 69 63 20 69 6e 74 65 72 66 61 63 65 20  neric interface 
60c0: 74 68 61 74 20 61 6c 6c 6f 77 73 20 63 75 73 74  that allows cust
60d0: 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d 70 6c 65 6d  om.** VFS implem
60e0: 65 6e 74 61 74 69 6f 6e 73 20 74 6f 20 64 69 72  entations to dir
60f0: 65 63 74 6c 79 20 63 6f 6e 74 72 6f 6c 20 61 6e  ectly control an
6100: 20 6f 70 65 6e 20 66 69 6c 65 20 75 73 69 6e 67   open file using
6110: 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
6120: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
6130: 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65   interface.  The
6140: 20 73 65 63 6f 6e 64 20 22 6f 70 22 20 61 72 67   second "op" arg
6150: 75 6d 65 6e 74 0a 2a 2a 20 69 73 20 61 6e 20 69  ument.** is an i
6160: 6e 74 65 67 65 72 20 6f 70 63 6f 64 65 2e 20 20  nteger opcode.  
6170: 20 54 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72   The third.** ar
6180: 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65 6e 65  gument is a gene
6190: 72 69 63 20 70 6f 69 6e 74 65 72 20 77 68 69 63  ric pointer whic
61a0: 68 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f  h is intended to
61b0: 20 62 65 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a   be a pointer.**
61c0: 20 74 6f 20 61 20 73 74 72 75 63 74 75 72 65 20   to a structure 
61d0: 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e  that may contain
61e0: 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 73 70   arguments or sp
61f0: 61 63 65 20 69 6e 20 77 68 69 63 68 20 74 6f 0a  ace in which to.
6200: 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72 6e 20  ** write return 
6210: 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74 69  values.  Potenti
6220: 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46 69 6c  al uses for xFil
6230: 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74  eControl() might
6240: 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73   be.** functions
6250: 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b   to enable block
6260: 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 20 74  ing locks with t
6270: 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e  imeouts, to chan
6280: 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e  ge the.** lockin
6290: 67 20 73 74 72 61 74 65 67 79 20 28 66 6f 72 20  g strategy (for 
62a0: 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 20 64  example to use d
62b0: 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20  ot-file locks), 
62c0: 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62  to inquire.** ab
62d0: 6f 75 74 20 74 68 65 20 73 74 61 74 75 73 20 6f  out the status o
62e0: 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20  f a lock, or to 
62f0: 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b  break stale lock
6300: 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65 0a 2a  s.  The SQLite.*
6310: 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65 73 20  * core reserves 
6320: 6f 70 63 6f 64 65 73 20 6c 65 73 73 20 74 68 61  opcodes less tha
6330: 6e 20 31 30 30 20 66 6f 72 20 69 74 73 20 6f 77  n 100 for its ow
6340: 6e 20 75 73 65 2e 20 0a 2a 2a 20 41 20 5b 53 51  n use. .** A [SQ
6350: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53  LITE_FCNTL_LOCKS
6360: 54 41 54 45 20 7c 20 6c 69 73 74 20 6f 66 20 6f  TATE | list of o
6370: 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 74 68 61  pcodes] less tha
6380: 6e 20 31 30 30 20 69 73 20 61 76 61 69 6c 61 62  n 100 is availab
6390: 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  le..** Applicati
63a0: 6f 6e 73 20 74 68 61 74 20 64 65 66 69 6e 65 20  ons that define 
63b0: 61 20 63 75 73 74 6f 6d 20 78 46 69 6c 65 43 6f  a custom xFileCo
63c0: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68 6f  ntrol method sho
63d0: 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 65 73 20  uld use opcodes 
63e0: 0a 2a 2a 20 67 72 65 61 74 65 72 20 74 68 61 6e  .** greater than
63f0: 20 31 30 30 20 74 6f 20 61 76 6f 69 64 20 63 6f   100 to avoid co
6400: 6e 66 6c 69 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54  nflicts..**.** T
6410: 68 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28 29  he xSectorSize()
6420: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
6430: 74 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20  the sector size 
6440: 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63 65  of the.** device
6450: 20 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73 20   that underlies 
6460: 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 73  the file.  The s
6470: 65 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74 68  ector size is th
6480: 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69  e.** minimum wri
6490: 74 65 20 74 68 61 74 20 63 61 6e 20 62 65 20 70  te that can be p
64a0: 65 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75 74  erformed without
64b0: 20 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f   disturbing.** o
64c0: 74 68 65 72 20 62 79 74 65 73 20 69 6e 20 74 68  ther bytes in th
64d0: 65 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44 65  e file.  The xDe
64e0: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74  viceCharacterist
64f0: 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20  ics().** method 
6500: 72 65 74 75 72 6e 73 20 61 20 62 69 74 20 76 65  returns a bit ve
6510: 63 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67 20  ctor describing 
6520: 62 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68 65  behaviors of the
6530: 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 64  .** underlying d
6540: 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  evice:.**.** <ul
6550: 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  >.** <li> [SQLIT
6560: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a  E_IOCAP_ATOMIC].
6570: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
6580: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d  IOCAP_ATOMIC512]
6590: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
65a0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d  _IOCAP_ATOMIC1K]
65b0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
65c0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d  _IOCAP_ATOMIC2K]
65d0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
65e0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d  _IOCAP_ATOMIC4K]
65f0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
6600: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d  _IOCAP_ATOMIC8K]
6610: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
6620: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b  _IOCAP_ATOMIC16K
6630: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
6640: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32  E_IOCAP_ATOMIC32
6650: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
6660: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36  TE_IOCAP_ATOMIC6
6670: 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  4K].** <li> [SQL
6680: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41  ITE_IOCAP_SAFE_A
6690: 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  PPEND].** <li> [
66a0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51  SQLITE_IOCAP_SEQ
66b0: 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c  UENTIAL].** </ul
66c0: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49  >.**.** The SQLI
66d0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20  TE_IOCAP_ATOMIC 
66e0: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
66f0: 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f  hat all writes o
6700: 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72  f.** any size ar
6710: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
6720: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6730: 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20  ICnnn values.** 
6740: 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73  mean that writes
6750: 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20   of blocks that 
6760: 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e  are nnn bytes in
6770: 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65   size and.** are
6780: 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61   aligned to an a
6790: 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20  ddress which is 
67a0: 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69  an integer multi
67b0: 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72  ple of.** nnn ar
67c0: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
67d0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
67e0: 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65  _APPEND value me
67f0: 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e  ans.** that when
6800: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
6810: 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65  d to a file, the
6820: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
6830: 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20  d.** first then 
6840: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
6850: 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64  file is extended
6860: 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65  , never the othe
6870: 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e  r.** way around.
6880: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
6890: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72  AP_SEQUENTIAL pr
68a0: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
68b0: 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  t.** information
68c0: 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64   is written to d
68d0: 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20  isk in the same 
68e0: 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a  order as calls.*
68f0: 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a  * to xWrite()..*
6900: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
6910: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
6920: 6f 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ods sqlite3_io_m
6930: 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73  ethods;.struct s
6940: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
6950: 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69  s {.  int iVersi
6960: 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f  on;.  int (*xClo
6970: 73 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  se)(sqlite3_file
6980: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61  *);.  int (*xRea
6990: 64 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  d)(sqlite3_file*
69a0: 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d  , void*, int iAm
69b0: 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  t, sqlite3_int64
69c0: 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28   iOfst);.  int (
69d0: 2a 78 57 72 69 74 65 29 28 73 71 6c 69 74 65 33  *xWrite)(sqlite3
69e0: 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f  _file*, const vo
69f0: 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73  id*, int iAmt, s
6a00: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
6a10: 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72  st);.  int (*xTr
6a20: 75 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f  uncate)(sqlite3_
6a30: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
6a40: 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e  nt64 size);.  in
6a50: 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74  t (*xSync)(sqlit
6a60: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c  e3_file*, int fl
6a70: 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  ags);.  int (*xF
6a80: 69 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33  ileSize)(sqlite3
6a90: 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f  _file*, sqlite3_
6aa0: 69 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20  int64 *pSize);. 
6ab0: 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71   int (*xLock)(sq
6ac0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
6ad0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f  );.  int (*xUnlo
6ae0: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
6af0: 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28  *, int);.  int (
6b00: 2a 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c  *xCheckReservedL
6b10: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
6b20: 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74  e*, int *pResOut
6b30: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65  );.  int (*xFile
6b40: 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33  Control)(sqlite3
6b50: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20  _file*, int op, 
6b60: 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69  void *pArg);.  i
6b70: 6e 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65  nt (*xSectorSize
6b80: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
6b90: 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63  ;.  int (*xDevic
6ba0: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73  eCharacteristics
6bb0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
6bc0: 3b 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61  ;.  /* Additiona
6bd0: 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65  l methods may be
6be0: 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
6bf0: 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a   releases */.};.
6c00: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
6c10: 20 53 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43   Standard File C
6c20: 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73 20 7b  ontrol Opcodes {
6c30: 46 31 31 33 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 68  F11310}.**.** Th
6c40: 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73  ese integer cons
6c50: 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65  tants are opcode
6c60: 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43  s for the xFileC
6c70: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a  ontrol method.**
6c80: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
6c90: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
6ca0: 65 63 74 20 61 6e 64 20 74 6f 20 74 68 65 20 5b  ect and to the [
6cb0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
6cc0: 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72  trol()].** inter
6cd0: 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  face..**.** The 
6ce0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f  [SQLITE_FCNTL_LO
6cf0: 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64 65 20  CKSTATE] opcode 
6d00: 69 73 20 75 73 65 64 20 66 6f 72 20 64 65 62 75  is used for debu
6d10: 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20  gging.  This.** 
6d20: 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20 74 68  opcode causes th
6d30: 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d  e xFileControl m
6d40: 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65 20 74  ethod to write t
6d50: 68 65 20 63 75 72 72 65 6e 74 20 73 74 61 74 65  he current state
6d60: 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b 20   of.** the lock 
6d70: 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f  (one of [SQLITE_
6d80: 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c  LOCK_NONE], [SQL
6d90: 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d  ITE_LOCK_SHARED]
6da0: 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  ,.** [SQLITE_LOC
6db0: 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b 53 51  K_RESERVED], [SQ
6dc0: 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e  LITE_LOCK_PENDIN
6dd0: 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4c  G], or [SQLITE_L
6de0: 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29 0a  OCK_EXCLUSIVE]).
6df0: 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65 67  ** into an integ
6e00: 65 72 20 74 68 61 74 20 74 68 65 20 70 41 72 67  er that the pArg
6e10: 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73   argument points
6e20: 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61 62 69   to. This capabi
6e30: 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65 64 20  lity.** is used 
6e40: 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20 61  during testing a
6e50: 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f  nd only needs to
6e60: 20 62 65 20 73 75 70 70 6f 72 74 65 64 20 77 68   be supported wh
6e70: 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a  en SQLITE_TEST.*
6e80: 2a 20 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2f  * is defined..*/
6e90: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6ea0: 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20  FCNTL_LOCKSTATE 
6eb0: 20 20 20 20 20 20 20 31 0a 0a 2f 2a 0a 2a 2a 20         1../*.** 
6ec0: 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20  CAPI3REF: Mutex 
6ed0: 48 61 6e 64 6c 65 20 7b 46 31 37 31 31 30 7d 0a  Handle {F17110}.
6ee0: 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20  **.** The mutex 
6ef0: 6d 6f 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51  module within SQ
6f00: 4c 69 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71  Lite defines [sq
6f10: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20  lite3_mutex] to 
6f20: 62 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63  be an.** abstrac
6f30: 74 20 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74  t type for a mut
6f40: 65 78 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20  ex object.  The 
6f50: 53 51 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65  SQLite core neve
6f60: 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68  r looks.** at th
6f70: 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65  e internal repre
6f80: 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20  sentation of an 
6f90: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e  [sqlite3_mutex].
6fa0: 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61    It only.** dea
6fb0: 6c 73 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73  ls with pointers
6fc0: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
6fd0: 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a  _mutex] object..
6fe0: 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72  **.** Mutexes ar
6ff0: 65 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20  e created using 
7000: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61  [sqlite3_mutex_a
7010: 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65  lloc()]..*/.type
7020: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
7030: 65 33 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33  e3_mutex sqlite3
7040: 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43  _mutex;../*.** C
7050: 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65  API3REF: OS Inte
7060: 72 66 61 63 65 20 4f 62 6a 65 63 74 20 7b 46 31  rface Object {F1
7070: 31 31 34 30 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69  1140}.**.** An i
7080: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
7090: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74  object defines t
70a0: 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74  he interface bet
70b0: 77 65 65 6e 20 74 68 65 0a 2a 2a 20 53 51 4c 69  ween the.** SQLi
70c0: 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20  te core and the 
70d0: 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61  underlying opera
70e0: 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68  ting system.  Th
70f0: 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68  e "vfs".** in th
7100: 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62  e name of the ob
7110: 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20  ject stands for 
7120: 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79  "virtual file sy
7130: 73 74 65 6d 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  stem"..**.** The
7140: 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20   iVersion field 
7150: 69 73 20 69 6e 69 74 69 61 6c 6c 79 20 31 20 62  is initially 1 b
7160: 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72  ut may be larger
7170: 20 66 6f 72 20 66 75 74 75 72 65 0a 2a 2a 20 76   for future.** v
7180: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
7190: 65 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 66  e.  Additional f
71a0: 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70  ields may be app
71b0: 65 6e 64 65 64 20 74 6f 20 74 68 69 73 0a 2a 2a  ended to this.**
71c0: 20 6f 62 6a 65 63 74 20 77 68 65 6e 20 74 68 65   object when the
71d0: 20 69 56 65 72 73 69 6f 6e 20 76 61 6c 75 65 20   iVersion value 
71e0: 69 73 20 69 6e 63 72 65 61 73 65 64 2e 0a 2a 2a  is increased..**
71f0: 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65  .** The szOsFile
7200: 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 73 69   field is the si
7210: 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61  ze of the subcla
7220: 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69  ssed [sqlite3_fi
7230: 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  le].** structure
7240: 20 75 73 65 64 20 62 79 20 74 68 69 73 20 56 46   used by this VF
7250: 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69  S.  mxPathname i
7260: 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  s the maximum le
7270: 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74  ngth of.** a pat
7280: 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46  hname in this VF
7290: 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65  S..**.** Registe
72a0: 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20  red sqlite3_vfs 
72b0: 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74  objects are kept
72c0: 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73   on a linked lis
72d0: 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74  t formed by.** t
72e0: 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72  he pNext pointer
72f0: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
7300: 76 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a  vfs_register()].
7310: 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
7320: 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29  vfs_unregister()
7330: 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e  ] interfaces man
7340: 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a  age this list.**
7350: 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66   in a thread-saf
7360: 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c  e way.  The [sql
7370: 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d  ite3_vfs_find()]
7380: 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65   interface.** se
7390: 61 72 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e  arches the list.
73a0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74  .**.** The pNext
73b0: 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e   field is the on
73c0: 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65 20  ly field in the 
73d0: 73 71 6c 69 74 65 33 5f 76 66 73 20 0a 2a 2a 20  sqlite3_vfs .** 
73e0: 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20 53  structure that S
73f0: 51 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20  QLite will ever 
7400: 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20  modify.  SQLite 
7410: 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73  will only access
7420: 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68  .** or modify th
7430: 69 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68  is field while h
7440: 6f 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63 75  olding a particu
7450: 6c 61 72 20 73 74 61 74 69 63 20 6d 75 74 65 78  lar static mutex
7460: 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
7470: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65  tion should neve
7480: 72 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e  r modify anythin
7490: 67 20 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c  g within the sql
74a0: 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65  ite3_vfs.** obje
74b0: 63 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65  ct once the obje
74c0: 63 74 20 68 61 73 20 62 65 65 6e 20 72 65 67 69  ct has been regi
74d0: 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  stered..**.** Th
74e0: 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f  e zName field ho
74f0: 6c 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  lds the name of 
7500: 74 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20  the VFS module. 
7510: 20 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a   The name must.*
7520: 2a 20 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f  * be unique acro
7530: 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c  ss all VFS modul
7540: 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 31 34  es..**.** {F1114
7550: 31 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 67  1} SQLite will g
7560: 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 74 68  uarantee that th
7570: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 73 74 72 69  e zFilename stri
7580: 6e 67 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20  ng passed to.** 
7590: 78 4f 70 65 6e 28 29 20 69 73 20 61 20 66 75 6c  xOpen() is a ful
75a0: 6c 20 70 61 74 68 6e 61 6d 65 20 61 73 20 67 65  l pathname as ge
75b0: 6e 65 72 61 74 65 64 20 62 79 20 78 46 75 6c 6c  nerated by xFull
75c0: 50 61 74 68 6e 61 6d 65 28 29 20 61 6e 64 0a 2a  Pathname() and.*
75d0: 2a 20 74 68 61 74 20 74 68 65 20 73 74 72 69 6e  * that the strin
75e0: 67 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20  g will be valid 
75f0: 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75 6e  and unchanged un
7600: 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73 0a  til xClose() is.
7610: 2a 2a 20 63 61 6c 6c 65 64 2e 20 20 7b 45 4e 44  ** called.  {END
7620: 7d 20 53 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  } So the [sqlite
7630: 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 74 6f 72  3_file] can stor
7640: 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  e a pointer to t
7650: 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69  he.** filename i
7660: 66 20 69 74 20 6e 65 65 64 73 20 74 6f 20 72 65  f it needs to re
7670: 6d 65 6d 62 65 72 20 74 68 65 20 66 69 6c 65 6e  member the filen
7680: 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 61  ame for some rea
7690: 73 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 31  son..**.** {F111
76a0: 34 32 7d 20 54 68 65 20 66 6c 61 67 73 20 61 72  42} The flags ar
76b0: 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28  gument to xOpen(
76c0: 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62  ) includes all b
76d0: 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68  its set in.** th
76e0: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
76f0: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
7700: 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 20  n_v2()].  Or if 
7710: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
7720: 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
7730: 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65  open16()] is use
7740: 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69 6e  d, then flags in
7750: 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74 0a  cludes at least.
7760: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
7770: 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51  READWRITE] | [SQ
7780: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
7790: 5d 2e 20 7b 45 4e 44 7d 0a 2a 2a 20 49 66 20 78  ]. {END}.** If x
77a0: 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66  Open() opens a f
77b0: 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68  ile read-only th
77c0: 65 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74  en it sets *pOut
77d0: 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c  Flags to.** incl
77e0: 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ude [SQLITE_OPEN
77f0: 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68  _READONLY].  Oth
7800: 65 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74  er bits in *pOut
7810: 46 6c 61 67 73 20 6d 61 79 20 62 65 0a 2a 2a 20  Flags may be.** 
7820: 73 65 74 2e 0a 2a 2a 20 0a 2a 2a 20 7b 46 31 31  set..** .** {F11
7830: 31 34 33 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c  143} SQLite will
7840: 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66   also add one of
7850: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66   the following f
7860: 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65  lags to the xOpe
7870: 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70  n().** call, dep
7880: 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62  ending on the ob
7890: 6a 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65  ject being opene
78a0: 64 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75 6c 3e 0a 2a  d:.** .** <ul>.*
78b0: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
78c0: 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a  OPEN_MAIN_DB].**
78d0: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
78e0: 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c  PEN_MAIN_JOURNAL
78f0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
7900: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d  TE_OPEN_TEMP_DB]
7910: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
7920: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52  E_OPEN_TEMP_JOUR
7930: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NAL].** <li>  [S
7940: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53  QLITE_OPEN_TRANS
7950: 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e  IENT_DB].** <li>
7960: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53    [SQLITE_OPEN_S
7970: 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c  UBJOURNAL].** <l
7980: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
7990: 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d  _MASTER_JOURNAL]
79a0: 0a 2a 2a 20 3c 2f 75 6c 3e 20 7b 45 4e 44 7d 0a  .** </ul> {END}.
79b0: 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20 49  **.** The file I
79c0: 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  /O implementatio
79d0: 6e 20 63 61 6e 20 75 73 65 20 74 68 65 20 6f 62  n can use the ob
79e0: 6a 65 63 74 20 74 79 70 65 20 66 6c 61 67 73 20  ject type flags 
79f0: 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 68  to.** changes th
7a00: 65 20 77 61 79 20 69 74 20 64 65 61 6c 73 20 77  e way it deals w
7a10: 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f 72 20  ith files.  For 
7a20: 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c  example, an appl
7a30: 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20  ication.** that 
7a40: 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 61 62  does not care ab
7a50: 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f 76 65  out crash recove
7a60: 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d  ry or rollback m
7a70: 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65  ight make.** the
7a80: 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e   open of a journ
7a90: 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e  al file a no-op.
7aa0: 20 20 57 72 69 74 65 73 20 74 6f 20 74 68 69 73    Writes to this
7ab0: 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a   journal would.*
7ac0: 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73  * also be no-ops
7ad0: 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 65 6d 70  , and any attemp
7ae0: 74 20 74 6f 20 72 65 61 64 20 74 68 65 20 6a 6f  t to read the jo
7af0: 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74 75  urnal would retu
7b00: 72 6e 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f  rn .** SQLITE_IO
7b10: 45 52 52 2e 20 20 4f 72 20 74 68 65 20 69 6d 70  ERR.  Or the imp
7b20: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68  lementation migh
7b30: 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 61 74  t recognize that
7b40: 20 61 20 64 61 74 61 62 61 73 65 20 0a 2a 2a 20   a database .** 
7b50: 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f 69  file will be doi
7b60: 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 20  ng page-aligned 
7b70: 73 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e 64  sector reads and
7b80: 20 77 72 69 74 65 73 20 69 6e 20 61 20 72 61 6e   writes in a ran
7b90: 64 6f 6d 20 0a 2a 2a 20 6f 72 64 65 72 20 61 6e  dom .** order an
7ba0: 64 20 73 65 74 20 75 70 20 69 74 73 20 49 2f 4f  d set up its I/O
7bb0: 20 73 75 62 73 79 73 74 65 6d 20 61 63 63 6f 72   subsystem accor
7bc0: 64 69 6e 67 6c 79 2e 0a 2a 2a 20 0a 2a 2a 20 53  dingly..** .** S
7bd0: 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f  QLite might also
7be0: 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20   add one of the 
7bf0: 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20  following flags 
7c00: 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a 2a 2a 20  to the xOpen.** 
7c10: 6d 65 74 68 6f 64 3a 0a 2a 2a 20 0a 2a 2a 20 3c  method:.** .** <
7c20: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  ul>.** <li> [SQL
7c30: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
7c40: 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20  NCLOSE].** <li> 
7c50: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43  [SQLITE_OPEN_EXC
7c60: 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e  LUSIVE].** </ul>
7c70: 0a 2a 2a 20 0a 2a 2a 20 7b 46 31 31 31 34 35 7d  .** .** {F11145}
7c80: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   The [SQLITE_OPE
7c90: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
7ca0: 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20   flag means the 
7cb0: 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a  file should be.*
7cc0: 2a 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69  * deleted when i
7cd0: 74 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 7b 46  t is closed.  {F
7ce0: 31 31 31 34 36 7d 20 54 68 65 20 5b 53 51 4c 49  11146} The [SQLI
7cf0: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
7d00: 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62  CLOSE].** will b
7d10: 65 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20 20  e set for TEMP  
7d20: 64 61 74 61 62 61 73 65 73 2c 20 6a 6f 75 72 6e  databases, journ
7d30: 61 6c 73 20 61 6e 64 20 66 6f 72 20 73 75 62 6a  als and for subj
7d40: 6f 75 72 6e 61 6c 73 2e 20 0a 2a 2a 20 7b 46 31  ournals. .** {F1
7d50: 31 31 34 37 7d 20 54 68 65 20 5b 53 51 4c 49 54  1147} The [SQLIT
7d60: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45  E_OPEN_EXCLUSIVE
7d70: 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65  ] flag means the
7d80: 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 20   file should be 
7d90: 6f 70 65 6e 65 64 0a 2a 2a 20 66 6f 72 20 65 78  opened.** for ex
7da0: 63 6c 75 73 69 76 65 20 61 63 63 65 73 73 2e 20  clusive access. 
7db0: 20 54 68 69 73 20 66 6c 61 67 20 69 73 20 73 65   This flag is se
7dc0: 74 20 66 6f 72 20 61 6c 6c 20 66 69 6c 65 73 20  t for all files 
7dd0: 65 78 63 65 70 74 0a 2a 2a 20 66 6f 72 20 74 68  except.** for th
7de0: 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20  e main database 
7df0: 66 69 6c 65 2e 20 7b 45 4e 44 7d 0a 2a 2a 20 0a  file. {END}.** .
7e00: 2a 2a 20 7b 46 31 31 31 34 38 7d 20 41 74 20 6c  ** {F11148} At l
7e10: 65 61 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 79  east szOsFile by
7e20: 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72  tes of memory ar
7e30: 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53  e allocated by S
7e40: 51 4c 69 74 65 20 0a 2a 2a 20 74 6f 20 68 6f 6c  QLite .** to hol
7e50: 64 20 74 68 65 20 20 5b 73 71 6c 69 74 65 33 5f  d the  [sqlite3_
7e60: 66 69 6c 65 5d 20 73 74 72 75 63 74 75 72 65 20  file] structure 
7e70: 70 61 73 73 65 64 20 61 73 20 74 68 65 20 74 68  passed as the th
7e80: 69 72 64 20 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  ird .** argument
7e90: 20 74 6f 20 78 4f 70 65 6e 2e 20 20 7b 45 4e 44   to xOpen.  {END
7ea0: 7d 20 20 54 68 65 20 78 4f 70 65 6e 20 6d 65 74  }  The xOpen met
7eb0: 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68 61 76  hod does not hav
7ec0: 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65  e to.** allocate
7ed0: 20 74 68 65 20 73 74 72 75 63 74 75 72 65 3b 20   the structure; 
7ee0: 69 74 20 73 68 6f 75 6c 64 20 6a 75 73 74 20 66  it should just f
7ef0: 69 6c 6c 20 69 74 20 69 6e 2e 0a 2a 2a 20 0a 2a  ill it in..** .*
7f00: 2a 20 7b 46 31 31 31 34 39 7d 20 54 68 65 20 66  * {F11149} The f
7f10: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
7f20: 20 78 41 63 63 65 73 73 28 29 20 6d 61 79 20 62   xAccess() may b
7f30: 65 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53  e [SQLITE_ACCESS
7f40: 5f 45 58 49 53 54 53 5d 20 0a 2a 2a 20 74 6f 20  _EXISTS] .** to 
7f50: 74 65 73 74 20 66 6f 72 20 74 68 65 20 65 78 69  test for the exi
7f60: 73 74 65 6e 63 65 20 6f 66 20 61 20 66 69 6c 65  stence of a file
7f70: 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ,.** or [SQLITE_
7f80: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
7f90: 5d 20 74 6f 20 74 65 73 74 20 74 6f 20 73 65 65  ] to test to see
7fa0: 0a 2a 2a 20 69 66 20 61 20 66 69 6c 65 20 69 73  .** if a file is
7fb0: 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72   readable and wr
7fc0: 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49  itable, or [SQLI
7fd0: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a  TE_ACCESS_READ].
7fe0: 2a 2a 20 74 6f 20 74 65 73 74 20 74 6f 20 73 65  ** to test to se
7ff0: 65 20 69 66 20 61 20 66 69 6c 65 20 69 73 20 61  e if a file is a
8000: 74 20 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65  t least readable
8010: 2e 20 20 7b 45 4e 44 7d 20 54 68 65 20 66 69 6c  .  {END} The fil
8020: 65 20 63 61 6e 20 62 65 20 61 20 0a 2a 2a 20 64  e can be a .** d
8030: 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 20 0a 2a 2a  irectory..** .**
8040: 20 7b 46 31 31 31 35 30 7d 20 53 51 4c 69 74 65   {F11150} SQLite
8050: 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c   will always all
8060: 6f 63 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d  ocate at least m
8070: 78 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65  xPathname+1 byte
8080: 73 20 66 6f 72 0a 2a 2a 20 74 68 65 20 6f 75 74  s for.** the out
8090: 70 75 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c  put buffer xFull
80a0: 50 61 74 68 6e 61 6d 65 2e 20 7b 46 31 31 31 35  Pathname. {F1115
80b0: 31 7d 20 54 68 65 20 65 78 61 63 74 0a 2a 2a 20  1} The exact.** 
80c0: 73 69 7a 65 20 6f 66 20 74 68 65 20 6f 75 74 70  size of the outp
80d0: 75 74 20 62 75 66 66 65 72 20 69 73 20 61 6c 73  ut buffer is als
80e0: 6f 20 70 61 73 73 65 64 20 61 73 20 61 20 70 61  o passed as a pa
80f0: 72 61 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20  rameter to both 
8100: 0a 2a 2a 20 6d 65 74 68 6f 64 73 2e 20 7b 45 4e  .** methods. {EN
8110: 44 7d 20 49 66 20 74 68 65 20 6f 75 74 70 75 74  D} If the output
8120: 20 62 75 66 66 65 72 20 69 73 20 6e 6f 74 20 6c   buffer is not l
8130: 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51  arge enough, [SQ
8140: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 0a 2a  LITE_CANTOPEN].*
8150: 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75  * should be retu
8160: 72 6e 65 64 2e 20 41 73 20 74 68 69 73 20 69 73  rned. As this is
8170: 20 68 61 6e 64 6c 65 64 20 61 73 20 61 20 66 61   handled as a fa
8180: 74 61 6c 20 65 72 72 6f 72 20 62 79 20 53 51 4c  tal error by SQL
8190: 69 74 65 2c 0a 2a 2a 20 76 66 73 20 69 6d 70 6c  ite,.** vfs impl
81a0: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75  ementations shou
81b0: 6c 64 20 65 6e 64 65 61 76 6f 72 20 74 6f 20 70  ld endeavor to p
81c0: 72 65 76 65 6e 74 20 74 68 69 73 20 62 79 20 73  revent this by s
81d0: 65 74 74 69 6e 67 20 0a 2a 2a 20 6d 78 50 61 74  etting .** mxPat
81e0: 68 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69  hname to a suffi
81f0: 63 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61  ciently large va
8200: 6c 75 65 2e 0a 2a 2a 20 0a 2a 2a 20 54 68 65 20  lue..** .** The 
8210: 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78  xRandomness(), x
8220: 53 6c 65 65 70 28 29 2c 20 61 6e 64 20 78 43 75  Sleep(), and xCu
8230: 72 72 65 6e 74 54 69 6d 65 28 29 20 69 6e 74 65  rrentTime() inte
8240: 72 66 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f  rfaces.** are no
8250: 74 20 73 74 72 69 63 74 6c 79 20 61 20 70 61 72  t strictly a par
8260: 74 20 6f 66 20 74 68 65 20 66 69 6c 65 73 79 73  t of the filesys
8270: 74 65 6d 2c 20 62 75 74 20 74 68 65 79 20 61 72  tem, but they ar
8280: 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69 6e  e.** included in
8290: 20 74 68 65 20 56 46 53 20 73 74 72 75 63 74 75   the VFS structu
82a0: 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65 6e  re for completen
82b0: 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61 6e  ess..** The xRan
82c0: 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63 74 69  domness() functi
82d0: 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72  on attempts to r
82e0: 65 74 75 72 6e 20 6e 42 79 74 65 73 20 62 79 74  eturn nBytes byt
82f0: 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71 75  es.** of good-qu
8300: 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73 73  ality randomness
8310: 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68 65   into zOut.  The
8320: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 69 73   return value is
8330: 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 6c 20 6e  .** the actual n
8340: 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 6f  umber of bytes o
8350: 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74  f randomness obt
8360: 61 69 6e 65 64 2e 20 20 54 68 65 0a 2a 2a 20 78  ained.  The.** x
8370: 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20 63  Sleep() method c
8380: 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 69 6e  auses the callin
8390: 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c 65 65  g thread to slee
83a0: 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73  p for at.** leas
83b0: 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
83c0: 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 69 76  microseconds giv
83d0: 65 6e 2e 20 20 54 68 65 20 78 43 75 72 72 65 6e  en.  The xCurren
83e0: 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 68 6f  tTime().** metho
83f0: 64 20 72 65 74 75 72 6e 73 20 61 20 4a 75 6c 69  d returns a Juli
8400: 61 6e 20 44 61 79 20 4e 75 6d 62 65 72 20 66 6f  an Day Number fo
8410: 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 61  r the current da
8420: 74 65 20 61 6e 64 0a 2a 2a 20 74 69 6d 65 2e 0a  te and.** time..
8430: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
8440: 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 73 71  t sqlite3_vfs sq
8450: 6c 69 74 65 33 5f 76 66 73 3b 0a 73 74 72 75 63  lite3_vfs;.struc
8460: 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a  t sqlite3_vfs {.
8470: 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20    int iVersion; 
8480: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74             /* St
8490: 72 75 63 74 75 72 65 20 76 65 72 73 69 6f 6e 20  ructure version 
84a0: 6e 75 6d 62 65 72 20 2a 2f 0a 20 20 69 6e 74 20  number */.  int 
84b0: 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20 20 20  szOsFile;       
84c0: 20 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20       /* Size of 
84d0: 73 75 62 63 6c 61 73 73 65 64 20 73 71 6c 69 74  subclassed sqlit
84e0: 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74  e3_file */.  int
84f0: 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20 20 20   mxPathname;    
8500: 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
8510: 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c   file pathname l
8520: 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74  ength */.  sqlit
8530: 65 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20 20  e3_vfs *pNext;  
8540: 20 20 20 20 2f 2a 20 4e 65 78 74 20 72 65 67 69      /* Next regi
8550: 73 74 65 72 65 64 20 56 46 53 20 2a 2f 0a 20 20  stered VFS */.  
8560: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
8570: 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65  e;       /* Name
8580: 20 6f 66 20 74 68 69 73 20 76 69 72 74 75 61 6c   of this virtual
8590: 20 66 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a   file system */.
85a0: 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61    void *pAppData
85b0: 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 50 6f  ;          /* Po
85c0: 69 6e 74 65 72 20 74 6f 20 61 70 70 6c 69 63 61  inter to applica
85d0: 74 69 6f 6e 2d 73 70 65 63 69 66 69 63 20 64 61  tion-specific da
85e0: 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f  ta */.  int (*xO
85f0: 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73  pen)(sqlite3_vfs
8600: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
8610: 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66 69  Name, sqlite3_fi
8620: 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20 20 20 20  le*,.           
8630: 20 20 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 69      int flags, i
8640: 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a  nt *pOutFlags);.
8650: 20 20 69 6e 74 20 28 2a 78 44 65 6c 65 74 65 29    int (*xDelete)
8660: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
8670: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
8680: 2c 20 69 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a  , int syncDir);.
8690: 20 20 69 6e 74 20 28 2a 78 41 63 63 65 73 73 29    int (*xAccess)
86a0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
86b0: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
86c0: 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74  , int flags, int
86d0: 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e   *pResOut);.  in
86e0: 74 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d  t (*xFullPathnam
86f0: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
8700: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
8710: 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68  me, int nOut, ch
8720: 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69  ar *zOut);.  voi
8730: 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71  d *(*xDlOpen)(sq
8740: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
8750: 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d  t char *zFilenam
8760: 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c  e);.  void (*xDl
8770: 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76  Error)(sqlite3_v
8780: 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20  fs*, int nByte, 
8790: 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a  char *zErrMsg);.
87a0: 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c 53 79 6d    void *(*xDlSym
87b0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76  )(sqlite3_vfs*,v
87c0: 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  oid*, const char
87d0: 20 2a 7a 53 79 6d 62 6f 6c 29 3b 0a 20 20 76 6f   *zSymbol);.  vo
87e0: 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29 28 73  id (*xDlClose)(s
87f0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76 6f 69  qlite3_vfs*, voi
8800: 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 61  d*);.  int (*xRa
8810: 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69 74 65  ndomness)(sqlite
8820: 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74  3_vfs*, int nByt
8830: 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a  e, char *zOut);.
8840: 20 20 69 6e 74 20 28 2a 78 53 6c 65 65 70 29 28    int (*xSleep)(
8850: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e  sqlite3_vfs*, in
8860: 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 29 3b  t microseconds);
8870: 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65 6e  .  int (*xCurren
8880: 74 54 69 6d 65 29 28 73 71 6c 69 74 65 33 5f 76  tTime)(sqlite3_v
8890: 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a 20  fs*, double*);. 
88a0: 20 69 6e 74 20 28 2a 78 47 65 74 4c 61 73 74 45   int (*xGetLastE
88b0: 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66  rror)(sqlite3_vf
88c0: 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72 20 2a 29  s*, int, char *)
88d0: 3b 0a 20 20 2f 2a 20 4e 65 77 20 66 69 65 6c 64  ;.  /* New field
88e0: 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65  s may be appende
88f0: 64 20 69 6e 20 66 69 67 75 72 65 20 76 65 72 73  d in figure vers
8900: 69 6f 6e 73 2e 20 20 54 68 65 20 69 56 65 72 73  ions.  The iVers
8910: 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77  ion.  ** value w
8920: 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 68  ill increment wh
8930: 65 6e 65 76 65 72 20 74 68 69 73 20 68 61 70 70  enever this happ
8940: 65 6e 73 2e 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  ens. */.};../*.*
8950: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67  * CAPI3REF: Flag
8960: 73 20 66 6f 72 20 74 68 65 20 78 41 63 63 65 73  s for the xAcces
8970: 73 20 56 46 53 20 6d 65 74 68 6f 64 20 7b 46 31  s VFS method {F1
8980: 31 31 39 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 31  1190}.**.** {F11
8990: 31 39 31 7d 20 54 68 65 73 65 20 69 6e 74 65 67  191} These integ
89a0: 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e  er constants can
89b0: 20 62 65 20 75 73 65 64 20 61 73 20 74 68 65 20   be used as the 
89c0: 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
89d0: 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73  to.** the xAcces
89e0: 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b  s method of an [
89f0: 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
8a00: 65 63 74 2e 20 7b 45 4e 44 7d 20 20 54 68 65 79  ect. {END}  They
8a10: 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68   determine.** wh
8a20: 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69  at kind of permi
8a30: 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65  ssions the xAcce
8a40: 73 73 20 6d 65 74 68 6f 64 20 69 73 0a 2a 2a 20  ss method is.** 
8a50: 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e 20 20 7b 46  looking for.  {F
8a60: 31 31 31 39 32 7d 20 57 69 74 68 20 5b 53 51 4c  11192} With [SQL
8a70: 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54  ITE_ACCESS_EXIST
8a80: 53 5d 2c 20 74 68 65 20 78 41 63 63 65 73 73 20  S], the xAccess 
8a90: 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79  method.** simply
8aa0: 20 63 68 65 63 6b 73 20 74 6f 20 73 65 65 20 69   checks to see i
8ab0: 66 20 74 68 65 20 66 69 6c 65 20 65 78 69 73 74  f the file exist
8ac0: 73 2e 20 7b 46 31 31 31 39 33 7d 20 57 69 74 68  s. {F11193} With
8ad0: 0a 2a 2a 20 53 51 4c 49 54 45 5f 41 43 43 45 53  .** SQLITE_ACCES
8ae0: 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68 65  S_READWRITE, the
8af0: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20   xAccess method 
8b00: 63 68 65 63 6b 73 20 74 6f 20 73 65 65 0a 2a 2a  checks to see.**
8b10: 20 69 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   if the file is 
8b20: 62 6f 74 68 20 72 65 61 64 61 62 6c 65 20 61 6e  both readable an
8b30: 64 20 77 72 69 74 61 62 6c 65 2e 20 20 7b 46 31  d writable.  {F1
8b40: 31 31 39 34 7d 20 57 69 74 68 0a 2a 2a 20 53 51  1194} With.** SQ
8b50: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
8b60: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
8b70: 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 74 6f  hod.** checks to
8b80: 20 73 65 65 20 69 66 20 74 68 65 20 66 69 6c 65   see if the file
8b90: 20 69 73 20 72 65 61 64 61 62 6c 65 2e 0a 2a 2f   is readable..*/
8ba0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8bb0: 41 43 43 45 53 53 5f 45 58 49 53 54 53 20 20 20  ACCESS_EXISTS   
8bc0: 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   0.#define SQLIT
8bd0: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49  E_ACCESS_READWRI
8be0: 54 45 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c  TE 1.#define SQL
8bf0: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20  ITE_ACCESS_READ 
8c00: 20 20 20 20 20 32 0a 0a 2f 2a 0a 2a 2a 20 43 41       2../*.** CA
8c10: 50 49 33 52 45 46 3a 20 49 6e 69 74 69 61 6c 69  PI3REF: Initiali
8c20: 7a 65 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69  ze The SQLite Li
8c30: 62 72 61 72 79 20 7b 46 31 30 31 33 30 7d 0a 2a  brary {F10130}.*
8c40: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
8c50: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f  _initialize() ro
8c60: 75 74 69 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65  utine initialize
8c70: 73 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20  s the.** SQLite 
8c80: 6c 69 62 72 61 72 79 20 70 72 69 6f 72 20 74 6f  library prior to
8c90: 20 75 73 65 2e 20 20 54 68 65 20 73 71 6c 69 74   use.  The sqlit
8ca0: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 72 6f  e3_shutdown() ro
8cb0: 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63  utine.** dealloc
8cc0: 61 74 65 73 20 61 6e 79 20 72 65 73 6f 75 72 63  ates any resourc
8cd0: 65 73 20 74 68 61 74 20 77 65 72 65 20 61 6c 6c  es that were all
8ce0: 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 65  ocated by sqlite
8cf0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a  3_initialize()..
8d00: 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20  **.** A call to 
8d10: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
8d20: 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66 66 65  ze() is an "effe
8d30: 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69  ctive" call if i
8d40: 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72 73  t is.** the firs
8d50: 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69  t time sqlite3_i
8d60: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69  nitialize() is i
8d70: 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74 68  nvoked during th
8d80: 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a  e lifetime of.**
8d90: 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f 72   the process, or
8da0: 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69   if it is the fi
8db0: 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33  rst time sqlite3
8dc0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
8dd0: 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c   invoked.** foll
8de0: 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20  owing a call to 
8df0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
8e00: 28 29 2e 20 20 4f 6e 6c 79 20 61 6e 20 65 66 66  ().  Only an eff
8e10: 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f  ective call.** o
8e20: 66 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  f sqlite3_initia
8e30: 6c 69 7a 65 28 29 20 64 6f 65 73 20 61 6e 79 20  lize() does any 
8e40: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 20  initialization. 
8e50: 20 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c 6c 73   All other calls
8e60: 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65 73 73  .** are harmless
8e70: 20 6e 6f 2d 6f 70 73 2e 20 20 49 6e 20 6f 74 68   no-ops.  In oth
8e80: 65 72 20 77 6f 72 64 73 2c 0a 2a 2a 20 74 68 65  er words,.** the
8e90: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
8ea0: 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 6d 61  ize() routine ma
8eb0: 79 20 62 65 20 63 61 6c 6c 65 64 20 6d 75 6c 74  y be called mult
8ec0: 69 70 6c 65 20 74 69 6d 65 73 0a 2a 2a 20 77 69  iple times.** wi
8ed0: 74 68 6f 75 74 20 63 6f 6e 73 65 71 75 65 6e 63  thout consequenc
8ee0: 65 2e 20 20 53 65 63 6f 6e 64 20 61 6e 64 20 73  e.  Second and s
8ef0: 75 62 73 65 71 75 65 6e 74 20 65 76 61 6c 75 61  ubsequent evalua
8f00: 74 69 6f 6e 73 20 6f 66 0a 2a 2a 20 73 71 6c 69  tions of.** sqli
8f10: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
8f20: 20 61 72 65 20 6e 6f 2d 6f 70 73 2e 20 20 54 68   are no-ops.  Th
8f30: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
8f40: 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 0a 2a  lize() routine.*
8f50: 2a 20 6f 6e 6c 79 20 77 6f 72 6b 73 20 74 68 65  * only works the
8f60: 20 66 69 72 73 74 20 74 69 6d 65 20 69 74 20 69   first time it i
8f70: 73 20 63 61 6c 6c 65 64 20 66 6f 72 20 61 20 70  s called for a p
8f80: 72 6f 63 65 73 73 2c 20 6f 72 20 74 68 65 20 66  rocess, or the f
8f90: 69 72 73 74 0a 2a 2a 20 74 69 6d 65 20 69 74 20  irst.** time it 
8fa0: 69 73 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20  is called after 
8fb0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
8fc0: 28 29 2e 20 20 49 6e 20 61 6c 6c 20 6f 74 68 65  ().  In all othe
8fd0: 72 20 63 61 73 65 73 2c 0a 2a 2a 20 73 71 6c 69  r cases,.** sqli
8fe0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
8ff0: 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f   returns SQLITE_
9000: 4f 4b 20 77 69 74 68 6f 75 74 20 64 6f 69 6e 67  OK without doing
9010: 20 61 6e 79 20 72 65 61 6c 20 77 6f 72 6b 2e 0a   any real work..
9020: 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65  **.** Among othe
9030: 72 20 74 68 69 6e 67 73 2c 20 73 71 6c 69 74 65  r things, sqlite
9040: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 73  3_initialize() s
9050: 68 61 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 5b  hall invoke.** [
9060: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 69 6e  sqlite3_mutex_in
9070: 69 74 28 29 5d 20 61 6e 64 20 73 71 6c 69 74 65  it()] and sqlite
9080: 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69  3_os_init().  Si
9090: 6d 69 6c 61 72 6c 79 2c 20 73 71 6c 69 74 65 33  milarly, sqlite3
90a0: 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 73  _shutdown().** s
90b0: 68 61 6c 6c 20 69 6e 76 6f 6b 65 20 5b 73 71 6c  hall invoke [sql
90c0: 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 64 28 29  ite3_mutex_end()
90d0: 5d 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73  ] and sqlite3_os
90e0: 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  _end()..**.** Th
90f0: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
9100: 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72  lize() routine r
9110: 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b  eturns SQLITE_OK
9120: 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20   on success..** 
9130: 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73  If for some reas
9140: 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  on, sqlite3_init
9150: 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e 61 62  ialize() is unab
9160: 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65  le to initialize
9170: 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72 79 20  .** the library 
9180: 28 70 65 72 68 61 70 73 20 69 74 20 69 73 20 75  (perhaps it is u
9190: 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74  nable to allocat
91a0: 65 20 61 20 6e 65 65 64 65 64 20 72 65 73 6f 75  e a needed resou
91b0: 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73 20 61  rce such.** as a
91c0: 20 6d 75 74 65 78 29 20 69 74 20 72 65 74 75 72   mutex) it retur
91d0: 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64  ns an [error cod
91e0: 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 53 51  e] other than SQ
91f0: 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a 0a 2a 2a 20 54  LITE_OK..**.** T
9200: 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  he sqlite3_initi
9210: 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20  alize() routine 
9220: 69 73 20 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e  is called intern
9230: 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74 68  ally by many oth
9240: 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74  er.** SQLite int
9250: 65 72 66 61 63 65 73 20 73 6f 20 74 68 61 74 20  erfaces so that 
9260: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75  an application u
9270: 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20  sually does not 
9280: 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b  need to.** invok
9290: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
92a0: 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 2e  lize() directly.
92b0: 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b    For example, [
92c0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a  sqlite3_open()].
92d0: 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33  ** calls sqlite3
92e0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 6f  _initialize() so
92f0: 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
9300: 61 72 79 20 77 69 6c 6c 20 62 65 20 61 75 74 6f  ary will be auto
9310: 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69  matically.** ini
9320: 74 69 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73  tialized when [s
9330: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69  qlite3_open()] i
9340: 73 20 63 61 6c 6c 65 64 20 69 66 20 69 74 20 68  s called if it h
9350: 61 73 20 6e 6f 74 20 62 65 20 69 6e 69 74 69 61  as not be initia
9360: 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79  lized.** already
9370: 2e 20 20 48 6f 77 65 76 65 72 2c 20 69 66 20 53  .  However, if S
9380: 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
9390: 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54  d with the SQLIT
93a0: 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 0a  E_OMIT_AUTOINIT.
93b0: 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  ** compile-time 
93c0: 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65  option, then the
93d0: 20 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73   automatic calls
93e0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   to sqlite3_init
93f0: 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20  ialize().** are 
9400: 6f 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65 20  omitted and the 
9410: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
9420: 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e   call sqlite3_in
9430: 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63  itialize() direc
9440: 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20  tly.** prior to 
9450: 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20  using any other 
9460: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
9470: 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70  .  For maximum p
9480: 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69  ortability,.** i
9490: 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  t is recommended
94a0: 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f   that applicatio
94b0: 6e 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65  ns always invoke
94c0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
94d0: 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c  ize().** directl
94e0: 79 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67  y prior to using
94f0: 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74   any other SQLit
9500: 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75  e interface.  Fu
9510: 74 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a  ture releases.**
9520: 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72   of SQLite may r
9530: 65 71 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e  equire this.  In
9540: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
9550: 65 20 62 65 68 61 76 69 6f 72 20 65 78 68 69 62  e behavior exhib
9560: 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c  ited.** when SQL
9570: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
9580: 77 69 74 68 20 53 51 4c 49 54 45 5f 4f 4d 49 54  with SQLITE_OMIT
9590: 5f 41 55 54 4f 49 4e 49 54 20 6d 69 67 68 74 20  _AUTOINIT might 
95a0: 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65  become the.** de
95b0: 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69  fault behavior i
95c0: 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65  n some future re
95d0: 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e  lease of SQLite.
95e0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
95f0: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75  e3_os_init() rou
9600: 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 61 74  tine does operat
9610: 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69  ing-system speci
9620: 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a  fic.** initializ
9630: 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c  ation of the SQL
9640: 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68  ite library.  Th
9650: 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  e sqlite3_os_end
9660: 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e  ().** routine un
9670: 64 6f 65 73 20 74 68 65 20 65 66 66 65 63 74 20  does the effect 
9680: 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  of sqlite3_os_in
9690: 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c 20 74  it().  Typical t
96a0: 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65  asks.** performe
96b0: 64 20 62 79 20 74 68 65 73 65 20 72 6f 75 74 69  d by these routi
96c0: 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f  nes include allo
96d0: 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f  cation or deallo
96e0: 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61  cation.** of sta
96f0: 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c 20 69  tic resources, i
9700: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66  nitialization of
9710: 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65   global variable
9720: 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75 70  s,.** setting up
9730: 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69   a default [sqli
9740: 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c  te3_vfs] module,
9750: 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70 0a 2a   or setting up.*
9760: 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  * a default conf
9770: 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e 67 20  iguration using 
9780: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
9790: 29 5d 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20  )].  .**.** The 
97a0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
97b0: 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20  ld never invoke 
97c0: 65 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f  either sqlite3_o
97d0: 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73  s_init().** or s
97e0: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20  qlite3_os_end() 
97f0: 64 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61  directly.  The a
9800: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
9810: 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a  d only invoke.**
9820: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
9830: 69 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ize() and sqlite
9840: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54  3_shutdown().  T
9850: 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  he sqlite3_os_in
9860: 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  it().** interfac
9870: 65 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f  e is called auto
9880: 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c  matically by sql
9890: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
98a0: 29 20 61 6e 64 20 0a 2a 2a 20 73 71 6c 69 74 65  ) and .** sqlite
98b0: 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61  3_os_end() is ca
98c0: 6c 6c 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  lled by sqlite3_
98d0: 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70  shutdown().  App
98e0: 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c  ropriate.** impl
98f0: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20  ementations for 
9900: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
9910: 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73  ) and sqlite3_os
9920: 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75  _end().** are bu
9930: 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20  ilt into SQLite 
9940: 77 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69  when it is compi
9950: 6c 65 64 20 66 6f 72 20 75 6e 69 78 2c 20 77 69  led for unix, wi
9960: 6e 64 6f 77 73 2c 20 6f 72 20 6f 73 2f 32 2e 0a  ndows, or os/2..
9970: 2a 2a 20 57 68 65 6e 20 62 75 69 6c 74 20 66 6f  ** When built fo
9980: 72 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d  r other platform
9990: 73 20 28 75 73 69 6e 67 20 74 68 65 20 53 51 4c  s (using the SQL
99a0: 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d 31 20 63  ITE_OS_OTHER=1 c
99b0: 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f  ompile-time.** o
99c0: 70 74 69 6f 6e 29 20 74 68 65 20 61 70 70 6c 69  ption) the appli
99d0: 63 61 74 69 6f 6e 20 6d 75 73 74 20 73 75 70 70  cation must supp
99e0: 6c 79 20 61 20 73 75 69 74 61 62 6c 65 20 69 6d  ly a suitable im
99f0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72  plementation for
9a00: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  .** sqlite3_os_i
9a10: 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65  nit() and sqlite
9a20: 33 5f 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20  3_os_end().  An 
9a30: 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70  application-supp
9a40: 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  lied.** implemen
9a50: 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65  tation of sqlite
9a60: 33 5f 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20 73  3_os_init() or s
9a70: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a  qlite3_os_end().
9a80: 2a 2a 20 6d 75 73 74 20 72 65 74 75 72 6e 20 53  ** must return S
9a90: 51 4c 49 54 45 5f 4f 4b 20 6f 6e 20 73 75 63 63  QLITE_OK on succ
9aa0: 65 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68  ess and some oth
9ab0: 65 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  er [error code] 
9ac0: 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e  upon.** failure.
9ad0: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
9ae0: 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64 29  initialize(void)
9af0: 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 68  ;.int sqlite3_sh
9b00: 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 69 6e  utdown(void);.in
9b10: 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  t sqlite3_os_ini
9b20: 74 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c  t(void);.int sql
9b30: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64  ite3_os_end(void
9b40: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
9b50: 45 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67 20  EF: Configuring 
9b60: 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61  The SQLite Libra
9b70: 72 79 20 7b 46 31 30 31 34 35 7d 0a 2a 2a 0a 2a  ry {F10145}.**.*
9b80: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  * The sqlite3_co
9b90: 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  nfig() interface
9ba0: 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65   is used to make
9bb0: 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72   global configur
9bc0: 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73  ation.** changes
9bd0: 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f 72   to SQLite in or
9be0: 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51 4c 69  der to tune SQLi
9bf0: 74 65 20 74 6f 20 74 68 65 20 73 70 65 63 69 66  te to the specif
9c00: 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74  ic needs of.** t
9c10: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20  he application. 
9c20: 20 54 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6e   The default con
9c30: 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20 72 65  figuration is re
9c40: 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f  commended for mo
9c50: 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f  st.** applicatio
9c60: 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73 20 72  ns and so this r
9c70: 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61 6c 6c  outine is usuall
9c80: 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 79 2e  y not necessary.
9c90: 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69    It is.** provi
9ca0: 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20 72  ded to support r
9cb0: 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  are applications
9cc0: 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20 6e 65   with unusual ne
9cd0: 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  eds..**.** The s
9ce0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
9cf0: 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74  interface is not
9d00: 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 68   threadsafe.  Th
9d10: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a  e application.**
9d20: 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74 68 61   must insure tha
9d30: 74 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69 74  t no other SQLit
9d40: 65 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  e interfaces are
9d50: 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68 65   invoked by othe
9d60: 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 68 69  r.** threads whi
9d70: 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  le sqlite3_confi
9d80: 67 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20  g() is running. 
9d90: 20 46 75 72 74 68 65 72 6d 6f 72 65 2c 20 73 71   Furthermore, sq
9da0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 0a 2a  lite3_config().*
9db0: 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e  * may only be in
9dc0: 76 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f 20 6c  voked prior to l
9dd0: 69 62 72 61 72 79 20 69 6e 69 74 69 61 6c 69 7a  ibrary initializ
9de0: 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b  ation using.** [
9df0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
9e00: 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 73  ze()] or after s
9e10: 68 75 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69  hutdown by [sqli
9e20: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e  te3_shutdown()].
9e30: 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65  .** Note, howeve
9e40: 72 2c 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f  r, that sqlite3_
9e50: 63 6f 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20  config() can be 
9e60: 63 61 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f  called as part o
9e70: 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65  f the.** impleme
9e80: 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70  ntation of an ap
9e90: 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
9ea0: 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  d [sqlite3_os_in
9eb0: 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  it()]..**.** The
9ec0: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
9ed0: 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  to sqlite3_confi
9ee0: 67 28 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65  g() is an intege
9ef0: 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  r.** [SQLITE_CON
9f00: 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
9f10: 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e   | configuration
9f20: 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 65   option] that de
9f30: 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74  termines.** what
9f40: 20 70 72 6f 70 65 72 74 79 20 6f 66 20 53 51 4c   property of SQL
9f50: 69 74 65 20 69 73 20 74 6f 20 62 65 20 63 6f 6e  ite is to be con
9f60: 66 69 67 75 72 65 64 2e 20 20 53 75 62 73 65 71  figured.  Subseq
9f70: 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a  uent arguments.*
9f80: 2a 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67  * vary depending
9f90: 20 6f 6e 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   on the [SQLITE_
9fa0: 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
9fb0: 45 41 44 20 7c 20 63 6f 6e 66 69 67 75 72 61 74  EAD | configurat
9fc0: 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69  ion option].** i
9fd0: 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
9fe0: 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  ment..**.** When
9ff0: 20 61 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e   a configuration
a000: 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 2c 20   option is set, 
a010: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
a020: 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f   returns SQLITE_
a030: 4f 4b 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70  OK..** If the op
a040: 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20  tion is unknown 
a050: 6f 72 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61  or SQLite is una
a060: 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 6f  ble to set the o
a070: 70 74 69 6f 6e 20 0a 2a 2a 20 74 68 65 6e 20 74  ption .** then t
a080: 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75  his routine retu
a090: 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b  rns a non-zero [
a0a0: 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a  error code]..*/.
a0b0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  int sqlite3_conf
a0c0: 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f  ig(int, ...);../
a0d0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
a0e0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74  onfiguration Opt
a0f0: 69 6f 6e 73 20 7b 46 31 30 31 36 30 7d 0a 2a 2a  ions {F10160}.**
a100: 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
a110: 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69  nts are the avai
a120: 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f  lable integer co
a130: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
a140: 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20  ons that.** can 
a150: 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  be passed as the
a160: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
a170: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
a180: 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66  config()] interf
a190: 61 63 65 2e 0a 2a 2a 20 0a 2a 2a 20 3c 64 6c 3e  ace..** .** <dl>
a1a0: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
a1b0: 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
a1c0: 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  AD</dt>.** <dd>T
a1d0: 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75  here are no argu
a1e0: 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70  ments to this op
a1f0: 74 69 6f 6e 2e 20 20 54 68 69 73 20 6f 70 74 69  tion.  This opti
a200: 6f 6e 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61  on disables.** a
a210: 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e 64 20  ll mutexing and 
a220: 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e 74 6f  puts SQLite into
a230: 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20 69 74   a mode where it
a240: 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65   can only be use
a250: 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c 65  d.** by a single
a260: 20 74 68 72 65 61 64 2e 3c 2f 64 64 3e 0a 2a 2a   thread.</dd>.**
a270: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
a280: 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
a290: 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
a2a0: 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d  ere are no argum
a2b0: 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74  ents to this opt
a2c0: 69 6f 6e 2e 20 20 54 68 69 73 20 6f 70 74 69 6f  ion.  This optio
a2d0: 6e 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75  n disables.** mu
a2e0: 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62  texing on [datab
a2f0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
a300: 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  and [prepared st
a310: 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73  atement] objects
a320: 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
a330: 74 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73 69  tion is responsi
a340: 62 6c 65 20 66 6f 72 20 73 65 72 69 61 6c 69 7a  ble for serializ
a350: 69 6e 67 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a  ing access to.**
a360: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
a370: 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65  ctions] and [pre
a380: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
a390: 5d 2e 20 20 42 75 74 20 6f 74 68 65 72 20 6d 75  ].  But other mu
a3a0: 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61  texes.** are ena
a3b0: 62 6c 65 64 20 73 6f 20 74 68 61 74 20 53 51 4c  bled so that SQL
a3c0: 69 74 65 20 77 69 6c 6c 20 62 65 20 73 61 66 65  ite will be safe
a3d0: 20 74 6f 20 75 73 65 20 69 6e 20 61 20 6d 75 6c   to use in a mul
a3e0: 74 69 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 65  ti-threaded.** e
a3f0: 6e 76 69 72 6f 6e 6d 65 6e 74 2e 3c 2f 64 64 3e  nvironment.</dd>
a400: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
a410: 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49  E_CONFIG_SERIALI
a420: 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ZED</dt>.** <dd>
a430: 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67  There are no arg
a440: 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f  uments to this o
a450: 70 74 69 6f 6e 2e 20 20 54 68 69 73 20 6f 70 74  ption.  This opt
a460: 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61  ion enables.** a
a470: 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e 63 6c 75  ll mutexes inclu
a480: 64 69 6e 67 20 74 68 65 20 72 65 63 75 72 73 69  ding the recursi
a490: 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e  ve.** mutexes on
a4a0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
a4b0: 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70  ction] and [prep
a4c0: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
a4d0: 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74  objects..** In t
a4e0: 68 69 73 20 6d 6f 64 65 20 28 77 68 69 63 68 20  his mode (which 
a4f0: 69 73 20 74 68 65 20 64 65 66 61 75 6c 74 20 77  is the default w
a500: 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f  hen SQLite is co
a510: 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53  mpiled with.** S
a520: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
a530: 3d 31 29 20 74 68 65 20 53 51 4c 69 74 65 20 6c  =1) the SQLite l
a540: 69 62 72 61 72 79 20 77 69 6c 6c 20 69 74 73 65  ibrary will itse
a550: 6c 66 20 73 65 72 69 61 6c 69 7a 65 20 61 63 63  lf serialize acc
a560: 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62  ess.** to [datab
a570: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d  ase connections]
a580: 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73   and [prepared s
a590: 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68  tatements] so th
a5a0: 61 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63  at the.** applic
a5b0: 61 74 69 6f 6e 20 69 73 20 66 72 65 65 20 74 6f  ation is free to
a5c0: 20 75 73 65 20 74 68 65 20 73 61 6d 65 20 5b 64   use the same [d
a5d0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
a5e0: 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61  on] or the.** sa
a5f0: 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  me [prepared sta
a600: 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66 65  tement] in diffe
a610: 72 65 6e 74 20 74 68 72 65 61 64 73 20 61 74 20  rent threads at 
a620: 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 3c 2f  the same time.</
a630: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
a640: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
a650: 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  OC</dt>.** <dd>T
a660: 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
a670: 20 66 69 76 65 20 61 72 67 75 6d 65 6e 74 73 2e   five arguments.
a680: 20 20 54 68 65 20 66 69 72 73 74 20 74 68 72 65    The first thre
a690: 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 61  e.** arguments a
a6a0: 72 65 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 66  re pointers to f
a6b0: 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 65 6d  unctions that em
a6c0: 75 6c 61 74 65 20 6d 61 6c 6c 6f 63 28 29 2c 20  ulate malloc(), 
a6d0: 66 72 65 65 28 29 2c 0a 2a 2a 20 61 6e 64 20 72  free(),.** and r
a6e0: 65 61 6c 6c 6f 63 28 29 2c 20 72 65 73 70 65 63  ealloc(), respec
a6f0: 74 69 76 65 6c 79 2e 20 20 54 68 65 20 66 6f 75  tively.  The fou
a700: 72 74 68 20 61 72 67 75 6d 65 6e 74 20 6d 75 73  rth argument mus
a710: 74 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74  t be a pointer t
a720: 6f 0a 2a 2a 20 61 20 66 75 6e 63 74 69 6f 6e 20  o.** a function 
a730: 74 68 61 74 20 72 65 74 75 72 6e 73 20 74 68 65  that returns the
a740: 20 73 69 7a 65 20 6f 66 20 61 20 70 72 69 6f 72   size of a prior
a750: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 77 68 65 6e   allocation when
a760: 20 68 61 6e 64 65 64 20 61 20 70 6f 69 6e 74 65   handed a pointe
a770: 72 0a 2a 2a 20 74 6f 20 74 68 65 20 61 6c 6c 6f  r.** to the allo
a780: 63 61 74 69 6f 6e 2e 20 54 68 65 20 66 69 66 74  cation. The fift
a790: 68 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  h argument is a 
a7a0: 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 66 75 6e  pointer to a fun
a7b0: 63 74 69 6f 6e 20 74 68 61 74 0a 2a 2a 20 72 65  ction that.** re
a7c0: 74 75 72 6e 73 20 74 68 65 20 72 6f 75 6e 64 65  turns the rounde
a7d0: 64 2d 75 70 20 73 69 7a 65 20 6f 66 20 61 20 6d  d-up size of a m
a7e0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
a7f0: 20 67 69 76 65 6e 20 74 68 65 20 72 65 71 75 65   given the reque
a800: 73 74 65 64 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69  sted.** allocati
a810: 6f 6e 20 73 69 7a 65 2e 20 20 54 68 69 73 20 6f  on size.  This o
a820: 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f  ption is used to
a830: 20 72 65 70 6c 61 63 65 20 74 68 65 20 64 65 66   replace the def
a840: 61 75 6c 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61  ault memory.** a
a850: 6c 6c 6f 63 61 74 6f 72 20 77 69 74 68 20 61 6e  llocator with an
a860: 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
a870: 69 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ined memory allo
a880: 63 61 74 6f 72 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  cator.</dd>.**.*
a890: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
a8a0: 46 49 47 5f 4d 45 4d 53 54 41 54 53 3c 2f 64 74  FIG_MEMSTATS</dt
a8b0: 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70  >.** <dd>This op
a8c0: 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c  tion takes singl
a8d0: 65 20 62 6f 6f 6c 65 61 6e 20 61 72 67 75 6d 65  e boolean argume
a8e0: 6e 74 20 77 68 69 63 68 20 65 6e 61 62 6c 65 73  nt which enables
a8f0: 20 6f 72 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20   or disables.** 
a900: 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f  the collection o
a910: 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  f memory allocat
a920: 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 2e 20  ion statistics. 
a930: 20 57 68 65 6e 20 64 69 73 61 62 6c 65 64 2c 20   When disabled, 
a940: 74 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67  the.** following
a950: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
a960: 65 73 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70  es become non-op
a970: 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20  erational:.**   
a980: 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b  <ul>.**   <li> [
a990: 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
a9a0: 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e  sed()].**   <li>
a9b0: 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
a9c0: 5f 68 69 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a  _highwater()].**
a9d0: 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33     <li> [sqlite3
a9e0: 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74  _soft_heap_limit
a9f0: 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 73 71  ()].**   <li> sq
aa00: 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 73 74 61  lite3_memory_sta
aa10: 74 75 73 28 29 0a 2a 2a 20 20 20 3c 2f 75 6c 3e  tus().**   </ul>
aa20: 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64  .** </dd>.** </d
aa30: 6c 3e 0a 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53  l>.*/ .#define S
aa40: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
aa50: 47 4c 45 54 48 52 45 41 44 20 20 31 20 20 2f 2a  GLETHREAD  1  /*
aa60: 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20   nil */.#define 
aa70: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
aa80: 4c 54 49 54 48 52 45 41 44 20 20 20 32 20 20 2f  LTITHREAD   2  /
aa90: 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65  * nil */.#define
aaa0: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
aab0: 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33 20 20  ERIALIZED    3  
aac0: 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e  /* nil */.#defin
aad0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
aae0: 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 34 20  MALLOC        4 
aaf0: 20 2f 2a 20 6d 61 6c 6c 6f 63 2c 66 72 65 65 2c   /* malloc,free,
ab00: 72 65 61 6c 6c 6f 63 2c 6d 65 6d 73 69 7a 65 2c  realloc,memsize,
ab10: 72 6f 75 6e 64 75 70 20 2a 2f 0a 23 64 65 66 69  roundup */.#defi
ab20: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
ab30: 5f 4d 45 4d 53 54 41 54 53 20 20 20 20 20 20 35  _MEMSTATS      5
ab40: 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a    /* boolean */.
ab50: 0a 2f 2a 20 54 68 65 73 65 20 6f 70 74 69 6f 6e  ./* These option
ab60: 73 20 61 72 65 20 74 6f 20 62 65 20 61 64 64 65  s are to be adde
ab70: 64 20 6c 61 74 65 72 2e 20 20 43 75 72 72 65 6e  d later.  Curren
ab80: 74 6c 79 20 75 6e 75 73 65 64 20 61 6e 64 20 75  tly unused and u
ab90: 6e 64 6f 63 75 6d 65 6e 74 65 64 2e 20 2a 2f 0a  ndocumented. */.
aba0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
abb0: 4f 4e 46 49 47 5f 48 45 41 50 20 20 20 20 20 20  ONFIG_HEAP      
abc0: 20 20 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c      6  /* void*,
abd0: 20 69 6e 74 36 34 2c 20 6d 69 6e 2c 20 6d 61 78   int64, min, max
abe0: 2c 20 74 6d 70 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a  , tmp */.../*.**
abf0: 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c   CAPI3REF: Enabl
ac00: 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74  e Or Disable Ext
ac10: 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64  ended Result Cod
ac20: 65 73 20 7b 46 31 32 32 30 30 7d 0a 2a 2a 0a 2a  es {F12200}.**.*
ac30: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78  * The sqlite3_ex
ac40: 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f  tended_result_co
ac50: 64 65 73 28 29 20 72 6f 75 74 69 6e 65 20 65 6e  des() routine en
ac60: 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65  ables or disable
ac70: 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  s the.** [SQLITE
ac80: 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 65 78  _IOERR_READ | ex
ac90: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
aca0: 64 65 73 5d 20 66 65 61 74 75 72 65 20 6f 66 20  des] feature of 
acb0: 53 51 4c 69 74 65 2e 0a 2a 2a 20 54 68 65 20 65  SQLite..** The e
acc0: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
acd0: 6f 64 65 73 20 61 72 65 20 64 69 73 61 62 6c 65  odes are disable
ace0: 64 20 62 79 20 64 65 66 61 75 6c 74 20 66 6f 72  d by default for
acf0: 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20 63   historical.** c
ad00: 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a  ompatibility..**
ad10: 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
ad20: 2a 2a 0a 2a 2a 20 7b 46 31 32 32 30 31 7d 20 45  **.** {F12201} E
ad30: 61 63 68 20 6e 65 77 20 5b 64 61 74 61 62 61 73  ach new [databas
ad40: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 68  e connection] sh
ad50: 61 6c 6c 20 68 61 76 65 20 74 68 65 20 0a 2a 2a  all have the .**
ad60: 20 20 20 20 20 20 20 20 20 20 5b 65 78 74 65 6e            [exten
ad70: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
ad80: 5d 20 66 65 61 74 75 72 65 0a 2a 2a 20 20 20 20  ] feature.**    
ad90: 20 20 20 20 20 20 64 69 73 61 62 6c 65 64 20 62        disabled b
ada0: 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a  y default..**.**
adb0: 20 7b 46 31 32 32 30 32 7d 20 54 68 65 20 5b 73   {F12202} The [s
adc0: 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
add0: 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 44 2c 46  result_codes(D,F
ade0: 29 5d 20 69 6e 74 65 72 66 61 63 65 20 73 68 61  )] interface sha
adf0: 6c 6c 20 65 6e 61 62 6c 65 0a 2a 2a 20 20 20 20  ll enable.**    
ae00: 20 20 20 20 20 20 5b 65 78 74 65 6e 64 65 64 20        [extended 
ae10: 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 6f  result codes] fo
ae20: 72 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 20 20  r the .**       
ae30: 20 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e     [database con
ae40: 6e 65 63 74 69 6f 6e 5d 20 44 20 69 66 20 74 68  nection] D if th
ae50: 65 20 46 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  e F parameter.**
ae60: 20 20 20 20 20 20 20 20 20 20 69 73 20 74 72 75            is tru
ae70: 65 2c 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68  e, or disable th
ae80: 65 6d 20 69 66 20 46 20 69 73 20 66 61 6c 73 65  em if F is false
ae90: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
aea0: 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74  _extended_result
aeb0: 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a 2c  _codes(sqlite3*,
aec0: 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a   int onoff);../*
aed0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 61  .** CAPI3REF: La
aee0: 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64 20  st Insert Rowid 
aef0: 7b 46 31 32 32 32 30 7d 0a 2a 2a 0a 2a 2a 20 45  {F12220}.**.** E
af00: 61 63 68 20 65 6e 74 72 79 20 69 6e 20 61 6e 20  ach entry in an 
af10: 53 51 4c 69 74 65 20 74 61 62 6c 65 20 68 61 73  SQLite table has
af20: 20 61 20 75 6e 69 71 75 65 20 36 34 2d 62 69 74   a unique 64-bit
af30: 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67   signed.** integ
af40: 65 72 20 6b 65 79 20 63 61 6c 6c 65 64 20 74 68  er key called th
af50: 65 20 22 72 6f 77 69 64 22 2e 20 54 68 65 20 72  e "rowid". The r
af60: 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73 20 61  owid is always a
af70: 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61  vailable.** as a
af80: 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c  n undeclared col
af90: 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c  umn named ROWID,
afa0: 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f   OID, or _ROWID_
afb0: 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73   as long as thos
afc0: 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e  e.** names are n
afd0: 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20  ot also used by 
afe0: 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61  explicitly decla
aff0: 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 49 66 0a  red columns. If.
b000: 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61 73  ** the table has
b010: 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70   a column of typ
b020: 65 20 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52  e INTEGER PRIMAR
b030: 59 20 4b 45 59 20 74 68 65 6e 20 74 68 61 74 20  Y KEY then that 
b040: 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f  column.** is ano
b050: 74 68 65 72 20 61 6c 69 61 73 20 66 6f 72 20 74  ther alias for t
b060: 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20  he rowid..**.** 
b070: 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  This routine ret
b080: 75 72 6e 73 20 74 68 65 20 72 6f 77 69 64 20 6f  urns the rowid o
b090: 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
b0a0: 74 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20  t.** successful 
b0b0: 49 4e 53 45 52 54 20 69 6e 74 6f 20 74 68 65 20  INSERT into the 
b0c0: 64 61 74 61 62 61 73 65 20 66 72 6f 6d 20 74 68  database from th
b0d0: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
b0e0: 63 74 69 6f 6e 0a 2a 2a 20 73 68 6f 77 6e 20 69  ction.** shown i
b0f0: 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
b100: 6d 65 6e 74 2e 20 20 49 66 20 6e 6f 20 73 75 63  ment.  If no suc
b110: 63 65 73 73 66 75 6c 20 69 6e 73 65 72 74 73 0a  cessful inserts.
b120: 2a 2a 20 68 61 76 65 20 65 76 65 72 20 6f 63 63  ** have ever occ
b130: 75 72 72 65 64 20 6f 6e 20 74 68 69 73 20 64 61  urred on this da
b140: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
b150: 6e 2c 20 7a 65 72 6f 20 69 73 20 72 65 74 75 72  n, zero is retur
b160: 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e  ned..**.** If an
b170: 20 49 4e 53 45 52 54 20 6f 63 63 75 72 73 20 77   INSERT occurs w
b180: 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 2c  ithin a trigger,
b190: 20 74 68 65 6e 20 74 68 65 20 72 6f 77 69 64 20   then the rowid 
b1a0: 6f 66 20 74 68 65 0a 2a 2a 20 69 6e 73 65 72 74  of the.** insert
b1b0: 65 64 20 72 6f 77 20 69 73 20 72 65 74 75 72 6e  ed row is return
b1c0: 65 64 20 62 79 20 74 68 69 73 20 72 6f 75 74 69  ed by this routi
b1d0: 6e 65 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  ne as long as th
b1e0: 65 20 74 72 69 67 67 65 72 0a 2a 2a 20 69 73 20  e trigger.** is 
b1f0: 72 75 6e 6e 69 6e 67 2e 20 20 42 75 74 20 6f 6e  running.  But on
b200: 63 65 20 74 68 65 20 74 72 69 67 67 65 72 20 74  ce the trigger t
b210: 65 72 6d 69 6e 61 74 65 73 2c 20 74 68 65 20 76  erminates, the v
b220: 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a  alue returned.**
b230: 20 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65   by this routine
b240: 20 72 65 76 65 72 74 73 20 74 6f 20 74 68 65 20   reverts to the 
b250: 6c 61 73 74 20 76 61 6c 75 65 20 69 6e 73 65 72  last value inser
b260: 74 65 64 20 62 65 66 6f 72 65 20 74 68 65 0a 2a  ted before the.*
b270: 2a 20 74 72 69 67 67 65 72 20 66 69 72 65 64 2e  * trigger fired.
b280: 0a 2a 2a 0a 2a 2a 20 41 6e 20 49 4e 53 45 52 54  .**.** An INSERT
b290: 20 74 68 61 74 20 66 61 69 6c 73 20 64 75 65 20   that fails due 
b2a0: 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20  to a constraint 
b2b0: 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74  violation is not
b2c0: 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c   a.** successful
b2d0: 20 69 6e 73 65 72 74 20 61 6e 64 20 64 6f 65 73   insert and does
b2e0: 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20   not change the 
b2f0: 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
b300: 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e  y this.** routin
b310: 65 2e 20 20 54 68 75 73 20 49 4e 53 45 52 54 20  e.  Thus INSERT 
b320: 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 54 20  OR FAIL, INSERT 
b330: 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52  OR IGNORE, INSER
b340: 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a  T OR ROLLBACK,.*
b350: 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f 52 20  * and INSERT OR 
b360: 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68  ABORT make no ch
b370: 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72 65 74  anges to the ret
b380: 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69  urn value of thi
b390: 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68 65  s.** routine whe
b3a0: 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74 69 6f  n their insertio
b3b0: 6e 20 66 61 69 6c 73 2e 20 20 57 68 65 6e 20 49  n fails.  When I
b3c0: 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45  NSERT OR REPLACE
b3d0: 20 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20   .** encounters 
b3e0: 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f  a constraint vio
b3f0: 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20  lation, it does 
b400: 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a  not fail.  The.*
b410: 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75  * INSERT continu
b420: 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e  es to completion
b430: 20 61 66 74 65 72 20 64 65 6c 65 74 69 6e 67 20   after deleting 
b440: 72 6f 77 73 20 74 68 61 74 20 63 61 75 73 65 64  rows that caused
b450: 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72 61 69  .** the constrai
b460: 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e  nt problem so IN
b470: 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 20  SERT OR REPLACE 
b480: 77 69 6c 6c 20 61 6c 77 61 79 73 20 63 68 61 6e  will always chan
b490: 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 6e  ge.** the return
b4a0: 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20 69   value of this i
b4b0: 6e 74 65 72 66 61 63 65 2e 20 0a 2a 2a 0a 2a 2a  nterface. .**.**
b4c0: 20 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65   For the purpose
b4d0: 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e  s of this routin
b4e0: 65 2c 20 61 6e 20 69 6e 73 65 72 74 20 69 73 20  e, an insert is 
b4f0: 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a  considered to.**
b500: 20 62 65 20 73 75 63 63 65 73 73 66 75 6c 20 65   be successful e
b510: 76 65 6e 20 69 66 20 69 74 20 69 73 20 73 75 62  ven if it is sub
b520: 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64  sequently rolled
b530: 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56   back..**.** INV
b540: 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
b550: 46 31 32 32 32 31 7d 20 54 68 65 20 5b 73 71 6c  F12221} The [sql
b560: 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
b570: 5f 72 6f 77 69 64 28 29 5d 20 66 75 6e 63 74 69  _rowid()] functi
b580: 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a  on returns the.*
b590: 2a 20 20 20 20 20 20 20 20 20 20 72 6f 77 69 64  *          rowid
b5a0: 20 6f 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63   of the most rec
b5b0: 65 6e 74 20 73 75 63 63 65 73 73 66 75 6c 20 69  ent successful i
b5c0: 6e 73 65 72 74 20 64 6f 6e 65 0a 2a 2a 20 20 20  nsert done.**   
b5d0: 20 20 20 20 20 20 20 6f 6e 20 74 68 65 20 73 61         on the sa
b5e0: 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
b5f0: 65 63 74 69 6f 6e 20 61 6e 64 20 77 69 74 68 69  ection and withi
b600: 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20  n the same.**   
b610: 20 20 20 20 20 20 20 6f 72 20 68 69 67 68 65 72         or higher
b620: 20 6c 65 76 65 6c 20 74 72 69 67 67 65 72 20 63   level trigger c
b630: 6f 6e 74 65 78 74 2c 20 6f 72 20 7a 65 72 6f 20  ontext, or zero 
b640: 69 66 20 74 68 65 72 65 20 68 61 76 65 0a 2a 2a  if there have.**
b650: 20 20 20 20 20 20 20 20 20 20 62 65 65 6e 20 6e            been n
b660: 6f 20 71 75 61 6c 69 66 79 69 6e 67 20 69 6e 73  o qualifying ins
b670: 65 72 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  erts..**.** {F12
b680: 32 32 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  223} The [sqlite
b690: 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
b6a0: 77 69 64 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20  wid()] function 
b6b0: 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20  returns.**      
b6c0: 20 20 20 20 73 61 6d 65 20 76 61 6c 75 65 20 77      same value w
b6d0: 68 65 6e 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20  hen called from 
b6e0: 74 68 65 20 73 61 6d 65 20 74 72 69 67 67 65 72  the same trigger
b6f0: 20 63 6f 6e 74 65 78 74 0a 2a 2a 20 20 20 20 20   context.**     
b700: 20 20 20 20 20 69 6d 6d 65 64 69 61 74 65 6c 79       immediately
b710: 20 62 65 66 6f 72 65 20 61 6e 64 20 61 66 74 65   before and afte
b720: 72 20 61 20 52 4f 4c 4c 42 41 43 4b 2e 0a 2a 2a  r a ROLLBACK..**
b730: 0a 2a 2a 20 4c 49 4d 49 54 41 54 49 4f 4e 53 3a  .** LIMITATIONS:
b740: 0a 2a 2a 0a 2a 2a 20 7b 55 31 32 32 33 32 7d 20  .**.** {U12232} 
b750: 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68  If a separate th
b760: 72 65 61 64 20 64 6f 65 73 20 61 20 6e 65 77 20  read does a new 
b770: 69 6e 73 65 72 74 20 6f 6e 20 74 68 65 20 73 61  insert on the sa
b780: 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64  me.**          d
b790: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
b7a0: 6f 6e 20 77 68 69 6c 65 20 74 68 65 20 5b 73 71  on while the [sq
b7b0: 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
b7c0: 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 20 20  t_rowid()].**   
b7d0: 20 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 20         function 
b7e0: 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74  is running and t
b7f0: 68 75 73 20 63 68 61 6e 67 65 73 20 74 68 65 20  hus changes the 
b800: 6c 61 73 74 20 69 6e 73 65 72 74 20 72 6f 77 69  last insert rowi
b810: 64 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  d,.**          t
b820: 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65  hen the value re
b830: 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
b840: 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  e3_last_insert_r
b850: 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20 20 20  owid()] is.**   
b860: 20 20 20 20 20 20 20 75 6e 70 72 65 64 69 63 74         unpredict
b870: 61 62 6c 65 20 61 6e 64 20 6d 69 67 68 74 20 6e  able and might n
b880: 6f 74 20 65 71 75 61 6c 20 65 69 74 68 65 72 20  ot equal either 
b890: 74 68 65 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e  the old or the n
b8a0: 65 77 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6c  ew.**          l
b8b0: 61 73 74 20 69 6e 73 65 72 74 20 72 6f 77 69 64  ast insert rowid
b8c0: 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74  ..*/.sqlite3_int
b8d0: 36 34 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  64 sqlite3_last_
b8e0: 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c  insert_rowid(sql
b8f0: 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
b900: 41 50 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 54  API3REF: Count T
b910: 68 65 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77  he Number Of Row
b920: 73 20 4d 6f 64 69 66 69 65 64 20 7b 46 31 32 32  s Modified {F122
b930: 34 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66  40}.**.** This f
b940: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
b950: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 61  the number of da
b960: 74 61 62 61 73 65 20 72 6f 77 73 20 74 68 61 74  tabase rows that
b970: 20 77 65 72 65 20 63 68 61 6e 67 65 64 0a 2a 2a   were changed.**
b980: 20 6f 72 20 69 6e 73 65 72 74 65 64 20 6f 72 20   or inserted or 
b990: 64 65 6c 65 74 65 64 20 62 79 20 74 68 65 20 6d  deleted by the m
b9a0: 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d  ost recently com
b9b0: 70 6c 65 74 65 64 20 53 51 4c 20 73 74 61 74 65  pleted SQL state
b9c0: 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 63  ment.** on the c
b9d0: 6f 6e 6e 65 63 74 69 6f 6e 20 73 70 65 63 69 66  onnection specif
b9e0: 69 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  ied by the first
b9f0: 20 70 61 72 61 6d 65 74 65 72 2e 20 20 4f 6e 6c   parameter.  Onl
ba00: 79 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 68 61  y.** changes tha
ba10: 74 20 61 72 65 20 64 69 72 65 63 74 6c 79 20 73  t are directly s
ba20: 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
ba30: 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20  INSERT, UPDATE, 
ba40: 6f 72 0a 2a 2a 20 44 45 4c 45 54 45 20 73 74 61  or.** DELETE sta
ba50: 74 65 6d 65 6e 74 20 61 72 65 20 63 6f 75 6e 74  tement are count
ba60: 65 64 2e 20 20 41 75 78 69 6c 69 61 72 79 20 63  ed.  Auxiliary c
ba70: 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79  hanges caused by
ba80: 0a 2a 2a 20 74 72 69 67 67 65 72 73 20 61 72 65  .** triggers are
ba90: 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20 55 73   not counted. Us
baa0: 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74  e the [sqlite3_t
bab0: 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20  otal_changes()] 
bac0: 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 6f 20 66  function.** to f
bad0: 69 6e 64 20 74 68 65 20 74 6f 74 61 6c 20 6e 75  ind the total nu
bae0: 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73 20  mber of changes 
baf0: 69 6e 63 6c 75 64 69 6e 67 20 63 68 61 6e 67 65  including change
bb00: 73 20 63 61 75 73 65 64 20 62 79 20 74 72 69 67  s caused by trig
bb10: 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 22 72  gers..**.** A "r
bb20: 6f 77 20 63 68 61 6e 67 65 22 20 69 73 20 61 20  ow change" is a 
bb30: 63 68 61 6e 67 65 20 74 6f 20 61 20 73 69 6e 67  change to a sing
bb40: 6c 65 20 72 6f 77 20 6f 66 20 61 20 73 69 6e 67  le row of a sing
bb50: 6c 65 20 74 61 62 6c 65 0a 2a 2a 20 63 61 75 73  le table.** caus
bb60: 65 64 20 62 79 20 61 6e 20 49 4e 53 45 52 54 2c  ed by an INSERT,
bb70: 20 44 45 4c 45 54 45 2c 20 6f 72 20 55 50 44 41   DELETE, or UPDA
bb80: 54 45 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 52  TE statement.  R
bb90: 6f 77 73 20 74 68 61 74 0a 2a 2a 20 61 72 65 20  ows that.** are 
bba0: 63 68 61 6e 67 65 64 20 61 73 20 73 69 64 65 20  changed as side 
bbb0: 65 66 66 65 63 74 73 20 6f 66 20 52 45 50 4c 41  effects of REPLA
bbc0: 43 45 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65  CE constraint re
bbd0: 73 6f 6c 75 74 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c  solution,.** rol
bbe0: 6c 62 61 63 6b 2c 20 41 42 4f 52 54 20 70 72 6f  lback, ABORT pro
bbf0: 63 65 73 73 69 6e 67 2c 20 44 52 4f 50 20 54 41  cessing, DROP TA
bc00: 42 4c 45 2c 20 6f 72 20 62 79 20 61 6e 79 20 6f  BLE, or by any o
bc10: 74 68 65 72 0a 2a 2a 20 6d 65 63 68 61 6e 69 73  ther.** mechanis
bc20: 6d 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20  ms do not count 
bc30: 61 73 20 64 69 72 65 63 74 20 72 6f 77 20 63 68  as direct row ch
bc40: 61 6e 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 22  anges..**.** A "
bc50: 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 22  trigger context"
bc60: 20 69 73 20 61 20 73 63 6f 70 65 20 6f 66 20 65   is a scope of e
bc70: 78 65 63 75 74 69 6f 6e 20 74 68 61 74 20 62 65  xecution that be
bc80: 67 69 6e 73 20 61 6e 64 0a 2a 2a 20 65 6e 64 73  gins and.** ends
bc90: 20 77 69 74 68 20 74 68 65 20 73 63 72 69 70 74   with the script
bca0: 20 6f 66 20 61 20 74 72 69 67 67 65 72 2e 20 20   of a trigger.  
bcb0: 4d 6f 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65  Most SQL stateme
bcc0: 6e 74 73 20 61 72 65 0a 2a 2a 20 65 76 61 6c 75  nts are.** evalu
bcd0: 61 74 65 64 20 6f 75 74 73 69 64 65 20 6f 66 20  ated outside of 
bce0: 61 6e 79 20 74 72 69 67 67 65 72 2e 20 20 54 68  any trigger.  Th
bcf0: 69 73 20 69 73 20 74 68 65 20 22 74 6f 70 20 6c  is is the "top l
bd00: 65 76 65 6c 22 0a 2a 2a 20 74 72 69 67 67 65 72  evel".** trigger
bd10: 20 63 6f 6e 74 65 78 74 2e 20 20 49 66 20 61 20   context.  If a 
bd20: 74 72 69 67 67 65 72 20 66 69 72 65 73 20 66 72  trigger fires fr
bd30: 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c  om the top level
bd40: 2c 20 61 0a 2a 2a 20 6e 65 77 20 74 72 69 67 67  , a.** new trigg
bd50: 65 72 20 63 6f 6e 74 65 78 74 20 69 73 20 65 6e  er context is en
bd60: 74 65 72 65 64 20 66 6f 72 20 74 68 65 20 64 75  tered for the du
bd70: 72 61 74 69 6f 6e 20 6f 66 20 74 68 61 74 20 6f  ration of that o
bd80: 6e 65 0a 2a 2a 20 74 72 69 67 67 65 72 2e 20 20  ne.** trigger.  
bd90: 53 75 62 74 72 69 67 67 65 72 73 20 63 72 65 61  Subtriggers crea
bda0: 74 65 20 73 75 62 63 6f 6e 74 65 78 74 73 20 66  te subcontexts f
bdb0: 6f 72 20 74 68 65 69 72 20 64 75 72 61 74 69 6f  or their duratio
bdc0: 6e 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67  n..**.** Calling
bdd0: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
bde0: 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 74  ] or [sqlite3_st
bdf0: 65 70 28 29 5d 20 72 65 63 75 72 73 69 76 65 6c  ep()] recursivel
be00: 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 63 72  y does.** not cr
be10: 65 61 74 65 20 61 20 6e 65 77 20 74 72 69 67 67  eate a new trigg
be20: 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a  er context..**.*
be30: 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  * This function 
be40: 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
be50: 65 72 20 6f 66 20 64 69 72 65 63 74 20 72 6f 77  er of direct row
be60: 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 0a   changes in the.
be70: 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49  ** most recent I
be80: 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f  NSERT, UPDATE, o
be90: 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65  r DELETE stateme
bea0: 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 73 61  nt within the sa
beb0: 6d 65 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 6f  me.** trigger co
bec0: 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 53 6f 20  ntext..**.** So 
bed0: 77 68 65 6e 20 63 61 6c 6c 65 64 20 66 72 6f 6d  when called from
bee0: 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20   the top level, 
bef0: 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65  this function re
bf00: 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 6e 75 6d  turns the.** num
bf10: 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73 20 69  ber of changes i
bf20: 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  n the most recen
bf30: 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  t INSERT, UPDATE
bf40: 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74  , or DELETE.** t
bf50: 68 61 74 20 61 6c 73 6f 20 6f 63 63 75 72 72 65  hat also occurre
bf60: 64 20 61 74 20 74 68 65 20 74 6f 70 20 6c 65 76  d at the top lev
bf70: 65 6c 2e 0a 2a 2a 20 57 69 74 68 69 6e 20 74 68  el..** Within th
bf80: 65 20 62 6f 64 79 20 6f 66 20 61 20 74 72 69 67  e body of a trig
bf90: 67 65 72 2c 20 74 68 65 20 73 71 6c 69 74 65 33  ger, the sqlite3
bfa0: 5f 63 68 61 6e 67 65 73 28 29 20 69 6e 74 65 72  _changes() inter
bfb0: 66 61 63 65 0a 2a 2a 20 63 61 6e 20 62 65 20 63  face.** can be c
bfc0: 61 6c 6c 65 64 20 74 6f 20 66 69 6e 64 20 74 68  alled to find th
bfd0: 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63  e number of.** c
bfe0: 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f  hanges in the mo
bff0: 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70  st recently comp
c000: 6c 65 74 65 64 20 49 4e 53 45 52 54 2c 20 55 50  leted INSERT, UP
c010: 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a  DATE, or DELETE.
c020: 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74  ** statement wit
c030: 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20  hin the body of 
c040: 74 68 65 20 73 61 6d 65 20 74 72 69 67 67 65 72  the same trigger
c050: 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68  ..** However, th
c060: 65 20 6e 75 6d 62 65 72 20 72 65 74 75 72 6e 65  e number returne
c070: 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75  d does not inclu
c080: 64 65 20 69 6e 20 63 68 61 6e 67 65 73 0a 2a 2a  de in changes.**
c090: 20 63 61 75 73 65 64 20 62 79 20 73 75 62 74 72   caused by subtr
c0a0: 69 67 67 65 72 73 20 73 69 6e 63 65 20 74 68 65  iggers since the
c0b0: 79 20 68 61 76 65 20 74 68 65 69 72 20 6f 77 6e  y have their own
c0c0: 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20   context..**.** 
c0d0: 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74  SQLite implement
c0e0: 73 20 74 68 65 20 63 6f 6d 6d 61 6e 64 20 22 44  s the command "D
c0f0: 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65  ELETE FROM table
c100: 22 20 77 69 74 68 6f 75 74 0a 2a 2a 20 61 20 57  " without.** a W
c110: 48 45 52 45 20 63 6c 61 75 73 65 20 62 79 20 64  HERE clause by d
c120: 72 6f 70 70 69 6e 67 20 61 6e 64 20 72 65 63 72  ropping and recr
c130: 65 61 74 69 6e 67 20 74 68 65 20 74 61 62 6c 65  eating the table
c140: 2e 20 20 28 54 68 69 73 20 69 73 20 6d 75 63 68  .  (This is much
c150: 0a 2a 2a 20 66 61 73 74 65 72 20 74 68 61 6e 20  .** faster than 
c160: 67 6f 69 6e 67 20 74 68 72 6f 75 67 68 20 61 6e  going through an
c170: 64 20 64 65 6c 65 74 69 6e 67 20 69 6e 64 69 76  d deleting indiv
c180: 69 64 75 61 6c 20 65 6c 65 6d 65 6e 74 73 20 66  idual elements f
c190: 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 61 62 6c 65  rom the.** table
c1a0: 2e 29 20 20 42 65 63 61 75 73 65 20 6f 66 20 74  .)  Because of t
c1b0: 68 69 73 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  his optimization
c1c0: 2c 20 74 68 65 20 64 65 6c 65 74 69 6f 6e 73 20  , the deletions 
c1d0: 69 6e 0a 2a 2a 20 22 44 45 4c 45 54 45 20 46 52  in.** "DELETE FR
c1e0: 4f 4d 20 74 61 62 6c 65 22 20 61 72 65 20 6e 6f  OM table" are no
c1f0: 74 20 72 6f 77 20 63 68 61 6e 67 65 73 20 61 6e  t row changes an
c200: 64 20 77 69 6c 6c 20 6e 6f 74 20 62 65 20 63 6f  d will not be co
c210: 75 6e 74 65 64 0a 2a 2a 20 62 79 20 74 68 65 20  unted.** by the 
c220: 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
c230: 29 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 74 6f  ) or [sqlite3_to
c240: 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 66  tal_changes()] f
c250: 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 20 54 6f 20  unctions..** To 
c260: 67 65 74 20 61 6e 20 61 63 63 75 72 61 74 65 20  get an accurate 
c270: 63 6f 75 6e 74 20 6f 66 20 74 68 65 20 6e 75 6d  count of the num
c280: 62 65 72 20 6f 66 20 72 6f 77 73 20 64 65 6c 65  ber of rows dele
c290: 74 65 64 2c 20 75 73 65 0a 2a 2a 20 22 44 45 4c  ted, use.** "DEL
c2a0: 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 20 57  ETE FROM table W
c2b0: 48 45 52 45 20 31 22 20 69 6e 73 74 65 61 64 2e  HERE 1" instead.
c2c0: 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
c2d0: 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 34 31  S:.**.** {F12241
c2e0: 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
c2f0: 68 61 6e 67 65 73 28 29 5d 20 66 75 6e 63 74 69  hanges()] functi
c300: 6f 6e 20 73 68 61 6c 6c 20 72 65 74 75 72 6e 20  on shall return 
c310: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
c320: 20 20 20 20 20 20 20 20 20 20 72 6f 77 20 63 68            row ch
c330: 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20  anges caused by 
c340: 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
c350: 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 0a  INSERT, UPDATE,.
c360: 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 44  **          or D
c370: 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20  ELETE statement 
c380: 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  on the same data
c390: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
c3a0: 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  and.**          
c3b0: 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20  within the same 
c3c0: 6f 72 20 68 69 67 68 65 72 20 74 72 69 67 67 65  or higher trigge
c3d0: 72 20 63 6f 6e 74 65 78 74 2c 20 6f 72 20 7a 65  r context, or ze
c3e0: 72 6f 20 69 66 20 74 68 65 72 65 20 68 61 76 65  ro if there have
c3f0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 6f 74  .**          not
c400: 20 62 65 65 6e 20 61 6e 79 20 71 75 61 6c 69 66   been any qualif
c410: 79 69 6e 67 20 72 6f 77 20 63 68 61 6e 67 65 73  ying row changes
c420: 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 34 33 7d  ..**.** {F12243}
c430: 20 53 74 61 74 65 6d 65 6e 74 73 20 6f 66 20 74   Statements of t
c440: 68 65 20 66 6f 72 6d 20 22 44 45 4c 45 54 45 20  he form "DELETE 
c450: 46 52 4f 4d 20 74 61 62 6c 65 6e 61 6d 65 22 20  FROM tablename" 
c460: 77 69 74 68 20 6e 6f 0a 2a 2a 20 20 20 20 20 20  with no.**      
c470: 20 20 20 20 57 48 45 52 45 20 63 6c 61 75 73 65      WHERE clause
c480: 20 73 68 61 6c 6c 20 63 61 75 73 65 20 73 75 62   shall cause sub
c490: 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
c4a0: 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73   .**          [s
c4b0: 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
c4c0: 5d 20 74 6f 20 72 65 74 75 72 6e 20 7a 65 72 6f  ] to return zero
c4d0: 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20  , regardless of 
c4e0: 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
c4f0: 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 6f  number of rows o
c500: 72 69 67 69 6e 61 6c 6c 79 20 69 6e 20 74 68 65  riginally in the
c510: 20 74 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4c 49   table..**.** LI
c520: 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a  MITATIONS:.**.**
c530: 20 7b 55 31 32 32 35 32 7d 20 49 66 20 61 20 73   {U12252} If a s
c540: 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d  eparate thread m
c550: 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20  akes changes on 
c560: 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
c570: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
c580: 20 20 20 20 20 20 20 20 20 77 68 69 6c 65 20 5b           while [
c590: 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
c5a0: 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68  )] is running th
c5b0: 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  en the value ret
c5c0: 75 72 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  urned.**        
c5d0: 20 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 62    is unpredictab
c5e0: 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69  le and not meani
c5f0: 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ngful..*/.int sq
c600: 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 73 71  lite3_changes(sq
c610: 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
c620: 43 41 50 49 33 52 45 46 3a 20 54 6f 74 61 6c 20  CAPI3REF: Total 
c630: 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d  Number Of Rows M
c640: 6f 64 69 66 69 65 64 20 7b 46 31 32 32 36 30 7d  odified {F12260}
c650: 0a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e  .***.** This fun
c660: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
c670: 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 20  e number of row 
c680: 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 0a 2a  changes caused.*
c690: 2a 20 62 79 20 49 4e 53 45 52 54 2c 20 55 50 44  * by INSERT, UPD
c6a0: 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74  ATE or DELETE st
c6b0: 61 74 65 6d 65 6e 74 73 20 73 69 6e 63 65 20 74  atements since t
c6c0: 68 65 20 64 61 74 61 62 61 73 65 20 68 61 6e 64  he database hand
c6d0: 6c 65 0a 2a 2a 20 77 61 73 20 6f 70 65 6e 65 64  le.** was opened
c6e0: 2e 20 20 54 68 65 20 63 6f 75 6e 74 20 69 6e 63  .  The count inc
c6f0: 6c 75 64 65 73 20 61 6c 6c 20 63 68 61 6e 67 65  ludes all change
c700: 73 20 66 72 6f 6d 20 61 6c 6c 20 74 72 69 67 67  s from all trigg
c710: 65 72 0a 2a 2a 20 63 6f 6e 74 65 78 74 73 2e 20  er.** contexts. 
c720: 20 42 75 74 20 74 68 65 20 63 6f 75 6e 74 20 64   But the count d
c730: 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20  oes not include 
c740: 63 68 61 6e 67 65 73 20 75 73 65 64 20 74 6f 0a  changes used to.
c750: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 52 45 50  ** implement REP
c760: 4c 41 43 45 20 63 6f 6e 73 74 72 61 69 6e 74 73  LACE constraints
c770: 2c 20 64 6f 20 72 6f 6c 6c 62 61 63 6b 73 20 6f  , do rollbacks o
c780: 72 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69  r ABORT processi
c790: 6e 67 2c 0a 2a 2a 20 6f 72 20 44 52 4f 50 20 74  ng,.** or DROP t
c7a0: 61 62 6c 65 20 70 72 6f 63 65 73 73 69 6e 67 2e  able processing.
c7b0: 0a 2a 2a 20 54 68 65 20 63 68 61 6e 67 65 73 0a  .** The changes.
c7c0: 2a 2a 20 61 72 65 20 63 6f 75 6e 74 65 64 20 61  ** are counted a
c7d0: 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 73 74  s soon as the st
c7e0: 61 74 65 6d 65 6e 74 20 74 68 61 74 20 6d 61 6b  atement that mak
c7f0: 65 73 20 74 68 65 6d 20 69 73 20 63 6f 6d 70 6c  es them is compl
c800: 65 74 65 64 20 0a 2a 2a 20 28 77 68 65 6e 20 74  eted .** (when t
c810: 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 6e  he statement han
c820: 64 6c 65 20 69 73 20 70 61 73 73 65 64 20 74 6f  dle is passed to
c830: 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
c840: 29 5d 20 6f 72 20 0a 2a 2a 20 5b 73 71 6c 69 74  )] or .** [sqlit
c850: 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 29 2e  e3_finalize()]).
c860: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6d  .**.** SQLite im
c870: 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 63 6f 6d  plements the com
c880: 6d 61 6e 64 20 22 44 45 4c 45 54 45 20 46 52 4f  mand "DELETE FRO
c890: 4d 20 74 61 62 6c 65 22 20 77 69 74 68 6f 75 74  M table" without
c8a0: 0a 2a 2a 20 61 20 57 48 45 52 45 20 63 6c 61 75  .** a WHERE clau
c8b0: 73 65 20 62 79 20 64 72 6f 70 70 69 6e 67 20 61  se by dropping a
c8c0: 6e 64 20 72 65 63 72 65 61 74 69 6e 67 20 74 68  nd recreating th
c8d0: 65 20 74 61 62 6c 65 2e 20 20 28 54 68 69 73 20  e table.  (This 
c8e0: 69 73 20 6d 75 63 68 0a 2a 2a 20 66 61 73 74 65  is much.** faste
c8f0: 72 20 74 68 61 6e 20 67 6f 69 6e 67 0a 2a 2a 20  r than going.** 
c900: 74 68 72 6f 75 67 68 20 61 6e 64 20 64 65 6c 65  through and dele
c910: 74 69 6e 67 20 69 6e 64 69 76 69 64 75 61 6c 20  ting individual 
c920: 65 6c 65 6d 65 6e 74 73 20 66 72 6f 6d 20 74 68  elements from th
c930: 65 20 74 61 62 6c 65 2e 29 20 20 42 65 63 61 75  e table.)  Becau
c940: 73 65 20 6f 66 0a 2a 2a 20 74 68 69 73 20 6f 70  se of.** this op
c950: 74 69 6d 69 7a 61 74 69 6f 6e 2c 20 74 68 65 20  timization, the 
c960: 63 68 61 6e 67 65 20 63 6f 75 6e 74 20 66 6f 72  change count for
c970: 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61   "DELETE FROM ta
c980: 62 6c 65 22 20 77 69 6c 6c 20 62 65 0a 2a 2a 20  ble" will be.** 
c990: 7a 65 72 6f 20 72 65 67 61 72 64 6c 65 73 73 20  zero regardless 
c9a0: 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  of the number of
c9b0: 20 65 6c 65 6d 65 6e 74 73 20 74 68 61 74 20 77   elements that w
c9c0: 65 72 65 20 6f 72 69 67 69 6e 61 6c 6c 79 20 69  ere originally i
c9d0: 6e 20 74 68 65 0a 2a 2a 20 74 61 62 6c 65 2e 20  n the.** table. 
c9e0: 54 6f 20 67 65 74 20 61 6e 20 61 63 63 75 72 61  To get an accura
c9f0: 74 65 20 63 6f 75 6e 74 20 6f 66 20 74 68 65 20  te count of the 
ca00: 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 64  number of rows d
ca10: 65 6c 65 74 65 64 2c 20 75 73 65 0a 2a 2a 20 22  eleted, use.** "
ca20: 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c  DELETE FROM tabl
ca30: 65 20 57 48 45 52 45 20 31 22 20 69 6e 73 74 65  e WHERE 1" inste
ca40: 61 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ad..**.** See al
ca50: 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  so the [sqlite3_
ca60: 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72  changes()] inter
ca70: 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  face..**.** INVA
ca80: 52 49 41 4e 54 53 3a 0a 2a 2a 20 0a 2a 2a 20 7b  RIANTS:.** .** {
ca90: 46 31 32 32 36 31 7d 20 54 68 65 20 5b 73 71 6c  F12261} The [sql
caa0: 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
cab0: 65 73 28 29 5d 20 72 65 74 75 72 6e 73 20 74 68  es()] returns th
cac0: 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 0a 2a  e total number.*
cad0: 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 72 6f  *          of ro
cae0: 77 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64  w changes caused
caf0: 20 62 79 20 49 4e 53 45 52 54 2c 20 55 50 44 41   by INSERT, UPDA
cb00: 54 45 2c 20 61 6e 64 2f 6f 72 20 44 45 4c 45 54  TE, and/or DELET
cb10: 45 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74  E.**          st
cb20: 61 74 65 6d 65 6e 74 73 20 6f 6e 20 74 68 65 20  atements on the 
cb30: 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63  same [database c
cb40: 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 69 6e 20 61  onnection], in a
cb50: 6e 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  ny.**          t
cb60: 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2c 20  rigger context, 
cb70: 73 69 6e 63 65 20 74 68 65 20 64 61 74 61 62 61  since the databa
cb80: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 61  se connection wa
cb90: 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 72  s.**          cr
cba0: 65 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  eated..**.** {F1
cbb0: 32 32 36 33 7d 20 53 74 61 74 65 6d 65 6e 74 73  2263} Statements
cbc0: 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 44 45   of the form "DE
cbd0: 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 6e  LETE FROM tablen
cbe0: 61 6d 65 22 20 77 69 74 68 20 6e 6f 0a 2a 2a 20  ame" with no.** 
cbf0: 20 20 20 20 20 20 20 20 20 57 48 45 52 45 20 63           WHERE c
cc00: 6c 61 75 73 65 20 73 68 61 6c 6c 20 6e 6f 74 20  lause shall not 
cc10: 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65  change the value
cc20: 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 20 20 20   returned.**    
cc30: 20 20 20 20 20 20 62 79 20 5b 73 71 6c 69 74 65        by [sqlite
cc40: 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
cc50: 29 5d 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49 54 41 54  )].**.** LIMITAT
cc60: 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 55 31 32  IONS:.**.** {U12
cc70: 32 36 34 7d 20 49 66 20 61 20 73 65 70 61 72 61  264} If a separa
cc80: 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20  te thread makes 
cc90: 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73  changes on the s
cca0: 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
ccb0: 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20  nection.**      
ccc0: 20 20 20 20 77 68 69 6c 65 20 5b 73 71 6c 69 74      while [sqlit
ccd0: 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
cce0: 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74  ()] is running t
ccf0: 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 0a 2a  hen the value .*
cd00: 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72  *          retur
cd10: 6e 65 64 20 69 73 20 75 6e 70 72 65 64 69 63 74  ned is unpredict
cd20: 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61  able and not mea
cd30: 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20  ningful..*/.int 
cd40: 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
cd50: 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b  anges(sqlite3*);
cd60: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
cd70: 3a 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c 6f  : Interrupt A Lo
cd80: 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 79  ng-Running Query
cd90: 20 7b 46 31 32 32 37 30 7d 0a 2a 2a 0a 2a 2a 20   {F12270}.**.** 
cda0: 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61  This function ca
cdb0: 75 73 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67  uses any pending
cdc0: 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74   database operat
cdd0: 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64  ion to abort and
cde0: 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74  .** return at it
cdf0: 73 20 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72  s earliest oppor
ce00: 74 75 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75  tunity. This rou
ce10: 74 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c  tine is typicall
ce20: 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72  y.** called in r
ce30: 65 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65  esponse to a use
ce40: 72 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73  r action such as
ce50: 20 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65   pressing "Cance
ce60: 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20  l".** or Ctrl-C 
ce70: 77 68 65 72 65 20 74 68 65 20 75 73 65 72 20 77  where the user w
ce80: 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72  ants a long quer
ce90: 79 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68  y operation to h
cea0: 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65  alt.** immediate
ceb0: 6c 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20  ly..**.** It is 
cec0: 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69  safe to call thi
ced0: 73 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61  s routine from a
cee0: 20 74 68 72 65 61 64 20 64 69 66 66 65 72 65 6e   thread differen
cef0: 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68  t from the.** th
cf00: 72 65 61 64 20 74 68 61 74 20 69 73 20 63 75 72  read that is cur
cf10: 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74  rently running t
cf20: 68 65 20 64 61 74 61 62 61 73 65 20 6f 70 65 72  he database oper
cf30: 61 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a  ation.  But it.*
cf40: 2a 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  * is not safe to
cf50: 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69   call this routi
cf60: 6e 65 20 77 69 74 68 20 61 20 64 61 74 61 62 61  ne with a databa
cf70: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  se connection th
cf80: 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20  at.** is closed 
cf90: 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73 65 20 62  or might close b
cfa0: 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 69 6e  efore sqlite3_in
cfb0: 74 65 72 72 75 70 74 28 29 20 72 65 74 75 72 6e  terrupt() return
cfc0: 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 53  s..**.** If an S
cfd0: 51 4c 20 69 73 20 76 65 72 79 20 6e 65 61 72 6c  QL is very nearl
cfe0: 79 20 66 69 6e 69 73 68 65 64 20 61 74 20 74 68  y finished at th
cff0: 65 20 74 69 6d 65 20 77 68 65 6e 20 73 71 6c 69  e time when sqli
d000: 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 0a  te3_interrupt().
d010: 2a 2a 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68  ** is called, th
d020: 65 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f 74 20  en it might not 
d030: 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e  have an opportun
d040: 69 74 79 20 74 6f 20 62 65 20 69 6e 74 65 72 72  ity to be interr
d050: 75 70 74 65 64 2e 0a 2a 2a 20 49 74 20 6d 69 67  upted..** It mig
d060: 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63  ht continue to c
d070: 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 20 41 6e  ompletion..** An
d080: 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74   SQL operation t
d090: 68 61 74 20 69 73 20 69 6e 74 65 72 72 75 70 74  hat is interrupt
d0a0: 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a  ed will return.*
d0b0: 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  * [SQLITE_INTERR
d0c0: 55 50 54 5d 2e 20 20 49 66 20 74 68 65 20 69 6e  UPT].  If the in
d0d0: 74 65 72 72 75 70 74 65 64 20 53 51 4c 20 6f 70  terrupted SQL op
d0e0: 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 0a 2a 2a  eration is an.**
d0f0: 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c   INSERT, UPDATE,
d100: 20 6f 72 20 44 45 4c 45 54 45 20 74 68 61 74 20   or DELETE that 
d110: 69 73 20 69 6e 73 69 64 65 20 61 6e 20 65 78 70  is inside an exp
d120: 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f  licit transactio
d130: 6e 2c 20 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  n, .** then the 
d140: 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63 74 69  entire transacti
d150: 6f 6e 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65  on will be rolle
d160: 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63  d back automatic
d170: 61 6c 6c 79 2e 0a 2a 2a 20 41 20 63 61 6c 6c 20  ally..** A call 
d180: 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  to sqlite3_inter
d190: 72 75 70 74 28 29 20 68 61 73 20 6e 6f 20 65 66  rupt() has no ef
d1a0: 66 65 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74  fect on SQL stat
d1b0: 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61  ements.** that a
d1c0: 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72  re started after
d1d0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
d1e0: 70 74 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  pt() returns..**
d1f0: 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
d200: 2a 2a 0a 2a 2a 20 7b 46 31 32 32 37 31 7d 20 54  **.** {F12271} T
d210: 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65  he [sqlite3_inte
d220: 72 72 75 70 74 28 29 5d 20 69 6e 74 65 72 66 61  rrupt()] interfa
d230: 63 65 20 77 69 6c 6c 20 66 6f 72 63 65 20 61 6c  ce will force al
d240: 6c 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 20 20 20  l running.**    
d250: 20 20 20 20 20 20 53 51 4c 20 73 74 61 74 65 6d        SQL statem
d260: 65 6e 74 73 20 61 73 73 6f 63 69 61 74 65 64 20  ents associated 
d270: 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 64 61  with the same da
d280: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
d290: 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f  n.**          to
d2a0: 20 68 61 6c 74 20 61 66 74 65 72 20 70 72 6f 63   halt after proc
d2b0: 65 73 73 69 6e 67 20 61 74 20 6d 6f 73 74 20 6f  essing at most o
d2c0: 6e 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 72 6f  ne additional ro
d2d0: 77 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20  w of.**         
d2e0: 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31   data..**.** {F1
d2f0: 32 32 37 32 7d 20 41 6e 79 20 53 51 4c 20 73 74  2272} Any SQL st
d300: 61 74 65 6d 65 6e 74 20 74 68 61 74 20 69 73 20  atement that is 
d310: 69 6e 74 65 72 72 75 70 74 65 64 20 62 79 20 5b  interrupted by [
d320: 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
d330: 74 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  t()].**         
d340: 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
d350: 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e  LITE_INTERRUPT].
d360: 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49 54 41 54 49 4f  .**.** LIMITATIO
d370: 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 55 31 32 32 37  NS:.**.** {U1227
d380: 39 7d 20 49 66 20 74 68 65 20 64 61 74 61 62 61  9} If the databa
d390: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c  se connection cl
d3a0: 6f 73 65 73 20 77 68 69 6c 65 20 5b 73 71 6c 69  oses while [sqli
d3b0: 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d  te3_interrupt()]
d3c0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20  .**          is 
d3d0: 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61 64  running then bad
d3e0: 20 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b   things will lik
d3f0: 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 76  ely happen..*/.v
d400: 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  oid sqlite3_inte
d410: 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b  rrupt(sqlite3*);
d420: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
d430: 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41  : Determine If A
d440: 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20  n SQL Statement 
d450: 49 73 20 43 6f 6d 70 6c 65 74 65 20 7b 46 31 30  Is Complete {F10
d460: 35 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  510}.**.** These
d470: 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73   routines are us
d480: 65 66 75 6c 20 66 6f 72 20 63 6f 6d 6d 61 6e 64  eful for command
d490: 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64  -line input to d
d4a0: 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a  etermine if the.
d4b0: 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74  ** currently ent
d4c0: 65 72 65 64 20 74 65 78 74 20 73 65 65 6d 73 20  ered text seems 
d4d0: 74 6f 20 66 6f 72 6d 20 63 6f 6d 70 6c 65 74 65  to form complete
d4e0: 20 61 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74   a SQL statement
d4f0: 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69   or.** if additi
d500: 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65  onal input is ne
d510: 65 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64  eded before send
d520: 69 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e 74  ing the text int
d530: 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20  o.** SQLite for 
d540: 70 61 72 73 69 6e 67 2e 20 20 54 68 65 73 65 20  parsing.  These 
d550: 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
d560: 74 72 75 65 20 69 66 20 74 68 65 20 69 6e 70 75  true if the inpu
d570: 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65  t string.** appe
d580: 61 72 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70  ars to be a comp
d590: 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65  lete SQL stateme
d5a0: 6e 74 2e 20 20 41 20 73 74 61 74 65 6d 65 6e 74  nt.  A statement
d5b0: 20 69 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65   is judged to be
d5c0: 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20  .** complete if 
d5d0: 69 74 20 65 6e 64 73 20 77 69 74 68 20 61 20 73  it ends with a s
d5e0: 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61  emicolon token a
d5f0: 6e 64 20 69 73 20 6e 6f 74 20 61 20 66 72 61 67  nd is not a frag
d600: 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 43 52 45  ment of a.** CRE
d610: 41 54 45 20 54 52 49 47 47 45 52 20 73 74 61 74  ATE TRIGGER stat
d620: 65 6d 65 6e 74 2e 20 20 53 65 6d 69 63 6f 6c 6f  ement.  Semicolo
d630: 6e 73 20 74 68 61 74 20 61 72 65 20 65 6d 62 65  ns that are embe
d640: 64 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73  dded within.** s
d650: 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f  tring literals o
d660: 72 20 71 75 6f 74 65 64 20 69 64 65 6e 74 69 66  r quoted identif
d670: 69 65 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d  ier names or com
d680: 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a  ments are not.**
d690: 20 69 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b   independent tok
d6a0: 65 6e 73 20 28 74 68 65 79 20 61 72 65 20 70 61  ens (they are pa
d6b0: 72 74 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20  rt of the token 
d6c0: 69 6e 20 77 68 69 63 68 20 74 68 65 79 20 61 72  in which they ar
d6d0: 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29 20 61  e.** embedded) a
d6e0: 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f 74 20 63  nd thus do not c
d6f0: 6f 75 6e 74 20 61 73 20 61 20 73 74 61 74 65 6d  ount as a statem
d700: 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a  ent terminator..
d710: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
d720: 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73  ines do not pars
d730: 65 20 74 68 65 20 53 51 4c 20 61 6e 64 0a 2a 2a  e the SQL and.**
d740: 20 73 6f 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74   so will not det
d750: 65 63 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c  ect syntacticall
d760: 79 20 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e  y incorrect SQL.
d770: 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
d780: 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 35 31 31  S:.**.** {F10511
d790: 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  } The sqlite3_co
d7a0: 6d 70 6c 65 74 65 28 29 20 61 6e 64 20 73 71 6c  mplete() and sql
d7b0: 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
d7c0: 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 20  ) functions.**  
d7d0: 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 74          return t
d7e0: 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69  rue (non-zero) i
d7f0: 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68  f and only if th
d800: 65 20 6c 61 73 74 0a 2a 2a 20 20 20 20 20 20 20  e last.**       
d810: 20 20 20 6e 6f 6e 2d 77 68 69 74 65 73 70 61 63     non-whitespac
d820: 65 20 74 6f 6b 65 6e 20 69 6e 20 74 68 65 69 72  e token in their
d830: 20 69 6e 70 75 74 20 69 73 20 61 20 73 65 6d 69   input is a semi
d840: 63 6f 6c 6f 6e 20 74 68 61 74 0a 2a 2a 20 20 20  colon that.**   
d850: 20 20 20 20 20 20 20 69 73 20 6e 6f 74 20 69 6e         is not in
d860: 20 62 65 74 77 65 65 6e 20 74 68 65 20 42 45 47   between the BEG
d870: 49 4e 20 61 6e 64 20 45 4e 44 20 6f 66 20 61 20  IN and END of a 
d880: 43 52 45 41 54 45 20 54 52 49 47 47 45 52 0a 2a  CREATE TRIGGER.*
d890: 2a 20 20 20 20 20 20 20 20 20 20 73 74 61 74 65  *          state
d8a0: 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49  ment..**.** LIMI
d8b0: 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b  TATIONS:.**.** {
d8c0: 55 31 30 35 31 32 7d 20 54 68 65 20 69 6e 70 75  U10512} The inpu
d8d0: 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d  t to sqlite3_com
d8e0: 70 6c 65 74 65 28 29 20 6d 75 73 74 20 62 65 20  plete() must be 
d8f0: 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
d900: 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 55 54  d.**          UT
d910: 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  F-8 string..**.*
d920: 2a 20 7b 55 31 30 35 31 33 7d 20 54 68 65 20 69  * {U10513} The i
d930: 6e 70 75 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  nput to sqlite3_
d940: 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 6d 75 73  complete16() mus
d950: 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d  t be a zero-term
d960: 69 6e 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20  inated.**       
d970: 20 20 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67     UTF-16 string
d980: 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20   in native byte 
d990: 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71  order..*/.int sq
d9a0: 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63  lite3_complete(c
d9b0: 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 29 3b  onst char *sql);
d9c0: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d  .int sqlite3_com
d9d0: 70 6c 65 74 65 31 36 28 63 6f 6e 73 74 20 76 6f  plete16(const vo
d9e0: 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a  id *sql);../*.**
d9f0: 20 43 41 50 49 33 52 45 46 3a 20 52 65 67 69 73   CAPI3REF: Regis
da00: 74 65 72 20 41 20 43 61 6c 6c 62 61 63 6b 20 54  ter A Callback T
da10: 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f  o Handle SQLITE_
da20: 42 55 53 59 20 45 72 72 6f 72 73 20 7b 46 31 32  BUSY Errors {F12
da30: 33 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  310}.**.** This 
da40: 72 6f 75 74 69 6e 65 20 69 64 65 6e 74 69 66 69  routine identifi
da50: 65 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  es a callback fu
da60: 6e 63 74 69 6f 6e 20 74 68 61 74 20 6d 69 67 68  nction that migh
da70: 74 20 62 65 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20  t be.** invoked 
da80: 77 68 65 6e 65 76 65 72 20 61 6e 20 61 74 74 65  whenever an atte
da90: 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20 6f  mpt is made to o
daa0: 70 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 74  pen a database t
dab0: 61 62 6c 65 20 0a 2a 2a 20 74 68 61 74 20 61 6e  able .** that an
dac0: 6f 74 68 65 72 20 74 68 72 65 61 64 20 6f 72 20  other thread or 
dad0: 70 72 6f 63 65 73 73 20 68 61 73 20 6c 6f 63 6b  process has lock
dae0: 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 62 75  ed..** If the bu
daf0: 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e  sy callback is N
db00: 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54  ULL, then [SQLIT
db10: 45 5f 42 55 53 59 5d 0a 2a 2a 20 6f 72 20 5b 53  E_BUSY].** or [S
db20: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
db30: 4b 45 44 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72  KED].** is retur
db40: 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20  ned immediately 
db50: 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e  upon encounterin
db60: 67 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 49  g the lock..** I
db70: 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62  f the busy callb
db80: 61 63 6b 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  ack is not NULL,
db90: 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 63 61 6c   then the.** cal
dba0: 6c 62 61 63 6b 20 77 69 6c 6c 20 62 65 20 69 6e  lback will be in
dbb0: 76 6f 6b 65 64 20 77 69 74 68 20 74 77 6f 20 61  voked with two a
dbc0: 72 67 75 6d 65 6e 74 73 2e 20 20 54 68 65 0a 2a  rguments.  The.*
dbd0: 2a 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  * first argument
dbe0: 20 74 6f 20 74 68 65 20 68 61 6e 64 6c 65 72 20   to the handler 
dbf0: 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
dc00: 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77   void* pointer w
dc10: 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74  hich.** is the t
dc20: 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  hird argument to
dc30: 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2e 20 20   this routine.  
dc40: 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
dc50: 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 68 61  ent to.** the ha
dc60: 6e 64 6c 65 72 20 69 73 20 74 68 65 20 6e 75 6d  ndler is the num
dc70: 62 65 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61  ber of times tha
dc80: 74 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  t the busy handl
dc90: 65 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69  er has.** been i
dca0: 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68 69 73 20  nvoked for this 
dcb0: 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20  locking event.  
dcc0: 20 49 66 20 74 68 65 0a 2a 2a 20 62 75 73 79 20   If the.** busy 
dcd0: 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
dce0: 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64 69   0, then no addi
dcf0: 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73 20  tional attempts 
dd00: 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61  are made to.** a
dd10: 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61  ccess the databa
dd20: 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42  se and [SQLITE_B
dd30: 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  USY] or [SQLITE_
dd40: 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69  IOERR_BLOCKED] i
dd50: 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 49  s returned..** I
dd60: 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  f the callback r
dd70: 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
dd80: 20 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74   then another at
dd90: 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65  tempt.** is made
dda0: 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74   to open the dat
ddb0: 61 62 61 73 65 20 66 6f 72 20 72 65 61 64 69 6e  abase for readin
ddc0: 67 20 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20  g and the cycle 
ddd0: 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54  repeats..**.** T
dde0: 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61  he presence of a
ddf0: 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f   busy handler do
de00: 65 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65  es not guarantee
de10: 20 74 68 61 74 0a 2a 2a 20 69 74 20 77 69 6c 6c   that.** it will
de20: 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   be invoked when
de30: 20 74 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63   there is lock c
de40: 6f 6e 74 65 6e 74 69 6f 6e 2e 0a 2a 2a 20 49 66  ontention..** If
de50: 20 53 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e   SQLite determin
de60: 65 73 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67  es that invoking
de70: 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
de80: 72 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69  r could result i
de90: 6e 0a 2a 2a 20 61 20 64 65 61 64 6c 6f 63 6b 2c  n.** a deadlock,
dea0: 20 69 74 20 77 69 6c 6c 20 67 6f 20 61 68 65 61   it will go ahea
deb0: 64 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51  d and return [SQ
dec0: 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 0a 2a 2a  LITE_BUSY] or.**
ded0: 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42   [SQLITE_IOERR_B
dee0: 4c 4f 43 4b 45 44 5d 20 69 6e 73 74 65 61 64 20  LOCKED] instead 
def0: 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 0a  of invoking the.
df00: 2a 2a 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e  ** busy handler.
df10: 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61 20 73  .** Consider a s
df20: 63 65 6e 61 72 69 6f 20 77 68 65 72 65 20 6f 6e  cenario where on
df30: 65 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c  e process is hol
df40: 64 69 6e 67 20 61 20 72 65 61 64 20 6c 6f 63 6b  ding a read lock
df50: 20 74 68 61 74 0a 2a 2a 20 69 74 20 69 73 20 74   that.** it is t
df60: 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65  rying to promote
df70: 20 74 6f 20 61 20 72 65 73 65 72 76 65 64 20 6c   to a reserved l
df80: 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63  ock and.** a sec
df90: 6f 6e 64 20 70 72 6f 63 65 73 73 20 69 73 20 68  ond process is h
dfa0: 6f 6c 64 69 6e 67 20 61 20 72 65 73 65 72 76 65  olding a reserve
dfb0: 64 20 6c 6f 63 6b 20 74 68 61 74 20 69 74 20 69  d lock that it i
dfc0: 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70  s trying.** to p
dfd0: 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78 63  romote to an exc
dfe0: 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68  lusive lock.  Th
dff0: 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20  e first process 
e000: 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a  cannot proceed.*
e010: 2a 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20  * because it is 
e020: 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 73  blocked by the s
e030: 65 63 6f 6e 64 20 61 6e 64 20 74 68 65 20 73 65  econd and the se
e040: 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 63 61 6e  cond process can
e050: 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62  not.** proceed b
e060: 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f  ecause it is blo
e070: 63 6b 65 64 20 62 79 20 74 68 65 20 66 69 72 73  cked by the firs
e080: 74 2e 20 20 49 66 20 62 6f 74 68 20 70 72 6f 63  t.  If both proc
e090: 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20  esses.** invoke 
e0a0: 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
e0b0: 73 2c 20 6e 65 69 74 68 65 72 20 77 69 6c 6c 20  s, neither will 
e0c0: 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67 72 65 73  make any progres
e0d0: 73 2e 20 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a  s.  Therefore,.*
e0e0: 2a 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e 73  * SQLite returns
e0f0: 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 66   [SQLITE_BUSY] f
e100: 6f 72 20 74 68 65 20 66 69 72 73 74 20 70 72 6f  or the first pro
e110: 63 65 73 73 2c 20 68 6f 70 69 6e 67 20 74 68 61  cess, hoping tha
e120: 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69  t this.** will i
e130: 6e 64 75 63 65 20 74 68 65 20 66 69 72 73 74 20  nduce the first 
e140: 70 72 6f 63 65 73 73 20 74 6f 20 72 65 6c 65 61  process to relea
e150: 73 65 20 69 74 73 20 72 65 61 64 20 6c 6f 63 6b  se its read lock
e160: 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68   and allow.** th
e170: 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73  e second process
e180: 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a   to proceed..**.
e190: 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20 62  ** The default b
e1a0: 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  usy callback is 
e1b0: 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  NULL..**.** The 
e1c0: 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 65 72  [SQLITE_BUSY] er
e1d0: 72 6f 72 20 69 73 20 63 6f 6e 76 65 72 74 65 64  ror is converted
e1e0: 20 74 6f 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52   to [SQLITE_IOER
e1f0: 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 77 68  R_BLOCKED].** wh
e200: 65 6e 20 53 51 4c 69 74 65 20 69 73 20 69 6e 20  en SQLite is in 
e210: 74 68 65 20 6d 69 64 64 6c 65 20 6f 66 20 61 20  the middle of a 
e220: 6c 61 72 67 65 20 74 72 61 6e 73 61 63 74 69 6f  large transactio
e230: 6e 20 77 68 65 72 65 20 61 6c 6c 20 74 68 65 0a  n where all the.
e240: 2a 2a 20 63 68 61 6e 67 65 73 20 77 69 6c 6c 20  ** changes will 
e250: 6e 6f 74 20 66 69 74 20 69 6e 74 6f 20 74 68 65  not fit into the
e260: 20 69 6e 2d 6d 65 6d 6f 72 79 20 63 61 63 68 65   in-memory cache
e270: 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a  .  SQLite will.*
e280: 2a 20 61 6c 72 65 61 64 79 20 68 6f 6c 64 20 61  * already hold a
e290: 20 52 45 53 45 52 56 45 44 20 6c 6f 63 6b 20 6f   RESERVED lock o
e2a0: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  n the database f
e2b0: 69 6c 65 2c 20 62 75 74 20 69 74 20 6e 65 65 64  ile, but it need
e2c0: 73 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20  s.** to promote 
e2d0: 74 68 69 73 20 6c 6f 63 6b 20 74 6f 20 45 58 43  this lock to EXC
e2e0: 4c 55 53 49 56 45 20 73 6f 20 74 68 61 74 20 69  LUSIVE so that i
e2f0: 74 20 63 61 6e 20 73 70 69 6c 6c 20 63 61 63 68  t can spill cach
e300: 65 0a 2a 2a 20 70 61 67 65 73 20 69 6e 74 6f 20  e.** pages into 
e310: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
e320: 65 20 77 69 74 68 6f 75 74 20 68 61 72 6d 20 74  e without harm t
e330: 6f 20 63 6f 6e 63 75 72 72 65 6e 74 0a 2a 2a 20  o concurrent.** 
e340: 72 65 61 64 65 72 73 2e 20 20 49 66 20 69 74 20  readers.  If it 
e350: 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 70 72 6f  is unable to pro
e360: 6d 6f 74 65 20 74 68 65 20 6c 6f 63 6b 2c 20 74  mote the lock, t
e370: 68 65 6e 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72  hen the in-memor
e380: 79 0a 2a 2a 20 63 61 63 68 65 20 77 69 6c 6c 20  y.** cache will 
e390: 62 65 20 6c 65 66 74 20 69 6e 20 61 6e 20 69 6e  be left in an in
e3a0: 63 6f 6e 73 69 73 74 65 6e 74 20 73 74 61 74 65  consistent state
e3b0: 20 61 6e 64 20 73 6f 20 74 68 65 20 65 72 72 6f   and so the erro
e3c0: 72 0a 2a 2a 20 63 6f 64 65 20 69 73 20 70 72 6f  r.** code is pro
e3d0: 6d 6f 74 65 64 20 66 72 6f 6d 20 74 68 65 20 72  moted from the r
e3e0: 65 6c 61 74 69 76 65 6c 79 20 62 65 6e 69 67 6e  elatively benign
e3f0: 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 74   [SQLITE_BUSY] t
e400: 6f 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 65  o.** the more se
e410: 76 65 72 65 20 5b 53 51 4c 49 54 45 5f 49 4f 45  vere [SQLITE_IOE
e420: 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 20 20 54 68  RR_BLOCKED].  Th
e430: 69 73 20 65 72 72 6f 72 20 63 6f 64 65 20 70 72  is error code pr
e440: 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65  omotion.** force
e450: 73 20 61 6e 20 61 75 74 6f 6d 61 74 69 63 20 72  s an automatic r
e460: 6f 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 63  ollback of the c
e470: 68 61 6e 67 65 73 2e 20 20 53 65 65 20 74 68 65  hanges.  See the
e480: 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22 68 74 74  .** <a href="htt
e490: 70 3a 2f 2f 77 77 77 2e 73 71 6c 69 74 65 2e 6f  p://www.sqlite.o
e4a0: 72 67 2f 63 76 73 74 72 61 63 2f 77 69 6b 69 3f  rg/cvstrac/wiki?
e4b0: 70 3d 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c  p=CorruptionFoll
e4c0: 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72 22 3e  owingBusyError">
e4d0: 0a 2a 2a 20 43 6f 72 72 75 70 74 69 6f 6e 46 6f  .** CorruptionFo
e4e0: 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72  llowingBusyError
e4f0: 3c 2f 61 3e 20 77 69 6b 69 20 70 61 67 65 20 66  </a> wiki page f
e500: 6f 72 20 61 20 64 69 73 63 75 73 73 69 6f 6e 20  or a discussion 
e510: 6f 66 20 77 68 79 0a 2a 2a 20 74 68 69 73 20 69  of why.** this i
e520: 73 20 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a 2a 09  s important..**.
e530: 0a 2a 2a 20 54 68 65 72 65 20 63 61 6e 20 6f 6e  .** There can on
e540: 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62  ly be a single b
e550: 75 73 79 20 68 61 6e 64 6c 65 72 20 64 65 66 69  usy handler defi
e560: 6e 65 64 20 66 6f 72 20 65 61 63 68 20 64 61 74  ned for each dat
e570: 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
e580: 69 6f 6e 2e 20 20 53 65 74 74 69 6e 67 20 61 20  ion.  Setting a 
e590: 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72  new busy handler
e5a0: 20 63 6c 65 61 72 73 20 61 6e 79 20 70 72 65 76   clears any prev
e5b0: 69 6f 75 73 20 6f 6e 65 2e 20 0a 2a 2a 20 4e 6f  ious one. .** No
e5c0: 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 20  te that calling 
e5d0: 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69  [sqlite3_busy_ti
e5e0: 6d 65 6f 75 74 28 29 5d 20 77 69 6c 6c 20 61 6c  meout()] will al
e5f0: 73 6f 20 73 65 74 20 6f 72 20 63 6c 65 61 72 0a  so set or clear.
e600: 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ** the busy hand
e610: 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ler..**.** INVAR
e620: 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31  IANTS:.**.** {F1
e630: 32 33 31 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  2311} The [sqlit
e640: 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
e650: 29 5d 20 66 75 6e 63 74 69 6f 6e 20 72 65 70 6c  )] function repl
e660: 61 63 65 73 20 74 68 65 20 62 75 73 79 20 68 61  aces the busy ha
e670: 6e 64 6c 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  ndler.**        
e680: 20 20 63 61 6c 6c 62 61 63 6b 20 69 6e 20 74 68    callback in th
e690: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
e6a0: 63 74 69 6f 6e 20 69 64 65 6e 74 69 66 69 65 64  ction identified
e6b0: 20 62 79 20 74 68 65 20 31 73 74 0a 2a 2a 20 20   by the 1st.**  
e6c0: 20 20 20 20 20 20 20 20 70 61 72 61 6d 65 74 65          paramete
e6d0: 72 20 77 69 74 68 20 61 20 6e 65 77 20 62 75 73  r with a new bus
e6e0: 79 20 68 61 6e 64 6c 65 72 20 69 64 65 6e 74 69  y handler identi
e6f0: 66 69 65 64 20 62 79 20 74 68 65 20 32 6e 64 20  fied by the 2nd 
e700: 61 6e 64 20 33 72 64 0a 2a 2a 20 20 20 20 20 20  and 3rd.**      
e710: 20 20 20 20 70 61 72 61 6d 65 74 65 72 73 2e 0a      parameters..
e720: 2a 2a 0a 2a 2a 20 7b 46 31 32 33 31 32 7d 20 54  **.** {F12312} T
e730: 68 65 20 64 65 66 61 75 6c 74 20 62 75 73 79 20  he default busy 
e740: 68 61 6e 64 6c 65 72 20 66 6f 72 20 6e 65 77 20  handler for new 
e750: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
e760: 69 6f 6e 73 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a  ions is NULL..**
e770: 0a 2a 2a 20 7b 46 31 32 33 31 34 7d 20 57 68 65  .** {F12314} Whe
e780: 6e 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 64 61  n two or more da
e790: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
e7a0: 6e 20 73 68 61 72 65 20 61 20 5b 73 71 6c 69 74  n share a [sqlit
e7b0: 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64  e3_enable_shared
e7c0: 5f 63 61 63 68 65 20 7c 20 63 6f 6d 6d 6f 6e 20  _cache | common 
e7d0: 63 61 63 68 65 5d 2c 0a 2a 2a 20 20 20 20 20 20  cache],.**      
e7e0: 20 20 20 20 74 68 65 20 62 75 73 79 20 68 61 6e      the busy han
e7f0: 64 6c 65 72 20 66 6f 72 20 74 68 65 20 64 61 74  dler for the dat
e800: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
e810: 20 63 75 72 72 65 6e 74 6c 79 20 75 73 69 6e 67   currently using
e820: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
e830: 20 63 61 63 68 65 20 69 73 20 69 6e 76 6f 6b 65   cache is invoke
e840: 64 20 77 68 65 6e 20 74 68 65 20 63 61 63 68 65  d when the cache
e850: 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 6c 6f   encounters a lo
e860: 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 31  ck..**.** {F1231
e870: 36 7d 20 49 66 20 61 20 62 75 73 79 20 68 61 6e  6} If a busy han
e880: 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65  dler callback re
e890: 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65 6e  turns zero, then
e8a0: 20 74 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 20   the SQLite.**  
e8b0: 20 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 63          interfac
e8c0: 65 20 74 68 61 74 20 70 72 6f 76 6f 6b 65 64 20  e that provoked 
e8d0: 74 68 65 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e  the locking even
e8e0: 74 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a  t will return.**
e8f0: 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54            [SQLIT
e900: 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  E_BUSY]..**.** {
e910: 46 31 32 33 31 38 7d 20 53 51 4c 69 74 65 20 77  F12318} SQLite w
e920: 69 6c 6c 20 69 6e 76 6f 6b 65 73 20 74 68 65 20  ill invokes the 
e930: 62 75 73 79 20 68 61 6e 64 6c 65 72 20 77 69 74  busy handler wit
e940: 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 20  h two arguments 
e950: 77 68 69 63 68 0a 2a 2a 20 20 20 20 20 20 20 20  which.**        
e960: 20 20 61 72 65 20 61 20 63 6f 70 79 20 6f 66 20    are a copy of 
e970: 74 68 65 20 70 6f 69 6e 74 65 72 20 73 75 70 70  the pointer supp
e980: 6c 69 65 64 20 62 79 20 74 68 65 20 33 72 64 20  lied by the 3rd 
e990: 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
e9a0: 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
e9b0: 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29  3_busy_handler()
e9c0: 5d 20 61 6e 64 20 61 20 63 6f 75 6e 74 20 6f 66  ] and a count of
e9d0: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70   the number of p
e9e0: 72 69 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  rior.**         
e9f0: 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20   invocations of 
ea00: 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
ea10: 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 6c 6f   for the same lo
ea20: 63 6b 69 6e 67 20 65 76 65 6e 74 2e 0a 2a 2a 0a  cking event..**.
ea30: 2a 2a 20 4c 49 4d 49 54 41 54 49 4f 4e 53 3a 0a  ** LIMITATIONS:.
ea40: 2a 2a 0a 2a 2a 20 7b 55 31 32 33 31 39 7d 20 41  **.** {U12319} A
ea50: 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 73 68   busy handler sh
ea60: 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 20 63 6c  ould not call cl
ea70: 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ose the database
ea80: 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20   connection.**  
ea90: 20 20 20 20 20 20 20 20 6f 72 20 70 72 65 70 61          or prepa
eaa0: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 74 68  red statement th
eab0: 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62  at invoked the b
eac0: 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a  usy handler..*/.
ead0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79  int sqlite3_busy
eae0: 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33  _handler(sqlite3
eaf0: 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c  *, int(*)(void*,
eb00: 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  int), void*);../
eb10: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
eb20: 65 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75  et A Busy Timeou
eb30: 74 20 7b 46 31 32 33 34 30 7d 0a 2a 2a 0a 2a 2a  t {F12340}.**.**
eb40: 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65   This routine se
eb50: 74 73 20 61 20 5b 73 71 6c 69 74 65 33 5f 62 75  ts a [sqlite3_bu
eb60: 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75 73  sy_handler | bus
eb70: 79 20 68 61 6e 64 6c 65 72 5d 0a 2a 2a 20 74 68  y handler].** th
eb80: 61 74 20 73 6c 65 65 70 73 20 66 6f 72 20 61 20  at sleeps for a 
eb90: 77 68 69 6c 65 20 77 68 65 6e 20 61 0a 2a 2a 20  while when a.** 
eba0: 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e  table is locked.
ebb0: 20 20 54 68 65 20 68 61 6e 64 6c 65 72 20 77 69    The handler wi
ebc0: 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c  ll sleep multipl
ebd0: 65 20 74 69 6d 65 73 20 75 6e 74 69 6c 20 0a 2a  e times until .*
ebe0: 2a 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20  * at least "ms" 
ebf0: 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20  milliseconds of 
ec00: 73 6c 65 65 70 69 6e 67 20 68 61 76 65 20 62 65  sleeping have be
ec10: 65 6e 20 64 6f 6e 65 2e 20 7b 46 31 32 33 34 33  en done. {F12343
ec20: 7d 20 41 66 74 65 72 0a 2a 2a 20 22 6d 73 22 20  } After.** "ms" 
ec30: 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20  milliseconds of 
ec40: 73 6c 65 65 70 69 6e 67 2c 20 74 68 65 20 68 61  sleeping, the ha
ec50: 6e 64 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20  ndler returns 0 
ec60: 77 68 69 63 68 0a 2a 2a 20 63 61 75 73 65 73 20  which.** causes 
ec70: 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
ec80: 20 74 6f 20 72 65 74 75 72 6e 20 5b 53 51 4c 49   to return [SQLI
ec90: 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c  TE_BUSY] or [SQL
eca0: 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45  ITE_IOERR_BLOCKE
ecb0: 44 5d 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e  D]..**.** Callin
ecc0: 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  g this routine w
ecd0: 69 74 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 20  ith an argument 
ece0: 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75  less than or equ
ecf0: 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75  al to zero.** tu
ed00: 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 79  rns off all busy
ed10: 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a   handlers..**.**
ed20: 20 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20   There can only 
ed30: 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79  be a single busy
ed40: 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 20 70   handler for a p
ed50: 61 72 74 69 63 75 6c 61 72 20 64 61 74 61 62 61  articular databa
ed60: 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
ed70: 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75  .  If another bu
ed80: 73 79 20 68 61 6e 64 6c 65 72 20 77 61 73 20 64  sy handler was d
ed90: 65 66 69 6e 65 64 20 20 0a 2a 2a 20 28 75 73 69  efined  .** (usi
eda0: 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  ng [sqlite3_busy
edb0: 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69  _handler()]) pri
edc0: 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a  or to calling.**
edd0: 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74   this routine, t
ede0: 68 61 74 20 6f 74 68 65 72 20 62 75 73 79 20 68  hat other busy h
edf0: 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65  andler is cleare
ee00: 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  d..**.** INVARIA
ee10: 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33  NTS:.**.** {F123
ee20: 34 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  41} The [sqlite3
ee30: 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
ee40: 20 66 75 6e 63 74 69 6f 6e 20 6f 76 65 72 72 69   function overri
ee50: 64 65 73 20 61 6e 79 20 70 72 69 6f 72 0a 2a 2a  des any prior.**
ee60: 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
ee70: 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28  e3_busy_timeout(
ee80: 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 62  )] or [sqlite3_b
ee90: 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 20 73  usy_handler()] s
eea0: 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20  etting.**       
eeb0: 20 20 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64     on the same d
eec0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
eed0: 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 34  on..**.** {F1234
eee0: 33 7d 20 49 66 20 74 68 65 20 32 6e 64 20 70 61  3} If the 2nd pa
eef0: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
ef00: 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74  te3_busy_timeout
ef10: 28 29 5d 20 69 73 20 6c 65 73 73 20 74 68 61 6e  ()] is less than
ef20: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
ef30: 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 2c 20 74  equal to zero, t
ef40: 68 65 6e 20 74 68 65 20 62 75 73 79 20 68 61 6e  hen the busy han
ef50: 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64 20  dler is cleared 
ef60: 73 6f 20 74 68 61 74 0a 2a 2a 20 20 20 20 20 20  so that.**      
ef70: 20 20 20 20 61 6c 6c 20 73 75 62 73 65 71 75 65      all subseque
ef80: 6e 74 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74  nt locking event
ef90: 73 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 72 65  s immediately re
efa0: 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  turn [SQLITE_BUS
efb0: 59 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 34  Y]..**.** {F1234
efc0: 34 7d 20 49 66 20 74 68 65 20 32 6e 64 20 70 61  4} If the 2nd pa
efd0: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
efe0: 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74  te3_busy_timeout
eff0: 28 29 5d 20 69 73 20 61 20 70 6f 73 69 74 69 76  ()] is a positiv
f000: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 75  e.**          nu
f010: 6d 62 65 72 20 4e 2c 20 74 68 65 6e 20 61 20 62  mber N, then a b
f020: 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 73  usy handler is s
f030: 65 74 20 74 68 61 74 20 72 65 70 65 61 74 65 64  et that repeated
f040: 6c 79 20 63 61 6c 6c 73 0a 2a 2a 20 20 20 20 20  ly calls.**     
f050: 20 20 20 20 20 74 68 65 20 78 53 6c 65 65 70 28       the xSleep(
f060: 29 20 6d 65 74 68 6f 64 20 69 6e 20 74 68 65 20  ) method in the 
f070: 56 46 53 20 69 6e 74 65 72 66 61 63 65 20 75 6e  VFS interface un
f080: 74 69 6c 20 65 69 74 68 65 72 20 74 68 65 0a 2a  til either the.*
f090: 2a 20 20 20 20 20 20 20 20 20 20 6c 6f 63 6b 20  *          lock 
f0a0: 63 6c 65 61 72 73 20 6f 72 20 75 6e 74 69 6c 20  clears or until 
f0b0: 74 68 65 20 63 75 6d 75 6c 61 74 69 76 65 20 73  the cumulative s
f0c0: 6c 65 65 70 20 74 69 6d 65 20 72 65 70 6f 72 74  leep time report
f0d0: 65 64 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20  ed back.**      
f0e0: 20 20 20 20 62 79 20 78 53 6c 65 65 70 28 29 20      by xSleep() 
f0f0: 65 78 63 65 65 64 73 20 4e 20 6d 69 6c 6c 69 73  exceeds N millis
f100: 65 63 6f 6e 64 73 2e 0a 2a 2f 0a 69 6e 74 20 73  econds..*/.int s
f110: 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65  qlite3_busy_time
f120: 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  out(sqlite3*, in
f130: 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  t ms);../*.** CA
f140: 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65  PI3REF: Convenie
f150: 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 46 6f 72  nce Routines For
f160: 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 73   Running Queries
f170: 20 7b 46 31 32 33 37 30 7d 0a 2a 2a 0a 2a 2a 20   {F12370}.**.** 
f180: 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62  Definition: A <b
f190: 3e 72 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62  >result table</b
f1a0: 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64 61 74 61  > is memory data
f1b0: 20 73 74 72 75 63 74 75 72 65 20 63 72 65 61 74   structure creat
f1c0: 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71  ed by the.** [sq
f1d0: 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
f1e0: 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 41  )] interface.  A
f1f0: 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 72 65   result table re
f200: 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d  cords the.** com
f210: 70 6c 65 74 65 20 71 75 65 72 79 20 72 65 73 75  plete query resu
f220: 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20  lts from one or 
f230: 6d 6f 72 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a  more queries..**
f240: 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 63 6f  .** The table co
f250: 6e 63 65 70 74 75 61 6c 6c 79 20 68 61 73 20 61  nceptually has a
f260: 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20   number of rows 
f270: 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75  and columns.  Bu
f280: 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62 65  t.** these numbe
f290: 72 73 20 61 72 65 20 6e 6f 74 20 70 61 72 74 20  rs are not part 
f2a0: 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61  of the result ta
f2b0: 62 6c 65 20 69 74 73 65 6c 66 2e 20 20 54 68 65  ble itself.  The
f2c0: 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72  se.** numbers ar
f2d0: 65 20 6f 62 74 61 69 6e 65 64 20 73 65 70 61 72  e obtained separ
f2e0: 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65  ately.  Let N be
f2f0: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72   the number of r
f300: 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20  ows.** and M be 
f310: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  the number of co
f320: 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72  lumns..**.** A r
f330: 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 61  esult table is a
f340: 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
f350: 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d  ers to zero-term
f360: 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20  inated.** UTF-8 
f370: 73 74 72 69 6e 67 73 2e 20 20 54 68 65 72 65 20  strings.  There 
f380: 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d  are (N+1)*M elem
f390: 65 6e 74 73 20 69 6e 20 74 68 65 20 61 72 72 61  ents in the arra
f3a0: 79 2e 20 20 0a 2a 2a 20 54 68 65 20 66 69 72 73  y.  .** The firs
f3b0: 74 20 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f 69  t M pointers poi
f3c0: 6e 74 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69  nt to zero-termi
f3d0: 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68  nated strings th
f3e0: 61 74 20 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 74  at .** contain t
f3f0: 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 20  he names of the 
f400: 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20  columns..** The 
f410: 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69 65  remaining entrie
f420: 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71  s all point to q
f430: 75 65 72 79 20 72 65 73 75 6c 74 73 2e 20 20 4e  uery results.  N
f440: 55 4c 4c 0a 2a 2a 20 76 61 6c 75 65 73 20 61 72  ULL.** values ar
f450: 65 20 67 69 76 65 20 61 20 4e 55 4c 4c 20 70 6f  e give a NULL po
f460: 69 6e 74 65 72 2e 20 20 41 6c 6c 20 6f 74 68 65  inter.  All othe
f470: 72 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 0a  r values are in.
f480: 2a 2a 20 74 68 65 69 72 20 55 54 46 2d 38 20 7a  ** their UTF-8 z
f490: 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73  ero-terminated s
f4a0: 74 72 69 6e 67 20 72 65 70 72 65 73 65 6e 74 61  tring representa
f4b0: 74 69 6f 6e 20 61 73 20 72 65 74 75 72 6e 65 64  tion as returned
f4c0: 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
f4d0: 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a  column_text()]..
f4e0: 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74  **.** A result t
f4f0: 61 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73 69  able might consi
f500: 73 74 73 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f  sts of one or mo
f510: 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  re memory alloca
f520: 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20  tions..** It is 
f530: 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 61 73 73  not safe to pass
f540: 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   a result table 
f550: 64 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c  directly to [sql
f560: 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a  ite3_free()]..**
f570: 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
f580: 73 68 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f  should be deallo
f590: 63 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  cated using [sql
f5a0: 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
f5b0: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 61 6e 20  )]..**.** As an 
f5c0: 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65 20 72  example of the r
f5d0: 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d  esult table form
f5e0: 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20 71 75  at, suppose a qu
f5f0: 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73  ery result.** is
f600: 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
f610: 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
f620: 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e  pre>.**        N
f630: 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67 65  ame        | Age
f640: 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d  .**        -----
f650: 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
f660: 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c 69  --.**        Ali
f670: 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a  ce       | 43.**
f680: 20 20 20 20 20 20 20 20 42 6f 62 20 20 20 20 20          Bob     
f690: 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20      | 28.**     
f6a0: 20 20 20 43 69 6e 64 79 20 20 20 20 20 20 20 7c     Cindy       |
f6b0: 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62   21.** </pre></b
f6c0: 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
f6d0: 20 54 68 65 72 65 20 61 72 65 20 74 77 6f 20 63   There are two c
f6e0: 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64  olumn (M==2) and
f6f0: 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d   three rows (N==
f700: 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a 2a 2a  3).  Thus the.**
f710: 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 68 61   result table ha
f720: 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20 53 75  s 8 entries.  Su
f730: 70 70 6f 73 65 20 74 68 65 20 72 65 73 75 6c 74  ppose the result
f740: 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72 65 64   table is stored
f750: 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61 79 20  .** in an array 
f760: 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e 20  names azResult. 
f770: 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74 20 68   Then azResult h
f780: 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74 65 6e  olds this conten
f790: 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  t:.**.** <blockq
f7a0: 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20  uote><pre>.**   
f7b0: 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
f7c0: 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a  1;0] = "Name";.*
f7d0: 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
f7e0: 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 65 22  t&#91;1] = "Age"
f7f0: 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
f800: 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22 41  sult&#91;2] = "A
f810: 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20  lice";.**       
f820: 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 33 5d   azResult&#91;3]
f830: 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20   = "43";.**     
f840: 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
f850: 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20  4] = "Bob";.**  
f860: 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
f870: 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a  91;5] = "28";.**
f880: 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
f890: 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79  &#91;6] = "Cindy
f8a0: 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
f8b0: 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22  esult&#91;7] = "
f8c0: 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  21";.** </pre></
f8d0: 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
f8e0: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65  * The sqlite3_ge
f8f0: 74 5f 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69  t_table() functi
f900: 6f 6e 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65  on evaluates one
f910: 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69   or more.** semi
f920: 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20  colon-separated 
f930: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69  SQL statements i
f940: 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69  n the zero-termi
f950: 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73  nated UTF-8.** s
f960: 74 72 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64  tring of its 2nd
f970: 20 70 61 72 61 6d 65 74 65 72 2e 20 20 49 74 20   parameter.  It 
f980: 72 65 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74  returns a result
f990: 20 74 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a   table to the.**
f9a0: 20 70 6f 69 6e 74 65 72 20 67 69 76 65 6e 20 69   pointer given i
f9b0: 6e 20 69 74 73 20 33 72 64 20 70 61 72 61 6d 65  n its 3rd parame
f9c0: 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72  ter..**.** After
f9d0: 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e   the calling fun
f9e0: 63 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68  ction has finish
f9f0: 65 64 20 75 73 69 6e 67 20 74 68 65 20 72 65 73  ed using the res
fa00: 75 6c 74 2c 20 69 74 20 73 68 6f 75 6c 64 20 0a  ult, it should .
fa10: 2a 2a 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e  ** pass the poin
fa20: 74 65 72 20 74 6f 20 74 68 65 20 72 65 73 75 6c  ter to the resul
fa30: 74 20 74 61 62 6c 65 20 74 6f 20 73 71 6c 69 74  t table to sqlit
fa40: 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20  e3_free_table() 
fa50: 69 6e 20 6f 72 64 65 72 20 74 6f 20 0a 2a 2a 20  in order to .** 
fa60: 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f  release the memo
fa70: 72 79 20 74 68 61 74 20 77 61 73 20 6d 61 6c 6c  ry that was mall
fa80: 6f 63 65 64 2e 20 20 42 65 63 61 75 73 65 20 6f  oced.  Because o
fa90: 66 20 74 68 65 20 77 61 79 20 74 68 65 20 0a 2a  f the way the .*
faa0: 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  * [sqlite3_mallo
fab0: 63 28 29 5d 20 68 61 70 70 65 6e 73 20 77 69 74  c()] happens wit
fac0: 68 69 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  hin sqlite3_get_
fad0: 74 61 62 6c 65 28 29 2c 20 74 68 65 20 63 61 6c  table(), the cal
fae0: 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  ling.** function
faf0: 20 6d 75 73 74 20 6e 6f 74 20 74 72 79 20 74 6f   must not try to
fb00: 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66   call [sqlite3_f
fb10: 72 65 65 28 29 5d 20 64 69 72 65 63 74 6c 79 2e  ree()] directly.
fb20: 20 20 4f 6e 6c 79 20 0a 2a 2a 20 5b 73 71 6c 69    Only .** [sqli
fb30: 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29  te3_free_table()
fb40: 5d 20 69 73 20 61 62 6c 65 20 74 6f 20 72 65 6c  ] is able to rel
fb50: 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  ease the memory 
fb60: 70 72 6f 70 65 72 6c 79 20 61 6e 64 20 73 61 66  properly and saf
fb70: 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ely..**.** The s
fb80: 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
fb90: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
fba0: 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73 20 61  implemented as a
fbb0: 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a   wrapper around.
fbc0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  ** [sqlite3_exec
fbd0: 28 29 5d 2e 20 20 54 68 65 20 73 71 6c 69 74 65  ()].  The sqlite
fbe0: 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 72 6f  3_get_table() ro
fbf0: 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68  utine does not h
fc00: 61 76 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f  ave access.** to
fc10: 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64 61   any internal da
fc20: 74 61 20 73 74 72 75 63 74 75 72 65 73 20 6f 66  ta structures of
fc30: 20 53 51 4c 69 74 65 2e 20 20 49 74 20 75 73 65   SQLite.  It use
fc40: 73 20 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c 69  s only the publi
fc50: 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 64  c.** interface d
fc60: 65 66 69 6e 65 64 20 68 65 72 65 2e 20 20 41 73  efined here.  As
fc70: 20 61 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20   a consequence, 
fc80: 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75  errors that occu
fc90: 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70  r in the.** wrap
fca0: 70 65 72 20 6c 61 79 65 72 20 6f 75 74 73 69 64  per layer outsid
fcb0: 65 20 6f 66 20 74 68 65 20 69 6e 74 65 72 6e 61  e of the interna
fcc0: 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  l [sqlite3_exec(
fcd0: 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a  )] call are not.
fce0: 2a 2a 20 72 65 66 6c 65 63 74 65 64 20 69 6e 20  ** reflected in 
fcf0: 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
fd00: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72   to [sqlite3_err
fd10: 63 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  code()] or.** [s
fd20: 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
fd30: 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
fd40: 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 37  TS:.**.** {F1237
fd50: 31 7d 20 49 66 20 61 20 5b 73 71 6c 69 74 65 33  1} If a [sqlite3
fd60: 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 66 61  _get_table()] fa
fd70: 69 6c 73 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c  ils a memory all
fd80: 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a  ocation, then.**
fd90: 20 20 20 20 20 20 20 20 20 20 69 74 20 66 72 65            it fre
fda0: 65 73 20 74 68 65 20 72 65 73 75 6c 74 20 74 61  es the result ta
fdb0: 62 6c 65 20 75 6e 64 65 72 20 63 6f 6e 73 74 72  ble under constr
fdc0: 75 63 74 69 6f 6e 2c 20 61 62 6f 72 74 73 20 74  uction, aborts t
fdd0: 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 71  he.**          q
fde0: 75 65 72 79 20 69 6e 20 70 72 6f 63 65 73 73 2c  uery in process,
fdf0: 20 73 6b 69 70 73 20 61 6e 79 20 73 75 62 73 65   skips any subse
fe00: 71 75 65 6e 74 20 71 75 65 72 69 65 73 2c 20 73  quent queries, s
fe10: 65 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  ets the.**      
fe20: 20 20 20 20 2a 72 65 73 75 6c 74 70 20 6f 75 74      *resultp out
fe30: 70 75 74 20 70 6f 69 6e 74 65 72 20 74 6f 20 4e  put pointer to N
fe40: 55 4c 4c 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ULL and returns 
fe50: 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a  [SQLITE_NOMEM]..
fe60: 2a 2a 0a 2a 2a 20 7b 46 31 32 33 37 33 7d 20 49  **.** {F12373} I
fe70: 66 20 74 68 65 20 6e 63 6f 6c 75 6d 6e 20 70 61  f the ncolumn pa
fe80: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
fe90: 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d  te3_get_table()]
fea0: 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 0a 2a 2a 20   is not NULL.** 
feb0: 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 5b 73           then [s
fec0: 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
fed0: 28 29 5d 20 77 72 69 74 65 20 74 68 65 20 6e 75  ()] write the nu
fee0: 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
fef0: 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  in the.**       
ff00: 20 20 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66     result set of
ff10: 20 74 68 65 20 71 75 65 72 79 20 69 6e 74 6f 20   the query into 
ff20: 2a 6e 63 6f 6c 75 6d 6e 20 69 66 20 74 68 65 20  *ncolumn if the 
ff30: 71 75 65 72 79 20 69 73 0a 2a 2a 20 20 20 20 20  query is.**     
ff40: 20 20 20 20 20 73 75 63 63 65 73 73 66 75 6c 20       successful 
ff50: 28 69 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  (if the function
ff60: 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f   returns SQLITE_
ff70: 4f 4b 29 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33  OK)..**.** {F123
ff80: 37 34 7d 20 49 66 20 74 68 65 20 6e 72 6f 77 20  74} If the nrow 
ff90: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
ffa0: 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
ffb0: 29 5d 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 0a 2a  )] is not NULL.*
ffc0: 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20  *          then 
ffd0: 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62  [sqlite3_get_tab
ffe0: 6c 65 28 29 5d 20 77 72 69 74 65 20 74 68 65 20  le()] write the 
fff0: 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 69  number of rows i
10000 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  n the.**        
10010 20 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20    result set of 
10020 74 68 65 20 71 75 65 72 79 20 69 6e 74 6f 20 2a  the query into *
10030 6e 72 6f 77 20 69 66 20 74 68 65 20 71 75 65 72  nrow if the quer
10040 79 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  y is.**         
10050 20 73 75 63 63 65 73 73 66 75 6c 20 28 69 66 20   successful (if 
10060 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  the function ret
10070 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 29 2e  urns SQLITE_OK).
10080 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 37 36 7d 20  .**.** {F12376} 
10090 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 67 65 74  The [sqlite3_get
100a0 5f 74 61 62 6c 65 28 29 5d 20 66 75 6e 63 74 69  _table()] functi
100b0 6f 6e 20 73 65 74 73 20 69 74 73 20 2a 6e 63 6f  on sets its *nco
100c0 6c 75 6d 6e 20 76 61 6c 75 65 0a 2a 2a 20 20 20  lumn value.**   
100d0 20 20 20 20 20 20 20 74 6f 20 74 68 65 20 6e 75         to the nu
100e0 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
100f0 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  in the result se
10100 74 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 69  t of the query i
10110 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  n the.**        
10120 20 20 73 71 6c 20 70 61 72 61 6d 65 74 65 72 2c    sql parameter,
10130 20 6f 72 20 74 6f 20 7a 65 72 6f 20 69 66 20 74   or to zero if t
10140 68 65 20 71 75 65 72 79 20 69 6e 20 73 71 6c 20  he query in sql 
10150 68 61 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20  has an empty.** 
10160 20 20 20 20 20 20 20 20 20 72 65 73 75 6c 74 20           result 
10170 73 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  set..*/.int sqli
10180 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20  te3_get_table(. 
10190 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20 20 20   sqlite3*,      
101a0 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65         /* An ope
101b0 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20  n database */.  
101c0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 2c  const char *sql,
101d0 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20        /* SQL to 
101e0 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a  be evaluated */.
101f0 20 20 63 68 61 72 20 2a 2a 2a 70 52 65 73 75 6c    char ***pResul
10200 74 2c 20 20 20 20 20 20 2f 2a 20 52 65 73 75 6c  t,      /* Resul
10210 74 73 20 6f 66 20 74 68 65 20 71 75 65 72 79 20  ts of the query 
10220 2a 2f 0a 20 20 69 6e 74 20 2a 6e 72 6f 77 2c 20  */.  int *nrow, 
10230 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75             /* Nu
10240 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 72  mber of result r
10250 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65 72 65  ows written here
10260 20 2a 2f 0a 20 20 69 6e 74 20 2a 6e 63 6f 6c 75   */.  int *ncolu
10270 6d 6e 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4e  mn,         /* N
10280 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20  umber of result 
10290 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e 20  columns written 
102a0 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a  here */.  char *
102b0 2a 65 72 72 6d 73 67 20 20 20 20 20 20 20 20 20  *errmsg         
102c0 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69  /* Error msg wri
102d0 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a  tten here */.);.
102e0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65  void sqlite3_fre
102f0 65 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72  e_table(char **r
10300 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  esult);../*.** C
10310 41 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74  API3REF: Formatt
10320 65 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69  ed String Printi
10330 6e 67 20 46 75 6e 63 74 69 6f 6e 73 20 7b 46 31  ng Functions {F1
10340 37 34 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  7400}.**.** Thes
10350 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77  e routines are w
10360 6f 72 6b 61 6c 69 6b 65 73 20 6f 66 20 74 68 65  orkalikes of the
10370 20 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69   "printf()" fami
10380 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a  ly of functions.
10390 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e  ** from the stan
103a0 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a  dard C library..
103b0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
103c0 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20  3_mprintf() and 
103d0 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66  sqlite3_vmprintf
103e0 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74  () routines writ
103f0 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c  e their.** resul
10400 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f  ts into memory o
10410 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
10420 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e  lite3_malloc()].
10430 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20  .** The strings 
10440 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73  returned by thes
10450 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73  e two routines s
10460 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65  hould be.** rele
10470 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  ased by [sqlite3
10480 5f 66 72 65 65 28 29 5d 2e 20 20 20 42 6f 74 68  _free()].   Both
10490 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
104a0 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74   a.** NULL point
104b0 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d  er if [sqlite3_m
104c0 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62  alloc()] is unab
104d0 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65  le to allocate e
104e0 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20  nough.** memory 
104f0 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75  to hold the resu
10500 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a  lting string..**
10510 0a 2a 2a 20 49 6e 20 73 71 6c 69 74 65 33 5f 73  .** In sqlite3_s
10520 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e  nprintf() routin
10530 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20  e is similar to 
10540 22 73 6e 70 72 69 6e 74 66 28 29 22 20 66 72 6f  "snprintf()" fro
10550 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72  m.** the standar
10560 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20 54 68  d C library.  Th
10570 65 20 72 65 73 75 6c 74 20 69 73 20 77 72 69 74  e result is writ
10580 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20  ten into the.** 
10590 62 75 66 66 65 72 20 73 75 70 70 6c 69 65 64 20  buffer supplied 
105a0 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  as the second pa
105b0 72 61 6d 65 74 65 72 20 77 68 6f 73 65 20 73 69  rameter whose si
105c0 7a 65 20 69 73 20 67 69 76 65 6e 20 62 79 0a 2a  ze is given by.*
105d0 2a 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  * the first para
105e0 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74 68 61 74  meter. Note that
105f0 20 74 68 65 20 6f 72 64 65 72 20 6f 66 20 74 68   the order of th
10600 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 70  e.** first two p
10610 61 72 61 6d 65 74 65 72 73 20 69 73 20 72 65 76  arameters is rev
10620 65 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 69  ersed from snpri
10630 6e 74 66 28 29 2e 20 20 54 68 69 73 20 69 73 20  ntf().  This is 
10640 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c  an.** historical
10650 20 61 63 63 69 64 65 6e 74 20 74 68 61 74 20 63   accident that c
10660 61 6e 6e 6f 74 20 62 65 20 66 69 78 65 64 20 77  annot be fixed w
10670 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a  ithout breaking.
10680 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  ** backwards com
10690 70 61 74 69 62 69 6c 69 74 79 2e 20 20 4e 6f 74  patibility.  Not
106a0 65 20 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69  e also that sqli
106b0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a  te3_snprintf().*
106c0 2a 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  * returns a poin
106d0 74 65 72 20 74 6f 20 69 74 73 20 62 75 66 66 65  ter to its buffe
106e0 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65  r instead of the
106f0 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68   number of.** ch
10700 61 72 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c  aracters actuall
10710 79 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74  y written into t
10720 68 65 20 62 75 66 66 65 72 2e 20 20 57 65 20 61  he buffer.  We a
10730 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 65  dmit that.** the
10740 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61   number of chara
10750 63 74 65 72 73 20 77 72 69 74 74 65 6e 20 77 6f  cters written wo
10760 75 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 75 73  uld be a more us
10770 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76  eful return.** v
10780 61 6c 75 65 20 62 75 74 20 77 65 20 63 61 6e 6e  alue but we cann
10790 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 69 6d  ot change the im
107a0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
107b0 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
107c0 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75  ().** now withou
107d0 74 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61  t breaking compa
107e0 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20  tibility..**.** 
107f0 41 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 62  As long as the b
10800 75 66 66 65 72 20 73 69 7a 65 20 69 73 20 67 72  uffer size is gr
10810 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c  eater than zero,
10820 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
10830 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65  f().** guarantee
10840 73 20 74 68 61 74 20 74 68 65 20 62 75 66 66 65  s that the buffe
10850 72 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f  r is always zero
10860 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 54 68  -terminated.  Th
10870 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d  e first.** param
10880 65 74 65 72 20 22 6e 22 20 69 73 20 74 68 65 20  eter "n" is the 
10890 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68  total size of th
108a0 65 20 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64  e buffer, includ
108b0 69 6e 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a  ing space for.**
108c0 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e   the zero termin
108d0 61 74 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f  ator.  So the lo
108e0 6e 67 65 73 74 20 73 74 72 69 6e 67 20 74 68 61  ngest string tha
108f0 74 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74  t can be complet
10900 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77  ely.** written w
10910 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61  ill be n-1 chara
10920 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  cters..**.** The
10930 73 65 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20  se routines all 
10940 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61  implement some a
10950 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74  dditional format
10960 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20  ting.** options 
10970 74 68 61 74 20 61 72 65 20 75 73 65 66 75 6c 20  that are useful 
10980 66 6f 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67  for constructing
10990 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e   SQL statements.
109a0 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75  .** All of the u
109b0 73 75 61 6c 20 70 72 69 6e 74 66 28 29 20 66 6f  sual printf() fo
109c0 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73  rmatting options
109d0 20 61 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69   apply.  In addi
109e0 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69  tion, there.** i
109f0 73 20 61 72 65 20 22 25 71 22 2c 20 22 25 51 22  s are "%q", "%Q"
10a00 2c 20 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f  , and "%z" optio
10a10 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 25 71  ns..**.** The %q
10a20 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69   option works li
10a30 6b 65 20 25 73 20 69 6e 20 74 68 61 74 20 69 74  ke %s in that it
10a40 20 73 75 62 73 74 69 74 75 74 65 73 20 61 20 6e   substitutes a n
10a50 75 6c 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ull-terminated.*
10a60 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68  * string from th
10a70 65 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e  e argument list.
10a80 20 20 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f    But %q also do
10a90 75 62 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27  ubles every '\''
10aa0 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25   character..** %
10ab0 71 20 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f  q is designed fo
10ac0 72 20 75 73 65 20 69 6e 73 69 64 65 20 61 20 73  r use inside a s
10ad0 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 20 20  tring literal.  
10ae0 42 79 20 64 6f 75 62 6c 69 6e 67 20 65 61 63 68  By doubling each
10af0 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63 74   '\''.** charact
10b00 65 72 20 69 74 20 65 73 63 61 70 65 73 20 74 68  er it escapes th
10b10 61 74 20 63 68 61 72 61 63 74 65 72 20 61 6e 64  at character and
10b20 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62 65   allows it to be
10b30 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a   inserted into.*
10b40 2a 20 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a  * the string..**
10b50 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  .** For example,
10b60 20 73 6f 20 73 6f 6d 65 20 73 74 72 69 6e 67 20   so some string 
10b70 76 61 72 69 61 62 6c 65 20 63 6f 6e 74 61 69 6e  variable contain
10b80 73 20 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77  s text as follow
10b90 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
10ba0 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63  uote><pre>.**  c
10bb0 68 61 72 20 2a 7a 54 65 78 74 20 3d 20 22 49 74  har *zText = "It
10bc0 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 22  's a happy day!"
10bd0 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
10be0 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f  ckquote>.**.** O
10bf0 6e 65 20 63 61 6e 20 75 73 65 20 74 68 69 73 20  ne can use this 
10c00 74 65 78 74 20 69 6e 20 61 6e 20 53 51 4c 20 73  text in an SQL s
10c10 74 61 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c  tatement as foll
10c20 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ows:.**.** <bloc
10c30 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
10c40 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71   char *zSQL = sq
10c50 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49  lite3_mprintf("I
10c60 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
10c70 20 56 41 4c 55 45 53 28 27 25 71 27 29 22 2c 20   VALUES('%q')", 
10c80 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69  zText);.**  sqli
10c90 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51  te3_exec(db, zSQ
10ca0 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20  L, 0, 0, 0);.** 
10cb0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53   sqlite3_free(zS
10cc0 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  QL);.** </pre></
10cd0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
10ce0 2a 20 42 65 63 61 75 73 65 20 74 68 65 20 25 71  * Because the %q
10cf0 20 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 69   format string i
10d00 73 20 75 73 65 64 2c 20 74 68 65 20 27 5c 27 27  s used, the '\''
10d10 20 63 68 61 72 61 63 74 65 72 20 69 6e 20 7a 54   character in zT
10d20 65 78 74 0a 2a 2a 20 69 73 20 65 73 63 61 70 65  ext.** is escape
10d30 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20 67 65  d and the SQL ge
10d40 6e 65 72 61 74 65 64 20 69 73 20 61 73 20 66 6f  nerated is as fo
10d50 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  llows:.**.** <bl
10d60 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
10d70 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74  *  INSERT INTO t
10d80 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74  able1 VALUES('It
10d90 27 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21  ''s a happy day!
10da0 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  ').** </pre></bl
10db0 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
10dc0 54 68 69 73 20 69 73 20 63 6f 72 72 65 63 74 2e  This is correct.
10dd0 20 20 48 61 64 20 77 65 20 75 73 65 64 20 25 73    Had we used %s
10de0 20 69 6e 73 74 65 61 64 20 6f 66 20 25 71 2c 20   instead of %q, 
10df0 74 68 65 20 67 65 6e 65 72 61 74 65 64 20 53 51  the generated SQ
10e00 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65 20  L.** would have 
10e10 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69 73  looked like this
10e20 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
10e30 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e  ote><pre>.**  IN
10e40 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31  SERT INTO table1
10e50 20 56 41 4c 55 45 53 28 27 49 74 27 73 20 61 20   VALUES('It's a 
10e60 68 61 70 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a  happy day!');.**
10e70 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
10e80 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ote>.**.** This 
10e90 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69  second example i
10ea0 73 20 61 6e 20 53 51 4c 20 73 79 6e 74 61 78 20  s an SQL syntax 
10eb0 65 72 72 6f 72 2e 20 20 41 73 20 61 20 67 65 6e  error.  As a gen
10ec0 65 72 61 6c 20 72 75 6c 65 20 79 6f 75 0a 2a 2a  eral rule you.**
10ed0 20 73 68 6f 75 6c 64 20 61 6c 77 61 79 73 20 75   should always u
10ee0 73 65 20 25 71 20 69 6e 73 74 65 61 64 20 6f 66  se %q instead of
10ef0 20 25 73 20 77 68 65 6e 20 69 6e 73 65 72 74 69   %s when inserti
10f00 6e 67 20 74 65 78 74 20 69 6e 74 6f 20 61 20 73  ng text into a s
10f10 74 72 69 6e 67 20 0a 2a 2a 20 6c 69 74 65 72 61  tring .** litera
10f20 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 25 51 20  l..**.** The %Q 
10f30 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b  option works lik
10f40 65 20 25 71 20 65 78 63 65 70 74 20 69 74 20 61  e %q except it a
10f50 6c 73 6f 20 61 64 64 73 20 73 69 6e 67 6c 65 20  lso adds single 
10f60 71 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a  quotes around.**
10f70 20 74 68 65 20 6f 75 74 73 69 64 65 20 6f 66 20   the outside of 
10f80 74 68 65 20 74 6f 74 61 6c 20 73 74 72 69 6e 67  the total string
10f90 2e 20 20 4f 72 20 69 66 20 74 68 65 20 70 61 72  .  Or if the par
10fa0 61 6d 65 74 65 72 20 69 6e 20 74 68 65 20 61 72  ameter in the ar
10fb0 67 75 6d 65 6e 74 0a 2a 2a 20 6c 69 73 74 20 69  gument.** list i
10fc0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
10fd0 2c 20 25 51 20 73 75 62 73 74 69 74 75 74 65 73  , %Q substitutes
10fe0 20 74 68 65 20 74 65 78 74 20 22 4e 55 4c 4c 22   the text "NULL"
10ff0 20 28 77 69 74 68 6f 75 74 20 73 69 6e 67 6c 65   (without single
11000 0a 2a 2a 20 71 75 6f 74 65 73 29 20 69 6e 20 70  .** quotes) in p
11010 6c 61 63 65 20 6f 66 20 74 68 65 20 25 51 20 6f  lace of the %Q o
11020 70 74 69 6f 6e 2e 20 7b 45 4e 44 7d 20 20 53 6f  ption. {END}  So
11030 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f  , for example, o
11040 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a  ne could say:.**
11050 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
11060 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a  <pre>.**  char *
11070 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d  zSQL = sqlite3_m
11080 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49  printf("INSERT I
11090 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53  NTO table VALUES
110a0 28 25 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a  (%Q)", zText);.*
110b0 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  *  sqlite3_exec(
110c0 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20  db, zSQL, 0, 0, 
110d0 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  0);.**  sqlite3_
110e0 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c  free(zSQL);.** <
110f0 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
11100 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64  e>.**.** The cod
11110 65 20 61 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e  e above will ren
11120 64 65 72 20 61 20 63 6f 72 72 65 63 74 20 53 51  der a correct SQ
11130 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74  L statement in t
11140 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61  he zSQL.** varia
11150 62 6c 65 20 65 76 65 6e 20 69 66 20 74 68 65 20  ble even if the 
11160 7a 54 65 78 74 20 76 61 72 69 61 62 6c 65 20 69  zText variable i
11170 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
11180 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 22 25 7a 22  ..**.** The "%z"
11190 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69   formatting opti
111a0 6f 6e 20 77 6f 72 6b 73 20 65 78 61 63 74 6c 79  on works exactly
111b0 20 6c 69 6b 65 20 22 25 73 22 20 77 69 74 68 20   like "%s" with 
111c0 74 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20  the.** addition 
111d0 74 68 61 74 20 61 66 74 65 72 20 74 68 65 20 73  that after the s
111e0 74 72 69 6e 67 20 68 61 73 20 62 65 65 6e 20 72  tring has been r
111f0 65 61 64 20 61 6e 64 20 63 6f 70 69 65 64 20 69  ead and copied i
11200 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c  nto.** the resul
11210 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  t, [sqlite3_free
11220 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e  ()] is called on
11230 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e   the input strin
11240 67 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 49  g. {END}.**.** I
11250 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
11260 20 7b 46 31 37 34 30 33 7d 20 20 54 68 65 20 5b   {F17403}  The [
11270 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
11280 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
11290 76 6d 70 72 69 6e 74 66 28 29 5d 20 69 6e 74 65  vmprintf()] inte
112a0 72 66 61 63 65 73 0a 2a 2a 20 20 20 20 20 20 20  rfaces.**       
112b0 20 20 20 20 72 65 74 75 72 6e 20 65 69 74 68 65      return eithe
112c0 72 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65  r pointers to ze
112d0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
112e0 46 2d 38 20 73 74 72 69 6e 67 73 20 68 65 6c 64  F-8 strings held
112f0 20 69 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   in.**          
11300 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
11310 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
11320 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 4e 55 4c 4c  alloc()] or NULL
11330 20 70 6f 69 6e 74 65 72 73 20 69 66 0a 2a 2a 20   pointers if.** 
11340 20 20 20 20 20 20 20 20 20 20 61 20 63 61 6c 6c            a call
11350 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   to [sqlite3_mal
11360 6c 6f 63 28 29 5d 20 66 61 69 6c 73 2e 0a 2a 2a  loc()] fails..**
11370 0a 2a 2a 20 7b 46 31 37 34 30 36 7d 20 20 54 68  .** {F17406}  Th
11380 65 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  e [sqlite3_snpri
11390 6e 74 66 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ntf()] interface
113a0 20 77 72 69 74 65 73 20 61 20 7a 65 72 6f 2d 74   writes a zero-t
113b0 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 20 20 20  erminated.**    
113c0 20 20 20 20 20 20 20 55 54 46 2d 38 20 73 74 72         UTF-8 str
113d0 69 6e 67 20 69 6e 74 6f 20 74 68 65 20 62 75 66  ing into the buf
113e0 66 65 72 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  fer pointed to b
113f0 79 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  y the second par
11400 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20 20 20  ameter.**       
11410 20 20 20 20 70 72 6f 76 69 64 65 64 20 74 68 61      provided tha
11420 74 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  t the first para
11430 6d 65 74 65 72 20 69 73 20 67 72 65 61 74 65 72  meter is greater
11440 20 74 68 61 6e 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a   than zero..**.*
11450 2a 20 7b 46 31 37 34 30 37 7d 20 20 54 68 65 20  * {F17407}  The 
11460 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  [sqlite3_snprint
11470 66 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64  f()] interface d
11480 6f 65 73 20 6e 6f 74 20 77 72 69 74 65 73 20 73  oes not writes s
11490 6c 6f 74 73 20 6f 66 0a 2a 2a 20 20 20 20 20 20  lots of.**      
114a0 20 20 20 20 20 69 74 73 20 6f 75 74 70 75 74 20       its output 
114b0 62 75 66 66 65 72 20 28 74 68 65 20 73 65 63 6f  buffer (the seco
114c0 6e 64 20 70 61 72 61 6d 65 74 65 72 29 20 6f 75  nd parameter) ou
114d0 74 73 69 64 65 20 74 68 65 20 72 61 6e 67 65 0a  tside the range.
114e0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6f 66 20  **           of 
114f0 30 20 74 68 72 6f 75 67 68 20 4e 2d 31 20 28 77  0 through N-1 (w
11500 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 66 69  here N is the fi
11510 72 73 74 20 70 61 72 61 6d 65 74 65 72 29 0a 2a  rst parameter).*
11520 2a 20 20 20 20 20 20 20 20 20 20 20 72 65 67 61  *           rega
11530 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20 6c 65  rdless of the le
11540 6e 67 74 68 20 6f 66 20 74 68 65 20 73 74 72 69  ngth of the stri
11550 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  ng.**           
11560 72 65 71 75 65 73 74 65 64 20 62 79 20 74 68 65  requested by the
11570 20 66 6f 72 6d 61 74 20 73 70 65 63 69 66 69 63   format specific
11580 61 74 69 6f 6e 2e 0a 2a 2a 20 20 20 0a 2a 2f 0a  ation..**   .*/.
11590 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70  char *sqlite3_mp
115a0 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72  rintf(const char
115b0 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71  *,...);.char *sq
115c0 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 63  lite3_vmprintf(c
115d0 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c  onst char*, va_l
115e0 69 73 74 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69  ist);.char *sqli
115f0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74  te3_snprintf(int
11600 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61  ,char*,const cha
11610 72 2a 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a  r*, ...);../*.**
11620 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72   CAPI3REF: Memor
11630 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62  y Allocation Sub
11640 73 79 73 74 65 6d 20 7b 46 31 37 33 30 30 7d 0a  system {F17300}.
11650 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65  **.** The SQLite
11660 20 63 6f 72 65 20 20 75 73 65 73 20 74 68 65 73   core  uses thes
11670 65 20 74 68 72 65 65 20 72 6f 75 74 69 6e 65 73  e three routines
11680 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20   for all of its 
11690 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20  own.** internal 
116a0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
116b0 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72 65 22 20  n needs. "Core" 
116c0 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  in the previous 
116d0 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73  sentence.** does
116e0 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f 70 65   not include ope
116f0 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70  rating-system sp
11700 65 63 69 66 69 63 20 56 46 53 20 69 6d 70 6c 65  ecific VFS imple
11710 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a  mentation.  The.
11720 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46 53 20 75  ** Windows VFS u
11730 73 65 73 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f  ses native mallo
11740 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 66  c() and free() f
11750 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f  or some operatio
11760 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ns..**.** The sq
11770 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72  lite3_malloc() r
11780 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61  outine returns a
11790 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 62 6c   pointer to a bl
117a0 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79  ock.** of memory
117b0 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65   at least N byte
117c0 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65  s in length, whe
117d0 72 65 20 4e 20 69 73 20 74 68 65 20 70 61 72 61  re N is the para
117e0 6d 65 74 65 72 2e 0a 2a 2a 20 49 66 20 73 71 6c  meter..** If sql
117f0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73  ite3_malloc() is
11800 20 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61 69   unable to obtai
11810 6e 20 73 75 66 66 69 63 69 65 6e 74 20 66 72 65  n sufficient fre
11820 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20  e.** memory, it 
11830 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70  returns a NULL p
11840 6f 69 6e 74 65 72 2e 20 20 49 66 20 74 68 65 20  ointer.  If the 
11850 70 61 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a  parameter N to.*
11860 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  * sqlite3_malloc
11870 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65  () is zero or ne
11880 67 61 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69  gative then sqli
11890 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74  te3_malloc() ret
118a0 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70  urns.** a NULL p
118b0 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 43 61  ointer..**.** Ca
118c0 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72  lling sqlite3_fr
118d0 65 65 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e  ee() with a poin
118e0 74 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72  ter previously r
118f0 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71  eturned.** by sq
11900 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f  lite3_malloc() o
11910 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  r sqlite3_reallo
11920 63 28 29 20 72 65 6c 65 61 73 65 73 20 74 68 61  c() releases tha
11930 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74  t memory so.** t
11940 68 61 74 20 69 74 20 6d 69 67 68 74 20 62 65 20  hat it might be 
11950 72 65 75 73 65 64 2e 20 20 54 68 65 20 73 71 6c  reused.  The sql
11960 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74  ite3_free() rout
11970 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f  ine is.** a no-o
11980 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77  p if is called w
11990 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ith a NULL point
119a0 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e  er.  Passing a N
119b0 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  ULL pointer.** t
119c0 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  o sqlite3_free()
119d0 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41   is harmless.  A
119e0 66 74 65 72 20 62 65 69 6e 67 20 66 72 65 65 64  fter being freed
119f0 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75  , memory.** shou
11a00 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20 72 65  ld neither be re
11a10 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20  ad nor written. 
11a20 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72   Even reading pr
11a30 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a  eviously freed.*
11a40 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72  * memory might r
11a50 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65  esult in a segme
11a60 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72  ntation fault or
11a70 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72   other severe er
11a80 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63  ror..** Memory c
11a90 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67  orruption, a seg
11aa0 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c  mentation fault,
11ab0 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65   or other severe
11ac0 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20   error.** might 
11ad0 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65  result if sqlite
11ae0 33 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c  3_free() is call
11af0 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55  ed with a non-NU
11b00 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a  LL pointer that.
11b10 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69  ** was not obtai
11b20 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ned from sqlite3
11b30 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c  _malloc() or sql
11b40 69 74 65 33 5f 66 72 65 65 28 29 2e 0a 2a 2a 0a  ite3_free()..**.
11b50 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
11b60 65 61 6c 6c 6f 63 28 29 20 69 6e 74 65 72 66 61  ealloc() interfa
11b70 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72  ce attempts to r
11b80 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72  esize a.** prior
11b90 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
11ba0 6f 6e 20 74 6f 20 62 65 20 61 74 20 6c 65 61 73  on to be at leas
11bb0 74 20 4e 20 62 79 74 65 73 2c 20 77 68 65 72 65  t N bytes, where
11bc0 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 73 65 63   N is the.** sec
11bd0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20  ond parameter.  
11be0 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  The memory alloc
11bf0 61 74 69 6f 6e 20 74 6f 20 62 65 20 72 65 73 69  ation to be resi
11c00 7a 65 64 20 69 73 20 74 68 65 20 66 69 72 73 74  zed is the first
11c10 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 20  .** parameter.  
11c20 49 66 20 74 68 65 20 66 69 72 73 74 20 70 61 72  If the first par
11c30 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
11c40 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69  3_realloc().** i
11c50 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
11c60 20 74 68 65 6e 20 69 74 73 20 62 65 68 61 76 69   then its behavi
11c70 6f 72 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20  or is identical 
11c80 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71  to calling.** sq
11c90 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20  lite3_malloc(N) 
11ca0 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73  where N is the s
11cb0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
11cc0 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  to sqlite3_reall
11cd0 6f 63 28 29 2e 0a 2a 2a 20 49 66 20 74 68 65 20  oc()..** If the 
11ce0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
11cf0 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   to sqlite3_real
11d00 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72  loc() is zero or
11d10 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65  .** negative the
11d20 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  n the behavior i
11d30 73 20 65 78 61 63 74 6c 79 20 74 68 65 20 73 61  s exactly the sa
11d40 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a  me as calling.**
11d50 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 50 29   sqlite3_free(P)
11d60 20 77 68 65 72 65 20 50 20 69 73 20 74 68 65 20   where P is the 
11d70 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
11d80 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  to sqlite3_reall
11d90 6f 63 28 29 2e 0a 2a 2a 20 53 71 6c 69 74 65 33  oc()..** Sqlite3
11da0 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72  _realloc() retur
11db0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
11dc0 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
11dd0 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61  ion.** of at lea
11de0 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69  st N bytes in si
11df0 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 73 75  ze or NULL if su
11e00 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20  fficient memory 
11e10 69 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a  is unavailable..
11e20 2a 2a 20 49 66 20 4d 20 69 73 20 74 68 65 20 73  ** If M is the s
11e30 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f 72  ize of the prior
11e40 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65   allocation, the
11e50 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73  n min(N,M) bytes
11e60 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f 72  .** of the prior
11e70 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20   allocation are 
11e80 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65 20  copied into the 
11e90 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66  beginning of buf
11ea0 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  fer returned.** 
11eb0 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  by sqlite3_reall
11ec0 6f 63 28 29 20 61 6e 64 20 74 68 65 20 70 72 69  oc() and the pri
11ed0 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73  or allocation is
11ee0 20 66 72 65 65 64 2e 0a 2a 2a 20 49 66 20 73 71   freed..** If sq
11ef0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
11f00 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74 68  returns NULL, th
11f10 65 6e 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c  en the prior all
11f20 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6e 6f  ocation.** is no
11f30 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  t freed..**.** T
11f40 68 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e  he memory return
11f50 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61  ed by sqlite3_ma
11f60 6c 6c 6f 63 28 29 20 61 6e 64 20 73 71 6c 69 74  lloc() and sqlit
11f70 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20  e3_realloc().** 
11f80 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e 65  is always aligne
11f90 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61 6e  d to at least an
11fa0 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79   8 byte boundary
11fb0 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68  . {END}.**.** Th
11fc0 65 20 64 65 66 61 75 6c 74 20 69 6d 70 6c 65 6d  e default implem
11fd0 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 74  entation.** of t
11fe0 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
11ff0 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 75  tion subsystem u
12000 73 65 73 20 74 68 65 20 6d 61 6c 6c 6f 63 28 29  ses the malloc()
12010 2c 20 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 61  , realloc().** a
12020 6e 64 20 66 72 65 65 28 29 20 70 72 6f 76 69 64  nd free() provid
12030 65 64 20 62 79 20 74 68 65 20 73 74 61 6e 64 61  ed by the standa
12040 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20 7b 46  rd C library. {F
12050 31 37 33 38 32 7d 20 48 6f 77 65 76 65 72 2c 20  17382} However, 
12060 69 66 20 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73  if .** SQLite is
12070 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74   compiled with t
12080 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 43 20 70  he following C p
12090 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
120a0 6f 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  o.**.** <blockqu
120b0 6f 74 65 3e 20 53 51 4c 49 54 45 5f 4d 45 4d 4f  ote> SQLITE_MEMO
120c0 52 59 5f 53 49 5a 45 3d 3c 69 3e 4e 4e 4e 3c 2f  RY_SIZE=<i>NNN</
120d0 69 3e 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  i> </blockquote>
120e0 0a 2a 2a 0a 2a 2a 20 77 68 65 72 65 20 3c 69 3e  .**.** where <i>
120f0 4e 4e 4e 3c 2f 69 3e 20 69 73 20 61 6e 20 69 6e  NNN</i> is an in
12100 74 65 67 65 72 2c 20 74 68 65 6e 20 53 51 4c 69  teger, then SQLi
12110 74 65 20 63 72 65 61 74 65 20 61 20 73 74 61 74  te create a stat
12120 69 63 0a 2a 2a 20 61 72 72 61 79 20 6f 66 20 61  ic.** array of a
12130 74 20 6c 65 61 73 74 20 3c 69 3e 4e 4e 4e 3c 2f  t least <i>NNN</
12140 69 3e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65  i> bytes in size
12150 20 61 6e 64 20 75 73 65 20 74 68 61 74 20 61 72   and use that ar
12160 72 61 79 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f  ray.** for all o
12170 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65  f its dynamic me
12180 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
12190 6e 65 65 64 73 2e 20 7b 45 4e 44 7d 20 20 41 64  needs. {END}  Ad
121a0 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 6d 65 6d 6f  ditional.** memo
121b0 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 6f 70 74  ry allocator opt
121c0 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65  ions may be adde
121d0 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
121e0 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53  ases..**.** In S
121f0 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
12200 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69  5.0 and 3.5.1, i
12210 74 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74  t was possible t
12220 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20  o define.** the 
12230 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f  SQLITE_OMIT_MEMO
12240 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68  RY_ALLOCATION wh
12250 69 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20  ich would cause 
12260 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20  the built-in.** 
12270 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
12280 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
12290 20 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20   to be omitted. 
122a0 20 54 68 61 74 20 63 61 70 61 62 69 6c 69 74 79   That capability
122b0 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72  .** is no longer
122c0 20 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79   provided.  Only
122d0 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79   built-in memory
122e0 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20   allocators can 
122f0 62 65 0a 2a 2a 20 75 73 65 64 2e 0a 2a 2a 0a 2a  be.** used..**.*
12300 2a 20 54 68 65 20 57 69 6e 64 6f 77 73 20 4f 53  * The Windows OS
12310 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72   interface layer
12320 20 63 61 6c 6c 73 0a 2a 2a 20 74 68 65 20 73 79   calls.** the sy
12330 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e  stem malloc() an
12340 64 20 66 72 65 65 28 29 20 64 69 72 65 63 74 6c  d free() directl
12350 79 20 77 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e  y when convertin
12360 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62  g.** filenames b
12370 65 74 77 65 65 6e 20 74 68 65 20 55 54 46 2d 38  etween the UTF-8
12380 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 62   encoding used b
12390 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20  y SQLite.** and 
123a0 77 68 61 74 65 76 65 72 20 66 69 6c 65 6e 61 6d  whatever filenam
123b0 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73  e encoding is us
123c0 65 64 20 62 79 20 74 68 65 20 70 61 72 74 69 63  ed by the partic
123d0 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20  ular Windows.** 
123e0 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d  installation.  M
123f0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
12400 20 65 72 72 6f 72 73 20 61 72 65 20 64 65 74 65   errors are dete
12410 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65  cted, but.** the
12420 79 20 61 72 65 20 72 65 70 6f 72 74 65 64 20 62  y are reported b
12430 61 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43  ack as [SQLITE_C
12440 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b  ANTOPEN] or.** [
12450 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61  SQLITE_IOERR] ra
12460 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
12470 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20  E_NOMEM]..**.** 
12480 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
12490 2a 20 7b 46 31 37 33 30 33 7d 20 20 54 68 65 20  * {F17303}  The 
124a0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
124b0 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  N)] interface re
124c0 74 75 72 6e 73 20 65 69 74 68 65 72 20 61 20 70  turns either a p
124d0 6f 69 6e 74 65 72 20 74 6f 20 0a 2a 2a 20 20 20  ointer to .**   
124e0 20 20 20 20 20 20 20 20 6e 65 77 6c 79 20 63 68          newly ch
124f0 65 63 6b 65 64 2d 6f 75 74 20 62 6c 6f 63 6b 20  ecked-out block 
12500 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79  of at least N by
12510 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a  tes of memory.**
12520 20 20 20 20 20 20 20 20 20 20 20 74 68 61 74 20             that 
12530 69 73 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65  is 8-byte aligne
12540 64 2c 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  d, .**          
12550 20 6f 72 20 69 74 20 72 65 74 75 72 6e 73 20 4e   or it returns N
12560 55 4c 4c 20 69 66 20 69 74 20 69 73 20 75 6e 61  ULL if it is una
12570 62 6c 65 20 74 6f 20 66 75 6c 66 69 6c 6c 20 74  ble to fulfill t
12580 68 65 20 72 65 71 75 65 73 74 2e 0a 2a 2a 0a 2a  he request..**.*
12590 2a 20 7b 46 31 37 33 30 34 7d 20 20 54 68 65 20  * {F17304}  The 
125a0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
125b0 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  N)] interface re
125c0 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69  turns a NULL poi
125d0 6e 74 65 72 20 69 66 0a 2a 2a 20 20 20 20 20 20  nter if.**      
125e0 20 20 20 20 20 4e 20 69 73 20 6c 65 73 73 20 74       N is less t
125f0 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20  han or equal to 
12600 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37  zero..**.** {F17
12610 33 30 35 7d 20 20 54 68 65 20 5b 73 71 6c 69 74  305}  The [sqlit
12620 65 33 5f 66 72 65 65 28 50 29 5d 20 69 6e 74 65  e3_free(P)] inte
12630 72 66 61 63 65 20 72 65 6c 65 61 73 65 73 20 6d  rface releases m
12640 65 6d 6f 72 79 20 70 72 65 76 69 6f 75 73 6c 79  emory previously
12650 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72 65  .**           re
12660 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  turned from [sql
12670 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f  ite3_malloc()] o
12680 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  r [sqlite3_reall
12690 6f 63 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  oc()],.**       
126a0 20 20 20 20 6d 61 6b 69 6e 67 20 69 74 20 61 76      making it av
126b0 61 69 6c 61 62 6c 65 20 66 6f 72 20 72 65 75 73  ailable for reus
126c0 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 30 36  e..**.** {F17306
126d0 7d 20 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73 71  }  A call to [sq
126e0 6c 69 74 65 33 5f 66 72 65 65 28 4e 55 4c 4c 29  lite3_free(NULL)
126f0 5d 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20  ] is a harmless 
12700 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  no-op..**.** {F1
12710 37 33 31 30 7d 20 20 41 20 63 61 6c 6c 20 74 6f  7310}  A call to
12720 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
12730 63 28 30 2c 4e 29 5d 20 69 73 20 65 71 75 69 76  c(0,N)] is equiv
12740 61 6c 65 6e 74 20 74 6f 20 61 20 63 61 6c 6c 0a  alent to a call.
12750 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 6f 20  **           to 
12760 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
12770 4e 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33  N)]..**.** {F173
12780 31 32 7d 20 20 41 20 63 61 6c 6c 20 74 6f 20 5b  12}  A call to [
12790 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
127a0 50 2c 30 29 5d 20 69 73 20 65 71 75 69 76 61 6c  P,0)] is equival
127b0 65 6e 74 20 74 6f 20 61 20 63 61 6c 6c 0a 2a 2a  ent to a call.**
127c0 20 20 20 20 20 20 20 20 20 20 20 74 6f 20 5b 73             to [s
127d0 71 6c 69 74 65 33 5f 66 72 65 65 28 50 29 5d 2e  qlite3_free(P)].
127e0 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 31 35 7d 20  .**.** {F17315} 
127f0 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
12800 20 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d   uses [sqlite3_m
12810 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74  alloc()], [sqlit
12820 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2c 0a 2a  e3_realloc()],.*
12830 2a 20 20 20 20 20 20 20 20 20 20 20 61 6e 64 20  *           and 
12840 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
12850 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20   for all of its 
12860 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
12870 6e 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20  n and.**        
12880 20 20 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 20     deallocation 
12890 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  needs..**.** {F1
128a0 37 33 31 38 7d 20 20 54 68 65 20 5b 73 71 6c 69  7318}  The [sqli
128b0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 50 2c 4e 29  te3_realloc(P,N)
128c0 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
128d0 72 6e 73 20 65 69 74 68 65 72 20 61 20 70 6f 69  rns either a poi
128e0 6e 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  nter.**         
128f0 20 20 74 6f 20 61 20 62 6c 6f 63 6b 20 6f 66 20    to a block of 
12900 63 68 65 63 6b 65 64 2d 6f 75 74 20 6d 65 6d 6f  checked-out memo
12910 72 79 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e  ry of at least N
12920 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 0a 2a   bytes in size.*
12930 2a 20 20 20 20 20 20 20 20 20 20 20 74 68 61 74  *           that
12940 20 69 73 20 38 2d 62 79 74 65 20 61 6c 69 67 6e   is 8-byte align
12950 65 64 2c 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f  ed, or a NULL po
12960 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  inter..**.** {F1
12970 37 33 32 31 7d 20 20 57 68 65 6e 20 5b 73 71 6c  7321}  When [sql
12980 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 50 2c 4e  ite3_realloc(P,N
12990 29 5d 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e  )] returns a non
129a0 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69  -NULL pointer, i
129b0 74 20 66 69 72 73 74 0a 2a 2a 20 20 20 20 20 20  t first.**      
129c0 20 20 20 20 20 63 6f 70 69 65 73 20 74 68 65 20       copies the 
129d0 66 69 72 73 74 20 4b 20 62 79 74 65 73 20 6f 66  first K bytes of
129e0 20 63 6f 6e 74 65 6e 74 20 66 72 6f 6d 20 50 20   content from P 
129f0 69 6e 74 6f 20 74 68 65 20 6e 65 77 6c 79 20 61  into the newly a
12a00 6c 6c 6f 63 61 74 65 64 0a 2a 2a 20 20 20 20 20  llocated.**     
12a10 20 20 20 20 20 20 77 68 65 72 65 20 4b 20 69 73        where K is
12a20 20 74 68 65 20 6c 65 73 73 65 72 20 6f 66 20 4e   the lesser of N
12a30 20 61 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66   and the size of
12a40 20 74 68 65 20 62 75 66 66 65 72 20 50 2e 0a 2a   the buffer P..*
12a50 2a 0a 2a 2a 20 7b 46 31 37 33 32 32 7d 20 20 57  *.** {F17322}  W
12a60 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 61  hen [sqlite3_rea
12a70 6c 6c 6f 63 28 50 2c 4e 29 5d 20 72 65 74 75 72  lloc(P,N)] retur
12a80 6e 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f  ns a non-NULL po
12a90 69 6e 74 65 72 2c 20 69 74 20 66 69 72 73 74 0a  inter, it first.
12aa0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72 65 6c  **           rel
12ab0 65 61 73 65 73 20 74 68 65 20 62 75 66 66 65 72  eases the buffer
12ac0 20 50 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 32   P..**.** {F1732
12ad0 33 7d 20 20 57 68 65 6e 20 5b 73 71 6c 69 74 65  3}  When [sqlite
12ae0 33 5f 72 65 61 6c 6c 6f 63 28 50 2c 4e 29 5d 20  3_realloc(P,N)] 
12af0 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74 68  returns NULL, th
12b00 65 20 62 75 66 66 65 72 20 50 20 69 73 0a 2a 2a  e buffer P is.**
12b10 20 20 20 20 20 20 20 20 20 20 20 6e 6f 74 20 6d             not m
12b20 6f 64 69 66 69 65 64 20 6f 72 20 72 65 6c 65 61  odified or relea
12b30 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49 54  sed..**.** LIMIT
12b40 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 55  ATIONS:.**.** {U
12b50 31 37 33 35 30 7d 20 20 54 68 65 20 70 6f 69 6e  17350}  The poin
12b60 74 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74 6f  ter arguments to
12b70 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
12b80 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72  ] and [sqlite3_r
12b90 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 20 20 20  ealloc()].**    
12ba0 20 20 20 20 20 20 20 6d 75 73 74 20 62 65 20 65         must be e
12bb0 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c  ither NULL or el
12bc0 73 65 20 61 20 70 6f 69 6e 74 65 72 20 6f 62 74  se a pointer obt
12bd0 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 70 72 69  ained from a pri
12be0 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  or.**           
12bf0 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73  invocation of [s
12c00 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
12c10 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61   or [sqlite3_rea
12c20 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61 73  lloc()] that has
12c30 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6e 6f  .**           no
12c40 74 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 2e  t been released.
12c50 0a 2a 2a 0a 2a 2a 20 7b 55 31 37 33 35 31 7d 20  .**.** {U17351} 
12c60 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
12c70 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 64 20 6f   must not read o
12c80 72 20 77 72 69 74 65 20 61 6e 79 20 70 61 72 74  r write any part
12c90 20 6f 66 20 0a 2a 2a 20 20 20 20 20 20 20 20 20   of .**         
12ca0 20 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d    a block of mem
12cb0 6f 72 79 20 61 66 74 65 72 20 69 74 20 68 61 73  ory after it has
12cc0 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75   been released u
12cd0 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20  sing.**         
12ce0 20 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28    [sqlite3_free(
12cf0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
12d00 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 0a 2a 2f  ealloc()]..**.*/
12d10 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d  .void *sqlite3_m
12d20 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64  alloc(int);.void
12d30 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   *sqlite3_reallo
12d40 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76  c(void*, int);.v
12d50 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65  oid sqlite3_free
12d60 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  (void*);../*.** 
12d70 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79  CAPI3REF: Memory
12d80 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74 69   Allocator Stati
12d90 73 74 69 63 73 20 7b 46 31 37 33 37 30 7d 0a 2a  stics {F17370}.*
12da0 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f 76  *.** SQLite prov
12db0 69 64 65 73 20 74 68 65 73 65 20 74 77 6f 20 69  ides these two i
12dc0 6e 74 65 72 66 61 63 65 73 20 66 6f 72 20 72 65  nterfaces for re
12dd0 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65 20 73  porting on the s
12de0 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20  tatus.** of the 
12df0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
12e00 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  )], [sqlite3_fre
12e10 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  e()], and [sqlit
12e20 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a  e3_realloc()].**
12e30 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
12e40 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d  cation subsystem
12e50 20 69 6e 63 6c 75 64 65 64 20 77 69 74 68 69 6e   included within
12e60 20 74 68 65 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a   the SQLite..**.
12e70 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
12e80 2a 0a 2a 2a 20 7b 46 31 37 33 37 31 7d 20 54 68  *.** {F17371} Th
12e90 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  e [sqlite3_memor
12ea0 79 5f 75 73 65 64 28 29 5d 20 72 6f 75 74 69 6e  y_used()] routin
12eb0 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a  e returns the.**
12ec0 20 20 20 20 20 20 20 20 20 20 6e 75 6d 62 65 72            number
12ed0 20 6f 66 20 62 79 74 65 73 20 6f 66 20 6d 65 6d   of bytes of mem
12ee0 6f 72 79 20 63 75 72 72 65 6e 74 6c 79 20 6f 75  ory currently ou
12ef0 74 73 74 61 6e 64 69 6e 67 20 0a 2a 2a 20 20 20  tstanding .**   
12f00 20 20 20 20 20 20 20 28 6d 61 6c 6c 6f 63 65 64         (malloced
12f10 20 62 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e   but not freed).
12f20 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 37 33 7d 20  .**.** {F17373} 
12f30 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  The [sqlite3_mem
12f40 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
12f50 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
12f60 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20   the maximum.** 
12f70 20 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 6f           value o
12f80 66 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  f [sqlite3_memor
12f90 79 5f 75 73 65 64 28 29 5d 20 0a 2a 2a 20 20 20  y_used()] .**   
12fa0 20 20 20 20 20 20 20 73 69 6e 63 65 20 74 68 65         since the
12fb0 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b   high-water mark
12fc0 20 77 61 73 20 6c 61 73 74 20 72 65 73 65 74 2e   was last reset.
12fd0 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 37 34 7d 20  .**.** {F17374} 
12fe0 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72  The values retur
12ff0 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
13000 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 61  memory_used()] a
13010 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  nd.**          [
13020 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
13030 69 67 68 77 61 74 65 72 28 29 5d 20 69 6e 63 6c  ighwater()] incl
13040 75 64 65 20 61 6e 79 20 6f 76 65 72 68 65 61 64  ude any overhead
13050 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 64 64  .**          add
13060 65 64 20 62 79 20 53 51 4c 69 74 65 20 69 6e 20  ed by SQLite in 
13070 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  its implementati
13080 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d  on of [sqlite3_m
13090 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 20 20 20  alloc()],.**    
130a0 20 20 20 20 20 20 62 75 74 20 6e 6f 74 20 6f 76        but not ov
130b0 65 72 68 65 61 64 20 61 64 64 65 64 20 62 79 20  erhead added by 
130c0 74 68 65 20 61 6e 79 20 75 6e 64 65 72 6c 79 69  the any underlyi
130d0 6e 67 20 73 79 73 74 65 6d 20 6c 69 62 72 61 72  ng system librar
130e0 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 6f  y.**          ro
130f0 75 74 69 6e 65 73 20 74 68 61 74 20 5b 73 71 6c  utines that [sql
13100 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d  ite3_malloc()] m
13110 61 79 20 63 61 6c 6c 2e 0a 2a 2a 20 0a 2a 2a 20  ay call..** .** 
13120 7b 46 31 37 33 37 35 7d 20 54 68 65 20 6d 65 6d  {F17375} The mem
13130 6f 72 79 20 68 69 67 68 2d 77 61 74 65 72 20 6d  ory high-water m
13140 61 72 6b 20 69 73 20 72 65 73 65 74 20 74 6f 20  ark is reset to 
13150 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75  the current valu
13160 65 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20  e of.**         
13170 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
13180 5f 75 73 65 64 28 29 5d 20 69 66 20 61 6e 64 20  _used()] if and 
13190 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 61 72 61  only if the para
131a0 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 20 20 20 20  meter to.**     
131b0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6d 65       [sqlite3_me
131c0 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
131d0 5d 20 69 73 20 74 72 75 65 2e 20 20 54 68 65 20  ] is true.  The 
131e0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a  value returned.*
131f0 2a 20 20 20 20 20 20 20 20 20 20 62 79 20 5b 73  *          by [s
13200 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
13210 67 68 77 61 74 65 72 28 31 29 5d 20 69 73 20 74  ghwater(1)] is t
13220 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61  he high-water ma
13230 72 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70  rk.**          p
13240 72 69 6f 72 20 74 6f 20 74 68 65 20 72 65 73 65  rior to the rese
13250 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e  t..*/.sqlite3_in
13260 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  t64 sqlite3_memo
13270 72 79 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 73  ry_used(void);.s
13280 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
13290 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
132a0 77 61 74 65 72 28 69 6e 74 20 72 65 73 65 74 46  water(int resetF
132b0 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  lag);../*.** CAP
132c0 49 33 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 61  I3REF: Pseudo-Ra
132d0 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65  ndom Number Gene
132e0 72 61 74 6f 72 20 7b 46 31 37 33 39 30 7d 0a 2a  rator {F17390}.*
132f0 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74  *.** SQLite cont
13300 61 69 6e 73 20 61 20 68 69 67 68 2d 71 75 61 6c  ains a high-qual
13310 69 74 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f  ity pseudo-rando
13320 6d 20 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 74  m number generat
13330 6f 72 20 28 50 52 4e 47 29 20 75 73 65 64 20 74  or (PRNG) used t
13340 6f 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e 64  o.** select rand
13350 6f 6d 20 52 4f 57 49 44 73 20 77 68 65 6e 20 69  om ROWIDs when i
13360 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65 63  nserting new rec
13370 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62 6c  ords into a tabl
13380 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64  e that.** alread
13390 79 20 75 73 65 73 20 74 68 65 20 6c 61 72 67 65  y uses the large
133a0 73 74 20 70 6f 73 73 69 62 6c 65 20 52 4f 57 49  st possible ROWI
133b0 44 2e 20 20 54 68 65 20 50 52 4e 47 20 69 73 20  D.  The PRNG is 
133c0 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a 2a  also used for.**
133d0 20 74 68 65 20 62 75 69 6c 64 2d 69 6e 20 72 61   the build-in ra
133e0 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64 6f  ndom() and rando
133f0 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e 63  mblob() SQL func
13400 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e 74  tions.  This int
13410 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a  erface allows.**
13420 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 6f   applications to
13430 20 61 63 63 65 73 73 20 74 68 65 20 73 61 6d 65   access the same
13440 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 65 72 20   PRNG for other 
13450 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20  purposes..**.** 
13460 41 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72  A call to this r
13470 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20 4e 20  outine stores N 
13480 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e  bytes of randomn
13490 65 73 73 20 69 6e 74 6f 20 62 75 66 66 65 72 20  ess into buffer 
134a0 50 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  P..**.** The fir
134b0 73 74 20 74 69 6d 65 20 74 68 69 73 20 72 6f 75  st time this rou
134c0 74 69 6e 65 20 69 73 20 69 6e 76 6f 6b 65 64 20  tine is invoked 
134d0 28 65 69 74 68 65 72 20 69 6e 74 65 72 6e 61 6c  (either internal
134e0 6c 79 20 6f 72 20 62 79 0a 2a 2a 20 74 68 65 20  ly or by.** the 
134f0 61 70 70 6c 69 63 61 74 69 6f 6e 29 20 74 68 65  application) the
13500 20 50 52 4e 47 20 69 73 20 73 65 65 64 65 64 20   PRNG is seeded 
13510 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73  using randomness
13520 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
13530 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  m the xRandomnes
13540 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20  s method of the 
13550 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
13560 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  _vfs] object..**
13570 20 4f 6e 20 61 6c 6c 20 73 75 62 73 65 71 75 65   On all subseque
13580 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73 2c 20  nt invocations, 
13590 74 68 65 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f  the pseudo-rando
135a0 6d 6e 65 73 73 20 69 73 20 67 65 6e 65 72 61 74  mness is generat
135b0 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79  ed.** internally
135c0 20 61 6e 64 20 77 69 74 68 6f 75 74 20 72 65 63   and without rec
135d0 6f 75 72 73 65 20 74 6f 20 74 68 65 20 5b 73 71  ourse to the [sq
135e0 6c 69 74 65 33 5f 76 66 73 5d 20 78 52 61 6e 64  lite3_vfs] xRand
135f0 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64  omness.** method
13600 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
13610 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 39  TS:.**.** {F1739
13620 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  2} The [sqlite3_
13630 72 61 6e 64 6f 6d 6e 65 73 73 28 4e 2c 50 29 5d  randomness(N,P)]
13640 20 69 6e 74 65 72 66 61 63 65 20 77 72 69 74 65   interface write
13650 73 20 4e 20 62 79 74 65 73 20 6f 66 0a 2a 2a 20  s N bytes of.** 
13660 20 20 20 20 20 20 20 20 20 68 69 67 68 2d 71 75           high-qu
13670 61 6c 69 74 79 20 70 73 65 75 64 6f 2d 72 61 6e  ality pseudo-ran
13680 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66  domness into buf
13690 66 65 72 20 50 2e 0a 2a 2f 0a 76 6f 69 64 20 73  fer P..*/.void s
136a0 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73  qlite3_randomnes
136b0 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50  s(int N, void *P
136c0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
136d0 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65  EF: Compile-Time
136e0 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43   Authorization C
136f0 61 6c 6c 62 61 63 6b 73 20 7b 46 31 32 35 30 30  allbacks {F12500
13700 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  }.**.** This rou
13710 74 69 6e 65 20 72 65 67 69 73 74 65 72 73 20 61  tine registers a
13720 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
13730 62 61 63 6b 20 77 69 74 68 20 61 20 70 61 72 74  back with a part
13740 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62  icular.** [datab
13750 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c  ase connection],
13760 20 73 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65   supplied in the
13770 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e   first argument.
13780 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a  .** The authoriz
13790 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  er callback is i
137a0 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74  nvoked as SQL st
137b0 61 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69  atements are bei
137c0 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62  ng compiled.** b
137d0 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  y [sqlite3_prepa
137e0 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72  re()] or its var
137f0 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70  iants [sqlite3_p
13800 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a  repare_v2()],.**
13810 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
13820 65 31 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  e16()] and [sqli
13830 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
13840 28 29 5d 2e 20 20 41 74 20 76 61 72 69 6f 75 73  ()].  At various
13850 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72 69 6e  .** points durin
13860 67 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f  g the compilatio
13870 6e 20 70 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f  n process, as lo
13880 67 69 63 20 69 73 20 62 65 69 6e 67 20 63 72 65  gic is being cre
13890 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f  ated.** to perfo
138a0 72 6d 20 76 61 72 69 6f 75 73 20 61 63 74 69 6f  rm various actio
138b0 6e 73 2c 20 74 68 65 20 61 75 74 68 6f 72 69 7a  ns, the authoriz
138c0 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  er callback is i
138d0 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65  nvoked to.** see
138e0 20 69 66 20 74 68 6f 73 65 20 61 63 74 69 6f 6e   if those action
138f0 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20  s are allowed.  
13900 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  The authorizer c
13910 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a  allback should.*
13920 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  * return [SQLITE
13930 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68  _OK] to allow th
13940 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54  e action, [SQLIT
13950 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73  E_IGNORE] to dis
13960 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65  allow the.** spe
13970 63 69 66 69 63 20 61 63 74 69 6f 6e 20 62 75 74  cific action but
13980 20 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 73   allow the SQL s
13990 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74  tatement to cont
139a0 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f  inue to be.** co
139b0 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49  mpiled, or [SQLI
139c0 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 73  TE_DENY] to caus
139d0 65 20 74 68 65 20 65 6e 74 69 72 65 20 53 51 4c  e the entire SQL
139e0 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65   statement to be
139f0 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20 77 69 74  .** rejected wit
13a00 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 20 49 66  h an error.   If
13a10 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
13a20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
13a30 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f 74  .** any value ot
13a40 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
13a50 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54  _IGNORE], [SQLIT
13a60 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  E_OK], or [SQLIT
13a70 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20  E_DENY].** then 
13a80 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
13a90 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61  _v2()] or equiva
13aa0 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74  lent call that t
13ab0 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 68 65 20  riggered.** the 
13ac0 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20  authorizer will 
13ad0 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72  fail with an err
13ae0 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a  or message..**.*
13af0 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62  * When the callb
13b00 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ack returns [SQL
13b10 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65  ITE_OK], that me
13b20 61 6e 73 20 74 68 65 20 6f 70 65 72 61 74 69 6f  ans the operatio
13b30 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 69  n.** requested i
13b40 73 20 6f 6b 2e 20 20 57 68 65 6e 20 74 68 65 20  s ok.  When the 
13b50 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
13b60 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20   [SQLITE_DENY], 
13b70 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
13b80 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
13b90 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c   equivalent call
13ba0 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64 20   that triggered 
13bb0 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65  the.** authorize
13bc0 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68  r will fail with
13bd0 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   an error messag
13be0 65 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61  e explaining tha
13bf0 74 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 20 64  t.** access is d
13c00 65 6e 69 65 64 2e 20 20 49 66 20 74 68 65 20 61  enied.  If the a
13c10 75 74 68 6f 72 69 7a 65 72 20 63 6f 64 65 20 69  uthorizer code i
13c20 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a  s [SQLITE_READ].
13c30 2a 2a 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62  ** and the callb
13c40 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ack returns [SQL
13c50 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e  ITE_IGNORE] then
13c60 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
13c70 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 74 61  d statement] sta
13c80 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72  tement is constr
13c90 75 63 74 65 64 20 74 6f 20 73 75 62 73 74 69 74  ucted to substit
13ca0 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61  ute.** a NULL va
13cb0 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20  lue in place of 
13cc0 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  the table column
13cd0 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65   that would have
13ce0 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 69 66  .** been read if
13cf0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64   [SQLITE_OK] had
13d00 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 20   been returned. 
13d10 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e   The [SQLITE_IGN
13d20 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63  ORE].** return c
13d30 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64 65  an be used to de
13d40 6e 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20  ny an untrusted 
13d50 75 73 65 72 20 61 63 63 65 73 73 20 74 6f 20 69  user access to i
13d60 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c  ndividual.** col
13d70 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65 2e  umns of a table.
13d80 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
13d90 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
13da0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
13db0 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20  lback is a copy 
13dc0 6f 66 0a 2a 2a 20 74 68 65 20 74 68 69 72 64 20  of.** the third 
13dd0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
13de0 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74   sqlite3_set_aut
13df0 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66  horizer() interf
13e00 61 63 65 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f  ace..** The seco
13e10 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
13e20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  the callback is 
13e30 61 6e 20 69 6e 74 65 67 65 72 20 0a 2a 2a 20 5b  an integer .** [
13e40 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63  SQLITE_COPY | ac
13e50 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20  tion code] that 
13e60 73 70 65 63 69 66 69 65 73 20 74 68 65 20 70 61  specifies the pa
13e70 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 0a  rticular action.
13e80 2a 2a 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69  ** to be authori
13e90 7a 65 64 2e 20 54 68 65 20 74 68 69 72 64 20 74  zed. The third t
13ea0 68 72 6f 75 67 68 20 73 69 78 74 68 0a 2a 2a 20  hrough sixth.** 
13eb0 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68  parameters to th
13ec0 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a  e callback are z
13ed0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73  ero-terminated s
13ee0 74 72 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74  trings that cont
13ef0 61 69 6e 20 0a 2a 2a 20 61 64 64 69 74 69 6f 6e  ain .** addition
13f00 61 6c 20 64 65 74 61 69 6c 73 20 61 62 6f 75 74  al details about
13f10 20 74 68 65 20 61 63 74 69 6f 6e 20 74 6f 20 62   the action to b
13f20 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a  e authorized..**
13f30 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a 65  .** An authorize
13f40 72 20 69 73 20 75 73 65 64 20 77 68 65 6e 20 5b  r is used when [
13f50 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20  sqlite3_prepare 
13f60 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20  | preparing].** 
13f70 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 66  SQL statements f
13f80 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74 65 64  rom an untrusted
13f90 0a 2a 2a 20 73 6f 75 72 63 65 2c 20 74 6f 20 65  .** source, to e
13fa0 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20 53  nsure that the S
13fb0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 64 6f  QL statements do
13fc0 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 63 63 65   not try to acce
13fd0 73 73 20 64 61 74 61 0a 2a 2a 20 74 68 61 74 20  ss data.** that 
13fe0 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c  they are not all
13ff0 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 20  owed to see, or 
14000 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74  that they do not
14010 20 74 72 79 20 74 6f 0a 2a 2a 20 65 78 65 63 75   try to.** execu
14020 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 61  te malicious sta
14030 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64 61 6d  tements that dam
14040 61 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65  age the database
14050 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c  .  For.** exampl
14060 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  e, an applicatio
14070 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 73  n may allow a us
14080 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72 62 69  er to enter arbi
14090 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65  trary.** SQL que
140a0 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75 61 74  ries for evaluat
140b0 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62 61 73  ion by a databas
140c0 65 2e 20 20 42 75 74 20 74 68 65 20 61 70 70 6c  e.  But the appl
140d0 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20  ication does.** 
140e0 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75 73 65  not want the use
140f0 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f 20  r to be able to 
14100 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79 20 63  make arbitrary c
14110 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a  hanges to the.**
14120 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e 20 61   database.  An a
14130 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20  uthorizer could 
14140 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e 20 70  then be put in p
14150 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65 0a 2a  lace while the.*
14160 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53  * user-entered S
14170 51 4c 20 69 73 20 62 65 69 6e 67 20 5b 73 71 6c  QL is being [sql
14180 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70  ite3_prepare | p
14190 72 65 70 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a  repared] that.**
141a0 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 79   disallows every
141b0 74 68 69 6e 67 20 65 78 63 65 70 74 20 5b 53 45  thing except [SE
141c0 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 73  LECT] statements
141d0 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74  ..**.** Applicat
141e0 69 6f 6e 73 20 74 68 61 74 20 6e 65 65 64 20 74  ions that need t
141f0 6f 20 70 72 6f 63 65 73 73 20 53 51 4c 20 66 72  o process SQL fr
14200 6f 6d 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75  om untrusted sou
14210 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c  rces.** might al
14220 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65  so consider lowe
14230 72 69 6e 67 20 72 65 73 6f 75 72 63 65 20 6c 69  ring resource li
14240 6d 69 74 73 20 75 73 69 6e 67 20 5b 73 71 6c 69  mits using [sqli
14250 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20  te3_limit()].** 
14260 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64 61 74  and limiting dat
14270 61 62 61 73 65 20 73 69 7a 65 20 75 73 69 6e 67  abase size using
14280 20 74 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63   the [max_page_c
14290 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a  ount] [PRAGMA].*
142a0 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f  * in addition to
142b0 20 75 73 69 6e 67 20 61 6e 20 61 75 74 68 6f 72   using an author
142c0 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 6c 79  izer..**.** Only
142d0 20 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72   a single author
142e0 69 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70  izer can be in p
142f0 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61  lace on a databa
14300 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
14310 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63   at a time.  Eac
14320 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  h call to sqlite
14330 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
14340 20 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a   overrides the.*
14350 2a 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e  * previous call.
14360 20 20 44 69 73 61 62 6c 65 20 74 68 65 20 61 75    Disable the au
14370 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 74  thorizer by inst
14380 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61  alling a NULL ca
14390 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61  llback..** The a
143a0 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69 73  uthorizer is dis
143b0 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
143c0 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
143d0 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  t the authorizer
143e0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
143f0 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67  oked only during
14400 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72   .** [sqlite3_pr
14410 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20  epare()] or its 
14420 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f  variants.  Autho
14430 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a  rization is not.
14440 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72  ** performed dur
14450 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76  ing statement ev
14460 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c  aluation in [sql
14470 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a  ite3_step()]..**
14480 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
14490 2a 2a 0a 2a 2a 20 7b 46 31 32 35 30 31 7d 20 54  **.** {F12501} T
144a0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  he [sqlite3_set_
144b0 61 75 74 68 6f 72 69 7a 65 72 28 44 2c 2e 2e 2e  authorizer(D,...
144c0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67  )] interface reg
144d0 69 73 74 65 72 73 20 61 0a 2a 2a 20 20 20 20 20  isters a.**     
144e0 20 20 20 20 20 61 75 74 68 6f 72 69 7a 65 72 20       authorizer 
144f0 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 64 61  callback with da
14500 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
14510 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35  n D..**.** {F125
14520 30 32 7d 20 54 68 65 20 61 75 74 68 6f 72 69 7a  02} The authoriz
14530 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  er callback is i
14540 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74  nvoked as SQL st
14550 61 74 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a 20  atements are.** 
14560 20 20 20 20 20 20 20 20 20 62 65 69 6e 67 20 63           being c
14570 6f 6d 70 69 6c 65 64 0a 2a 2a 0a 2a 2a 20 7b 46  ompiled.**.** {F
14580 31 32 35 30 33 7d 20 49 66 20 74 68 65 20 61 75  12503} If the au
14590 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
145a0 6b 20 72 65 74 75 72 6e 73 20 61 6e 79 20 76 61  k returns any va
145b0 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e 0a 2a  lue other than.*
145c0 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49  *          [SQLI
145d0 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c  TE_IGNORE], [SQL
145e0 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c  ITE_OK], or [SQL
145f0 49 54 45 5f 44 45 4e 59 5d 20 74 68 65 6e 0a 2a  ITE_DENY] then.*
14600 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b  *          the [
14610 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
14620 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c  v2()] or equival
14630 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 63 61  ent call that ca
14640 75 73 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  used.**         
14650 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
14660 63 61 6c 6c 62 61 63 6b 20 74 6f 20 72 75 6e 20  callback to run 
14670 73 68 61 6c 6c 20 66 61 69 6c 20 77 69 74 68 20  shall fail with 
14680 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  an.**          [
14690 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 65 72  SQLITE_ERROR] er
146a0 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 61 6e 20  ror code and an 
146b0 61 70 70 72 6f 70 72 69 61 74 65 20 65 72 72 6f  appropriate erro
146c0 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a  r message..**.**
146d0 20 7b 46 31 32 35 30 34 7d 20 57 68 65 6e 20 74   {F12504} When t
146e0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
146f0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b  llback returns [
14700 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 65 20  SQLITE_OK], the 
14710 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 20 20 20  operation.**    
14720 20 20 20 20 20 20 64 65 73 63 72 69 62 65 64 20        described 
14730 69 73 20 63 6f 64 65 64 20 6e 6f 72 6d 61 6c 6c  is coded normall
14740 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 30 35  y..**.** {F12505
14750 7d 20 57 68 65 6e 20 74 68 65 20 61 75 74 68 6f  } When the autho
14760 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72  rizer callback r
14770 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44  eturns [SQLITE_D
14780 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 20 20 20  ENY], the.**    
14790 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 70        [sqlite3_p
147a0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
147b0 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20  equivalent call 
147c0 74 68 61 74 20 63 61 75 73 65 64 20 74 68 65 0a  that caused the.
147d0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 75 74 68  **          auth
147e0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
147f0 74 6f 20 72 75 6e 20 73 68 61 6c 6c 20 66 61 69  to run shall fai
14800 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69  l.**          wi
14810 74 68 20 61 6e 20 5b 53 51 4c 49 54 45 5f 45 52  th an [SQLITE_ER
14820 52 4f 52 5d 20 65 72 72 6f 72 20 63 6f 64 65 20  ROR] error code 
14830 61 6e 64 20 61 6e 20 65 72 72 6f 72 20 6d 65 73  and an error mes
14840 73 61 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  sage.**         
14850 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74   explaining that
14860 20 61 63 63 65 73 73 20 69 73 20 64 65 6e 69 65   access is denie
14870 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 30 36  d..**.** {F12506
14880 7d 20 49 66 20 74 68 65 20 61 75 74 68 6f 72 69  } If the authori
14890 7a 65 72 20 63 6f 64 65 20 28 74 68 65 20 32 6e  zer code (the 2n
148a0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
148b0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 0a 2a 2a  he authorizer.**
148c0 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c 62 61            callba
148d0 63 6b 29 20 69 73 20 5b 53 51 4c 49 54 45 5f 52  ck) is [SQLITE_R
148e0 45 41 44 5d 20 61 6e 64 20 74 68 65 20 61 75 74  EAD] and the aut
148f0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
14900 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20   returns.**     
14910 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 49 47 4e       [SQLITE_IGN
14920 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 20 70 72  ORE] then the pr
14930 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
14940 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65 64 20   is constructed 
14950 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  to.**          i
14960 6e 73 65 72 74 20 61 20 4e 55 4c 4c 20 76 61 6c  nsert a NULL val
14970 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74  ue in place of t
14980 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20  he table column 
14990 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a  that would have.
149a0 2a 2a 20 20 20 20 20 20 20 20 20 20 62 65 65 6e  **          been
149b0 20 72 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45   read if [SQLITE
149c0 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65  _OK] had been re
149d0 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46  turned..**.** {F
149e0 31 32 35 30 37 7d 20 49 66 20 74 68 65 20 61 75  12507} If the au
149f0 74 68 6f 72 69 7a 65 72 20 63 6f 64 65 20 28 74  thorizer code (t
14a00 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
14a10 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
14a20 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63  er.**          c
14a30 61 6c 6c 62 61 63 6b 29 20 69 73 20 61 6e 79 74  allback) is anyt
14a40 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20  hing other than 
14a50 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 2c 20 74  [SQLITE_READ], t
14a60 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  hen.**          
14a70 61 20 72 65 74 75 72 6e 20 6f 66 20 5b 53 51 4c  a return of [SQL
14a80 49 54 45 5f 49 47 4e 4f 52 45 5d 20 68 61 73 20  ITE_IGNORE] has 
14a90 74 68 65 20 73 61 6d 65 20 65 66 66 65 63 74 20  the same effect 
14aa0 61 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d  as [SQLITE_DENY]
14ab0 2e 20 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 31 30  . .**.** {F12510
14ac0 7d 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61  } The first para
14ad0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74  meter to the aut
14ae0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
14af0 20 69 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a   is a copy of.**
14b00 20 20 20 20 20 20 20 20 20 20 74 68 65 20 74 68            the th
14b10 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
14b20 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65   the [sqlite3_se
14b30 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20  t_authorizer()] 
14b40 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
14b50 20 7b 46 31 32 35 31 31 7d 20 54 68 65 20 73 65   {F12511} The se
14b60 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74  cond parameter t
14b70 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  o the callback i
14b80 73 20 61 6e 20 69 6e 74 65 67 65 72 20 0a 2a 2a  s an integer .**
14b90 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54            [SQLIT
14ba0 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20  E_COPY | action 
14bb0 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63 69  code] that speci
14bc0 66 69 65 73 20 74 68 65 20 70 61 72 74 69 63 75  fies the particu
14bd0 6c 61 72 20 61 63 74 69 6f 6e 0a 2a 2a 20 20 20  lar action.**   
14be0 20 20 20 20 20 20 20 74 6f 20 62 65 20 61 75 74         to be aut
14bf0 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b  horized..**.** {
14c00 46 31 32 35 31 32 7d 20 54 68 65 20 74 68 69 72  F12512} The thir
14c10 64 20 74 68 72 6f 75 67 68 20 73 69 78 74 68 20  d through sixth 
14c20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68  parameters to th
14c30 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 0a 2a  e callback are.*
14c40 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 2d  *          zero-
14c50 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e  terminated strin
14c60 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20  gs that contain 
14c70 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 64 64  .**          add
14c80 69 74 69 6f 6e 61 6c 20 64 65 74 61 69 6c 73 20  itional details 
14c90 61 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e  about the action
14ca0 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65   to be authorize
14cb0 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 32 30  d..**.** {F12520
14cc0 7d 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 5b  } Each call to [
14cd0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
14ce0 6f 72 69 7a 65 72 28 29 5d 20 6f 76 65 72 72 69  orizer()] overri
14cf0 64 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  des the.**      
14d00 20 20 20 20 61 6e 79 20 70 72 65 76 69 6f 75 73      any previous
14d10 6c 79 20 69 6e 73 74 61 6c 6c 65 64 20 61 75 74  ly installed aut
14d20 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b  horizer..**.** {
14d30 46 31 32 35 32 31 7d 20 41 20 4e 55 4c 4c 20 61  F12521} A NULL a
14d40 75 74 68 6f 72 69 7a 65 72 20 6d 65 61 6e 73 20  uthorizer means 
14d50 74 68 61 74 20 6e 6f 20 61 75 74 68 6f 72 69 7a  that no authoriz
14d60 61 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20  ation.**        
14d70 20 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e    callback is in
14d80 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  voked..**.** {F1
14d90 32 35 32 32 7d 20 54 68 65 20 64 65 66 61 75 6c  2522} The defaul
14da0 74 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20  t authorizer is 
14db0 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  NULL..*/.int sql
14dc0 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
14dd0 7a 65 72 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  zer(.  sqlite3*,
14de0 0a 20 20 69 6e 74 20 28 2a 78 41 75 74 68 29 28  .  int (*xAuth)(
14df0 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
14e00 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
14e10 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f  *,const char*,co
14e20 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f  nst char*),.  vo
14e30 69 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29 3b  id *pUserData.);
14e40 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
14e50 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 52 65 74  : Authorizer Ret
14e60 75 72 6e 20 43 6f 64 65 73 20 7b 46 31 32 35 39  urn Codes {F1259
14e70 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71  0}.**.** The [sq
14e80 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
14e90 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65  izer | authorize
14ea0 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  r callback funct
14eb0 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74  ion] must.** ret
14ec0 75 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49  urn either [SQLI
14ed0 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66  TE_OK] or one of
14ee0 20 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74   these two const
14ef0 61 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a  ants in order.**
14f00 20 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74   to signal SQLit
14f10 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  e whether or not
14f20 20 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70   the action is p
14f30 65 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74  ermitted.  See t
14f40 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  he.** [sqlite3_s
14f50 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20  et_authorizer | 
14f60 61 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d  authorizer docum
14f70 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64  entation] for ad
14f80 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f  ditional.** info
14f90 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 23 64 65 66  rmation..*/.#def
14fa0 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e 59 20  ine SQLITE_DENY 
14fb0 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 74 20 74    1   /* Abort t
14fc0 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
14fd0 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 2a   with an error *
14fe0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
14ff0 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44  _IGNORE 2   /* D
15000 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63 65 73  on't allow acces
15010 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 67 65 6e  s, but don't gen
15020 65 72 61 74 65 20 61 6e 20 65 72 72 6f 72 20 2a  erate an error *
15030 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
15040 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 41 63  F: Authorizer Ac
15050 74 69 6f 6e 20 43 6f 64 65 73 20 7b 46 31 32 35  tion Codes {F125
15060 35 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73  50}.**.** The [s
15070 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
15080 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61  rizer()] interfa
15090 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63  ce registers a c
150a0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
150b0 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f  .** that is invo
150c0 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65  ked to authorize
150d0 72 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74  r certain SQL st
150e0 61 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e  atement actions.
150f0 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20    The.** second 
15100 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
15110 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
15120 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 61  integer code tha
15130 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77  t specifies.** w
15140 68 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65  hat action is be
15150 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20  ing authorized. 
15160 20 54 68 65 73 65 20 61 72 65 20 74 68 65 20 69   These are the i
15170 6e 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f  nteger action co
15180 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  des that.** the 
15190 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
151a0 61 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65  ack may be passe
151b0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61  d..**.** These a
151c0 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65  ction code value
151d0 73 20 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b  s signify what k
151e0 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e  ind of operation
151f0 20 69 73 20 74 6f 20 62 65 20 0a 2a 2a 20 61 75   is to be .** au
15200 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33  thorized.  The 3
15210 72 64 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d  rd and 4th param
15220 65 74 65 72 73 20 74 6f 20 74 68 65 20 61 75 74  eters to the aut
15230 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61  horization.** ca
15240 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
15250 77 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65  will be paramete
15260 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e  rs or NULL depen
15270 64 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66  ding on which of
15280 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20   these.** codes 
15290 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20 73  is used as the s
152a0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e  econd parameter.
152b0 20 20 54 68 65 20 35 74 68 20 70 61 72 61 6d 65    The 5th parame
152c0 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75  ter to the.** au
152d0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
152e0 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  k is the name of
152f0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 28 22   the database ("
15300 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 20 0a  main", "temp", .
15310 2a 2a 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c  ** etc.) if appl
15320 69 63 61 62 6c 65 2e 20 20 54 68 65 20 36 74 68  icable.  The 6th
15330 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
15340 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
15350 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20  lback.** is the 
15360 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65  name of the inne
15370 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f  r-most trigger o
15380 72 20 76 69 65 77 20 74 68 61 74 20 69 73 20 72  r view that is r
15390 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a  esponsible for.*
153a0 2a 20 74 68 65 20 61 63 63 65 73 73 20 61 74 74  * the access att
153b0 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20  empt or NULL if 
153c0 74 68 69 73 20 61 63 63 65 73 73 20 61 74 74 65  this access atte
153d0 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c 79 20  mpt is directly 
153e0 66 72 6f 6d 20 0a 2a 2a 20 74 6f 70 2d 6c 65 76  from .** top-lev
153f0 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2a 0a  el SQL code..**.
15400 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
15410 2a 0a 2a 2a 20 7b 46 31 32 35 35 31 7d 20 54 68  *.** {F12551} Th
15420 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
15430 65 72 20 74 6f 20 61 6e 20 0a 2a 2a 20 20 20 20  er to an .**    
15440 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73        [sqlite3_s
15450 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20  et_authorizer | 
15460 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
15470 61 63 6b 5d 20 69 73 20 61 6c 77 61 79 73 20 61  ack] is always a
15480 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 20 20 20  n integer.**    
15490 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 43 4f        [SQLITE_CO
154a0 50 59 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20  PY | authorizer 
154b0 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63 69  code] that speci
154c0 66 69 65 73 20 77 68 61 74 20 61 63 74 69 6f 6e  fies what action
154d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20  .**          is 
154e0 62 65 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64  being authorized
154f0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 35 32 7d  ..**.** {F12552}
15500 20 54 68 65 20 33 72 64 20 61 6e 64 20 34 74 68   The 3rd and 4th
15510 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74   parameters to t
15520 68 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  he .**          
15530 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
15540 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72  horizer | author
15550 69 7a 61 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b  ization callback
15560 20 66 75 6e 63 74 69 6f 6e 5d 0a 2a 2a 20 20 20   function].**   
15570 20 20 20 20 20 20 20 77 69 6c 6c 20 62 65 20 70         will be p
15580 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c  arameters or NUL
15590 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77  L depending on w
155a0 68 69 63 68 20 0a 2a 2a 20 20 20 20 20 20 20 20  hich .**        
155b0 20 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c    [SQLITE_COPY |
155c0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 64 65   authorizer code
155d0 5d 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65  ] is used as the
155e0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
155f0 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 35 33  r..**.** {F12553
15600 7d 20 54 68 65 20 35 74 68 20 70 61 72 61 6d 65  } The 5th parame
15610 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20  ter to the.**   
15620 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
15630 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c  set_authorizer |
15640 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
15650 62 61 63 6b 5d 20 69 73 20 74 68 65 20 6e 61 6d  back] is the nam
15660 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66  e.**          of
15670 20 74 68 65 20 64 61 74 61 62 61 73 65 20 28 65   the database (e
15680 78 61 6d 70 6c 65 3a 20 22 6d 61 69 6e 22 2c 20  xample: "main", 
15690 22 74 65 6d 70 22 2c 20 65 74 63 2e 29 20 69 66  "temp", etc.) if
156a0 20 61 70 70 6c 69 63 61 62 6c 65 2e 0a 2a 2a 0a   applicable..**.
156b0 2a 2a 20 7b 46 31 32 35 35 34 7d 20 54 68 65 20  ** {F12554} The 
156c0 36 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  6th parameter to
156d0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
156e0 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
156f0 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f  thorizer | autho
15700 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 5d 20  rizer callback] 
15710 69 73 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 20  is the name.**  
15720 20 20 20 20 20 20 20 20 6f 66 20 74 68 65 20 69          of the i
15730 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65  nner-most trigge
15740 72 20 6f 72 20 76 69 65 77 20 74 68 61 74 20 69  r or view that i
15750 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
15760 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  r.**          th
15770 65 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74  e access attempt
15780 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73   or NULL if this
15790 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20   access attempt 
157a0 69 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d  is directly from
157b0 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f   .**          to
157c0 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 65  p-level SQL code
157d0 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ..*/./**********
157e0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
157f0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
15800 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  * 3rd **********
15810 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a  ** 4th *********
15820 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  **/.#define SQLI
15830 54 45 5f 43 52 45 41 54 45 5f 49 4e 44 45 58 20  TE_CREATE_INDEX 
15840 20 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20           1   /* 
15850 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
15860 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
15870 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
15880 45 5f 43 52 45 41 54 45 5f 54 41 42 4c 45 20 20  E_CREATE_TABLE  
15890 20 20 20 20 20 20 20 20 32 20 20 20 2f 2a 20 54          2   /* T
158a0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
158b0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
158c0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
158d0 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44  _CREATE_TEMP_IND
158e0 45 58 20 20 20 20 20 33 20 20 20 2f 2a 20 49 6e  EX     3   /* In
158f0 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
15900 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
15910 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
15920 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c  CREATE_TEMP_TABL
15930 45 20 20 20 20 20 34 20 20 20 2f 2a 20 54 61 62  E     4   /* Tab
15940 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
15950 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
15960 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
15970 52 45 41 54 45 5f 54 45 4d 50 5f 54 52 49 47 47  REATE_TEMP_TRIGG
15980 45 52 20 20 20 35 20 20 20 2f 2a 20 54 72 69 67  ER   5   /* Trig
15990 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
159a0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
159b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
159c0 45 41 54 45 5f 54 45 4d 50 5f 56 49 45 57 20 20  EATE_TEMP_VIEW  
159d0 20 20 20 20 36 20 20 20 2f 2a 20 56 69 65 77 20      6   /* View 
159e0 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
159f0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
15a00 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
15a10 41 54 45 5f 54 52 49 47 47 45 52 20 20 20 20 20  ATE_TRIGGER     
15a20 20 20 20 37 20 20 20 2f 2a 20 54 72 69 67 67 65     7   /* Trigge
15a30 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
15a40 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
15a50 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
15a60 54 45 5f 56 49 45 57 20 20 20 20 20 20 20 20 20  TE_VIEW         
15a70 20 20 38 20 20 20 2f 2a 20 56 69 65 77 20 4e 61    8   /* View Na
15a80 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
15a90 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
15aa0 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c 45 54  ine SQLITE_DELET
15ab0 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  E               
15ac0 20 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61   9   /* Table Na
15ad0 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
15ae0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
15af0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49  ne SQLITE_DROP_I
15b00 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20 31  NDEX           1
15b10 30 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  0   /* Index Nam
15b20 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
15b30 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
15b40 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41  e SQLITE_DROP_TA
15b50 42 4c 45 20 20 20 20 20 20 20 20 20 20 20 31 31  BLE           11
15b60 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
15b70 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
15b80 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
15b90 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d   SQLITE_DROP_TEM
15ba0 50 5f 49 4e 44 45 58 20 20 20 20 20 20 31 32 20  P_INDEX      12 
15bb0 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
15bc0 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
15bd0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
15be0 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50  SQLITE_DROP_TEMP
15bf0 5f 54 41 42 4c 45 20 20 20 20 20 20 31 33 20 20  _TABLE      13  
15c00 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
15c10 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
15c20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
15c30 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f  QLITE_DROP_TEMP_
15c40 54 52 49 47 47 45 52 20 20 20 20 31 34 20 20 20  TRIGGER    14   
15c50 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
15c60 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
15c70 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
15c80 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56  LITE_DROP_TEMP_V
15c90 49 45 57 20 20 20 20 20 20 20 31 35 20 20 20 2f  IEW       15   /
15ca0 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
15cb0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
15cc0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
15cd0 49 54 45 5f 44 52 4f 50 5f 54 52 49 47 47 45 52  ITE_DROP_TRIGGER
15ce0 20 20 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a           16   /*
15cf0 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
15d00 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
15d10 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
15d20 54 45 5f 44 52 4f 50 5f 56 49 45 57 20 20 20 20  TE_DROP_VIEW    
15d30 20 20 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20          17   /* 
15d40 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
15d50 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
15d60 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
15d70 45 5f 49 4e 53 45 52 54 20 20 20 20 20 20 20 20  E_INSERT        
15d80 20 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 54         18   /* T
15d90 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
15da0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
15db0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
15dc0 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 20  _PRAGMA         
15dd0 20 20 20 20 20 20 31 39 20 20 20 2f 2a 20 50 72        19   /* Pr
15de0 61 67 6d 61 20 4e 61 6d 65 20 20 20 20 20 31 73  agma Name     1s
15df0 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f  t arg or NULL */
15e00 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
15e10 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20 20  READ            
15e20 20 20 20 20 20 32 30 20 20 20 2f 2a 20 54 61 62       20   /* Tab
15e30 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c  le Name      Col
15e40 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  umn Name     */.
15e50 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
15e60 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20  ELECT           
15e70 20 20 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c      21   /* NULL
15e80 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c              NULL
15e90 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
15ea0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52  define SQLITE_TR
15eb0 41 4e 53 41 43 54 49 4f 4e 20 20 20 20 20 20 20  ANSACTION       
15ec0 20 20 20 32 32 20 20 20 2f 2a 20 4e 55 4c 4c 20     22   /* NULL 
15ed0 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20             NULL 
15ee0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
15ef0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 50 44  efine SQLITE_UPD
15f00 41 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ATE             
15f10 20 20 32 33 20 20 20 2f 2a 20 54 61 62 6c 65 20    23   /* Table 
15f20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e  Name      Column
15f30 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
15f40 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 54 54 41  fine SQLITE_ATTA
15f50 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CH              
15f60 20 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d   24   /* Filenam
15f70 65 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  e        NULL   
15f80 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
15f90 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 41 43  ine SQLITE_DETAC
15fa0 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
15fb0 32 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  25   /* Database
15fc0 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20   Name   NULL    
15fd0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
15fe0 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f  ne SQLITE_ALTER_
15ff0 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32  TABLE          2
16000 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  6   /* Database 
16010 4e 61 6d 65 20 20 20 54 61 62 6c 65 20 4e 61 6d  Name   Table Nam
16020 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
16030 65 20 53 51 4c 49 54 45 5f 52 45 49 4e 44 45 58  e SQLITE_REINDEX
16040 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 37                27
16050 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
16060 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
16070 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
16080 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20   SQLITE_ANALYZE 
16090 20 20 20 20 20 20 20 20 20 20 20 20 20 32 38 20               28 
160a0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
160b0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
160c0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
160d0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 54  SQLITE_CREATE_VT
160e0 41 42 4c 45 20 20 20 20 20 20 20 20 32 39 20 20  ABLE        29  
160f0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
16100 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20      Module Name 
16110 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
16120 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c  QLITE_DROP_VTABL
16130 45 20 20 20 20 20 20 20 20 20 20 33 30 20 20 20  E          30   
16140 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
16150 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20     Module Name  
16160 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
16170 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20  LITE_FUNCTION   
16180 20 20 20 20 20 20 20 20 20 20 33 31 20 20 20 2f            31   /
16190 2a 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20  * Function Name 
161a0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
161b0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
161c0 49 54 45 5f 43 4f 50 59 20 20 20 20 20 20 20 20  ITE_COPY        
161d0 20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a            0   /*
161e0 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64 20   No longer used 
161f0 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
16200 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e 64 20  EF: Tracing And 
16210 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74 69  Profiling Functi
16220 6f 6e 73 20 7b 46 31 32 32 38 30 7d 0a 2a 2a 0a  ons {F12280}.**.
16230 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
16240 73 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62  s register callb
16250 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 68  ack functions th
16260 61 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 66  at can be used f
16270 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e  or.** tracing an
16280 64 20 70 72 6f 66 69 6c 69 6e 67 20 74 68 65 20  d profiling the 
16290 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c  execution of SQL
162a0 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a   statements..**.
162b0 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  ** The callback 
162c0 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65  function registe
162d0 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74  red by sqlite3_t
162e0 72 61 63 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  race() is invoke
162f0 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20  d at.** various 
16300 74 69 6d 65 73 20 77 68 65 6e 20 61 6e 20 53 51  times when an SQ
16310 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 62  L statement is b
16320 65 69 6e 67 20 72 75 6e 20 62 79 20 5b 73 71 6c  eing run by [sql
16330 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a  ite3_step()]..**
16340 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   The callback re
16350 74 75 72 6e 73 20 61 20 55 54 46 2d 38 20 72 65  turns a UTF-8 re
16360 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 53  ndering of the S
16370 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78  QL statement tex
16380 74 0a 2a 2a 20 61 73 20 74 68 65 20 73 74 61 74  t.** as the stat
16390 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65 67 69  ement first begi
163a0 6e 73 20 65 78 65 63 75 74 69 6e 67 2e 20 20 41  ns executing.  A
163b0 64 64 69 74 69 6f 6e 61 6c 20 63 61 6c 6c 62 61  dditional callba
163c0 63 6b 73 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20  cks occur.** as 
163d0 65 61 63 68 20 74 72 69 67 67 65 72 65 64 20 73  each triggered s
163e0 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74  ubprogram is ent
163f0 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62  ered.  The callb
16400 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72  acks for trigger
16410 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55  s.** contain a U
16420 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74  TF-8 SQL comment
16430 20 74 68 61 74 20 69 64 65 6e 74 69 66 69 65 73   that identifies
16440 20 74 68 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a   the trigger..**
16450 20 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63   .** The callbac
16460 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73  k function regis
16470 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33  tered by sqlite3
16480 5f 70 72 6f 66 69 6c 65 28 29 20 69 73 20 69 6e  _profile() is in
16490 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63 68  voked.** as each
164a0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66   SQL statement f
164b0 69 6e 69 73 68 65 73 2e 20 20 54 68 65 20 70 72  inishes.  The pr
164c0 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63  ofile callback c
164d0 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f  ontains.** the o
164e0 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e  riginal statemen
164f0 74 20 74 65 78 74 20 61 6e 64 20 61 6e 20 65 73  t text and an es
16500 74 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63  timate of wall-c
16510 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20  lock time.** of 
16520 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 74  how long that st
16530 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20  atement took to 
16540 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  run..**.** The s
16550 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29  qlite3_profile()
16560 20 41 50 49 20 69 73 20 63 75 72 72 65 6e 74 6c   API is currentl
16570 79 20 63 6f 6e 73 69 64 65 72 65 64 20 65 78 70  y considered exp
16580 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 0a 2a 2a  erimental and.**
16590 20 69 73 20 73 75 62 6a 65 63 74 20 74 6f 20 63   is subject to c
165a0 68 61 6e 67 65 20 6f 72 20 72 65 6d 6f 76 61 6c  hange or removal
165b0 20 69 6e 20 61 20 66 75 74 75 72 65 20 72 65 6c   in a future rel
165c0 65 61 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ease..**.** The 
165d0 74 72 69 67 67 65 72 20 72 65 70 6f 72 74 69 6e  trigger reportin
165e0 67 20 66 65 61 74 75 72 65 20 6f 66 20 74 68 65  g feature of the
165f0 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 20   trace callback 
16600 69 73 20 63 6f 6e 73 69 64 65 72 65 64 0a 2a 2a  is considered.**
16610 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e   experimental an
16620 64 20 69 73 20 73 75 62 6a 65 63 74 20 74 6f 20  d is subject to 
16630 63 68 61 6e 67 65 20 6f 72 20 72 65 6d 6f 76 61  change or remova
16640 6c 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  l in future rele
16650 61 73 65 73 2e 0a 2a 2a 20 46 75 74 75 72 65 20  ases..** Future 
16660 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
16670 74 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 61 64  te might also ad
16680 64 20 6e 65 77 20 74 72 61 63 65 20 63 61 6c 6c  d new trace call
16690 62 61 63 6b 20 0a 2a 2a 20 69 6e 76 6f 63 61 74  back .** invocat
166a0 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  ions..**.** INVA
166b0 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  RIANTS:.**.** {F
166c0 31 32 32 38 31 7d 20 54 68 65 20 63 61 6c 6c 62  12281} The callb
166d0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67  ack function reg
166e0 69 73 74 65 72 65 64 20 62 79 20 5b 73 71 6c 69  istered by [sqli
166f0 74 65 33 5f 74 72 61 63 65 28 29 5d 20 69 73 0a  te3_trace()] is.
16700 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68 65 6e  **          when
16710 65 76 65 72 20 61 6e 20 53 51 4c 20 73 74 61 74  ever an SQL stat
16720 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65 67 69  ement first begi
16730 6e 73 20 74 6f 20 65 78 65 63 75 74 65 20 61 6e  ns to execute an
16740 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68  d.**          wh
16750 65 6e 65 76 65 72 20 61 20 74 72 69 67 67 65 72  enever a trigger
16760 20 73 75 62 70 72 6f 67 72 61 6d 20 66 69 72 73   subprogram firs
16770 74 20 62 65 67 69 6e 73 20 74 6f 20 72 75 6e 2e  t begins to run.
16780 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 38 32 7d 20  .**.** {F12282} 
16790 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71  Each call to [sq
167a0 6c 69 74 65 33 5f 74 72 61 63 65 28 29 5d 20 6f  lite3_trace()] o
167b0 76 65 72 72 69 64 65 73 20 74 68 65 20 70 72 65  verrides the pre
167c0 76 69 6f 75 73 6c 79 0a 2a 2a 20 20 20 20 20 20  viously.**      
167d0 20 20 20 20 72 65 67 69 73 74 65 72 65 64 20 74      registered t
167e0 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a  race callback..*
167f0 2a 0a 2a 2a 20 7b 46 31 32 32 38 33 7d 20 41 20  *.** {F12283} A 
16800 4e 55 4c 4c 20 74 72 61 63 65 20 63 61 6c 6c 62  NULL trace callb
16810 61 63 6b 20 64 69 73 61 62 6c 65 73 20 74 72 61  ack disables tra
16820 63 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  cing..**.** {F12
16830 32 38 34 7d 20 54 68 65 20 66 69 72 73 74 20 61  284} The first a
16840 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 74  rgument to the t
16850 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 20 69 73  race callback is
16860 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 20 20   a copy of.**   
16870 20 20 20 20 20 20 20 74 68 65 20 70 6f 69 6e 74         the point
16880 65 72 20 77 68 69 63 68 20 77 61 73 20 74 68 65  er which was the
16890 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f   3rd argument to
168a0 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28   [sqlite3_trace(
168b0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 38  )]..**.** {F1228
168c0 35 7d 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72  5} The second ar
168d0 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 74 72  gument to the tr
168e0 61 63 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ace callback is 
168f0 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65  a.**          ze
16900 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
16910 46 38 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69  F8 string contai
16920 6e 69 6e 67 20 74 68 65 20 6f 72 69 67 69 6e 61  ning the origina
16930 6c 20 74 65 78 74 0a 2a 2a 20 20 20 20 20 20 20  l text.**       
16940 20 20 20 6f 66 20 74 68 65 20 53 51 4c 20 73 74     of the SQL st
16950 61 74 65 6d 65 6e 74 20 61 73 20 69 74 20 77 61  atement as it wa
16960 73 20 70 61 73 73 65 64 20 69 6e 74 6f 20 5b 73  s passed into [s
16970 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
16980 32 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  2()].**         
16990 20 6f 72 20 74 68 65 20 65 71 75 69 76 61 6c 65   or the equivale
169a0 6e 74 2c 20 6f 72 20 61 6e 20 53 51 4c 20 63 6f  nt, or an SQL co
169b0 6d 6d 65 6e 74 20 69 6e 64 69 63 61 74 69 6e 67  mment indicating
169c0 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a   the beginning.*
169d0 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 61 20  *          of a 
169e0 74 72 69 67 67 65 72 20 73 75 62 70 72 6f 67 72  trigger subprogr
169f0 61 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 38  am..**.** {F1228
16a00 37 7d 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  7} The callback 
16a10 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65  function registe
16a20 72 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  red by [sqlite3_
16a30 70 72 6f 66 69 6c 65 28 29 5d 20 69 73 20 69 6e  profile()] is in
16a40 76 6f 6b 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  voked.**        
16a50 20 20 61 73 20 65 61 63 68 20 53 51 4c 20 73 74    as each SQL st
16a60 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73  atement finishes
16a70 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 38 38 7d  ..**.** {F12288}
16a80 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   The first param
16a90 65 74 65 72 20 74 6f 20 74 68 65 20 70 72 6f 66  eter to the prof
16aa0 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ile callback is 
16ab0 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 20 20 20  a copy of.**    
16ac0 20 20 20 20 20 20 74 68 65 20 33 72 64 20 70 61        the 3rd pa
16ad0 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
16ae0 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 5d 2e 0a  te3_profile()]..
16af0 2a 2a 0a 2a 2a 20 7b 46 31 32 32 38 39 7d 20 54  **.** {F12289} T
16b00 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
16b10 74 65 72 20 74 6f 20 74 68 65 20 70 72 6f 66 69  ter to the profi
16b20 6c 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  le callback is a
16b30 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72  .**          zer
16b40 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
16b50 2d 38 20 73 74 72 69 6e 67 20 74 68 61 74 20 63  -8 string that c
16b60 6f 6e 74 61 69 6e 73 20 74 68 65 20 63 6f 6d 70  ontains the comp
16b70 6c 65 74 65 20 74 65 78 74 20 6f 66 0a 2a 2a 20  lete text of.** 
16b80 20 20 20 20 20 20 20 20 20 74 68 65 20 53 51 4c           the SQL
16b90 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20 69 74   statement as it
16ba0 20 77 61 73 20 70 72 6f 63 65 73 73 65 64 20 62   was processed b
16bb0 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  y [sqlite3_prepa
16bc0 72 65 5f 76 32 28 29 5d 0a 2a 2a 20 20 20 20 20  re_v2()].**     
16bd0 20 20 20 20 20 6f 72 20 74 68 65 20 65 71 75 69       or the equi
16be0 76 61 6c 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46  valent..**.** {F
16bf0 31 32 32 39 30 7d 20 54 68 65 20 74 68 69 72 64  12290} The third
16c00 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
16c10 65 20 70 72 6f 66 69 6c 65 20 20 63 61 6c 6c 62  e profile  callb
16c20 61 63 6b 20 69 73 20 61 6e 20 65 73 74 69 6d 61  ack is an estima
16c30 74 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  te.**          o
16c40 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  f the number of 
16c50 6e 61 6e 6f 73 65 63 6f 6e 64 73 20 6f 66 20 77  nanoseconds of w
16c60 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 20 72  all-clock time r
16c70 65 71 75 69 72 65 64 20 74 6f 0a 2a 2a 20 20 20  equired to.**   
16c80 20 20 20 20 20 20 20 72 75 6e 20 74 68 65 20 53         run the S
16c90 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 72 6f  QL statement fro
16ca0 6d 20 73 74 61 72 74 20 74 6f 20 66 69 6e 69 73  m start to finis
16cb0 68 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  h..*/.void *sqli
16cc0 74 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74 65  te3_trace(sqlite
16cd0 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61 63 65  3*, void(*xTrace
16ce0 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68  )(void*,const ch
16cf0 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 76 6f  ar*), void*);.vo
16d00 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66  id *sqlite3_prof
16d10 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20  ile(sqlite3*,.  
16d20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65 29   void(*xProfile)
16d30 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61  (void*,const cha
16d40 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  r*,sqlite3_uint6
16d50 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  4), void*);../*.
16d60 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75 65  ** CAPI3REF: Que
16d70 72 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c 6c  ry Progress Call
16d80 62 61 63 6b 73 20 7b 46 31 32 39 31 30 7d 0a 2a  backs {F12910}.*
16d90 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
16da0 65 20 63 6f 6e 66 69 67 75 72 65 73 20 61 20 63  e configures a c
16db0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
16dc0 20 2d 20 74 68 65 0a 2a 2a 20 70 72 6f 67 72 65   - the.** progre
16dd0 73 73 20 63 61 6c 6c 62 61 63 6b 20 2d 20 74 68  ss callback - th
16de0 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 70 65  at is invoked pe
16df0 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e  riodically durin
16e00 67 20 6c 6f 6e 67 0a 2a 2a 20 72 75 6e 6e 69 6e  g long.** runnin
16e10 67 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  g calls to [sqli
16e20 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71  te3_exec()], [sq
16e30 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 61 6e  lite3_step()] an
16e40 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65  d.** [sqlite3_ge
16e50 74 5f 74 61 62 6c 65 28 29 5d 2e 20 20 20 41 6e  t_table()].   An
16e60 20 65 78 61 6d 70 6c 65 20 75 73 65 20 66 6f 72   example use for
16e70 20 74 68 69 73 20 0a 2a 2a 20 69 6e 74 65 72 66   this .** interf
16e80 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70 20 61  ace is to keep a
16e90 20 47 55 49 20 75 70 64 61 74 65 64 20 64 75 72   GUI updated dur
16ea0 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75 65 72  ing a large quer
16eb0 79 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  y..**.** If the 
16ec0 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63  progress callbac
16ed0 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  k returns non-ze
16ee0 72 6f 2c 20 74 68 65 20 6f 70 65 72 61 74 69 6f  ro, the operatio
16ef0 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70  n is.** interrup
16f00 74 65 64 2e 20 20 54 68 69 73 20 66 65 61 74 75  ted.  This featu
16f10 72 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  re can be used t
16f20 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a  o implement a.**
16f30 20 22 43 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e   "Cancel" button
16f40 20 6f 6e 20 61 20 47 55 49 20 64 69 61 6c 6f 67   on a GUI dialog
16f50 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41   box..**.** INVA
16f60 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  RIANTS:.**.** {F
16f70 31 32 39 31 31 7d 20 54 68 65 20 63 61 6c 6c 62  12911} The callb
16f80 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67  ack function reg
16f90 69 73 74 65 72 65 64 20 62 79 20 5b 73 71 6c 69  istered by [sqli
16fa0 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e  te3_progress_han
16fb0 64 6c 65 72 28 29 5d 0a 2a 2a 20 20 20 20 20 20  dler()].**      
16fc0 20 20 20 20 69 73 20 69 6e 76 6f 6b 65 64 20 70      is invoked p
16fd0 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69  eriodically duri
16fe0 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20  ng long running 
16ff0 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 20 20 20 20  calls to.**     
17000 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 74       [sqlite3_st
17010 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  ep()]..**.** {F1
17020 32 39 31 32 7d 20 54 68 65 20 70 72 6f 67 72 65  2912} The progre
17030 73 73 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  ss callback is i
17040 6e 76 6f 6b 65 64 20 6f 6e 63 65 20 66 6f 72 20  nvoked once for 
17050 65 76 65 72 79 20 4e 20 76 69 72 74 75 61 6c 0a  every N virtual.
17060 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 61 63 68  **          mach
17070 69 6e 65 20 6f 70 63 6f 64 65 73 2c 20 77 68 65  ine opcodes, whe
17080 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f  re N is the seco
17090 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 0a  nd argument to .
170a0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
170b0 5b 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73  [sqlite3_progres
170c0 73 5f 68 61 6e 64 6c 65 72 28 29 5d 20 63 61 6c  s_handler()] cal
170d0 6c 20 74 68 61 74 20 72 65 67 69 73 74 65 72 65  l that registere
170e0 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  d.**          th
170f0 65 20 63 61 6c 6c 62 61 63 6b 2e 20 20 3c 74 6f  e callback.  <to
17100 64 6f 3e 57 68 61 74 20 69 66 20 4e 20 69 73 20  do>What if N is 
17110 6c 65 73 73 20 74 68 61 6e 20 31 3f 3c 2f 74 6f  less than 1?</to
17120 64 6f 3e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 31  do>.**.** {F1291
17130 33 7d 20 54 68 65 20 70 72 6f 67 72 65 73 73 20  3} The progress 
17140 63 61 6c 6c 62 61 63 6b 20 69 74 73 65 6c 66 20  callback itself 
17150 69 73 20 69 64 65 6e 74 69 66 69 65 64 20 62 79  is identified by
17160 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 20 20   the third.**   
17170 20 20 20 20 20 20 20 61 72 67 75 6d 65 6e 74 20         argument 
17180 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 67  to [sqlite3_prog
17190 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 29 5d 2e  ress_handler()].
171a0 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 31 34 7d 20  .**.** {F12914} 
171b0 54 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d  The fourth argum
171c0 65 6e 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f  ent [sqlite3_pro
171d0 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 29 5d  gress_handler()]
171e0 20 69 73 20 61 0a 2a 2a 2a 20 20 20 20 20 20 20   is a.***       
171f0 20 20 76 6f 69 64 20 70 6f 69 6e 74 65 72 20 70    void pointer p
17200 61 73 73 65 64 20 74 6f 20 74 68 65 20 70 72 6f  assed to the pro
17210 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 0a 2a  gress callback.*
17220 2a 20 20 20 20 20 20 20 20 20 20 66 75 6e 63 74  *          funct
17230 69 6f 6e 20 65 61 63 68 20 74 69 6d 65 20 69 74  ion each time it
17240 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a   is invoked..**.
17250 2a 2a 20 7b 46 31 32 39 31 35 7d 20 49 66 20 61  ** {F12915} If a
17260 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
17270 33 5f 73 74 65 70 28 29 5d 20 72 65 73 75 6c 74  3_step()] result
17280 73 20 69 6e 20 66 65 77 65 72 20 74 68 61 6e 0a  s in fewer than.
17290 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 20 6f 70  **          N op
172a0 63 6f 64 65 73 20 62 65 69 6e 67 20 65 78 65 63  codes being exec
172b0 75 74 65 64 2c 0a 2a 2a 20 20 20 20 20 20 20 20  uted,.**        
172c0 20 20 74 68 65 6e 20 74 68 65 20 70 72 6f 67 72    then the progr
172d0 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ess callback is 
172e0 6e 65 76 65 72 20 69 6e 76 6f 6b 65 64 2e 20 7b  never invoked. {
172f0 45 4e 44 7d 0a 2a 2a 20 0a 2a 2a 20 7b 46 31 32  END}.** .** {F12
17300 39 31 36 7d 20 45 76 65 72 79 20 63 61 6c 6c 20  916} Every call 
17310 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 67  to [sqlite3_prog
17320 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 29 5d 0a  ress_handler()].
17330 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 76 65 72  **          over
17340 77 72 69 74 65 73 20 61 6e 79 20 70 72 65 76 69  writes any previ
17350 6f 75 73 6c 79 20 72 65 67 69 73 74 65 72 65 64  ously registered
17360 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
17370 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 31 37  r..**.** {F12917
17380 7d 20 49 66 20 74 68 65 20 70 72 6f 67 72 65 73  } If the progres
17390 73 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61  s handler callba
173a0 63 6b 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20  ck is NULL then 
173b0 6e 6f 20 70 72 6f 67 72 65 73 73 0a 2a 2a 20 20  no progress.**  
173c0 20 20 20 20 20 20 20 20 68 61 6e 64 6c 65 72 20          handler 
173d0 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a  is invoked..**.*
173e0 2a 20 7b 46 31 32 39 31 38 7d 20 49 66 20 74 68  * {F12918} If th
173f0 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62  e progress callb
17400 61 63 6b 20 72 65 74 75 72 6e 73 20 61 20 72 65  ack returns a re
17410 73 75 6c 74 20 6f 74 68 65 72 20 74 68 61 6e 20  sult other than 
17420 30 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20  0, then.**      
17430 20 20 20 20 74 68 65 20 62 65 68 61 76 69 6f 72      the behavior
17440 20 69 73 20 61 20 69 66 20 5b 73 71 6c 69 74 65   is a if [sqlite
17450 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 20 68  3_interrupt()] h
17460 61 64 20 62 65 65 6e 20 63 61 6c 6c 65 64 2e 0a  ad been called..
17470 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  */.void sqlite3_
17480 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72  progress_handler
17490 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20  (sqlite3*, int, 
174a0 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76  int(*)(void*), v
174b0 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
174c0 50 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20  PI3REF: Opening 
174d0 41 20 4e 65 77 20 44 61 74 61 62 61 73 65 20 43  A New Database C
174e0 6f 6e 6e 65 63 74 69 6f 6e 20 7b 46 31 32 37 30  onnection {F1270
174f0 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  0}.**.** These r
17500 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20  outines open an 
17510 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20  SQLite database 
17520 66 69 6c 65 20 77 68 6f 73 65 20 6e 61 6d 65 0a  file whose name.
17530 2a 2a 20 69 73 20 67 69 76 65 6e 20 62 79 20 74  ** is given by t
17540 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  he filename argu
17550 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 66 69 6c  ment..** The fil
17560 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69  ename argument i
17570 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
17580 20 55 54 46 2d 38 0a 2a 2a 20 66 6f 72 20 5b 73   UTF-8.** for [s
17590 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 61  qlite3_open()] a
175a0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  nd [sqlite3_open
175b0 5f 76 32 28 29 5d 20 61 6e 64 20 61 73 20 55 54  _v2()] and as UT
175c0 46 2d 31 36 0a 2a 2a 20 69 6e 20 74 68 65 20 6e  F-16.** in the n
175d0 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
175e0 20 66 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70   for [sqlite3_op
175f0 65 6e 31 36 28 29 5d 2e 0a 2a 2a 20 41 6e 20 5b  en16()]..** An [
17600 73 71 6c 69 74 65 33 2a 5d 20 68 61 6e 64 6c 65  sqlite3*] handle
17610 20 69 73 20 75 73 75 61 6c 6c 79 20 72 65 74 75   is usually retu
17620 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 65  rned in *ppDb, e
17630 76 65 6e 0a 2a 2a 20 69 66 20 61 6e 20 65 72 72  ven.** if an err
17640 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20  or occurs.  The 
17650 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69  only exception i
17660 73 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 75  s if SQLite is u
17670 6e 61 62 6c 65 0a 2a 2a 20 74 6f 20 61 6c 6c 6f  nable.** to allo
17680 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68  cate memory to h
17690 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33  old the [sqlite3
176a0 5d 20 6f 62 6a 65 63 74 2c 20 61 20 4e 55 4c 4c  ] object, a NULL
176b0 20 77 69 6c 6c 0a 2a 2a 20 62 65 20 77 72 69 74   will.** be writ
176c0 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20 69  ten into *ppDb i
176d0 6e 73 74 65 61 64 20 6f 66 20 61 20 70 6f 69 6e  nstead of a poin
176e0 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ter to the [sqli
176f0 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20  te3] object..** 
17700 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
17710 69 73 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f  is opened (and/o
17720 72 20 63 72 65 61 74 65 64 29 0a 2a 2a 20 73 75  r created).** su
17730 63 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e  ccessfully, then
17740 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20   [SQLITE_OK] is 
17750 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72  returned.  Other
17760 77 69 73 65 20 61 6e 0a 2a 2a 20 65 72 72 6f 72  wise an.** error
17770 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65   code is returne
17780 64 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69  d.  The.** [sqli
17790 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72  te3_errmsg()] or
177a0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
177b0 31 36 28 29 5d 20 20 72 6f 75 74 69 6e 65 73 20  16()]  routines 
177c0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
177d0 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c  btain.** an Engl
177e0 69 73 68 20 6c 61 6e 67 75 61 67 65 20 64 65 73  ish language des
177f0 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 68 65 20  cription of the 
17800 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  error..**.** The
17810 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e   default encodin
17820 67 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61  g for the databa
17830 73 65 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38  se will be UTF-8
17840 20 69 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   if.** [sqlite3_
17850 6f 70 65 6e 28 29 5d 20 6f 72 20 5b 73 71 6c 69  open()] or [sqli
17860 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69  te3_open_v2()] i
17870 73 20 63 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20  s called and.** 
17880 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61  UTF-16 in the na
17890 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
178a0 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  if [sqlite3_open
178b0 31 36 28 29 5d 20 69 73 20 75 73 65 64 2e 0a 2a  16()] is used..*
178c0 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20  *.** Whether or 
178d0 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63  not an error occ
178e0 75 72 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f  urs when it is o
178f0 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73  pened, resources
17900 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77  .** associated w
17910 69 74 68 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ith the [sqlite3
17920 2a 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64  *] handle should
17930 20 62 65 20 72 65 6c 65 61 73 65 64 20 62 79 20   be released by 
17940 70 61 73 73 69 6e 67 20 69 74 0a 2a 2a 20 74 6f  passing it.** to
17950 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
17960 29 5d 20 77 68 65 6e 20 69 74 20 69 73 20 6e 6f  )] when it is no
17970 20 6c 6f 6e 67 65 72 20 72 65 71 75 69 72 65 64   longer required
17980 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  ..**.** The [sql
17990 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20  ite3_open_v2()] 
179a0 69 6e 74 65 72 66 61 63 65 20 77 6f 72 6b 73 20  interface works 
179b0 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70  like [sqlite3_op
179c0 65 6e 28 29 5d 20 0a 2a 2a 20 65 78 63 65 70 74  en()] .** except
179d0 20 74 68 61 74 20 69 74 20 61 63 63 65 70 74 73   that it accepts
179e0 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20   two additional 
179f0 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20 61  parameters for a
17a00 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f  dditional contro
17a10 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e 65  l.** over the ne
17a20 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  w database conne
17a30 63 74 69 6f 6e 2e 20 20 54 68 65 20 66 6c 61 67  ction.  The flag
17a40 73 20 70 61 72 61 6d 65 74 65 72 20 63 61 6e 20  s parameter can 
17a50 62 65 0a 2a 2a 20 6f 6e 65 20 6f 66 3a 0a 2a 2a  be.** one of:.**
17a60 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ol>.** <li>
17a70 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52    [SQLITE_OPEN_R
17a80 45 41 44 4f 4e 4c 59 5d 0a 2a 2a 20 3c 6c 69 3e  EADONLY].** <li>
17a90 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52    [SQLITE_OPEN_R
17aa0 45 41 44 57 52 49 54 45 5d 0a 2a 2a 20 3c 6c 69  EADWRITE].** <li
17ab0 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
17ac0 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51  READWRITE] | [SQ
17ad0 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
17ae0 5d 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a  ].** </ol>.**.**
17af0 20 54 68 65 20 66 69 72 73 74 20 76 61 6c 75 65   The first value
17b00 20 6f 70 65 6e 73 20 74 68 65 20 64 61 74 61 62   opens the datab
17b10 61 73 65 20 72 65 61 64 2d 6f 6e 6c 79 2e 20 0a  ase read-only. .
17b20 2a 2a 20 49 66 20 74 68 65 20 64 61 74 61 62 61  ** If the databa
17b30 73 65 20 64 6f 65 73 20 6e 6f 74 20 70 72 65 76  se does not prev
17b40 69 6f 75 73 6c 79 20 65 78 69 73 74 2c 20 61 6e  iously exist, an
17b50 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
17b60 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  ed..** The secon
17b70 64 20 6f 70 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a  d option opens.*
17b80 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  * the database f
17b90 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77  or reading and w
17ba0 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62  riting if possib
17bb0 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 20 6f  le, or reading o
17bc0 6e 6c 79 20 69 66 0a 2a 2a 20 69 66 20 74 68 65  nly if.** if the
17bd0 20 66 69 6c 65 20 69 73 20 77 72 69 74 65 20 70   file is write p
17be0 72 6f 74 65 63 74 65 64 2e 20 20 49 6e 20 65 69  rotected.  In ei
17bf0 74 68 65 72 20 63 61 73 65 20 74 68 65 20 64 61  ther case the da
17c00 74 61 62 61 73 65 0a 2a 2a 20 6d 75 73 74 20 61  tabase.** must a
17c10 6c 72 65 61 64 79 20 65 78 69 73 74 20 6f 72 20  lready exist or 
17c20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  an error is retu
17c30 72 6e 65 64 2e 20 20 54 68 65 20 74 68 69 72 64  rned.  The third
17c40 20 6f 70 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73   option.** opens
17c50 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 6f   the database fo
17c60 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72  r reading and wr
17c70 69 74 69 6e 67 20 61 6e 64 20 63 72 65 61 74 65  iting and create
17c80 73 20 69 74 20 69 66 20 69 74 20 64 6f 65 73 0a  s it if it does.
17c90 2a 2a 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 65  ** not already e
17ca0 78 69 73 74 2e 0a 2a 2a 20 54 68 65 20 74 68 69  xist..** The thi
17cb0 72 64 20 6f 70 74 69 6f 6e 73 20 69 73 20 62 65  rd options is be
17cc0 68 61 76 69 6f 72 20 74 68 61 74 20 69 73 20 61  havior that is a
17cd0 6c 77 61 79 73 20 75 73 65 64 20 66 6f 72 20 5b  lways used for [
17ce0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a  sqlite3_open()].
17cf0 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
17d00 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a  open16()]..**.**
17d10 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61   If the 3rd para
17d20 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
17d30 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 73 20  3_open_v2()] is 
17d40 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a  not one of the.*
17d50 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73  * combinations s
17d60 68 6f 77 6e 20 61 62 6f 76 65 20 74 68 65 6e 20  hown above then 
17d70 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
17d80 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
17d90 20 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65   If the filename
17da0 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20   is ":memory:", 
17db0 74 68 65 6e 20 61 6e 20 70 72 69 76 61 74 65 0a  then an private.
17dc0 2a 2a 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74  ** in-memory dat
17dd0 61 62 61 73 65 20 69 73 20 63 72 65 61 74 65 64  abase is created
17de0 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74   for the connect
17df0 69 6f 6e 2e 20 20 54 68 69 73 20 69 6e 2d 6d 65  ion.  This in-me
17e00 6d 6f 72 79 0a 2a 2a 20 64 61 74 61 62 61 73 65  mory.** database
17e10 20 77 69 6c 6c 20 76 61 6e 69 73 68 20 77 68 65   will vanish whe
17e20 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
17e30 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f  onnection is clo
17e40 73 65 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20  sed.  Future.** 
17e50 76 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74  version of SQLit
17e60 65 20 6d 69 67 68 74 20 6d 61 6b 65 20 75 73 65  e might make use
17e70 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73   of additional s
17e80 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73  pecial filenames
17e90 0a 2a 2a 20 74 68 61 74 20 62 65 67 69 6e 20 77  .** that begin w
17ea0 69 74 68 20 74 68 65 20 22 3a 22 20 63 68 61 72  ith the ":" char
17eb0 61 63 74 65 72 2e 20 20 49 74 20 69 73 20 72 65  acter.  It is re
17ec0 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 0a  commended that .
17ed0 2a 2a 20 77 68 65 6e 20 61 20 64 61 74 61 62 61  ** when a databa
17ee0 73 65 20 66 69 6c 65 6e 61 6d 65 20 72 65 61 6c  se filename real
17ef0 6c 79 20 64 6f 65 73 20 62 65 67 69 6e 20 77 69  ly does begin wi
17f00 74 68 0a 2a 2a 20 22 3a 22 20 74 68 61 74 20 79  th.** ":" that y
17f10 6f 75 20 70 72 65 66 69 78 20 74 68 65 20 66 69  ou prefix the fi
17f20 6c 65 6e 61 6d 65 20 77 69 74 68 20 61 20 70 61  lename with a pa
17f30 74 68 6e 61 6d 65 20 6c 69 6b 65 20 22 2e 2f 22  thname like "./"
17f40 20 74 6f 0a 2a 2a 20 61 76 6f 69 64 20 61 6d 62   to.** avoid amb
17f50 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 49 66  iguity..**.** If
17f60 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73   the filename is
17f70 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
17f80 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65  , then a private
17f90 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e   temporary.** on
17fa0 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65 20 77  -disk database w
17fb0 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20  ill be created. 
17fc0 20 54 68 69 73 20 70 72 69 76 61 74 65 20 64 61   This private da
17fd0 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a  tabase will be.*
17fe0 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  * automatically 
17ff0 64 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20  deleted as soon 
18000 61 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  as the database 
18010 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c  connection is cl
18020 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  osed..**.** The 
18030 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
18040 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
18050 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d  _v2() is the nam
18060 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  e of the.** [sql
18070 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
18080 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 74 68   that defines th
18090 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  e operating syst
180a0 65 6d 20 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  em .** interface
180b0 20 74 68 61 74 20 74 68 65 20 6e 65 77 20 64 61   that the new da
180c0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
180d0 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 49  n should use.  I
180e0 66 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20  f the.** fourth 
180f0 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 4e  parameter is a N
18100 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
18110 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71   the default [sq
18120 6c 69 74 65 33 5f 76 66 73 5d 0a 2a 2a 20 6f 62  lite3_vfs].** ob
18130 6a 65 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a  ject is used..**
18140 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57  .** <b>Note to W
18150 69 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62  indows users:</b
18160 3e 20 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20  >  The encoding 
18170 75 73 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c  used for the fil
18180 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a  ename argument.*
18190 2a 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70  * of [sqlite3_op
181a0 65 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  en()] and [sqlit
181b0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6d 75  e3_open_v2()] mu
181c0 73 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74  st be UTF-8, not
181d0 20 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64   whatever.** cod
181e0 65 70 61 67 65 20 69 73 20 63 75 72 72 65 6e 74  epage is current
181f0 6c 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c  ly defined.  Fil
18200 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e  enames containin
18210 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a  g international.
18220 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d 75  ** characters mu
18230 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20  st be converted 
18240 74 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74  to UTF-8 prior t
18250 6f 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69  o passing them i
18260 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  nto.** [sqlite3_
18270 6f 70 65 6e 28 29 5d 20 6f 72 20 5b 73 71 6c 69  open()] or [sqli
18280 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 0a  te3_open_v2()]..
18290 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
182a0 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 30 31 7d  :.**.** {F12701}
182b0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70   The [sqlite3_op
182c0 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
182d0 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a  open16()], and.*
182e0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
182f0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69  te3_open_v2()] i
18300 6e 74 65 72 66 61 63 65 73 20 63 72 65 61 74 65  nterfaces create
18310 20 61 20 6e 65 77 0a 2a 2a 20 20 20 20 20 20 20   a new.**       
18320 20 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e     [database con
18330 6e 65 63 74 69 6f 6e 5d 20 61 73 73 6f 63 69 61  nection] associa
18340 74 65 64 20 77 69 74 68 0a 2a 2a 20 20 20 20 20  ted with.**     
18350 20 20 20 20 20 74 68 65 20 64 61 74 61 62 61 73       the databas
18360 65 20 66 69 6c 65 20 67 69 76 65 6e 20 69 6e 20  e file given in 
18370 74 68 65 69 72 20 66 69 72 73 74 20 70 61 72 61  their first para
18380 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  meter..**.** {F1
18390 32 37 30 32 7d 20 54 68 65 20 66 69 6c 65 6e 61  2702} The filena
183a0 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69  me argument is i
183b0 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55 54  nterpreted as UT
183c0 46 2d 38 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  F-8.**          
183d0 66 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  for [sqlite3_ope
183e0 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  n()] and [sqlite
183f0 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 61 6e 64  3_open_v2()] and
18400 20 61 73 20 55 54 46 2d 31 36 0a 2a 2a 20 20 20   as UTF-16.**   
18410 20 20 20 20 20 20 20 69 6e 20 74 68 65 20 6e 61         in the na
18420 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
18430 66 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  for [sqlite3_ope
18440 6e 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46  n16()]..**.** {F
18450 31 32 37 30 33 7d 20 41 20 73 75 63 63 65 73 73  12703} A success
18460 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  ful invocation o
18470 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  f [sqlite3_open(
18480 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
18490 6e 31 36 28 29 5d 2c 20 0a 2a 2a 20 20 20 20 20  n16()], .**     
184a0 20 20 20 20 20 6f 72 20 5b 73 71 6c 69 74 65 33       or [sqlite3
184b0 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 77 72 69 74  _open_v2()] writ
184c0 65 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  es a pointer to 
184d0 61 20 6e 65 77 0a 2a 2a 20 20 20 20 20 20 20 20  a new.**        
184e0 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e    [database conn
184f0 65 63 74 69 6f 6e 5d 20 69 6e 74 6f 20 2a 70 70  ection] into *pp
18500 44 62 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 30  Db..**.** {F1270
18510 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  4} The [sqlite3_
18520 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
18530 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64  3_open16()], and
18540 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
18550 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
18560 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 74 75   interfaces retu
18570 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 75  rn [SQLITE_OK] u
18580 70 6f 6e 20 73 75 63 63 65 73 73 2c 0a 2a 2a 20  pon success,.** 
18590 20 20 20 20 20 20 20 20 20 6f 72 20 61 6e 20 61           or an a
185a0 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f  ppropriate [erro
185b0 72 20 63 6f 64 65 5d 20 6f 6e 20 66 61 69 6c 75  r code] on failu
185c0 72 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 30  re..**.** {F1270
185d0 36 7d 20 54 68 65 20 64 65 66 61 75 6c 74 20 74  6} The default t
185e0 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72  ext encoding for
185f0 20 61 20 6e 65 77 20 64 61 74 61 62 61 73 65 20   a new database 
18600 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a  created using.**
18610 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
18620 65 33 5f 6f 70 65 6e 28 29 5d 20 6f 72 20 5b 73  e3_open()] or [s
18630 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
18640 5d 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38 2e  ] will be UTF-8.
18650 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 30 37 7d 20  .**.** {F12707} 
18660 54 68 65 20 64 65 66 61 75 6c 74 20 74 65 78 74  The default text
18670 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 61 20   encoding for a 
18680 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 72 65  new database cre
18690 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20  ated using.**   
186a0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
186b0 6f 70 65 6e 31 36 28 29 5d 20 77 69 6c 6c 20 62  open16()] will b
186c0 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20  e UTF-16..**.** 
186d0 7b 46 31 32 37 30 39 7d 20 54 68 65 20 5b 73 71  {F12709} The [sq
186e0 6c 69 74 65 33 5f 6f 70 65 6e 28 46 2c 44 29 5d  lite3_open(F,D)]
186f0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 65 71   interface is eq
18700 75 69 76 61 6c 65 6e 74 20 74 6f 0a 2a 2a 20 20  uivalent to.**  
18710 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
18720 5f 6f 70 65 6e 5f 76 32 28 46 2c 44 2c 47 2c 30  _open_v2(F,D,G,0
18730 29 5d 20 77 68 65 72 65 20 74 68 65 20 47 20 70  )] where the G p
18740 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 20  arameter is.**  
18750 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f          [SQLITE_
18760 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 7c  OPEN_READWRITE]|
18770 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45  [SQLITE_OPEN_CRE
18780 41 54 45 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  ATE]..**.** {F12
18790 37 31 31 7d 20 49 66 20 74 68 65 20 47 20 70 61  711} If the G pa
187a0 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
187b0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 46 2c 44 2c  te3_open_v2(F,D,
187c0 47 2c 56 29 5d 20 63 6f 6e 74 61 69 6e 73 20 74  G,V)] contains t
187d0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62  he.**          b
187e0 69 74 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45  it value [SQLITE
187f0 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20  _OPEN_READONLY] 
18800 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  then the databas
18810 65 20 69 73 20 6f 70 65 6e 65 64 0a 2a 2a 20 20  e is opened.**  
18820 20 20 20 20 20 20 20 20 66 6f 72 20 72 65 61 64          for read
18830 69 6e 67 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ing only..**.** 
18840 7b 46 31 32 37 31 32 7d 20 49 66 20 74 68 65 20  {F12712} If the 
18850 47 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  G parameter to [
18860 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
18870 46 2c 44 2c 47 2c 56 29 5d 20 63 6f 6e 74 61 69  F,D,G,V)] contai
18880 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ns the.**       
18890 20 20 20 62 69 74 20 76 61 6c 75 65 20 5b 53 51     bit value [SQ
188a0 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
188b0 49 54 45 5d 20 74 68 65 6e 20 74 68 65 20 64 61  ITE] then the da
188c0 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
188d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 61  .**          rea
188e0 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67  ding and writing
188f0 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72   if possible, or
18900 20 66 6f 72 20 72 65 61 64 69 6e 67 20 6f 6e 6c   for reading onl
18910 79 20 69 66 20 74 68 65 0a 2a 2a 20 20 20 20 20  y if the.**     
18920 20 20 20 20 20 66 69 6c 65 20 69 73 20 77 72 69       file is wri
18930 74 65 20 70 72 6f 74 65 63 74 65 64 20 62 79 20  te protected by 
18940 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
18950 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  stem..**.** {F12
18960 37 31 33 7d 20 49 66 20 74 68 65 20 47 20 70 61  713} If the G pa
18970 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
18980 74 65 33 5f 6f 70 65 6e 28 76 32 28 46 2c 44 2c  te3_open(v2(F,D,
18990 47 2c 56 29 5d 20 6f 6d 69 74 73 20 74 68 65 0a  G,V)] omits the.
189a0 2a 2a 20 20 20 20 20 20 20 20 20 20 62 69 74 20  **          bit 
189b0 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 4f 50  value [SQLITE_OP
189c0 45 4e 5f 43 52 45 41 54 45 5d 20 61 6e 64 20 74  EN_CREATE] and t
189d0 68 65 20 64 61 74 61 62 61 73 65 20 64 6f 65 73  he database does
189e0 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 20 20 20 20   not.**         
189f0 20 70 72 65 76 69 6f 75 73 6c 79 20 65 78 69 73   previously exis
18a00 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72  t, an error is r
18a10 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b  eturned..**.** {
18a20 46 31 32 37 31 34 7d 20 49 66 20 74 68 65 20 47  F12714} If the G
18a30 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
18a40 71 6c 69 74 65 33 5f 6f 70 65 6e 28 76 32 28 46  qlite3_open(v2(F
18a50 2c 44 2c 47 2c 56 29 5d 20 63 6f 6e 74 61 69 6e  ,D,G,V)] contain
18a60 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
18a70 20 20 62 69 74 20 76 61 6c 75 65 20 5b 53 51 4c    bit value [SQL
18a80 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d  ITE_OPEN_CREATE]
18a90 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61 73   and the databas
18aa0 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 20 20  e does not.**   
18ab0 20 20 20 20 20 20 20 70 72 65 76 69 6f 75 73 6c         previousl
18ac0 79 20 65 78 69 73 74 2c 20 74 68 65 6e 20 61 6e  y exist, then an
18ad0 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65   attempt is made
18ae0 20 74 6f 20 63 72 65 61 74 65 20 61 6e 64 0a 2a   to create and.*
18af0 2a 20 20 20 20 20 20 20 20 20 20 69 6e 69 74 69  *          initi
18b00 61 6c 69 7a 65 20 74 68 65 20 64 61 74 61 62 61  alize the databa
18b10 73 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 31  se..**.** {F1271
18b20 37 7d 20 49 66 20 74 68 65 20 66 69 6c 65 6e 61  7} If the filena
18b30 6d 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b  me argument to [
18b40 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
18b50 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
18b60 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ()],.**         
18b70 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   or [sqlite3_ope
18b80 6e 5f 76 32 28 29 5d 20 69 73 20 22 3a 6d 65 6d  n_v2()] is ":mem
18b90 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 6e 20 70  ory:", then an p
18ba0 72 69 76 61 74 65 2c 0a 2a 2a 20 20 20 20 20 20  rivate,.**      
18bb0 20 20 20 20 65 70 68 65 6d 65 72 61 6c 2c 20 69      ephemeral, i
18bc0 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73  n-memory databas
18bd0 65 20 69 73 20 63 72 65 61 74 65 64 20 66 6f 72  e is created for
18be0 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e   the connection.
18bf0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 3c 74 6f  .**          <to
18c00 64 6f 3e 49 73 20 53 51 4c 49 54 45 5f 4f 50 45  do>Is SQLITE_OPE
18c10 4e 5f 43 52 45 41 54 45 7c 53 51 4c 49 54 45 5f  N_CREATE|SQLITE_
18c20 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 72  OPEN_READWRITE r
18c30 65 71 75 69 72 65 64 0a 2a 2a 20 20 20 20 20 20  equired.**      
18c40 20 20 20 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f      in sqlite3_o
18c50 70 65 6e 5f 76 32 28 29 3f 3c 2f 74 6f 64 6f 3e  pen_v2()?</todo>
18c60 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 31 39 7d 20  .**.** {F12719} 
18c70 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  If the filename 
18c80 69 73 20 4e 55 4c 4c 20 6f 72 20 61 6e 20 65 6d  is NULL or an em
18c90 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e  pty string, then
18ca0 20 61 20 70 72 69 76 61 74 65 2c 0a 2a 2a 20 20   a private,.**  
18cb0 20 20 20 20 20 20 20 20 65 70 68 65 6d 65 72 61          ephemera
18cc0 6c 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62 61  l on-disk databa
18cd0 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61 74  se will be creat
18ce0 65 64 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ed..**          
18cf0 3c 74 6f 64 6f 3e 49 73 20 53 51 4c 49 54 45 5f  <todo>Is SQLITE_
18d00 4f 50 45 4e 5f 43 52 45 41 54 45 7c 53 51 4c 49  OPEN_CREATE|SQLI
18d10 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
18d20 45 20 72 65 71 75 69 72 65 64 0a 2a 2a 20 20 20  E required.**   
18d30 20 20 20 20 20 20 20 69 6e 20 73 71 6c 69 74 65         in sqlite
18d40 33 5f 6f 70 65 6e 5f 76 32 28 29 3f 3c 2f 74 6f  3_open_v2()?</to
18d50 64 6f 3e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 32  do>.**.** {F1272
18d60 31 7d 20 54 68 65 20 5b 64 61 74 61 62 61 73 65  1} The [database
18d70 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 63 72 65   connection] cre
18d80 61 74 65 64 20 62 79 20 0a 2a 2a 20 20 20 20 20  ated by .**     
18d90 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f 70       [sqlite3_op
18da0 65 6e 5f 76 32 28 46 2c 44 2c 47 2c 56 29 5d 20  en_v2(F,D,G,V)] 
18db0 77 69 6c 6c 20 75 73 65 20 74 68 65 0a 2a 2a 20  will use the.** 
18dc0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
18dd0 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 64  3_vfs] object id
18de0 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20  entified by the 
18df0 56 20 70 61 72 61 6d 65 74 65 72 2c 20 6f 72 0a  V parameter, or.
18e00 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
18e10 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
18e20 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 73 20  _vfs] object is 
18e30 56 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  V is a NULL poin
18e40 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37  ter..**.** {F127
18e50 32 33 7d 20 54 77 6f 20 5b 64 61 74 61 62 61 73  23} Two [databas
18e60 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 7c 20 64  e connection | d
18e70 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
18e80 6f 6e 73 5d 20 77 69 6c 6c 20 73 68 61 72 65 20  ons] will share 
18e90 61 20 63 6f 6d 6d 6f 6e 20 63 61 63 68 65 0a 2a  a common cache.*
18ea0 2a 20 20 20 20 20 20 20 20 20 20 69 66 20 62 6f  *          if bo
18eb0 74 68 20 77 65 72 65 20 6f 70 65 6e 65 64 20 77  th were opened w
18ec0 69 74 68 20 74 68 65 20 73 61 6d 65 20 56 46 53  ith the same VFS
18ed0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68 69  .**          whi
18ee0 6c 65 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62  le [sqlite3_enab
18ef0 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 20  le_shared_cache 
18f00 7c 20 73 68 61 72 65 64 20 63 61 63 68 65 20 6d  | shared cache m
18f10 6f 64 65 20 77 61 73 20 65 6e 61 62 6c 65 64 5d  ode was enabled]
18f20 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20   and.**         
18f30 20 69 66 20 62 6f 74 68 20 66 69 6c 65 6e 61 6d   if both filenam
18f40 65 73 20 63 6f 6d 70 61 72 65 20 65 71 75 61 6c  es compare equal
18f50 20 75 73 69 6e 67 20 6d 65 6d 63 6d 70 28 29 0a   using memcmp().
18f60 2a 2a 20 20 20 20 20 20 20 20 20 20 61 66 74 65  **          afte
18f70 72 20 68 61 76 69 6e 67 20 62 65 65 6e 20 70 72  r having been pr
18f80 6f 63 65 73 73 65 64 20 62 79 20 74 68 65 20 5b  ocessed by the [
18f90 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 78 46  sqlite3_vfs | xF
18fa0 75 6c 6c 50 61 74 68 6e 61 6d 65 5d 20 6d 65 74  ullPathname] met
18fb0 68 6f 64 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20  hod of.**       
18fc0 20 20 20 74 68 65 20 56 46 53 2e 0a 2a 2a 0a 2a     the VFS..**.*
18fd0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70  /.int sqlite3_op
18fe0 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  en(.  const char
18ff0 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a   *filename,   /*
19000 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   Database filena
19010 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20  me (UTF-8) */.  
19020 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20  sqlite3 **ppDb  
19030 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20          /* OUT: 
19040 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65  SQLite db handle
19050 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
19060 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e  e3_open16(.  con
19070 73 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d  st void *filenam
19080 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  e,   /* Database
19090 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31   filename (UTF-1
190a0 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20  6) */.  sqlite3 
190b0 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20  **ppDb          
190c0 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64  /* OUT: SQLite d
190d0 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69  b handle */.);.i
190e0 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  nt sqlite3_open_
190f0 76 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  v2(.  const char
19100 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a   *filename,   /*
19110 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   Database filena
19120 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20  me (UTF-8) */.  
19130 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20  sqlite3 **ppDb, 
19140 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20          /* OUT: 
19150 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65  SQLite db handle
19160 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c   */.  int flags,
19170 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
19180 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73   Flags */.  cons
19190 74 20 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20  t char *zVfs    
191a0 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56      /* Name of V
191b0 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65  FS module to use
191c0 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.);../*.** CA
191d0 50 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f  PI3REF: Error Co
191e0 64 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73  des And Messages
191f0 20 7b 46 31 32 38 30 30 7d 0a 2a 2a 0a 2a 2a 20   {F12800}.**.** 
19200 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63  The sqlite3_errc
19210 6f 64 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ode() interface 
19220 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65  returns the nume
19230 72 69 63 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  ric.** [SQLITE_O
19240 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 5d  K | result code]
19250 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52   or [SQLITE_IOER
19260 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65  R_READ | extende
19270 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 0a 2a  d result code].*
19280 2a 20 66 6f 72 20 74 68 65 20 6d 6f 73 74 20 72  * for the most r
19290 65 63 65 6e 74 20 66 61 69 6c 65 64 20 73 71 6c  ecent failed sql
192a0 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 20  ite3_* API call 
192b0 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69  associated.** wi
192c0 74 68 20 5b 73 71 6c 69 74 65 33 5d 20 68 61 6e  th [sqlite3] han
192d0 64 6c 65 20 27 64 62 27 2e 20 49 66 20 61 20 70  dle 'db'. If a p
192e0 72 69 6f 72 20 41 50 49 20 63 61 6c 6c 20 66 61  rior API call fa
192f0 69 6c 65 64 20 62 75 74 20 74 68 65 0a 2a 2a 20  iled but the.** 
19300 6d 6f 73 74 20 72 65 63 65 6e 74 20 41 50 49 20  most recent API 
19310 63 61 6c 6c 20 73 75 63 63 65 65 64 65 64 2c 20  call succeeded, 
19320 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
19330 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 65 72   from sqlite3_er
19340 72 63 6f 64 65 28 29 0a 2a 2a 20 69 73 20 75 6e  rcode().** is un
19350 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  defined..**.** T
19360 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  he sqlite3_errms
19370 67 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  g() and sqlite3_
19380 65 72 72 6d 73 67 31 36 28 29 20 72 65 74 75 72  errmsg16() retur
19390 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61  n English-langua
193a0 67 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20  ge.** text that 
193b0 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72  describes the er
193c0 72 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20 55  ror, as either U
193d0 54 46 38 20 6f 72 20 55 54 46 31 36 20 72 65 73  TF8 or UTF16 res
193e0 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 4d 65  pectively..** Me
193f0 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
19400 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
19410 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64  tring is managed
19420 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20   internally..** 
19430 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
19440 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
19450 20 77 6f 72 72 79 20 77 69 74 68 20 66 72 65 65   worry with free
19460 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e 0a  ing the result..
19470 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20  ** However, the 
19480 65 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69 67  error string mig
19490 68 74 20 62 65 20 6f 76 65 72 77 72 69 74 74 65  ht be overwritte
194a0 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 64  n or deallocated
194b0 20 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e   by.** subsequen
194c0 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72  t calls to other
194d0 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
194e0 65 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a  e functions..**.
194f0 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
19500 2a 0a 2a 2a 20 7b 46 31 32 38 30 31 7d 20 54 68  *.** {F12801} Th
19510 65 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  e [sqlite3_errco
19520 64 65 28 44 29 5d 20 69 6e 74 65 72 66 61 63 65  de(D)] interface
19530 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
19540 65 72 69 63 0a 2a 2a 20 20 20 20 20 20 20 20 20  eric.**         
19550 20 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 72 65   [SQLITE_OK | re
19560 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a  sult code] or.**
19570 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54            [SQLIT
19580 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 65  E_IOERR_READ | e
19590 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
195a0 6f 64 65 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ode].**         
195b0 20 66 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 65   for the most re
195c0 63 65 6e 74 6c 79 20 66 61 69 6c 65 64 20 69 6e  cently failed in
195d0 74 65 72 66 61 63 65 20 63 61 6c 6c 20 61 73 73  terface call ass
195e0 6f 63 69 61 74 65 64 0a 2a 2a 20 20 20 20 20 20  ociated.**      
195f0 20 20 20 20 77 69 74 68 20 5b 64 61 74 61 62 61      with [databa
19600 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
19610 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 38 30 33 7d  ..**.** {F12803}
19620 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 72   The [sqlite3_er
19630 72 6d 73 67 28 44 29 5d 20 61 6e 64 20 5b 73 71  rmsg(D)] and [sq
19640 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 44  lite3_errmsg16(D
19650 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  )].**          i
19660 6e 74 65 72 66 61 63 65 73 20 72 65 74 75 72 6e  nterfaces return
19670 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67   English-languag
19680 65 20 74 65 78 74 20 74 68 61 74 20 64 65 73 63  e text that desc
19690 72 69 62 65 73 0a 2a 2a 20 20 20 20 20 20 20 20  ribes.**        
196a0 20 20 74 68 65 20 65 72 72 6f 72 20 69 6e 20 74    the error in t
196b0 68 65 20 6d 6f 73 74 6c 79 20 72 65 63 65 6e 74  he mostly recent
196c0 6c 79 20 66 61 69 6c 65 64 20 69 6e 74 65 72 66  ly failed interf
196d0 61 63 65 20 63 61 6c 6c 2c 0a 2a 2a 20 20 20 20  ace call,.**    
196e0 20 20 20 20 20 20 65 6e 63 6f 64 65 64 20 61 73        encoded as
196f0 20 65 69 74 68 65 72 20 55 54 46 38 20 6f 72 20   either UTF8 or 
19700 55 54 46 31 36 20 72 65 73 70 65 63 74 69 76 65  UTF16 respective
19710 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 38 30  ly..**.** {F1280
19720 37 7d 20 54 68 65 20 73 74 72 69 6e 67 73 20 72  7} The strings r
19730 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
19740 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 61 6e  te3_errmsg()] an
19750 64 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  d [sqlite3_errms
19760 67 31 36 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20  g16()].**       
19770 20 20 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74     are valid unt
19780 69 6c 20 74 68 65 20 6e 65 78 74 20 53 51 4c 69  il the next SQLi
19790 74 65 20 69 6e 74 65 72 66 61 63 65 20 63 61 6c  te interface cal
197a0 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 38 30 38  l..**.** {F12808
197b0 7d 20 43 61 6c 6c 73 20 74 6f 20 41 50 49 20 72  } Calls to API r
197c0 6f 75 74 69 6e 65 73 20 74 68 61 74 20 64 6f 20  outines that do 
197d0 6e 6f 74 20 72 65 74 75 72 6e 20 61 6e 20 65 72  not return an er
197e0 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 20 20 20 20  ror code.**     
197f0 20 20 20 20 20 28 65 78 61 6d 70 6c 65 3a 20 5b       (example: [
19800 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
19810 6e 74 28 29 5d 29 20 64 6f 20 6e 6f 74 0a 2a 2a  nt()]) do not.**
19820 20 20 20 20 20 20 20 20 20 20 63 68 61 6e 67 65            change
19830 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20   the error code 
19840 6f 72 20 6d 65 73 73 61 67 65 20 72 65 74 75 72  or message retur
19850 6e 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20  ned by.**       
19860 20 20 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63     [sqlite3_errc
19870 6f 64 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  ode()], [sqlite3
19880 5f 65 72 72 6d 73 67 28 29 5d 2c 20 6f 72 20 5b  _errmsg()], or [
19890 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
198a0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 38  ()]..**.** {F128
198b0 30 39 7d 20 49 6e 74 65 72 66 61 63 65 73 20 74  09} Interfaces t
198c0 68 61 74 20 61 72 65 20 6e 6f 74 20 61 73 73 6f  hat are not asso
198d0 63 69 61 74 65 64 20 77 69 74 68 20 61 20 73 70  ciated with a sp
198e0 65 63 69 66 69 63 0a 2a 2a 20 20 20 20 20 20 20  ecific.**       
198f0 20 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e     [database con
19900 6e 65 63 74 69 6f 6e 5d 20 28 65 78 61 6d 70 6c  nection] (exampl
19910 65 73 3a 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  es:.**          
19920 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66  [sqlite3_mprintf
19930 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
19940 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61  enable_shared_ca
19950 63 68 65 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20  che()].**       
19960 20 20 20 64 6f 20 6e 6f 74 20 63 68 61 6e 67 65     do not change
19970 20 74 68 65 20 76 61 6c 75 65 73 20 72 65 74 75   the values retu
19980 72 6e 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20  rned by.**      
19990 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 65 72 72      [sqlite3_err
199a0 63 6f 64 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65  code()], [sqlite
199b0 33 5f 65 72 72 6d 73 67 28 29 5d 2c 20 6f 72 20  3_errmsg()], or 
199c0 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31  [sqlite3_errmsg1
199d0 36 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  6()]..*/.int sql
199e0 69 74 65 33 5f 65 72 72 63 6f 64 65 28 73 71 6c  ite3_errcode(sql
199f0 69 74 65 33 20 2a 64 62 29 3b 0a 63 6f 6e 73 74  ite3 *db);.const
19a00 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65   char *sqlite3_e
19a10 72 72 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b  rrmsg(sqlite3*);
19a20 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
19a30 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 73 71  ite3_errmsg16(sq
19a40 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
19a50 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 53 74  CAPI3REF: SQL St
19a60 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 20 7b  atement Object {
19a70 46 31 33 30 30 30 7d 0a 2a 2a 20 4b 45 59 57 4f  F13000}.** KEYWO
19a80 52 44 53 3a 20 7b 70 72 65 70 61 72 65 64 20 73  RDS: {prepared s
19a90 74 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61  tatement} {prepa
19aa0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a  red statements}.
19ab0 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63  **.** An instanc
19ac0 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
19ad0 20 72 65 70 72 65 73 65 6e 74 73 20 61 20 73 69   represents a si
19ae0 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65  ngle SQL stateme
19af0 6e 74 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 62 6a  nt.  This.** obj
19b00 65 63 74 20 69 73 20 76 61 72 69 6f 75 73 6c 79  ect is variously
19b10 20 6b 6e 6f 77 6e 20 61 73 20 61 20 22 70 72 65   known as a "pre
19b20 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 22  pared statement"
19b30 20 6f 72 20 61 20 0a 2a 2a 20 22 63 6f 6d 70 69   or a .** "compi
19b40 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  led SQL statemen
19b50 74 22 20 6f 72 20 73 69 6d 70 6c 79 20 61 73 20  t" or simply as 
19b60 61 20 22 73 74 61 74 65 6d 65 6e 74 22 2e 0a 2a  a "statement"..*
19b70 2a 20 0a 2a 2a 20 54 68 65 20 6c 69 66 65 20 6f  * .** The life o
19b80 66 20 61 20 73 74 61 74 65 6d 65 6e 74 20 6f 62  f a statement ob
19b90 6a 65 63 74 20 67 6f 65 73 20 73 6f 6d 65 74 68  ject goes someth
19ba0 69 6e 67 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a  ing like this:.*
19bb0 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ol>.** <li
19bc0 3e 20 43 72 65 61 74 65 20 74 68 65 20 6f 62 6a  > Create the obj
19bd0 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ect using [sqlit
19be0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
19bf0 20 6f 72 20 61 20 72 65 6c 61 74 65 64 0a 2a 2a   or a related.**
19c00 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 2e 0a        function..
19c10 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c  ** <li> Bind val
19c20 75 65 73 20 74 6f 20 68 6f 73 74 20 70 61 72 61  ues to host para
19c30 6d 65 74 65 72 73 20 75 73 69 6e 67 0a 2a 2a 20  meters using.** 
19c40 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69       [sqlite3_bi
19c50 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65  nd_blob | sqlite
19c60 33 5f 62 69 6e 64 5f 2a 20 69 6e 74 65 72 66 61  3_bind_* interfa
19c70 63 65 73 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75  ces]..** <li> Ru
19c80 6e 20 74 68 65 20 53 51 4c 20 62 79 20 63 61 6c  n the SQL by cal
19c90 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74  ling [sqlite3_st
19ca0 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72  ep()] one or mor
19cb0 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e  e times..** <li>
19cc0 20 52 65 73 65 74 20 74 68 65 20 73 74 61 74 65   Reset the state
19cd0 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  ment using [sqli
19ce0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 68 65  te3_reset()] the
19cf0 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20  n go back.**    
19d00 20 20 74 6f 20 73 74 65 70 20 32 2e 20 20 44 6f    to step 2.  Do
19d10 20 74 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f   this zero or mo
19d20 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69  re times..** <li
19d30 3e 20 44 65 73 74 72 6f 79 20 74 68 65 20 6f 62  > Destroy the ob
19d40 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  ject using [sqli
19d50 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e  te3_finalize()].
19d60 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ol>.**.** 
19d70 52 65 66 65 72 20 74 6f 20 64 6f 63 75 6d 65 6e  Refer to documen
19d80 74 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69  tation on indivi
19d90 64 75 61 6c 20 6d 65 74 68 6f 64 73 20 61 62 6f  dual methods abo
19da0 76 65 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  ve for additiona
19db0 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  l.** information
19dc0 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
19dd0 75 63 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  uct sqlite3_stmt
19de0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a   sqlite3_stmt;..
19df0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
19e00 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73 20  Run-time Limits 
19e10 7b 46 31 32 37 36 30 7d 0a 2a 2a 0a 2a 2a 20 54  {F12760}.**.** T
19e20 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c  his interface al
19e30 6c 6f 77 73 20 74 68 65 20 73 69 7a 65 20 6f 66  lows the size of
19e40 20 76 61 72 69 6f 75 73 20 63 6f 6e 73 74 72 75   various constru
19e50 63 74 73 20 74 6f 20 62 65 20 6c 69 6d 69 74 65  cts to be limite
19e60 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63  d.** on a connec
19e70 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69  tion by connecti
19e80 6f 6e 20 62 61 73 69 73 2e 20 20 54 68 65 20 66  on basis.  The f
19e90 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
19ea0 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61  s the.** [databa
19eb0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77  se connection] w
19ec0 68 6f 73 65 20 6c 69 6d 69 74 20 69 73 20 74 6f  hose limit is to
19ed0 20 62 65 20 73 65 74 20 6f 72 20 71 75 65 72 69   be set or queri
19ee0 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f  ed.  The.** seco
19ef0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
19f00 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69  one of the [limi
19f10 74 20 63 61 74 65 67 6f 72 69 65 73 5d 20 74 68  t categories] th
19f20 61 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63  at define a.** c
19f30 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74 72 75 63  lass of construc
19f40 74 73 20 74 6f 20 62 65 20 73 69 7a 65 20 6c 69  ts to be size li
19f50 6d 69 74 65 64 2e 20 20 54 68 65 20 74 68 69 72  mited.  The thir
19f60 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  d parameter is t
19f70 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20  he.** new limit 
19f80 66 6f 72 20 74 68 61 74 20 63 6f 6e 73 74 72 75  for that constru
19f90 63 74 2e 20 20 54 68 65 20 66 75 6e 63 74 69 6f  ct.  The functio
19fa0 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6f 6c  n returns the ol
19fb0 64 20 6c 69 6d 69 74 2e 0a 2a 2a 0a 2a 2a 20 49  d limit..**.** I
19fc0 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 74 20  f the new limit 
19fd0 69 73 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75  is a negative nu
19fe0 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 74 20  mber, the limit 
19ff0 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a  is unchanged..**
1a000 20 46 6f 72 20 74 68 65 20 6c 69 6d 69 74 20 63   For the limit c
1a010 61 74 65 67 6f 72 79 20 6f 66 20 53 51 4c 49 54  ategory of SQLIT
1a020 45 5f 4c 49 4d 49 54 5f 58 59 5a 20 74 68 65 72  E_LIMIT_XYZ ther
1a030 65 20 69 73 20 61 20 68 61 72 64 20 75 70 70 65  e is a hard uppe
1a040 72 0a 2a 2a 20 62 6f 75 6e 64 20 73 65 74 20 62  r.** bound set b
1a050 79 20 61 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  y a compile-time
1a060 20 43 2d 70 72 65 70 72 6f 63 65 73 73 20 6d 61   C-preprocess ma
1a070 63 72 6f 20 6e 61 6d 65 64 20 53 51 4c 49 54 45  cro named SQLITE
1a080 5f 4d 41 58 5f 58 59 5a 2e 0a 2a 2a 20 28 54 68  _MAX_XYZ..** (Th
1a090 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74  e "_LIMIT_" in t
1a0a0 68 65 20 6e 61 6d 65 20 69 73 20 63 68 61 6e 67  he name is chang
1a0b0 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 0a  ed to "_MAX_".).
1a0c0 2a 2a 20 41 74 74 65 6d 70 74 73 20 74 6f 20 69  ** Attempts to i
1a0d0 6e 63 72 65 61 73 65 20 61 20 6c 69 6d 69 74 20  ncrease a limit 
1a0e0 61 62 6f 76 65 20 69 74 73 20 68 61 72 64 20 75  above its hard u
1a0f0 70 70 65 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a  pper bound are.*
1a100 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63  * silently trunc
1a110 61 74 65 64 20 74 6f 20 74 68 65 20 68 61 72 64  ated to the hard
1a120 20 75 70 70 65 72 20 6c 69 6d 69 74 2e 0a 2a 2a   upper limit..**
1a130 0a 2a 2a 20 52 75 6e 20 74 69 6d 65 20 6c 69 6d  .** Run time lim
1a140 69 74 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64  its are intended
1a150 20 66 6f 72 20 75 73 65 20 69 6e 20 61 70 70 6c   for use in appl
1a160 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6d 61  ications that ma
1a170 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65  nage.** both the
1a180 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20  ir own internal 
1a190 64 61 74 61 62 61 73 65 20 61 6e 64 20 61 6c 73  database and als
1a1a0 6f 20 64 61 74 61 62 61 73 65 73 20 74 68 61 74  o databases that
1a1b0 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a   are controlled.
1a1c0 2a 2a 20 62 79 20 75 6e 74 72 75 73 74 65 64 20  ** by untrusted 
1a1d0 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73  external sources
1a1e0 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 61 70  .  An example ap
1a1f0 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68 74 20  plication might 
1a200 62 65 20 61 0a 2a 2a 20 77 65 62 62 72 6f 77 73  be a.** webbrows
1a210 65 72 20 74 68 61 74 20 68 61 73 20 69 74 73 20  er that has its 
1a220 6f 77 6e 20 64 61 74 61 62 61 73 65 73 20 66 6f  own databases fo
1a230 72 20 73 74 6f 72 69 6e 67 20 68 69 73 74 6f 72  r storing histor
1a240 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74  y and.** separat
1a250 65 20 64 61 74 61 62 61 73 65 73 20 63 6f 6e 74  e databases cont
1a260 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61 53 63  rolled by JavaSc
1a270 72 69 70 74 20 61 70 70 6c 69 63 61 74 69 6f 6e  ript application
1a280 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20  s downloaded.** 
1a290 6f 66 66 20 74 68 65 20 49 6e 74 65 72 6e 65 74  off the Internet
1a2a0 2e 20 20 54 68 65 20 69 6e 74 65 72 6e 61 6c 20  .  The internal 
1a2b0 64 61 74 61 62 61 73 65 73 20 63 61 6e 20 62 65  databases can be
1a2c0 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61   given the.** la
1a2d0 72 67 65 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d  rge, default lim
1a2e0 69 74 73 2e 20 20 44 61 74 61 62 61 73 65 73 20  its.  Databases 
1a2f0 6d 61 6e 61 67 65 64 20 62 79 20 65 78 74 65 72  managed by exter
1a300 6e 61 6c 20 73 6f 75 72 63 65 73 20 63 61 6e 0a  nal sources can.
1a310 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d 75 63 68  ** be given much
1a320 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20   smaller limits 
1a330 64 65 73 69 67 6e 65 64 20 74 6f 20 70 72 65 76  designed to prev
1a340 65 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f 66 20  ent a denial of 
1a350 73 65 72 76 69 63 65 0a 2a 2a 20 61 74 74 61 63  service.** attac
1a360 68 2e 20 20 44 65 76 65 6c 6f 70 65 72 73 20 6d  h.  Developers m
1a370 69 67 68 74 20 61 6c 73 6f 20 77 61 6e 74 20 74  ight also want t
1a380 6f 20 75 73 65 20 74 68 65 20 5b 73 71 6c 69 74  o use the [sqlit
1a390 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
1a3a0 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63  r()].** interfac
1a3b0 65 20 74 6f 20 66 75 72 74 68 65 72 20 63 6f 6e  e to further con
1a3c0 74 72 6f 6c 20 75 6e 74 72 75 73 74 65 64 20 53  trol untrusted S
1a3d0 51 4c 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66  QL.  The size of
1a3e0 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
1a3f0 20 63 72 65 61 74 65 64 20 62 79 20 61 6e 20 75   created by an u
1a400 6e 74 72 75 73 74 65 64 20 73 63 72 69 70 74 20  ntrusted script 
1a410 63 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65 64  can be contained
1a420 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d   using the.** [m
1a430 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b  ax_page_count] [
1a440 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 54  PRAGMA]..**.** T
1a450 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73  his interface is
1a460 20 63 75 72 72 65 6e 74 6c 79 20 63 6f 6e 73 69   currently consi
1a470 64 65 72 65 64 20 65 78 70 65 72 69 6d 65 6e 74  dered experiment
1a480 61 6c 20 61 6e 64 20 69 73 20 73 75 62 6a 65 63  al and is subjec
1a490 74 0a 2a 2a 20 74 6f 20 63 68 61 6e 67 65 20 6f  t.** to change o
1a4a0 72 20 72 65 6d 6f 76 61 6c 20 77 69 74 68 6f 75  r removal withou
1a4b0 74 20 70 72 69 6f 72 20 6e 6f 74 69 63 65 2e 0a  t prior notice..
1a4c0 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
1a4d0 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 36 32 7d  :.**.** {F12762}
1a4e0 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61   A successful ca
1a4f0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6c  ll to [sqlite3_l
1a500 69 6d 69 74 28 44 2c 43 2c 56 29 5d 20 77 68 65  imit(D,C,V)] whe
1a510 72 65 20 56 20 69 73 0a 2a 2a 20 20 20 20 20 20  re V is.**      
1a520 20 20 20 20 70 6f 73 69 74 69 76 65 20 63 68 61      positive cha
1a530 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  nges the.**     
1a540 20 20 20 20 20 6c 69 6d 69 74 20 6f 6e 20 74 68       limit on th
1a550 65 20 73 69 7a 65 20 6f 66 20 63 6f 6e 73 74 72  e size of constr
1a560 75 63 74 20 43 20 69 6e 20 5b 64 61 74 61 62 61  uct C in [databa
1a570 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
1a580 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20  .**          to 
1a590 74 68 65 20 6c 65 73 73 65 72 20 6f 66 20 56 20  the lesser of V 
1a5a0 61 6e 64 20 74 68 65 20 68 61 72 64 20 75 70 70  and the hard upp
1a5b0 65 72 20 62 6f 75 6e 64 20 6f 6e 20 74 68 65 20  er bound on the 
1a5c0 73 69 7a 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  size.**         
1a5d0 20 6f 66 20 43 20 74 68 61 74 20 69 73 20 73 65   of C that is se
1a5e0 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  t at compile-tim
1a5f0 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 36 36  e..**.** {F12766
1a600 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63  } A successful c
1a610 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
1a620 6c 69 6d 69 74 28 44 2c 43 2c 56 29 5d 20 77 68  limit(D,C,V)] wh
1a630 65 72 65 20 56 20 69 73 20 6e 65 67 61 74 69 76  ere V is negativ
1a640 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6c 65  e.**          le
1a650 61 76 65 73 20 74 68 65 20 73 74 61 74 65 20 6f  aves the state o
1a660 66 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  f [database conn
1a670 65 63 74 69 6f 6e 5d 20 44 20 75 6e 63 68 61 6e  ection] D unchan
1a680 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37  ged..**.** {F127
1a690 36 39 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c  69} A successful
1a6a0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
1a6b0 33 5f 6c 69 6d 69 74 28 44 2c 43 2c 56 29 5d 20  3_limit(D,C,V)] 
1a6c0 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20  returns the.**  
1a6d0 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 6f 66          value of
1a6e0 20 74 68 65 20 6c 69 6d 69 74 20 6f 6e 20 74 68   the limit on th
1a6f0 65 20 73 69 7a 65 20 6f 66 20 63 6f 6e 73 74 72  e size of constr
1a700 75 63 74 20 43 20 69 6e 0a 2a 2a 20 20 20 20 20  uct C in.**     
1a710 20 20 20 20 20 69 6e 20 5b 64 61 74 61 62 61 73       in [databas
1a720 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20  e connection] D 
1a730 61 73 20 69 74 20 77 61 73 20 70 72 69 6f 72 20  as it was prior 
1a740 74 6f 20 74 68 65 20 63 61 6c 6c 2e 0a 2a 2f 0a  to the call..*/.
1a750 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69  int sqlite3_limi
1a760 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20  t(sqlite3*, int 
1a770 69 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b  id, int newVal);
1a780 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1a790 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74  : Run-Time Limit
1a7a0 20 43 61 74 65 67 6f 72 69 65 73 20 7b 46 31 32   Categories {F12
1a7b0 37 39 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  790}.** KEYWORDS
1a7c0 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  : {limit categor
1a7d0 79 7d 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f  y} {limit catego
1a7e0 72 69 65 73 7d 0a 2a 2a 20 0a 2a 2a 20 54 68 65  ries}.** .** The
1a7f0 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66  se constants def
1a800 69 6e 65 20 76 61 72 69 6f 75 73 20 61 73 70 65  ine various aspe
1a810 63 74 73 20 6f 66 20 61 20 5b 64 61 74 61 62 61  cts of a [databa
1a820 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a  se connection].*
1a830 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 6c 69  * that can be li
1a840 6d 69 74 65 64 20 69 6e 20 73 69 7a 65 20 62 79  mited in size by
1a850 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
1a860 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20  e3_limit()]..** 
1a870 54 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20  The meanings of 
1a880 74 68 65 20 76 61 72 69 6f 75 73 20 6c 69 6d 69  the various limi
1a890 74 73 20 61 72 65 20 61 73 20 66 6f 6c 6c 6f 77  ts are as follow
1a8a0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  s:.**.** <dl>.**
1a8b0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49   <dt>SQLITE_LIMI
1a8c0 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a  T_LENGTH</dt>.**
1a8d0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
1a8e0 20 73 69 7a 65 20 6f 66 20 61 6e 79 0a 2a 2a 20   size of any.** 
1a8f0 73 74 72 69 6e 67 20 6f 72 20 62 6c 6f 62 20 6f  string or blob o
1a900 72 20 74 61 62 6c 65 20 72 6f 77 2e 3c 64 64 3e  r table row.<dd>
1a910 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
1a920 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47  E_LIMIT_SQL_LENG
1a930 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
1a940 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  he maximum lengt
1a950 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74  h of an SQL stat
1a960 65 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ement.</dd>.**.*
1a970 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  * <dt>SQLITE_LIM
1a980 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a  IT_COLUMN</dt>.*
1a990 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
1a9a0 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  m number of colu
1a9b0 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c 65 20 64  mns in a table d
1a9c0 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20  efinition or in 
1a9d0 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65  the.** result se
1a9e0 74 20 6f 66 20 61 20 53 45 4c 45 43 54 20 6f 72  t of a SELECT or
1a9f0 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d   the maximum num
1aa00 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
1aa10 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72  n an index.** or
1aa20 20 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 59 20   in an ORDER BY 
1aa30 6f 72 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75  or GROUP BY clau
1aa40 73 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  se.</dd>.**.** <
1aa50 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
1aa60 45 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a  EXPR_DEPTH</dt>.
1aa70 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
1aa80 75 6d 20 64 65 70 74 68 20 6f 66 20 74 68 65 20  um depth of the 
1aa90 70 61 72 73 65 20 74 72 65 65 20 6f 6e 20 61 6e  parse tree on an
1aaa0 79 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64  y expression.</d
1aab0 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
1aac0 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55  ITE_LIMIT_COMPOU
1aad0 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a  ND_SELECT</dt>.*
1aae0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
1aaf0 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d  m number of term
1ab00 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20  s in a compound 
1ab10 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74  SELECT statement
1ab20 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
1ab30 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44  >SQLITE_LIMIT_VD
1ab40 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  BE_OP</dt>.** <d
1ab50 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
1ab60 6d 62 65 72 20 6f 66 20 69 6e 73 74 72 75 63 74  mber of instruct
1ab70 69 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 75 61  ions in a virtua
1ab80 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 61  l machine progra
1ab90 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d 70  m.** used to imp
1aba0 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 74  lement an SQL st
1abb0 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a  atement.</dd>.**
1abc0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  .** <dt>SQLITE_L
1abd0 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52  IMIT_FUNCTION_AR
1abe0 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  G</dt>.** <dd>Th
1abf0 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
1ac00 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e   of arguments on
1ac10 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64   a function.</dd
1ac20 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
1ac30 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45  TE_LIMIT_ATTACHE
1ac40 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
1ac50 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
1ac60 20 6f 66 20 61 74 74 61 63 68 65 64 20 64 61 74   of attached dat
1ac70 61 62 61 73 65 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a  abases.</dd>.**.
1ac80 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49  ** <dt>SQLITE_LI
1ac90 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e  MIT_LIKE_PATTERN
1aca0 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20  _LENGTH</dt>.** 
1acb0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
1acc0 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61  length of the pa
1acd0 74 74 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74  ttern argument t
1ace0 6f 20 74 68 65 20 4c 49 4b 45 20 6f 72 0a 2a 2a  o the LIKE or.**
1acf0 20 47 4c 4f 42 20 6f 70 65 72 61 74 6f 72 73 2e   GLOB operators.
1ad00 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
1ad10 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52  SQLITE_LIMIT_VAR
1ad20 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74  IABLE_NUMBER</dt
1ad30 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
1ad40 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 76  imum number of v
1ad50 61 72 69 61 62 6c 65 73 20 69 6e 20 61 6e 20 53  ariables in an S
1ad60 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61  QL statement tha
1ad70 74 20 63 61 6e 0a 2a 2a 20 62 65 20 62 6f 75 6e  t can.** be boun
1ad80 64 2e 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e  d.</dd>.** </dl>
1ad90 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
1ada0 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20  TE_LIMIT_LENGTH 
1adb0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1adc0 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c     0.#define SQL
1add0 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45  ITE_LIMIT_SQL_LE
1ade0 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20  NGTH            
1adf0 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
1ae00 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d  LITE_LIMIT_COLUM
1ae10 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  N               
1ae20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
1ae30 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52  QLITE_LIMIT_EXPR
1ae40 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20  _DEPTH          
1ae50 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
1ae60 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d  SQLITE_LIMIT_COM
1ae70 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20  POUND_SELECT    
1ae80 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65         4.#define
1ae90 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44   SQLITE_LIMIT_VD
1aea0 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20  BE_OP           
1aeb0 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e          5.#defin
1aec0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  e SQLITE_LIMIT_F
1aed0 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20  UNCTION_ARG     
1aee0 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69           6.#defi
1aef0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
1af00 41 54 54 41 43 48 45 44 20 20 20 20 20 20 20 20  ATTACHED        
1af10 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66            7.#def
1af20 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
1af30 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45  _LIKE_PATTERN_LE
1af40 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23 64 65  NGTH       8.#de
1af50 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
1af60 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45  T_VARIABLE_NUMBE
1af70 52 20 20 20 20 20 20 20 20 20 20 20 39 0a 0a 2f  R           9../
1af80 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
1af90 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20  ompiling An SQL 
1afa0 53 74 61 74 65 6d 65 6e 74 20 7b 46 31 33 30 31  Statement {F1301
1afb0 30 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63  0}.**.** To exec
1afc0 75 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79  ute an SQL query
1afd0 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73 74 20  , it must first 
1afe0 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f  be compiled into
1aff0 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20   a byte-code.** 
1b000 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e  program using on
1b010 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  e of these routi
1b020 6e 65 73 2e 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20  nes. .**.** The 
1b030 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 22  first argument "
1b040 64 62 22 20 69 73 20 61 6e 20 5b 64 61 74 61 62  db" is an [datab
1b050 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
1b060 0a 2a 2a 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  .** obtained fro
1b070 6d 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74  m a prior call t
1b080 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  o [sqlite3_open(
1b090 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
1b0a0 6e 5f 76 32 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73  n_v2()].** or [s
1b0b0 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
1b0c0 2e 20 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  . .** The second
1b0d0 20 61 72 67 75 6d 65 6e 74 20 22 7a 53 71 6c 22   argument "zSql"
1b0e0 20 69 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e   is the statemen
1b0f0 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64  t to be compiled
1b100 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20  , encoded.** as 
1b110 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20  either UTF-8 or 
1b120 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c  UTF-16.  The sql
1b130 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 61  ite3_prepare() a
1b140 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
1b150 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72  re_v2().** inter
1b160 66 61 63 65 73 20 75 73 65 73 20 55 54 46 2d 38  faces uses UTF-8
1b170 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
1b180 70 61 72 65 31 36 28 29 20 61 6e 64 20 73 71 6c  pare16() and sql
1b190 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
1b1a0 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31  2().** use UTF-1
1b1b0 36 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 49  6. {END}.**.** I
1b1c0 66 20 74 68 65 20 6e 42 79 74 65 20 61 72 67 75  f the nByte argu
1b1d0 6d 65 6e 74 20 69 73 20 6c 65 73 73 0a 2a 2a 20  ment is less.** 
1b1e0 74 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65 6e 20  than zero, then 
1b1f0 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75 70 20  zSql is read up 
1b200 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72  to the first zer
1b210 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a  o terminator..**
1b220 20 49 66 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e   If nByte is non
1b230 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20  -negative, then 
1b240 69 74 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75  it is the maximu
1b250 6d 20 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20  m number of .** 
1b260 62 79 74 65 73 20 72 65 61 64 20 66 72 6f 6d 20  bytes read from 
1b270 7a 53 71 6c 2e 20 20 57 68 65 6e 20 6e 42 79 74  zSql.  When nByt
1b280 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  e is non-negativ
1b290 65 2c 20 74 68 65 0a 2a 2a 20 7a 53 71 6c 20 73  e, the.** zSql s
1b2a0 74 72 69 6e 67 20 65 6e 64 73 20 61 74 20 65 69  tring ends at ei
1b2b0 74 68 65 72 20 74 68 65 20 66 69 72 73 74 20 27  ther the first '
1b2c0 5c 30 30 30 27 20 6f 72 20 27 5c 75 30 30 30 30  \000' or '\u0000
1b2d0 27 20 63 68 61 72 61 63 74 65 72 20 6f 72 20 0a  ' character or .
1b2e0 2a 2a 20 74 68 65 20 6e 42 79 74 65 2d 74 68 20  ** the nByte-th 
1b2f0 62 79 74 65 2c 20 77 68 69 63 68 65 76 65 72 20  byte, whichever 
1b300 63 6f 6d 65 73 20 66 69 72 73 74 2e 20 49 66 20  comes first. If 
1b310 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73  the caller knows
1b320 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 73 75 70  .** that the sup
1b330 70 6c 69 65 64 20 73 74 72 69 6e 67 20 69 73 20  plied string is 
1b340 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20  nul-terminated, 
1b350 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 61 20  then there is a 
1b360 73 6d 61 6c 6c 0a 2a 2a 20 70 65 72 66 6f 72 6d  small.** perform
1b370 61 6e 63 65 20 61 64 76 61 6e 74 61 67 65 20 74  ance advantage t
1b380 6f 20 62 65 20 68 61 64 20 62 79 20 70 61 73 73  o be had by pass
1b390 69 6e 67 20 61 6e 20 6e 42 79 74 65 20 70 61 72  ing an nByte par
1b3a0 61 6d 65 74 65 72 20 74 68 61 74 20 0a 2a 2a 20  ameter that .** 
1b3b0 69 73 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20  is equal to the 
1b3c0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
1b3d0 69 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72  in the input str
1b3e0 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67  ing <i>including
1b3f0 3c 2f 69 3e 20 0a 2a 2a 20 74 68 65 20 6e 75 6c  </i> .** the nul
1b400 2d 74 65 72 6d 69 6e 61 74 6f 72 20 62 79 74 65  -terminator byte
1b410 73 2e 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 2a 70  s.{END}.**.** *p
1b420 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f  zTail is made to
1b430 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 66 69   point to the fi
1b440 72 73 74 20 62 79 74 65 20 70 61 73 74 20 74 68  rst byte past th
1b450 65 20 65 6e 64 20 6f 66 20 74 68 65 0a 2a 2a 20  e end of the.** 
1b460 66 69 72 73 74 20 53 51 4c 20 73 74 61 74 65 6d  first SQL statem
1b470 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68  ent in zSql.  Th
1b480 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c  ese routines onl
1b490 79 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69  y compile the fi
1b4a0 72 73 74 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  rst.** statement
1b4b0 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a   in zSql, so *pz
1b4c0 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f 69  Tail is left poi
1b4d0 6e 74 69 6e 67 20 74 6f 20 77 68 61 74 20 72 65  nting to what re
1b4e0 6d 61 69 6e 73 0a 2a 2a 20 75 6e 63 6f 6d 70 69  mains.** uncompi
1b4f0 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 2a 70 70 53 74  led..**.** *ppSt
1b500 6d 74 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74  mt is left point
1b510 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65  ing to a compile
1b520 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
1b530 65 6d 65 6e 74 5d 20 74 68 61 74 20 63 61 6e 20  ement] that can 
1b540 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 75  be.** executed u
1b550 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74  sing [sqlite3_st
1b560 65 70 28 29 5d 2e 20 20 4f 72 20 69 66 20 74 68  ep()].  Or if th
1b570 65 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c  ere is an error,
1b580 20 2a 70 70 53 74 6d 74 20 69 73 0a 2a 2a 20 73   *ppStmt is.** s
1b590 65 74 20 74 6f 20 4e 55 4c 4c 2e 20 20 49 66 20  et to NULL.  If 
1b5a0 74 68 65 20 69 6e 70 75 74 20 74 65 78 74 20 63  the input text c
1b5b0 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28  ontains no SQL (
1b5c0 69 66 20 74 68 65 20 69 6e 70 75 74 0a 2a 2a 20  if the input.** 
1b5d0 69 73 20 61 6e 64 20 65 6d 70 74 79 20 73 74 72  is and empty str
1b5e0 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74  ing or a comment
1b5f0 29 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 69  ) then *ppStmt i
1b600 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a  s set to NULL..*
1b610 2a 20 7b 55 31 33 30 31 38 7d 20 54 68 65 20 63  * {U13018} The c
1b620 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65  alling procedure
1b630 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20   is responsible 
1b640 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65  for deleting the
1b650 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 53 51 4c  .** compiled SQL
1b660 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 75 73   statement.** us
1b670 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  ing [sqlite3_fin
1b680 61 6c 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69  alize()] after i
1b690 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77  t has finished w
1b6a0 69 74 68 20 69 74 2e 0a 2a 2a 0a 2a 2a 20 4f 6e  ith it..**.** On
1b6b0 20 73 75 63 63 65 73 73 2c 20 5b 53 51 4c 49 54   success, [SQLIT
1b6c0 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65  E_OK] is returne
1b6d0 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e  d.  Otherwise an
1b6e0 20 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65   .** [error code
1b6f0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  ] is returned..*
1b700 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
1b710 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 61 6e  _prepare_v2() an
1b720 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
1b730 65 31 36 5f 76 32 28 29 20 69 6e 74 65 72 66 61  e16_v2() interfa
1b740 63 65 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d  ces are.** recom
1b750 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e  mended for all n
1b760 65 77 20 70 72 6f 67 72 61 6d 73 2e 20 54 68 65  ew programs. The
1b770 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72   two older inter
1b780 66 61 63 65 73 20 61 72 65 20 72 65 74 61 69 6e  faces are retain
1b790 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61  ed.** for backwa
1b7a0 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
1b7b0 79 2c 20 62 75 74 20 74 68 65 69 72 20 75 73 65  y, but their use
1b7c0 20 69 73 20 64 69 73 63 6f 75 72 61 67 65 64 2e   is discouraged.
1b7d0 0a 2a 2a 20 49 6e 20 74 68 65 20 22 76 32 22 20  .** In the "v2" 
1b7e0 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20  interfaces, the 
1b7f0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1b800 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 65  nt.** that is re
1b810 74 75 72 6e 65 64 20 28 74 68 65 20 5b 73 71 6c  turned (the [sql
1b820 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63  ite3_stmt] objec
1b830 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f  t) contains a co
1b840 70 79 20 6f 66 20 74 68 65 20 0a 2a 2a 20 6f 72  py of the .** or
1b850 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e  iginal SQL text.
1b860 20 7b 45 4e 44 7d 20 54 68 69 73 20 63 61 75 73   {END} This caus
1b870 65 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  es the [sqlite3_
1b880 73 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61 63  step()] interfac
1b890 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20 61  e to.** behave a
1b8a0 20 64 69 66 66 65 72 65 6e 74 6c 79 20 69 6e 20   differently in 
1b8b0 74 77 6f 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20  two ways:.**.** 
1b8c0 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20  <ol>.** <li>.** 
1b8d0 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
1b8e0 73 63 68 65 6d 61 20 63 68 61 6e 67 65 73 2c 20  schema changes, 
1b8f0 69 6e 73 74 65 61 64 20 6f 66 20 72 65 74 75 72  instead of retur
1b900 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43 48  ning [SQLITE_SCH
1b910 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c  EMA] as it.** al
1b920 77 61 79 73 20 75 73 65 64 20 74 6f 20 64 6f 2c  ways used to do,
1b930 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1b940 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63  ] will automatic
1b950 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20 74  ally recompile t
1b960 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d  he SQL.** statem
1b970 65 6e 74 20 61 6e 64 20 74 72 79 20 74 6f 20 72  ent and try to r
1b980 75 6e 20 69 74 20 61 67 61 69 6e 2e 20 20 49 66  un it again.  If
1b990 20 74 68 65 20 73 63 68 65 6d 61 20 68 61 73 20   the schema has 
1b9a0 63 68 61 6e 67 65 64 20 69 6e 0a 2a 2a 20 61 20  changed in.** a 
1b9b0 77 61 79 20 74 68 61 74 20 6d 61 6b 65 73 20 74  way that makes t
1b9c0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 6e 6f 20  he statement no 
1b9d0 6c 6f 6e 67 65 72 20 76 61 6c 69 64 2c 20 5b 73  longer valid, [s
1b9e0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77  qlite3_step()] w
1b9f0 69 6c 6c 20 73 74 69 6c 6c 0a 2a 2a 20 72 65 74  ill still.** ret
1ba00 75 72 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48 45  urn [SQLITE_SCHE
1ba10 4d 41 5d 2e 20 20 42 75 74 20 75 6e 6c 69 6b 65  MA].  But unlike
1ba20 20 74 68 65 20 6c 65 67 61 63 79 20 62 65 68 61   the legacy beha
1ba30 76 69 6f 72 2c 20 0a 2a 2a 20 5b 53 51 4c 49 54  vior, .** [SQLIT
1ba40 45 5f 53 43 48 45 4d 41 5d 20 69 73 20 6e 6f 77  E_SCHEMA] is now
1ba50 20 61 20 66 61 74 61 6c 20 65 72 72 6f 72 2e 20   a fatal error. 
1ba60 20 43 61 6c 6c 69 6e 67 0a 2a 2a 20 5b 73 71 6c   Calling.** [sql
1ba70 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1ba80 29 5d 20 61 67 61 69 6e 20 77 69 6c 6c 20 6e 6f  )] again will no
1ba90 74 20 6d 61 6b 65 20 74 68 65 0a 2a 2a 20 65 72  t make the.** er
1baa0 72 6f 72 20 67 6f 20 61 77 61 79 2e 20 20 4e 6f  ror go away.  No
1bab0 74 65 3a 20 75 73 65 20 5b 73 71 6c 69 74 65 33  te: use [sqlite3
1bac0 5f 65 72 72 6d 73 67 28 29 5d 20 74 6f 20 66 69  _errmsg()] to fi
1bad0 6e 64 20 74 68 65 20 74 65 78 74 0a 2a 2a 20 6f  nd the text.** o
1bae0 66 20 74 68 65 20 70 61 72 73 69 6e 67 20 65 72  f the parsing er
1baf0 72 6f 72 20 74 68 61 74 20 72 65 73 75 6c 74 73  ror that results
1bb00 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 53   in an [SQLITE_S
1bb10 43 48 45 4d 41 5d 20 72 65 74 75 72 6e 2e 20 7b  CHEMA] return. {
1bb20 45 4e 44 7d 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a  END}.** </li>.**
1bb30 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 57 68 65 6e  .** <li>.** When
1bb40 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
1bb50 2c 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  , .** [sqlite3_s
1bb60 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  tep()] will retu
1bb70 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65  rn one of the de
1bb80 74 61 69 6c 65 64 20 0a 2a 2a 20 5b 65 72 72 6f  tailed .** [erro
1bb90 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74  r codes] or [ext
1bba0 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65  ended error code
1bbb0 73 5d 2e 20 0a 2a 2a 20 54 68 65 20 6c 65 67 61  s]. .** The lega
1bbc0 63 79 20 62 65 68 61 76 69 6f 72 20 77 61 73 20  cy behavior was 
1bbd0 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 73 74  that [sqlite3_st
1bbe0 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79  ep()] would only
1bbf0 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65 72 69   return a generi
1bc00 63 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52  c.** [SQLITE_ERR
1bc10 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 20  OR] result code 
1bc20 61 6e 64 20 79 6f 75 20 77 6f 75 6c 64 20 68 61  and you would ha
1bc30 76 65 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 63  ve to make a sec
1bc40 6f 6e 64 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  ond call to.** [
1bc50 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
1bc60 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e   in order to fin
1bc70 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67  d the underlying
1bc80 20 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72   cause of the pr
1bc90 6f 62 6c 65 6d 2e 0a 2a 2a 20 57 69 74 68 20 74  oblem..** With t
1bca0 68 65 20 22 76 32 22 20 70 72 65 70 61 72 65 20  he "v2" prepare 
1bcb0 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20  interfaces, the 
1bcc0 75 6e 64 65 72 6c 79 69 6e 67 20 72 65 61 73 6f  underlying reaso
1bcd0 6e 20 66 6f 72 20 74 68 65 20 65 72 72 6f 72 20  n for the error 
1bce0 69 73 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69  is.** returned i
1bcf0 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c  mmediately..** <
1bd00 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a  /li>.** </ol>.**
1bd10 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
1bd20 2a 2a 0a 2a 2a 20 7b 46 31 33 30 31 31 7d 20 54  **.** {F13011} T
1bd30 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  he [sqlite3_prep
1bd40 61 72 65 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29  are(db,zSql,...)
1bd50 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20  ] and.**        
1bd60 20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61    [sqlite3_prepa
1bd70 72 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 2e 2e  re_v2(db,zSql,..
1bd80 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 69  .)] interfaces i
1bd90 6e 74 65 72 70 72 65 74 20 74 68 65 0a 2a 2a 20  nterpret the.** 
1bda0 20 20 20 20 20 20 20 20 20 74 65 78 74 20 69 6e           text in
1bdb0 20 74 68 65 69 72 20 7a 53 71 6c 20 70 61 72 61   their zSql para
1bdc0 6d 65 74 65 72 20 61 73 20 55 54 46 2d 38 2e 0a  meter as UTF-8..
1bdd0 2a 2a 0a 2a 2a 20 7b 46 31 33 30 31 32 7d 20 54  **.** {F13012} T
1bde0 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  he [sqlite3_prep
1bdf0 61 72 65 31 36 28 64 62 2c 7a 53 71 6c 2c 2e 2e  are16(db,zSql,..
1be00 2e 29 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20  .)] and.**      
1be10 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65      [sqlite3_pre
1be20 70 61 72 65 31 36 5f 76 32 28 64 62 2c 7a 53 71  pare16_v2(db,zSq
1be30 6c 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63  l,...)] interfac
1be40 65 73 20 69 6e 74 65 72 70 72 65 74 20 74 68 65  es interpret the
1be50 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 65 78  .**          tex
1be60 74 20 69 6e 20 74 68 65 69 72 20 7a 53 71 6c 20  t in their zSql 
1be70 70 61 72 61 6d 65 74 65 72 20 61 73 20 55 54 46  parameter as UTF
1be80 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76  -16 in the nativ
1be90 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a  e byte order..**
1bea0 0a 2a 2a 20 7b 46 31 33 30 31 33 7d 20 49 66 20  .** {F13013} If 
1beb0 74 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65  the nByte argume
1bec0 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70  nt to [sqlite3_p
1bed0 72 65 70 61 72 65 5f 76 32 28 64 62 2c 7a 53 71  repare_v2(db,zSq
1bee0 6c 2c 6e 42 79 74 65 2c 2e 2e 2e 29 5d 0a 2a 2a  l,nByte,...)].**
1bef0 20 20 20 20 20 20 20 20 20 20 61 6e 64 20 69 74            and it
1bf00 73 20 76 61 72 69 61 6e 74 73 20 69 73 20 6c 65  s variants is le
1bf10 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20 74 68  ss than zero, th
1bf20 65 6e 20 53 51 4c 20 74 65 78 74 20 69 73 0a 2a  en SQL text is.*
1bf30 2a 20 20 20 20 20 20 20 20 20 20 72 65 61 64 20  *          read 
1bf40 66 72 6f 6d 20 7a 53 71 6c 20 69 73 20 72 65 61  from zSql is rea
1bf50 64 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73  d up to the firs
1bf60 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  t zero terminato
1bf70 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 30 31 34  r..**.** {F13014
1bf80 7d 20 49 66 20 74 68 65 20 6e 42 79 74 65 20 61  } If the nByte a
1bf90 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69  rgument to [sqli
1bfa0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 64  te3_prepare_v2(d
1bfb0 62 2c 7a 53 71 6c 2c 6e 42 79 74 65 2c 2e 2e 2e  b,zSql,nByte,...
1bfc0 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  )].**          a
1bfd0 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 20  nd its variants 
1bfe0 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c  is non-negative,
1bff0 20 74 68 65 6e 20 61 74 20 6d 6f 73 74 20 6e 42   then at most nB
1c000 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20 20 20  ytes bytes.**   
1c010 20 20 20 20 20 20 20 53 51 4c 20 74 65 78 74 20         SQL text 
1c020 69 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71  is read from zSq
1c030 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 30 31 35  l..**.** {F13015
1c040 7d 20 49 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72  } In [sqlite3_pr
1c050 65 70 61 72 65 5f 76 32 28 64 62 2c 7a 53 71 6c  epare_v2(db,zSql
1c060 2c 4e 2c 50 2c 70 7a 54 61 69 6c 29 5d 20 61 6e  ,N,P,pzTail)] an
1c070 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 0a 2a  d its variants.*
1c080 2a 20 20 20 20 20 20 20 20 20 20 69 66 20 74 68  *          if th
1c090 65 20 7a 53 71 6c 20 69 6e 70 75 74 20 74 65 78  e zSql input tex
1c0a0 74 20 63 6f 6e 74 61 69 6e 73 20 6d 6f 72 65 20  t contains more 
1c0b0 74 68 61 6e 20 6f 6e 65 20 53 51 4c 20 73 74 61  than one SQL sta
1c0c0 74 65 6d 65 6e 74 0a 2a 2a 20 20 20 20 20 20 20  tement.**       
1c0d0 20 20 20 61 6e 64 20 70 7a 54 61 69 6c 20 69 73     and pzTail is
1c0e0 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20   not NULL, then 
1c0f0 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20  *pzTail is made 
1c100 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 0a  to point to the.
1c110 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 72 73  **          firs
1c120 74 20 62 79 74 65 20 70 61 73 74 20 74 68 65 20  t byte past the 
1c130 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73 74  end of the first
1c140 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69   SQL statement i
1c150 6e 20 7a 53 71 6c 2e 0a 2a 2a 20 20 20 20 20 20  n zSql..**      
1c160 20 20 20 20 3c 74 6f 64 6f 3e 57 68 61 74 20 64      <todo>What d
1c170 6f 65 73 20 2a 70 7a 54 61 69 6c 20 70 6f 69 6e  oes *pzTail poin
1c180 74 20 74 6f 20 69 66 20 74 68 65 72 65 20 69 73  t to if there is
1c190 20 6f 6e 65 20 73 74 61 74 65 6d 65 6e 74 3f 3c   one statement?<
1c1a0 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 7b 46 31  /todo>.**.** {F1
1c1b0 33 30 31 36 7d 20 41 20 73 75 63 63 65 73 73 66  3016} A successf
1c1c0 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ul call to [sqli
1c1d0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 64  te3_prepare_v2(d
1c1e0 62 2c 7a 53 71 6c 2c 4e 2c 70 70 53 74 6d 74 2c  b,zSql,N,ppStmt,
1c1f0 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  ...)].**        
1c200 20 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20    or one of its 
1c210 76 61 72 69 61 6e 74 73 20 77 72 69 74 65 73 20  variants writes 
1c220 69 6e 74 6f 20 2a 70 70 53 74 6d 74 20 61 20 70  into *ppStmt a p
1c230 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e 65 77 0a  ointer to a new.
1c240 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65  **          [pre
1c250 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
1c260 20 6f 72 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   or a pointer to
1c270 20 4e 55 4c 4c 0a 2a 2a 20 20 20 20 20 20 20 20   NULL.**        
1c280 20 20 69 66 20 7a 53 71 6c 20 63 6f 6e 74 61 69    if zSql contai
1c290 6e 73 20 6e 6f 74 68 69 6e 67 20 6f 74 68 65 72  ns nothing other
1c2a0 20 74 68 61 6e 20 77 68 69 74 65 73 70 61 63 65   than whitespace
1c2b0 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 2e 20 0a 2a   or comments. .*
1c2c0 2a 0a 2a 2a 20 7b 46 31 33 30 31 39 7d 20 54 68  *.** {F13019} Th
1c2d0 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  e [sqlite3_prepa
1c2e0 72 65 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61  re_v2()] interfa
1c2f0 63 65 20 61 6e 64 20 69 74 73 20 76 61 72 69 61  ce and its varia
1c300 6e 74 73 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20  nts return.**   
1c310 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 4f         [SQLITE_O
1c320 4b 5d 20 6f 72 20 61 6e 20 61 70 70 72 6f 70 72  K] or an appropr
1c330 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65  iate [error code
1c340 5d 20 75 70 6f 6e 20 66 61 69 6c 75 72 65 2e 0a  ] upon failure..
1c350 2a 2a 0a 2a 2a 20 7b 46 31 33 30 32 31 7d 20 42  **.** {F13021} B
1c360 65 66 6f 72 65 20 5b 73 71 6c 69 74 65 33 5f 70  efore [sqlite3_p
1c370 72 65 70 61 72 65 28 64 62 2c 7a 53 71 6c 2c 6e  repare(db,zSql,n
1c380 42 79 74 65 2c 70 70 53 74 6d 74 2c 70 7a 54 61  Byte,ppStmt,pzTa
1c390 69 6c 29 5d 20 6f 72 20 69 74 73 0a 2a 2a 20 20  il)] or its.**  
1c3a0 20 20 20 20 20 20 20 20 76 61 72 69 61 6e 74 73          variants
1c3b0 20 72 65 74 75 72 6e 73 20 61 6e 20 65 72 72 6f   returns an erro
1c3c0 72 20 28 61 6e 79 20 76 61 6c 75 65 20 6f 74 68  r (any value oth
1c3d0 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
1c3e0 4f 4b 5d 29 0a 2a 2a 20 20 20 20 20 20 20 20 20  OK]).**         
1c3f0 20 69 74 20 66 69 72 73 74 20 73 65 74 73 20 2a   it first sets *
1c400 70 70 53 74 6d 74 20 74 6f 20 4e 55 4c 4c 2e 0a  ppStmt to NULL..
1c410 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  */.int sqlite3_p
1c420 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74 65  repare(.  sqlite
1c430 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
1c440 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
1c450 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
1c460 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20  char *zSql,     
1c470 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
1c480 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  nt, UTF-8 encode
1c490 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
1c4a0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
1c4b0 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
1c4c0 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
1c4d0 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
1c4e0 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
1c4f0 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
1c500 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
1c510 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69  nst char **pzTai
1c520 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
1c530 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
1c540 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
1c550 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
1c560 33 5f 70 72 65 70 61 72 65 5f 76 32 28 0a 20 20  3_prepare_v2(.  
1c570 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
1c580 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
1c590 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
1c5a0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c  const char *zSql
1c5b0 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
1c5c0 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20  tatement, UTF-8 
1c5d0 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
1c5e0 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
1c5f0 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
1c600 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
1c610 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
1c620 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
1c630 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
1c640 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
1c650 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
1c660 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
1c670 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
1c680 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
1c690 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20   zSql */.);.int 
1c6a0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1c6b0 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  6(.  sqlite3 *db
1c6c0 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
1c6d0 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
1c6e0 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
1c6f0 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
1c700 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
1c710 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f  TF-16 encoded */
1c720 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
1c730 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
1c740 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
1c750 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
1c760 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
1c770 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
1c780 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
1c790 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
1c7a0 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20  void **pzTail   
1c7b0 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
1c7c0 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
1c7d0 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
1c7e0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  ;.int sqlite3_pr
1c7f0 65 70 61 72 65 31 36 5f 76 32 28 0a 20 20 73 71  epare16_v2(.  sq
1c800 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
1c810 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
1c820 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
1c830 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20  nst void *zSql, 
1c840 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
1c850 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65  tement, UTF-16 e
1c860 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
1c870 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
1c880 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
1c890 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
1c8a0 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
1c8b0 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
1c8c0 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
1c8d0 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
1c8e0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a  .  const void **
1c8f0 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
1c900 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
1c910 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
1c920 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a  zSql */.);../*.*
1c930 2a 20 43 41 50 49 52 45 46 3a 20 52 65 74 72 69  * CAPIREF: Retri
1c940 65 76 69 6e 67 20 53 74 61 74 65 6d 65 6e 74 20  eving Statement 
1c950 53 51 4c 20 7b 46 31 33 31 30 30 7d 0a 2a 2a 0a  SQL {F13100}.**.
1c960 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
1c970 65 20 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  e  can be used t
1c980 6f 20 72 65 74 72 69 65 76 65 20 61 20 73 61 76  o retrieve a sav
1c990 65 64 20 63 6f 70 79 20 6f 66 20 74 68 65 20 6f  ed copy of the o
1c9a0 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74  riginal.** SQL t
1c9b0 65 78 74 20 75 73 65 64 20 74 6f 20 63 72 65 61  ext used to crea
1c9c0 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  te a [prepared s
1c9d0 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 0a 2a 2a  tatement]..**.**
1c9e0 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
1c9f0 2a 2a 20 7b 46 31 33 31 30 31 7d 20 49 66 20 74  ** {F13101} If t
1ca00 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
1ca10 74 65 6d 65 6e 74 5d 20 70 61 73 73 65 64 20 61  tement] passed a
1ca20 73 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  s .**          t
1ca30 68 65 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 74  he an argument t
1ca40 6f 20 5b 73 71 6c 69 74 65 33 5f 73 71 6c 28 29  o [sqlite3_sql()
1ca50 5d 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 0a 2a  ] was compiled.*
1ca60 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6d 70 69  *          compi
1ca70 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72  led using either
1ca80 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1ca90 65 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 20 20  e_v2()] or.**   
1caa0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
1cab0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2c  prepare16_v2()],
1cac0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
1cad0 6e 20 5b 73 71 6c 69 74 65 33 5f 73 71 6c 28 29  n [sqlite3_sql()
1cae0 5d 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  ] function retur
1caf0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
1cb00 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65  a.**          ze
1cb10 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74  ro-terminated st
1cb20 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20  ring containing 
1cb30 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e  a UTF-8 renderin
1cb40 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66  g.**          of
1cb50 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 53 51   the original SQ
1cb60 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a  L statement..**.
1cb70 2a 2a 20 7b 46 31 33 31 30 32 7d 20 49 66 20 74  ** {F13102} If t
1cb80 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
1cb90 74 65 6d 65 6e 74 5d 20 70 61 73 73 65 64 20 61  tement] passed a
1cba0 73 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  s .**          t
1cbb0 68 65 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 74  he an argument t
1cbc0 6f 20 5b 73 71 6c 69 74 65 33 5f 73 71 6c 28 29  o [sqlite3_sql()
1cbd0 5d 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 0a 2a  ] was compiled.*
1cbe0 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6d 70 69  *          compi
1cbf0 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72  led using either
1cc00 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1cc10 65 28 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20  e()] or.**      
1cc20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65      [sqlite3_pre
1cc30 70 61 72 65 31 36 28 29 5d 2c 0a 2a 2a 20 20 20  pare16()],.**   
1cc40 20 20 20 20 20 20 20 74 68 65 6e 20 5b 73 71 6c         then [sql
1cc50 69 74 65 33 5f 73 71 6c 28 29 5d 20 66 75 6e 63  ite3_sql()] func
1cc60 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20 4e  tion returns a N
1cc70 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
1cc80 2a 2a 20 7b 46 31 33 31 30 33 7d 20 54 68 65 20  ** {F13103} The 
1cc90 73 74 72 69 6e 67 20 72 65 74 75 72 6e 65 64 20  string returned 
1cca0 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 71 6c 28  by [sqlite3_sql(
1ccb0 53 29 5d 20 69 73 20 76 61 6c 69 64 20 75 6e 74  S)] is valid unt
1ccc0 69 6c 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  il the.**       
1ccd0 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61     [prepared sta
1cce0 74 65 6d 65 6e 74 5d 20 53 20 69 73 20 64 65 6c  tement] S is del
1ccf0 65 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  eted using [sqli
1cd00 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 5d  te3_finalize(S)]
1cd10 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
1cd20 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c  *sqlite3_sql(sql
1cd30 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
1cd40 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1cd50 45 46 3a 20 20 44 79 6e 61 6d 69 63 61 6c 6c 79  EF:  Dynamically
1cd60 20 54 79 70 65 64 20 56 61 6c 75 65 20 4f 62 6a   Typed Value Obj
1cd70 65 63 74 20 20 7b 46 31 35 30 30 30 7d 0a 2a 2a  ect  {F15000}.**
1cd80 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74   KEYWORDS: {prot
1cd90 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
1cda0 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65  lue} {unprotecte
1cdb0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d  d sqlite3_value}
1cdc0 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73  .**.** SQLite us
1cdd0 65 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  es the sqlite3_v
1cde0 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f 20 72  alue object to r
1cdf0 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c  epresent all val
1ce00 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20  ues.** that can 
1ce10 62 65 20 73 74 6f 72 65 64 20 69 6e 20 61 20 64  be stored in a d
1ce20 61 74 61 62 61 73 65 20 74 61 62 6c 65 2e 0a 2a  atabase table..*
1ce30 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 64 79  * SQLite uses dy
1ce40 6e 61 6d 69 63 20 74 79 70 69 6e 67 20 66 6f 72  namic typing for
1ce50 20 74 68 65 20 76 61 6c 75 65 73 20 69 74 20 73   the values it s
1ce60 74 6f 72 65 73 2e 20 20 0a 2a 2a 20 56 61 6c 75  tores.  .** Valu
1ce70 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c  es stored in sql
1ce80 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
1ce90 74 73 20 63 61 6e 20 62 65 0a 2a 2a 20 62 65 20  ts can be.** be 
1cea0 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69  integers, floati
1ceb0 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c  ng point values,
1cec0 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c   strings, BLOBs,
1ced0 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   or NULL..**.** 
1cee0 41 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  An sqlite3_value
1cef0 20 6f 62 6a 65 63 74 20 6d 61 79 20 62 65 20 65   object may be e
1cf00 69 74 68 65 72 20 22 70 72 6f 74 65 63 74 65 64  ither "protected
1cf10 22 20 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 65  " or "unprotecte
1cf20 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65  d"..** Some inte
1cf30 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20 61  rfaces require a
1cf40 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74   protected sqlit
1cf50 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 72  e3_value.  Other
1cf60 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 77   interfaces.** w
1cf70 69 6c 6c 20 61 63 63 65 70 74 20 65 69 74 68 65  ill accept eithe
1cf80 72 20 61 20 70 72 6f 74 65 63 74 65 64 20 6f 72  r a protected or
1cf90 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20   an unprotected 
1cfa0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a  sqlite3_value..*
1cfb0 2a 20 45 76 65 72 79 20 69 6e 74 65 72 66 61 63  * Every interfac
1cfc0 65 20 74 68 61 74 20 61 63 63 65 70 74 73 20 73  e that accepts s
1cfd0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 61 72 67  qlite3_value arg
1cfe0 75 6d 65 6e 74 73 20 73 70 65 63 69 66 69 65 73  uments specifies
1cff0 20 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 20   .** whether or 
1d000 6e 6f 74 20 69 74 20 72 65 71 75 69 72 65 73 20  not it requires 
1d010 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  a protected sqli
1d020 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a  te3_value..**.**
1d030 20 54 68 65 20 74 65 72 6d 73 20 22 70 72 6f 74   The terms "prot
1d040 65 63 74 65 64 22 20 61 6e 64 20 22 75 6e 70 72  ected" and "unpr
1d050 6f 74 65 63 74 65 64 22 20 72 65 66 65 72 20 74  otected" refer t
1d060 6f 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  o whether or not
1d070 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69 73 20 68  .** a mutex is h
1d080 65 6c 64 2e 20 20 41 20 69 6e 74 65 72 6e 61 6c  eld.  A internal
1d090 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66   mutex is held f
1d0a0 6f 72 20 61 20 70 72 6f 74 65 63 74 65 64 0a 2a  or a protected.*
1d0b0 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  * sqlite3_value 
1d0c0 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d 75  object but no mu
1d0d0 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20  tex is held for 
1d0e0 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a  an unprotected.*
1d0f0 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  * sqlite3_value 
1d100 6f 62 6a 65 63 74 2e 20 20 49 66 20 53 51 4c 69  object.  If SQLi
1d110 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 74  te is compiled t
1d120 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74 68 72 65  o be single-thre
1d130 61 64 65 64 0a 2a 2a 20 28 77 69 74 68 20 53 51  aded.** (with SQ
1d140 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
1d150 30 20 61 6e 64 20 77 69 74 68 20 5b 73 71 6c 69  0 and with [sqli
1d160 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29  te3_threadsafe()
1d170 5d 20 72 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a  ] returning 0).*
1d180 2a 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20  * then there is 
1d190 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62  no distinction b
1d1a0 65 74 77 65 65 6e 0a 2a 2a 20 70 72 6f 74 65 63  etween.** protec
1d1b0 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63  ted and unprotec
1d1c0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
1d1d0 65 20 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68  e objects and th
1d1e0 65 79 20 63 61 6e 20 62 65 0a 2a 2a 20 75 73 65  ey can be.** use
1d1f0 64 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62 6c  d interchangeabl
1d200 65 2e 20 20 48 6f 77 65 76 65 72 2c 20 66 6f 72  e.  However, for
1d210 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f   maximum code po
1d220 72 74 61 62 69 6c 69 74 79 20 69 74 0a 2a 2a 20  rtability it.** 
1d230 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74  is recommended t
1d240 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  hat applications
1d250 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e   make the distin
1d260 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a  ction between.**
1d270 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74   between protect
1d280 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74  ed and unprotect
1d290 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
1d2a0 20 6f 62 6a 65 63 74 73 20 65 76 65 6e 20 69 66   objects even if
1d2b0 0a 2a 2a 20 74 68 65 79 20 61 72 65 20 73 69 6e  .** they are sin
1d2c0 67 6c 65 20 74 68 72 65 61 64 65 64 2e 0a 2a 2a  gle threaded..**
1d2d0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
1d2e0 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 74 68  value objects th
1d2f0 61 74 20 61 72 65 20 70 61 73 73 65 64 20 61 73  at are passed as
1d300 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 74 6f   parameters into
1d310 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e   the.** implemen
1d320 74 61 74 69 6f 6e 20 6f 66 20 0a 2a 2a 20 5b 73  tation of .** [s
1d330 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
1d340 6e 63 74 69 6f 6e 20 7c 20 61 70 70 6c 69 63 61  nction | applica
1d350 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
1d360 20 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20 61   functions].** a
1d370 72 65 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a  re protected..**
1d380 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c   The sqlite3_val
1d390 75 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  ue object return
1d3a0 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  ed by.** [sqlite
1d3b0 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29  3_column_value()
1d3c0 5d 20 69 73 20 75 6e 70 72 6f 74 65 63 74 65 64  ] is unprotected
1d3d0 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65 64  ..** Unprotected
1d3e0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
1d3f0 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20  bjects may only 
1d400 62 65 20 75 73 65 64 20 77 69 74 68 0a 2a 2a 20  be used with.** 
1d410 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
1d420 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71  value()] and [sq
1d430 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65  lite3_bind_value
1d440 28 29 5d 2e 20 20 0a 2a 2a 20 54 68 65 20 5b 73  ()].  .** The [s
1d450 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f  qlite3_value_blo
1d460 62 20 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  b | sqlite3_valu
1d470 65 5f 74 79 70 65 28 29 5d 20 66 61 6d 69 6c 79  e_type()] family
1d480 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65   of.** interface
1d490 73 20 72 65 71 75 69 72 65 20 70 72 6f 74 65 63  s require protec
1d4a0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
1d4b0 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79  e objects..*/.ty
1d4c0 70 65 64 65 66 20 73 74 72 75 63 74 20 4d 65 6d  pedef struct Mem
1d4d0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a   sqlite3_value;.
1d4e0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1d4f0 20 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43    SQL Function C
1d500 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 20 7b 46  ontext Object {F
1d510 31 36 30 30 31 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  16001}.**.** The
1d520 20 63 6f 6e 74 65 78 74 20 69 6e 20 77 68 69 63   context in whic
1d530 68 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f  h an SQL functio
1d540 6e 20 65 78 65 63 75 74 65 73 20 69 73 20 73 74  n executes is st
1d550 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71  ored in an.** sq
1d560 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62  lite3_context ob
1d570 6a 65 63 74 2e 20 20 41 20 70 6f 69 6e 74 65 72  ject.  A pointer
1d580 20 74 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63   to an sqlite3_c
1d590 6f 6e 74 65 78 74 0a 2a 2a 20 6f 62 6a 65 63 74  ontext.** object
1d5a0 20 69 73 20 61 6c 77 61 79 73 20 66 69 72 73 74   is always first
1d5b0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 0a 2a   parameter to .*
1d5c0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  * [sqlite3_creat
1d5d0 65 5f 66 75 6e 63 74 69 6f 6e 20 7c 20 61 70 70  e_function | app
1d5e0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
1d5f0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e   SQL functions].
1d600 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
1d610 69 6f 6e 65 64 2d 64 65 66 69 6e 65 64 20 53 51  ioned-defined SQ
1d620 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  L function imple
1d630 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70  mentation will p
1d640 61 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e  ass this.** poin
1d650 74 65 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f  ter through into
1d660 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71   calls to.** [sq
1d670 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
1d680 20 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c   | sqlite3_resul
1d690 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  t()],.** [sqlite
1d6a0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
1d6b0 65 78 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ext()],.** [sqli
1d6c0 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d  te3_user_data()]
1d6d0 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  ,.** [sqlite3_co
1d6e0 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28  ntext_db_handle(
1d6f0 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
1d700 67 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2c 20  get_auxdata()], 
1d710 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f  and/or [sqlite3_
1d720 73 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a  set_auxdata()]..
1d730 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
1d740 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t sqlite3_contex
1d750 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t sqlite3_contex
1d760 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  t;../*.** CAPI3R
1d770 45 46 3a 20 20 42 69 6e 64 69 6e 67 20 56 61 6c  EF:  Binding Val
1d780 75 65 73 20 54 6f 20 50 72 65 70 61 72 65 64 20  ues To Prepared 
1d790 53 74 61 74 65 6d 65 6e 74 73 20 7b 46 31 33 35  Statements {F135
1d7a0 30 30 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65  00}.**.** In the
1d7b0 20 53 51 4c 20 73 74 72 69 6e 67 73 20 69 6e 70   SQL strings inp
1d7c0 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70  ut to [sqlite3_p
1d7d0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
1d7e0 20 69 74 73 0a 2a 2a 20 76 61 72 69 61 6e 74 73   its.** variants
1d7f0 2c 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 62  , literals may b
1d800 65 20 72 65 70 6c 61 63 65 20 62 79 20 61 20 70  e replace by a p
1d810 61 72 61 6d 65 74 65 72 20 69 6e 20 6f 6e 65 0a  arameter in one.
1d820 2a 2a 20 6f 66 20 74 68 65 73 65 20 66 6f 72 6d  ** of these form
1d830 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
1d840 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e   <li>  ?.** <li>
1d850 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20    ?NNN.** <li>  
1d860 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56  :VVV.** <li>  @V
1d870 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56  VV.** <li>  $VVV
1d880 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
1d890 49 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  In the parameter
1d8a0 20 66 6f 72 6d 73 20 73 68 6f 77 6e 20 61 62 6f   forms shown abo
1d8b0 76 65 20 4e 4e 4e 20 69 73 20 61 6e 20 69 6e 74  ve NNN is an int
1d8c0 65 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a  eger literal,.**
1d8d0 20 56 56 56 20 61 6c 70 68 61 2d 6e 75 6d 65 72   VVV alpha-numer
1d8e0 69 63 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d  ic parameter nam
1d8f0 65 2e 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 73  e..** The values
1d900 20 6f 66 20 74 68 65 73 65 20 70 61 72 61 6d 65   of these parame
1d910 74 65 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65  ters (also calle
1d920 64 20 22 68 6f 73 74 20 70 61 72 61 6d 65 74 65  d "host paramete
1d930 72 20 6e 61 6d 65 73 22 0a 2a 2a 20 6f 72 20 22  r names".** or "
1d940 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 22 29  SQL parameters")
1d950 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 20 75  .** can be set u
1d960 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33  sing the sqlite3
1d970 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
1d980 65 73 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e  es defined here.
1d990 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
1d9a0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
1d9b0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
1d9c0 29 20 72 6f 75 74 69 6e 65 73 20 61 6c 77 61 79  ) routines alway
1d9d0 73 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65  s.** is a pointe
1d9e0 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  r to the [sqlite
1d9f0 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72  3_stmt] object r
1da00 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20  eturned from.** 
1da10 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1da20 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76 61  _v2()] or its va
1da30 72 69 61 6e 74 73 2e 20 54 68 65 20 73 65 63 6f  riants. The seco
1da40 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69  nd.** argument i
1da50 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74  s the index of t
1da60 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  he parameter to 
1da70 62 65 20 73 65 74 2e 20 54 68 65 0a 2a 2a 20 66  be set. The.** f
1da80 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 68  irst parameter h
1da90 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31  as an index of 1
1daa0 2e 20 20 57 68 65 6e 20 74 68 65 20 73 61 6d 65  .  When the same
1dab0 20 6e 61 6d 65 64 0a 2a 2a 20 70 61 72 61 6d 65   named.** parame
1dac0 74 65 72 20 69 73 20 75 73 65 64 20 6d 6f 72 65  ter is used more
1dad0 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f   than once, seco
1dae0 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e  nd and subsequen
1daf0 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65 73  t.** occurrences
1db00 20 68 61 76 65 20 74 68 65 20 73 61 6d 65 20 69   have the same i
1db10 6e 64 65 78 20 61 73 20 74 68 65 20 66 69 72 73  ndex as the firs
1db20 74 20 6f 63 63 75 72 72 65 6e 63 65 2e 20 0a 2a  t occurrence. .*
1db30 2a 20 54 68 65 20 69 6e 64 65 78 20 66 6f 72 20  * The index for 
1db40 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 73  named parameters
1db50 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75   can be looked u
1db60 70 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b  p using the.** [
1db70 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
1db80 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 20 41  ameter_name()] A
1db90 50 49 20 69 66 20 64 65 73 69 72 65 64 2e 20 20  PI if desired.  
1dba0 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72  The index.** for
1dbb0 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65   "?NNN" paramete
1dbc0 72 73 20 69 73 20 74 68 65 20 76 61 6c 75 65 20  rs is the value 
1dbd0 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 54 68 65 20 4e  of NNN..** The N
1dbe0 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74 20 62 65  NN value must be
1dbf0 20 62 65 74 77 65 65 6e 20 31 20 61 6e 64 20 74   between 1 and t
1dc00 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a  he compile-time.
1dc10 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 53 51 4c  ** parameter SQL
1dc20 49 54 45 5f 4d 41 58 5f 56 41 52 49 41 42 4c 45  ITE_MAX_VARIABLE
1dc30 5f 4e 55 4d 42 45 52 20 28 64 65 66 61 75 6c 74  _NUMBER (default
1dc40 20 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a   value: 999)..**
1dc50 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20 61 72  .** The third ar
1dc60 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 76 61  gument is the va
1dc70 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 6f 20 74  lue to bind to t
1dc80 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  he parameter..**
1dc90 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 0a 2a 2a 20  .** In those.** 
1dca0 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68 61  routines that ha
1dcb0 76 65 20 61 20 66 6f 75 72 74 68 20 61 72 67 75  ve a fourth argu
1dcc0 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 20  ment, its value 
1dcd0 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
1dce0 20 62 79 74 65 73 0a 2a 2a 20 69 6e 20 74 68 65   bytes.** in the
1dcf0 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f 20   parameter.  To 
1dd00 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76 61  be clear: the va
1dd10 6c 75 65 20 69 73 20 74 68 65 20 6e 75 6d 62 65  lue is the numbe
1dd20 72 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75  r of <u>bytes</u
1dd30 3e 0a 2a 2a 20 69 6e 20 74 68 65 20 76 61 6c 75  >.** in the valu
1dd40 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65  e, not the numbe
1dd50 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e  r of characters.
1dd60 20 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f 75 72   .** If the four
1dd70 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
1dd80 6e 65 67 61 74 69 76 65 2c 20 74 68 65 20 6c 65  negative, the le
1dd90 6e 67 74 68 20 6f 66 20 74 68 65 20 73 74 72 69  ngth of the stri
1dda0 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d  ng is.** the num
1ddb0 62 65 72 20 6f 66 20 62 79 74 65 73 20 75 70 20  ber of bytes up 
1ddc0 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72  to the first zer
1ddd0 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a  o terminator..**
1dde0 0a 2a 2a 20 54 68 65 20 66 69 66 74 68 20 61 72  .** The fifth ar
1ddf0 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
1de00 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 20 73  3_bind_blob(), s
1de10 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
1de20 28 29 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74  (), and.** sqlit
1de30 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29  e3_bind_text16()
1de40 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f 72   is a destructor
1de50 20 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73 65   used to dispose
1de60 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a   of the BLOB or.
1de70 2a 2a 20 73 74 72 69 6e 67 20 61 66 74 65 72 20  ** string after 
1de80 53 51 4c 69 74 65 20 68 61 73 20 66 69 6e 69 73  SQLite has finis
1de90 68 65 64 20 77 69 74 68 20 69 74 2e 20 49 66 20  hed with it. If 
1dea0 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65  the fifth argume
1deb0 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 65  nt is.** the spe
1dec0 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49  cial value [SQLI
1ded0 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e  TE_STATIC], then
1dee0 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20   SQLite assumes 
1def0 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f  that the.** info
1df00 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 74  rmation is in st
1df10 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20  atic, unmanaged 
1df20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e  space and does n
1df30 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72  ot need to be fr
1df40 65 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66  eed..** If the f
1df50 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68 61  ifth argument ha
1df60 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51 4c  s the value [SQL
1df70 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20  ITE_TRANSIENT], 
1df80 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d  then.** SQLite m
1df90 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 72 69  akes its own pri
1dfa0 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65  vate copy of the
1dfb0 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65 6c   data immediatel
1dfc0 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65  y, before.** the
1dfd0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
1dfe0 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
1dff0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  s..**.** The sql
1e000 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c  ite3_bind_zerobl
1e010 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e  ob() routine bin
1e020 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e  ds a BLOB of len
1e030 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73  gth N that.** is
1e040 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72   filled with zer
1e050 6f 73 2e 20 20 41 20 7a 65 72 6f 62 6c 6f 62 20  os.  A zeroblob 
1e060 75 73 65 73 20 61 20 66 69 78 65 64 20 61 6d 6f  uses a fixed amo
1e070 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a  unt of memory.**
1e080 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 65   (just an intege
1e090 72 20 74 6f 20 68 6f 6c 64 20 69 74 20 73 69 7a  r to hold it siz
1e0a0 65 29 20 77 68 69 6c 65 20 69 74 20 69 73 20 62  e) while it is b
1e0b0 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64 2e 0a  eing processed..
1e0c0 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65  ** Zeroblobs are
1e0d0 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 65 72   intended to ser
1e0e0 76 65 20 61 73 20 70 6c 61 63 65 68 6f 6c 64 65  ve as placeholde
1e0f0 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f  rs for BLOBs who
1e100 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73  se.** content is
1e110 20 6c 61 74 65 72 20 77 72 69 74 74 65 6e 20 75   later written u
1e120 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  sing .** [sqlite
1e130 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e  3_blob_open | in
1e140 63 72 65 6d 65 6e 74 20 42 4c 4f 42 20 49 2f 4f  crement BLOB I/O
1e150 5d 20 72 6f 75 74 69 6e 65 73 2e 20 41 20 6e 65  ] routines. A ne
1e160 67 61 74 69 76 65 0a 2a 2a 20 76 61 6c 75 65 20  gative.** value 
1e170 66 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62  for the zeroblob
1e180 20 72 65 73 75 6c 74 73 20 69 6e 20 61 20 7a 65   results in a ze
1e190 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a  ro-length BLOB..
1e1a0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
1e1b0 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
1e1c0 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  nes must be call
1e1d0 65 64 20 61 66 74 65 72 0a 2a 2a 20 5b 73 71 6c  ed after.** [sql
1e1e0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1e1f0 29 5d 20 28 61 6e 64 20 69 74 73 20 76 61 72 69  )] (and its vari
1e200 61 6e 74 73 29 20 6f 72 20 5b 73 71 6c 69 74 65  ants) or [sqlite
1e210 33 5f 72 65 73 65 74 28 29 5d 20 61 6e 64 0a 2a  3_reset()] and.*
1e220 2a 20 62 65 66 6f 72 65 20 5b 73 71 6c 69 74 65  * before [sqlite
1e230 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 42 69  3_step()]..** Bi
1e240 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f 74 20 63  ndings are not c
1e250 6c 65 61 72 65 64 20 62 79 20 74 68 65 20 5b 73  leared by the [s
1e260 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
1e270 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 55 6e 62 6f  routine..** Unbo
1e280 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73 20 61  und parameters a
1e290 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  re interpreted a
1e2a0 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68  s NULL..**.** Th
1e2b0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
1e2c0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  urn [SQLITE_OK] 
1e2d0 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 20 61 6e  on success or an
1e2e0 20 65 72 72 6f 72 20 63 6f 64 65 20 69 66 0a 2a   error code if.*
1e2f0 2a 20 61 6e 79 74 68 69 6e 67 20 67 6f 65 73 20  * anything goes 
1e300 77 72 6f 6e 67 2e 20 20 5b 53 51 4c 49 54 45 5f  wrong.  [SQLITE_
1e310 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e  RANGE] is return
1e320 65 64 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  ed if the parame
1e330 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20  ter.** index is 
1e340 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5b  out of range.  [
1e350 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73  SQLITE_NOMEM] is
1e360 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c   returned if mal
1e370 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20  loc() fails..** 
1e380 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20  [SQLITE_MISUSE] 
1e390 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e 65  might be returne
1e3a0 64 20 69 66 20 74 68 65 73 65 20 72 6f 75 74 69  d if these routi
1e3b0 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 6f  nes are called o
1e3c0 6e 20 61 0a 2a 2a 20 76 69 72 74 75 61 6c 20 6d  n a.** virtual m
1e3d0 61 63 68 69 6e 65 20 74 68 61 74 20 69 73 20 74  achine that is t
1e3e0 68 65 20 77 72 6f 6e 67 20 73 74 61 74 65 20 6f  he wrong state o
1e3f0 72 20 77 68 69 63 68 20 68 61 73 20 61 6c 72 65  r which has alre
1e400 61 64 79 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a  ady been finaliz
1e410 65 64 2e 0a 2a 2a 20 44 65 74 65 63 74 69 6f 6e  ed..** Detection
1e420 20 6f 66 20 6d 69 73 75 73 65 20 69 73 20 75 6e   of misuse is un
1e430 72 65 6c 69 61 62 6c 65 2e 20 20 41 70 70 6c 69  reliable.  Appli
1e440 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e  cations should n
1e450 6f 74 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20  ot depend.** on 
1e460 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 72 65  SQLITE_MISUSE re
1e470 74 75 72 6e 73 2e 20 20 53 51 4c 49 54 45 5f 4d  turns.  SQLITE_M
1e480 49 53 55 53 45 20 69 73 20 69 6e 74 65 6e 64 65  ISUSE is intende
1e490 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 61 0a  d to indicate a.
1e4a0 2a 2a 20 61 20 6c 6f 67 69 63 20 65 72 72 6f 72  ** a logic error
1e4b0 20 69 6e 20 74 68 65 20 61 70 70 6c 69 63 61 74   in the applicat
1e4c0 69 6f 6e 2e 20 20 46 75 74 75 72 65 20 76 65 72  ion.  Future ver
1e4d0 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
1e4e0 6d 69 67 68 74 0a 2a 2a 20 70 61 6e 69 63 20 72  might.** panic r
1e4f0 61 74 68 65 72 20 74 68 61 6e 20 72 65 74 75 72  ather than retur
1e500 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e  n SQLITE_MISUSE.
1e510 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
1e520 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
1e530 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29  arameter_count()
1e540 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
1e550 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
1e560 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  me()], and.** [s
1e570 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
1e580 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
1e590 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
1e5a0 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 30 36 7d  :.**.** {F13506}
1e5b0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72   The [sqlite3_pr
1e5c0 65 70 61 72 65 20 7c 20 53 51 4c 20 73 74 61 74  epare | SQL stat
1e5d0 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 5d 20  ement compiler] 
1e5e0 72 65 63 6f 67 6e 69 7a 65 73 0a 2a 2a 20 20 20  recognizes.**   
1e5f0 20 20 20 20 20 20 20 74 6f 6b 65 6e 73 20 6f 66         tokens of
1e600 20 74 68 65 20 66 6f 72 6d 73 20 22 3f 22 2c 20   the forms "?", 
1e610 22 3f 4e 4e 4e 22 2c 20 22 24 56 56 56 22 2c 20  "?NNN", "$VVV", 
1e620 22 3a 56 56 56 22 2c 20 61 6e 64 20 22 40 56 56  ":VVV", and "@VV
1e630 56 22 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  V".**          a
1e640 73 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73  s SQL parameters
1e650 2c 20 77 68 65 72 65 20 4e 4e 4e 20 69 73 20 61  , where NNN is a
1e660 6e 79 20 73 65 71 75 65 6e 63 65 20 6f 66 20 6f  ny sequence of o
1e670 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 20 20  ne or more.**   
1e680 20 20 20 20 20 20 20 64 69 67 69 74 73 20 61 6e         digits an
1e690 64 20 77 68 65 72 65 20 56 56 56 20 69 73 20 61  d where VVV is a
1e6a0 6e 79 20 73 65 71 75 65 6e 63 65 20 6f 66 20 6f  ny sequence of o
1e6b0 6e 65 20 6f 72 20 6d 6f 72 65 20 0a 2a 2a 20 20  ne or more .**  
1e6c0 20 20 20 20 20 20 20 20 61 6c 70 68 61 6e 75 6d          alphanum
1e6d0 65 72 69 63 20 63 68 61 72 61 63 74 65 72 73 20  eric characters 
1e6e0 6f 72 20 22 3a 3a 22 20 6f 70 74 69 6f 6e 61 6c  or "::" optional
1e6f0 6c 79 20 66 6f 6c 6c 6f 77 65 64 20 62 79 0a 2a  ly followed by.*
1e700 2a 20 20 20 20 20 20 20 20 20 20 61 20 73 74 72  *          a str
1e710 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 6e  ing containing n
1e720 6f 20 73 70 61 63 65 73 20 61 6e 64 20 63 6f 6e  o spaces and con
1e730 74 61 69 6e 65 64 20 77 69 74 68 69 6e 20 70 61  tained within pa
1e740 72 65 6e 74 68 65 73 65 73 2e 0a 2a 2a 0a 2a 2a  rentheses..**.**
1e750 20 7b 46 31 33 35 30 39 7d 20 54 68 65 20 69 6e   {F13509} The in
1e760 69 74 69 61 6c 20 76 61 6c 75 65 20 6f 66 20 61  itial value of a
1e770 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  n SQL parameter 
1e780 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b  is NULL..**.** {
1e790 46 31 33 35 31 32 7d 20 54 68 65 20 69 6e 64 65  F13512} The inde
1e7a0 78 20 6f 66 20 61 6e 20 22 3f 22 20 53 51 4c 20  x of an "?" SQL 
1e7b0 70 61 72 61 6d 65 74 65 72 20 69 73 20 6f 6e 65  parameter is one
1e7c0 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68 65   larger than the
1e7d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6c 61 72  .**          lar
1e7e0 67 65 73 74 20 69 6e 64 65 78 20 6f 66 20 53 51  gest index of SQ
1e7f0 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  L parameter to t
1e800 68 65 20 6c 65 66 74 2c 20 6f 72 20 31 20 69 66  he left, or 1 if
1e810 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
1e820 20 22 3f 22 20 69 73 20 74 68 65 20 6c 65 66 74   "?" is the left
1e830 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65 74  most SQL paramet
1e840 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 31  er..**.** {F1351
1e850 35 7d 20 54 68 65 20 69 6e 64 65 78 20 6f 66 20  5} The index of 
1e860 61 6e 20 22 3f 4e 4e 4e 22 20 53 51 4c 20 70 61  an "?NNN" SQL pa
1e870 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 69  rameter is the i
1e880 6e 74 65 67 65 72 20 4e 4e 4e 2e 0a 2a 2a 0a 2a  nteger NNN..**.*
1e890 2a 20 7b 46 31 33 35 31 38 7d 20 54 68 65 20 69  * {F13518} The i
1e8a0 6e 64 65 78 20 6f 66 20 61 6e 20 22 3a 56 56 56  ndex of an ":VVV
1e8b0 22 2c 20 22 24 56 56 56 22 2c 20 6f 72 20 22 40  ", "$VVV", or "@
1e8c0 56 56 56 22 20 53 51 4c 20 70 61 72 61 6d 65 74  VVV" SQL paramet
1e8d0 65 72 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20  er is.**        
1e8e0 20 20 74 68 65 20 73 61 6d 65 20 61 73 20 74 68    the same as th
1e8f0 65 20 69 6e 64 65 78 20 6f 66 20 6c 65 66 74 6d  e index of leftm
1e900 6f 73 74 20 6f 63 63 75 72 72 65 6e 63 65 73 20  ost occurrences 
1e910 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20  of the same.**  
1e920 20 20 20 20 20 20 20 20 70 61 72 61 6d 65 74 65          paramete
1e930 72 2c 20 6f 72 20 6f 6e 65 20 6d 6f 72 65 20 74  r, or one more t
1e940 68 61 6e 20 74 68 65 20 6c 61 72 67 65 73 74 20  han the largest 
1e950 69 6e 64 65 78 20 6f 76 65 72 20 61 6c 6c 0a 2a  index over all.*
1e960 2a 20 20 20 20 20 20 20 20 20 20 70 61 72 61 6d  *          param
1e970 65 74 65 72 73 20 74 6f 20 74 68 65 20 6c 65 66  eters to the lef
1e980 74 20 69 66 20 74 68 69 73 20 69 73 20 74 68 65  t if this is the
1e990 20 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63   first occurrenc
1e9a0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66  e.**          of
1e9b0 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 2c   this parameter,
1e9c0 20 6f 72 20 31 20 69 66 20 74 68 69 73 20 69 73   or 1 if this is
1e9d0 20 74 68 65 20 6c 65 66 74 6d 6f 73 74 20 70 61   the leftmost pa
1e9e0 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b  rameter..**.** {
1e9f0 46 31 33 35 32 31 7d 20 54 68 65 20 5b 73 71 6c  F13521} The [sql
1ea00 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 53  ite3_prepare | S
1ea10 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d  QL statement com
1ea20 70 69 6c 65 72 5d 20 66 61 69 6c 20 77 69 74 68  piler] fail with
1ea30 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 20  .**          an 
1ea40 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 65  [SQLITE_RANGE] e
1ea50 72 72 6f 72 20 69 66 20 74 68 65 20 69 6e 64 65  rror if the inde
1ea60 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61  x of an SQL para
1ea70 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  meter.**        
1ea80 20 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 31    is less than 1
1ea90 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e   or greater than
1eaa0 20 53 51 4c 49 54 45 5f 4d 41 58 5f 56 41 52 49   SQLITE_MAX_VARI
1eab0 41 42 4c 45 5f 4e 55 4d 42 45 52 2e 0a 2a 2a 0a  ABLE_NUMBER..**.
1eac0 2a 2a 20 7b 46 31 33 35 32 34 7d 20 43 61 6c 6c  ** {F13524} Call
1ead0 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69  s to [sqlite3_bi
1eae0 6e 64 5f 74 65 78 74 20 7c 20 73 71 6c 69 74 65  nd_text | sqlite
1eaf0 33 5f 62 69 6e 64 28 53 2c 4e 2c 56 2c 2e 2e 2e  3_bind(S,N,V,...
1eb00 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  )].**          a
1eb10 73 73 6f 63 69 61 74 65 20 74 68 65 20 76 61 6c  ssociate the val
1eb20 75 65 20 56 20 77 69 74 68 20 61 6c 6c 20 53 51  ue V with all SQ
1eb30 4c 20 70 61 72 61 6d 65 74 65 72 73 20 68 61 76  L parameters hav
1eb40 69 6e 67 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20  ing an.**       
1eb50 20 20 20 69 6e 64 65 78 20 6f 66 20 4e 20 69 6e     index of N in
1eb60 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
1eb70 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2a 0a  tatement] S..**.
1eb80 2a 2a 20 7b 46 31 33 35 32 37 7d 20 43 61 6c 6c  ** {F13527} Call
1eb90 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69  s to [sqlite3_bi
1eba0 6e 64 5f 74 65 78 74 20 7c 20 73 71 6c 69 74 65  nd_text | sqlite
1ebb0 33 5f 62 69 6e 64 28 53 2c 4e 2c 2e 2e 2e 29 5d  3_bind(S,N,...)]
1ebc0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 76 65  .**          ove
1ebd0 72 72 69 64 65 20 70 72 69 6f 72 20 63 61 6c 6c  rride prior call
1ebe0 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20  s with the same 
1ebf0 76 61 6c 75 65 73 20 6f 66 20 53 20 61 6e 64 20  values of S and 
1ec00 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 33 30  N..**.** {F13530
1ec10 7d 20 42 69 6e 64 69 6e 67 73 20 65 73 74 61 62  } Bindings estab
1ec20 6c 69 73 68 65 64 20 62 79 20 5b 73 71 6c 69 74  lished by [sqlit
1ec30 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 73  e3_bind_text | s
1ec40 71 6c 69 74 65 33 5f 62 69 6e 64 28 53 2c 2e 2e  qlite3_bind(S,..
1ec50 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  .)].**          
1ec60 70 65 72 73 69 73 74 20 61 63 72 6f 73 73 20 63  persist across c
1ec70 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
1ec80 5f 72 65 73 65 74 28 53 29 5d 2e 0a 2a 2a 0a 2a  _reset(S)]..**.*
1ec90 2a 20 7b 46 31 33 35 33 33 7d 20 49 6e 20 63 61  * {F13533} In ca
1eca0 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
1ecb0 62 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56 2c  bind_blob(S,N,V,
1ecc0 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  L,D)],.**       
1ecd0 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64     [sqlite3_bind
1ece0 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29  _text(S,N,V,L,D)
1ecf0 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  ], or.**        
1ed00 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f    [sqlite3_bind_
1ed10 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44  text16(S,N,V,L,D
1ed20 29 5d 20 53 51 4c 69 74 65 20 62 69 6e 64 73 20  )] SQLite binds 
1ed30 74 68 65 20 66 69 72 73 74 20 4c 0a 2a 2a 20 20  the first L.**  
1ed40 20 20 20 20 20 20 20 20 62 79 74 65 73 20 6f 66          bytes of
1ed50 20 74 68 65 20 62 6c 6f 62 20 6f 72 20 73 74 72   the blob or str
1ed60 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  ing pointed to b
1ed70 79 20 56 2c 20 77 68 65 6e 20 4c 0a 2a 2a 20 20  y V, when L.**  
1ed80 20 20 20 20 20 20 20 20 69 73 20 6e 6f 6e 2d 6e          is non-n
1ed90 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b  egative..**.** {
1eda0 46 31 33 35 33 36 7d 20 49 6e 20 63 61 6c 6c 73  F13536} In calls
1edb0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e   to [sqlite3_bin
1edc0 64 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44  d_text(S,N,V,L,D
1edd0 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  )] or.**        
1ede0 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f    [sqlite3_bind_
1edf0 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44  text16(S,N,V,L,D
1ee00 29 5d 20 53 51 4c 69 74 65 20 62 69 6e 64 73 20  )] SQLite binds 
1ee10 63 68 61 72 61 63 74 65 72 73 0a 2a 2a 20 20 20  characters.**   
1ee20 20 20 20 20 20 20 20 66 72 6f 6d 20 56 20 74 68         from V th
1ee30 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20  rough the first 
1ee40 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 20 77  zero character w
1ee50 68 65 6e 20 4c 20 69 73 20 6e 65 67 61 74 69 76  hen L is negativ
1ee60 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 33 39  e..**.** {F13539
1ee70 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73  } In calls to [s
1ee80 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
1ee90 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a  (S,N,V,L,D)],.**
1eea0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
1eeb0 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 53 2c 4e  e3_bind_text(S,N
1eec0 2c 56 2c 4c 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20  ,V,L,D)], or.** 
1eed0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
1eee0 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 53 2c  3_bind_text16(S,
1eef0 4e 2c 56 2c 4c 2c 44 29 5d 20 77 68 65 6e 20 44  N,V,L,D)] when D
1ef00 20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 0a   is the special.
1ef10 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e 73  **          cons
1ef20 74 61 6e 74 20 5b 53 51 4c 49 54 45 5f 53 54 41  tant [SQLITE_STA
1ef30 54 49 43 5d 2c 20 53 51 4c 69 74 65 20 61 73 73  TIC], SQLite ass
1ef40 75 6d 65 73 20 74 68 61 74 20 74 68 65 20 76 61  umes that the va
1ef50 6c 75 65 20 56 0a 2a 2a 20 20 20 20 20 20 20 20  lue V.**        
1ef60 20 20 69 73 20 68 65 6c 64 20 69 6e 20 73 74 61    is held in sta
1ef70 74 69 63 20 75 6e 6d 61 6e 61 67 65 64 20 73 70  tic unmanaged sp
1ef80 61 63 65 20 74 68 61 74 20 77 69 6c 6c 20 6e 6f  ace that will no
1ef90 74 20 63 68 61 6e 67 65 0a 2a 2a 20 20 20 20 20  t change.**     
1efa0 20 20 20 20 20 64 75 72 69 6e 67 20 74 68 65 20       during the 
1efb0 6c 69 66 65 74 69 6d 65 20 6f 66 20 74 68 65 20  lifetime of the 
1efc0 62 69 6e 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b  binding..**.** {
1efd0 46 31 33 35 34 32 7d 20 49 6e 20 63 61 6c 6c 73  F13542} In calls
1efe0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e   to [sqlite3_bin
1eff0 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 2c 44  d_blob(S,N,V,L,D
1f000 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  )],.**          
1f010 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65  [sqlite3_bind_te
1f020 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 20  xt(S,N,V,L,D)], 
1f030 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  or.**          [
1f040 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
1f050 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20  t16(S,N,V,L,D)] 
1f060 77 68 65 6e 20 44 20 69 73 20 74 68 65 20 73 70  when D is the sp
1f070 65 63 69 61 6c 0a 2a 2a 20 20 20 20 20 20 20 20  ecial.**        
1f080 20 20 63 6f 6e 73 74 61 6e 74 20 5b 53 51 4c 49    constant [SQLI
1f090 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74  TE_TRANSIENT], t
1f0a0 68 65 20 72 6f 75 74 69 6e 65 20 6d 61 6b 65 73  he routine makes
1f0b0 20 61 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   a .**          
1f0c0 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20  private copy of 
1f0d0 56 20 76 61 6c 75 65 20 62 65 66 6f 72 65 20 69  V value before i
1f0e0 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a  t returns..**.**
1f0f0 20 7b 46 31 33 35 34 35 7d 20 49 6e 20 63 61 6c   {F13545} In cal
1f100 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62  ls to [sqlite3_b
1f110 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c  ind_blob(S,N,V,L
1f120 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  ,D)],.**        
1f130 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f    [sqlite3_bind_
1f140 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d  text(S,N,V,L,D)]
1f150 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  , or.**         
1f160 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74   [sqlite3_bind_t
1f170 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29  ext16(S,N,V,L,D)
1f180 5d 20 77 68 65 6e 20 44 20 69 73 20 61 20 70 6f  ] when D is a po
1f190 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 20 20 20 20  inter to.**     
1f1a0 20 20 20 20 20 61 20 66 75 6e 63 74 69 6f 6e 2c       a function,
1f1b0 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20   SQLite invokes 
1f1c0 74 68 61 74 20 66 75 6e 63 74 69 6f 6e 20 74 6f  that function to
1f1d0 20 64 65 73 74 72 6f 79 20 74 68 65 0a 2a 2a 20   destroy the.** 
1f1e0 20 20 20 20 20 20 20 20 20 56 20 76 61 6c 75 65           V value
1f1f0 20 61 66 74 65 72 20 69 74 20 68 61 73 20 66 69   after it has fi
1f200 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 65  nished using the
1f210 20 56 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20   V value..**.** 
1f220 7b 46 31 33 35 34 38 7d 20 49 6e 20 63 61 6c 6c  {F13548} In call
1f230 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69  s to [sqlite3_bi
1f240 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 53 2c 4e 2c  nd_zeroblob(S,N,
1f250 56 2c 4c 29 5d 20 74 68 65 20 76 61 6c 75 65 20  V,L)] the value 
1f260 62 6f 75 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20  bound.**        
1f270 20 20 69 73 20 61 20 62 6c 6f 62 20 6f 66 20 4c    is a blob of L
1f280 20 62 79 74 65 73 2c 20 6f 72 20 61 20 7a 65 72   bytes, or a zer
1f290 6f 2d 6c 65 6e 67 74 68 20 62 6c 6f 62 20 69 66  o-length blob if
1f2a0 20 4c 20 69 73 20 6e 65 67 61 74 69 76 65 2e 0a   L is negative..
1f2b0 2a 2a 0a 2a 2a 20 7b 46 31 33 35 35 31 7d 20 49  **.** {F13551} I
1f2c0 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  n calls to [sqli
1f2d0 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 53  te3_bind_value(S
1f2e0 2c 4e 2c 56 29 5d 20 74 68 65 20 56 20 61 72 67  ,N,V)] the V arg
1f2f0 75 6d 65 6e 74 20 6d 61 79 0a 2a 2a 20 20 20 20  ument may.**    
1f300 20 20 20 20 20 20 62 65 20 65 69 74 68 65 72 20        be either 
1f310 61 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  a [protected sql
1f320 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
1f330 63 74 20 6f 72 20 61 6e 0a 2a 2a 20 20 20 20 20  ct or an.**     
1f340 20 20 20 20 20 5b 75 6e 70 72 6f 74 65 63 74 65       [unprotecte
1f350 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
1f360 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 69 6e 74 20   object..*/.int 
1f370 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
1f380 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  b(sqlite3_stmt*,
1f390 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64   int, const void
1f3a0 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a  *, int n, void(*
1f3b0 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73  )(void*));.int s
1f3c0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62  qlite3_bind_doub
1f3d0 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  le(sqlite3_stmt*
1f3e0 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a  , int, double);.
1f3f0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
1f400 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  _int(sqlite3_stm
1f410 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 69  t*, int, int);.i
1f420 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
1f430 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74  int64(sqlite3_st
1f440 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65  mt*, int, sqlite
1f450 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73 71  3_int64);.int sq
1f460 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28  lite3_bind_null(
1f470 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
1f480 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  nt);.int sqlite3
1f490 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74  _bind_text(sqlit
1f4a0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
1f4b0 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 20  onst char*, int 
1f4c0 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  n, void(*)(void*
1f4d0 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  ));.int sqlite3_
1f4e0 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69  bind_text16(sqli
1f4f0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
1f500 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
1f510 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
1f520 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
1f530 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 65  ind_value(sqlite
1f540 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
1f550 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  nst sqlite3_valu
1f560 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
1f570 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73  _bind_zeroblob(s
1f580 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
1f590 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a  t, int n);../*.*
1f5a0 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62  * CAPI3REF: Numb
1f5b0 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61 6d 65  er Of SQL Parame
1f5c0 74 65 72 73 20 7b 46 31 33 36 30 30 7d 0a 2a 2a  ters {F13600}.**
1f5d0 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
1f5e0 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
1f5f0 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20  find the number 
1f600 6f 66 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  of SQL parameter
1f610 73 0a 2a 2a 20 69 6e 20 61 20 70 72 65 70 61 72  s.** in a prepar
1f620 65 64 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 53  ed statement.  S
1f630 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 61 72  QL parameters ar
1f640 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a  e tokens of the.
1f650 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e  ** form "?", "?N
1f660 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41  NN", ":AAA", "$A
1f670 41 41 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74  AA", or "@AAA" t
1f680 68 61 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20  hat serve as.** 
1f690 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72  placeholders for
1f6a0 20 76 61 6c 75 65 73 20 74 68 61 74 20 61 72 65   values that are
1f6b0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
1f6c0 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20  lob | bound].** 
1f6d0 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  to the parameter
1f6e0 73 20 61 74 20 61 20 6c 61 74 65 72 20 74 69 6d  s at a later tim
1f6f0 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  e..**.** This ro
1f700 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72  utine actually r
1f710 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78  eturns the index
1f720 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20   of the largest 
1f730 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 46 6f  parameter..** Fo
1f740 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65  r all forms exce
1f750 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69  pt ?NNN, this wi
1f760 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f  ll correspond to
1f770 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
1f780 2a 20 75 6e 69 71 75 65 20 70 61 72 61 6d 65 74  * unique paramet
1f790 65 72 73 2e 20 20 49 66 20 70 61 72 61 6d 65 74  ers.  If paramet
1f7a0 65 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20  ers of the ?NNN 
1f7b0 61 72 65 20 75 73 65 64 2c 20 74 68 65 72 65 20  are used, there 
1f7c0 6d 61 79 0a 2a 2a 20 62 65 20 67 61 70 73 20 69  may.** be gaps i
1f7d0 6e 20 74 68 65 20 6c 69 73 74 2e 0a 2a 2a 0a 2a  n the list..**.*
1f7e0 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
1f7f0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
1f800 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a  qlite3_bind()],.
1f810 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
1f820 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
1f830 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
1f840 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
1f850 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a  er_index()]..**.
1f860 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
1f870 2a 0a 2a 2a 20 7b 46 31 33 36 30 31 7d 20 54 68  *.** {F13601} Th
1f880 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
1f890 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
1f8a0 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  S)] interface re
1f8b0 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20  turns.**        
1f8c0 20 20 74 68 65 20 6c 61 72 67 65 73 74 20 69 6e    the largest in
1f8d0 64 65 78 20 6f 66 20 61 6c 6c 20 53 51 4c 20 70  dex of all SQL p
1f8e0 61 72 61 6d 65 74 65 72 73 20 69 6e 20 74 68 65  arameters in the
1f8f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
1f900 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1f910 5d 20 53 2c 20 6f 72 20 30 20 69 66 20 53 0a 2a  ] S, or 0 if S.*
1f920 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e 74 61  *          conta
1f930 69 6e 73 20 6e 6f 20 53 51 4c 20 70 61 72 61 6d  ins no SQL param
1f940 65 74 65 72 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71  eters..*/.int sq
1f950 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
1f960 65 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74  eter_count(sqlit
1f970 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
1f980 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65  * CAPI3REF: Name
1f990 20 4f 66 20 41 20 48 6f 73 74 20 50 61 72 61 6d   Of A Host Param
1f9a0 65 74 65 72 20 7b 46 31 33 36 32 30 7d 0a 2a 2a  eter {F13620}.**
1f9b0 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
1f9c0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
1f9d0 65 72 20 74 6f 20 74 68 65 20 6e 61 6d 65 20 6f  er to the name o
1f9e0 66 20 74 68 65 20 6e 2d 74 68 0a 2a 2a 20 53 51  f the n-th.** SQ
1f9f0 4c 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 61  L parameter in a
1fa00 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1fa10 6d 65 6e 74 5d 2e 0a 2a 2a 20 53 51 4c 20 70 61  ment]..** SQL pa
1fa20 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20  rameters of the 
1fa30 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22  form "?NNN" or "
1fa40 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20  :AAA" or "@AAA" 
1fa50 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 68 61 76  or "$AAA".** hav
1fa60 65 20 61 20 6e 61 6d 65 20 77 68 69 63 68 20 69  e a name which i
1fa70 73 20 74 68 65 20 73 74 72 69 6e 67 20 22 3f 4e  s the string "?N
1fa80 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72  NN" or ":AAA" or
1fa90 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41   "@AAA" or "$AAA
1faa0 22 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c  ".** respectivel
1fab0 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77  y..** In other w
1fac0 6f 72 64 73 2c 20 74 68 65 20 69 6e 69 74 69 61  ords, the initia
1fad0 6c 20 22 3a 22 20 6f 72 20 22 24 22 20 6f 72 20  l ":" or "$" or 
1fae0 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73  "@" or "?".** is
1faf0 20 69 6e 63 6c 75 64 65 64 20 61 73 20 70 61 72   included as par
1fb00 74 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e 0a 2a  t of the name..*
1fb10 2a 20 50 61 72 61 6d 65 74 65 72 73 20 6f 66 20  * Parameters of 
1fb20 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 69 74  the form "?" wit
1fb30 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67  hout a following
1fb40 20 69 6e 74 65 67 65 72 20 68 61 76 65 20 6e 6f   integer have no
1fb50 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   name..**.** The
1fb60 20 66 69 72 73 74 20 68 6f 73 74 20 70 61 72 61   first host para
1fb70 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64  meter has an ind
1fb80 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a  ex of 1, not 0..
1fb90 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 76 61 6c  **.** If the val
1fba0 75 65 20 6e 20 69 73 20 6f 75 74 20 6f 66 20 72  ue n is out of r
1fbb0 61 6e 67 65 20 6f 72 20 69 66 20 74 68 65 20 6e  ange or if the n
1fbc0 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  -th parameter is
1fbd0 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68  .** nameless, th
1fbe0 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72  en NULL is retur
1fbf0 6e 65 64 2e 20 20 54 68 65 20 72 65 74 75 72 6e  ned.  The return
1fc00 65 64 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20  ed string is.** 
1fc10 61 6c 77 61 79 73 20 69 6e 20 74 68 65 20 55 54  always in the UT
1fc20 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 65  F-8 encoding eve
1fc30 6e 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20 70  n if the named p
1fc40 61 72 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20  arameter was.** 
1fc50 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 63 69  originally speci
1fc60 66 69 65 64 20 61 73 20 55 54 46 2d 31 36 20 69  fied as UTF-16 i
1fc70 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  n [sqlite3_prepa
1fc80 72 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  re16()] or.** [s
1fc90 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
1fca0 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65  _v2()]..**.** Se
1fcb0 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
1fcc0 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74  _bind_blob|sqlit
1fcd0 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b  e3_bind()],.** [
1fce0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
1fcf0 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c  ameter_count()],
1fd00 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
1fd10 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
1fd20 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  index()]..**.** 
1fd30 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
1fd40 2a 20 7b 46 31 33 36 32 31 7d 20 54 68 65 20 5b  * {F13621} The [
1fd50 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
1fd60 61 6d 65 74 65 72 5f 6e 61 6d 65 28 53 2c 4e 29  ameter_name(S,N)
1fd70 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
1fd80 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  rns.**          
1fd90 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e  a UTF-8 renderin
1fda0 67 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 6f 66  g of the name of
1fdb0 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74   the SQL paramet
1fdc0 65 72 20 69 6e 0a 2a 2a 20 20 20 20 20 20 20 20  er in.**        
1fdd0 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74    [prepared stat
1fde0 65 6d 65 6e 74 5d 20 53 20 68 61 76 69 6e 67 20  ement] S having 
1fdf0 69 6e 64 65 78 20 4e 2c 20 6f 72 0a 2a 2a 20 20  index N, or.**  
1fe00 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 69 66 20          NULL if 
1fe10 74 68 65 72 65 20 69 73 20 6e 6f 20 53 51 4c 20  there is no SQL 
1fe20 70 61 72 61 6d 65 74 65 72 20 77 69 74 68 20 69  parameter with i
1fe30 6e 64 65 78 20 4e 20 6f 72 20 69 66 20 74 68 65  ndex N or if the
1fe40 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 61 72  .**          par
1fe50 61 6d 65 74 65 72 20 77 69 74 68 20 69 6e 64 65  ameter with inde
1fe60 78 20 4e 20 69 73 20 61 6e 20 61 6e 6f 6e 79 6d  x N is an anonym
1fe70 6f 75 73 20 70 61 72 61 6d 65 74 65 72 20 22 3f  ous parameter "?
1fe80 22 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  "..*/.const char
1fe90 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   *sqlite3_bind_p
1fea0 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71  arameter_name(sq
1feb0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
1fec0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1fed0 45 46 3a 20 49 6e 64 65 78 20 4f 66 20 41 20 50  EF: Index Of A P
1fee0 61 72 61 6d 65 74 65 72 20 57 69 74 68 20 41 20  arameter With A 
1fef0 47 69 76 65 6e 20 4e 61 6d 65 20 7b 46 31 33 36  Given Name {F136
1ff00 34 30 7d 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e  40}.**.** Return
1ff10 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e   the index of an
1ff20 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67   SQL parameter g
1ff30 69 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20  iven its name.  
1ff40 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c  The.** index val
1ff50 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 73  ue returned is s
1ff60 75 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20  uitable for use 
1ff70 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a  as the second.**
1ff80 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
1ff90 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
1ffa0 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
1ffb0 2e 20 20 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20  .  A zero.** is 
1ffc0 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d  returned if no m
1ffd0 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65  atching paramete
1ffe0 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 54 68 65  r is found.  The
1fff0 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61   parameter.** na
20000 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e  me must be given
20010 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69   in UTF-8 even i
20020 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73  f the original s
20030 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20  tatement.** was 
20040 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54  prepared from UT
20050 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67 20  F-16 text using 
20060 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
20070 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  16_v2()]..**.** 
20080 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
20090 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c  e3_bind_blob|sql
200a0 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a  ite3_bind()],.**
200b0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
200c0 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29  arameter_count()
200d0 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
200e0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
200f0 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a  r_index()]..**.*
20100 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
20110 0a 2a 2a 20 7b 46 31 33 36 34 31 7d 20 54 68 65  .** {F13641} The
20120 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
20130 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 53  arameter_index(S
20140 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  ,N)] interface r
20150 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20  eturns.**       
20160 20 20 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20     the index of 
20170 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 6e  SQL parameter in
20180 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
20190 6d 65 6e 74 5d 0a 2a 2a 20 20 20 20 20 20 20 20  ment].**        
201a0 20 20 53 20 77 68 6f 73 65 20 6e 61 6d 65 20 6d    S whose name m
201b0 61 74 63 68 65 73 20 74 68 65 20 55 54 46 2d 38  atches the UTF-8
201c0 20 73 74 72 69 6e 67 20 4e 2c 20 6f 72 20 30 20   string N, or 0 
201d0 69 66 20 74 68 65 72 65 20 69 73 0a 2a 2a 20 20  if there is.**  
201e0 20 20 20 20 20 20 20 20 6e 6f 20 6d 61 74 63 68          no match
201f0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
20200 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
20210 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f 73 74  index(sqlite3_st
20220 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  mt*, const char 
20230 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *zName);../*.** 
20240 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20  CAPI3REF: Reset 
20250 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20  All Bindings On 
20260 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
20270 6d 65 6e 74 20 7b 46 31 33 36 36 30 7d 0a 2a 2a  ment {F13660}.**
20280 0a 2a 2a 20 43 6f 6e 74 72 61 72 79 20 74 6f 20  .** Contrary to 
20290 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66  the intuition of
202a0 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f   many, [sqlite3_
202b0 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f  reset()] does no
202c0 74 0a 2a 2a 20 72 65 73 65 74 20 74 68 65 20 5b  t.** reset the [
202d0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
202e0 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e  b | bindings] on
202f0 20 61 20 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64   a .** [prepared
20300 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 55 73   statement].  Us
20310 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74  e this routine t
20320 6f 0a 2a 2a 20 72 65 73 65 74 20 61 6c 6c 20 68  o.** reset all h
20330 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 74  ost parameters t
20340 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 49 4e  o NULL..**.** IN
20350 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
20360 7b 46 31 33 36 36 31 7d 20 54 68 65 20 5b 73 71  {F13661} The [sq
20370 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64  lite3_clear_bind
20380 69 6e 67 73 28 53 29 5d 20 69 6e 74 65 72 66 61  ings(S)] interfa
20390 63 65 20 72 65 73 65 74 73 20 61 6c 6c 0a 2a 2a  ce resets all.**
203a0 20 20 20 20 20 20 20 20 20 20 53 51 4c 20 70 61            SQL pa
203b0 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 73  rameter bindings
203c0 20 69 6e 20 5b 70 72 65 70 61 72 65 64 20 73 74   in [prepared st
203d0 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 20 20  atement] S.**   
203e0 20 20 20 20 20 20 20 62 61 63 6b 20 74 6f 20 4e         back to N
203f0 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ULL..*/.int sqli
20400 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e  te3_clear_bindin
20410 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  gs(sqlite3_stmt*
20420 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
20430 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f  EF: Number Of Co
20440 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 6c  lumns In A Resul
20450 74 20 53 65 74 20 7b 46 31 33 37 31 30 7d 0a 2a  t Set {F13710}.*
20460 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 74 68 65 20  *.** Return the 
20470 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
20480 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20  s in the result 
20490 73 65 74 20 72 65 74 75 72 6e 65 64 20 62 79 20  set returned by 
204a0 74 68 65 20 0a 2a 2a 20 5b 70 72 65 70 61 72 65  the .** [prepare
204b0 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 54 68  d statement]. Th
204c0 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  is routine retur
204d0 6e 73 20 30 0a 2a 2a 20 69 66 20 70 53 74 6d 74  ns 0.** if pStmt
204e0 20 69 73 20 61 6e 20 53 51 4c 20 73 74 61 74 65   is an SQL state
204f0 6d 65 6e 74 20 74 68 61 74 20 64 6f 65 73 20 6e  ment that does n
20500 6f 74 20 72 65 74 75 72 6e 20 64 61 74 61 20 28  ot return data (
20510 66 6f 72 20 0a 2a 2a 20 65 78 61 6d 70 6c 65 20  for .** example 
20520 61 6e 20 55 50 44 41 54 45 29 2e 0a 2a 2a 0a 2a  an UPDATE)..**.*
20530 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
20540 0a 2a 2a 20 7b 46 31 33 37 31 31 7d 20 54 68 65  .** {F13711} The
20550 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
20560 5f 63 6f 75 6e 74 28 53 29 5d 20 69 6e 74 65 72  _count(S)] inter
20570 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
20580 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 20 20   number of.**   
20590 20 20 20 20 20 20 20 63 6f 6c 75 6d 6e 73 20 69         columns i
205a0 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  n the result set
205b0 20 67 65 6e 65 72 61 74 65 64 20 62 79 20 74 68   generated by th
205c0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  e.**          [p
205d0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
205e0 74 5d 20 53 2c 20 6f 72 20 30 20 69 66 20 53 20  t] S, or 0 if S 
205f0 64 6f 65 73 20 6e 6f 74 20 67 65 6e 65 72 61 74  does not generat
20600 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20  e.**          a 
20610 72 65 73 75 6c 74 20 73 65 74 2e 0a 2a 2f 0a 69  result set..*/.i
20620 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
20630 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  n_count(sqlite3_
20640 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
20650 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
20660 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41  olumn Names In A
20670 20 52 65 73 75 6c 74 20 53 65 74 20 7b 46 31 33   Result Set {F13
20680 37 32 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  720}.**.** These
20690 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
206a0 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e   the name assign
206b0 65 64 20 74 6f 20 61 20 70 61 72 74 69 63 75 6c  ed to a particul
206c0 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20  ar column.** in 
206d0 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f  the result set o
206e0 66 20 61 20 53 45 4c 45 43 54 20 73 74 61 74 65  f a SELECT state
206f0 6d 65 6e 74 2e 20 20 54 68 65 20 73 71 6c 69 74  ment.  The sqlit
20700 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29  e3_column_name()
20710 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65  .** interface re
20720 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
20730 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  to a zero-termin
20740 61 74 65 64 20 55 54 46 38 20 73 74 72 69 6e 67  ated UTF8 string
20750 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  .** and sqlite3_
20760 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20  column_name16() 
20770 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
20780 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d  r to a zero-term
20790 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 31 36 20  inated.** UTF16 
207a0 73 74 72 69 6e 67 2e 20 20 54 68 65 20 66 69 72  string.  The fir
207b0 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  st parameter is 
207c0 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
207d0 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
207e0 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20   implements the 
207f0 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74  SELECT statement
20800 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
20810 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
20820 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20   column number. 
20830 20 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63   The left-most c
20840 6f 6c 75 6d 6e 20 69 73 0a 2a 2a 20 6e 75 6d 62  olumn is.** numb
20850 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  er 0..**.** The 
20860 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
20870 70 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64  pointer is valid
20880 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68   until either th
20890 65 20 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  e .** [prepared 
208a0 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65  statement] is de
208b0 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69  stroyed by [sqli
208c0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a  te3_finalize()].
208d0 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  ** or until the 
208e0 6e 65 78 74 20 63 61 6c 6c 20 73 71 6c 69 74 65  next call sqlite
208f0 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20  3_column_name() 
20900 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  or sqlite3_colum
20910 6e 5f 6e 61 6d 65 31 36 28 29 0a 2a 2a 20 6f 6e  n_name16().** on
20920 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e   the same column
20930 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 73 71 6c 69 74  ..**.** If sqlit
20940 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c  e3_malloc() fail
20950 73 20 64 75 72 69 6e 67 20 74 68 65 20 70 72 6f  s during the pro
20960 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68 65  cessing of eithe
20970 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f  r routine.** (fo
20980 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e 67  r example during
20990 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72   a conversion fr
209a0 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46 2d  om UTF-8 to UTF-
209b0 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55  16) then a.** NU
209c0 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65  LL pointer is re
209d0 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  turned..**.** Th
209e0 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65 73 75  e name of a resu
209f0 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65  lt column is the
20a00 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 22 41   value of the "A
20a10 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a  S" clause for.**
20a20 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66   that column, if
20a30 20 74 68 65 72 65 20 69 73 20 61 6e 20 41 53 20   there is an AS 
20a40 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68 65 72  clause.  If ther
20a50 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61 75 73  e is no AS claus
20a60 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e 61  e.** then the na
20a70 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  me of the column
20a80 20 69 73 20 75 6e 73 70 65 63 69 66 69 65 64 20   is unspecified 
20a90 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 20 66  and may change f
20aa0 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61  rom.** one relea
20ab0 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74 6f 20  se of SQLite to 
20ac0 74 68 65 20 6e 65 78 74 2e 0a 2a 2a 0a 2a 2a 20  the next..**.** 
20ad0 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
20ae0 2a 20 7b 46 31 33 37 32 31 7d 20 41 20 73 75 63  * {F13721} A suc
20af0 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69  cessful invocati
20b00 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  on of the [sqlit
20b10 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 53  e3_column_name(S
20b20 2c 4e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ,N)].**         
20b30 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
20b40 6e 73 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 20  ns the name.**  
20b50 20 20 20 20 20 20 20 20 6f 66 20 74 68 65 20 4e          of the N
20b60 74 68 20 63 6f 6c 75 6d 6e 20 28 77 68 65 72 65  th column (where
20b70 20 30 20 69 73 20 74 68 65 20 6c 65 66 74 2d 6d   0 is the left-m
20b80 6f 73 74 20 63 6f 6c 75 6d 6e 29 20 66 6f 72 20  ost column) for 
20b90 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
20ba0 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 5b 70  result set of [p
20bb0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
20bc0 74 5d 20 53 20 61 73 20 61 0a 2a 2a 20 20 20 20  t] S as a.**    
20bd0 20 20 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69        zero-termi
20be0 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69  nated UTF-8 stri
20bf0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 32  ng..**.** {F1372
20c00 33 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20  3} A successful 
20c10 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68  invocation of th
20c20 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
20c30 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 0a 2a  n_name16(S,N)].*
20c40 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 72  *          inter
20c50 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
20c60 20 6e 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20   name.**        
20c70 20 20 6f 66 20 74 68 65 20 4e 74 68 20 63 6f 6c    of the Nth col
20c80 75 6d 6e 20 28 77 68 65 72 65 20 30 20 69 73 20  umn (where 0 is 
20c90 74 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f  the left-most co
20ca0 6c 75 6d 6e 29 20 66 6f 72 20 74 68 65 0a 2a 2a  lumn) for the.**
20cb0 20 20 20 20 20 20 20 20 20 20 72 65 73 75 6c 74            result
20cc0 20 73 65 74 20 6f 66 20 5b 70 72 65 70 61 72 65   set of [prepare
20cd0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 61  d statement] S a
20ce0 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  s a.**          
20cf0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
20d00 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e  UTF-16 string in
20d10 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
20d20 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46   order..**.** {F
20d30 31 33 37 32 34 7d 20 54 68 65 20 5b 73 71 6c 69  13724} The [sqli
20d40 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
20d50 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
20d60 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 5d  column_name16()]
20d70 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74  .**          int
20d80 65 72 66 61 63 65 73 20 72 65 74 75 72 6e 20 61  erfaces return a
20d90 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66   NULL pointer if
20da0 20 74 68 65 79 20 61 72 65 20 75 6e 61 62 6c 65   they are unable
20db0 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   to.**          
20dc0 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20  allocate memory 
20dd0 74 6f 20 68 6f 6c 64 20 74 68 65 69 72 20 6e 6f  to hold their no
20de0 72 6d 61 6c 20 72 65 74 75 72 6e 20 73 74 72 69  rmal return stri
20df0 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37  ngs..**.** {F137
20e00 32 35 7d 20 49 66 20 74 68 65 20 4e 20 70 61 72  25} If the N par
20e10 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
20e20 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 53  e3_column_name(S
20e30 2c 4e 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20  ,N)] or.**      
20e40 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c      [sqlite3_col
20e50 75 6d 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d  umn_name16(S,N)]
20e60 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
20e70 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 20 20  , then the.**   
20e80 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65         interface
20e90 73 20 72 65 74 75 72 6e 20 61 20 4e 55 4c 4c 20  s return a NULL 
20ea0 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 0a 2a 2a 20  pointer..** .** 
20eb0 7b 46 31 33 37 32 36 7d 20 54 68 65 20 73 74 72  {F13726} The str
20ec0 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79  ings returned by
20ed0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
20ee0 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 61 6e 64 0a  _name(S,N)] and.
20ef0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
20f00 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
20f10 31 36 28 53 2c 4e 29 5d 20 61 72 65 20 76 61 6c  16(S,N)] are val
20f20 69 64 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78  id until the nex
20f30 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61  t.**          ca
20f40 6c 6c 20 74 6f 20 65 69 74 68 65 72 20 72 6f 75  ll to either rou
20f50 74 69 6e 65 20 77 69 74 68 20 74 68 65 20 73 61  tine with the sa
20f60 6d 65 20 53 20 61 6e 64 20 4e 20 70 61 72 61 6d  me S and N param
20f70 65 74 65 72 73 0a 2a 2a 20 20 20 20 20 20 20 20  eters.**        
20f80 20 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69    or until [sqli
20f90 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 5d  te3_finalize(S)]
20fa0 20 69 73 20 63 61 6c 6c 65 64 2e 0a 2a 2a 0a 2a   is called..**.*
20fb0 2a 20 7b 46 31 33 37 32 37 7d 20 57 68 65 6e 20  * {F13727} When 
20fc0 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  a result column 
20fd0 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74  of a [SELECT] st
20fe0 61 74 65 6d 65 6e 74 20 63 6f 6e 74 61 69 6e 73  atement contains
20ff0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 20  .**          an 
21000 41 53 20 63 6c 61 75 73 65 2c 20 74 68 65 20 6e  AS clause, the n
21010 61 6d 65 20 6f 66 20 74 68 61 74 20 63 6f 6c 75  ame of that colu
21020 6d 6e 20 69 73 20 74 68 65 20 69 64 65 6e 74 69  mn is the identi
21030 66 69 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  fier.**         
21040 20 74 6f 20 74 68 65 20 72 69 67 68 74 20 6f 66   to the right of
21050 20 74 68 65 20 41 53 20 6b 65 79 77 6f 72 64 2e   the AS keyword.
21060 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
21070 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
21080 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
21090 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74  *, int N);.const
210a0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
210b0 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c  olumn_name16(sql
210c0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
210d0 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  N);../*.** CAPI3
210e0 52 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 44  REF: Source Of D
210f0 61 74 61 20 49 6e 20 41 20 51 75 65 72 79 20 52  ata In A Query R
21100 65 73 75 6c 74 20 7b 46 31 33 37 34 30 7d 0a 2a  esult {F13740}.*
21110 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
21120 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65  nes provide a me
21130 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65  ans to determine
21140 20 77 68 61 74 20 63 6f 6c 75 6d 6e 20 6f 66 20   what column of 
21150 77 68 61 74 0a 2a 2a 20 74 61 62 6c 65 20 69 6e  what.** table in
21160 20 77 68 69 63 68 20 64 61 74 61 62 61 73 65 20   which database 
21170 61 20 72 65 73 75 6c 74 20 6f 66 20 61 20 53 45  a result of a SE
21180 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 20 63  LECT statement c
21190 6f 6d 65 73 20 66 72 6f 6d 2e 0a 2a 2a 20 54 68  omes from..** Th
211a0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61  e name of the da
211b0 74 61 62 61 73 65 20 6f 72 20 74 61 62 6c 65 20  tabase or table 
211c0 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65  or column can be
211d0 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20   returned as.** 
211e0 65 69 74 68 65 72 20 61 20 55 54 46 38 20 6f 72  either a UTF8 or
211f0 20 55 54 46 31 36 20 73 74 72 69 6e 67 2e 20 20   UTF16 string.  
21200 54 68 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72  The _database_ r
21210 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a  outines return.*
21220 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e  * the database n
21230 61 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f  ame, the _table_
21240 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
21250 20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c   the table name,
21260 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67   and.** the orig
21270 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74  in_ routines ret
21280 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e  urn the column n
21290 61 6d 65 2e 0a 2a 2a 20 54 68 65 20 72 65 74 75  ame..** The retu
212a0 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 76  rned string is v
212b0 61 6c 69 64 20 75 6e 74 69 6c 0a 2a 2a 20 74 68  alid until.** th
212c0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
212d0 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f  ement] is destro
212e0 79 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  yed using.** [sq
212f0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
21300 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73  ] or until the s
21310 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  ame information 
21320 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a 2a 20  is requested.** 
21330 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66 66 65  again in a diffe
21340 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a  rent encoding..*
21350 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 73 20 72  *.** The names r
21360 65 74 75 72 6e 65 64 20 61 72 65 20 74 68 65 20  eturned are the 
21370 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61  original un-alia
21380 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 65  sed names of the
21390 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 74 61  .** database, ta
213a0 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e  ble, and column.
213b0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
213c0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
213d0 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 6c 6c 73   following calls
213e0 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20   is a [prepared 
213f0 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 54  statement]..** T
21400 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72  hese functions r
21410 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f  eturn informatio
21420 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74 68 20  n about the Nth 
21430 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20  column returned 
21440 62 79 20 0a 2a 2a 20 74 68 65 20 73 74 61 74 65  by .** the state
21450 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 69 73  ment, where N is
21460 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63   the second func
21470 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  tion argument..*
21480 2a 0a 2a 2a 20 49 66 20 74 68 65 20 4e 74 68 20  *.** If the Nth 
21490 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20  column returned 
214a0 62 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  by the statement
214b0 20 69 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f   is an expressio
214c0 6e 0a 2a 2a 20 6f 72 20 73 75 62 71 75 65 72 79  n.** or subquery
214d0 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 6f   and is not a co
214e0 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e  lumn value, then
214f0 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 75   all of these fu
21500 6e 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 74 75 72  nctions.** retur
21510 6e 20 4e 55 4c 4c 2e 20 20 54 68 65 73 65 20 72  n NULL.  These r
21520 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 61 6c 73  outine might als
21530 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66  o return NULL if
21540 20 61 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c   a memory.** all
21550 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63  ocation error oc
21560 63 75 72 73 2e 20 20 4f 74 68 65 72 77 69 73 65  curs.  Otherwise
21570 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20 74 68  , they return th
21580 65 20 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20 74 68  e .** name of th
21590 65 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62  e attached datab
215a0 61 73 65 2c 20 74 61 62 6c 65 20 61 6e 64 20 63  ase, table and c
215b0 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79  olumn that query
215c0 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d   result.** colum
215d0 6e 20 77 61 73 20 65 78 74 72 61 63 74 65 64 20  n was extracted 
215e0 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 77  from..**.** As w
215f0 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51  ith all other SQ
21600 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65  Lite APIs, those
21610 20 70 6f 73 74 66 69 78 65 64 20 77 69 74 68 20   postfixed with 
21620 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55  "16" return.** U
21630 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 74  TF-16 encoded st
21640 72 69 6e 67 73 2c 20 74 68 65 20 6f 74 68 65 72  rings, the other
21650 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72   functions retur
21660 6e 20 55 54 46 2d 38 2e 20 7b 45 4e 44 7d 0a 2a  n UTF-8. {END}.*
21670 2a 0a 2a 2a 20 54 68 65 73 65 20 41 50 49 73 20  *.** These APIs 
21680 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62  are only availab
21690 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 72  le if the librar
216a0 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77  y was compiled w
216b0 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49  ith the .** SQLI
216c0 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e  TE_ENABLE_COLUMN
216d0 5f 4d 45 54 41 44 41 54 41 20 70 72 65 70 72 6f  _METADATA prepro
216e0 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 20 64 65  cessor symbol de
216f0 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 55 31  fined..**.** {U1
21700 33 37 35 31 7d 0a 2a 2a 20 49 66 20 74 77 6f 20  3751}.** If two 
21710 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20  or more threads 
21720 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  call one or more
21730 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
21740 65 73 20 61 67 61 69 6e 73 74 20 74 68 65 20 73  es against the s
21750 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20  ame.** prepared 
21760 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f  statement and co
21770 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d 65  lumn at the same
21780 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72   time then the r
21790 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e  esults are.** un
217a0 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  defined..**.** I
217b0 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
217c0 20 7b 46 31 33 37 34 31 7d 20 54 68 65 20 5b 73   {F13741} The [s
217d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61  qlite3_column_da
217e0 74 61 62 61 73 65 5f 6e 61 6d 65 28 53 2c 4e 29  tabase_name(S,N)
217f0 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
21800 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20  rns either.**   
21810 20 20 20 20 20 20 20 74 68 65 20 55 54 46 2d 38         the UTF-8
21820 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
21830 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74   name of the dat
21840 61 62 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68  abase from which
21850 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 20 20 20   the .**        
21860 20 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c    Nth result col
21870 75 6d 6e 20 6f 66 20 5b 70 72 65 70 61 72 65 64  umn of [prepared
21880 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 0a 2a   statement] S .*
21890 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 65 78  *          is ex
218a0 74 72 61 63 74 65 64 2c 20 6f 72 20 4e 55 4c 4c  tracted, or NULL
218b0 20 69 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75   if the Nth colu
218c0 6d 6e 20 6f 66 20 53 20 69 73 20 61 0a 2a 2a 20  mn of S is a.** 
218d0 20 20 20 20 20 20 20 20 20 67 65 6e 65 72 61 6c           general
218e0 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 69   expression or i
218f0 66 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f  f unable to allo
21900 63 61 74 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20  cate memory.**  
21910 20 20 20 20 20 20 20 20 74 6f 20 73 74 6f 72 65          to store
21920 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 20 20 20   the name..**   
21930 20 20 20 20 20 20 20 0a 2a 2a 20 7b 46 31 33 37         .** {F137
21940 34 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  42} The [sqlite3
21950 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65  _column_database
21960 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20 69 6e  _name16(S,N)] in
21970 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
21980 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20  either.**       
21990 20 20 20 74 68 65 20 55 54 46 2d 31 36 20 6e 61     the UTF-16 na
219a0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 0a  tive byte order.
219b0 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f  **          zero
219c0 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65  -terminated name
219d0 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
219e0 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20   from which the 
219f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68  .**          Nth
21a00 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f   result column o
21a10 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  f [prepared stat
21a20 65 6d 65 6e 74 5d 20 53 20 0a 2a 2a 20 20 20 20  ement] S .**    
21a30 20 20 20 20 20 20 69 73 20 65 78 74 72 61 63 74        is extract
21a40 65 64 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74  ed, or NULL if t
21a50 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66  he Nth column of
21a60 20 53 20 69 73 20 61 0a 2a 2a 20 20 20 20 20 20   S is a.**      
21a70 20 20 20 20 67 65 6e 65 72 61 6c 20 65 78 70 72      general expr
21a80 65 73 73 69 6f 6e 20 6f 72 20 69 66 20 75 6e 61  ession or if una
21a90 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ble to allocate 
21aa0 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20 20 20 20 20  memory.**       
21ab0 20 20 20 74 6f 20 73 74 6f 72 65 20 74 68 65 20     to store the 
21ac0 6e 61 6d 65 2e 0a 2a 2a 20 20 20 20 20 20 20 20  name..**        
21ad0 20 20 0a 2a 2a 20 7b 46 31 33 37 34 33 7d 20 54    .** {F13743} T
21ae0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
21af0 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 53 2c  mn_table_name(S,
21b00 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  N)] interface re
21b10 74 75 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20  turns either.** 
21b20 20 20 20 20 20 20 20 20 20 74 68 65 20 55 54 46           the UTF
21b30 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  -8 zero-terminat
21b40 65 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 74  ed name of the t
21b50 61 62 6c 65 20 66 72 6f 6d 20 77 68 69 63 68 20  able from which 
21b60 74 68 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  the .**         
21b70 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75   Nth result colu
21b80 6d 6e 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20  mn of [prepared 
21b90 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 0a 2a 2a  statement] S .**
21ba0 20 20 20 20 20 20 20 20 20 20 69 73 20 65 78 74            is ext
21bb0 72 61 63 74 65 64 2c 20 6f 72 20 4e 55 4c 4c 20  racted, or NULL 
21bc0 69 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  if the Nth colum
21bd0 6e 20 6f 66 20 53 20 69 73 20 61 0a 2a 2a 20 20  n of S is a.**  
21be0 20 20 20 20 20 20 20 20 67 65 6e 65 72 61 6c 20          general 
21bf0 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 69 66  expression or if
21c00 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
21c10 61 74 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20  ate memory.**   
21c20 20 20 20 20 20 20 20 74 6f 20 73 74 6f 72 65 20         to store 
21c30 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 20 20 20 20  the name..**    
21c40 20 20 20 20 20 20 0a 2a 2a 20 7b 46 31 33 37 34        .** {F1374
21c50 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  4} The [sqlite3_
21c60 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d  column_table_nam
21c70 65 31 36 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66  e16(S,N)] interf
21c80 61 63 65 20 72 65 74 75 72 6e 73 20 65 69 74 68  ace returns eith
21c90 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  er.**          t
21ca0 68 65 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65  he UTF-16 native
21cb0 20 62 79 74 65 20 6f 72 64 65 72 0a 2a 2a 20 20   byte order.**  
21cc0 20 20 20 20 20 20 20 20 7a 65 72 6f 2d 74 65 72          zero-ter
21cd0 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66 20  minated name of 
21ce0 74 68 65 20 74 61 62 6c 65 20 66 72 6f 6d 20 77  the table from w
21cf0 68 69 63 68 20 74 68 65 20 0a 2a 2a 20 20 20 20  hich the .**    
21d00 20 20 20 20 20 20 4e 74 68 20 72 65 73 75 6c 74        Nth result
21d10 20 63 6f 6c 75 6d 6e 20 6f 66 20 5b 70 72 65 70   column of [prep
21d20 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
21d30 53 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  S .**          i
21d40 73 20 65 78 74 72 61 63 74 65 64 2c 20 6f 72 20  s extracted, or 
21d50 4e 55 4c 4c 20 69 66 20 74 68 65 20 4e 74 68 20  NULL if the Nth 
21d60 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20 61  column of S is a
21d70 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 67 65 6e  .**          gen
21d80 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e 20  eral expression 
21d90 6f 72 20 69 66 20 75 6e 61 62 6c 65 20 74 6f 20  or if unable to 
21da0 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 0a  allocate memory.
21db0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 73  **          to s
21dc0 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a  tore the name..*
21dd0 2a 20 20 20 20 20 20 20 20 20 20 0a 2a 2a 20 7b  *          .** {
21de0 46 31 33 37 34 35 7d 20 54 68 65 20 5b 73 71 6c  F13745} The [sql
21df0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67  ite3_column_orig
21e00 69 6e 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 69 6e  in_name(S,N)] in
21e10 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
21e20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20  either.**       
21e30 20 20 20 74 68 65 20 55 54 46 2d 38 20 7a 65 72     the UTF-8 zer
21e40 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d  o-terminated nam
21e50 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63  e of the table c
21e60 6f 6c 75 6d 6e 20 66 72 6f 6d 20 77 68 69 63 68  olumn from which
21e70 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 20 20 20   the .**        
21e80 20 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c    Nth result col
21e90 75 6d 6e 20 6f 66 20 5b 70 72 65 70 61 72 65 64  umn of [prepared
21ea0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 0a 2a   statement] S .*
21eb0 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 65 78  *          is ex
21ec0 74 72 61 63 74 65 64 2c 20 6f 72 20 4e 55 4c 4c  tracted, or NULL
21ed0 20 69 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75   if the Nth colu
21ee0 6d 6e 20 6f 66 20 53 20 69 73 20 61 0a 2a 2a 20  mn of S is a.** 
21ef0 20 20 20 20 20 20 20 20 20 67 65 6e 65 72 61 6c           general
21f00 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 69   expression or i
21f10 66 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f  f unable to allo
21f20 63 61 74 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20  cate memory.**  
21f30 20 20 20 20 20 20 20 20 74 6f 20 73 74 6f 72 65          to store
21f40 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 20 20 20   the name..**   
21f50 20 20 20 20 20 20 20 0a 2a 2a 20 7b 46 31 33 37         .** {F137
21f60 34 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  46} The [sqlite3
21f70 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e  _column_origin_n
21f80 61 6d 65 31 36 28 53 2c 4e 29 5d 20 69 6e 74 65  ame16(S,N)] inte
21f90 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 65 69  rface returns ei
21fa0 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  ther.**         
21fb0 20 74 68 65 20 55 54 46 2d 31 36 20 6e 61 74 69   the UTF-16 nati
21fc0 76 65 20 62 79 74 65 20 6f 72 64 65 72 0a 2a 2a  ve byte order.**
21fd0 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 2d 74            zero-t
21fe0 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f  erminated name o
21ff0 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75  f the table colu
22000 6d 6e 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68  mn from which th
22010 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e  e .**          N
22020 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  th result column
22030 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74   of [prepared st
22040 61 74 65 6d 65 6e 74 5d 20 53 20 0a 2a 2a 20 20  atement] S .**  
22050 20 20 20 20 20 20 20 20 69 73 20 65 78 74 72 61          is extra
22060 63 74 65 64 2c 20 6f 72 20 4e 55 4c 4c 20 69 66  cted, or NULL if
22070 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
22080 6f 66 20 53 20 69 73 20 61 0a 2a 2a 20 20 20 20  of S is a.**    
22090 20 20 20 20 20 20 67 65 6e 65 72 61 6c 20 65 78        general ex
220a0 70 72 65 73 73 69 6f 6e 20 6f 72 20 69 66 20 75  pression or if u
220b0 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74  nable to allocat
220c0 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20 20 20  e memory.**     
220d0 20 20 20 20 20 74 6f 20 73 74 6f 72 65 20 74 68       to store th
220e0 65 20 6e 61 6d 65 2e 0a 2a 2a 20 20 20 20 20 20  e name..**      
220f0 20 20 20 20 0a 2a 2a 20 7b 46 31 33 37 34 38 7d      .** {F13748}
22100 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   The return valu
22110 65 73 20 66 72 6f 6d 0a 2a 2a 20 20 20 20 20 20  es from.**      
22120 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c      [sqlite3_col
22130 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d  umn_database_nam
22140 65 7c 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74  e|column metadat
22150 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a  a interfaces].**
22160 20 20 20 20 20 20 20 20 20 20 61 72 65 20 76 61            are va
22170 6c 69 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  lid.**          
22180 66 6f 72 20 74 68 65 20 6c 69 66 65 74 69 6d 65  for the lifetime
22190 20 6f 66 20 74 68 65 20 5b 70 72 65 70 61 72 65   of the [prepare
221a0 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
221b0 20 20 20 20 20 20 20 20 20 6f 72 20 75 6e 74 69           or unti
221c0 6c 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 69  l the encoding i
221d0 73 20 63 68 61 6e 67 65 64 20 62 79 20 61 6e 6f  s changed by ano
221e0 74 68 65 72 20 6d 65 74 61 64 61 74 61 0a 2a 2a  ther metadata.**
221f0 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 66            interf
22200 61 63 65 20 63 61 6c 6c 20 66 6f 72 20 74 68 65  ace call for the
22210 20 73 61 6d 65 20 70 72 65 70 61 72 65 64 20 73   same prepared s
22220 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c  tatement and col
22230 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49 54  umn..**.** LIMIT
22240 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 55  ATIONS:.**.** {U
22250 31 33 37 35 31 7d 20 49 66 20 74 77 6f 20 6f 72  13751} If two or
22260 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61   more threads ca
22270 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a  ll one or more.*
22280 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
22290 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62  te3_column_datab
222a0 61 73 65 5f 6e 61 6d 65 7c 63 6f 6c 75 6d 6e 20  ase_name|column 
222b0 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72 66 61  metadata interfa
222c0 63 65 73 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ces].**         
222d0 20 74 68 65 20 73 61 6d 65 20 5b 70 72 65 70 61   the same [prepa
222e0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61  red statement] a
222f0 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  nd result column
22300 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 74 20  .**          at 
22310 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68  the same time th
22320 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  en the results a
22330 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f  re undefined..*/
22340 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
22350 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61  ite3_column_data
22360 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65  base_name(sqlite
22370 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
22380 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
22390 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73  3_column_databas
223a0 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  e_name16(sqlite3
223b0 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
223c0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
223d0 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61  _column_table_na
223e0 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
223f0 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  ,int);.const voi
22400 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
22410 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73  n_table_name16(s
22420 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
22430 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  );.const char *s
22440 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72  qlite3_column_or
22450 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65  igin_name(sqlite
22460 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
22470 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
22480 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f  3_column_origin_
22490 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73  name16(sqlite3_s
224a0 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  tmt*,int);../*.*
224b0 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c  * CAPI3REF: Decl
224c0 61 72 65 64 20 44 61 74 61 74 79 70 65 20 4f 66  ared Datatype Of
224d0 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 20   A Query Result 
224e0 7b 46 31 33 37 36 30 7d 0a 2a 2a 0a 2a 2a 20 54  {F13760}.**.** T
224f0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
22500 65 72 20 69 73 20 61 20 5b 70 72 65 70 61 72 65  er is a [prepare
22510 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 0a 2a  d statement]. .*
22520 2a 20 49 66 20 74 68 69 73 20 73 74 61 74 65 6d  * If this statem
22530 65 6e 74 20 69 73 20 61 20 53 45 4c 45 43 54 20  ent is a SELECT 
22540 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 68  statement and th
22550 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20  e Nth column of 
22560 74 68 65 20 0a 2a 2a 20 72 65 74 75 72 6e 65 64  the .** returned
22570 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74   result set of t
22580 68 61 74 20 53 45 4c 45 43 54 20 69 73 20 61 20  hat SELECT is a 
22590 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f  table column (no
225a0 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69  t an.** expressi
225b0 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 29 20  on or subquery) 
225c0 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61 72 65  then the declare
225d0 64 20 74 79 70 65 20 6f 66 20 74 68 65 20 74 61  d type of the ta
225e0 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73  ble.** column is
225f0 20 72 65 74 75 72 6e 65 64 2e 20 20 49 66 20 74   returned.  If t
22600 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66  he Nth column of
22610 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
22620 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73  is an.** express
22630 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 2c  ion or subquery,
22640 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69   then a NULL poi
22650 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64  nter is returned
22660 2e 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 6e 65  ..** The returne
22670 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c 77 61  d string is alwa
22680 79 73 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64  ys UTF-8 encoded
22690 2e 20 20 7b 45 4e 44 7d 20 0a 2a 2a 20 46 6f 72  .  {END} .** For
226a0 20 65 78 61 6d 70 6c 65 2c 20 69 6e 20 74 68 65   example, in the
226b0 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61   database schema
226c0 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54  :.**.** CREATE T
226d0 41 42 4c 45 20 74 31 28 63 31 20 56 41 52 49 41  ABLE t1(c1 VARIA
226e0 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 41 6e 64 20 74  NT);.**.** And t
226f0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61  he following sta
22700 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 64 3a  tement compiled:
22710 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31  .**.** SELECT c1
22720 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31   + 1, c1 FROM t1
22730 3b 0a 2a 2a 0a 2a 2a 20 54 68 65 6e 20 74 68 69  ;.**.** Then thi
22740 73 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20  s routine would 
22750 72 65 74 75 72 6e 20 74 68 65 20 73 74 72 69 6e  return the strin
22760 67 20 22 56 41 52 49 41 4e 54 22 20 66 6f 72 20  g "VARIANT" for 
22770 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 72 65  the second.** re
22780 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d  sult column (i==
22790 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70  1), and a NULL p
227a0 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65 20 66  ointer for the f
227b0 69 72 73 74 20 72 65 73 75 6c 74 20 63 6f 6c 75  irst result colu
227c0 6d 6e 0a 2a 2a 20 28 69 3d 3d 30 29 2e 0a 2a 2a  mn.** (i==0)..**
227d0 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20  .** SQLite uses 
227e0 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65  dynamic run-time
227f0 20 74 79 70 69 6e 67 2e 20 20 53 6f 20 6a 75 73   typing.  So jus
22800 74 20 62 65 63 61 75 73 65 20 61 20 63 6f 6c 75  t because a colu
22810 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72 65  mn.** is declare
22820 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70  d to contain a p
22830 61 72 74 69 63 75 6c 61 72 20 74 79 70 65 20 64  articular type d
22840 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61  oes not mean tha
22850 74 20 74 68 65 0a 2a 2a 20 64 61 74 61 20 73 74  t the.** data st
22860 6f 72 65 64 20 69 6e 20 74 68 61 74 20 63 6f 6c  ored in that col
22870 75 6d 6e 20 69 73 20 6f 66 20 74 68 65 20 64 65  umn is of the de
22880 63 6c 61 72 65 64 20 74 79 70 65 2e 20 20 53 51  clared type.  SQ
22890 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e  Lite is.** stron
228a0 67 6c 79 20 74 79 70 65 64 2c 20 62 75 74 20 74  gly typed, but t
228b0 68 65 20 74 79 70 69 6e 67 20 69 73 20 64 79 6e  he typing is dyn
228c0 61 6d 69 63 20 6e 6f 74 20 73 74 61 74 69 63 2e  amic not static.
228d0 20 20 54 79 70 65 0a 2a 2a 20 69 73 20 61 73 73    Type.** is ass
228e0 6f 63 69 61 74 65 64 20 77 69 74 68 20 69 6e 64  ociated with ind
228f0 69 76 69 64 75 61 6c 20 76 61 6c 75 65 73 2c 20  ividual values, 
22900 6e 6f 74 20 77 69 74 68 20 74 68 65 20 63 6f 6e  not with the con
22910 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20  tainers.** used 
22920 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20 76 61  to hold those va
22930 6c 75 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  lues..**.** INVA
22940 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  RIANTS:.**.** {F
22950 31 33 37 36 31 7d 20 20 41 20 73 75 63 63 65 73  13761}  A succes
22960 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71  sful call to [sq
22970 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63  lite3_column_dec
22980 6c 74 79 70 65 28 53 2c 4e 29 5d 0a 2a 2a 20 20  ltype(S,N)].**  
22990 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 73           returns
229a0 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
229b0 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20  ed UTF-8 string 
229c0 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 0a 2a  containing the.*
229d0 2a 20 20 20 20 20 20 20 20 20 20 20 74 68 65 20  *           the 
229e0 64 65 63 6c 61 72 65 64 20 64 61 74 61 74 79 70  declared datatyp
229f0 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63  e of the table c
22a00 6f 6c 75 6d 6e 20 74 68 61 74 20 61 70 70 65 61  olumn that appea
22a10 72 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  rs.**           
22a20 61 73 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  as the Nth colum
22a30 6e 20 28 6e 75 6d 62 65 72 65 64 20 66 72 6f 6d  n (numbered from
22a40 20 30 29 20 6f 66 20 74 68 65 20 72 65 73 75 6c   0) of the resul
22a50 74 20 73 65 74 20 74 6f 20 74 68 65 0a 2a 2a 20  t set to the.** 
22a60 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61            [prepa
22a70 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
22a80 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 36 32 7d  ..**.** {F13762}
22a90 20 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63    A successful c
22aa0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
22ab0 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31  column_decltype1
22ac0 36 28 53 2c 4e 29 5d 0a 2a 2a 20 20 20 20 20 20  6(S,N)].**      
22ad0 20 20 20 20 20 72 65 74 75 72 6e 73 20 61 20 7a       returns a z
22ae0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
22af0 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74  TF-16 native byt
22b00 65 20 6f 72 64 65 72 20 73 74 72 69 6e 67 0a 2a  e order string.*
22b10 2a 20 20 20 20 20 20 20 20 20 20 20 63 6f 6e 74  *           cont
22b20 61 69 6e 69 6e 67 20 74 68 65 20 64 65 63 6c 61  aining the decla
22b30 72 65 64 20 64 61 74 61 74 79 70 65 20 6f 66 20  red datatype of 
22b40 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  the table column
22b50 20 74 68 61 74 20 61 70 70 65 61 72 73 0a 2a 2a   that appears.**
22b60 20 20 20 20 20 20 20 20 20 20 20 61 73 20 74 68             as th
22b70 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 28 6e 75  e Nth column (nu
22b80 6d 62 65 72 65 64 20 66 72 6f 6d 20 30 29 20 6f  mbered from 0) o
22b90 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
22ba0 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   to the.**      
22bb0 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73       [prepared s
22bc0 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2a 0a  tatement] S..**.
22bd0 2a 2a 20 7b 46 31 33 37 36 33 7d 20 20 49 66 20  ** {F13763}  If 
22be0 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 30  N is less than 0
22bf0 20 6f 72 20 4e 20 69 73 20 67 72 65 61 74 65 72   or N is greater
22c00 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74   than or equal t
22c10 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74  o.**           t
22c20 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
22c30 75 6d 6e 73 20 69 6e 20 5b 70 72 65 70 61 72 65  umns in [prepare
22c40 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a  d statement] S.*
22c50 2a 20 20 20 20 20 20 20 20 20 20 20 6f 72 20 69  *           or i
22c60 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  f the Nth column
22c70 20 6f 66 20 53 20 69 73 20 61 6e 20 65 78 70 72   of S is an expr
22c80 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65  ession or subque
22c90 72 79 20 72 61 74 68 65 72 0a 2a 2a 20 20 20 20  ry rather.**    
22ca0 20 20 20 20 20 20 20 74 68 61 6e 20 61 20 74 61         than a ta
22cb0 62 6c 65 20 63 6f 6c 75 6d 6e 20 6f 72 20 69 66  ble column or if
22cc0 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
22cd0 74 69 6f 6e 20 66 61 69 6c 75 72 65 0a 2a 2a 20  tion failure.** 
22ce0 20 20 20 20 20 20 20 20 20 20 6f 63 63 75 72 73            occurs
22cf0 20 64 75 72 69 6e 67 20 65 6e 63 6f 64 69 6e 67   during encoding
22d00 20 63 6f 6e 76 65 72 73 69 6f 6e 73 2c 20 74 68   conversions, th
22d10 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  en.**           
22d20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
22d30 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70  3_column_decltyp
22d40 65 28 53 2c 4e 29 5d 20 6f 72 0a 2a 2a 20 20 20  e(S,N)] or.**   
22d50 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
22d60 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65  _column_decltype
22d70 31 36 28 53 2c 4e 29 5d 20 72 65 74 75 72 6e 20  16(S,N)] return 
22d80 4e 55 4c 4c 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63  NULL..*/.const c
22d90 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
22da0 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c  umn_decltype(sql
22db0 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
22dc0 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
22dd0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c  ite3_column_decl
22de0 74 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73  type16(sqlite3_s
22df0 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 20 0a  tmt*,int);../* .
22e00 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 45 76  ** CAPI3REF:  Ev
22e10 61 6c 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74  aluate An SQL St
22e20 61 74 65 6d 65 6e 74 20 7b 46 31 33 32 30 30 7d  atement {F13200}
22e30 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 6e 20  .**.** After an 
22e40 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
22e50 65 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72  ent] has been pr
22e60 65 70 61 72 65 64 20 77 69 74 68 20 61 20 63 61  epared with a ca
22e70 6c 6c 0a 2a 2a 20 74 6f 20 65 69 74 68 65 72 20  ll.** to either 
22e80 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
22e90 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  _v2()] or [sqlit
22ea0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
22eb0 29 5d 20 6f 72 20 74 6f 20 6f 6e 65 20 6f 66 0a  )] or to one of.
22ec0 2a 2a 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e  ** the legacy in
22ed0 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65  terfaces [sqlite
22ee0 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20  3_prepare()] or 
22ef0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
22f00 31 36 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74  16()],.** then t
22f10 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73  his function mus
22f20 74 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20  t be called one 
22f30 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f  or more times to
22f40 20 65 76 61 6c 75 61 74 65 20 74 68 65 20 0a 2a   evaluate the .*
22f50 2a 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a  * statement..**.
22f60 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f  ** The details o
22f70 66 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f  f the behavior o
22f80 66 20 74 68 69 73 20 73 71 6c 69 74 65 33 5f 73  f this sqlite3_s
22f90 74 65 70 28 29 20 69 6e 74 65 72 66 61 63 65 20  tep() interface 
22fa0 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65  depend.** on whe
22fb0 74 68 65 72 20 74 68 65 20 73 74 61 74 65 6d 65  ther the stateme
22fc0 6e 74 20 77 61 73 20 70 72 65 70 61 72 65 64 20  nt was prepared 
22fd0 75 73 69 6e 67 20 74 68 65 20 6e 65 77 65 72 20  using the newer 
22fe0 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 0a 2a  "v2" interface.*
22ff0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
23000 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71  re_v2()] and [sq
23010 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
23020 76 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64  v2()] or the old
23030 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74  er legacy.** int
23040 65 72 66 61 63 65 20 5b 73 71 6c 69 74 65 33 5f  erface [sqlite3_
23050 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b  prepare()] and [
23060 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
23070 36 28 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f  6()].  The use o
23080 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32  f the.** new "v2
23090 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72  " interface is r
230a0 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e  ecommended for n
230b0 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ew applications 
230c0 62 75 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a  but the legacy.*
230d0 2a 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c  * interface will
230e0 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20   continue to be 
230f0 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a  supported..**.**
23100 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69   In the legacy i
23110 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 72 65  nterface, the re
23120 74 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20  turn value will 
23130 62 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54  be either [SQLIT
23140 45 5f 42 55 53 59 5d 2c 20 0a 2a 2a 20 5b 53 51  E_BUSY], .** [SQ
23150 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c  LITE_DONE], [SQL
23160 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54  ITE_ROW], [SQLIT
23170 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51  E_ERROR], or [SQ
23180 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a  LITE_MISUSE]..**
23190 20 57 69 74 68 20 74 68 65 20 22 76 32 22 20 69   With the "v2" i
231a0 6e 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66  nterface, any of
231b0 20 74 68 65 20 6f 74 68 65 72 20 5b 53 51 4c 49   the other [SQLI
231c0 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63  TE_OK | result c
231d0 6f 64 65 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49  ode].** or [SQLI
231e0 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20  TE_IOERR_READ | 
231f0 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
23200 63 6f 64 65 5d 20 6d 69 67 68 74 20 62 65 20 72  code] might be r
23210 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 77 65  eturned as.** we
23220 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54  ll..**.** [SQLIT
23230 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68  E_BUSY] means th
23240 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20  at the database 
23250 65 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c  engine was unabl
23260 65 20 74 6f 20 61 63 71 75 69 72 65 20 74 68 65  e to acquire the
23270 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63  .** database loc
23280 6b 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64  ks it needs to d
23290 6f 20 69 74 73 20 6a 6f 62 2e 20 20 49 66 20 74  o its job.  If t
232a0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
232b0 61 20 43 4f 4d 4d 49 54 0a 2a 2a 20 6f 72 20 6f  a COMMIT.** or o
232c0 63 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66  ccurs outside of
232d0 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61   an explicit tra
232e0 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79  nsaction, then y
232f0 6f 75 20 63 61 6e 20 72 65 74 72 79 20 74 68 65  ou can retry the
23300 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  .** statement.  
23310 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  If the statement
23320 20 69 73 20 6e 6f 74 20 61 20 43 4f 4d 4d 49 54   is not a COMMIT
23330 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68   and occurs with
23340 69 6e 20 61 0a 2a 2a 20 65 78 70 6c 69 63 69 74  in a.** explicit
23350 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65   transaction the
23360 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c  n you should rol
23370 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61  lback the transa
23380 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20  ction before.** 
23390 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a  continuing..**.*
233a0 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20  * [SQLITE_DONE] 
233b0 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 73  means that the s
233c0 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e  tatement has fin
233d0 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a  ished executing.
233e0 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e  ** successfully.
233f0 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29    sqlite3_step()
23400 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63   should not be c
23410 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74  alled again on t
23420 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d  his virtual.** m
23430 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66  achine without f
23440 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71  irst calling [sq
23450 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74  lite3_reset()] t
23460 6f 20 72 65 73 65 74 20 74 68 65 20 76 69 72 74  o reset the virt
23470 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62  ual.** machine b
23480 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69  ack to its initi
23490 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20  al state..**.** 
234a0 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  If the SQL state
234b0 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75  ment being execu
234c0 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20  ted returns any 
234d0 64 61 74 61 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b  data, then .** [
234e0 53 51 4c 49 54 45 5f 52 4f 57 5d 20 69 73 20 72  SQLITE_ROW] is r
234f0 65 74 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d  eturned each tim
23500 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64  e a new row of d
23510 61 74 61 20 69 73 20 72 65 61 64 79 0a 2a 2a 20  ata is ready.** 
23520 66 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62  for processing b
23530 79 20 74 68 65 20 63 61 6c 6c 65 72 2e 20 54 68  y the caller. Th
23540 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20  e values may be 
23550 61 63 63 65 73 73 65 64 20 75 73 69 6e 67 0a 2a  accessed using.*
23560 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  * the [sqlite3_c
23570 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 63 6f 6c 75  olumn_int | colu
23580 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69  mn access functi
23590 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33  ons]..** sqlite3
235a0 5f 73 74 65 70 28 29 20 69 73 20 63 61 6c 6c 65  _step() is calle
235b0 64 20 61 67 61 69 6e 20 74 6f 20 72 65 74 72 69  d again to retri
235c0 65 76 65 20 74 68 65 20 6e 65 78 74 20 72 6f 77  eve the next row
235d0 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 20 0a 2a 2a   of data..** .**
235e0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
235f0 6d 65 61 6e 73 20 74 68 61 74 20 61 20 72 75 6e  means that a run
23600 2d 74 69 6d 65 20 65 72 72 6f 72 20 28 73 75 63  -time error (suc
23610 68 20 61 73 20 61 20 63 6f 6e 73 74 72 61 69 6e  h as a constrain
23620 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20  t.** violation) 
23630 68 61 73 20 6f 63 63 75 72 72 65 64 2e 20 20 73  has occurred.  s
23640 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68  qlite3_step() sh
23650 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c  ould not be call
23660 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74  ed again on.** t
23670 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f  he VM. More info
23680 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 66  rmation may be f
23690 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 20  ound by calling 
236a0 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
236b0 29 5d 2e 0a 2a 2a 20 57 69 74 68 20 74 68 65 20  )]..** With the 
236c0 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
236d0 2c 20 61 20 6d 6f 72 65 20 73 70 65 63 69 66 69  , a more specifi
236e0 63 20 65 72 72 6f 72 20 63 6f 64 65 20 28 65 78  c error code (ex
236f0 61 6d 70 6c 65 3a 0a 2a 2a 20 5b 53 51 4c 49 54  ample:.** [SQLIT
23700 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53  E_INTERRUPT], [S
23710 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b  QLITE_SCHEMA], [
23720 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c  SQLITE_CORRUPT],
23730 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a   and so forth).*
23740 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65  * can be obtaine
23750 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71  d by calling [sq
23760 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
23770 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  n the.** [prepar
23780 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20  ed statement].  
23790 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  In the "v2" inte
237a0 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f  rface,.** the mo
237b0 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f  re specific erro
237c0 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e  r code is return
237d0 65 64 20 64 69 72 65 63 74 6c 79 20 62 79 20 73  ed directly by s
237e0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a  qlite3_step()..*
237f0 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53  *.** [SQLITE_MIS
23800 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20  USE] means that 
23810 74 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  the this routine
23820 20 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70   was called inap
23830 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20  propriately..** 
23840 50 65 72 68 61 70 73 20 69 74 20 77 61 73 20 63  Perhaps it was c
23850 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70  alled on a [prep
23860 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
23870 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65  that has.** alre
23880 61 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65  ady been [sqlite
23890 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e  3_finalize | fin
238a0 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e  alized] or on on
238b0 65 20 74 68 61 74 20 68 61 64 20 0a 2a 2a 20 70  e that had .** p
238c0 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e  reviously return
238d0 65 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ed [SQLITE_ERROR
238e0 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  ] or [SQLITE_DON
238f0 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64  E].  Or it could
23900 0a 2a 2a 20 62 65 20 74 68 65 20 63 61 73 65 20  .** be the case 
23910 74 68 61 74 20 74 68 65 20 73 61 6d 65 20 64 61  that the same da
23920 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
23930 6e 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20  n is being used 
23940 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72  by two or.** mor
23950 65 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65  e threads at the
23960 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20   same moment in 
23970 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47  time..**.** <b>G
23980 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 65 20 41  oofy Interface A
23990 6c 65 72 74 3a 3c 2f 62 3e 0a 2a 2a 20 49 6e 20  lert:</b>.** In 
239a0 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72  the legacy inter
239b0 66 61 63 65 2c 20 0a 2a 2a 20 74 68 65 20 73 71  face, .** the sq
239c0 6c 69 74 65 33 5f 73 74 65 70 28 29 20 41 50 49  lite3_step() API
239d0 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20   always returns 
239e0 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20  a generic error 
239f0 63 6f 64 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  code,.** [SQLITE
23a00 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69  _ERROR], followi
23a10 6e 67 20 61 6e 79 20 65 72 72 6f 72 20 6f 74 68  ng any error oth
23a20 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
23a30 42 55 53 59 5d 0a 2a 2a 20 61 6e 64 20 5b 53 51  BUSY].** and [SQ
23a40 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59  LITE_MISUSE].  Y
23a50 6f 75 20 6d 75 73 74 20 63 61 6c 6c 20 5b 73 71  ou must call [sq
23a60 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
23a70 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  r.** [sqlite3_fi
23a80 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64  nalize()] in ord
23a90 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f  er to find one o
23aa0 66 20 74 68 65 20 73 70 65 63 69 66 69 63 0a 2a  f the specific.*
23ab0 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20  * [error codes] 
23ac0 74 68 61 74 20 62 65 74 74 65 72 20 64 65 73 63  that better desc
23ad0 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2e  ribes the error.
23ae0 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68 61  .** We admit tha
23af0 74 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f 66  t this is a goof
23b00 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20 70  y design.  The p
23b10 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e 20  roblem has been 
23b20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74 68  fixed.** with th
23b30 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
23b40 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70 61 72  .  If you prepar
23b50 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51  e all of your SQ
23b60 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
23b70 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71  using either [sq
23b80 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
23b90 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
23ba0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20  prepare16_v2()] 
23bb0 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68  instead.** of th
23bc0 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65  e legacy [sqlite
23bd0 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64  3_prepare()] and
23be0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
23bf0 65 31 36 28 29 5d 2c 20 74 68 65 6e 20 74 68 65  e16()], then the
23c00 20 0a 2a 2a 20 6d 6f 72 65 20 73 70 65 63 69 66   .** more specif
23c10 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d  ic [error codes]
23c20 20 61 72 65 20 72 65 74 75 72 6e 65 64 20 64 69   are returned di
23c30 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c  rectly.** by sql
23c40 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 54 68  ite3_step().  Th
23c50 65 20 75 73 65 20 6f 66 20 74 68 65 20 22 76 32  e use of the "v2
23c60 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72  " interface is r
23c70 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a  ecommended..**.*
23c80 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
23c90 0a 2a 2a 20 7b 46 31 33 32 30 32 7d 20 20 49 66  .** {F13202}  If
23ca0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
23cb0 6d 65 6e 74 5d 20 53 20 69 73 20 72 65 61 64 79  ment] S is ready
23cc0 20 74 6f 20 62 65 0a 2a 2a 20 20 20 20 20 20 20   to be.**       
23cd0 20 20 20 20 72 75 6e 2c 20 74 68 65 6e 20 5b 73      run, then [s
23ce0 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
23cf0 61 64 76 61 6e 63 65 73 20 74 68 61 74 20 70 72  advances that pr
23d00 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
23d10 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 75 6e  .**           un
23d20 74 69 6c 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f  til to completio
23d30 6e 20 6f 72 20 75 6e 74 69 6c 20 69 74 20 69 73  n or until it is
23d40 20 72 65 61 64 79 20 74 6f 20 72 65 74 75 72 6e   ready to return
23d50 20 61 6e 6f 74 68 65 72 0a 2a 2a 20 20 20 20 20   another.**     
23d60 20 20 20 20 20 20 72 6f 77 20 6f 66 20 74 68 65        row of the
23d70 20 72 65 73 75 6c 74 20 73 65 74 20 6f 72 20 61   result set or a
23d80 6e 20 69 6e 74 65 72 72 75 70 74 20 6f 72 20 72  n interrupt or r
23d90 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 6f 63  un-time error oc
23da0 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35  curs..**.** {F15
23db0 33 30 34 7d 20 20 57 68 65 6e 20 61 20 63 61 6c  304}  When a cal
23dc0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
23dd0 65 70 28 53 29 5d 20 63 61 75 73 65 73 20 74 68  ep(S)] causes th
23de0 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  e .**           
23df0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
23e00 65 6e 74 5d 20 53 20 74 6f 20 72 75 6e 20 74 6f  ent] S to run to
23e10 20 63 6f 6d 70 6c 65 74 69 6f 6e 2c 0a 2a 2a 20   completion,.** 
23e20 20 20 20 20 20 20 20 20 20 20 74 68 65 20 66 75            the fu
23e30 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 5b  nction returns [
23e40 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 0a 2a 2a  SQLITE_DONE]..**
23e50 0a 2a 2a 20 7b 46 31 35 33 30 36 7d 20 20 57 68  .** {F15306}  Wh
23e60 65 6e 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71  en a call to [sq
23e70 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 73  lite3_step(S)] s
23e80 74 6f 70 73 20 62 65 63 61 75 73 65 20 69 74 20  tops because it 
23e90 69 73 20 72 65 61 64 79 0a 2a 2a 20 20 20 20 20  is ready.**     
23ea0 20 20 20 20 20 20 74 6f 20 72 65 74 75 72 6e 20        to return 
23eb0 61 6e 6f 74 68 65 72 20 72 6f 77 20 6f 66 20 74  another row of t
23ec0 68 65 20 72 65 73 75 6c 74 20 73 65 74 2c 20 69  he result set, i
23ed0 74 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20  t returns.**    
23ee0 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 52         [SQLITE_R
23ef0 4f 57 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 33  OW]..**.** {F153
23f00 30 38 7d 20 20 49 66 20 61 20 63 61 6c 6c 20 74  08}  If a call t
23f10 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
23f20 53 29 5d 20 65 6e 63 6f 75 6e 74 65 72 73 20 61  S)] encounters a
23f30 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b  n.**           [
23f40 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
23f50 74 7c 69 6e 74 65 72 72 75 70 74 5d 20 6f 72 20  t|interrupt] or 
23f60 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72  a run-time error
23f70 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 69  ,.**           i
23f80 74 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70  t returns an app
23f90 72 6f 70 72 69 61 74 65 20 65 72 72 6f 72 20 63  ropriate error c
23fa0 6f 64 65 20 74 68 61 74 20 69 73 20 6e 6f 74 20  ode that is not 
23fb0 6f 6e 65 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20  one of.**       
23fc0 20 20 20 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c      [SQLITE_OK],
23fd0 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 6f   [SQLITE_ROW], o
23fe0 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e  r [SQLITE_DONE].
23ff0 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 33 31 30 7d 20  .**.** {F15310} 
24000 20 49 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   If an [sqlite3_
24010 69 6e 74 65 72 72 75 70 74 7c 69 6e 74 65 72 72  interrupt|interr
24020 75 70 74 5d 20 6f 72 20 72 75 6e 2d 74 69 6d 65  upt] or run-time
24030 20 65 72 72 6f 72 0a 2a 2a 20 20 20 20 20 20 20   error.**       
24040 20 20 20 20 6f 63 63 75 72 73 20 64 75 72 69 6e      occurs durin
24050 67 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  g a call to [sql
24060 69 74 65 33 5f 73 74 65 70 28 53 29 5d 0a 2a 2a  ite3_step(S)].**
24070 20 20 20 20 20 20 20 20 20 20 20 66 6f 72 20 61             for a
24080 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
24090 6d 65 6e 74 5d 20 53 20 63 72 65 61 74 65 64 20  ment] S created 
240a0 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20  using.**        
240b0 20 20 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66     legacy interf
240c0 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72  aces [sqlite3_pr
240d0 65 70 61 72 65 28 29 5d 20 6f 72 0a 2a 2a 20 20  epare()] or.**  
240e0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
240f0 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 74  3_prepare16()] t
24100 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  hen the function
24110 20 72 65 74 75 72 6e 73 20 65 69 74 68 65 72 0a   returns either.
24120 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 53 51  **           [SQ
24130 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 5b 53 51  LITE_ERROR], [SQ
24140 4c 49 54 45 5f 42 55 53 59 5d 2c 20 6f 72 20 5b  LITE_BUSY], or [
24150 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a  SQLITE_MISUSE]..
24160 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  */.int sqlite3_s
24170 74 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  tep(sqlite3_stmt
24180 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
24190 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63  REF: Number of c
241a0 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 73 75  olumns in a resu
241b0 6c 74 20 73 65 74 20 7b 46 31 33 37 37 30 7d 0a  lt set {F13770}.
241c0 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 74 68 65  **.** Return the
241d0 20 6e 75 6d 62 65 72 20 6f 66 20 76 61 6c 75 65   number of value
241e0 73 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74  s in the current
241f0 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75   row of the resu
24200 6c 74 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 49 4e  lt set..**.** IN
24210 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
24220 7b 46 31 33 37 37 31 7d 20 20 41 66 74 65 72 20  {F13771}  After 
24230 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  a call to [sqlit
24240 65 33 5f 73 74 65 70 28 53 29 5d 20 74 68 61 74  e3_step(S)] that
24250 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20   returns.**     
24260 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 52 4f        [SQLITE_RO
24270 57 5d 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33  W], the [sqlite3
24280 5f 64 61 74 61 5f 63 6f 75 6e 74 28 53 29 5d 20  _data_count(S)] 
24290 72 6f 75 74 69 6e 65 0a 2a 2a 20 20 20 20 20 20  routine.**      
242a0 20 20 20 20 20 77 69 6c 6c 20 72 65 74 75 72 6e       will return
242b0 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65 20   the same value 
242c0 61 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  as the.**       
242d0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c      [sqlite3_col
242e0 75 6d 6e 5f 63 6f 75 6e 74 28 53 29 5d 20 66 75  umn_count(S)] fu
242f0 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46  nction..**.** {F
24300 31 33 37 37 32 7d 20 20 41 66 74 65 72 20 5b 73  13772}  After [s
24310 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
24320 68 61 73 20 72 65 74 75 72 6e 65 64 20 61 6e 79  has returned any
24330 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61   value other tha
24340 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b  n.**           [
24350 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 62  SQLITE_ROW] or b
24360 65 66 6f 72 65 20 5b 73 71 6c 69 74 65 33 5f 73  efore [sqlite3_s
24370 74 65 70 28 53 29 5d 20 68 61 73 20 62 65 65 6e  tep(S)] has been
24380 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 63   .**           c
24390 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 5b 70 72  alled on the [pr
243a0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
243b0 5d 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  ] for.**        
243c0 20 20 20 74 68 65 20 66 69 72 73 74 20 74 69 6d     the first tim
243d0 65 20 73 69 6e 63 65 20 69 74 20 77 61 73 20 5b  e since it was [
243e0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 7c  sqlite3_prepare|
243f0 70 72 65 70 61 72 65 64 5d 0a 2a 2a 20 20 20 20  prepared].**    
24400 20 20 20 20 20 20 20 6f 72 20 5b 73 71 6c 69 74         or [sqlit
24410 65 33 5f 72 65 73 65 74 7c 72 65 73 65 74 5d 2c  e3_reset|reset],
24420 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 61   the [sqlite3_da
24430 74 61 5f 63 6f 75 6e 74 28 53 29 5d 0a 2a 2a 20  ta_count(S)].** 
24440 20 20 20 20 20 20 20 20 20 20 72 6f 75 74 69 6e            routin
24450 65 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a  e returns zero..
24460 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64  */.int sqlite3_d
24470 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  ata_count(sqlite
24480 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
24490 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
244a0 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74   Fundamental Dat
244b0 61 74 79 70 65 73 20 7b 46 31 30 32 36 35 7d 0a  atypes {F10265}.
244c0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c  ** KEYWORDS: SQL
244d0 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 7b  ITE_TEXT.**.** {
244e0 46 31 30 32 36 36 7d 45 76 65 72 79 20 76 61 6c  F10266}Every val
244f0 75 65 20 69 6e 20 53 51 4c 69 74 65 20 68 61 73  ue in SQLite has
24500 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 75 6e   one of five fun
24510 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 79 70  damental datatyp
24520 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  es:.**.** <ul>.*
24530 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73 69  * <li> 64-bit si
24540 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20  gned integer.** 
24550 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 45 45  <li> 64-bit IEEE
24560 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
24570 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73  number.** <li> s
24580 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c  tring.** <li> BL
24590 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a  OB.** <li> NULL.
245a0 2a 2a 20 3c 2f 75 6c 3e 20 7b 45 4e 44 7d 0a 2a  ** </ul> {END}.*
245b0 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
245c0 61 6e 74 73 20 61 72 65 20 63 6f 64 65 73 20 66  ants are codes f
245d0 6f 72 20 65 61 63 68 20 6f 66 20 74 68 6f 73 65  or each of those
245e0 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f   types..**.** No
245f0 74 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 49  te that the SQLI
24600 54 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e 74  TE_TEXT constant
24610 20 77 61 73 20 61 6c 73 6f 20 75 73 65 64 20 69   was also used i
24620 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  n SQLite version
24630 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70   2.** for a comp
24640 6c 65 74 65 6c 79 20 64 69 66 66 65 72 65 6e 74  letely different
24650 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77   meaning.  Softw
24660 61 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61  are that links a
24670 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53  gainst both.** S
24680 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 20  QLite version 2 
24690 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 69  and SQLite versi
246a0 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 65 20  on 3 should use 
246b0 53 51 4c 49 54 45 33 5f 54 45 58 54 20 6e 6f 74  SQLITE3_TEXT not
246c0 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e  .** SQLITE_TEXT.
246d0 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
246e0 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64  TE_INTEGER  1.#d
246f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f  efine SQLITE_FLO
24700 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20  AT    2.#define 
24710 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20  SQLITE_BLOB     
24720 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
24730 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64  _NULL     5.#ifd
24740 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23  ef SQLITE_TEXT.#
24750 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45   undef SQLITE_TE
24760 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e  XT.#else.# defin
24770 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20  e SQLITE_TEXT   
24780 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69    3.#endif.#defi
24790 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20  ne SQLITE3_TEXT 
247a0 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50      3../*.** CAP
247b0 49 33 52 45 46 3a 20 52 65 73 75 6c 74 73 20 56  I3REF: Results V
247c0 61 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 75 65  alues From A Que
247d0 72 79 20 7b 46 31 33 38 30 30 7d 0a 2a 2a 0a 2a  ry {F13800}.**.*
247e0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
247f0 20 66 6f 72 6d 20 74 68 65 20 22 72 65 73 75 6c   form the "resul
24800 74 20 73 65 74 20 71 75 65 72 79 22 20 69 6e 74  t set query" int
24810 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  erface..**.** Th
24820 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
24830 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  urn information 
24840 61 62 6f 75 74 0a 2a 2a 20 61 20 73 69 6e 67 6c  about.** a singl
24850 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  e column of the 
24860 63 75 72 72 65 6e 74 20 72 65 73 75 6c 74 20 72  current result r
24870 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20  ow of a query.  
24880 49 6e 20 65 76 65 72 79 0a 2a 2a 20 63 61 73 65  In every.** case
24890 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
248a0 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ent is a pointer
248b0 20 74 6f 20 74 68 65 20 0a 2a 2a 20 5b 70 72 65   to the .** [pre
248c0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
248d0 20 74 68 61 74 20 69 73 20 62 65 69 6e 67 0a 2a   that is being.*
248e0 2a 20 65 76 61 6c 75 61 74 65 64 20 28 74 68 65  * evaluated (the
248f0 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d   [sqlite3_stmt*]
24900 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e   that was return
24910 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c  ed from .** [sql
24920 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
24930 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73  )] or one of its
24940 20 76 61 72 69 61 6e 74 73 29 20 61 6e 64 0a 2a   variants) and.*
24950 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  * the second arg
24960 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64  ument is the ind
24970 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  ex of the column
24980 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f 72   for which infor
24990 6d 61 74 69 6f 6e 20 0a 2a 2a 20 73 68 6f 75 6c  mation .** shoul
249a0 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 20  d be returned.  
249b0 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f  The left-most co
249c0 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75  lumn of the resu
249d0 6c 74 20 73 65 74 0a 2a 2a 20 68 61 73 20 61 6e  lt set.** has an
249e0 20 69 6e 64 65 78 20 6f 66 20 30 2e 0a 2a 2a 0a   index of 0..**.
249f0 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 74  ** If the SQL st
24a00 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20 63  atement is not c
24a10 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74  urrently point t
24a20 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f  o a valid row, o
24a30 72 20 69 66 20 74 68 65 0a 2a 2a 20 74 68 65 20  r if the.** the 
24a40 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73 20  column index is 
24a50 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68  out of range, th
24a60 65 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65  e result is unde
24a70 66 69 6e 65 64 2e 20 0a 2a 2a 20 54 68 65 73 65  fined. .** These
24a80 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e   routines may on
24a90 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65  ly be called whe
24aa0 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  n the most recen
24ab0 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  t call to.** [sq
24ac0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61  lite3_step()] ha
24ad0 73 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49  s returned [SQLI
24ae0 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74  TE_ROW] and neit
24af0 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  her.** [sqlite3_
24b00 72 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71  reset()] nor [sq
24b10 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
24b20 5d 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 20  ] has been call 
24b30 73 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a  subsequently..**
24b40 20 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73 65   If any of these
24b50 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61   routines are ca
24b60 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69  lled after [sqli
24b70 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a  te3_reset()] or.
24b80 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ** [sqlite3_fina
24b90 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72  lize()] or after
24ba0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
24bb0 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a 2a  ] has returned.*
24bc0 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65  * something othe
24bd0 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52  r than [SQLITE_R
24be0 4f 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74 73  OW], the results
24bf0 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a   are undefined..
24c00 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 73  ** If [sqlite3_s
24c10 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  tep()] or [sqlit
24c20 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b  e3_reset()] or [
24c30 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
24c40 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65  ()].** are calle
24c50 64 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72 65  d from a differe
24c60 6e 74 20 74 68 72 65 61 64 20 77 68 69 6c 65 20  nt thread while 
24c70 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75  any of these rou
24c80 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e  tines.** are pen
24c90 64 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72  ding, then the r
24ca0 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
24cb0 69 6e 65 64 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68  ined.  .**.** Th
24cc0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
24cd0 5f 74 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20  _type() routine 
24ce0 72 65 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c  returns .** [SQL
24cf0 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61  ITE_INTEGER | da
24d00 74 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f 72  tatype code] for
24d10 20 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61 74   the initial dat
24d20 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65  a type.** of the
24d30 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20   result column. 
24d40 20 54 68 65 20 72 65 74 75 72 6e 65 64 20 76 61   The returned va
24d50 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53  lue is one of [S
24d60 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a  QLITE_INTEGER],.
24d70 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54  ** [SQLITE_FLOAT
24d80 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d  ], [SQLITE_TEXT]
24d90 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c  , [SQLITE_BLOB],
24da0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c   or [SQLITE_NULL
24db0 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a  ].  The value.**
24dc0 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
24dd0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
24de0 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69  () is only meani
24df0 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74 79 70 65  ngful if no type
24e00 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20  .** conversions 
24e10 68 61 76 65 20 6f 63 63 75 72 72 65 64 20 61 73  have occurred as
24e20 20 64 65 73 63 72 69 62 65 64 20 62 65 6c 6f 77   described below
24e30 2e 20 20 41 66 74 65 72 20 61 20 74 79 70 65 20  .  After a type 
24e40 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74  conversion,.** t
24e50 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
24e60 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
24e70 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 75 6e  umn_type() is un
24e80 64 65 66 69 6e 65 64 2e 20 20 46 75 74 75 72 65  defined.  Future
24e90 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  .** versions of 
24ea0 53 51 4c 69 74 65 20 6d 61 79 20 63 68 61 6e 67  SQLite may chang
24eb0 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f  e the behavior o
24ec0 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  f sqlite3_column
24ed0 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f  _type().** follo
24ee0 77 69 6e 67 20 61 20 74 79 70 65 20 63 6f 6e 76  wing a type conv
24ef0 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66  ersion..**.** If
24f00 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
24f10 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 73   BLOB or UTF-8 s
24f20 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73  tring then the s
24f30 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
24f40 74 65 73 28 29 20 0a 2a 2a 20 72 6f 75 74 69 6e  tes() .** routin
24f50 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
24f60 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
24f70 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74   that BLOB or st
24f80 72 69 6e 67 2e 0a 2a 2a 20 49 66 20 74 68 65 20  ring..** If the 
24f90 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d  result is a UTF-
24fa0 31 36 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20  16 string, then 
24fb0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
24fc0 79 74 65 73 28 29 20 63 6f 6e 76 65 72 74 73 0a  ytes() converts.
24fd0 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f  ** the string to
24fe0 20 55 54 46 2d 38 20 61 6e 64 20 74 68 65 6e 20   UTF-8 and then 
24ff0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
25000 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20  er of bytes..** 
25010 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
25020 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65   a numeric value
25030 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
25040 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65  lumn_bytes() use
25050 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e  s.** [sqlite3_sn
25060 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e  printf()] to con
25070 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20  vert that value 
25080 74 6f 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e  to a UTF-8 strin
25090 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a  g and returns.**
250a0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
250b0 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72  ytes in that str
250c0 69 6e 67 2e 0a 2a 2a 20 54 68 65 20 76 61 6c 75  ing..** The valu
250d0 65 20 72 65 74 75 72 6e 65 64 20 64 6f 65 73 20  e returned does 
250e0 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 65 20  not include the 
250f0 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20  zero terminator 
25100 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66  at the end.** of
25110 20 74 68 65 20 73 74 72 69 6e 67 2e 20 20 46 6f   the string.  Fo
25120 72 20 63 6c 61 72 69 74 79 3a 20 74 68 65 20 76  r clarity: the v
25130 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 73  alue returned is
25140 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
25150 2a 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 73  * bytes in the s
25160 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e  tring, not the n
25170 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74  umber of charact
25180 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 53 74 72 69 6e  ers..**.** Strin
25190 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  gs returned by s
251a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
251b0 78 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  xt() and sqlite3
251c0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
251d0 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79 20  ,.** even empty 
251e0 73 74 72 69 6e 67 73 2c 20 61 72 65 20 61 6c 77  strings, are alw
251f0 61 79 73 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  ays zero termina
25200 74 65 64 2e 20 20 54 68 65 20 72 65 74 75 72 6e  ted.  The return
25210 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20 73  .** value from s
25220 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
25230 6f 62 28 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d  ob() for a zero-
25240 6c 65 6e 67 74 68 20 62 6c 6f 62 20 69 73 20 61  length blob is a
25250 6e 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 70  n arbitrary.** p
25260 6f 69 6e 74 65 72 2c 20 70 6f 73 73 69 62 6c 79  ointer, possibly
25270 20 65 76 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69   even a NULL poi
25280 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  nter..**.** The 
25290 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
252a0 79 74 65 73 31 36 28 29 20 72 6f 75 74 69 6e 65  ytes16() routine
252b0 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 73   is similar to s
252c0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
252d0 74 65 73 28 29 0a 2a 2a 20 62 75 74 20 6c 65 61  tes().** but lea
252e0 76 65 73 20 74 68 65 20 72 65 73 75 6c 74 20 69  ves the result i
252f0 6e 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69  n UTF-16 in nati
25300 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 69 6e  ve byte order in
25310 73 74 65 61 64 20 6f 66 20 55 54 46 2d 38 2e 20  stead of UTF-8. 
25320 20 0a 2a 2a 20 54 68 65 20 7a 65 72 6f 20 74 65   .** The zero te
25330 72 6d 69 6e 61 74 6f 72 20 69 73 20 6e 6f 74 20  rminator is not 
25340 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 69 73  included in this
25350 20 63 6f 75 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68   count..**.** Th
25360 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65  e object returne
25370 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d by [sqlite3_co
25380 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73  lumn_value()] is
25390 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63   an.** [unprotec
253a0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
253b0 65 5d 20 6f 62 6a 65 63 74 2e 20 20 41 6e 20 75  e] object.  An u
253c0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
253d0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 0a  e3_value object.
253e0 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75  ** may only be u
253f0 73 65 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65  sed with [sqlite
25400 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20  3_bind_value()] 
25410 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  and [sqlite3_res
25420 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a  ult_value()]..**
25430 20 49 66 20 74 68 65 20 5b 75 6e 70 72 6f 74 65   If the [unprote
25440 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
25450 75 65 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72  ue] object retur
25460 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ned by.** [sqlit
25470 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28  e3_column_value(
25480 29 5d 20 69 73 20 75 73 65 64 20 69 6e 20 61 6e  )] is used in an
25490 79 20 6f 74 68 65 72 20 77 61 79 2c 20 69 6e 63  y other way, inc
254a0 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20  luding calls.** 
254b0 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65  to routines like
254c0 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61   .** [sqlite3_va
254d0 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c  lue_int()], [sql
254e0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28  ite3_value_text(
254f0 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  )], or [sqlite3_
25500 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 0a  value_bytes()],.
25510 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  ** then the beha
25520 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
25530 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  d..**.** These r
25540 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74 20  outines attempt 
25550 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76  to convert the v
25560 61 6c 75 65 20 77 68 65 72 65 20 61 70 70 72 6f  alue where appro
25570 70 72 69 61 74 65 2e 20 20 46 6f 72 0a 2a 2a 20  priate.  For.** 
25580 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20  example, if the 
25590 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65  internal represe
255a0 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54  ntation is FLOAT
255b0 20 61 6e 64 20 61 20 74 65 78 74 20 72 65 73 75   and a text resu
255c0 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 74  lt.** is request
255d0 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70  ed, [sqlite3_snp
255e0 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73 65 64  rintf()] is used
255f0 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 64   internally to d
25600 6f 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e  o the conversion
25610 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  .** automaticall
25620 79 2e 20 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e  y.  The followin
25630 67 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73 20  g table details 
25640 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20  the conversions 
25650 74 68 61 74 0a 2a 2a 20 61 72 65 20 61 70 70 6c  that.** are appl
25660 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ied:.**.** <bloc
25670 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c  kquote>.** <tabl
25680 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a  e border="1">.**
25690 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e   <tr><th> Intern
256a0 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20  al<br>Type <th> 
256b0 52 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79 70  Requested<br>Typ
256c0 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73 69  e <th>  Conversi
256d0 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64  on.**.** <tr><td
256e0 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
256f0 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 52  INTEGER   <td> R
25700 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74  esult is 0.** <t
25710 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
25720 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
25730 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 2e  td> Result is 0.
25740 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  0.** <tr><td>  N
25750 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54 45  ULL    <td>   TE
25760 58 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  XT    <td> Resul
25770 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  t is NULL pointe
25780 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  r.** <tr><td>  N
25790 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42 4c  ULL    <td>   BL
257a0 4f 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  OB    <td> Resul
257b0 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  t is NULL pointe
257c0 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e  r.** <tr><td> IN
257d0 54 45 47 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f  TEGER  <td>  FLO
257e0 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65  AT    <td> Conve
257f0 72 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 72 20  rt from integer 
25800 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e  to float.** <tr>
25810 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74  <td> INTEGER  <t
25820 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64  d>   TEXT    <td
25830 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e  > ASCII renderin
25840 67 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72  g of the integer
25850 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54  .** <tr><td> INT
25860 45 47 45 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f  EGER  <td>   BLO
25870 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61  B    <td> Same a
25880 73 20 66 6f 72 20 49 4e 54 45 47 45 52 2d 3e 54  s for INTEGER->T
25890 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  EXT.** <tr><td> 
258a0 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e   FLOAT   <td> IN
258b0 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e  TEGER   <td> Con
258c0 76 65 72 74 20 66 72 6f 6d 20 66 6c 6f 61 74 20  vert from float 
258d0 74 6f 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74  to integer.** <t
258e0 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20  r><td>  FLOAT   
258f0 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c  <td>   TEXT    <
25900 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72  td> ASCII render
25910 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61 74  ing of the float
25920 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c  .** <tr><td>  FL
25930 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f  OAT   <td>   BLO
25940 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61  B    <td> Same a
25950 73 20 46 4c 4f 41 54 2d 3e 54 45 58 54 0a 2a 2a  s FLOAT->TEXT.**
25960 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20   <tr><td>  TEXT 
25970 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
25980 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 69 28    <td> Use atoi(
25990 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54  ).** <tr><td>  T
259a0 45 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f  EXT    <td>  FLO
259b0 41 54 20 20 20 20 3c 74 64 3e 20 55 73 65 20 61  AT    <td> Use a
259c0 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64  tof().** <tr><td
259d0 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20  >  TEXT    <td> 
259e0 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e    BLOB    <td> N
259f0 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e  o change.** <tr>
25a00 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74  <td>  BLOB    <t
25a10 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
25a20 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58  > Convert to TEX
25a30 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f 69 28  T then use atoi(
25a40 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42  ).** <tr><td>  B
25a50 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f  LOB    <td>  FLO
25a60 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65  AT    <td> Conve
25a70 72 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20  rt to TEXT then 
25a80 75 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74  use atof().** <t
25a90 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20  r><td>  BLOB    
25aa0 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c  <td>   TEXT    <
25ab0 74 64 3e 20 41 64 64 20 61 20 7a 65 72 6f 20 74  td> Add a zero t
25ac0 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65 65  erminator if nee
25ad0 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a  ded.** </table>.
25ae0 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  ** </blockquote>
25af0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65  .**.** The table
25b00 20 61 62 6f 76 65 20 6d 61 6b 65 73 20 72 65 66   above makes ref
25b10 65 72 65 6e 63 65 20 74 6f 20 73 74 61 6e 64 61  erence to standa
25b20 72 64 20 43 20 6c 69 62 72 61 72 79 20 66 75 6e  rd C library fun
25b30 63 74 69 6f 6e 73 20 61 74 6f 69 28 29 0a 2a 2a  ctions atoi().**
25b40 20 61 6e 64 20 61 74 6f 66 28 29 2e 20 20 53 51   and atof().  SQ
25b50 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74 20 72 65  Lite does not re
25b60 61 6c 6c 79 20 75 73 65 20 74 68 65 73 65 20 66  ally use these f
25b70 75 6e 63 74 69 6f 6e 73 2e 20 20 49 74 20 68 61  unctions.  It ha
25b80 73 20 69 74 73 0a 2a 2a 20 6f 77 6e 20 65 71 75  s its.** own equ
25b90 69 76 61 6c 65 6e 74 20 69 6e 74 65 72 6e 61 6c  ivalent internal
25ba0 20 72 6f 75 74 69 6e 65 73 2e 20 20 54 68 65 20   routines.  The 
25bb0 61 74 6f 69 28 29 20 61 6e 64 20 61 74 6f 66 28  atoi() and atof(
25bc0 29 20 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 75  ) names are.** u
25bd0 73 65 64 20 69 6e 20 74 68 65 20 74 61 62 6c 65  sed in the table
25be0 20 66 6f 72 20 62 72 65 76 69 74 79 20 61 6e 64   for brevity and
25bf0 20 62 65 63 61 75 73 65 20 74 68 65 79 20 61 72   because they ar
25c00 65 20 66 61 6d 69 6c 69 61 72 20 74 6f 20 6d 6f  e familiar to mo
25c10 73 74 0a 2a 2a 20 43 20 70 72 6f 67 72 61 6d 6d  st.** C programm
25c20 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  ers..**.** Note 
25c30 74 68 61 74 20 77 68 65 6e 20 74 79 70 65 20 63  that when type c
25c40 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63 75 72  onversions occur
25c50 2c 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72  , pointers retur
25c60 6e 65 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20  ned by prior.** 
25c70 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
25c80 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20  _column_blob(), 
25c90 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
25ca0 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a  ext(), and/or.**
25cb0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
25cc0 74 65 78 74 31 36 28 29 20 6d 61 79 20 62 65 20  text16() may be 
25cd0 69 6e 76 61 6c 69 64 61 74 65 64 2e 20 0a 2a 2a  invalidated. .**
25ce0 20 54 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   Type conversion
25cf0 73 20 61 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e  s and pointer in
25d00 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67 68  validations migh
25d10 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68  t occur.** in th
25d20 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65  e following case
25d30 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
25d40 20 3c 6c 69 3e 3c 70 3e 20 20 54 68 65 20 69 6e   <li><p>  The in
25d50 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73  itial content is
25d60 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69   a BLOB and sqli
25d70 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
25d80 29 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  ) .**          o
25d90 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  r sqlite3_column
25da0 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c  _text16() is cal
25db0 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72  led.  A zero-ter
25dc0 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a  minator might.**
25dd0 20 20 20 20 20 20 20 20 20 20 6e 65 65 64 20 74            need t
25de0 6f 20 62 65 20 61 64 64 65 64 20 74 6f 20 74 68  o be added to th
25df0 65 20 73 74 72 69 6e 67 2e 3c 2f 70 3e 3c 2f 6c  e string.</p></l
25e00 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 3c 70 3e  i>.**.** <li><p>
25e10 20 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f    The initial co
25e20 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74  ntent is UTF-8 t
25e30 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  ext and sqlite3_
25e40 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
25e50 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   or.**          
25e60 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
25e70 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65  ext16() is calle
25e80 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20  d.  The content 
25e90 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65  must be converte
25ea0 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f  d.**          to
25eb0 20 55 54 46 2d 31 36 2e 3c 2f 70 3e 3c 2f 6c 69   UTF-16.</p></li
25ec0 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 3c 70 3e 20  >.**.** <li><p> 
25ed0 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e   The initial con
25ee0 74 65 6e 74 20 69 73 20 55 54 46 2d 31 36 20 74  tent is UTF-16 t
25ef0 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  ext and sqlite3_
25f00 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f  column_bytes() o
25f10 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 71  r.**          sq
25f20 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
25f30 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  t() is called.  
25f40 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74  The content must
25f50 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a   be converted.**
25f60 20 20 20 20 20 20 20 20 20 20 74 6f 20 55 54 46            to UTF
25f70 2d 38 2e 3c 2f 70 3e 3c 2f 6c 69 3e 0a 2a 2a 20  -8.</p></li>.** 
25f80 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 43 6f 6e 76  </ul>.**.** Conv
25f90 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20  ersions between 
25fa0 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46  UTF-16be and UTF
25fb0 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73  -16le are always
25fc0 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61   done in place a
25fd0 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76  nd do.** not inv
25fe0 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72 20  alidate a prior 
25ff0 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20  pointer, though 
26000 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f  of course the co
26010 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66  ntent of the buf
26020 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20  fer.** that the 
26030 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 70 6f  prior pointer po
26040 69 6e 74 73 20 74 6f 20 77 69 6c 6c 20 68 61 76  ints to will hav
26050 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e  e been modified.
26060 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a    Other kinds.**
26070 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61   of conversion a
26080 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65  re done in place
26090 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73 73   when it is poss
260a0 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 69  ible, but someti
260b0 6d 65 20 69 74 20 69 73 0a 2a 2a 20 6e 6f 74 20  me it is.** not 
260c0 70 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e 20  possible and in 
260d0 74 68 6f 73 65 20 63 61 73 65 73 20 70 72 69 6f  those cases prio
260e0 72 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20 69  r pointers are i
260f0 6e 76 61 6c 69 64 61 74 65 64 2e 20 20 0a 2a 2a  nvalidated.  .**
26100 0a 2a 2a 20 54 68 65 20 73 61 66 65 73 74 20 61  .** The safest a
26110 6e 64 20 65 61 73 69 65 73 74 20 74 6f 20 72 65  nd easiest to re
26120 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79 20 69 73  member policy is
26130 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65   to invoke these
26140 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20   routines.** in 
26150 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f  one of the follo
26160 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a  wing ways:.**.**
26170 20 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73    <ul>.**  <li>s
26180 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
26190 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79  xt() followed by
261a0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
261b0 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20  bytes()</li>.** 
261c0 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c   <li>sqlite3_col
261d0 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f  umn_blob() follo
261e0 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  wed by sqlite3_c
261f0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c  olumn_bytes()</l
26200 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74  i>.**  <li>sqlit
26210 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
26220 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73  () followed by s
26230 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
26240 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20  tes16()</li>.** 
26250 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20   </ul>.**.** In 
26260 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f 75  other words, you
26270 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c   should call sql
26280 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
26290 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  (), sqlite3_colu
262a0 6d 6e 5f 62 6c 6f 62 28 29 2c 0a 2a 2a 20 6f 72  mn_blob(),.** or
262b0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
262c0 74 65 78 74 31 36 28 29 20 66 69 72 73 74 20 74  text16() first t
262d0 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65 73 75  o force the resu
262e0 6c 74 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69  lt into the desi
262f0 72 65 64 0a 2a 2a 20 66 6f 72 6d 61 74 2c 20 74  red.** format, t
26300 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  hen invoke sqlit
26310 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
26320 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ) or sqlite3_col
26330 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f  umn_bytes16() to
26340 0a 2a 2a 20 66 69 6e 64 20 74 68 65 20 73 69 7a  .** find the siz
26350 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e  e of the result.
26360 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c    Do not mix cal
26370 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  l to sqlite3_col
26380 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a  umn_text() or.**
26390 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
263a0 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61 6c 6c  blob() with call
263b0 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  s to sqlite3_col
263c0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2e 20 20  umn_bytes16().  
263d0 41 6e 64 20 64 6f 20 6e 6f 74 0a 2a 2a 20 6d 69  And do not.** mi
263e0 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  x calls to sqlit
263f0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
26400 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f  () with calls to
26410 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
26420 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 54  bytes()..**.** T
26430 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75  he pointers retu
26440 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20 75  rned are valid u
26450 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e 76  ntil a type conv
26460 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 73  ersion occurs as
26470 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61 62  .** described ab
26480 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73  ove, or until [s
26490 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f  qlite3_step()] o
264a0 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  r [sqlite3_reset
264b0 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
264c0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69  e3_finalize()] i
264d0 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 6d  s called.  The m
264e0 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73 65 64  emory space used
264f0 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 73   to hold strings
26500 0a 2a 2a 20 61 6e 64 20 62 6c 6f 62 73 20 69 73  .** and blobs is
26510 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63   freed automatic
26520 61 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74  ally.  Do <b>not
26530 3c 2f 62 3e 20 70 61 73 73 20 74 68 65 20 70 6f  </b> pass the po
26540 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 0a  inters returned.
26550 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
26560 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c  mn_blob()], [sql
26570 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
26580 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 20 0a  ()], etc. into .
26590 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ** [sqlite3_free
265a0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20  ()]..**.** If a 
265b0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
265c0 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64  n error occurs d
265d0 75 72 69 6e 67 20 74 68 65 20 65 76 61 6c 75 61  uring the evalua
265e0 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f  tion of any.** o
265f0 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
26600 2c 20 61 20 64 65 66 61 75 6c 74 20 76 61 6c 75  , a default valu
26610 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  e is returned.  
26620 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75  The default valu
26630 65 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 74  e.** is either t
26640 68 65 20 69 6e 74 65 67 65 72 20 30 2c 20 74 68  he integer 0, th
26650 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  e floating point
26660 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20   number 0.0, or 
26670 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65  a NULL.** pointe
26680 72 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 63  r.  Subsequent c
26690 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
266a0 5f 65 72 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c  _errcode()] will
266b0 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49   return.** [SQLI
266c0 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a  TE_NOMEM]..**.**
266d0 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
266e0 2a 2a 20 7b 46 31 33 38 30 33 7d 20 54 68 65 20  ** {F13803} The 
266f0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
26700 62 6c 6f 62 28 53 2c 4e 29 5d 20 69 6e 74 65 72  blob(S,N)] inter
26710 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68  face converts th
26720 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74  e.**          Nt
26730 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20  h column in the 
26740 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74  current row of t
26750 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f  he result set fo
26760 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  r.**          [p
26770 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
26780 74 5d 20 53 20 69 6e 74 6f 20 61 20 62 6c 6f 62  t] S into a blob
26790 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e   and then return
267a0 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  s a.**          
267b0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 63  pointer to the c
267c0 6f 6e 76 65 72 74 65 64 20 76 61 6c 75 65 2e 0a  onverted value..
267d0 2a 2a 0a 2a 2a 20 7b 46 31 33 38 30 36 7d 20 54  **.** {F13806} T
267e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
267f0 6d 6e 5f 62 79 74 65 73 28 53 2c 4e 29 5d 20 69  mn_bytes(S,N)] i
26800 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
26810 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
26820 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
26830 20 69 6e 20 74 68 65 20 62 6c 6f 62 20 6f 72 20   in the blob or 
26840 73 74 72 69 6e 67 20 28 65 78 63 6c 75 73 69 76  string (exclusiv
26850 65 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20  e of the.**     
26860 20 20 20 20 20 7a 65 72 6f 20 74 65 72 6d 69 6e       zero termin
26870 61 74 6f 72 20 6f 6e 20 74 68 65 20 73 74 72 69  ator on the stri
26880 6e 67 29 20 74 68 61 74 20 77 61 73 20 72 65 74  ng) that was ret
26890 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20  urned by the.** 
268a0 20 20 20 20 20 20 20 20 20 6d 6f 73 74 20 72 65           most re
268b0 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  cent call to [sq
268c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
268d0 62 28 53 2c 4e 29 5d 20 6f 72 0a 2a 2a 20 20 20  b(S,N)] or.**   
268e0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
268f0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 53 2c 4e 29  column_text(S,N)
26900 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 30 39  ]..**.** {F13809
26910 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
26920 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 53 2c  olumn_bytes16(S,
26930 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  N)] interface re
26940 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20  turns the.**    
26950 20 20 20 20 20 20 6e 75 6d 62 65 72 20 6f 66 20        number of 
26960 62 79 74 65 73 20 69 6e 20 74 68 65 20 73 74 72  bytes in the str
26970 69 6e 67 20 28 65 78 63 6c 75 73 69 76 65 20 6f  ing (exclusive o
26980 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  f the.**        
26990 20 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f    zero terminato
269a0 72 20 6f 6e 20 74 68 65 20 73 74 72 69 6e 67 29  r on the string)
269b0 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e   that was return
269c0 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 20 20 20  ed by the.**    
269d0 20 20 20 20 20 20 6d 6f 73 74 20 72 65 63 65 6e        most recen
269e0 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
269f0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
26a00 28 53 2c 4e 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46  (S,N)]..**.** {F
26a10 31 33 38 31 32 7d 20 54 68 65 20 5b 73 71 6c 69  13812} The [sqli
26a20 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c  te3_column_doubl
26a30 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63  e(S,N)] interfac
26a40 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a  e converts the.*
26a50 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 63  *          Nth c
26a60 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72  olumn in the cur
26a70 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20  rent row of the 
26a80 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72 0a 2a  result set for.*
26a90 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70  *          [prep
26aa0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
26ab0 53 20 69 6e 74 6f 20 61 20 66 6c 6f 61 74 69 6e  S into a floatin
26ac0 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 61 6e  g point value an
26ad0 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  d.**          re
26ae0 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 20  turns a copy of 
26af0 74 68 61 74 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a  that value..**.*
26b00 2a 20 7b 46 31 33 38 31 35 7d 20 54 68 65 20 5b  * {F13815} The [
26b10 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69  sqlite3_column_i
26b20 6e 74 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61  nt(S,N)] interfa
26b30 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a  ce converts the.
26b40 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20  **          Nth 
26b50 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75  column in the cu
26b60 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65  rrent row of the
26b70 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72 0a   result set for.
26b80 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65  **          [pre
26b90 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
26ba0 20 53 20 69 6e 74 6f 20 61 20 36 34 2d 62 69 74   S into a 64-bit
26bb0 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20   signed integer 
26bc0 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  and.**          
26bd0 72 65 74 75 72 6e 73 20 74 68 65 20 6c 6f 77 65  returns the lowe
26be0 72 20 33 32 20 62 69 74 73 20 6f 66 20 74 68 61  r 32 bits of tha
26bf0 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a  t integer..**.**
26c00 20 7b 46 31 33 38 31 38 7d 20 54 68 65 20 5b 73   {F13818} The [s
26c10 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e  qlite3_column_in
26c20 74 36 34 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66  t64(S,N)] interf
26c30 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65  ace converts the
26c40 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68  .**          Nth
26c50 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63   column in the c
26c60 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68  urrent row of th
26c70 65 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72  e result set for
26c80 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
26c90 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
26ca0 5d 20 53 20 69 6e 74 6f 20 61 20 36 34 2d 62 69  ] S into a 64-bi
26cb0 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
26cc0 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20   and.**         
26cd0 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20   returns a copy 
26ce0 6f 66 20 74 68 61 74 20 69 6e 74 65 67 65 72 2e  of that integer.
26cf0 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 32 31 7d 20  .**.** {F13821} 
26d00 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  The [sqlite3_col
26d10 75 6d 6e 5f 74 65 78 74 28 53 2c 4e 29 5d 20 69  umn_text(S,N)] i
26d20 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74  nterface convert
26d30 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
26d40 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20    Nth column in 
26d50 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20  the current row 
26d60 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
26d70 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  t for.**        
26d80 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74    [prepared stat
26d90 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20  ement] S into a 
26da0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
26db0 55 54 46 2d 38 20 0a 2a 2a 20 20 20 20 20 20 20  UTF-8 .**       
26dc0 20 20 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65     string and re
26dd0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
26de0 74 6f 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a  to that string..
26df0 2a 2a 0a 2a 2a 20 7b 46 31 33 38 32 34 7d 20 54  **.** {F13824} T
26e00 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
26e10 6d 6e 5f 74 65 78 74 31 36 28 53 2c 4e 29 5d 20  mn_text16(S,N)] 
26e20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72  interface conver
26e30 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ts the.**       
26e40 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e     Nth column in
26e50 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77   the current row
26e60 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
26e70 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20  et for.**       
26e80 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61     [prepared sta
26e90 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61  tement] S into a
26ea0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
26eb0 20 32 2d 62 79 74 65 0a 2a 2a 20 20 20 20 20 20   2-byte.**      
26ec0 20 20 20 20 61 6c 69 67 6e 65 64 20 55 54 46 2d      aligned UTF-
26ed0 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  16 native byte o
26ee0 72 64 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  rder.**         
26ef0 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75   string and retu
26f00 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
26f10 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a   that string..**
26f20 0a 2a 2a 20 7b 46 31 33 38 32 37 7d 20 54 68 65  .** {F13827} The
26f30 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
26f40 5f 74 79 70 65 28 53 2c 4e 29 5d 20 69 6e 74 65  _type(S,N)] inte
26f50 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a  rface returns.**
26f60 20 20 20 20 20 20 20 20 20 20 6f 6e 65 20 6f 66            one of
26f70 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2c 20   [SQLITE_NULL], 
26f80 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d  [SQLITE_INTEGER]
26f90 2c 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d  , [SQLITE_FLOAT]
26fa0 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53  ,.**          [S
26fb0 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 6f 72 20  QLITE_TEXT], or 
26fc0 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 20 61 73  [SQLITE_BLOB] as
26fd0 20 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72   appropriate for
26fe0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
26ff0 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74   Nth column in t
27000 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f  he current row o
27010 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
27020 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20   for.**         
27030 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
27040 6d 65 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b  ment] S..**.** {
27050 46 31 33 38 33 30 7d 20 54 68 65 20 5b 73 71 6c  F13830} The [sql
27060 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
27070 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63  e(S,N)] interfac
27080 65 20 72 65 74 75 72 6e 73 20 61 0a 2a 2a 20 20  e returns a.**  
27090 20 20 20 20 20 20 20 20 70 6f 69 6e 74 65 72 20          pointer 
270a0 74 6f 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74  to an [unprotect
270b0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
270c0 5d 20 6f 62 6a 65 63 74 20 66 6f 72 20 74 68 65  ] object for the
270d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68  .**          Nth
270e0 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63   column in the c
270f0 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68  urrent row of th
27100 65 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72  e result set for
27110 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
27120 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
27130 5d 20 53 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f  ] S..*/.const vo
27140 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
27150 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  mn_blob(sqlite3_
27160 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
27170 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
27180 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74  lumn_bytes(sqlit
27190 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
271a0 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ol);.int sqlite3
271b0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
271c0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
271d0 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65  nt iCol);.double
271e0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
271f0 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73  double(sqlite3_s
27200 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
27210 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
27220 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  umn_int(sqlite3_
27230 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
27240 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  ;.sqlite3_int64 
27250 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69  sqlite3_column_i
27260 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d  nt64(sqlite3_stm
27270 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63  t*, int iCol);.c
27280 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68  onst unsigned ch
27290 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
272a0 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f  mn_text(sqlite3_
272b0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
272c0 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
272d0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
272e0 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t16(sqlite3_stmt
272f0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e  *, int iCol);.in
27300 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
27310 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74  _type(sqlite3_st
27320 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
27330 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73  sqlite3_value *s
27340 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
27350 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lue(sqlite3_stmt
27360 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f  *, int iCol);../
27370 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
27380 65 73 74 72 6f 79 20 41 20 50 72 65 70 61 72 65  estroy A Prepare
27390 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65  d Statement Obje
273a0 63 74 20 7b 46 31 33 33 30 30 7d 0a 2a 2a 0a 2a  ct {F13300}.**.*
273b0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69  * The sqlite3_fi
273c0 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69 6f  nalize() functio
273d0 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 64  n is called to d
273e0 65 6c 65 74 65 20 61 20 0a 2a 2a 20 5b 70 72 65  elete a .** [pre
273f0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
27400 2e 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65  . If the stateme
27410 6e 74 20 77 61 73 0a 2a 2a 20 65 78 65 63 75 74  nt was.** execut
27420 65 64 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c  ed successfully,
27430 20 6f 72 20 6e 6f 74 20 65 78 65 63 75 74 65 64   or not executed
27440 20 61 74 20 61 6c 6c 2c 20 74 68 65 6e 20 53 51   at all, then SQ
27450 4c 49 54 45 5f 4f 4b 20 69 73 20 72 65 74 75 72  LITE_OK is retur
27460 6e 65 64 2e 0a 2a 2a 20 49 66 20 65 78 65 63 75  ned..** If execu
27470 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 74  tion of the stat
27480 65 6d 65 6e 74 20 66 61 69 6c 65 64 20 74 68 65  ement failed the
27490 6e 20 61 6e 20 0a 2a 2a 20 5b 65 72 72 6f 72 20  n an .** [error 
274a0 63 6f 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64  code] or [extend
274b0 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 0a 2a  ed error code].*
274c0 2a 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 0a  * is returned. .
274d0 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
274e0 6e 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64  ne can be called
274f0 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 75   at any point du
27500 72 69 6e 67 20 74 68 65 20 65 78 65 63 75 74 69  ring the executi
27510 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 70 72  on of the.** [pr
27520 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
27530 5d 2e 20 20 49 66 20 74 68 65 20 76 69 72 74 75  ].  If the virtu
27540 61 6c 20 6d 61 63 68 69 6e 65 20 68 61 73 20 6e  al machine has n
27550 6f 74 20 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64  ot .** completed
27560 20 65 78 65 63 75 74 69 6f 6e 20 77 68 65 6e 20   execution when 
27570 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  this routine is 
27580 63 61 6c 6c 65 64 2c 20 74 68 61 74 20 69 73 20  called, that is 
27590 6c 69 6b 65 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65  like.** encounte
275a0 72 69 6e 67 20 61 6e 20 65 72 72 6f 72 20 6f 72  ring an error or
275b0 20 61 6e 20 69 6e 74 65 72 72 75 70 74 2e 20 20   an interrupt.  
275c0 28 53 65 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e  (See [sqlite3_in
275d0 74 65 72 72 75 70 74 28 29 5d 2e 29 20 0a 2a 2a  terrupt()].) .**
275e0 20 49 6e 63 6f 6d 70 6c 65 74 65 20 75 70 64 61   Incomplete upda
275f0 74 65 73 20 6d 61 79 20 62 65 20 72 6f 6c 6c 65  tes may be rolle
27600 64 20 62 61 63 6b 20 61 6e 64 20 74 72 61 6e 73  d back and trans
27610 61 63 74 69 6f 6e 73 20 63 61 6e 63 65 6c 65 64  actions canceled
27620 2c 20 20 0a 2a 2a 20 64 65 70 65 6e 64 69 6e 67  ,  .** depending
27630 20 6f 6e 20 74 68 65 20 63 69 72 63 75 6d 73 74   on the circumst
27640 61 6e 63 65 73 2c 20 61 6e 64 20 74 68 65 20 0a  ances, and the .
27650 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  ** [error code] 
27660 72 65 74 75 72 6e 65 64 20 77 69 6c 6c 20 62 65  returned will be
27670 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e   [SQLITE_ABORT].
27680 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
27690 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 33 30 32  S:.**.** {F11302
276a0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  } The [sqlite3_f
276b0 69 6e 61 6c 69 7a 65 28 53 29 5d 20 69 6e 74 65  inalize(S)] inte
276c0 72 66 61 63 65 20 64 65 73 74 72 6f 79 73 20 74  rface destroys t
276d0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
276e0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
276f0 6e 74 5d 20 53 20 61 6e 64 20 72 65 6c 65 61 73  nt] S and releas
27700 65 73 20 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20  es all.**       
27710 20 20 20 6d 65 6d 6f 72 79 20 61 6e 64 20 66 69     memory and fi
27720 6c 65 20 72 65 73 6f 75 72 63 65 73 20 68 65 6c  le resources hel
27730 64 20 62 79 20 74 68 61 74 20 6f 62 6a 65 63 74  d by that object
27740 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 33 30 34 7d  ..**.** {F11304}
27750 20 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63   If the most rec
27760 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ent call to [sql
27770 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f  ite3_step(S)] fo
27780 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  r the.**        
27790 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74    [prepared stat
277a0 65 6d 65 6e 74 5d 20 53 20 72 65 74 75 72 6e 65  ement] S returne
277b0 64 20 61 6e 20 65 72 72 6f 72 2c 0a 2a 2a 20 20  d an error,.**  
277c0 20 20 20 20 20 20 20 20 74 68 65 6e 20 5b 73 71          then [sq
277d0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53  lite3_finalize(S
277e0 29 5d 20 72 65 74 75 72 6e 73 20 74 68 61 74 20  )] returns that 
277f0 73 61 6d 65 20 65 72 72 6f 72 2e 0a 2a 2f 0a 69  same error..*/.i
27800 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  nt sqlite3_final
27810 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ize(sqlite3_stmt
27820 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
27830 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74   CAPI3REF: Reset
27840 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74   A Prepared Stat
27850 65 6d 65 6e 74 20 4f 62 6a 65 63 74 20 7b 46 31  ement Object {F1
27860 33 33 33 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20  3330}.**.** The 
27870 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 20  sqlite3_reset() 
27880 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c  function is call
27890 65 64 20 74 6f 20 72 65 73 65 74 20 61 20 0a 2a  ed to reset a .*
278a0 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
278b0 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 2e 0a 2a  ement] object..*
278c0 2a 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e  * back to its in
278d0 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65 61  itial state, rea
278e0 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65 63  dy to be re-exec
278f0 75 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 53 51 4c  uted..** Any SQL
27900 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69 61   statement varia
27910 62 6c 65 73 20 74 68 61 74 20 68 61 64 20 76 61  bles that had va
27920 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74 68  lues bound to th
27930 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20  em using.** the 
27940 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
27950 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e  ob | sqlite3_bin
27960 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61 69  d_*() API] retai
27970 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e 0a  n their values..
27980 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33 5f  ** Use [sqlite3_
27990 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 29  clear_bindings()
279a0 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 62  ] to reset the b
279b0 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 7b  indings..**.** {
279c0 46 31 31 33 33 32 7d 20 54 68 65 20 5b 73 71 6c  F11332} The [sql
279d0 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69  ite3_reset(S)] i
279e0 6e 74 65 72 66 61 63 65 20 72 65 73 65 74 73 20  nterface resets 
279f0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
27a00 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 20 20  atement] S.**   
27a10 20 20 20 20 20 20 20 62 61 63 6b 20 74 6f 20 74         back to t
27a20 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20  he beginning of 
27a30 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a  its program..**.
27a40 2a 2a 20 7b 46 31 31 33 33 34 7d 20 49 66 20 74  ** {F11334} If t
27a50 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63  he most recent c
27a60 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
27a70 73 74 65 70 28 53 29 5d 20 66 6f 72 20 0a 2a 2a  step(S)] for .**
27a80 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61            [prepa
27a90 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
27aa0 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54   returned [SQLIT
27ab0 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54  E_ROW] or [SQLIT
27ac0 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 20 20 20 20  E_DONE],.**     
27ad0 20 20 20 20 20 6f 72 20 69 66 20 5b 73 71 6c 69       or if [sqli
27ae0 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73  te3_step(S)] has
27af0 20 6e 65 76 65 72 20 62 65 66 6f 72 65 20 62 65   never before be
27b00 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a  en called on S,.
27b10 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e  **          then
27b20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
27b30 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  S)] returns [SQL
27b40 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  ITE_OK]..**.** {
27b50 46 31 31 33 33 36 7d 20 49 66 20 74 68 65 20 6d  F11336} If the m
27b60 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
27b70 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
27b80 28 53 29 5d 20 66 6f 72 0a 2a 2a 20 20 20 20 20  (S)] for.**     
27b90 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73       [prepared s
27ba0 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69  tatement] S indi
27bb0 63 61 74 65 64 20 61 6e 20 65 72 72 6f 72 2c 20  cated an error, 
27bc0 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  then.**         
27bd0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
27be0 53 29 5d 20 72 65 74 75 72 6e 73 20 61 6e 20 61  S)] returns an a
27bf0 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f  ppropriate [erro
27c00 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  r code]..**.** {
27c10 46 31 31 33 33 38 7d 20 54 68 65 20 5b 73 71 6c  F11338} The [sql
27c20 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69  ite3_reset(S)] i
27c30 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f  nterface does no
27c40 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c  t change the val
27c50 75 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ues.**          
27c60 6f 66 20 61 6e 79 20 5b 73 71 6c 69 74 65 33 5f  of any [sqlite3_
27c70 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e  bind_blob|bindin
27c80 67 73 5d 20 6f 6e 20 5b 70 72 65 70 61 72 65 64  gs] on [prepared
27c90 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a   statement] S..*
27ca0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65  /.int sqlite3_re
27cb0 73 65 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  set(sqlite3_stmt
27cc0 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
27cd0 20 43 41 50 49 33 52 45 46 3a 20 43 72 65 61 74   CAPI3REF: Creat
27ce0 65 20 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51  e Or Redefine SQ
27cf0 4c 20 46 75 6e 63 74 69 6f 6e 73 20 7b 46 31 36  L Functions {F16
27d00 31 30 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  100}.** KEYWORDS
27d10 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65 61  : {function crea
27d20 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 20 0a  tion routines} .
27d30 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 74 77 6f 20  **.** These two 
27d40 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65  functions (colle
27d50 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73  ctively known as
27d60 0a 2a 2a 20 22 66 75 6e 63 74 69 6f 6e 20 63 72  .** "function cr
27d70 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22  eation routines"
27d80 29 20 61 72 65 20 75 73 65 64 20 74 6f 20 61 64  ) are used to ad
27d90 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  d SQL functions 
27da0 6f 72 20 61 67 67 72 65 67 61 74 65 73 0a 2a 2a  or aggregates.**
27db0 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65 20   or to redefine 
27dc0 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20  the behavior of 
27dd0 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e  existing SQL fun
27de0 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67  ctions or aggreg
27df0 61 74 65 73 2e 20 20 54 68 65 0a 2a 2a 20 64 69  ates.  The.** di
27e00 66 66 65 72 65 6e 63 65 20 6f 6e 6c 79 20 62 65  fference only be
27e10 74 77 65 65 6e 20 74 68 65 20 74 77 6f 20 69 73  tween the two is
27e20 20 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e 64   that the second
27e30 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 0a   parameter, the.
27e40 2a 2a 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 28  ** name of the (
27e50 73 63 61 6c 61 72 29 20 66 75 6e 63 74 69 6f 6e  scalar) function
27e60 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20 69   or aggregate, i
27e70 73 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54 46  s encoded in UTF
27e80 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  -8 for.** sqlite
27e90 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
27ea0 6e 28 29 20 61 6e 64 20 55 54 46 2d 31 36 20 66  n() and UTF-16 f
27eb0 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  or sqlite3_creat
27ec0 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 2e 0a  e_function16()..
27ed0 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
27ee0 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
27ef0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
27f00 63 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20  ction] to which 
27f10 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74  the SQL.** funct
27f20 69 6f 6e 20 69 73 20 74 6f 20 62 65 20 61 64 64  ion is to be add
27f30 65 64 2e 20 20 49 66 20 61 20 73 69 6e 67 6c 65  ed.  If a single
27f40 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 65 73  .** program uses
27f50 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 5b   more than one [
27f60 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
27f70 69 6f 6e 5d 20 69 6e 74 65 72 6e 61 6c 6c 79 2c  ion] internally,
27f80 20 74 68 65 6e 20 53 51 4c 0a 2a 2a 20 66 75 6e   then SQL.** fun
27f90 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 61  ctions must be a
27fa0 64 64 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c  dded individuall
27fb0 79 20 74 6f 20 65 61 63 68 20 5b 64 61 74 61 62  y to each [datab
27fc0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
27fd0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  .**.** The secon
27fe0 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  d parameter is t
27ff0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53  he name of the S
28000 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  QL function to b
28010 65 20 63 72 65 61 74 65 64 0a 2a 2a 20 6f 72 20  e created.** or 
28020 72 65 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68  redefined..** Th
28030 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20  e length of the 
28040 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20  name is limited 
28050 74 6f 20 32 35 35 20 62 79 74 65 73 2c 20 65 78  to 255 bytes, ex
28060 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65 20 0a  clusive of the .
28070 2a 2a 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  ** zero-terminat
28080 6f 72 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74  or.  Note that t
28090 68 65 20 6e 61 6d 65 20 6c 65 6e 67 74 68 20 6c  he name length l
280a0 69 6d 69 74 20 69 73 20 69 6e 20 62 79 74 65 73  imit is in bytes
280b0 2c 20 6e 6f 74 0a 2a 2a 20 63 68 61 72 61 63 74  , not.** charact
280c0 65 72 73 2e 20 20 41 6e 79 20 61 74 74 65 6d 70  ers.  Any attemp
280d0 74 20 74 6f 20 63 72 65 61 74 65 20 61 20 66 75  t to create a fu
280e0 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f  nction with a lo
280f0 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c  nger name.** wil
28100 6c 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20 53  l result in an S
28110 51 4c 49 54 45 5f 45 52 52 4f 52 20 65 72 72 6f  QLITE_ERROR erro
28120 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69  r..**.** The thi
28130 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  rd parameter is 
28140 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72  the number of ar
28150 67 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68 65  guments that the
28160 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
28170 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74 61  .** aggregate ta
28180 6b 65 73 2e 20 49 66 20 74 68 69 73 20 70 61 72  kes. If this par
28190 61 6d 65 74 65 72 20 69 73 20 6e 65 67 61 74 69  ameter is negati
281a0 76 65 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c  ve, then the SQL
281b0 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20   function or.** 
281c0 61 67 67 72 65 67 61 74 65 20 6d 61 79 20 74 61  aggregate may ta
281d0 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66  ke any number of
281e0 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a   arguments..**.*
281f0 2a 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72  * The fourth par
28200 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65 70  ameter, eTextRep
28210 2c 20 73 70 65 63 69 66 69 65 73 20 77 68 61 74  , specifies what
28220 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46   .** [SQLITE_UTF
28230 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  8 | text encodin
28240 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63  g] this SQL func
28250 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72  tion prefers for
28260 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65  .** its paramete
28270 72 73 2e 20 20 41 6e 79 20 53 51 4c 20 66 75 6e  rs.  Any SQL fun
28280 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
28290 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20 61  tion should be a
282a0 62 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77  ble to work.** w
282b0 6f 72 6b 20 77 69 74 68 20 55 54 46 2d 38 2c 20  ork with UTF-8, 
282c0 55 54 46 2d 31 36 6c 65 2c 20 6f 72 20 55 54 46  UTF-16le, or UTF
282d0 2d 31 36 62 65 2e 20 20 42 75 74 20 73 6f 6d 65  -16be.  But some
282e0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
282f0 20 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f 72 65 20   may be.** more 
28300 65 66 66 69 63 69 65 6e 74 20 77 69 74 68 20 6f  efficient with o
28310 6e 65 20 65 6e 63 6f 64 69 6e 67 20 74 68 61 6e  ne encoding than
28320 20 61 6e 6f 74 68 65 72 2e 20 20 49 74 20 69 73   another.  It is
28330 20 61 6c 6c 6f 77 65 64 20 74 6f 0a 2a 2a 20 69   allowed to.** i
28340 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 72  nvoke sqlite3_cr
28350 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20  eate_function() 
28360 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  or sqlite3_creat
28370 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 20 6d  e_function16() m
28380 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 73  ultiple.** times
28390 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 66   with the same f
283a0 75 6e 63 74 69 6f 6e 20 62 75 74 20 77 69 74 68  unction but with
283b0 20 64 69 66 66 65 72 65 6e 74 20 76 61 6c 75 65   different value
283c0 73 20 6f 66 20 65 54 65 78 74 52 65 70 2e 0a 2a  s of eTextRep..*
283d0 2a 20 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20  * When multiple 
283e0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
283f0 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63  of the same func
28400 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62  tion are availab
28410 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69  le, SQLite.** wi
28420 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20  ll pick the one 
28430 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68  that involves th
28440 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f  e least amount o
28450 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f  f data conversio
28460 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 72 65 20 69  n..** If there i
28470 73 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20  s only a single 
28480 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
28490 68 69 63 68 20 64 6f 65 73 20 6e 6f 74 20 63 61  hich does not ca
284a0 72 65 20 77 68 61 74 0a 2a 2a 20 74 65 78 74 20  re what.** text 
284b0 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64  encoding is used
284c0 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74  , then the fourt
284d0 68 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  h argument shoul
284e0 64 20 62 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  d be.** [SQLITE_
284f0 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ANY]..**.** The 
28500 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20  fifth parameter 
28510 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 20  is an arbitrary 
28520 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d  pointer.  The im
28530 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20  plementation.** 
28540 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  of the function 
28550 63 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20  can gain access 
28560 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20  to this pointer 
28570 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
28580 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e 0a  3_user_data()]..
28590 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 76 65 6e 74  **.** The sevent
285a0 68 2c 20 65 69 67 68 74 68 20 61 6e 64 20 6e 69  h, eighth and ni
285b0 6e 74 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20  nth parameters, 
285c0 78 46 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64  xFunc, xStep and
285d0 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20   xFinal, are.** 
285e0 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61  pointers to C-la
285f0 6e 67 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73  nguage functions
28600 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20   that implement 
28610 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74  the SQL.** funct
28620 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65  ion or aggregate
28630 2e 20 41 20 73 63 61 6c 61 72 20 53 51 4c 20 66  . A scalar SQL f
28640 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73  unction requires
28650 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69   an implementati
28660 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 20 78 46 75  on of.** the xFu
28670 6e 63 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79  nc callback only
28680 2c 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20  , NULL pointers 
28690 73 68 6f 75 6c 64 20 62 65 20 70 61 73 73 65 64  should be passed
286a0 20 61 73 20 74 68 65 20 78 53 74 65 70 0a 2a 2a   as the xStep.**
286b0 20 61 6e 64 20 78 46 69 6e 61 6c 20 70 61 72 61   and xFinal para
286c0 6d 65 74 65 72 73 2e 20 41 6e 20 61 67 67 72 65  meters. An aggre
286d0 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  gate SQL functio
286e0 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d  n requires an im
286f0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20  plementation.** 
28700 6f 66 20 78 53 74 65 70 20 61 6e 64 20 78 46 69  of xStep and xFi
28710 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 73 68 6f  nal and NULL sho
28720 75 6c 64 20 62 65 20 70 61 73 73 65 64 20 66 6f  uld be passed fo
28730 72 20 78 46 75 6e 63 2e 20 54 6f 20 64 65 6c 65  r xFunc. To dele
28740 74 65 20 61 6e 0a 2a 2a 20 65 78 69 73 74 69 6e  te an.** existin
28750 67 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  g SQL function o
28760 72 20 61 67 67 72 65 67 61 74 65 2c 20 70 61 73  r aggregate, pas
28770 73 20 4e 55 4c 4c 20 66 6f 72 20 61 6c 6c 20 74  s NULL for all t
28780 68 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  hree function.**
28790 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a   callbacks..**.*
287a0 2a 20 49 74 20 69 73 20 70 65 72 6d 69 74 74 65  * It is permitte
287b0 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d 75  d to register mu
287c0 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  ltiple implement
287d0 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
287e0 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20  me.** functions 
287f0 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61  with the same na
28800 6d 65 20 62 75 74 20 77 69 74 68 20 65 69 74 68  me but with eith
28810 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75 6d  er differing num
28820 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d  bers of.** argum
28830 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69 6e  ents or differin
28840 67 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74  g preferred text
28850 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 53 51 4c   encodings.  SQL
28860 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20  ite will use.** 
28870 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
28880 6f 6e 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20  on most closely 
28890 6d 61 74 63 68 65 73 20 74 68 65 20 77 61 79 20  matches the way 
288a0 69 6e 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20  in which the.** 
288b0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  SQL function is 
288c0 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  used..**.** INVA
288d0 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  RIANTS:.**.** {F
288e0 31 36 31 30 33 7d 20 54 68 65 20 5b 73 71 6c 69  16103} The [sqli
288f0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
28900 69 6f 6e 31 36 28 29 5d 20 69 6e 74 65 72 66 61  ion16()] interfa
28910 63 65 20 62 65 68 61 76 65 73 20 65 78 61 63 74  ce behaves exact
28920 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6c  ly.**          l
28930 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  ike [sqlite3_cre
28940 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20  ate_function()] 
28950 69 6e 20 65 76 65 72 79 20 77 61 79 20 65 78 63  in every way exc
28960 65 70 74 20 74 68 61 74 20 69 74 0a 2a 2a 20 20  ept that it.**  
28970 20 20 20 20 20 20 20 20 69 6e 74 65 72 70 72 65          interpre
28980 74 73 20 74 68 65 20 7a 46 75 6e 63 74 69 6f 6e  ts the zFunction
28990 4e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 61 73  Name argument as
289a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72  .**          zer
289b0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
289c0 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20  -16 native byte 
289d0 6f 72 64 65 72 20 69 6e 73 74 65 61 64 20 6f 66  order instead of
289e0 20 61 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20   as a.**        
289f0 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65    zero-terminate
28a00 64 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b  d UTF-8..**.** {
28a10 46 31 36 31 30 36 7d 20 41 20 73 75 63 63 65 73  F16106} A succes
28a20 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20  sful invocation 
28a30 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  of.**          t
28a40 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  he [sqlite3_crea
28a50 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c  te_function(D,X,
28a60 4e 2c 45 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66  N,E,...)] interf
28a70 61 63 65 20 72 65 67 69 73 74 65 72 73 0a 2a 2a  ace registers.**
28a80 20 20 20 20 20 20 20 20 20 20 6f 72 20 72 65 70            or rep
28a90 6c 61 63 65 73 20 63 61 6c 6c 62 61 63 6b 20 66  laces callback f
28aa0 75 6e 63 74 69 6f 6e 73 20 69 6e 20 5b 64 61 74  unctions in [dat
28ab0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
28ac0 5d 20 44 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ] D.**          
28ad0 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  used to implemen
28ae0 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  t the SQL functi
28af0 6f 6e 20 6e 61 6d 65 64 20 58 20 77 69 74 68 20  on named X with 
28b00 4e 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20  N parameters.** 
28b10 20 20 20 20 20 20 20 20 20 61 6e 64 20 68 61 76           and hav
28b20 69 6e 67 20 61 20 70 72 65 66 65 72 72 65 64 20  ing a preferred 
28b30 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 6f 66  text encoding of
28b40 20 45 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 30   E..**.** {F1610
28b50 39 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20  9} A successful 
28b60 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
28b70 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
28b80 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c  (D,X,N,E,P,F,S,L
28b90 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  )].**          r
28ba0 65 70 6c 61 63 65 73 20 74 68 65 20 50 2c 20 46  eplaces the P, F
28bb0 2c 20 53 2c 20 61 6e 64 20 4c 20 76 61 6c 75 65  , S, and L value
28bc0 73 20 66 72 6f 6d 20 61 6e 79 20 70 72 69 6f 72  s from any prior
28bd0 20 63 61 6c 6c 73 20 77 69 74 68 0a 2a 2a 20 20   calls with.**  
28be0 20 20 20 20 20 20 20 20 74 68 65 20 73 61 6d 65          the same
28bf0 20 44 2c 20 58 2c 20 4e 2c 20 61 6e 64 20 45 20   D, X, N, and E 
28c00 76 61 6c 75 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46  values..**.** {F
28c10 31 36 31 31 32 7d 20 54 68 65 20 5b 73 71 6c 69  16112} The [sqli
28c20 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
28c30 69 6f 6e 28 44 2c 58 2c 2e 2e 2e 29 5d 20 69 6e  ion(D,X,...)] in
28c40 74 65 72 66 61 63 65 20 66 61 69 6c 73 20 77 69  terface fails wi
28c50 74 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  th.**          a
28c60 20 72 65 74 75 72 6e 20 63 6f 64 65 20 6f 66 20   return code of 
28c70 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69  [SQLITE_ERROR] i
28c80 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  f the SQL functi
28c90 6f 6e 20 6e 61 6d 65 20 58 20 69 73 0a 2a 2a 20  on name X is.** 
28ca0 20 20 20 20 20 20 20 20 20 6c 6f 6e 67 65 72 20           longer 
28cb0 74 68 61 6e 20 32 35 35 20 62 79 74 65 73 20 65  than 255 bytes e
28cc0 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65 20  xclusive of the 
28cd0 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e  zero terminator.
28ce0 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 31 38 7d 20  .**.** {F16118} 
28cf0 45 69 74 68 65 72 20 46 20 6d 75 73 74 20 62 65  Either F must be
28d00 20 4e 55 4c 4c 20 61 6e 64 20 53 20 61 6e 64 20   NULL and S and 
28d10 4c 20 61 72 65 20 6e 6f 6e 2d 4e 55 4c 4c 20 6f  L are non-NULL o
28d20 72 20 65 6c 73 65 20 46 0a 2a 2a 20 20 20 20 20  r else F.**     
28d30 20 20 20 20 20 69 73 20 6e 6f 6e 2d 4e 55 4c 4c       is non-NULL
28d40 20 61 6e 64 20 53 20 61 6e 64 20 4c 20 61 72 65   and S and L are
28d50 20 4e 55 4c 4c 2c 20 6f 74 68 65 72 77 69 73 65   NULL, otherwise
28d60 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
28d70 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
28d80 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c  ction(D,X,N,E,P,
28d90 46 2c 53 2c 4c 29 5d 20 72 65 74 75 72 6e 73 20  F,S,L)] returns 
28da0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 0a  [SQLITE_ERROR]..
28db0 2a 2a 0a 2a 2a 20 7b 46 31 36 31 32 31 7d 20 54  **.** {F16121} T
28dc0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  he [sqlite3_crea
28dd0 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 2e 2e  te_function(D,..
28de0 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 66 61  .)] interface fa
28df0 69 6c 73 20 77 69 74 68 20 61 6e 0a 2a 2a 20 20  ils with an.**  
28e00 20 20 20 20 20 20 20 20 65 72 72 6f 72 20 63 6f          error co
28e10 64 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 42 55  de of [SQLITE_BU
28e20 53 59 5d 20 69 66 20 74 68 65 72 65 20 65 78 69  SY] if there exi
28e30 73 74 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  st [prepared sta
28e40 74 65 6d 65 6e 74 73 5d 0a 2a 2a 20 20 20 20 20  tements].**     
28e50 20 20 20 20 20 61 73 73 6f 63 69 61 74 65 64 20       associated 
28e60 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61  with the [databa
28e70 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
28e80 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 32 34 7d  ..**.** {F16124}
28e90 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72   The [sqlite3_cr
28ea0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c  eate_function(D,
28eb0 58 2c 4e 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66  X,N,...)] interf
28ec0 61 63 65 20 66 61 69 6c 73 20 77 69 74 68 20 61  ace fails with a
28ed0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 72  n.**          er
28ee0 72 6f 72 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c  ror code of [SQL
28ef0 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 70 61  ITE_ERROR] if pa
28f00 72 61 6d 65 74 65 72 20 4e 20 28 73 70 65 63 69  rameter N (speci
28f10 66 79 69 6e 67 20 74 68 65 20 6e 75 6d 62 65 72  fying the number
28f20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20  .**          of 
28f30 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65  arguments to the
28f40 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 62 65   SQL function be
28f50 69 6e 67 20 72 65 67 69 73 74 65 72 65 64 29 20  ing registered) 
28f60 69 73 20 6c 65 73 73 0a 2a 2a 20 20 20 20 20 20  is less.**      
28f70 20 20 20 20 74 68 61 6e 20 2d 31 20 6f 72 20 67      than -1 or g
28f80 72 65 61 74 65 72 20 74 68 61 6e 20 31 32 37 2e  reater than 127.
28f90 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 32 37 7d 20  .**.** {F16127} 
28fa0 57 68 65 6e 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65  When N is non-ne
28fb0 67 61 74 69 76 65 2c 20 74 68 65 20 5b 73 71 6c  gative, the [sql
28fc0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
28fd0 74 69 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d  tion(D,X,N,...)]
28fe0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74  .**          int
28ff0 65 72 66 61 63 65 20 63 61 75 73 65 73 20 63 61  erface causes ca
29000 6c 6c 62 61 63 6b 73 20 74 6f 20 62 65 20 69 6e  llbacks to be in
29010 76 6f 6b 65 64 20 66 6f 72 20 74 68 65 20 53 51  voked for the SQ
29020 4c 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20  L function.**   
29030 20 20 20 20 20 20 20 6e 61 6d 65 64 20 58 20 77         named X w
29040 68 65 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  hen the number o
29050 66 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  f arguments to t
29060 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
29070 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65  is.**          e
29080 78 61 63 74 6c 79 20 4e 2e 0a 2a 2a 0a 2a 2a 20  xactly N..**.** 
29090 7b 46 31 36 31 33 30 7d 20 57 68 65 6e 20 4e 20  {F16130} When N 
290a0 69 73 20 2d 31 2c 20 74 68 65 20 5b 73 71 6c 69  is -1, the [sqli
290b0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
290c0 69 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d 0a  ion(D,X,N,...)].
290d0 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65  **          inte
290e0 72 66 61 63 65 20 63 61 75 73 65 73 20 63 61 6c  rface causes cal
290f0 6c 62 61 63 6b 73 20 74 6f 20 62 65 20 69 6e 76  lbacks to be inv
29100 6f 6b 65 64 20 66 6f 72 20 74 68 65 20 53 51 4c  oked for the SQL
29110 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20 20   function.**    
29120 20 20 20 20 20 20 6e 61 6d 65 64 20 58 20 77 69        named X wi
29130 74 68 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66  th any number of
29140 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a   arguments..**.*
29150 2a 20 7b 46 31 36 31 33 33 7d 20 57 68 65 6e 20  * {F16133} When 
29160 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
29170 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
29180 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a  n(D,X,N,...)].**
29190 20 20 20 20 20 20 20 20 20 20 73 70 65 63 69 66            specif
291a0 79 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65  y multiple imple
291b0 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68  mentations of th
291c0 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20  e same function 
291d0 58 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e  X.**          an
291e0 64 20 77 68 65 6e 20 6f 6e 65 20 69 6d 70 6c 65  d when one imple
291f0 6d 65 6e 74 61 74 69 6f 6e 20 68 61 73 20 4e 3e  mentation has N>
29200 3d 30 20 61 6e 64 20 74 68 65 20 6f 74 68 65 72  =0 and the other
29210 20 68 61 73 20 4e 3d 28 2d 31 29 0a 2a 2a 20 20   has N=(-1).**  
29220 20 20 20 20 20 20 20 20 74 68 65 20 69 6d 70 6c          the impl
29230 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20  ementation with 
29240 61 20 6e 6f 6e 2d 7a 65 72 6f 20 4e 20 69 73 20  a non-zero N is 
29250 70 72 65 66 65 72 72 65 64 2e 0a 2a 2a 0a 2a 2a  preferred..**.**
29260 20 7b 46 31 36 31 33 36 7d 20 57 68 65 6e 20 63   {F16136} When c
29270 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
29280 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
29290 28 44 2c 58 2c 4e 2c 45 2c 2e 2e 2e 29 5d 0a 2a  (D,X,N,E,...)].*
292a0 2a 20 20 20 20 20 20 20 20 20 20 73 70 65 63 69  *          speci
292b0 66 79 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c  fy multiple impl
292c0 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74  ementations of t
292d0 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e  he same function
292e0 20 58 20 77 69 74 68 0a 2a 2a 20 20 20 20 20 20   X with.**      
292f0 20 20 20 20 74 68 65 20 73 61 6d 65 20 6e 75 6d      the same num
29300 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73  ber of arguments
29310 20 4e 20 62 75 74 20 77 69 74 68 20 64 69 66 66   N but with diff
29320 65 72 65 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20  erent.**        
29330 20 20 65 6e 63 6f 64 69 6e 67 73 20 45 2c 20 74    encodings E, t
29340 68 65 6e 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e  hen the implemen
29350 74 61 74 69 6f 6e 20 77 68 65 72 65 20 45 20 6d  tation where E m
29360 61 74 63 68 65 73 20 74 68 65 0a 2a 2a 20 20 20  atches the.**   
29370 20 20 20 20 20 20 20 64 61 74 61 62 61 73 65 20         database 
29380 65 6e 63 6f 64 69 6e 67 20 69 73 20 70 72 65 66  encoding is pref
29390 65 72 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  erred..**.** {F1
293a0 36 31 33 39 7d 20 46 6f 72 20 61 6e 20 61 67 67  6139} For an agg
293b0 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74  regate SQL funct
293c0 69 6f 6e 20 63 72 65 61 74 65 64 20 75 73 69 6e  ion created usin
293d0 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  g.**          [s
293e0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
293f0 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50  nction(D,X,N,E,P
29400 2c 30 2c 53 2c 4c 29 5d 20 74 68 65 20 66 69 6e  ,0,S,L)] the fin
29410 69 61 6c 69 7a 65 72 0a 2a 2a 20 20 20 20 20 20  ializer.**      
29420 20 20 20 20 66 75 6e 63 74 69 6f 6e 20 4c 20 77      function L w
29430 69 6c 6c 20 61 6c 77 61 79 73 20 62 65 20 69 6e  ill always be in
29440 76 6f 6b 65 64 20 65 78 61 63 74 6c 79 20 6f 6e  voked exactly on
29450 63 65 20 69 66 20 74 68 65 0a 2a 2a 20 20 20 20  ce if the.**    
29460 20 20 20 20 20 20 73 74 65 70 20 66 75 6e 63 74        step funct
29470 69 6f 6e 20 53 20 69 73 20 63 61 6c 6c 65 64 20  ion S is called 
29480 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  one or more time
29490 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 34 32  s..**.** {F16142
294a0 7d 20 57 68 65 6e 20 53 51 4c 69 74 65 20 69 6e  } When SQLite in
294b0 76 6f 6b 65 73 20 65 69 74 68 65 72 20 74 68 65  vokes either the
294c0 20 78 46 75 6e 63 20 6f 72 20 78 53 74 65 70 20   xFunc or xStep 
294d0 66 75 6e 63 74 69 6f 6e 20 6f 66 0a 2a 2a 20 20  function of.**  
294e0 20 20 20 20 20 20 20 20 61 6e 20 61 70 70 6c 69          an appli
294f0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
29500 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61  QL function or a
29510 67 67 72 65 67 61 74 65 20 63 72 65 61 74 65 64  ggregate created
29520 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 79 20  .**          by 
29530 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
29540 66 75 6e 63 74 69 6f 6e 28 29 5d 20 6f 72 20 5b  function()] or [
29550 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
29560 75 6e 63 74 69 6f 6e 31 36 28 29 5d 2c 0a 2a 2a  unction16()],.**
29570 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 74            then t
29580 68 65 20 61 72 72 61 79 20 6f 66 20 5b 73 71 6c  he array of [sql
29590 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
295a0 63 74 73 20 70 61 73 73 65 64 20 61 73 20 74 68  cts passed as th
295b0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  e.**          th
295c0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 61 72  ird parameter ar
295d0 65 20 61 6c 77 61 79 73 20 5b 70 72 6f 74 65 63  e always [protec
295e0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
295f0 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 69  e] objects..*/.i
29600 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
29610 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71  e_function(.  sq
29620 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e  lite3 *db,.  con
29630 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69  st char *zFuncti
29640 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41  onName,.  int nA
29650 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52  rg,.  int eTextR
29660 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70  ep,.  void *pApp
29670 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63  ,.  void (*xFunc
29680 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
29690 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
296a0 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
296b0 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33  (*xStep)(sqlite3
296c0 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
296d0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
296e0 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29    void (*xFinal)
296f0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
29700 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  *).);.int sqlite
29710 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
29720 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  n16(.  sqlite3 *
29730 64 62 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64  db,.  const void
29740 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c   *zFunctionName,
29750 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69  .  int nArg,.  i
29760 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76  nt eTextRep,.  v
29770 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69  oid *pApp,.  voi
29780 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74  d (*xFunc)(sqlit
29790 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
297a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
297b0 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70  ,.  void (*xStep
297c0 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
297d0 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
297e0 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
297f0 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65  (*xFinal)(sqlite
29800 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 0a  3_context*).);..
29810 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
29820 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 20 7b  Text Encodings {
29830 46 31 30 32 36 37 7d 0a 2a 2a 0a 2a 2a 20 54 68  F10267}.**.** Th
29840 65 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 65 66  ese constant def
29850 69 6e 65 20 69 6e 74 65 67 65 72 20 63 6f 64 65  ine integer code
29860 73 20 74 68 61 74 20 72 65 70 72 65 73 65 6e 74  s that represent
29870 20 74 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20   the various.** 
29880 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 20 73  text encodings s
29890 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69  upported by SQLi
298a0 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  te..*/.#define S
298b0 51 4c 49 54 45 5f 55 54 46 38 20 20 20 20 20 20  QLITE_UTF8      
298c0 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
298d0 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 20 20  QLITE_UTF16LE   
298e0 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
298f0 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20 20  QLITE_UTF16BE   
29900 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
29910 51 4c 49 54 45 5f 55 54 46 31 36 20 20 20 20 20  QLITE_UTF16     
29920 20 20 20 20 20 34 20 20 20 20 2f 2a 20 55 73 65       4    /* Use
29930 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
29940 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  er */.#define SQ
29950 4c 49 54 45 5f 41 4e 59 20 20 20 20 20 20 20 20  LITE_ANY        
29960 20 20 20 20 35 20 20 20 20 2f 2a 20 73 71 6c 69      5    /* sqli
29970 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
29980 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  ion only */.#def
29990 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
299a0 5f 41 4c 49 47 4e 45 44 20 20 38 20 20 20 20 2f  _ALIGNED  8    /
299b0 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  * sqlite3_create
299c0 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20  _collation only 
299d0 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
299e0 45 46 3a 20 4f 62 73 6f 6c 65 74 65 20 46 75 6e  EF: Obsolete Fun
299f0 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65  ctions.**.** The
29a00 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65  se functions are
29a10 20 61 6c 6c 20 6e 6f 77 20 6f 62 73 6f 6c 65 74   all now obsolet
29a20 65 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20  e.  In order to 
29a30 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b  maintain.** back
29a40 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
29a50 69 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20 63  ity with older c
29a60 6f 64 65 2c 20 77 65 20 63 6f 6e 74 69 6e 75 65  ode, we continue
29a70 20 74 6f 20 73 75 70 70 6f 72 74 0a 2a 2a 20 74   to support.** t
29a80 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20  hese functions. 
29a90 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 64 65   However, new de
29aa0 76 65 6c 6f 70 6d 65 6e 74 20 70 72 6f 6a 65 63  velopment projec
29ab0 74 73 20 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a  ts should avoid.
29ac0 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 74 68  ** the use of th
29ad0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20  ese functions.  
29ae0 54 6f 20 68 65 6c 70 20 65 6e 63 6f 75 72 61 67  To help encourag
29af0 65 20 70 65 6f 70 6c 65 20 74 6f 20 61 76 6f 69  e people to avoi
29b00 64 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 73 65  d.** using these
29b10 20 66 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20 61   functions, we a
29b20 72 65 20 6e 6f 74 20 67 6f 69 6e 67 20 74 6f 20  re not going to 
29b30 74 65 6c 6c 20 79 6f 75 20 77 61 6e 74 20 74 68  tell you want th
29b40 65 79 20 64 6f 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ey do..*/.int sq
29b50 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
29b60 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f  count(sqlite3_co
29b70 6e 74 65 78 74 2a 29 3b 0a 69 6e 74 20 73 71 6c  ntext*);.int sql
29b80 69 74 65 33 5f 65 78 70 69 72 65 64 28 73 71 6c  ite3_expired(sql
29b90 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 69 6e 74  ite3_stmt*);.int
29ba0 20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 65   sqlite3_transfe
29bb0 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74  r_bindings(sqlit
29bc0 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65  e3_stmt*, sqlite
29bd0 33 5f 73 74 6d 74 2a 29 3b 0a 69 6e 74 20 73 71  3_stmt*);.int sq
29be0 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63  lite3_global_rec
29bf0 6f 76 65 72 28 76 6f 69 64 29 3b 0a 76 6f 69 64  over(void);.void
29c00 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 5f   sqlite3_thread_
29c10 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a 69  cleanup(void);.i
29c20 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  nt sqlite3_memor
29c30 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29 28  y_alarm(void(*)(
29c40 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e  void*,sqlite3_in
29c50 74 36 34 2c 69 6e 74 29 2c 76 6f 69 64 2a 2c 73  t64,int),void*,s
29c60 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 0a  qlite3_int64);..
29c70 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
29c80 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c 20 46 75  Obtaining SQL Fu
29c90 6e 63 74 69 6f 6e 20 50 61 72 61 6d 65 74 65 72  nction Parameter
29ca0 20 56 61 6c 75 65 73 20 7b 46 31 35 31 30 30 7d   Values {F15100}
29cb0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e  .**.** The C-lan
29cc0 67 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61  guage implementa
29cd0 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63  tion of SQL func
29ce0 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67  tions and aggreg
29cf0 61 74 65 73 20 75 73 65 73 0a 2a 2a 20 74 68 69  ates uses.** thi
29d00 73 20 73 65 74 20 6f 66 20 69 6e 74 65 72 66 61  s set of interfa
29d10 63 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 61  ce routines to a
29d20 63 63 65 73 73 20 74 68 65 20 70 61 72 61 6d 65  ccess the parame
29d30 74 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a  ter values on.**
29d40 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72   the function or
29d50 20 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a   aggregate..**.*
29d60 2a 20 54 68 65 20 78 46 75 6e 63 20 28 66 6f 72  * The xFunc (for
29d70 20 73 63 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e   scalar function
29d80 73 29 20 6f 72 20 78 53 74 65 70 20 28 66 6f 72  s) or xStep (for
29d90 20 61 67 67 72 65 67 61 74 65 73 29 20 70 61 72   aggregates) par
29da0 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73  ameters.** to [s
29db0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
29dc0 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73  nction()] and [s
29dd0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
29de0 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64  nction16()].** d
29df0 65 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20  efine callbacks 
29e00 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74  that implement t
29e10 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  he SQL functions
29e20 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e   and aggregates.
29e30 0a 2a 2a 20 54 68 65 20 34 74 68 20 70 61 72 61  .** The 4th para
29e40 6d 65 74 65 72 20 74 6f 20 74 68 65 73 65 20 63  meter to these c
29e50 61 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e 20 61  allbacks is an a
29e60 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73  rray of pointers
29e70 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65   to.** [protecte
29e80 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
29e90 20 6f 62 6a 65 63 74 73 2e 20 20 54 68 65 72 65   objects.  There
29ea0 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33   is one [sqlite3
29eb0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66  _value] object f
29ec0 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61 72 61 6d  or.** each param
29ed0 65 74 65 72 20 74 6f 20 74 68 65 20 53 51 4c 20  eter to the SQL 
29ee0 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73 65  function.  These
29ef0 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73   routines are us
29f00 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74  ed to.** extract
29f10 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 74 68 65   values from the
29f20 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
29f30 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20   objects..**.** 
29f40 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77  These routines w
29f50 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70  ork only with [p
29f60 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
29f70 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e  _value] objects.
29f80 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20  .** Any attempt 
29f90 74 6f 20 75 73 65 20 74 68 65 73 65 20 72 6f 75  to use these rou
29fa0 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70  tines on an [unp
29fb0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
29fc0 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63  _value].** objec
29fd0 74 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64  t results in und
29fe0 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e  efined behavior.
29ff0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
2a000 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74 20  tines work just 
2a010 6c 69 6b 65 20 74 68 65 20 63 6f 72 72 65 73 70  like the corresp
2a020 6f 6e 64 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69  onding .** [sqli
2a030 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 20  te3_column_blob 
2a040 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  | sqlite3_column
2a050 5f 2a 20 72 6f 75 74 69 6e 65 73 5d 20 65 78 63  _* routines] exc
2a060 65 70 74 20 74 68 61 74 20 0a 2a 2a 20 74 68 65  ept that .** the
2a070 73 65 20 72 6f 75 74 69 6e 65 73 20 74 61 6b 65  se routines take
2a080 20 61 20 73 69 6e 67 6c 65 20 5b 70 72 6f 74 65   a single [prote
2a090 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2a0a0 75 65 5d 20 6f 62 6a 65 63 74 20 70 6f 69 6e 74  ue] object point
2a0b0 65 72 0a 2a 2a 20 69 6e 73 74 65 61 64 20 6f 66  er.** instead of
2a0c0 20 61 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74   a [sqlite3_stmt
2a0d0 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 61  *] pointer and a
2a0e0 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d 6e  n integer column
2a0f0 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 54   number..**.** T
2a100 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
2a110 5f 74 65 78 74 31 36 28 29 20 69 6e 74 65 72 66  _text16() interf
2a120 61 63 65 20 65 78 74 72 61 63 74 73 20 61 20 55  ace extracts a U
2a130 54 46 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69  TF16 string.** i
2a140 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74  n the native byt
2a150 65 2d 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68  e-order of the h
2a160 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20 20 54 68  ost machine.  Th
2a170 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  e.** sqlite3_val
2a180 75 65 5f 74 65 78 74 31 36 62 65 28 29 20 61 6e  ue_text16be() an
2a190 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  d sqlite3_value_
2a1a0 74 65 78 74 31 36 6c 65 28 29 20 69 6e 74 65 72  text16le() inter
2a1b0 66 61 63 65 73 0a 2a 2a 20 65 78 74 72 61 63 74  faces.** extract
2a1c0 20 55 54 46 31 36 20 73 74 72 69 6e 67 73 20 61   UTF16 strings a
2a1d0 73 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64  s big-endian and
2a1e0 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72   little-endian r
2a1f0 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a  espectively..**.
2a200 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76  ** The sqlite3_v
2a210 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70  alue_numeric_typ
2a220 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74  e() interface at
2a230 74 65 6d 70 74 73 20 74 6f 20 61 70 70 6c 79 0a  tempts to apply.
2a240 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 69 6e  ** numeric affin
2a250 69 74 79 20 74 6f 20 74 68 65 20 76 61 6c 75 65  ity to the value
2a260 2e 20 20 54 68 69 73 20 6d 65 61 6e 73 20 74 68  .  This means th
2a270 61 74 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73  at an attempt is
2a280 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76  .** made to conv
2a290 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 74 6f  ert the value to
2a2a0 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 20 66   an integer or f
2a2b0 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20  loating point.  
2a2c0 49 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e  If.** such a con
2a2d0 76 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 73 69  version is possi
2a2e0 62 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f 73 73  ble without loss
2a2f0 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20   of information 
2a300 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72  (in other.** wor
2a310 64 73 20 69 66 20 74 68 65 20 76 61 6c 75 65 20  ds if the value 
2a320 69 73 20 61 20 73 74 72 69 6e 67 20 74 68 61 74  is a string that
2a330 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75   looks like a nu
2a340 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68  mber).** then th
2a350 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20  e conversion is 
2a360 64 6f 6e 65 2e 20 20 4f 74 68 65 72 77 69 73 65  done.  Otherwise
2a370 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f   no conversion o
2a380 63 63 75 72 73 2e 20 20 54 68 65 20 0a 2a 2a 20  ccurs.  The .** 
2a390 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20  [SQLITE_INTEGER 
2a3a0 7c 20 64 61 74 61 74 79 70 65 5d 20 61 66 74 65  | datatype] afte
2a3b0 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20  r conversion is 
2a3c0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
2a3d0 50 6c 65 61 73 65 20 70 61 79 20 70 61 72 74 69  Please pay parti
2a3e0 63 75 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e 20  cular attention 
2a3f0 74 6f 20 74 68 65 20 66 61 63 74 20 74 68 61 74  to the fact that
2a400 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 68 61   the pointer tha
2a410 74 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64  t.** is returned
2a420 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76   from [sqlite3_v
2a430 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73  alue_blob()], [s
2a440 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2a450 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  t()], or.** [sql
2a460 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
2a470 36 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76 61  6()] can be inva
2a480 6c 69 64 61 74 65 64 20 62 79 20 61 20 73 75 62  lidated by a sub
2a490 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a  sequent call to.
2a4a0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ** [sqlite3_valu
2a4b0 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c  e_bytes()], [sql
2a4c0 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
2a4d0 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  16()], [sqlite3_
2a4e0 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a  value_text()],.*
2a4f0 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61  * or [sqlite3_va
2a500 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 20 20  lue_text16()].  
2a510 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
2a520 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61  tines must be ca
2a530 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61  lled from the sa
2a540 6d 65 20 74 68 72 65 61 64 20 61 73 0a 2a 2a 20  me thread as.** 
2a550 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
2a560 20 74 68 61 74 20 73 75 70 70 6c 69 65 64 20 74   that supplied t
2a570 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
2a580 65 2a 5d 20 70 61 72 61 6d 65 74 65 72 73 2e 0a  e*] parameters..
2a590 2a 2a 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  **.**.** INVARIA
2a5a0 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31  NTS:.**.** {F151
2a5b0 30 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  03} The [sqlite3
2a5c0 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 56 29 5d 20  _value_blob(V)] 
2a5d0 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72  interface conver
2a5e0 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ts the.**       
2a5f0 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71     [protected sq
2a600 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2a610 65 63 74 20 56 20 69 6e 74 6f 20 61 20 62 6c 6f  ect V into a blo
2a620 62 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72  b and then retur
2a630 6e 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20  ns a.**         
2a640 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
2a650 63 6f 6e 76 65 72 74 65 64 20 76 61 6c 75 65 2e  converted value.
2a660 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31 30 36 7d 20  .**.** {F15106} 
2a670 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  The [sqlite3_val
2a680 75 65 5f 62 79 74 65 73 28 56 29 5d 20 69 6e 74  ue_bytes(V)] int
2a690 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
2a6a0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e  he.**          n
2a6b0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
2a6c0 6e 20 74 68 65 20 62 6c 6f 62 20 6f 72 20 73 74  n the blob or st
2a6d0 72 69 6e 67 20 28 65 78 63 6c 75 73 69 76 65 20  ring (exclusive 
2a6e0 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  of the.**       
2a6f0 20 20 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74     zero terminat
2a700 6f 72 20 6f 6e 20 74 68 65 20 73 74 72 69 6e 67  or on the string
2a710 29 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72  ) that was retur
2a720 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 20 20  ned by the.**   
2a730 20 20 20 20 20 20 20 6d 6f 73 74 20 72 65 63 65         most rece
2a740 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  nt call to [sqli
2a750 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 56  te3_value_blob(V
2a760 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  )] or.**        
2a770 20 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65    [sqlite3_value
2a780 5f 74 65 78 74 28 56 29 5d 2e 0a 2a 2a 0a 2a 2a  _text(V)]..**.**
2a790 20 7b 46 31 35 31 30 39 7d 20 54 68 65 20 5b 73   {F15109} The [s
2a7a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
2a7b0 65 73 31 36 28 56 29 5d 20 69 6e 74 65 72 66 61  es16(V)] interfa
2a7c0 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a  ce returns the.*
2a7d0 2a 20 20 20 20 20 20 20 20 20 20 6e 75 6d 62 65  *          numbe
2a7e0 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
2a7f0 65 20 73 74 72 69 6e 67 20 28 65 78 63 6c 75 73  e string (exclus
2a800 69 76 65 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20  ive of the.**   
2a810 20 20 20 20 20 20 20 7a 65 72 6f 20 74 65 72 6d         zero term
2a820 69 6e 61 74 6f 72 20 6f 6e 20 74 68 65 20 73 74  inator on the st
2a830 72 69 6e 67 29 20 74 68 61 74 20 77 61 73 20 72  ring) that was r
2a840 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a  eturned by the.*
2a850 2a 20 20 20 20 20 20 20 20 20 20 6d 6f 73 74 20  *          most 
2a860 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b  recent call to [
2a870 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
2a880 78 74 31 36 28 56 29 5d 2c 0a 2a 2a 20 20 20 20  xt16(V)],.**    
2a890 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 76        [sqlite3_v
2a8a0 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 56 29  alue_text16be(V)
2a8b0 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76  ], or [sqlite3_v
2a8c0 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 56 29  alue_text16le(V)
2a8d0 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31 31 32  ]..**.** {F15112
2a8e0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  } The [sqlite3_v
2a8f0 61 6c 75 65 5f 64 6f 75 62 6c 65 28 56 29 5d 20  alue_double(V)] 
2a900 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72  interface conver
2a910 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ts the.**       
2a920 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71     [protected sq
2a930 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2a940 65 63 74 20 56 20 69 6e 74 6f 20 61 20 66 6c 6f  ect V into a flo
2a950 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75  ating point valu
2a960 65 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20  e and.**        
2a970 20 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79    returns a copy
2a980 20 6f 66 20 74 68 61 74 20 76 61 6c 75 65 2e 0a   of that value..
2a990 2a 2a 0a 2a 2a 20 7b 46 31 35 31 31 35 7d 20 54  **.** {F15115} T
2a9a0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
2a9b0 65 5f 69 6e 74 28 56 29 5d 20 69 6e 74 65 72 66  e_int(V)] interf
2a9c0 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65  ace converts the
2a9d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
2a9e0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2a9f0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20  value] object V 
2aa00 69 6e 74 6f 20 61 20 36 34 2d 62 69 74 20 73 69  into a 64-bit si
2aa10 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64  gned integer and
2aa20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74  .**          ret
2aa30 75 72 6e 73 20 74 68 65 20 6c 6f 77 65 72 20 33  urns the lower 3
2aa40 32 20 62 69 74 73 20 6f 66 20 74 68 61 74 20 69  2 bits of that i
2aa50 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46  nteger..**.** {F
2aa60 31 35 31 31 38 7d 20 54 68 65 20 5b 73 71 6c 69  15118} The [sqli
2aa70 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28  te3_value_int64(
2aa80 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f  V)] interface co
2aa90 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20  nverts the.**   
2aaa0 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65         [protecte
2aab0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
2aac0 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61   object V into a
2aad0 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69   64-bit signed i
2aae0 6e 74 65 67 65 72 20 61 6e 64 0a 2a 2a 20 20 20  nteger and.**   
2aaf0 20 20 20 20 20 20 20 72 65 74 75 72 6e 73 20 61         returns a
2ab00 20 63 6f 70 79 20 6f 66 20 74 68 61 74 20 69 6e   copy of that in
2ab10 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  teger..**.** {F1
2ab20 35 31 32 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  5121} The [sqlit
2ab30 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 56 29  e3_value_text(V)
2ab40 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76  ] interface conv
2ab50 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  erts the.**     
2ab60 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20       [protected 
2ab70 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2ab80 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20 7a  bject V into a z
2ab90 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
2aba0 54 46 2d 38 20 0a 2a 2a 20 20 20 20 20 20 20 20  TF-8 .**        
2abb0 20 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74    string and ret
2abc0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
2abd0 6f 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a  o that string..*
2abe0 2a 0a 2a 2a 20 7b 46 31 35 31 32 34 7d 20 54 68  *.** {F15124} Th
2abf0 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
2ac00 5f 74 65 78 74 31 36 28 56 29 5d 20 69 6e 74 65  _text16(V)] inte
2ac10 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74  rface converts t
2ac20 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
2ac30 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2ac40 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
2ac50 56 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65  V into a zero-te
2ac60 72 6d 69 6e 61 74 65 64 20 32 2d 62 79 74 65 0a  rminated 2-byte.
2ac70 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c 69 67  **          alig
2ac80 6e 65 64 20 55 54 46 2d 31 36 20 6e 61 74 69 76  ned UTF-16 nativ
2ac90 65 20 62 79 74 65 20 6f 72 64 65 72 0a 2a 2a 20  e byte order.** 
2aca0 20 20 20 20 20 20 20 20 20 73 74 72 69 6e 67 20           string 
2acb0 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f  and returns a po
2acc0 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20 73 74  inter to that st
2acd0 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35  ring..**.** {F15
2ace0 31 32 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  127} The [sqlite
2acf0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65  3_value_text16be
2ad00 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  (V)] interface c
2ad10 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20  onverts the.**  
2ad20 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74          [protect
2ad30 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2ad40 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20  ] object V into 
2ad50 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
2ad60 64 20 32 2d 62 79 74 65 0a 2a 2a 20 20 20 20 20  d 2-byte.**     
2ad70 20 20 20 20 20 61 6c 69 67 6e 65 64 20 55 54 46       aligned UTF
2ad80 2d 31 36 20 62 69 67 2d 65 6e 64 69 61 6e 0a 2a  -16 big-endian.*
2ad90 2a 20 20 20 20 20 20 20 20 20 20 73 74 72 69 6e  *          strin
2ada0 67 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20  g and returns a 
2adb0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20  pointer to that 
2adc0 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46  string..**.** {F
2add0 31 35 31 33 30 7d 20 54 68 65 20 5b 73 71 6c 69  15130} The [sqli
2ade0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
2adf0 6c 65 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65  le(V)] interface
2ae00 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a   converts the.**
2ae10 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65            [prote
2ae20 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2ae30 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74  ue] object V int
2ae40 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  o a zero-termina
2ae50 74 65 64 20 32 2d 62 79 74 65 0a 2a 2a 20 20 20  ted 2-byte.**   
2ae60 20 20 20 20 20 20 20 61 6c 69 67 6e 65 64 20 55         aligned U
2ae70 54 46 2d 31 36 20 6c 69 74 74 6c 65 2d 65 6e 64  TF-16 little-end
2ae80 69 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ian.**          
2ae90 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72  string and retur
2aea0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
2aeb0 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  that string..**.
2aec0 2a 2a 20 7b 46 31 35 31 33 33 7d 20 54 68 65 20  ** {F15133} The 
2aed0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
2aee0 79 70 65 28 56 29 5d 20 69 6e 74 65 72 66 61 63  ype(V)] interfac
2aef0 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20  e returns.**    
2af00 20 20 20 20 20 20 6f 6e 65 20 6f 66 20 5b 53 51        one of [SQ
2af10 4c 49 54 45 5f 4e 55 4c 4c 5d 2c 20 5b 53 51 4c  LITE_NULL], [SQL
2af20 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 20 5b 53  ITE_INTEGER], [S
2af30 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 0a 2a 2a  QLITE_FLOAT],.**
2af40 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54            [SQLIT
2af50 45 5f 54 45 58 54 5d 2c 20 6f 72 20 5b 53 51 4c  E_TEXT], or [SQL
2af60 49 54 45 5f 42 4c 4f 42 5d 20 61 73 20 61 70 70  ITE_BLOB] as app
2af70 72 6f 70 72 69 61 74 65 20 66 6f 72 0a 2a 2a 20  ropriate for.** 
2af80 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 73 71           the [sq
2af90 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2afa0 65 63 74 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  ect V..**.** {F1
2afb0 35 31 33 36 7d 20 54 68 65 20 5b 73 71 6c 69 74  5136} The [sqlit
2afc0 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63  e3_value_numeric
2afd0 5f 74 79 70 65 28 56 29 5d 20 69 6e 74 65 72 66  _type(V)] interf
2afe0 61 63 65 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20  ace converts.** 
2aff0 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 70 72           the [pr
2b000 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2b010 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20  value] object V 
2b020 69 6e 74 6f 20 65 69 74 68 65 72 20 61 6e 20 69  into either an i
2b030 6e 74 65 67 65 72 20 6f 72 0a 2a 2a 20 20 20 20  nteger or.**    
2b040 20 20 20 20 20 20 61 20 66 6c 6f 61 74 69 6e 67        a floating
2b050 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 69 66 20   point value if 
2b060 69 74 20 63 61 6e 20 64 6f 20 73 6f 20 77 69 74  it can do so wit
2b070 68 6f 75 74 20 6c 6f 73 73 20 6f 66 0a 2a 2a 20  hout loss of.** 
2b080 20 20 20 20 20 20 20 20 20 69 6e 66 6f 72 6d 61           informa
2b090 74 69 6f 6e 2c 20 61 6e 64 20 72 65 74 75 72 6e  tion, and return
2b0a0 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45  s one of [SQLITE
2b0b0 5f 4e 55 4c 4c 5d 2c 0a 2a 2a 20 20 20 20 20 20  _NULL],.**      
2b0c0 20 20 20 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45      [SQLITE_INTE
2b0d0 47 45 52 5d 2c 20 5b 53 51 4c 49 54 45 5f 46 4c  GER], [SQLITE_FL
2b0e0 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45  OAT], [SQLITE_TE
2b0f0 58 54 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20  XT], or.**      
2b100 20 20 20 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42      [SQLITE_BLOB
2b110 5d 20 61 73 20 61 70 70 72 6f 70 72 69 61 74 65  ] as appropriate
2b120 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20   for.**         
2b130 20 74 68 65 20 5b 70 72 6f 74 65 63 74 65 64 20   the [protected 
2b140 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2b150 62 6a 65 63 74 20 56 20 61 66 74 65 72 20 74 68  bject V after th
2b160 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 74 74  e conversion att
2b170 65 6d 70 74 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76  empt..*/.const v
2b180 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  oid *sqlite3_val
2b190 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  ue_blob(sqlite3_
2b1a0 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
2b1b0 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
2b1c0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
2b1d0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  ;.int sqlite3_va
2b1e0 6c 75 65 5f 62 79 74 65 73 31 36 28 73 71 6c 69  lue_bytes16(sqli
2b1f0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f 75  te3_value*);.dou
2b200 62 6c 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ble sqlite3_valu
2b210 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  e_double(sqlite3
2b220 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
2b230 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28  lite3_value_int(
2b240 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
2b250 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
2b260 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74  qlite3_value_int
2b270 36 34 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  64(sqlite3_value
2b280 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e  *);.const unsign
2b290 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  ed char *sqlite3
2b2a0 5f 76 61 6c 75 65 5f 74 65 78 74 28 73 71 6c 69  _value_text(sqli
2b2b0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e  te3_value*);.con
2b2c0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
2b2d0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 73 71  _value_text16(sq
2b2e0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63  lite3_value*);.c
2b2f0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
2b300 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c  e3_value_text16l
2b310 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
2b320 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
2b330 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2b340 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 76 61  t16be(sqlite3_va
2b350 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
2b360 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 73 71  e3_value_type(sq
2b370 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
2b380 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
2b390 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 73 71  _numeric_type(sq
2b3a0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a  lite3_value*);..
2b3b0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2b3c0 4f 62 74 61 69 6e 20 41 67 67 72 65 67 61 74 65  Obtain Aggregate
2b3d0 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78   Function Contex
2b3e0 74 20 7b 46 31 36 32 31 30 7d 0a 2a 2a 0a 2a 2a  t {F16210}.**.**
2b3f0 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   The implementat
2b400 69 6f 6e 20 6f 66 20 61 67 67 72 65 67 61 74 65  ion of aggregate
2b410 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 75   SQL functions u
2b420 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  se this routine 
2b430 74 6f 20 61 6c 6c 6f 63 61 74 65 0a 2a 2a 20 61  to allocate.** a
2b440 20 73 74 72 75 63 74 75 72 65 20 66 6f 72 20 73   structure for s
2b450 74 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74 61  toring their sta
2b460 74 65 2e 20 20 0a 2a 2a 20 54 68 65 20 66 69 72  te.  .** The fir
2b470 73 74 20 74 69 6d 65 20 74 68 65 20 73 71 6c 69  st time the sqli
2b480 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
2b490 6e 74 65 78 74 28 29 20 72 6f 75 74 69 6e 65 20  ntext() routine 
2b4a0 69 73 0a 2a 2a 20 69 73 20 63 61 6c 6c 65 64 20  is.** is called 
2b4b0 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72  for a particular
2b4c0 20 61 67 67 72 65 67 61 74 65 2c 20 53 51 4c 69   aggregate, SQLi
2b4d0 74 65 20 61 6c 6c 6f 63 61 74 65 73 20 6e 42 79  te allocates nBy
2b4e0 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a  tes of memory.**
2b4f0 20 7a 65 72 6f 73 20 74 68 61 74 20 6d 65 6d 6f   zeros that memo
2b500 72 79 2c 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ry, and returns 
2b510 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 2e  a pointer to it.
2b520 0a 2a 2a 20 4f 6e 20 73 65 63 6f 6e 64 20 61 6e  .** On second an
2b530 64 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  d subsequent cal
2b540 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67  ls to sqlite3_ag
2b550 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
2b560 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d  ).** for the sam
2b570 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  e aggregate func
2b580 74 69 6f 6e 20 69 6e 64 65 78 2c 20 74 68 65 20  tion index, the 
2b590 73 61 6d 65 20 62 75 66 66 65 72 20 69 73 20 72  same buffer is r
2b5a0 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 54 68 65 20  eturned..** The 
2b5b0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a  implementation.*
2b5c0 2a 20 6f 66 20 74 68 65 20 61 67 67 72 65 67 61  * of the aggrega
2b5d0 74 65 20 63 61 6e 20 75 73 65 20 74 68 65 20 72  te can use the r
2b5e0 65 74 75 72 6e 65 64 20 62 75 66 66 65 72 20 74  eturned buffer t
2b5f0 6f 20 61 63 63 75 6d 75 6c 61 74 65 20 64 61 74  o accumulate dat
2b600 61 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  a..**.** SQLite 
2b610 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72  automatically fr
2b620 65 65 73 20 74 68 65 20 61 6c 6c 6f 63 61 74 65  ees the allocate
2b630 64 20 62 75 66 66 65 72 20 77 68 65 6e 20 74 68  d buffer when th
2b640 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 71  e aggregate.** q
2b650 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a  uery concludes..
2b660 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
2b670 70 61 72 61 6d 65 74 65 72 20 73 68 6f 75 6c 64  parameter should
2b680 20 62 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68   be a copy of th
2b690 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  e .** [sqlite3_c
2b6a0 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20 66 75 6e  ontext | SQL fun
2b6b0 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74  ction context] t
2b6c0 68 61 74 20 69 73 20 74 68 65 20 66 69 72 73 74  hat is the first
2b6d0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f  .** parameter to
2b6e0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 6f   the callback ro
2b6f0 75 74 69 6e 65 20 74 68 61 74 20 69 6d 70 6c 65  utine that imple
2b700 6d 65 6e 74 73 20 74 68 65 20 61 67 67 72 65 67  ments the aggreg
2b710 61 74 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e  ate.** function.
2b720 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
2b730 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  ine must be call
2b740 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
2b750 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68   thread in which
2b760 0a 2a 2a 20 74 68 65 20 61 67 67 72 65 67 61 74  .** the aggregat
2b770 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  e SQL function i
2b780 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a  s running..**.**
2b790 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
2b7a0 2a 2a 20 7b 46 31 36 32 31 31 7d 20 54 68 65 20  ** {F16211} The 
2b7b0 66 69 72 73 74 20 69 6e 76 6f 63 61 74 69 6f 6e  first invocation
2b7c0 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 61 67 67   of [sqlite3_agg
2b7d0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43  regate_context(C
2b7e0 2c 4e 29 5d 20 66 6f 72 0a 2a 2a 20 20 20 20 20  ,N)] for.**     
2b7f0 20 20 20 20 20 61 20 70 61 72 74 69 63 75 6c 61       a particula
2b800 72 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 61 6e  r instance of an
2b810 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74   aggregate funct
2b820 69 6f 6e 20 28 66 6f 72 20 61 20 70 61 72 74 69  ion (for a parti
2b830 63 75 6c 61 72 0a 2a 2a 20 20 20 20 20 20 20 20  cular.**        
2b840 20 20 63 6f 6e 74 65 78 74 20 43 29 20 63 61 75    context C) cau
2b850 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 61 6c  ses SQLite to al
2b860 6c 6f 63 61 74 69 6f 6e 20 4e 20 62 79 74 65 73  location N bytes
2b870 20 6f 66 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 20   of memory,.**  
2b880 20 20 20 20 20 20 20 20 7a 65 72 6f 20 74 68 61          zero tha
2b890 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65  t memory, and re
2b8a0 74 75 72 6e 20 61 20 70 6f 69 6e 74 65 72 20 74  turn a pointer t
2b8b0 6f 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 0a  o the allocated.
2b8c0 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 65 6d 6f  **          memo
2b8d0 72 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32 31  ry..**.** {F1621
2b8e0 33 7d 20 49 66 20 61 20 6d 65 6d 6f 72 79 20 61  3} If a memory a
2b8f0 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20  llocation error 
2b900 6f 63 63 75 72 73 20 64 75 72 69 6e 67 0a 2a 2a  occurs during.**
2b910 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
2b920 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
2b930 74 65 78 74 28 43 2c 4e 29 5d 20 74 68 65 6e 20  text(C,N)] then 
2b940 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  the function ret
2b950 75 72 6e 73 20 30 2e 0a 2a 2a 0a 2a 2a 20 7b 46  urns 0..**.** {F
2b960 31 36 32 31 35 7d 20 53 65 63 6f 6e 64 20 61 6e  16215} Second an
2b970 64 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76  d subsequent inv
2b980 6f 63 61 74 69 6f 6e 73 20 6f 66 0a 2a 2a 20 20  ocations of.**  
2b990 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
2b9a0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
2b9b0 78 74 28 43 2c 4e 29 5d 20 66 6f 72 20 74 68 65  xt(C,N)] for the
2b9c0 20 73 61 6d 65 20 63 6f 6e 74 65 78 74 20 70 6f   same context po
2b9d0 69 6e 74 65 72 20 43 0a 2a 2a 20 20 20 20 20 20  inter C.**      
2b9e0 20 20 20 20 69 67 6e 6f 72 65 20 74 68 65 20 4e      ignore the N
2b9f0 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72   parameter and r
2ba00 65 74 75 72 6e 20 61 20 70 6f 69 6e 74 65 72 20  eturn a pointer 
2ba10 74 6f 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20  to the same.**  
2ba20 20 20 20 20 20 20 20 20 62 6c 6f 63 6b 20 6f 66          block of
2ba30 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64   memory returned
2ba40 20 62 79 20 74 68 65 20 66 69 72 73 74 20 69 6e   by the first in
2ba50 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  vocation..**.** 
2ba60 7b 46 31 36 32 31 37 7d 20 54 68 65 20 6d 65 6d  {F16217} The mem
2ba70 6f 72 79 20 61 6c 6c 6f 63 61 74 65 64 20 62 79  ory allocated by
2ba80 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67   [sqlite3_aggreg
2ba90 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29  ate_context(C,N)
2baa0 5d 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  ] is.**         
2bab0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66   automatically f
2bac0 72 65 65 64 20 6f 6e 20 74 68 65 20 6e 65 78 74  reed on the next
2bad0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
2bae0 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20 20 20  3_reset()].**   
2baf0 20 20 20 20 20 20 20 6f 72 20 5b 73 71 6c 69 74         or [sqlit
2bb00 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 66  e3_finalize()] f
2bb10 6f 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  or the [prepared
2bb20 20 73 74 61 74 65 6d 65 6e 74 5d 20 63 6f 6e 74   statement] cont
2bb30 61 69 6e 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20  aining.**       
2bb40 20 20 20 74 68 65 20 61 67 67 72 65 67 61 74 65     the aggregate
2bb50 20 66 75 6e 63 74 69 6f 6e 20 61 73 73 6f 63 69   function associ
2bb60 61 74 65 64 20 77 69 74 68 20 63 6f 6e 74 65 78  ated with contex
2bb70 74 20 43 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  t C..*/.void *sq
2bb80 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
2bb90 63 6f 6e 74 65 78 74 28 73 71 6c 69 74 65 33 5f  context(sqlite3_
2bba0 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42  context*, int nB
2bbb0 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ytes);../*.** CA
2bbc0 50 49 33 52 45 46 3a 20 55 73 65 72 20 44 61 74  PI3REF: User Dat
2bbd0 61 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 20  a For Functions 
2bbe0 7b 46 31 36 32 34 30 7d 0a 2a 2a 0a 2a 2a 20 54  {F16240}.**.** T
2bbf0 68 65 20 73 71 6c 69 74 65 33 5f 75 73 65 72 5f  he sqlite3_user_
2bc00 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65  data() interface
2bc10 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20   returns a copy 
2bc20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65  of.** the pointe
2bc30 72 20 74 68 61 74 20 77 61 73 20 74 68 65 20 70  r that was the p
2bc40 55 73 65 72 44 61 74 61 20 70 61 72 61 6d 65 74  UserData paramet
2bc50 65 72 20 28 74 68 65 20 35 74 68 20 70 61 72 61  er (the 5th para
2bc60 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65  meter).** of the
2bc70 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2bc80 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20  _function()].** 
2bc90 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  and [sqlite3_cre
2bca0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
2bcb0 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20  ] routines that 
2bcc0 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65  originally.** re
2bcd0 67 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70  gistered the app
2bce0 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64  lication defined
2bcf0 20 66 75 6e 63 74 69 6f 6e 2e 20 7b 45 4e 44 7d   function. {END}
2bd00 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
2bd10 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  ine must be call
2bd20 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
2bd30 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68   thread in which
2bd40 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the applicat
2bd50 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
2bd60 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e  tion is running.
2bd70 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
2bd80 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32 34 33  S:.**.** {F16243
2bd90 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 75  } The [sqlite3_u
2bda0 73 65 72 5f 64 61 74 61 28 43 29 5d 20 69 6e 74  ser_data(C)] int
2bdb0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
2bdc0 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20   copy of the.** 
2bdd0 20 20 20 20 20 20 20 20 20 50 20 70 6f 69 6e 74           P point
2bde0 65 72 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c  er from the [sql
2bdf0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2be00 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46  tion(D,X,N,E,P,F
2be10 2c 53 2c 4c 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ,S,L)].**       
2be20 20 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63     or [sqlite3_c
2be30 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
2be40 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c  (D,X,N,E,P,F,S,L
2be50 29 5d 20 63 61 6c 6c 20 74 68 61 74 0a 2a 2a 20  )] call that.** 
2be60 20 20 20 20 20 20 20 20 20 72 65 67 69 73 74 65           registe
2be70 72 65 64 20 74 68 65 20 53 51 4c 20 66 75 6e 63  red the SQL func
2be80 74 69 6f 6e 20 61 73 73 6f 63 69 61 74 65 64 20  tion associated 
2be90 77 69 74 68 20 0a 2a 2a 20 20 20 20 20 20 20 20  with .**        
2bea0 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65    [sqlite3_conte
2beb0 78 74 5d 20 43 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  xt] C..*/.void *
2bec0 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74  sqlite3_user_dat
2bed0 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  a(sqlite3_contex
2bee0 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
2bef0 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43  3REF: Database C
2bf00 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46 75  onnection For Fu
2bf10 6e 63 74 69 6f 6e 73 20 7b 46 31 36 32 35 30 7d  nctions {F16250}
2bf20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
2bf30 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61  e3_context_db_ha
2bf40 6e 64 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65  ndle() interface
2bf50 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20   returns a copy 
2bf60 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65  of.** the pointe
2bf70 72 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61  r to the [databa
2bf80 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28  se connection] (
2bf90 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65  the 1st paramete
2bfa0 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71  r).** of the [sq
2bfb0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2bfc0 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20  ction()].** and 
2bfd0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2bfe0 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f  function16()] ro
2bff0 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67  utines that orig
2c000 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74  inally.** regist
2c010 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 61  ered the applica
2c020 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e  tion defined fun
2c030 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  ction..**.** INV
2c040 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
2c050 46 31 36 32 35 33 7d 20 54 68 65 20 5b 73 71 6c  F16253} The [sql
2c060 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f  ite3_context_db_
2c070 68 61 6e 64 6c 65 28 43 29 5d 20 69 6e 74 65 72  handle(C)] inter
2c080 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63  face returns a c
2c090 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20  opy of the.**   
2c0a0 20 20 20 20 20 20 20 44 20 70 6f 69 6e 74 65 72         D pointer
2c0b0 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74   from the [sqlit
2c0c0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2c0d0 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53  on(D,X,N,E,P,F,S
2c0e0 2c 4c 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ,L)].**         
2c0f0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63 72 65   or [sqlite3_cre
2c100 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 44  ate_function16(D
2c110 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d  ,X,N,E,P,F,S,L)]
2c120 20 63 61 6c 6c 20 74 68 61 74 0a 2a 2a 20 20 20   call that.**   
2c130 20 20 20 20 20 20 20 72 65 67 69 73 74 65 72 65         registere
2c140 64 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  d the SQL functi
2c150 6f 6e 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  on associated wi
2c160 74 68 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  th .**          
2c170 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  [sqlite3_context
2c180 5d 20 43 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20  ] C..*/.sqlite3 
2c190 2a 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  *sqlite3_context
2c1a0 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74  _db_handle(sqlit
2c1b0 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f  e3_context*);../
2c1c0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
2c1d0 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c 69 61 72  unction Auxiliar
2c1e0 79 20 44 61 74 61 20 7b 46 31 36 32 37 30 7d 0a  y Data {F16270}.
2c1f0 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77  **.** The follow
2c200 69 6e 67 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e  ing two function
2c210 73 20 6d 61 79 20 62 65 20 75 73 65 64 20 62 79  s may be used by
2c220 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63   scalar SQL func
2c230 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f  tions to.** asso
2c240 63 69 61 74 65 20 6d 65 74 61 2d 64 61 74 61 20  ciate meta-data 
2c250 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61  with argument va
2c260 6c 75 65 73 2e 20 49 66 20 74 68 65 20 73 61 6d  lues. If the sam
2c270 65 20 76 61 6c 75 65 20 69 73 20 70 61 73 73 65  e value is passe
2c280 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65  d to.** multiple
2c290 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20   invocations of 
2c2a0 74 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e  the same SQL fun
2c2b0 63 74 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 65  ction during que
2c2c0 72 79 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e  ry execution, un
2c2d0 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63  der.** some circ
2c2e0 75 6d 73 74 61 6e 63 65 73 20 74 68 65 20 61 73  umstances the as
2c2f0 73 6f 63 69 61 74 65 64 20 6d 65 74 61 2d 64 61  sociated meta-da
2c300 74 61 20 6d 61 79 20 62 65 20 70 72 65 73 65 72  ta may be preser
2c310 76 65 64 2e 20 54 68 69 73 20 6d 61 79 0a 2a 2a  ved. This may.**
2c320 20 62 65 20 75 73 65 64 2c 20 66 6f 72 20 65 78   be used, for ex
2c330 61 6d 70 6c 65 2c 20 74 6f 20 61 64 64 20 61 20  ample, to add a 
2c340 72 65 67 75 6c 61 72 2d 65 78 70 72 65 73 73 69  regular-expressi
2c350 6f 6e 20 6d 61 74 63 68 69 6e 67 20 73 63 61 6c  on matching scal
2c360 61 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20  ar.** function. 
2c370 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 76 65 72  The compiled ver
2c380 73 69 6f 6e 20 6f 66 20 74 68 65 20 72 65 67 75  sion of the regu
2c390 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 69  lar expression i
2c3a0 73 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d  s stored as.** m
2c3b0 65 74 61 2d 64 61 74 61 20 61 73 73 6f 63 69 61  eta-data associa
2c3c0 74 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c  ted with the SQL
2c3d0 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73   value passed as
2c3e0 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 70   the regular exp
2c3f0 72 65 73 73 69 6f 6e 0a 2a 2a 20 70 61 74 74 65  ression.** patte
2c400 72 6e 2e 20 20 54 68 65 20 63 6f 6d 70 69 6c 65  rn.  The compile
2c410 64 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73  d regular expres
2c420 73 69 6f 6e 20 63 61 6e 20 62 65 20 72 65 75 73  sion can be reus
2c430 65 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a  ed on multiple.*
2c440 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66  * invocations of
2c450 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69   the same functi
2c460 6f 6e 20 73 6f 20 74 68 61 74 20 74 68 65 20 6f  on so that the o
2c470 72 69 67 69 6e 61 6c 20 70 61 74 74 65 72 6e 20  riginal pattern 
2c480 73 74 72 69 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e  string.** does n
2c490 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 72 65  ot need to be re
2c4a0 63 6f 6d 70 69 6c 65 64 20 6f 6e 20 65 61 63 68  compiled on each
2c4b0 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a   invocation..**.
2c4c0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67  ** The sqlite3_g
2c4d0 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74  et_auxdata() int
2c4e0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
2c4f0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
2c500 6d 65 74 61 2d 64 61 74 61 0a 2a 2a 20 61 73 73  meta-data.** ass
2c510 6f 63 69 61 74 65 64 20 62 79 20 74 68 65 20 73  ociated by the s
2c520 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
2c530 74 61 28 29 20 66 75 6e 63 74 69 6f 6e 20 77 69  ta() function wi
2c540 74 68 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d  th the Nth argum
2c550 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20  ent.** value to 
2c560 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
2c570 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
2c580 2e 0a 2a 2a 20 49 66 20 6e 6f 20 6d 65 74 61 2d  ..** If no meta-
2c590 64 61 74 61 20 68 61 73 20 62 65 65 6e 20 65 76  data has been ev
2c5a0 65 72 20 62 65 65 6e 20 73 65 74 20 66 6f 72 20  er been set for 
2c5b0 74 68 65 20 4e 74 68 0a 2a 2a 20 61 72 67 75 6d  the Nth.** argum
2c5c0 65 6e 74 20 6f 66 20 74 68 65 20 66 75 6e 63 74  ent of the funct
2c5d0 69 6f 6e 2c 20 6f 72 20 69 66 20 74 68 65 20 63  ion, or if the c
2c5e0 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e  orresponding fun
2c5f0 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 0a  ction parameter.
2c600 2a 2a 20 68 61 73 20 63 68 61 6e 67 65 64 20 73  ** has changed s
2c610 69 6e 63 65 20 74 68 65 20 6d 65 74 61 2d 64 61  ince the meta-da
2c620 74 61 20 77 61 73 20 73 65 74 2c 20 74 68 65 6e  ta was set, then
2c630 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78   sqlite3_get_aux
2c640 64 61 74 61 28 29 0a 2a 2a 20 72 65 74 75 72 6e  data().** return
2c650 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
2c660 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
2c670 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
2c680 29 20 69 6e 74 65 72 66 61 63 65 20 73 61 76 65  ) interface save
2c690 73 20 74 68 65 20 6d 65 74 61 2d 64 61 74 61 0a  s the meta-data.
2c6a0 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79  ** pointed to by
2c6b0 20 69 74 73 20 33 72 64 20 70 61 72 61 6d 65 74   its 3rd paramet
2c6c0 65 72 20 61 73 20 74 68 65 20 6d 65 74 61 2d 64  er as the meta-d
2c6d0 61 74 61 20 66 6f 72 20 74 68 65 20 4e 2d 74 68  ata for the N-th
2c6e0 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6f 66 20  .** argument of 
2c6f0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
2c700 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
2c710 2e 20 20 53 75 62 73 65 71 75 65 6e 74 0a 2a 2a  .  Subsequent.**
2c720 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
2c730 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_get_auxdata() 
2c740 6d 69 67 68 74 20 72 65 74 75 72 6e 20 74 68 69  might return thi
2c750 73 20 64 61 74 61 2c 20 69 66 20 69 74 20 68 61  s data, if it ha
2c760 73 0a 2a 2a 20 6e 6f 74 20 62 65 65 6e 20 64 65  s.** not been de
2c770 73 74 72 6f 79 65 64 2e 20 0a 2a 2a 20 49 66 20  stroyed. .** If 
2c780 69 74 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20  it is not NULL, 
2c790 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f  SQLite will invo
2c7a0 6b 65 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  ke the destructo
2c7b0 72 20 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 67  r .** function g
2c7c0 69 76 65 6e 20 62 79 20 74 68 65 20 34 74 68 20  iven by the 4th 
2c7d0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
2c7e0 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
2c7f0 28 29 20 6f 6e 0a 2a 2a 20 74 68 65 20 6d 65 74  () on.** the met
2c800 61 2d 64 61 74 61 20 77 68 65 6e 20 74 68 65 20  a-data when the 
2c810 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 66 75  corresponding fu
2c820 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72  nction parameter
2c830 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f 72 20 77   changes.** or w
2c840 68 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74  hen the SQL stat
2c850 65 6d 65 6e 74 20 63 6f 6d 70 6c 65 74 65 73 2c  ement completes,
2c860 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73   whichever comes
2c870 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 51   first..**.** SQ
2c880 4c 69 74 65 20 69 73 20 66 72 65 65 20 74 6f 20  Lite is free to 
2c890 63 61 6c 6c 20 74 68 65 20 64 65 73 74 72 75 63  call the destruc
2c8a0 74 6f 72 20 61 6e 64 20 64 72 6f 70 20 6d 65 74  tor and drop met
2c8b0 61 2d 64 61 74 61 20 6f 6e 0a 2a 2a 20 61 6e 79  a-data on.** any
2c8c0 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 61 6e   parameter of an
2c8d0 79 20 66 75 6e 63 74 69 6f 6e 20 61 74 20 61 6e  y function at an
2c8e0 79 20 74 69 6d 65 2e 20 20 54 68 65 20 6f 6e 6c  y time.  The onl
2c8f0 79 20 67 75 61 72 61 6e 74 65 65 0a 2a 2a 20 69  y guarantee.** i
2c900 73 20 74 68 61 74 20 74 68 65 20 64 65 73 74 72  s that the destr
2c910 75 63 74 6f 72 20 77 69 6c 6c 20 62 65 20 63 61  uctor will be ca
2c920 6c 6c 65 64 20 62 65 66 6f 72 65 20 74 68 65 20  lled before the 
2c930 6d 65 74 61 64 61 74 61 20 69 73 0a 2a 2a 20 64  metadata is.** d
2c940 72 6f 70 70 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e  ropped..**.** In
2c950 20 70 72 61 63 74 69 63 65 2c 20 6d 65 74 61 2d   practice, meta-
2c960 64 61 74 61 20 69 73 20 70 72 65 73 65 72 76 65  data is preserve
2c970 64 20 62 65 74 77 65 65 6e 20 66 75 6e 63 74 69  d between functi
2c980 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20  on calls for.** 
2c990 65 78 70 72 65 73 73 69 6f 6e 73 20 74 68 61 74  expressions that
2c9a0 20 61 72 65 20 63 6f 6e 73 74 61 6e 74 20 61 74   are constant at
2c9b0 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 54   compile time. T
2c9c0 68 69 73 20 69 6e 63 6c 75 64 65 73 20 6c 69 74  his includes lit
2c9d0 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61  eral.** values a
2c9e0 6e 64 20 53 51 4c 20 76 61 72 69 61 62 6c 65 73  nd SQL variables
2c9f0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
2ca00 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63  utines must be c
2ca10 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73  alled from the s
2ca20 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68  ame thread in wh
2ca30 69 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66  ich.** the SQL f
2ca40 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
2ca50 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  ng..**.** INVARI
2ca60 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  ANTS:.**.** {F16
2ca70 32 37 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  272} The [sqlite
2ca80 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 43 2c  3_get_auxdata(C,
2ca90 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  N)] interface re
2caa0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a  turns a pointer.
2cab0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 6d  **          to m
2cac0 65 74 61 64 61 74 61 20 61 73 73 6f 63 69 61 74  etadata associat
2cad0 65 64 20 77 69 74 68 20 74 68 65 20 4e 74 68 20  ed with the Nth 
2cae0 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65  parameter of the
2caf0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a   SQL function.**
2cb00 20 20 20 20 20 20 20 20 20 20 77 68 6f 73 65 20            whose 
2cb10 63 6f 6e 74 65 78 74 20 69 73 20 43 2c 20 6f 72  context is C, or
2cb20 20 4e 55 4c 4c 20 69 66 20 74 68 65 72 65 20 69   NULL if there i
2cb30 73 20 6e 6f 20 6d 65 74 61 64 61 74 61 20 61 73  s no metadata as
2cb40 73 6f 63 69 61 74 65 64 0a 2a 2a 20 20 20 20 20  sociated.**     
2cb50 20 20 20 20 20 77 69 74 68 20 74 68 61 74 20 70       with that p
2cb60 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
2cb70 7b 46 31 36 32 37 34 7d 20 54 68 65 20 5b 73 71  {F16274} The [sq
2cb80 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
2cb90 61 28 43 2c 4e 2c 50 2c 44 29 5d 20 69 6e 74 65  a(C,N,P,D)] inte
2cba0 72 66 61 63 65 20 61 73 73 69 67 6e 73 20 61 20  rface assigns a 
2cbb0 6d 65 74 61 64 61 74 61 0a 2a 2a 20 20 20 20 20  metadata.**     
2cbc0 20 20 20 20 20 70 6f 69 6e 74 65 72 20 50 20 74       pointer P t
2cbd0 6f 20 74 68 65 20 4e 74 68 20 70 61 72 61 6d 65  o the Nth parame
2cbe0 74 65 72 20 6f 66 20 74 68 65 20 53 51 4c 20 66  ter of the SQL f
2cbf0 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 63 6f 6e  unction with con
2cc00 74 65 78 74 0a 2a 2a 20 20 20 20 20 20 20 20 20  text.**         
2cc10 20 43 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32 37   C..**.** {F1627
2cc20 36 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69  6} SQLite will i
2cc30 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75  nvoke the destru
2cc40 63 74 6f 72 20 44 20 77 69 74 68 20 61 20 73 69  ctor D with a si
2cc50 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  ngle argument.**
2cc60 20 20 20 20 20 20 20 20 20 20 77 68 69 63 68 20            which 
2cc70 69 73 20 74 68 65 20 6d 65 74 61 64 61 74 61 20  is the metadata 
2cc80 70 6f 69 6e 74 65 72 20 50 20 66 6f 6c 6c 6f 77  pointer P follow
2cc90 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a  ing a call to.**
2cca0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
2ccb0 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43  e3_set_auxdata(C
2ccc0 2c 4e 2c 50 2c 44 29 5d 20 77 68 65 6e 20 53 51  ,N,P,D)] when SQ
2ccd0 4c 69 74 65 20 63 65 61 73 65 73 20 74 6f 20 68  Lite ceases to h
2cce0 6f 6c 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  old.**          
2ccf0 74 68 65 20 6d 65 74 61 64 61 74 61 2e 0a 2a 2a  the metadata..**
2cd00 0a 2a 2a 20 7b 46 31 36 32 37 37 7d 20 53 51 4c  .** {F16277} SQL
2cd10 69 74 65 20 63 65 61 73 65 73 20 74 6f 20 68 6f  ite ceases to ho
2cd20 6c 64 20 6d 65 74 61 64 61 74 61 20 66 6f 72 20  ld metadata for 
2cd30 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  an SQL function 
2cd40 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20  parameter.**    
2cd50 20 20 20 20 20 20 77 68 65 6e 20 74 68 65 20 76        when the v
2cd60 61 6c 75 65 20 6f 66 20 74 68 61 74 20 70 61 72  alue of that par
2cd70 61 6d 65 74 65 72 20 63 68 61 6e 67 65 73 2e 0a  ameter changes..
2cd80 2a 2a 0a 2a 2a 20 7b 46 31 36 32 37 38 7d 20 57  **.** {F16278} W
2cd90 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  hen [sqlite3_set
2cda0 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 44  _auxdata(C,N,P,D
2cdb0 29 5d 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74  )] is invoked, t
2cdc0 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a  he destructor.**
2cdd0 20 20 20 20 20 20 20 20 20 20 69 73 20 63 61 6c            is cal
2cde0 6c 65 64 20 66 6f 72 20 61 6e 79 20 70 72 69 6f  led for any prio
2cdf0 72 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63  r metadata assoc
2ce00 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 73  iated with the s
2ce10 61 6d 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ame function.** 
2ce20 20 20 20 20 20 20 20 20 20 63 6f 6e 74 65 78 74           context
2ce30 20 43 20 61 6e 64 20 70 61 72 61 6d 65 74 65 72   C and parameter
2ce40 20 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32 37   N..**.** {F1627
2ce50 39 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 63  9} SQLite will c
2ce60 61 6c 6c 20 64 65 73 74 72 75 63 74 6f 72 73 20  all destructors 
2ce70 66 6f 72 20 61 6e 79 20 6d 65 74 61 64 61 74 61  for any metadata
2ce80 20 69 74 20 69 73 20 68 6f 6c 64 69 6e 67 0a 2a   it is holding.*
2ce90 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 61 20  *          in a 
2cea0 70 61 72 74 69 63 75 6c 61 72 20 5b 70 72 65 70  particular [prep
2ceb0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2cec0 53 20 77 68 65 6e 20 65 69 74 68 65 72 0a 2a 2a  S when either.**
2ced0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
2cee0 65 33 5f 72 65 73 65 74 28 53 29 5d 20 6f 72 20  e3_reset(S)] or 
2cef0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2cf00 65 28 53 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e  e(S)] is called.
2cf10 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  .*/.void *sqlite
2cf20 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 73 71  3_get_auxdata(sq
2cf30 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
2cf40 69 6e 74 20 4e 29 3b 0a 76 6f 69 64 20 73 71 6c  int N);.void sql
2cf50 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
2cf60 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2cf70 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c  *, int N, void*,
2cf80 20 76 6f 69 64 20 28 2a 29 28 76 6f 69 64 2a 29   void (*)(void*)
2cf90 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  );.../*.** CAPI3
2cfa0 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74 73 20 44  REF: Constants D
2cfb0 65 66 69 6e 69 6e 67 20 53 70 65 63 69 61 6c 20  efining Special 
2cfc0 44 65 73 74 72 75 63 74 6f 72 20 42 65 68 61 76  Destructor Behav
2cfd0 69 6f 72 20 7b 46 31 30 32 38 30 7d 0a 2a 2a 0a  ior {F10280}.**.
2cfe0 2a 2a 20 54 68 65 73 65 20 61 72 65 20 73 70 65  ** These are spe
2cff0 63 69 61 6c 20 76 61 6c 75 65 20 66 6f 72 20 74  cial value for t
2d000 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 74 68  he destructor th
2d010 61 74 20 69 73 20 70 61 73 73 65 64 20 69 6e 20  at is passed in 
2d020 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20  as the.** final 
2d030 61 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74  argument to rout
2d040 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74  ines like [sqlit
2d050 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29  e3_result_blob()
2d060 5d 2e 20 20 49 66 20 74 68 65 20 64 65 73 74 72  ].  If the destr
2d070 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e  uctor.** argumen
2d080 74 20 69 73 20 53 51 4c 49 54 45 5f 53 54 41 54  t is SQLITE_STAT
2d090 49 43 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61  IC, it means tha
2d0a0 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f  t the content po
2d0b0 69 6e 74 65 72 20 69 73 20 63 6f 6e 73 74 61 6e  inter is constan
2d0c0 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65  t.** and will ne
2d0d0 76 65 72 20 63 68 61 6e 67 65 2e 20 20 49 74 20  ver change.  It 
2d0e0 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
2d0f0 20 62 65 20 64 65 73 74 72 6f 79 65 64 2e 20 20   be destroyed.  
2d100 54 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 54  The .** SQLITE_T
2d110 52 41 4e 53 49 45 4e 54 20 76 61 6c 75 65 20 6d  RANSIENT value m
2d120 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f  eans that the co
2d130 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c  ntent will likel
2d140 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74  y change in.** t
2d150 68 65 20 6e 65 61 72 20 66 75 74 75 72 65 20 61  he near future a
2d160 6e 64 20 74 68 61 74 20 53 51 4c 69 74 65 20 73  nd that SQLite s
2d170 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f  hould make its o
2d180 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20  wn private copy 
2d190 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e  of.** the conten
2d1a0 74 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69  t before returni
2d1b0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79  ng..**.** The ty
2d1c0 70 65 64 65 66 20 69 73 20 6e 65 63 65 73 73 61  pedef is necessa
2d1d0 72 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e  ry to work aroun
2d1e0 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65  d problems in ce
2d1f0 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d  rtain.** C++ com
2d200 70 69 6c 65 72 73 2e 20 20 53 65 65 20 74 69 63  pilers.  See tic
2d210 6b 65 74 20 23 32 31 39 31 2e 0a 2a 2f 0a 74 79  ket #2191..*/.ty
2d220 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c  pedef void (*sql
2d230 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f  ite3_destructor_
2d240 74 79 70 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64  type)(void*);.#d
2d250 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41  efine SQLITE_STA
2d260 54 49 43 20 20 20 20 20 20 28 28 73 71 6c 69 74  TIC      ((sqlit
2d270 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79  e3_destructor_ty
2d280 70 65 29 30 29 0a 23 64 65 66 69 6e 65 20 53 51  pe)0).#define SQ
2d290 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 20  LITE_TRANSIENT  
2d2a0 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72   ((sqlite3_destr
2d2b0 75 63 74 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a  uctor_type)-1)..
2d2c0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2d2d0 53 65 74 74 69 6e 67 20 54 68 65 20 52 65 73 75  Setting The Resu
2d2e0 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e  lt Of An SQL Fun
2d2f0 63 74 69 6f 6e 20 7b 46 31 36 34 30 30 7d 0a 2a  ction {F16400}.*
2d300 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
2d310 6e 65 73 20 61 72 65 20 75 73 65 64 20 62 79 20  nes are used by 
2d320 74 68 65 20 78 46 75 6e 63 20 6f 72 20 78 46 69  the xFunc or xFi
2d330 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 74 68  nal callbacks th
2d340 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20  at.** implement 
2d350 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e  SQL functions an
2d360 64 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 53  d aggregates.  S
2d370 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  ee.** [sqlite3_c
2d380 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
2d390 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
2d3a0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
2d3b0 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64 64 69 74  ()].** for addit
2d3c0 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
2d3d0 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66  n..**.** These f
2d3e0 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b 20 76 65  unctions work ve
2d3f0 72 79 20 6d 75 63 68 20 6c 69 6b 65 20 74 68 65  ry much like the
2d400 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69   .** [sqlite3_bi
2d410 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65  nd_blob | sqlite
2d420 33 5f 62 69 6e 64 5f 2a 5d 20 66 61 6d 69 6c 79  3_bind_*] family
2d430 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 20 75 73   of functions us
2d440 65 64 0a 2a 2a 20 74 6f 20 62 69 6e 64 20 76 61  ed.** to bind va
2d450 6c 75 65 73 20 74 6f 20 68 6f 73 74 20 70 61 72  lues to host par
2d460 61 6d 65 74 65 72 73 20 69 6e 20 70 72 65 70 61  ameters in prepa
2d470 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  red statements..
2d480 2a 2a 20 52 65 66 65 72 20 74 6f 20 74 68 65 0a  ** Refer to the.
2d490 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
2d4a0 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f  _blob | sqlite3_
2d4b0 62 69 6e 64 5f 2a 20 64 6f 63 75 6d 65 6e 74 61  bind_* documenta
2d4c0 74 69 6f 6e 5d 20 66 6f 72 0a 2a 2a 20 61 64 64  tion] for.** add
2d4d0 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74  itional informat
2d4e0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ion..**.** The s
2d4f0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
2d500 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  ob() interface s
2d510 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 66  ets the result f
2d520 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63  rom.** an applic
2d530 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75  ation defined fu
2d540 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65  nction to be the
2d550 20 42 4c 4f 42 20 77 68 6f 73 65 20 63 6f 6e 74   BLOB whose cont
2d560 65 6e 74 20 69 73 20 70 6f 69 6e 74 65 64 0a 2a  ent is pointed.*
2d570 2a 20 74 6f 20 62 79 20 74 68 65 20 73 65 63 6f  * to by the seco
2d580 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64  nd parameter and
2d590 20 77 68 69 63 68 20 69 73 20 4e 20 62 79 74 65   which is N byte
2d5a0 73 20 6c 6f 6e 67 20 77 68 65 72 65 20 4e 20 69  s long where N i
2d5b0 73 20 74 68 65 0a 2a 2a 20 74 68 69 72 64 20 70  s the.** third p
2d5c0 61 72 61 6d 65 74 65 72 2e 20 0a 2a 2a 20 54 68  arameter. .** Th
2d5d0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
2d5e0 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 69 6e 74 65  _zeroblob() inte
2d5f0 72 66 61 63 65 73 20 73 65 74 20 74 68 65 20 72  rfaces set the r
2d600 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20  esult of.** the 
2d610 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69  application defi
2d620 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
2d630 62 65 20 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69  be a BLOB contai
2d640 6e 69 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a  ning all zero.**
2d650 20 62 79 74 65 73 20 61 6e 64 20 4e 20 62 79 74   bytes and N byt
2d660 65 73 20 69 6e 20 73 69 7a 65 2c 20 77 68 65 72  es in size, wher
2d670 65 20 4e 20 69 73 20 74 68 65 20 76 61 6c 75 65  e N is the value
2d680 20 6f 66 20 74 68 65 20 32 6e 64 20 70 61 72 61   of the 2nd para
2d690 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  meter..**.** The
2d6a0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2d6b0 64 6f 75 62 6c 65 28 29 20 69 6e 74 65 72 66 61  double() interfa
2d6c0 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75  ce sets the resu
2d6d0 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70  lt from.** an ap
2d6e0 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65  plication define
2d6f0 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
2d700 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e   a floating poin
2d710 74 20 76 61 6c 75 65 20 73 70 65 63 69 66 69 65  t value specifie
2d720 64 0a 2a 2a 20 62 79 20 69 74 73 20 32 6e 64 20  d.** by its 2nd 
2d730 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
2d740 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
2d750 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73  lt_error() and s
2d760 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
2d770 72 6f 72 31 36 28 29 20 66 75 6e 63 74 69 6f 6e  ror16() function
2d780 73 0a 2a 2a 20 63 61 75 73 65 20 74 68 65 20 69  s.** cause the i
2d790 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20 66  mplemented SQL f
2d7a0 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77  unction to throw
2d7b0 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a   an exception..*
2d7c0 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 68  * SQLite uses th
2d7d0 65 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 64  e string pointed
2d7e0 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e   to by the.** 2n
2d7f0 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73  d parameter of s
2d800 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
2d810 72 6f 72 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ror() or sqlite3
2d820 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
2d830 29 0a 2a 2a 20 61 73 20 74 68 65 20 74 65 78 74  ).** as the text
2d840 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d 65 73   of an error mes
2d850 73 61 67 65 2e 20 20 53 51 4c 69 74 65 20 69 6e  sage.  SQLite in
2d860 74 65 72 70 72 65 74 73 20 74 68 65 20 65 72 72  terprets the err
2d870 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73 74  or.** message st
2d880 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65  ring from sqlite
2d890 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
2d8a0 20 61 73 20 55 54 46 38 2e 20 53 51 4c 69 74 65   as UTF8. SQLite
2d8b0 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 73 20 74  .** interprets t
2d8c0 68 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73  he string from s
2d8d0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
2d8e0 72 6f 72 31 36 28 29 20 61 73 20 55 54 46 31 36  ror16() as UTF16
2d8f0 20 69 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 62 79   in native.** by
2d900 74 65 20 6f 72 64 65 72 2e 20 20 49 66 20 74 68  te order.  If th
2d910 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
2d920 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73  r to sqlite3_res
2d930 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f  ult_error().** o
2d940 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
2d950 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 65  _error16() is ne
2d960 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69  gative then SQLi
2d970 74 65 20 74 61 6b 65 73 20 61 73 20 74 68 65 20  te takes as the 
2d980 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65  error.** message
2d990 20 61 6c 6c 20 74 65 78 74 20 75 70 20 74 68 72   all text up thr
2d9a0 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a  ough the first z
2d9b0 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a  ero character..*
2d9c0 2a 20 49 66 20 74 68 65 20 74 68 69 72 64 20 70  * If the third p
2d9d0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
2d9e0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
2d9f0 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  () or.** sqlite3
2da00 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
2da10 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  ) is non-negativ
2da20 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61  e then SQLite ta
2da30 6b 65 73 20 74 68 61 74 20 6d 61 6e 79 0a 2a 2a  kes that many.**
2da40 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72   bytes (not char
2da50 61 63 74 65 72 73 29 20 66 72 6f 6d 20 74 68 65  acters) from the
2da60 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61   2nd parameter a
2da70 73 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  s the error mess
2da80 61 67 65 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69  age..** The sqli
2da90 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
2daa0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72  () and sqlite3_r
2dab0 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a  esult_error16().
2dac0 2a 2a 20 72 6f 75 74 69 6e 65 73 20 6d 61 6b 65  ** routines make
2dad0 20 61 20 63 6f 70 79 20 70 72 69 76 61 74 65 20   a copy private 
2dae0 63 6f 70 79 20 6f 66 20 74 68 65 20 65 72 72 6f  copy of the erro
2daf0 72 20 6d 65 73 73 61 67 65 20 74 65 78 74 20 62  r message text b
2db00 65 66 6f 72 65 0a 2a 2a 20 74 68 65 79 20 72 65  efore.** they re
2db10 74 75 72 6e 2e 20 20 48 65 6e 63 65 2c 20 74 68  turn.  Hence, th
2db20 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69  e calling functi
2db30 6f 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63 61 74  on can deallocat
2db40 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79 20 74  e or.** modify t
2db50 68 65 20 74 65 78 74 20 61 66 74 65 72 20 74 68  he text after th
2db60 65 79 20 72 65 74 75 72 6e 20 77 69 74 68 6f 75  ey return withou
2db70 74 20 68 61 72 6d 2e 0a 2a 2a 20 54 68 65 20 73  t harm..** The s
2db80 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
2db90 72 6f 72 5f 63 6f 64 65 28 29 20 66 75 6e 63 74  ror_code() funct
2dba0 69 6f 6e 20 63 68 61 6e 67 65 73 20 74 68 65 20  ion changes the 
2dbb0 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 65  error code.** re
2dbc0 74 75 72 6e 65 64 20 62 79 20 53 51 4c 69 74 65  turned by SQLite
2dbd0 20 61 73 20 61 20 72 65 73 75 6c 74 20 6f 66 20   as a result of 
2dbe0 61 6e 20 65 72 72 6f 72 20 69 6e 20 61 20 66 75  an error in a fu
2dbf0 6e 63 74 69 6f 6e 2e 20 20 42 79 20 64 65 66 61  nction.  By defa
2dc00 75 6c 74 2c 0a 2a 2a 20 74 68 65 20 65 72 72 6f  ult,.** the erro
2dc10 72 20 63 6f 64 65 20 69 73 20 53 51 4c 49 54 45  r code is SQLITE
2dc20 5f 45 52 52 4f 52 2e 20 20 41 20 73 75 62 73 65  _ERROR.  A subse
2dc30 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71  quent call to sq
2dc40 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
2dc50 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  or().** or sqlit
2dc60 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
2dc70 36 28 29 20 72 65 73 65 74 73 20 74 68 65 20 65  6() resets the e
2dc80 72 72 6f 72 20 63 6f 64 65 20 74 6f 20 53 51 4c  rror code to SQL
2dc90 49 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a  ITE_ERROR..**.**
2dca0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
2dcb0 75 6c 74 5f 74 6f 6f 62 69 67 28 29 20 69 6e 74  ult_toobig() int
2dcc0 65 72 66 61 63 65 20 63 61 75 73 65 73 20 53 51  erface causes SQ
2dcd0 4c 69 74 65 0a 2a 2a 20 74 6f 20 74 68 72 6f 77  Lite.** to throw
2dce0 20 61 6e 20 65 72 72 6f 72 20 69 6e 64 69 63 61   an error indica
2dcf0 74 69 6e 67 20 74 68 61 74 20 61 20 73 74 72 69  ting that a stri
2dd00 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73 20 74 6f  ng or BLOB is to
2dd10 20 6c 6f 6e 67 0a 2a 2a 20 74 6f 20 72 65 70 72   long.** to repr
2dd20 65 73 65 6e 74 2e 20 20 54 68 65 20 73 71 6c 69  esent.  The sqli
2dd30 74 65 33 5f 72 65 73 75 6c 74 5f 6e 6f 6d 65 6d  te3_result_nomem
2dd40 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  () interface.** 
2dd50 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f  causes SQLite to
2dd60 20 74 68 72 6f 77 20 61 6e 20 65 78 63 65 70 74   throw an except
2dd70 69 6f 6e 20 69 6e 64 69 63 61 74 69 6e 67 20 74  ion indicating t
2dd80 68 61 74 20 74 68 65 20 61 0a 2a 2a 20 6d 65 6d  hat the a.** mem
2dd90 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
2dda0 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ailed..**.** The
2ddb0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2ddc0 69 6e 74 28 29 20 69 6e 74 65 72 66 61 63 65 20  int() interface 
2ddd0 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20  sets the return 
2dde0 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20  value.** of the 
2ddf0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2de00 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
2de10 62 65 20 74 68 65 20 33 32 2d 62 69 74 20 73 69  be the 32-bit si
2de20 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20  gned integer.** 
2de30 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74  value given in t
2de40 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e  he 2nd argument.
2de50 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
2de60 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 29 20 69  result_int64() i
2de70 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
2de80 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a  e return value.*
2de90 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  * of the applica
2dea0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
2deb0 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20  ction to be the 
2dec0 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  64-bit signed in
2ded0 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67  teger.** value g
2dee0 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20  iven in the 2nd 
2def0 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
2df00 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
2df10 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66  lt_null() interf
2df20 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74  ace sets the ret
2df30 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20  urn value.** of 
2df40 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
2df50 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
2df60 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a   to be NULL..**.
2df70 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
2df80 65 73 75 6c 74 5f 74 65 78 74 28 29 2c 20 73 71  esult_text(), sq
2df90 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
2dfa0 74 31 36 28 29 2c 20 0a 2a 2a 20 73 71 6c 69 74  t16(), .** sqlit
2dfb0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
2dfc0 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65  le(), and sqlite
2dfd0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62  3_result_text16b
2dfe0 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  e() interfaces.*
2dff0 2a 20 73 65 74 20 74 68 65 20 72 65 74 75 72 6e  * set the return
2e000 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 61 70   value of the ap
2e010 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2e020 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
2e030 0a 2a 2a 20 61 20 74 65 78 74 20 73 74 72 69 6e  .** a text strin
2e040 67 20 77 68 69 63 68 20 69 73 20 72 65 70 72 65  g which is repre
2e050 73 65 6e 74 65 64 20 61 73 20 55 54 46 2d 38 2c  sented as UTF-8,
2e060 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62   UTF-16 native b
2e070 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54  yte order,.** UT
2e080 46 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e 64 69  F-16 little endi
2e090 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69  an, or UTF-16 bi
2e0a0 67 20 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63  g endian, respec
2e0b0 74 69 76 65 6c 79 2e 0a 2a 2a 20 53 51 4c 69 74  tively..** SQLit
2e0c0 65 20 74 61 6b 65 73 20 74 68 65 20 74 65 78 74  e takes the text
2e0d0 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 74 68 65   result from the
2e0e0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 66 72 6f   application fro
2e0f0 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20 70 61 72  m.** the 2nd par
2e100 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20 73 71  ameter of the sq
2e110 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
2e120 74 2a 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a  t* interfaces..*
2e130 2a 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72  * If the 3rd par
2e140 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
2e150 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
2e160 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  t* interfaces.**
2e170 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
2e180 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20  en SQLite takes 
2e190 72 65 73 75 6c 74 20 74 65 78 74 20 66 72 6f 6d  result text from
2e1a0 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
2e1b0 65 72 20 0a 2a 2a 20 74 68 72 6f 75 67 68 20 74  er .** through t
2e1c0 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68  he first zero ch
2e1d0 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 66 20 74  aracter..** If t
2e1e0 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
2e1f0 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
2e200 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
2e210 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 6f  erfaces.** is no
2e220 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  n-negative, then
2e230 20 61 73 20 6d 61 6e 79 20 62 79 74 65 73 20 28   as many bytes (
2e240 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20  not characters) 
2e250 6f 66 20 74 68 65 20 74 65 78 74 0a 2a 2a 20 70  of the text.** p
2e260 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65  ointed to by the
2e270 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61   2nd parameter a
2e280 72 65 20 74 61 6b 65 6e 20 61 73 20 74 68 65 20  re taken as the 
2e290 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2e2a0 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ned.** function 
2e2b0 72 65 73 75 6c 74 2e 0a 2a 2a 20 49 66 20 74 68  result..** If th
2e2c0 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
2e2d0 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  to the sqlite3_r
2e2e0 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
2e2f0 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c  rfaces.** or sql
2e300 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
2e310 20 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70   is a non-NULL p
2e320 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c  ointer, then SQL
2e330 69 74 65 20 63 61 6c 6c 73 20 74 68 61 74 0a 2a  ite calls that.*
2e340 2a 20 66 75 6e 63 74 69 6f 6e 20 61 73 20 74 68  * function as th
2e350 65 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20  e destructor on 
2e360 74 68 65 20 74 65 78 74 20 6f 72 20 62 6c 6f 62  the text or blob
2e370 20 72 65 73 75 6c 74 20 77 68 65 6e 20 69 74 20   result when it 
2e380 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20  has.** finished 
2e390 75 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c  using that resul
2e3a0 74 2e 0a 2a 2a 20 49 66 20 74 68 65 20 34 74 68  t..** If the 4th
2e3b0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
2e3c0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
2e3d0 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
2e3e0 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  s.** or sqlite3_
2e3f0 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74  result_blob is t
2e400 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74  he special const
2e410 61 6e 74 20 53 51 4c 49 54 45 5f 53 54 41 54 49  ant SQLITE_STATI
2e420 43 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74  C, then.** SQLit
2e430 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74  e assumes that t
2e440 68 65 20 74 65 78 74 20 6f 72 20 62 6c 6f 62 20  he text or blob 
2e450 72 65 73 75 6c 74 20 69 73 20 63 6f 6e 73 74 61  result is consta
2e460 6e 74 20 73 70 61 63 65 20 61 6e 64 0a 2a 2a 20  nt space and.** 
2e470 64 6f 65 73 20 6e 6f 74 20 63 6f 70 79 20 74 68  does not copy th
2e480 65 20 73 70 61 63 65 20 6f 72 20 63 61 6c 6c 20  e space or call 
2e490 61 20 64 65 73 74 72 75 63 74 6f 72 20 77 68 65  a destructor whe
2e4a0 6e 20 69 74 20 68 61 73 0a 2a 2a 20 66 69 6e 69  n it has.** fini
2e4b0 73 68 65 64 20 75 73 69 6e 67 20 74 68 61 74 20  shed using that 
2e4c0 72 65 73 75 6c 74 2e 0a 2a 2a 20 49 66 20 74 68  result..** If th
2e4d0 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
2e4e0 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  to the sqlite3_r
2e4f0 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
2e500 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c  rfaces.** or sql
2e510 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
2e520 20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 20   is the special 
2e530 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f  constant SQLITE_
2e540 54 52 41 4e 53 49 45 4e 54 0a 2a 2a 20 74 68 65  TRANSIENT.** the
2e550 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61  n SQLite makes a
2e560 20 63 6f 70 79 20 6f 66 20 74 68 65 20 72 65 73   copy of the res
2e570 75 6c 74 20 69 6e 74 6f 20 73 70 61 63 65 20 6f  ult into space o
2e580 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20  btained from.** 
2e590 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
2e5a0 6c 6c 6f 63 28 29 5d 20 62 65 66 6f 72 65 20 69  lloc()] before i
2e5b0 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a  t returns..**.**
2e5c0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
2e5d0 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65  ult_value() inte
2e5e0 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
2e5f0 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20  esult of.** the 
2e600 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2e610 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
2e620 62 65 20 61 20 63 6f 70 79 20 74 68 65 0a 2a 2a  be a copy the.**
2e630 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
2e640 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2e650 65 63 74 20 73 70 65 63 69 66 69 65 64 20 62 79  ect specified by
2e660 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
2e670 65 72 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69  er.  The.** sqli
2e680 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
2e690 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 61 6b  () interface mak
2e6a0 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  es a copy of the
2e6b0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
2e6c0 0a 2a 2a 20 73 6f 20 74 68 61 74 20 5b 73 71 6c  .** so that [sql
2e6d0 69 74 65 33 5f 76 61 6c 75 65 5d 20 73 70 65 63  ite3_value] spec
2e6e0 69 66 69 65 64 20 69 6e 20 74 68 65 20 70 61 72  ified in the par
2e6f0 61 6d 65 74 65 72 20 6d 61 79 20 63 68 61 6e 67  ameter may chang
2e700 65 20 6f 72 0a 2a 2a 20 62 65 20 64 65 61 6c 6c  e or.** be deall
2e710 6f 63 61 74 65 64 20 61 66 74 65 72 20 73 71 6c  ocated after sql
2e720 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
2e730 65 28 29 20 72 65 74 75 72 6e 73 20 77 69 74 68  e() returns with
2e740 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 41 20 5b  out harm..** A [
2e750 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2e760 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
2e770 6d 61 79 20 61 6c 77 61 79 73 20 62 65 20 75 73  may always be us
2e780 65 64 20 77 68 65 72 65 20 61 6e 0a 2a 2a 20 5b  ed where an.** [
2e790 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
2e7a0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
2e7b0 74 20 69 73 20 72 65 71 75 69 72 65 64 2c 20 73  t is required, s
2e7c0 6f 20 65 69 74 68 65 72 0a 2a 2a 20 6b 69 6e 64  o either.** kind
2e7d0 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c   of [sqlite3_val
2e7e0 75 65 5d 20 6f 62 6a 65 63 74 20 63 61 6e 20 62  ue] object can b
2e7f0 65 20 75 73 65 64 20 77 69 74 68 20 74 68 69 73  e used with this
2e800 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
2e810 2a 20 49 66 20 74 68 65 73 65 20 72 6f 75 74 69  * If these routi
2e820 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 66  nes are called f
2e830 72 6f 6d 20 77 69 74 68 69 6e 20 74 68 65 20 64  rom within the d
2e840 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 20  ifferent thread 
2e850 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f 6e 65  .** than the one
2e860 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
2e870 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2e880 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 68 61  ned function tha
2e890 74 20 72 65 63 65 69 76 65 64 0a 2a 2a 20 74 68  t received.** th
2e8a0 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  e [sqlite3_conte
2e8b0 78 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74 68 65  xt] pointer, the
2e8c0 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
2e8d0 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e  efined..**.** IN
2e8e0 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
2e8f0 7b 46 31 36 34 30 33 7d 20 54 68 65 20 64 65 66  {F16403} The def
2e900 61 75 6c 74 20 72 65 74 75 72 6e 20 76 61 6c 75  ault return valu
2e910 65 20 66 72 6f 6d 20 61 6e 79 20 53 51 4c 20 66  e from any SQL f
2e920 75 6e 63 74 69 6f 6e 20 69 73 20 4e 55 4c 4c 2e  unction is NULL.
2e930 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 30 36 7d 20  .**.** {F16406} 
2e940 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
2e950 75 6c 74 5f 62 6c 6f 62 28 43 2c 56 2c 4e 2c 44  ult_blob(C,V,N,D
2e960 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61  )] interface cha
2e970 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  nges the.**     
2e980 20 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75       return valu
2e990 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20  e of function C 
2e9a0 74 6f 20 62 65 20 61 20 62 6c 6f 62 20 74 68 61  to be a blob tha
2e9b0 74 20 69 73 20 4e 20 62 79 74 65 73 0a 2a 2a 20  t is N bytes.** 
2e9c0 20 20 20 20 20 20 20 20 20 69 6e 20 6c 65 6e 67           in leng
2e9d0 74 68 20 61 6e 64 20 77 69 74 68 20 63 6f 6e 74  th and with cont
2e9e0 65 6e 74 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  ent pointed to b
2e9f0 79 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34  y V..**.** {F164
2ea00 30 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  09} The [sqlite3
2ea10 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 43  _result_double(C
2ea20 2c 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  ,V)] interface c
2ea30 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20  hanges the.**   
2ea40 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 61         return va
2ea50 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20  lue of function 
2ea60 43 20 74 6f 20 62 65 20 74 68 65 20 66 6c 6f 61  C to be the floa
2ea70 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65  ting point value
2ea80 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 31   V..**.** {F1641
2ea90 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  2} The [sqlite3_
2eaa0 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 43 2c 56  result_error(C,V
2eab0 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  ,N)] interface c
2eac0 68 61 6e 67 65 73 20 74 68 65 20 72 65 74 75 72  hanges the retur
2ead0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61  n.**          va
2eae0 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20  lue of function 
2eaf0 43 20 74 6f 20 62 65 20 61 6e 20 65 78 63 65 70  C to be an excep
2eb00 74 69 6f 6e 20 77 69 74 68 20 65 72 72 6f 72 20  tion with error 
2eb10 63 6f 64 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  code.**         
2eb20 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
2eb30 61 6e 64 20 61 20 55 54 46 38 20 65 72 72 6f 72  and a UTF8 error
2eb40 20 6d 65 73 73 61 67 65 20 63 6f 70 69 65 64 20   message copied 
2eb50 66 72 6f 6d 20 56 20 75 70 20 74 6f 20 74 68 65  from V up to the
2eb60 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 72  .**          fir
2eb70 73 74 20 7a 65 72 6f 20 62 79 74 65 20 6f 72 20  st zero byte or 
2eb80 75 6e 74 69 6c 20 4e 20 62 79 74 65 73 20 61 72  until N bytes ar
2eb90 65 20 72 65 61 64 20 69 66 20 4e 20 69 73 20 70  e read if N is p
2eba0 6f 73 69 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b  ositive..**.** {
2ebb0 46 31 36 34 31 35 7d 20 54 68 65 20 5b 73 71 6c  F16415} The [sql
2ebc0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
2ebd0 72 31 36 28 43 2c 56 2c 4e 29 5d 20 69 6e 74 65  r16(C,V,N)] inte
2ebe0 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68  rface changes th
2ebf0 65 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20  e return.**     
2ec00 20 20 20 20 20 76 61 6c 75 65 20 6f 66 20 66 75       value of fu
2ec10 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 61  nction C to be a
2ec20 6e 20 65 78 63 65 70 74 69 6f 6e 20 77 69 74 68  n exception with
2ec30 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 20   error code.**  
2ec40 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f          [SQLITE_
2ec50 45 52 52 4f 52 5d 20 61 6e 64 20 61 20 55 54 46  ERROR] and a UTF
2ec60 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  16 native byte o
2ec70 72 64 65 72 20 65 72 72 6f 72 20 6d 65 73 73 61  rder error messa
2ec80 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63  ge.**          c
2ec90 6f 70 69 65 64 20 66 72 6f 6d 20 56 20 75 70 20  opied from V up 
2eca0 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72  to the first zer
2ecb0 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 6f 72 20  o terminator or 
2ecc0 75 6e 74 69 6c 20 4e 20 62 79 74 65 73 0a 2a 2a  until N bytes.**
2ecd0 20 20 20 20 20 20 20 20 20 20 61 72 65 20 72 65            are re
2ece0 61 64 20 69 66 20 4e 20 69 73 20 70 6f 73 69 74  ad if N is posit
2ecf0 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34  ive..**.** {F164
2ed00 31 38 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  18} The [sqlite3
2ed10 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f  _result_error_to
2ed20 6f 62 69 67 28 43 29 5d 20 69 6e 74 65 72 66 61  obig(C)] interfa
2ed30 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 20 72  ce changes the r
2ed40 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20  eturn.**        
2ed50 20 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 66    value of the f
2ed60 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20  unction C to be 
2ed70 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 77 69 74  an exception wit
2ed80 68 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20  h error code.** 
2ed90 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45           [SQLITE
2eda0 5f 54 4f 4f 42 49 47 5d 20 61 6e 64 20 61 6e 20  _TOOBIG] and an 
2edb0 61 70 70 72 6f 70 72 69 61 74 65 20 65 72 72 6f  appropriate erro
2edc0 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a  r message..**.**
2edd0 20 7b 46 31 36 34 32 31 7d 20 54 68 65 20 5b 73   {F16421} The [s
2ede0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
2edf0 72 6f 72 5f 6e 6f 6d 65 6d 28 43 29 5d 20 69 6e  ror_nomem(C)] in
2ee00 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20  terface changes 
2ee10 74 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20  the return.**   
2ee20 20 20 20 20 20 20 20 76 61 6c 75 65 20 6f 66 20         value of 
2ee30 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 43 20 74  the function C t
2ee40 6f 20 62 65 20 61 6e 20 65 78 63 65 70 74 69 6f  o be an exceptio
2ee50 6e 20 77 69 74 68 20 65 72 72 6f 72 20 63 6f 64  n with error cod
2ee60 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53  e.**          [S
2ee70 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 61 6e 64  QLITE_NOMEM] and
2ee80 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20   an appropriate 
2ee90 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a  error message..*
2eea0 2a 0a 2a 2a 20 7b 46 31 36 34 32 34 7d 20 54 68  *.** {F16424} Th
2eeb0 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  e [sqlite3_resul
2eec0 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 43 2c 45  t_error_code(C,E
2eed0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61  )] interface cha
2eee0 6e 67 65 73 20 74 68 65 20 72 65 74 75 72 6e 0a  nges the return.
2eef0 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c 75  **          valu
2ef00 65 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f  e of the functio
2ef10 6e 20 43 20 74 6f 20 62 65 20 61 6e 20 65 78 63  n C to be an exc
2ef20 65 70 74 69 6f 6e 20 77 69 74 68 20 65 72 72 6f  eption with erro
2ef30 72 20 63 6f 64 65 20 45 2e 0a 2a 2a 20 20 20 20  r code E..**    
2ef40 20 20 20 20 20 20 54 68 65 20 65 72 72 6f 72 20        The error 
2ef50 6d 65 73 73 61 67 65 20 74 65 78 74 20 69 73 20  message text is 
2ef60 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a  unchanged..**.**
2ef70 20 7b 46 31 36 34 32 37 7d 20 54 68 65 20 5b 73   {F16427} The [s
2ef80 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
2ef90 74 28 43 2c 56 29 5d 20 69 6e 74 65 72 66 61 63  t(C,V)] interfac
2efa0 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a  e changes the.**
2efb0 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e            return
2efc0 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69   value of functi
2efd0 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65 20 33  on C to be the 3
2efe0 32 2d 62 69 74 20 69 6e 74 65 67 65 72 20 76 61  2-bit integer va
2eff0 6c 75 65 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  lue V..**.** {F1
2f000 36 34 33 30 7d 20 54 68 65 20 5b 73 71 6c 69 74  6430} The [sqlit
2f010 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28  e3_result_int64(
2f020 43 2c 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20  C,V)] interface 
2f030 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20  changes the.**  
2f040 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 76          return v
2f050 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e  alue of function
2f060 20 43 20 74 6f 20 62 65 20 74 68 65 20 36 34 2d   C to be the 64-
2f070 62 69 74 20 69 6e 74 65 67 65 72 20 76 61 6c 75  bit integer valu
2f080 65 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34  e V..**.** {F164
2f090 33 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  33} The [sqlite3
2f0a0 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 43 29 5d  _result_null(C)]
2f0b0 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67   interface chang
2f0c0 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  es the.**       
2f0d0 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20     return value 
2f0e0 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f  of function C to
2f0f0 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   be NULL..**.** 
2f100 7b 46 31 36 34 33 36 7d 20 54 68 65 20 5b 73 71  {F16436} The [sq
2f110 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
2f120 74 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74 65  t(C,V,N,D)] inte
2f130 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68  rface changes th
2f140 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  e.**          re
2f150 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75  turn value of fu
2f160 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74  nction C to be t
2f170 68 65 20 55 54 46 38 20 73 74 72 69 6e 67 0a 2a  he UTF8 string.*
2f180 2a 20 20 20 20 20 20 20 20 20 20 56 20 75 70 20  *          V up 
2f190 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72  to the first zer
2f1a0 6f 20 69 66 20 4e 20 69 73 20 6e 65 67 61 74 69  o if N is negati
2f1b0 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  ve.**          o
2f1c0 72 20 74 68 65 20 66 69 72 73 74 20 4e 20 62 79  r the first N by
2f1d0 74 65 73 20 6f 66 20 56 20 69 66 20 4e 20 69 73  tes of V if N is
2f1e0 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2e 0a 2a   non-negative..*
2f1f0 2a 0a 2a 2a 20 7b 46 31 36 34 33 39 7d 20 54 68  *.** {F16439} Th
2f200 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  e [sqlite3_resul
2f210 74 5f 74 65 78 74 31 36 28 43 2c 56 2c 4e 2c 44  t_text16(C,V,N,D
2f220 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61  )] interface cha
2f230 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  nges the.**     
2f240 20 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75       return valu
2f250 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20  e of function C 
2f260 74 6f 20 62 65 20 74 68 65 20 55 54 46 31 36 20  to be the UTF16 
2f270 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
2f280 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74  r.**          st
2f290 72 69 6e 67 20 56 20 75 70 20 74 6f 20 74 68 65  ring V up to the
2f2a0 20 66 69 72 73 74 20 7a 65 72 6f 20 69 66 20 4e   first zero if N
2f2b0 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   is.**          
2f2c0 6e 65 67 61 74 69 76 65 20 6f 72 20 74 68 65 20  negative or the 
2f2d0 66 69 72 73 74 20 4e 20 62 79 74 65 73 20 6f 66  first N bytes of
2f2e0 20 56 20 69 66 20 4e 20 69 73 20 6e 6f 6e 2d 6e   V if N is non-n
2f2f0 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b  egative..**.** {
2f300 46 31 36 34 34 32 7d 20 54 68 65 20 5b 73 71 6c  F16442} The [sql
2f310 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
2f320 31 36 62 65 28 43 2c 56 2c 4e 2c 44 29 5d 20 69  16be(C,V,N,D)] i
2f330 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73  nterface changes
2f340 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
2f350 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
2f360 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62   function C to b
2f370 65 20 74 68 65 20 55 54 46 31 36 20 62 69 67 2d  e the UTF16 big-
2f380 65 6e 64 69 61 6e 0a 2a 2a 20 20 20 20 20 20 20  endian.**       
2f390 20 20 20 73 74 72 69 6e 67 20 56 20 75 70 20 74     string V up t
2f3a0 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f  o the first zero
2f3b0 20 69 66 20 4e 20 69 73 0a 2a 2a 20 20 20 20 20   if N is.**     
2f3c0 20 20 20 20 20 69 73 20 6e 65 67 61 74 69 76 65       is negative
2f3d0 20 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e 20   or the first N 
2f3e0 62 79 74 65 73 20 6f 72 20 56 20 69 66 20 4e 20  bytes or V if N 
2f3f0 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2e  is non-negative.
2f400 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 34 35 7d 20  .**.** {F16445} 
2f410 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
2f420 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 43 2c 56  ult_text16le(C,V
2f430 2c 4e 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65  ,N,D)] interface
2f440 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20   changes the.** 
2f450 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20           return 
2f460 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f  value of functio
2f470 6e 20 43 20 74 6f 20 62 65 20 74 68 65 20 55 54  n C to be the UT
2f480 46 31 36 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61  F16 little-endia
2f490 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74  n.**          st
2f4a0 72 69 6e 67 20 56 20 75 70 20 74 6f 20 74 68 65  ring V up to the
2f4b0 20 66 69 72 73 74 20 7a 65 72 6f 20 69 66 20 4e   first zero if N
2f4c0 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   is.**          
2f4d0 6e 65 67 61 74 69 76 65 20 6f 72 20 74 68 65 20  negative or the 
2f4e0 66 69 72 73 74 20 4e 20 62 79 74 65 73 20 6f 66  first N bytes of
2f4f0 20 56 20 69 66 20 4e 20 69 73 20 6e 6f 6e 2d 6e   V if N is non-n
2f500 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b  egative..**.** {
2f510 46 31 36 34 34 38 7d 20 54 68 65 20 5b 73 71 6c  F16448} The [sql
2f520 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
2f530 65 28 43 2c 56 29 5d 20 69 6e 74 65 72 66 61 63  e(C,V)] interfac
2f540 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a  e changes the.**
2f550 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e            return
2f560 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69   value of functi
2f570 6f 6e 20 43 20 74 6f 20 62 65 20 5b 75 6e 70 72  on C to be [unpr
2f580 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2f590 76 61 6c 75 65 5d 0a 2a 2a 20 20 20 20 20 20 20  value].**       
2f5a0 20 20 20 6f 62 6a 65 63 74 20 56 2e 0a 2a 2a 0a     object V..**.
2f5b0 2a 2a 20 7b 46 31 36 34 35 31 7d 20 54 68 65 20  ** {F16451} The 
2f5c0 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
2f5d0 7a 65 72 6f 62 6c 6f 62 28 43 2c 4e 29 5d 20 69  zeroblob(C,N)] i
2f5e0 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73  nterface changes
2f5f0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
2f600 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
2f610 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62   function C to b
2f620 65 20 61 6e 20 4e 2d 62 79 74 65 20 62 6c 6f 62  e an N-byte blob
2f630 20 6f 66 20 61 6c 6c 20 7a 65 72 6f 73 2e 0a 2a   of all zeros..*
2f640 2a 0a 2a 2a 20 7b 46 31 36 34 35 34 7d 20 54 68  *.** {F16454} Th
2f650 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  e [sqlite3_resul
2f660 74 5f 65 72 72 6f 72 28 29 5d 20 61 6e 64 20 5b  t_error()] and [
2f670 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
2f680 72 72 6f 72 31 36 28 29 5d 0a 2a 2a 20 20 20 20  rror16()].**    
2f690 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73        interfaces
2f6a0 20 6d 61 6b 65 20 61 20 63 6f 70 79 20 6f 66 20   make a copy of 
2f6b0 74 68 65 69 72 20 65 72 72 6f 72 20 6d 65 73 73  their error mess
2f6c0 61 67 65 20 73 74 72 69 6e 67 73 20 62 65 66 6f  age strings befo
2f6d0 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  re.**          r
2f6e0 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  eturning..**.** 
2f6f0 7b 46 31 36 34 35 37 7d 20 49 66 20 74 68 65 20  {F16457} If the 
2f700 44 20 64 65 73 74 72 75 63 74 6f 72 20 70 61 72  D destructor par
2f710 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
2f720 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 43  e3_result_blob(C
2f730 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20  ,V,N,D)],.**    
2f740 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72        [sqlite3_r
2f750 65 73 75 6c 74 5f 74 65 78 74 28 43 2c 56 2c 4e  esult_text(C,V,N
2f760 2c 44 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 72  ,D)], [sqlite3_r
2f770 65 73 75 6c 74 5f 74 65 78 74 31 36 28 43 2c 56  esult_text16(C,V
2f780 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20  ,N,D)],.**      
2f790 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73      [sqlite3_res
2f7a0 75 6c 74 5f 74 65 78 74 31 36 62 65 28 43 2c 56  ult_text16be(C,V
2f7b0 2c 4e 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20  ,N,D)], or.**   
2f7c0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
2f7d0 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28  result_text16le(
2f7e0 43 2c 56 2c 4e 2c 44 29 5d 20 69 73 20 74 68 65  C,V,N,D)] is the
2f7f0 20 63 6f 6e 73 74 61 6e 74 20 5b 53 51 4c 49 54   constant [SQLIT
2f800 45 5f 53 54 41 54 49 43 5d 0a 2a 2a 20 20 20 20  E_STATIC].**    
2f810 20 20 20 20 20 20 74 68 65 6e 20 6e 6f 20 64 65        then no de
2f820 73 74 72 75 63 74 6f 72 20 69 73 20 65 76 65 72  structor is ever
2f830 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 70   called on the p
2f840 6f 69 6e 74 65 72 20 56 20 61 6e 64 20 53 51 4c  ointer V and SQL
2f850 69 74 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ite.**          
2f860 61 73 73 75 6d 65 73 20 74 68 61 74 20 56 20 69  assumes that V i
2f870 73 20 69 6d 6d 75 74 61 62 6c 65 2e 0a 2a 2a 0a  s immutable..**.
2f880 2a 2a 20 7b 46 31 36 34 36 30 7d 20 49 66 20 74  ** {F16460} If t
2f890 68 65 20 44 20 64 65 73 74 72 75 63 74 6f 72 20  he D destructor 
2f8a0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
2f8b0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
2f8c0 62 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20  b(C,V,N,D)],.** 
2f8d0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
2f8e0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 43 2c  3_result_text(C,
2f8f0 56 2c 4e 2c 44 29 5d 2c 20 5b 73 71 6c 69 74 65  V,N,D)], [sqlite
2f900 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28  3_result_text16(
2f910 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20  C,V,N,D)],.**   
2f920 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
2f930 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28  result_text16be(
2f940 43 2c 56 2c 4e 2c 44 29 5d 2c 20 6f 72 0a 2a 2a  C,V,N,D)], or.**
2f950 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
2f960 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
2f970 6c 65 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 73 20  le(C,V,N,D)] is 
2f980 74 68 65 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20  the constant.** 
2f990 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45           [SQLITE
2f9a0 5f 54 52 41 4e 53 49 45 4e 54 5d 20 74 68 65 6e  _TRANSIENT] then
2f9b0 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 73 20   the interfaces 
2f9c0 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20  makes a copy of 
2f9d0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
2f9e0 63 6f 6e 74 65 6e 74 20 6f 66 20 56 20 61 6e 64  content of V and
2f9f0 20 72 65 74 61 69 6e 73 20 74 68 65 20 63 6f 70   retains the cop
2fa00 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 36 33  y..**.** {F16463
2fa10 7d 20 49 66 20 74 68 65 20 44 20 64 65 73 74 72  } If the D destr
2fa20 75 63 74 6f 72 20 70 61 72 61 6d 65 74 65 72 20  uctor parameter 
2fa30 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  to [sqlite3_resu
2fa40 6c 74 5f 62 6c 6f 62 28 43 2c 56 2c 4e 2c 44 29  lt_blob(C,V,N,D)
2fa50 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ],.**          [
2fa60 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
2fa70 65 78 74 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 5b  ext(C,V,N,D)], [
2fa80 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
2fa90 65 78 74 31 36 28 43 2c 56 2c 4e 2c 44 29 5d 2c  ext16(C,V,N,D)],
2faa0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
2fab0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
2fac0 74 31 36 62 65 28 43 2c 56 2c 4e 2c 44 29 5d 2c  t16be(C,V,N,D)],
2fad0 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   or.**          
2fae0 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
2faf0 74 65 78 74 31 36 6c 65 28 43 2c 56 2c 4e 2c 44  text16le(C,V,N,D
2fb00 29 5d 20 69 73 20 73 6f 6d 65 20 76 61 6c 75 65  )] is some value
2fb10 20 6f 74 68 65 72 20 74 68 61 6e 0a 2a 2a 20 20   other than.**  
2fb20 20 20 20 20 20 20 20 20 74 68 65 20 63 6f 6e 73          the cons
2fb30 74 61 6e 74 73 20 5b 53 51 4c 49 54 45 5f 53 54  tants [SQLITE_ST
2fb40 41 54 49 43 5d 20 61 6e 64 20 5b 53 51 4c 49 54  ATIC] and [SQLIT
2fb50 45 5f 54 52 41 4e 53 49 45 4e 54 5d 20 74 68 65  E_TRANSIENT] the
2fb60 6e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53  n .**          S
2fb70 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b  QLite will invok
2fb80 65 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  e the destructor
2fb90 20 44 20 77 69 74 68 20 56 20 61 73 20 69 74 73   D with V as its
2fba0 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74 0a 2a   only argument.*
2fbb0 2a 20 20 20 20 20 20 20 20 20 20 77 68 65 6e 20  *          when 
2fbc0 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  it has finished 
2fbd0 77 69 74 68 20 74 68 65 20 56 20 76 61 6c 75 65  with the V value
2fbe0 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  ..*/.void sqlite
2fbf0 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71  3_result_blob(sq
2fc00 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
2fc10 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
2fc20 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
2fc30 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
2fc40 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71  result_double(sq
2fc50 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
2fc60 64 6f 75 62 6c 65 29 3b 0a 76 6f 69 64 20 73 71  double);.void sq
2fc70 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
2fc80 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  or(sqlite3_conte
2fc90 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  xt*, const char*
2fca0 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c  , int);.void sql
2fcb0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
2fcc0 72 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  r16(sqlite3_cont
2fcd0 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ext*, const void
2fce0 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71  *, int);.void sq
2fcf0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
2fd00 6f 72 5f 74 6f 6f 62 69 67 28 73 71 6c 69 74 65  or_toobig(sqlite
2fd10 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69  3_context*);.voi
2fd20 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
2fd30 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c  _error_nomem(sql
2fd40 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
2fd50 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
2fd60 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73  ult_error_code(s
2fd70 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2fd80 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69   int);.void sqli
2fd90 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73  te3_result_int(s
2fda0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2fdb0 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69   int);.void sqli
2fdc0 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34  te3_result_int64
2fdd0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2fde0 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
2fdf0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
2fe00 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69  result_null(sqli
2fe10 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76  te3_context*);.v
2fe20 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
2fe30 6c 74 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f  lt_text(sqlite3_
2fe40 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
2fe50 63 68 61 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64  char*, int, void
2fe60 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69  (*)(void*));.voi
2fe70 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
2fe80 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f  _text16(sqlite3_
2fe90 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
2fea0 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64  void*, int, void
2feb0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69  (*)(void*));.voi
2fec0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
2fed0 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65  _text16le(sqlite
2fee0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
2fef0 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69  t void*, int,voi
2ff00 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f  d(*)(void*));.vo
2ff10 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
2ff20 74 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74  t_text16be(sqlit
2ff30 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
2ff40 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f  st void*, int,vo
2ff50 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76  id(*)(void*));.v
2ff60 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
2ff70 6c 74 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33  lt_value(sqlite3
2ff80 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74  _context*, sqlit
2ff90 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f 69 64  e3_value*);.void
2ffa0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2ffb0 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33  zeroblob(sqlite3
2ffc0 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e  _context*, int n
2ffd0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2ffe0 45 46 3a 20 44 65 66 69 6e 65 20 4e 65 77 20 43  EF: Define New C
2fff0 6f 6c 6c 61 74 69 6e 67 20 53 65 71 75 65 6e 63  ollating Sequenc
30000 65 73 20 7b 46 31 36 36 30 30 7d 0a 2a 2a 0a 2a  es {F16600}.**.*
30010 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  * These function
30020 73 20 61 72 65 20 75 73 65 64 20 74 6f 20 61 64  s are used to ad
30030 64 20 6e 65 77 20 63 6f 6c 6c 61 74 69 6f 6e 20  d new collation 
30040 73 65 71 75 65 6e 63 65 73 20 74 6f 20 74 68 65  sequences to the
30050 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 2a 5d 20 68  .** [sqlite3*] h
30060 61 6e 64 6c 65 20 73 70 65 63 69 66 69 65 64 20  andle specified 
30070 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67  as the first arg
30080 75 6d 65 6e 74 2e 20 0a 2a 2a 0a 2a 2a 20 54 68  ument. .**.** Th
30090 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6e 65  e name of the ne
300a0 77 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  w collation sequ
300b0 65 6e 63 65 20 69 73 20 73 70 65 63 69 66 69 65  ence is specifie
300c0 64 20 61 73 20 61 20 55 54 46 2d 38 20 73 74 72  d as a UTF-8 str
300d0 69 6e 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74  ing.** for sqlit
300e0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
300f0 69 6f 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ion() and sqlite
30100 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
30110 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20 61  on_v2().** and a
30120 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 66   UTF-16 string f
30130 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  or sqlite3_creat
30140 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e  e_collation16().
30150 20 49 6e 20 61 6c 6c 20 63 61 73 65 73 0a 2a 2a   In all cases.**
30160 20 74 68 65 20 6e 61 6d 65 20 69 73 20 70 61 73   the name is pas
30170 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  sed as the secon
30180 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d  d function argum
30190 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  ent..**.** The t
301a0 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 6d 61  hird argument ma
301b0 79 20 62 65 20 6f 6e 65 20 6f 66 20 74 68 65 20  y be one of the 
301c0 63 6f 6e 73 74 61 6e 74 73 20 5b 53 51 4c 49 54  constants [SQLIT
301d0 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 5b 53 51 4c  E_UTF8],.** [SQL
301e0 49 54 45 5f 55 54 46 31 36 4c 45 5d 20 6f 72 20  ITE_UTF16LE] or 
301f0 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d  [SQLITE_UTF16BE]
30200 2c 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61  , indicating tha
30210 74 20 74 68 65 20 75 73 65 72 2d 73 75 70 70 6c  t the user-suppl
30220 69 65 64 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 65  ied.** routine e
30230 78 70 65 63 74 73 20 74 6f 20 62 65 20 70 61 73  xpects to be pas
30240 73 65 64 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  sed pointers to 
30250 73 74 72 69 6e 67 73 20 65 6e 63 6f 64 65 64 20  strings encoded 
30260 75 73 69 6e 67 20 55 54 46 2d 38 2c 0a 2a 2a 20  using UTF-8,.** 
30270 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 2d 65 6e  UTF-16 little-en
30280 64 69 61 6e 20 6f 72 20 55 54 46 2d 31 36 20 62  dian or UTF-16 b
30290 69 67 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 63  ig-endian respec
302a0 74 69 76 65 6c 79 2e 20 54 68 65 0a 2a 2a 20 74  tively. The.** t
302b0 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 6d 69  hird argument mi
302c0 67 68 74 20 61 6c 73 6f 20 62 65 20 5b 53 51 4c  ght also be [SQL
302d0 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45  ITE_UTF16_ALIGNE
302e0 44 5d 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  D] to indicate t
302f0 68 61 74 0a 2a 2a 20 74 68 65 20 72 6f 75 74 69  hat.** the routi
30300 6e 65 20 65 78 70 65 63 74 73 20 70 6f 69 6e 74  ne expects point
30310 65 72 73 20 74 6f 20 31 36 2d 62 69 74 20 77 6f  ers to 16-bit wo
30320 72 64 20 61 6c 69 67 6e 65 64 20 73 74 72 69 6e  rd aligned strin
30330 67 73 0a 2a 2a 20 6f 66 20 55 54 46 31 36 20 69  gs.** of UTF16 i
30340 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74  n the native byt
30350 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68  e order of the h
30360 6f 73 74 20 63 6f 6d 70 75 74 65 72 2e 0a 2a 2a  ost computer..**
30370 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f  .** A pointer to
30380 20 74 68 65 20 75 73 65 72 20 73 75 70 70 6c 69   the user suppli
30390 65 64 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20  ed routine must 
303a0 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  be passed as the
303b0 20 66 69 66 74 68 0a 2a 2a 20 61 72 67 75 6d 65   fifth.** argume
303c0 6e 74 2e 20 20 49 66 20 69 74 20 69 73 20 4e 55  nt.  If it is NU
303d0 4c 4c 2c 20 74 68 69 73 20 69 73 20 74 68 65 20  LL, this is the 
303e0 73 61 6d 65 20 61 73 20 64 65 6c 65 74 69 6e 67  same as deleting
303f0 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a   the collation.*
30400 2a 20 73 65 71 75 65 6e 63 65 20 28 73 6f 20 74  * sequence (so t
30410 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 6e 6f  hat SQLite canno
30420 74 20 63 61 6c 6c 20 69 74 20 61 6e 79 6d 6f 72  t call it anymor
30430 65 29 2e 0a 2a 2a 20 45 61 63 68 20 74 69 6d 65  e)..** Each time
30440 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
30450 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20 66 75 6e  .** supplied fun
30460 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64  ction is invoked
30470 2c 20 69 74 20 69 73 20 70 61 73 73 65 64 20 61  , it is passed a
30480 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69   copy of the voi
30490 64 2a 20 70 61 73 73 65 64 20 61 73 0a 2a 2a 20  d* passed as.** 
304a0 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d  the fourth argum
304b0 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  ent to sqlite3_c
304c0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
304d0 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ) or.** sqlite3_
304e0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
304f0 31 36 28 29 20 61 73 20 69 74 73 20 66 69 72 73  16() as its firs
30500 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  t parameter..**.
30510 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67  ** The remaining
30520 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
30530 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75  e application-su
30540 70 70 6c 69 65 64 20 72 6f 75 74 69 6e 65 20 61  pplied routine a
30550 72 65 20 74 77 6f 20 73 74 72 69 6e 67 73 2c 0a  re two strings,.
30560 2a 2a 20 65 61 63 68 20 72 65 70 72 65 73 65 6e  ** each represen
30570 74 65 64 20 62 79 20 61 20 28 6c 65 6e 67 74 68  ted by a (length
30580 2c 20 64 61 74 61 29 20 70 61 69 72 20 61 6e 64  , data) pair and
30590 20 65 6e 63 6f 64 65 64 20 69 6e 20 74 68 65 20   encoded in the 
305a0 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 74 68 61 74  encoding.** that
305b0 20 77 61 73 20 70 61 73 73 65 64 20 61 73 20 74   was passed as t
305c0 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
305d0 74 20 77 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61  t when the colla
305e0 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 77 61  tion sequence wa
305f0 73 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 2e  s.** registered.
30600 20 7b 45 4e 44 7d 20 54 68 65 20 61 70 70 6c 69   {END} The appli
30610 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 63  cation defined c
30620 6f 6c 6c 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  ollation routine
30630 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72   should.** retur
30640 6e 20 6e 65 67 61 74 69 76 65 2c 20 7a 65 72 6f  n negative, zero
30650 20 6f 72 20 70 6f 73 69 74 69 76 65 20 69 66 0a   or positive if.
30660 2a 2a 20 74 68 65 20 66 69 72 73 74 20 73 74 72  ** the first str
30670 69 6e 67 20 69 73 20 6c 65 73 73 20 74 68 61 6e  ing is less than
30680 2c 20 65 71 75 61 6c 20 74 6f 2c 20 6f 72 20 67  , equal to, or g
30690 72 65 61 74 65 72 20 74 68 61 6e 20 74 68 65 20  reater than the 
306a0 73 65 63 6f 6e 64 0a 2a 2a 20 73 74 72 69 6e 67  second.** string
306b0 2e 20 69 2e 65 2e 20 28 53 54 52 49 4e 47 31 20  . i.e. (STRING1 
306c0 2d 20 53 54 52 49 4e 47 32 29 2e 0a 2a 2a 0a 2a  - STRING2)..**.*
306d0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 72  * The sqlite3_cr
306e0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
306f0 32 28 29 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73  2() works like s
30700 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
30710 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20 65 78 63  llation().** exc
30720 65 70 74 20 74 68 61 74 20 69 74 20 74 61 6b 65  ept that it take
30730 73 20 61 6e 20 65 78 74 72 61 20 61 72 67 75 6d  s an extra argum
30740 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 64  ent which is a d
30750 65 73 74 72 75 63 74 6f 72 20 66 6f 72 0a 2a 2a  estructor for.**
30760 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 2e 20   the collation. 
30770 20 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   The destructor 
30780 69 73 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74  is called when t
30790 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 0a  he collation is.
307a0 2a 2a 20 64 65 73 74 72 6f 79 65 64 20 61 6e 64  ** destroyed and
307b0 20 69 73 20 70 61 73 73 65 64 20 61 20 63 6f 70   is passed a cop
307c0 79 20 6f 66 20 74 68 65 20 66 6f 75 72 74 68 20  y of the fourth 
307d0 70 61 72 61 6d 65 74 65 72 20 76 6f 69 64 2a 20  parameter void* 
307e0 70 6f 69 6e 74 65 72 0a 2a 2a 20 6f 66 20 74 68  pointer.** of th
307f0 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  e sqlite3_create
30800 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 2e  _collation_v2().
30810 0a 2a 2a 20 43 6f 6c 6c 61 74 69 6f 6e 73 20 61  .** Collations a
30820 72 65 20 64 65 73 74 72 6f 79 65 64 20 77 68 65  re destroyed whe
30830 6e 0a 2a 2a 20 74 68 65 79 20 61 72 65 20 6f 76  n.** they are ov
30840 65 72 72 69 64 64 65 6e 20 62 79 20 6c 61 74 65  erridden by late
30850 72 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 63  r calls to the c
30860 6f 6c 6c 61 74 69 6f 6e 20 63 72 65 61 74 69 6f  ollation creatio
30870 6e 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 6f  n functions.** o
30880 72 20 77 68 65 6e 20 74 68 65 20 5b 73 71 6c 69  r when the [sqli
30890 74 65 33 2a 5d 20 64 61 74 61 62 61 73 65 20 68  te3*] database h
308a0 61 6e 64 6c 65 20 69 73 20 63 6c 6f 73 65 64 20  andle is closed 
308b0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63  using [sqlite3_c
308c0 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49  lose()]..**.** I
308d0 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
308e0 20 7b 46 31 36 36 30 33 7d 20 41 20 73 75 63 63   {F16603} A succ
308f0 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 74  essful call to t
30900 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
30910 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
30920 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c  ollation_v2(B,X,
30930 45 2c 50 2c 46 2c 44 29 5d 20 69 6e 74 65 72 66  E,P,F,D)] interf
30940 61 63 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ace.**          
30950 72 65 67 69 73 74 65 72 73 20 66 75 6e 63 74 69  registers functi
30960 6f 6e 20 46 20 61 73 20 74 68 65 20 63 6f 6d 70  on F as the comp
30970 61 72 69 73 6f 6e 20 66 75 6e 63 74 69 6f 6e 20  arison function 
30980 75 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 20  used to.**      
30990 20 20 20 20 69 6d 70 6c 65 6d 65 6e 74 20 63 6f      implement co
309a0 6c 6c 61 74 69 6f 6e 20 58 20 6f 6e 20 5b 64 61  llation X on [da
309b0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
309c0 6e 5d 20 42 20 66 6f 72 0a 2a 2a 20 20 20 20 20  n] B for.**     
309d0 20 20 20 20 20 64 61 74 61 62 61 73 65 73 20 68       databases h
309e0 61 76 69 6e 67 20 65 6e 63 6f 64 69 6e 67 20 45  aving encoding E
309f0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36 30 34 7d  ..**.** {F16604}
30a00 20 53 51 4c 69 74 65 20 75 6e 64 65 72 73 74 61   SQLite understa
30a10 6e 64 73 20 74 68 65 20 58 20 70 61 72 61 6d 65  nds the X parame
30a20 74 65 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20  ter to.**       
30a30 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61     [sqlite3_crea
30a40 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
30a50 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 20 61 73  B,X,E,P,F,D)] as
30a60 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
30a70 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 55  ed.**          U
30a80 54 46 2d 38 20 73 74 72 69 6e 67 20 69 6e 20 77  TF-8 string in w
30a90 68 69 63 68 20 63 61 73 65 20 69 73 20 69 67 6e  hich case is ign
30aa0 6f 72 65 64 20 66 6f 72 20 41 53 43 49 49 20 63  ored for ASCII c
30ab0 68 61 72 61 63 74 65 72 73 20 61 6e 64 0a 2a 2a  haracters and.**
30ac0 20 20 20 20 20 20 20 20 20 20 69 73 20 73 69 67            is sig
30ad0 6e 69 66 69 63 61 6e 74 20 66 6f 72 20 6e 6f 6e  nificant for non
30ae0 2d 41 53 43 49 49 20 63 68 61 72 61 63 74 65 72  -ASCII character
30af0 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36 30 36  s..**.** {F16606
30b00 7d 20 53 75 63 63 65 73 73 69 76 65 20 63 61 6c  } Successive cal
30b10 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ls to [sqlite3_c
30b20 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
30b30 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d  v2(B,X,E,P,F,D)]
30b40 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69 74  .**          wit
30b50 68 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65  h the same value
30b60 73 20 66 6f 72 20 42 2c 20 58 2c 20 61 6e 64 20  s for B, X, and 
30b70 45 2c 20 6f 76 65 72 72 69 64 65 20 70 72 69 6f  E, override prio
30b80 72 20 76 61 6c 75 65 73 0a 2a 2a 20 20 20 20 20  r values.**     
30b90 20 20 20 20 20 6f 66 20 50 2c 20 46 2c 20 61 6e       of P, F, an
30ba0 64 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36  d D..**.** {F166
30bb0 30 39 7d 20 54 68 65 20 64 65 73 74 72 75 63 74  09} The destruct
30bc0 6f 72 20 44 20 69 6e 20 5b 73 71 6c 69 74 65 33  or D in [sqlite3
30bd0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
30be0 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44  n_v2(B,X,E,P,F,D
30bf0 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  )].**          i
30c00 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20  s not NULL then 
30c10 69 74 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74  it is called wit
30c20 68 20 61 72 67 75 6d 65 6e 74 20 50 20 77 68 65  h argument P whe
30c30 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  n the.**        
30c40 20 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63    collating func
30c50 74 69 6f 6e 20 69 73 20 64 72 6f 70 70 65 64 20  tion is dropped 
30c60 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a  by SQLite..**.**
30c70 20 7b 46 31 36 36 31 32 7d 20 41 20 63 6f 6c 6c   {F16612} A coll
30c80 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69  ating function i
30c90 73 20 64 72 6f 70 70 65 64 20 77 68 65 6e 20 69  s dropped when i
30ca0 74 20 69 73 20 6f 76 65 72 6c 6f 61 64 65 64 2e  t is overloaded.
30cb0 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36 31 35 7d 20  .**.** {F16615} 
30cc0 41 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  A collating func
30cd0 74 69 6f 6e 20 69 73 20 64 72 6f 70 70 65 64 20  tion is dropped 
30ce0 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  when the databas
30cf0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
30d00 20 20 20 20 20 20 20 20 20 69 73 20 63 6c 6f 73           is clos
30d10 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
30d20 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a  3_close()]..**.*
30d30 2a 20 7b 46 31 36 36 31 38 7d 20 54 68 65 20 70  * {F16618} The p
30d40 6f 69 6e 74 65 72 20 50 20 69 6e 20 5b 73 71 6c  ointer P in [sql
30d50 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
30d60 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50  ation_v2(B,X,E,P
30d70 2c 46 2c 44 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ,F,D)].**       
30d80 20 20 20 69 73 20 70 61 73 73 65 64 20 74 68 72     is passed thr
30d90 6f 75 67 68 20 61 73 20 74 68 65 20 66 69 72 73  ough as the firs
30da0 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  t parameter to t
30db0 68 65 20 63 6f 6d 70 61 72 69 73 6f 6e 0a 2a 2a  he comparison.**
30dc0 20 20 20 20 20 20 20 20 20 20 66 75 6e 63 74 69            functi
30dd0 6f 6e 20 46 20 66 6f 72 20 61 6c 6c 20 73 75 62  on F for all sub
30de0 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69  sequent invocati
30df0 6f 6e 73 20 6f 66 20 46 2e 0a 2a 2a 0a 2a 2a 20  ons of F..**.** 
30e00 7b 46 31 36 36 32 31 7d 20 41 20 63 61 6c 6c 20  {F16621} A call 
30e10 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  to [sqlite3_crea
30e20 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 42 2c 58  te_collation(B,X
30e30 2c 45 2c 50 2c 46 29 5d 20 69 73 20 65 78 61 63  ,E,P,F)] is exac
30e40 74 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  tly.**          
30e50 74 68 65 20 73 61 6d 65 20 61 73 20 61 20 63 61  the same as a ca
30e60 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
30e70 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
30e80 76 32 28 29 5d 20 77 69 74 68 0a 2a 2a 20 20 20  v2()] with.**   
30e90 20 20 20 20 20 20 20 74 68 65 20 73 61 6d 65 20         the same 
30ea0 70 61 72 61 6d 65 74 65 72 73 20 61 6e 64 20 61  parameters and a
30eb0 20 4e 55 4c 4c 20 64 65 73 74 72 75 63 74 6f 72   NULL destructor
30ec0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36 32 34 7d  ..**.** {F16624}
30ed0 20 46 6f 6c 6c 6f 77 69 6e 67 20 61 20 5b 73 71   Following a [sq
30ee0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
30ef0 6c 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c  lation_v2(B,X,E,
30f00 50 2c 46 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20  P,F,D)],.**     
30f10 20 20 20 20 20 53 51 4c 69 74 65 20 75 73 65 73       SQLite uses
30f20 20 74 68 65 20 63 6f 6d 70 61 72 69 73 6f 6e 20   the comparison 
30f30 66 75 6e 63 74 69 6f 6e 20 46 20 66 6f 72 20 61  function F for a
30f40 6c 6c 20 74 65 78 74 20 63 6f 6d 70 61 72 69 73  ll text comparis
30f50 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  on.**          o
30f60 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 5b 64 61  perations on [da
30f70 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
30f80 6e 5d 20 42 20 6f 6e 20 74 65 78 74 20 76 61 6c  n] B on text val
30f90 75 65 73 20 74 68 61 74 0a 2a 2a 20 20 20 20 20  ues that.**     
30fa0 20 20 20 20 20 75 73 65 20 74 68 65 20 63 6f 6c       use the col
30fb0 6c 61 74 69 6e 67 20 73 65 71 75 65 6e 63 65 20  lating sequence 
30fc0 6e 61 6d 65 20 58 2e 0a 2a 2a 0a 2a 2a 20 7b 46  name X..**.** {F
30fd0 31 36 36 32 37 7d 20 54 68 65 20 5b 73 71 6c 69  16627} The [sqli
30fe0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
30ff0 74 69 6f 6e 31 36 28 42 2c 58 2c 45 2c 50 2c 46  tion16(B,X,E,P,F
31000 29 5d 20 77 6f 72 6b 73 20 74 68 65 20 73 61 6d  )] works the sam
31010 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 73  e.**          as
31020 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
31030 5f 63 6f 6c 6c 61 74 69 6f 6e 28 42 2c 58 2c 45  _collation(B,X,E
31040 2c 50 2c 46 29 5d 20 65 78 63 65 70 74 20 74 68  ,P,F)] except th
31050 61 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  at the.**       
31060 20 20 20 63 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d     collation nam
31070 65 20 58 20 69 73 20 75 6e 64 65 72 73 74 6f 6f  e X is understoo
31080 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6e  d as UTF-16 in n
31090 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
310a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 73  .**          ins
310b0 74 65 61 64 20 6f 66 20 55 54 46 2d 38 2e 0a 2a  tead of UTF-8..*
310c0 2a 0a 2a 2a 20 7b 46 31 36 36 33 30 7d 20 57 68  *.** {F16630} Wh
310d0 65 6e 20 6d 75 6c 74 69 70 6c 65 20 63 6f 6d 70  en multiple comp
310e0 61 72 69 73 6f 6e 20 66 75 6e 63 74 69 6f 6e 73  arison functions
310f0 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 20 66   are available f
31100 6f 72 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20  or the same.**  
31110 20 20 20 20 20 20 20 20 63 6f 6c 6c 61 74 69 6e          collatin
31120 67 20 73 65 71 75 65 6e 63 65 2c 20 53 51 4c 69  g sequence, SQLi
31130 74 65 20 63 68 6f 6f 73 65 73 20 74 68 65 20 6f  te chooses the o
31140 6e 65 20 77 68 6f 73 65 20 74 65 78 74 20 65 6e  ne whose text en
31150 63 6f 64 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20  coding.**       
31160 20 20 20 72 65 71 75 69 72 65 73 20 74 68 65 20     requires the 
31170 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20  least amount of 
31180 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20  conversion from 
31190 74 68 65 20 64 65 66 61 75 6c 74 0a 2a 2a 20 20  the default.**  
311a0 20 20 20 20 20 20 20 20 74 65 78 74 20 65 6e 63          text enc
311b0 6f 64 69 6e 67 20 6f 66 20 74 68 65 20 64 61 74  oding of the dat
311c0 61 62 61 73 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71  abase..*/.int sq
311d0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
311e0 6c 61 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65  lation(.  sqlite
311f0 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61  3*, .  const cha
31200 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74  r *zName, .  int
31210 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f   eTextRep, .  vo
31220 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d  id*,.  int(*xCom
31230 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  pare)(void*,int,
31240 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c  const void*,int,
31250 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a  const void*).);.
31260 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
31270 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
31280 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
31290 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
312a0 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52  e, .  int eTextR
312b0 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20  ep, .  void*,.  
312c0 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76  int(*xCompare)(v
312d0 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
312e0 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
312f0 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78  oid*),.  void(*x
31300 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a  Destroy)(void*).
31310 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
31320 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31  reate_collation1
31330 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  6(.  sqlite3*, .
31340 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e    const char *zN
31350 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78  ame, .  int eTex
31360 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a  tRep, .  void*,.
31370 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29    int(*xCompare)
31380 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
31390 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74   void*,int,const
313a0 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a   void*).);../*.*
313b0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c  * CAPI3REF: Coll
313c0 61 74 69 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c  ation Needed Cal
313d0 6c 62 61 63 6b 73 20 7b 46 31 36 37 30 30 7d 0a  lbacks {F16700}.
313e0 2a 2a 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 68  **.** To avoid h
313f0 61 76 69 6e 67 20 74 6f 20 72 65 67 69 73 74 65  aving to registe
31400 72 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20  r all collation 
31410 73 65 71 75 65 6e 63 65 73 20 62 65 66 6f 72 65  sequences before
31420 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63   a database.** c
31430 61 6e 20 62 65 20 75 73 65 64 2c 20 61 20 73 69  an be used, a si
31440 6e 67 6c 65 20 63 61 6c 6c 62 61 63 6b 20 66 75  ngle callback fu
31450 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65  nction may be re
31460 67 69 73 74 65 72 65 64 20 77 69 74 68 20 74 68  gistered with th
31470 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 68 61  e.** database ha
31480 6e 64 6c 65 20 74 6f 20 62 65 20 63 61 6c 6c 65  ndle to be calle
31490 64 20 77 68 65 6e 65 76 65 72 20 61 6e 20 75 6e  d whenever an un
314a0 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f  defined collatio
314b0 6e 20 73 65 71 75 65 6e 63 65 20 69 73 0a 2a 2a  n sequence is.**
314c0 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a   required..**.**
314d0 20 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   If the function
314e0 20 69 73 20 72 65 67 69 73 74 65 72 65 64 20 75   is registered u
314f0 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33  sing the sqlite3
31500 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
31510 64 28 29 20 41 50 49 2c 0a 2a 2a 20 74 68 65 6e  d() API,.** then
31520 20 69 74 20 69 73 20 70 61 73 73 65 64 20 74 68   it is passed th
31530 65 20 6e 61 6d 65 73 20 6f 66 20 75 6e 64 65 66  e names of undef
31540 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73  ined collation s
31550 65 71 75 65 6e 63 65 73 20 61 73 20 73 74 72 69  equences as stri
31560 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 69  ngs.** encoded i
31570 6e 20 55 54 46 2d 38 2e 20 7b 46 31 36 37 30 33  n UTF-8. {F16703
31580 7d 20 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c  } If sqlite3_col
31590 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28  lation_needed16(
315a0 29 20 69 73 20 75 73 65 64 2c 20 74 68 65 20 6e  ) is used, the n
315b0 61 6d 65 73 0a 2a 2a 20 61 72 65 20 70 61 73 73  ames.** are pass
315c0 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20  ed as UTF-16 in 
315d0 6d 61 63 68 69 6e 65 20 6e 61 74 69 76 65 20 62  machine native b
315e0 79 74 65 20 6f 72 64 65 72 2e 20 41 20 63 61 6c  yte order. A cal
315f0 6c 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 66  l to either.** f
31600 75 6e 63 74 69 6f 6e 20 72 65 70 6c 61 63 65 73  unction replaces
31610 20 61 6e 79 20 65 78 69 73 74 69 6e 67 20 63 61   any existing ca
31620 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 57 68  llback..**.** Wh
31630 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  en the callback 
31640 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20  is invoked, the 
31650 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 70  first argument p
31660 61 73 73 65 64 20 69 73 20 61 20 63 6f 70 79 0a  assed is a copy.
31670 2a 2a 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64  ** of the second
31680 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
31690 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
316a0 65 65 64 65 64 28 29 20 6f 72 0a 2a 2a 20 73 71  eeded() or.** sq
316b0 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
316c0 6e 65 65 64 65 64 31 36 28 29 2e 20 20 54 68 65  needed16().  The
316d0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
316e0 20 69 73 20 74 68 65 20 64 61 74 61 62 61 73 65   is the database
316f0 0a 2a 2a 20 68 61 6e 64 6c 65 2e 20 20 54 68 65  .** handle.  The
31700 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
31710 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  is one of [SQLIT
31720 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 5b 53 51 4c  E_UTF8],.** [SQL
31730 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 20 6f 72  ITE_UTF16BE], or
31740 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45   [SQLITE_UTF16LE
31750 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68  ], indicating th
31760 65 20 6d 6f 73 74 0a 2a 2a 20 64 65 73 69 72 61  e most.** desira
31770 62 6c 65 20 66 6f 72 6d 20 6f 66 20 74 68 65 20  ble form of the 
31780 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
31790 63 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  ce function requ
317a0 69 72 65 64 2e 0a 2a 2a 20 54 68 65 20 66 6f 75  ired..** The fou
317b0 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
317c0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
317d0 0a 2a 2a 20 72 65 71 75 69 72 65 64 20 63 6f 6c  .** required col
317e0 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 2e  lation sequence.
317f0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62  .**.** The callb
31800 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f  ack function sho
31810 75 6c 64 20 72 65 67 69 73 74 65 72 20 74 68 65  uld register the
31820 20 64 65 73 69 72 65 64 20 63 6f 6c 6c 61 74 69   desired collati
31830 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  on using.** [sql
31840 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
31850 61 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  ation()], [sqlit
31860 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
31870 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20  ion16()], or.** 
31880 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
31890 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 2e  collation_v2()].
318a0 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
318b0 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 37 30 32  S:.**.** {F16702
318c0 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63  } A successful c
318d0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
318e0 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
318f0 28 44 2c 50 2c 46 29 5d 0a 2a 2a 20 20 20 20 20  (D,P,F)].**     
31900 20 20 20 20 20 6f 72 20 5b 73 71 6c 69 74 65 33       or [sqlite3
31910 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
31920 64 31 36 28 44 2c 50 2c 46 29 5d 20 63 61 75 73  d16(D,P,F)] caus
31930 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  es.**          t
31940 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
31950 6e 65 63 74 69 6f 6e 5d 20 44 20 74 6f 20 69 6e  nection] D to in
31960 76 6f 6b 65 20 63 61 6c 6c 62 61 63 6b 20 46 20  voke callback F 
31970 77 69 74 68 20 66 69 72 73 74 0a 2a 2a 20 20 20  with first.**   
31980 20 20 20 20 20 20 20 70 61 72 61 6d 65 74 65 72         parameter
31990 20 50 20 77 68 65 6e 65 76 65 72 20 69 74 20 6e   P whenever it n
319a0 65 65 64 73 20 61 20 63 6f 6d 70 61 72 69 73 6f  eeds a compariso
319b0 6e 20 66 75 6e 63 74 69 6f 6e 20 66 6f 72 20 61  n function for a
319c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6c  .**          col
319d0 6c 61 74 69 6e 67 20 73 65 71 75 65 6e 63 65 20  lating sequence 
319e0 74 68 61 74 20 69 74 20 64 6f 65 73 20 6e 6f 74  that it does not
319f0 20 6b 6e 6f 77 20 61 62 6f 75 74 2e 0a 2a 2a 0a   know about..**.
31a00 2a 2a 20 7b 46 31 36 37 30 34 7d 20 45 61 63 68  ** {F16704} Each
31a10 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c   successful call
31a20 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   to [sqlite3_col
31a30 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d  lation_needed()]
31a40 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   or.**          
31a50 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69  [sqlite3_collati
31a60 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 5d 20 6f  on_needed16()] o
31a70 76 65 72 72 69 64 65 73 20 74 68 65 20 63 61 6c  verrides the cal
31a80 6c 62 61 63 6b 20 72 65 67 69 73 74 65 72 65 64  lback registered
31a90 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 6e 20  .**          on 
31aa0 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61  the same [databa
31ab0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 62  se connection] b
31ac0 79 20 70 72 69 6f 72 20 63 61 6c 6c 73 20 74 6f  y prior calls to
31ad0 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20   either.**      
31ae0 20 20 20 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a      interface..*
31af0 2a 0a 2a 2a 20 7b 46 31 36 37 30 36 7d 20 54 68  *.** {F16706} Th
31b00 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 72 65  e name of the re
31b10 71 75 65 73 74 65 64 20 63 6f 6c 6c 61 74 69 6e  quested collatin
31b20 67 20 66 75 6e 63 74 69 6f 6e 20 70 61 73 73 65  g function passe
31b30 64 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20  d in the.**     
31b40 20 20 20 20 20 34 74 68 20 70 61 72 61 6d 65 74       4th paramet
31b50 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  er to the callba
31b60 63 6b 20 69 73 20 69 6e 20 55 54 46 2d 38 20 69  ck is in UTF-8 i
31b70 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a  f the callback.*
31b80 2a 20 20 20 20 20 20 20 20 20 20 77 61 73 20 72  *          was r
31b90 65 67 69 73 74 65 72 65 64 20 75 73 69 6e 67 20  egistered using 
31ba0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69  [sqlite3_collati
31bb0 6f 6e 5f 6e 65 65 64 65 64 28 29 5d 20 61 6e 64  on_needed()] and
31bc0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20  .**          is 
31bd0 69 6e 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65  in UTF-16 native
31be0 20 62 79 74 65 20 6f 72 64 65 72 20 69 66 20 74   byte order if t
31bf0 68 65 20 63 61 6c 6c 62 61 63 6b 20 77 61 73 0a  he callback was.
31c00 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 67 69  **          regi
31c10 73 74 65 72 65 64 20 75 73 69 6e 67 20 5b 73 71  stered using [sq
31c20 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
31c30 6e 65 65 64 65 64 31 36 28 29 5d 2e 0a 2a 2a 0a  needed16()]..**.
31c40 2a 2a 20 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ** .*/.int sqlit
31c50 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
31c60 64 65 64 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  ded(.  sqlite3*,
31c70 20 0a 20 20 76 6f 69 64 2a 2c 20 0a 20 20 76 6f   .  void*, .  vo
31c80 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69  id(*)(void*,sqli
31c90 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65  te3*,int eTextRe
31ca0 70 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 0a 29  p,const char*).)
31cb0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
31cc0 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36  llation_needed16
31cd0 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
31ce0 20 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 28 2a   void*,.  void(*
31cf0 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a  )(void*,sqlite3*
31d00 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f  ,int eTextRep,co
31d10 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f  nst void*).);../
31d20 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65  *.** Specify the
31d30 20 6b 65 79 20 66 6f 72 20 61 6e 20 65 6e 63 72   key for an encr
31d40 79 70 74 65 64 20 64 61 74 61 62 61 73 65 2e 20  ypted database. 
31d50 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 68   This routine sh
31d60 6f 75 6c 64 20 62 65 0a 2a 2a 20 63 61 6c 6c 65  ould be.** calle
31d70 64 20 72 69 67 68 74 20 61 66 74 65 72 20 73 71  d right after sq
31d80 6c 69 74 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a  lite3_open()..**
31d90 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20  .** The code to 
31da0 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41  implement this A
31db0 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61  PI is not availa
31dc0 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69  ble in the publi
31dd0 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20  c release.** of 
31de0 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73  SQLite..*/.int s
31df0 71 6c 69 74 65 33 5f 6b 65 79 28 0a 20 20 73 71  qlite3_key(.  sq
31e00 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
31e10 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
31e20 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72  Database to be r
31e30 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73  ekeyed */.  cons
31e40 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e  t void *pKey, in
31e50 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68  t nKey     /* Th
31e60 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a  e key */.);../*.
31e70 2a 2a 20 43 68 61 6e 67 65 20 74 68 65 20 6b 65  ** Change the ke
31e80 79 20 6f 6e 20 61 6e 20 6f 70 65 6e 20 64 61 74  y on an open dat
31e90 61 62 61 73 65 2e 20 20 49 66 20 74 68 65 20 63  abase.  If the c
31ea0 75 72 72 65 6e 74 20 64 61 74 61 62 61 73 65 20  urrent database 
31eb0 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79 70  is not.** encryp
31ec0 74 65 64 2c 20 74 68 69 73 20 72 6f 75 74 69 6e  ted, this routin
31ed0 65 20 77 69 6c 6c 20 65 6e 63 72 79 70 74 20 69  e will encrypt i
31ee0 74 2e 20 20 49 66 20 70 4e 65 77 3d 3d 30 20 6f  t.  If pNew==0 o
31ef0 72 20 6e 4e 65 77 3d 3d 30 2c 20 74 68 65 0a 2a  r nNew==0, the.*
31f00 2a 20 64 61 74 61 62 61 73 65 20 69 73 20 64 65  * database is de
31f10 63 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  crypted..**.** T
31f20 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65  he code to imple
31f30 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20 69 73  ment this API is
31f40 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69   not available i
31f50 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c  n the public rel
31f60 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74  ease.** of SQLit
31f70 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  e..*/.int sqlite
31f80 33 5f 72 65 6b 65 79 28 0a 20 20 73 71 6c 69 74  3_rekey(.  sqlit
31f90 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
31fa0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
31fb0 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65  abase to be reke
31fc0 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  yed */.  const v
31fd0 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e  oid *pKey, int n
31fe0 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6e  Key     /* The n
31ff0 65 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a  ew key */.);../*
32000 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 53  .** CAPI3REF:  S
32010 75 73 70 65 6e 64 20 45 78 65 63 75 74 69 6f 6e  uspend Execution
32020 20 46 6f 72 20 41 20 53 68 6f 72 74 20 54 69 6d   For A Short Tim
32030 65 20 7b 46 31 30 35 33 30 7d 0a 2a 2a 0a 2a 2a  e {F10530}.**.**
32040 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6c 65   The sqlite3_sle
32050 65 70 28 29 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  ep() function.**
32060 20 63 61 75 73 65 73 20 74 68 65 20 63 75 72 72   causes the curr
32070 65 6e 74 20 74 68 72 65 61 64 20 74 6f 20 73 75  ent thread to su
32080 73 70 65 6e 64 20 65 78 65 63 75 74 69 6f 6e 0a  spend execution.
32090 2a 2a 20 66 6f 72 20 61 74 20 6c 65 61 73 74 20  ** for at least 
320a0 61 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c  a number of mill
320b0 69 73 65 63 6f 6e 64 73 20 73 70 65 63 69 66 69  iseconds specifi
320c0 65 64 20 69 6e 20 69 74 73 20 70 61 72 61 6d 65  ed in its parame
320d0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ter..**.** If th
320e0 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  e operating syst
320f0 65 6d 20 64 6f 65 73 20 6e 6f 74 20 73 75 70 70  em does not supp
32100 6f 72 74 20 73 6c 65 65 70 20 72 65 71 75 65 73  ort sleep reques
32110 74 73 20 77 69 74 68 20 0a 2a 2a 20 6d 69 6c 6c  ts with .** mill
32120 69 73 65 63 6f 6e 64 20 74 69 6d 65 20 72 65 73  isecond time res
32130 6f 6c 75 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68  olution, then th
32140 65 20 74 69 6d 65 20 77 69 6c 6c 20 62 65 20 72  e time will be r
32150 6f 75 6e 64 65 64 20 75 70 20 74 6f 20 0a 2a 2a  ounded up to .**
32160 20 74 68 65 20 6e 65 61 72 65 73 74 20 73 65 63   the nearest sec
32170 6f 6e 64 2e 20 54 68 65 20 6e 75 6d 62 65 72 20  ond. The number 
32180 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  of milliseconds 
32190 6f 66 20 73 6c 65 65 70 20 61 63 74 75 61 6c 6c  of sleep actuall
321a0 79 20 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20  y .** requested 
321b0 66 72 6f 6d 20 74 68 65 20 6f 70 65 72 61 74 69  from the operati
321c0 6e 67 20 73 79 73 74 65 6d 20 69 73 20 72 65 74  ng system is ret
321d0 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  urned..**.** SQL
321e0 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74  ite implements t
321f0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 62 79  his interface by
32200 20 63 61 6c 6c 69 6e 67 20 74 68 65 20 78 53 6c   calling the xSl
32210 65 65 70 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20  eep().** method 
32220 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b  of the default [
32230 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
32240 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ect..**.** INVAR
32250 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31  IANTS:.**.** {F1
32260 30 35 33 33 7d 20 54 68 65 20 5b 73 71 6c 69 74  0533} The [sqlit
32270 65 33 5f 73 6c 65 65 70 28 4d 29 5d 20 69 6e 74  e3_sleep(M)] int
32280 65 72 66 61 63 65 20 69 6e 76 6f 6b 65 73 20 74  erface invokes t
32290 68 65 20 78 53 6c 65 65 70 0a 2a 2a 20 20 20 20  he xSleep.**    
322a0 20 20 20 20 20 20 6d 65 74 68 6f 64 20 6f 66 20        method of 
322b0 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c  the default [sql
322c0 69 74 65 33 5f 76 66 73 7c 56 46 53 5d 20 69 6e  ite3_vfs|VFS] in
322d0 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 20 20 20   order to.**    
322e0 20 20 20 20 20 20 73 75 73 70 65 6e 64 20 65 78        suspend ex
322f0 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 20 63  ecution of the c
32300 75 72 72 65 6e 74 20 74 68 72 65 61 64 20 66 6f  urrent thread fo
32310 72 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 20 20  r at least.**   
32320 20 20 20 20 20 20 20 4d 20 6d 69 6c 6c 69 73 65         M millise
32330 63 6f 6e 64 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  conds..**.** {F1
32340 30 35 33 36 7d 20 54 68 65 20 5b 73 71 6c 69 74  0536} The [sqlit
32350 65 33 5f 73 6c 65 65 70 28 4d 29 5d 20 69 6e 74  e3_sleep(M)] int
32360 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
32370 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
32380 20 20 20 20 20 20 20 20 20 6d 69 6c 6c 69 73 65           millise
32390 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 20 61  conds of sleep a
323a0 63 74 75 61 6c 6c 79 20 72 65 71 75 65 73 74 65  ctually requeste
323b0 64 20 6f 66 20 74 68 65 20 6f 70 65 72 61 74 69  d of the operati
323c0 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73  ng.**          s
323d0 79 73 74 65 6d 2c 20 77 68 69 63 68 20 6d 69 67  ystem, which mig
323e0 68 74 20 62 65 20 6c 61 72 67 65 72 20 74 68 61  ht be larger tha
323f0 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  n the parameter 
32400 4d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  M..*/.int sqlite
32410 33 5f 73 6c 65 65 70 28 69 6e 74 29 3b 0a 0a 2f  3_sleep(int);../
32420 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20  *.** CAPI3REF:  
32430 4e 61 6d 65 20 4f 66 20 54 68 65 20 46 6f 6c 64  Name Of The Fold
32440 65 72 20 48 6f 6c 64 69 6e 67 20 54 65 6d 70 6f  er Holding Tempo
32450 72 61 72 79 20 46 69 6c 65 73 20 7b 46 31 30 33  rary Files {F103
32460 31 30 7d 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 69  10}.**.** If thi
32470 73 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c  s global variabl
32480 65 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69  e is made to poi
32490 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 77  nt to a string w
324a0 68 69 63 68 20 69 73 0a 2a 2a 20 74 68 65 20 6e  hich is.** the n
324b0 61 6d 65 20 6f 66 20 61 20 66 6f 6c 64 65 72 20  ame of a folder 
324c0 28 61 2e 6b 2e 61 2e 20 64 69 72 65 63 74 6f 72  (a.k.a. director
324d0 79 29 2c 20 74 68 65 6e 20 61 6c 6c 20 74 65 6d  y), then all tem
324e0 70 6f 72 61 72 79 20 66 69 6c 65 73 0a 2a 2a 20  porary files.** 
324f0 63 72 65 61 74 65 64 20 62 79 20 53 51 4c 69 74  created by SQLit
32500 65 20 77 69 6c 6c 20 62 65 20 70 6c 61 63 65 64  e will be placed
32510 20 69 6e 20 74 68 61 74 20 64 69 72 65 63 74 6f   in that directo
32520 72 79 2e 20 20 49 66 20 74 68 69 73 20 76 61 72  ry.  If this var
32530 69 61 62 6c 65 0a 2a 2a 20 69 73 20 4e 55 4c 4c  iable.** is NULL
32540 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53   pointer, then S
32550 51 4c 69 74 65 20 64 6f 65 73 20 61 20 73 65 61  QLite does a sea
32560 72 63 68 20 66 6f 72 20 61 6e 20 61 70 70 72 6f  rch for an appro
32570 70 72 69 61 74 65 20 74 65 6d 70 6f 72 61 72 79  priate temporary
32580 0a 2a 2a 20 66 69 6c 65 20 64 69 72 65 63 74 6f  .** file directo
32590 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20  ry..**.** It is 
325a0 6e 6f 74 20 73 61 66 65 20 74 6f 20 6d 6f 64 69  not safe to modi
325b0 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  fy this variable
325c0 20 6f 6e 63 65 20 61 20 64 61 74 61 62 61 73 65   once a database
325d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 68   connection.** h
325e0 61 73 20 62 65 65 6e 20 6f 70 65 6e 65 64 2e 20  as been opened. 
325f0 20 49 74 20 69 73 20 69 6e 74 65 6e 64 65 64 20   It is intended 
32600 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62  that this variab
32610 6c 65 20 62 65 20 73 65 74 20 6f 6e 63 65 0a 2a  le be set once.*
32620 2a 20 61 73 20 70 61 72 74 20 6f 66 20 70 72 6f  * as part of pro
32630 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74  cess initializat
32640 69 6f 6e 20 61 6e 64 20 62 65 66 6f 72 65 20 61  ion and before a
32650 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ny SQLite interf
32660 61 63 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  ace.** routines 
32670 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 20 61  have been call a
32680 6e 64 20 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e  nd remain unchan
32690 67 65 64 20 74 68 65 72 65 61 66 74 65 72 2e 0a  ged thereafter..
326a0 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45 52 4e  */.SQLITE_EXTERN
326b0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 74   char *sqlite3_t
326c0 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 3b 0a 0a  emp_directory;..
326d0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
326e0 20 54 65 73 74 20 54 6f 20 53 65 65 20 49 66 20   Test To See If 
326f0 54 68 65 20 44 61 74 61 62 61 73 65 20 49 73 20  The Database Is 
32700 49 6e 20 41 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d  In Auto-Commit M
32710 6f 64 65 20 7b 46 31 32 39 33 30 7d 0a 2a 2a 0a  ode {F12930}.**.
32720 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67  ** The sqlite3_g
32730 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 29 20  et_autocommit() 
32740 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
32750 73 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 0a 2a 2a  s non-zero or.**
32760 20 7a 65 72 6f 20 69 66 20 74 68 65 20 67 69 76   zero if the giv
32770 65 6e 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  en database conn
32780 65 63 74 69 6f 6e 20 69 73 20 6f 72 20 69 73 20  ection is or is 
32790 6e 6f 74 20 69 6e 20 61 75 74 6f 63 6f 6d 6d 69  not in autocommi
327a0 74 20 6d 6f 64 65 2c 0a 2a 2a 20 72 65 73 70 65  t mode,.** respe
327b0 63 74 69 76 65 6c 79 2e 20 20 20 41 75 74 6f 63  ctively.   Autoc
327c0 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 6f 6e  ommit mode is on
327d0 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c 74 2e 20  .** by default. 
327e0 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65   Autocommit mode
327f0 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20   is disabled by 
32800 61 20 5b 42 45 47 49 4e 5d 20 73 74 61 74 65 6d  a [BEGIN] statem
32810 65 6e 74 2e 0a 2a 2a 20 41 75 74 6f 63 6f 6d 6d  ent..** Autocomm
32820 69 74 20 6d 6f 64 65 20 69 73 20 72 65 2d 65 6e  it mode is re-en
32830 61 62 6c 65 64 20 62 79 20 61 20 5b 43 4f 4d 4d  abled by a [COMM
32840 49 54 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41 43 4b  IT] or [ROLLBACK
32850 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 63 65 72 74  ]..**.** If cert
32860 61 69 6e 20 6b 69 6e 64 73 20 6f 66 20 65 72 72  ain kinds of err
32870 6f 72 73 20 6f 63 63 75 72 20 6f 6e 20 61 20 73  ors occur on a s
32880 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20  tatement within 
32890 61 20 6d 75 6c 74 69 2d 73 74 61 74 65 6d 65 6e  a multi-statemen
328a0 74 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e  t.** transaction
328b0 73 20 28 65 72 72 6f 72 73 20 69 6e 63 6c 75 64  s (errors includ
328c0 69 6e 67 20 5b 53 51 4c 49 54 45 5f 46 55 4c 4c  ing [SQLITE_FULL
328d0 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  ], [SQLITE_IOERR
328e0 5d 2c 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e  ], .** [SQLITE_N
328f0 4f 4d 45 4d 5d 2c 20 5b 53 51 4c 49 54 45 5f 42  OMEM], [SQLITE_B
32900 55 53 59 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54  USY], and [SQLIT
32910 45 5f 49 4e 54 45 52 52 55 50 54 5d 29 20 74 68  E_INTERRUPT]) th
32920 65 6e 20 74 68 65 0a 2a 2a 20 74 72 61 6e 73 61  en the.** transa
32930 63 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 72  ction might be r
32940 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d  olled back autom
32950 61 74 69 63 61 6c 6c 79 2e 20 20 54 68 65 20 6f  atically.  The o
32960 6e 6c 79 20 77 61 79 20 74 6f 0a 2a 2a 20 66 69  nly way to.** fi
32970 6e 64 20 6f 75 74 20 69 66 20 53 51 4c 69 74 65  nd out if SQLite
32980 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72   automatically r
32990 6f 6c 6c 65 64 20 62 61 63 6b 20 74 68 65 20 74  olled back the t
329a0 72 61 6e 73 61 63 74 69 6f 6e 20 61 66 74 65 72  ransaction after
329b0 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 69 73 20  .** an error is 
329c0 74 6f 20 75 73 65 20 74 68 69 73 20 66 75 6e 63  to use this func
329d0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  tion..**.** INVA
329e0 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  RIANTS:.**.** {F
329f0 31 32 39 33 31 7d 20 54 68 65 20 5b 73 71 6c 69  12931} The [sqli
32a00 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d  te3_get_autocomm
32a10 69 74 28 44 29 5d 20 69 6e 74 65 72 66 61 63 65  it(D)] interface
32a20 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
32a30 6f 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  o or.**         
32a40 20 7a 65 72 6f 20 69 66 20 74 68 65 20 5b 64 61   zero if the [da
32a50 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
32a60 6e 5d 20 44 20 69 73 20 6f 72 20 69 73 20 6e 6f  n] D is or is no
32a70 74 20 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 0a  t in autocommit.
32a80 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 6f 64 65  **          mode
32a90 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a  , respectively..
32aa0 2a 2a 0a 2a 2a 20 7b 46 31 32 39 33 32 7d 20 41  **.** {F12932} A
32ab0 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69  utocommit mode i
32ac0 73 20 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e  s on by default.
32ad0 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 33 33 7d 20  .**.** {F12933} 
32ae0 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20  Autocommit mode 
32af0 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 61  is disabled by a
32b00 20 73 75 63 63 65 73 73 66 75 6c 20 5b 42 45 47   successful [BEG
32b10 49 4e 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a  IN] statement..*
32b20 2a 0a 2a 2a 20 7b 46 31 32 39 33 34 7d 20 41 75  *.** {F12934} Au
32b30 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73  tocommit mode is
32b40 20 65 6e 61 62 6c 65 64 20 62 79 20 61 20 73 75   enabled by a su
32b50 63 63 65 73 73 66 75 6c 20 5b 43 4f 4d 4d 49 54  ccessful [COMMIT
32b60 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41 43 4b 5d 0a  ] or [ROLLBACK].
32b70 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 61 74  **          stat
32b80 65 6d 65 6e 74 2e 0a 2a 2a 20 0a 2a 2a 0a 2a 2a  ement..** .**.**
32b90 20 4c 49 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a   LIMITATIONS:.**
32ba0 2a 0a 2a 2a 20 7b 55 31 32 39 33 36 7d 20 49 66  *.** {U12936} If
32bb0 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20   another thread 
32bc0 63 68 61 6e 67 65 73 20 74 68 65 20 61 75 74 6f  changes the auto
32bd0 63 6f 6d 6d 69 74 20 73 74 61 74 75 73 20 6f 66  commit status of
32be0 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
32bf0 20 20 20 20 20 20 20 20 20 20 63 6f 6e 6e 65 63            connec
32c00 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 69 73 20  tion while this 
32c10 72 6f 75 74 69 6e 65 20 69 73 20 72 75 6e 6e 69  routine is runni
32c20 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 74  ng, then the ret
32c30 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 20 20 20  urn value.**    
32c40 20 20 20 20 20 20 69 73 20 75 6e 64 65 66 69 6e        is undefin
32c50 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ed..*/.int sqlit
32c60 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69  e3_get_autocommi
32c70 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  t(sqlite3*);../*
32c80 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 46  .** CAPI3REF:  F
32c90 69 6e 64 20 54 68 65 20 44 61 74 61 62 61 73 65  ind The Database
32ca0 20 48 61 6e 64 6c 65 20 4f 66 20 41 20 50 72 65   Handle Of A Pre
32cb0 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20  pared Statement 
32cc0 7b 46 31 33 31 32 30 7d 0a 2a 2a 0a 2a 2a 20 54  {F13120}.**.** T
32cd0 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61  he sqlite3_db_ha
32ce0 6e 64 6c 65 20 69 6e 74 65 72 66 61 63 65 0a 2a  ndle interface.*
32cf0 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b 73  * returns the [s
32d00 71 6c 69 74 65 33 2a 5d 20 64 61 74 61 62 61 73  qlite3*] databas
32d10 65 20 68 61 6e 64 6c 65 20 74 6f 20 77 68 69 63  e handle to whic
32d20 68 20 61 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  h a.** [prepared
32d30 20 73 74 61 74 65 6d 65 6e 74 5d 20 62 65 6c 6f   statement] belo
32d40 6e 67 73 2e 0a 2a 2a 20 54 68 65 20 64 61 74 61  ngs..** The data
32d50 62 61 73 65 20 68 61 6e 64 6c 65 20 72 65 74 75  base handle retu
32d60 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
32d70 64 62 5f 68 61 6e 64 6c 65 0a 2a 2a 20 69 73 20  db_handle.** is 
32d80 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
32d90 65 20 68 61 6e 64 6c 65 20 74 68 61 74 20 77 61  e handle that wa
32da0 73 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 61  s.** the first a
32db0 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b  rgument to the [
32dc0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
32dd0 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72  v2()] or its var
32de0 69 61 6e 74 73 0a 2a 2a 20 74 68 61 74 20 77 61  iants.** that wa
32df0 73 20 75 73 65 64 20 74 6f 20 63 72 65 61 74 65  s used to create
32e00 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
32e10 6e 20 74 68 65 20 66 69 72 73 74 20 70 6c 61 63  n the first plac
32e20 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  e..**.** INVARIA
32e30 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 31  NTS:.**.** {F131
32e40 32 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  23} The [sqlite3
32e50 5f 64 62 5f 68 61 6e 64 6c 65 28 53 29 5d 20 69  _db_handle(S)] i
32e60 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
32e70 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 20 20   a pointer.**   
32e80 20 20 20 20 20 20 20 74 6f 20 74 68 65 20 5b 64         to the [d
32e90 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
32ea0 6f 6e 5d 20 61 73 73 6f 63 69 61 74 65 64 20 77  on] associated w
32eb0 69 74 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ith.**          
32ec0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
32ed0 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 73 71 6c 69 74  ent] S..*/.sqlit
32ee0 65 33 20 2a 73 71 6c 69 74 65 33 5f 64 62 5f 68  e3 *sqlite3_db_h
32ef0 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 73 74  andle(sqlite3_st
32f00 6d 74 2a 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41  mt*);.../*.** CA
32f10 50 49 33 52 45 46 3a 20 43 6f 6d 6d 69 74 20 41  PI3REF: Commit A
32f20 6e 64 20 52 6f 6c 6c 62 61 63 6b 20 4e 6f 74 69  nd Rollback Noti
32f30 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63  fication Callbac
32f40 6b 73 20 7b 46 31 32 39 35 30 7d 0a 2a 2a 0a 2a  ks {F12950}.**.*
32f50 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  * The sqlite3_co
32f60 6d 6d 69 74 5f 68 6f 6f 6b 28 29 20 69 6e 74 65  mmit_hook() inte
32f70 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20  rface registers 
32f80 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75  a callback.** fu
32f90 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76  nction to be inv
32fa0 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20  oked whenever a 
32fb0 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 63  transaction is c
32fc0 6f 6d 6d 69 74 74 65 64 2e 0a 2a 2a 20 41 6e 79  ommitted..** Any
32fd0 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79   callback set by
32fe0 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c   a previous call
32ff0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d   to sqlite3_comm
33000 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72  it_hook().** for
33010 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
33020 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
33030 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20   overridden..** 
33040 54 68 65 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c  The sqlite3_roll
33050 62 61 63 6b 5f 68 6f 6f 6b 28 29 20 69 6e 74 65  back_hook() inte
33060 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20  rface registers 
33070 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75  a callback.** fu
33080 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76  nction to be inv
33090 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20  oked whenever a 
330a0 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 63  transaction is c
330b0 6f 6d 6d 69 74 74 65 64 2e 0a 2a 2a 20 41 6e 79  ommitted..** Any
330c0 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79   callback set by
330d0 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c   a previous call
330e0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d   to sqlite3_comm
330f0 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72  it_hook().** for
33100 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
33110 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
33120 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20   overridden..** 
33130 54 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e  The pArg argumen
33140 74 20 69 73 20 70 61 73 73 65 64 20 74 68 72 6f  t is passed thro
33150 75 67 68 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61  ugh.** to the ca
33160 6c 6c 62 61 63 6b 2e 20 20 49 66 20 74 68 65 20  llback.  If the 
33170 63 61 6c 6c 62 61 63 6b 20 6f 6e 20 61 20 63 6f  callback on a co
33180 6d 6d 69 74 20 68 6f 6f 6b 20 66 75 6e 63 74 69  mmit hook functi
33190 6f 6e 20 0a 2a 2a 20 72 65 74 75 72 6e 73 20 6e  on .** returns n
331a0 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68  on-zero, then th
331b0 65 20 63 6f 6d 6d 69 74 20 69 73 20 63 6f 6e 76  e commit is conv
331c0 65 72 74 65 64 20 69 6e 74 6f 20 61 20 72 6f 6c  erted into a rol
331d0 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  lback..**.** If 
331e0 61 6e 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e  another function
331f0 20 77 61 73 20 70 72 65 76 69 6f 75 73 6c 79 20   was previously 
33200 72 65 67 69 73 74 65 72 65 64 2c 20 69 74 73 0a  registered, its.
33210 2a 2a 20 70 41 72 67 20 76 61 6c 75 65 20 69 73  ** pArg value is
33220 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65   returned.  Othe
33230 72 77 69 73 65 20 4e 55 4c 4c 20 69 73 20 72 65  rwise NULL is re
33240 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65  turned..**.** Re
33250 67 69 73 74 65 72 69 6e 67 20 61 20 4e 55 4c 4c  gistering a NULL
33260 20 66 75 6e 63 74 69 6f 6e 20 64 69 73 61 62 6c   function disabl
33270 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e  es the callback.
33280 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 74 68 65 20 70  .**.** For the p
33290 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20  urposes of this 
332a0 41 50 49 2c 20 61 20 74 72 61 6e 73 61 63 74 69  API, a transacti
332b0 6f 6e 20 69 73 20 73 61 69 64 20 74 6f 20 68 61  on is said to ha
332c0 76 65 20 62 65 65 6e 20 0a 2a 2a 20 72 6f 6c 6c  ve been .** roll
332d0 65 64 20 62 61 63 6b 20 69 66 20 61 6e 20 65 78  ed back if an ex
332e0 70 6c 69 63 69 74 20 22 52 4f 4c 4c 42 41 43 4b  plicit "ROLLBACK
332f0 22 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 65  " statement is e
33300 78 65 63 75 74 65 64 2c 20 6f 72 0a 2a 2a 20 61  xecuted, or.** a
33310 6e 20 65 72 72 6f 72 20 6f 72 20 63 6f 6e 73 74  n error or const
33320 72 61 69 6e 74 20 63 61 75 73 65 73 20 61 6e 20  raint causes an 
33330 69 6d 70 6c 69 63 69 74 20 72 6f 6c 6c 62 61 63  implicit rollbac
33340 6b 20 74 6f 20 6f 63 63 75 72 2e 0a 2a 2a 20 54  k to occur..** T
33350 68 65 20 72 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c  he rollback call
33360 62 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f  back is not invo
33370 6b 65 64 20 69 66 20 61 20 74 72 61 6e 73 61 63  ked if a transac
33380 74 69 6f 6e 20 69 73 0a 2a 2a 20 61 75 74 6f 6d  tion is.** autom
33390 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20  atically rolled 
333a0 62 61 63 6b 20 62 65 63 61 75 73 65 20 74 68 65  back because the
333b0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
333c0 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a  tion is closed..
333d0 2a 2a 20 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20  ** The rollback 
333e0 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20  callback is not 
333f0 69 6e 76 6f 6b 65 64 20 69 66 20 61 20 74 72 61  invoked if a tra
33400 6e 73 61 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 72  nsaction is.** r
33410 6f 6c 6c 65 64 20 62 61 63 6b 20 62 65 63 61 75  olled back becau
33420 73 65 20 61 20 63 6f 6d 6d 69 74 20 63 61 6c 6c  se a commit call
33430 62 61 63 6b 20 72 65 74 75 72 6e 65 64 20 6e 6f  back returned no
33440 6e 2d 7a 65 72 6f 2e 0a 2a 2a 20 3c 74 6f 64 6f  n-zero..** <todo
33450 3e 20 43 68 65 63 6b 20 6f 6e 20 74 68 69 73 20  > Check on this 
33460 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 54 68  </todo>.**.** Th
33470 65 73 65 20 61 72 65 20 65 78 70 65 72 69 6d 65  ese are experime
33480 6e 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20  ntal interfaces 
33490 61 6e 64 20 61 72 65 20 73 75 62 6a 65 63 74 20  and are subject 
334a0 74 6f 20 63 68 61 6e 67 65 2e 0a 2a 2a 0a 2a 2a  to change..**.**
334b0 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
334c0 2a 2a 20 7b 46 31 32 39 35 31 7d 20 54 68 65 20  ** {F12951} The 
334d0 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f  [sqlite3_commit_
334e0 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 6e 74  hook(D,F,P)] int
334f0 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73  erface registers
33500 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
33510 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
33520 6f 6e 20 46 20 74 6f 20 62 65 20 69 6e 76 6f 6b  on F to be invok
33530 65 64 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74  ed with argument
33540 20 50 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 20   P whenever.**  
33550 20 20 20 20 20 20 20 20 61 20 74 72 61 6e 73 61          a transa
33560 63 74 69 6f 6e 20 63 6f 6d 6d 69 74 73 20 6f 6e  ction commits on
33570 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
33580 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20  ction] D..**.** 
33590 7b 46 31 32 39 35 32 7d 20 54 68 65 20 5b 73 71  {F12952} The [sq
335a0 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f  lite3_commit_hoo
335b0 6b 28 44 2c 46 2c 50 29 5d 20 69 6e 74 65 72 66  k(D,F,P)] interf
335c0 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
335d0 50 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 72  P.**          ar
335e0 67 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68 65 20  gument from the 
335f0 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 77 69  previous call wi
33600 74 68 20 74 68 65 20 73 61 6d 65 20 0a 2a 2a 20  th the same .** 
33610 20 20 20 20 20 20 20 20 20 5b 64 61 74 61 62 61           [databa
33620 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 5d 20  se connection ] 
33630 44 20 2c 20 6f 72 20 4e 55 4c 4c 20 6f 6e 20 74  D , or NULL on t
33640 68 65 20 66 69 72 73 74 20 63 61 6c 6c 0a 2a 2a  he first call.**
33650 20 20 20 20 20 20 20 20 20 20 66 6f 72 20 61 20            for a 
33660 70 61 72 74 69 63 75 6c 61 72 20 5b 64 61 74 61  particular [data
33670 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
33680 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 35   D..**.** {F1295
33690 33 7d 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20  3} Each call to 
336a0 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f  [sqlite3_commit_
336b0 68 6f 6f 6b 28 29 5d 20 6f 76 65 72 77 72 69 74  hook()] overwrit
336c0 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a  es the callback.
336d0 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 67 69  **          regi
336e0 73 74 65 72 65 64 20 62 79 20 70 72 69 6f 72 20  stered by prior 
336f0 63 61 6c 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  calls..**.** {F1
33700 32 39 35 34 7d 20 49 66 20 74 68 65 20 46 20 61  2954} If the F a
33710 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69  rgument to [sqli
33720 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28  te3_commit_hook(
33730 44 2c 46 2c 50 29 5d 20 69 73 20 4e 55 4c 4c 0a  D,F,P)] is NULL.
33740 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e  **          then
33750 20 74 68 65 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b   the commit hook
33760 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 63 61 6e   callback is can
33770 63 65 6c 65 64 20 61 6e 64 20 6e 6f 20 63 61 6c  celed and no cal
33780 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20  lback.**        
33790 20 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65    is invoked whe
337a0 6e 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  n a transaction 
337b0 63 6f 6d 6d 69 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b  commits..**.** {
337c0 46 31 32 39 35 35 7d 20 49 66 20 74 68 65 20 63  F12955} If the c
337d0 6f 6d 6d 69 74 20 63 61 6c 6c 62 61 63 6b 20 72  ommit callback r
337e0 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20  eturns non-zero 
337f0 74 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20  then the commit 
33800 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63  is.**          c
33810 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20  onverted into a 
33820 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  rollback..**.** 
33830 7b 46 31 32 39 36 31 7d 20 54 68 65 20 5b 73 71  {F12961} The [sq
33840 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68  lite3_rollback_h
33850 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 6e 74 65  ook(D,F,P)] inte
33860 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20  rface registers 
33870 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
33880 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
33890 6e 20 46 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65  n F to be invoke
338a0 64 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20  d with argument 
338b0 50 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 20 20  P whenever.**   
338c0 20 20 20 20 20 20 20 61 20 74 72 61 6e 73 61 63         a transac
338d0 74 69 6f 6e 20 72 6f 6c 6c 73 20 62 61 63 6b 20  tion rolls back 
338e0 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  on [database con
338f0 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a  nection] D..**.*
33900 2a 20 7b 46 31 32 39 36 32 7d 20 54 68 65 20 5b  * {F12962} The [
33910 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b  sqlite3_rollback
33920 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 6e  _hook(D,F,P)] in
33930 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
33940 74 68 65 20 50 0a 2a 2a 20 20 20 20 20 20 20 20  the P.**        
33950 20 20 61 72 67 75 6d 65 6e 74 20 66 72 6f 6d 20    argument from 
33960 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c  the previous cal
33970 6c 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20  l with the same 
33980 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61  .**          [da
33990 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
339a0 6e 20 5d 20 44 20 2c 20 6f 72 20 4e 55 4c 4c 20  n ] D , or NULL 
339b0 6f 6e 20 74 68 65 20 66 69 72 73 74 20 63 61 6c  on the first cal
339c0 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 6f  l.**          fo
339d0 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 5b  r a particular [
339e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
339f0 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46  ion] D..**.** {F
33a00 31 32 39 36 33 7d 20 45 61 63 68 20 63 61 6c 6c  12963} Each call
33a10 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 6f 6c   to [sqlite3_rol
33a20 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 5d 20 6f 76  lback_hook()] ov
33a30 65 72 77 72 69 74 65 73 20 74 68 65 20 63 61 6c  erwrites the cal
33a40 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20  lback.**        
33a50 20 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20    registered by 
33a60 70 72 69 6f 72 20 63 61 6c 6c 73 2e 0a 2a 2a 0a  prior calls..**.
33a70 2a 2a 20 7b 46 31 32 39 36 34 7d 20 49 66 20 74  ** {F12964} If t
33a80 68 65 20 46 20 61 72 67 75 6d 65 6e 74 20 74 6f  he F argument to
33a90 20 5b 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61   [sqlite3_rollba
33aa0 63 6b 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20  ck_hook(D,F,P)] 
33ab0 69 73 20 4e 55 4c 4c 0a 2a 2a 20 20 20 20 20 20  is NULL.**      
33ac0 20 20 20 20 74 68 65 6e 20 74 68 65 20 72 6f 6c      then the rol
33ad0 6c 62 61 63 6b 20 68 6f 6f 6b 20 63 61 6c 6c 62  lback hook callb
33ae0 61 63 6b 20 69 73 20 63 61 6e 63 65 6c 65 64 20  ack is canceled 
33af0 61 6e 64 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 0a  and no callback.
33b00 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 69  **          is i
33b10 6e 76 6f 6b 65 64 20 77 68 65 6e 20 61 20 74 72  nvoked when a tr
33b20 61 6e 73 61 63 74 69 6f 6e 20 72 6f 6c 6c 73 20  ansaction rolls 
33b30 62 61 63 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73  back..*/.void *s
33b40 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f  qlite3_commit_ho
33b50 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  ok(sqlite3*, int
33b60 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64  (*)(void*), void
33b70 2a 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  *);.void *sqlite
33b80 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28  3_rollback_hook(
33b90 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a  sqlite3*, void(*
33ba0 29 28 76 6f 69 64 20 2a 29 2c 20 76 6f 69 64 2a  )(void *), void*
33bb0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
33bc0 45 46 3a 20 44 61 74 61 20 43 68 61 6e 67 65 20  EF: Data Change 
33bd0 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 61 6c  Notification Cal
33be0 6c 62 61 63 6b 73 20 7b 46 31 32 39 37 30 7d 0a  lbacks {F12970}.
33bf0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
33c00 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 20  3_update_hook() 
33c10 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 65 67  interface.** reg
33c20 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63  isters a callbac
33c30 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20  k function with 
33c40 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
33c50 6e 65 63 74 69 6f 6e 20 69 64 65 6e 74 69 66 69  nection identifi
33c60 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 66 69  ed by the .** fi
33c70 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
33c80 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65  be invoked whene
33c90 76 65 72 20 61 20 72 6f 77 20 69 73 20 75 70 64  ver a row is upd
33ca0 61 74 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f  ated, inserted o
33cb0 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 41 6e  r deleted..** An
33cc0 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62  y callback set b
33cd0 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c  y a previous cal
33ce0 6c 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69  l to this functi
33cf0 6f 6e 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  on for the same 
33d00 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
33d10 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72  nection is overr
33d20 69 64 64 65 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  idden..**.** The
33d30 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
33d40 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
33d50 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 74 6f   the function to
33d60 20 69 6e 76 6f 6b 65 20 77 68 65 6e 20 61 20 0a   invoke when a .
33d70 2a 2a 20 72 6f 77 20 69 73 20 75 70 64 61 74 65  ** row is update
33d80 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64  d, inserted or d
33d90 65 6c 65 74 65 64 2e 20 0a 2a 2a 20 54 68 65 20  eleted. .** The 
33da0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
33db0 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  o the callback i
33dc0 73 0a 2a 2a 20 61 20 63 6f 70 79 20 6f 66 20 74  s.** a copy of t
33dd0 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
33de0 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 75 70 64  t to sqlite3_upd
33df0 61 74 65 5f 68 6f 6f 6b 28 29 2e 0a 2a 2a 20 54  ate_hook()..** T
33e00 68 65 20 73 65 63 6f 6e 64 20 63 61 6c 6c 62 61  he second callba
33e10 63 6b 20 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  ck .** argument 
33e20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  is one of [SQLIT
33e30 45 5f 49 4e 53 45 52 54 5d 2c 20 5b 53 51 4c 49  E_INSERT], [SQLI
33e40 54 45 5f 44 45 4c 45 54 45 5d 20 6f 72 20 5b 53  TE_DELETE] or [S
33e50 51 4c 49 54 45 5f 55 50 44 41 54 45 5d 2c 0a 2a  QLITE_UPDATE],.*
33e60 2a 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  * depending on t
33e70 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61  he operation tha
33e80 74 20 63 61 75 73 65 64 20 74 68 65 20 63 61 6c  t caused the cal
33e90 6c 62 61 63 6b 20 74 6f 20 62 65 20 69 6e 76 6f  lback to be invo
33ea0 6b 65 64 2e 0a 2a 2a 20 54 68 65 20 74 68 69 72  ked..** The thir
33eb0 64 20 61 6e 64 20 0a 2a 2a 20 66 6f 75 72 74 68  d and .** fourth
33ec0 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
33ed0 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61  e callback conta
33ee0 69 6e 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74  in pointers to t
33ef0 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20  he database and 
33f00 0a 2a 2a 20 74 61 62 6c 65 20 6e 61 6d 65 20 63  .** table name c
33f10 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61 66  ontaining the af
33f20 66 65 63 74 65 64 20 72 6f 77 2e 0a 2a 2a 20 54  fected row..** T
33f30 68 65 20 66 69 6e 61 6c 20 63 61 6c 6c 62 61 63  he final callbac
33f40 6b 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 0a  k parameter is .
33f50 2a 2a 20 74 68 65 20 72 6f 77 69 64 20 6f 66 20  ** the rowid of 
33f60 74 68 65 20 72 6f 77 2e 0a 2a 2a 20 49 6e 20 74  the row..** In t
33f70 68 65 20 63 61 73 65 20 6f 66 20 61 6e 20 75 70  he case of an up
33f80 64 61 74 65 2c 20 74 68 69 73 20 69 73 20 74 68  date, this is th
33f90 65 20 72 6f 77 69 64 20 61 66 74 65 72 20 0a 2a  e rowid after .*
33fa0 2a 20 74 68 65 20 75 70 64 61 74 65 20 74 61 6b  * the update tak
33fb0 65 73 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  es place..**.** 
33fc0 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 20  The update hook 
33fd0 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77  is not invoked w
33fe0 68 65 6e 20 69 6e 74 65 72 6e 61 6c 20 73 79 73  hen internal sys
33ff0 74 65 6d 20 74 61 62 6c 65 73 20 61 72 65 0a 2a  tem tables are.*
34000 2a 20 6d 6f 64 69 66 69 65 64 20 28 69 2e 65 2e  * modified (i.e.
34010 20 73 71 6c 69 74 65 5f 6d 61 73 74 65 72 20 61   sqlite_master a
34020 6e 64 20 73 71 6c 69 74 65 5f 73 65 71 75 65 6e  nd sqlite_sequen
34030 63 65 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e  ce)..**.** If an
34040 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 77  other function w
34050 61 73 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65  as previously re
34060 67 69 73 74 65 72 65 64 2c 20 69 74 73 20 70 41  gistered, its pA
34070 72 67 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 72  rg value.** is r
34080 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77  eturned.  Otherw
34090 69 73 65 20 4e 55 4c 4c 20 69 73 20 72 65 74 75  ise NULL is retu
340a0 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  rned..**.** INVA
340b0 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  RIANTS:.**.** {F
340c0 31 32 39 37 31 7d 20 54 68 65 20 5b 73 71 6c 69  12971} The [sqli
340d0 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28  te3_update_hook(
340e0 44 2c 46 2c 50 29 5d 20 69 6e 74 65 72 66 61 63  D,F,P)] interfac
340f0 65 20 63 61 75 73 65 73 20 63 61 6c 6c 62 61 63  e causes callbac
34100 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 75  k.**          fu
34110 6e 63 74 69 6f 6e 20 46 20 74 6f 20 62 65 20 69  nction F to be i
34120 6e 76 6f 6b 65 64 20 77 69 74 68 20 66 69 72 73  nvoked with firs
34130 74 20 70 61 72 61 6d 65 74 65 72 20 50 20 77 68  t parameter P wh
34140 65 6e 65 76 65 72 0a 2a 2a 20 20 20 20 20 20 20  enever.**       
34150 20 20 20 61 20 74 61 62 6c 65 20 72 6f 77 20 69     a table row i
34160 73 20 6d 6f 64 69 66 69 65 64 2c 20 69 6e 73 65  s modified, inse
34170 72 74 65 64 2c 20 6f 72 20 64 65 6c 65 74 65 64  rted, or deleted
34180 20 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   on.**          
34190 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
341a0 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b  tion] D..**.** {
341b0 46 31 32 39 37 33 7d 20 54 68 65 20 5b 73 71 6c  F12973} The [sql
341c0 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b  ite3_update_hook
341d0 28 44 2c 46 2c 50 29 5d 20 69 6e 74 65 72 66 61  (D,F,P)] interfa
341e0 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 76  ce returns the v
341f0 61 6c 75 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  alue.**         
34200 20 6f 66 20 50 20 66 6f 72 20 74 68 65 20 70 72   of P for the pr
34210 65 76 69 6f 75 73 20 63 61 6c 6c 20 6f 6e 20 74  evious call on t
34220 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73  he same [databas
34230 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c  e connection] D,
34240 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
34250 4e 55 4c 4c 20 66 6f 72 20 74 68 65 20 66 69 72  NULL for the fir
34260 73 74 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 7b  st call..**.** {
34270 46 31 32 39 37 35 7d 20 49 66 20 74 68 65 20 75  F12975} If the u
34280 70 64 61 74 65 20 68 6f 6f 6b 20 63 61 6c 6c 62  pdate hook callb
34290 61 63 6b 20 46 20 69 6e 20 5b 73 71 6c 69 74 65  ack F in [sqlite
342a0 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44 2c  3_update_hook(D,
342b0 46 2c 50 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  F,P)].**        
342c0 20 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74    is NULL then t
342d0 68 65 20 6e 6f 20 75 70 64 61 74 65 20 63 61 6c  he no update cal
342e0 6c 62 61 63 6b 73 20 61 72 65 20 6d 61 64 65 2e  lbacks are made.
342f0 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 37 37 7d 20  .**.** {F12977} 
34300 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71  Each call to [sq
34310 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f  lite3_update_hoo
34320 6b 28 44 2c 46 2c 50 29 5d 20 6f 76 65 72 72 69  k(D,F,P)] overri
34330 64 65 73 20 70 72 69 6f 72 20 63 61 6c 6c 73 0a  des prior calls.
34340 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 74  **          to t
34350 68 65 20 73 61 6d 65 20 69 6e 74 65 72 66 61 63  he same interfac
34360 65 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64  e on the same [d
34370 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
34380 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  on] D..**.** {F1
34390 32 39 37 39 7d 20 54 68 65 20 75 70 64 61 74 65  2979} The update
343a0 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 69   hook callback i
343b0 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77 68  s not invoked wh
343c0 65 6e 20 69 6e 74 65 72 6e 61 6c 20 73 79 73 74  en internal syst
343d0 65 6d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  em.**          t
343e0 61 62 6c 65 73 20 73 75 63 68 20 61 73 20 73 71  ables such as sq
343f0 6c 69 74 65 5f 6d 61 73 74 65 72 20 61 6e 64 20  lite_master and 
34400 73 71 6c 69 74 65 5f 73 65 71 75 65 6e 63 65 20  sqlite_sequence 
34410 61 72 65 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a  are modified..**
34420 0a 2a 2a 20 7b 46 31 32 39 38 31 7d 20 54 68 65  .** {F12981} The
34430 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
34440 72 20 74 6f 20 74 68 65 20 75 70 64 61 74 65 20  r to the update 
34450 63 61 6c 6c 62 61 63 6b 20 0a 2a 2a 20 20 20 20  callback .**    
34460 20 20 20 20 20 20 69 73 20 6f 6e 65 20 6f 66 20        is one of 
34470 5b 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 5d 2c  [SQLITE_INSERT],
34480 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d   [SQLITE_DELETE]
34490 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 50 44 41   or [SQLITE_UPDA
344a0 54 45 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  TE],.**         
344b0 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68   depending on th
344c0 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74  e operation that
344d0 20 63 61 75 73 65 64 20 74 68 65 20 63 61 6c 6c   caused the call
344e0 62 61 63 6b 20 74 6f 20 62 65 20 69 6e 76 6f 6b  back to be invok
344f0 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 38  ed..**.** {F1298
34500 33 7d 20 54 68 65 20 74 68 69 72 64 20 61 6e 64  3} The third and
34510 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
34520 73 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  s to the callbac
34530 6b 20 63 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65  k contain pointe
34540 72 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  rs.**          t
34550 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  o zero-terminate
34560 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73 20  d UTF-8 strings 
34570 77 68 69 63 68 20 61 72 65 20 74 68 65 20 6e 61  which are the na
34580 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20  mes of the.**   
34590 20 20 20 20 20 20 20 64 61 74 61 62 61 73 65 20         database 
345a0 61 6e 64 20 74 61 62 6c 65 20 74 68 61 74 20 69  and table that i
345b0 73 20 62 65 69 6e 67 20 75 70 64 61 74 65 64 2e  s being updated.
345c0 0a 0a 2a 2a 20 7b 46 31 32 39 38 35 7d 20 54 68  ..** {F12985} Th
345d0 65 20 66 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b  e final callback
345e0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
345f0 65 20 72 6f 77 69 64 20 6f 66 20 74 68 65 20 72  e rowid of the r
34600 6f 77 20 61 66 74 65 72 0a 2a 2a 20 20 20 20 20  ow after.**     
34610 20 20 20 20 20 74 68 65 20 63 68 61 6e 67 65 20       the change 
34620 6f 63 63 75 72 73 2e 0a 2a 2f 0a 76 6f 69 64 20  occurs..*/.void 
34630 2a 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f  *sqlite3_update_
34640 68 6f 6f 6b 28 0a 20 20 73 71 6c 69 74 65 33 2a  hook(.  sqlite3*
34650 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69  , .  void(*)(voi
34660 64 20 2a 2c 69 6e 74 20 2c 63 68 61 72 20 63 6f  d *,int ,char co
34670 6e 73 74 20 2a 2c 63 68 61 72 20 63 6f 6e 73 74  nst *,char const
34680 20 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34   *,sqlite3_int64
34690 29 2c 0a 20 20 76 6f 69 64 2a 0a 29 3b 0a 0a 2f  ),.  void*.);../
346a0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20  *.** CAPI3REF:  
346b0 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c  Enable Or Disabl
346c0 65 20 53 68 61 72 65 64 20 50 61 67 65 72 20 43  e Shared Pager C
346d0 61 63 68 65 20 7b 46 31 30 33 33 30 7d 0a 2a 2a  ache {F10330}.**
346e0 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
346f0 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61   enables or disa
34700 62 6c 65 73 20 74 68 65 20 73 68 61 72 69 6e 67  bles the sharing
34710 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
34720 20 63 61 63 68 65 0a 2a 2a 20 61 6e 64 20 73 63   cache.** and sc
34730 68 65 6d 61 20 64 61 74 61 20 73 74 72 75 63 74  hema data struct
34740 75 72 65 73 20 62 65 74 77 65 65 6e 20 63 6f 6e  ures between con
34750 6e 65 63 74 69 6f 6e 73 20 74 6f 20 74 68 65 20  nections to the 
34760 73 61 6d 65 20 64 61 74 61 62 61 73 65 2e 0a 2a  same database..*
34770 2a 20 53 68 61 72 69 6e 67 20 69 73 20 65 6e 61  * Sharing is ena
34780 62 6c 65 64 20 69 66 20 74 68 65 20 61 72 67 75  bled if the argu
34790 6d 65 6e 74 20 69 73 20 74 72 75 65 20 61 6e 64  ment is true and
347a0 20 64 69 73 61 62 6c 65 64 20 69 66 20 74 68 65   disabled if the
347b0 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 69 73 20   argument.** is 
347c0 66 61 6c 73 65 2e 0a 2a 2a 0a 2a 2a 20 43 61 63  false..**.** Cac
347d0 68 65 20 73 68 61 72 69 6e 67 20 69 73 20 65 6e  he sharing is en
347e0 61 62 6c 65 64 20 61 6e 64 20 64 69 73 61 62 6c  abled and disabl
347f0 65 64 0a 2a 2a 20 66 6f 72 20 61 6e 20 65 6e 74  ed.** for an ent
34800 69 72 65 20 70 72 6f 63 65 73 73 2e 20 7b 45 4e  ire process. {EN
34810 44 7d 20 54 68 69 73 20 69 73 20 61 20 63 68 61  D} This is a cha
34820 6e 67 65 20 61 73 20 6f 66 20 53 51 4c 69 74 65  nge as of SQLite
34830 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2e 0a   version 3.5.0..
34840 2a 2a 20 49 6e 20 70 72 69 6f 72 20 76 65 72 73  ** In prior vers
34850 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2c 20  ions of SQLite, 
34860 73 68 61 72 69 6e 67 20 77 61 73 0a 2a 2a 20 65  sharing was.** e
34870 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c  nabled or disabl
34880 65 64 20 66 6f 72 20 65 61 63 68 20 74 68 72 65  ed for each thre
34890 61 64 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a  ad separately..*
348a0 2a 0a 2a 2a 20 54 68 65 20 63 61 63 68 65 20 73  *.** The cache s
348b0 68 61 72 69 6e 67 20 6d 6f 64 65 20 73 65 74 20  haring mode set 
348c0 62 79 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  by this interfac
348d0 65 20 65 66 66 65 63 74 73 20 61 6c 6c 20 73 75  e effects all su
348e0 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c  bsequent.** call
348f0 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  s to [sqlite3_op
34900 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
34910 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20  open_v2()], and 
34920 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
34930 29 5d 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20  )]..** Existing 
34940 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
34950 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 75 73  ions continue us
34960 65 20 74 68 65 20 73 68 61 72 69 6e 67 20 6d 6f  e the sharing mo
34970 64 65 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 69  de.** that was i
34980 6e 20 65 66 66 65 63 74 20 61 74 20 74 68 65 20  n effect at the 
34990 74 69 6d 65 20 74 68 65 79 20 77 65 72 65 20 6f  time they were o
349a0 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 56 69 72  pened..**.** Vir
349b0 74 75 61 6c 20 74 61 62 6c 65 73 20 63 61 6e 6e  tual tables cann
349c0 6f 74 20 62 65 20 75 73 65 64 20 77 69 74 68 20  ot be used with 
349d0 61 20 73 68 61 72 65 64 20 63 61 63 68 65 2e 20  a shared cache. 
349e0 20 20 57 68 65 6e 20 73 68 61 72 65 64 0a 2a 2a    When shared.**
349f0 20 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65   cache is enable
34a00 64 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  d, the [sqlite3_
34a10 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 5d  create_module()]
34a20 20 41 50 49 20 75 73 65 64 20 74 6f 20 72 65 67   API used to reg
34a30 69 73 74 65 72 0a 2a 2a 20 76 69 72 74 75 61 6c  ister.** virtual
34a40 20 74 61 62 6c 65 73 20 77 69 6c 6c 20 61 6c 77   tables will alw
34a50 61 79 73 20 72 65 74 75 72 6e 20 61 6e 20 65 72  ays return an er
34a60 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ror..**.** This 
34a70 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
34a80 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 20 73  [SQLITE_OK] if s
34a90 68 61 72 65 64 20 63 61 63 68 65 20 77 61 73 0a  hared cache was.
34aa0 2a 2a 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69  ** enabled or di
34ab0 73 61 62 6c 65 64 20 73 75 63 63 65 73 73 66 75  sabled successfu
34ac0 6c 6c 79 2e 20 20 41 6e 20 5b 65 72 72 6f 72 20  lly.  An [error 
34ad0 63 6f 64 65 5d 0a 2a 2a 20 69 73 20 72 65 74 75  code].** is retu
34ae0 72 6e 65 64 20 6f 74 68 65 72 77 69 73 65 2e 0a  rned otherwise..
34af0 2a 2a 0a 2a 2a 20 53 68 61 72 65 64 20 63 61 63  **.** Shared cac
34b00 68 65 20 69 73 20 64 69 73 61 62 6c 65 64 20 62  he is disabled b
34b10 79 20 64 65 66 61 75 6c 74 2e 20 42 75 74 20 74  y default. But t
34b20 68 69 73 20 6d 69 67 68 74 20 63 68 61 6e 67 65  his might change
34b30 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65 20 72 65   in.** future re
34b40 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
34b50 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  .  Applications 
34b60 74 68 61 74 20 63 61 72 65 20 61 62 6f 75 74 20  that care about 
34b70 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20  shared.** cache 
34b80 73 65 74 74 69 6e 67 20 73 68 6f 75 6c 64 20 73  setting should s
34b90 65 74 20 69 74 20 65 78 70 6c 69 63 69 74 6c 79  et it explicitly
34ba0 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
34bb0 54 53 3a 0a 2a 2a 20 0a 2a 2a 20 7b 46 31 30 33  TS:.** .** {F103
34bc0 33 31 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c  31} A successful
34bd0 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b   invocation of [
34be0 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73  sqlite3_enable_s
34bf0 68 61 72 65 64 5f 63 61 63 68 65 28 42 29 5d 0a  hared_cache(B)].
34c00 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69 6c 6c  **          will
34c10 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62   enable or disab
34c20 6c 65 20 73 68 61 72 65 64 20 63 61 63 68 65 20  le shared cache 
34c30 6d 6f 64 65 20 66 6f 72 20 61 6e 79 20 73 75 62  mode for any sub
34c40 73 65 71 75 65 6e 74 6c 79 0a 2a 2a 20 20 20 20  sequently.**    
34c50 20 20 20 20 20 20 63 72 65 61 74 65 64 20 5b 64        created [d
34c60 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
34c70 6f 6e 5d 20 69 6e 20 74 68 65 20 73 61 6d 65 20  on] in the same 
34c80 70 72 6f 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 7b  process..**.** {
34c90 46 31 30 33 33 36 7d 20 57 68 65 6e 20 73 68 61  F10336} When sha
34ca0 72 65 64 20 63 61 63 68 65 20 69 73 20 65 6e 61  red cache is ena
34cb0 62 6c 65 64 2c 20 74 68 65 20 5b 73 71 6c 69 74  bled, the [sqlit
34cc0 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65  e3_create_module
34cd0 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ()].**          
34ce0 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 61  interface will a
34cf0 6c 77 61 79 73 20 72 65 74 75 72 6e 20 61 6e 20  lways return an 
34d00 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  error..**.** {F1
34d10 30 33 33 37 7d 20 54 68 65 20 5b 73 71 6c 69 74  0337} The [sqlit
34d20 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64  e3_enable_shared
34d30 5f 63 61 63 68 65 28 42 29 5d 20 69 6e 74 65 72  _cache(B)] inter
34d40 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20  face returns.** 
34d50 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45           [SQLITE
34d60 5f 4f 4b 5d 20 69 66 20 73 68 61 72 65 64 20 63  _OK] if shared c
34d70 61 63 68 65 20 77 61 73 20 65 6e 61 62 6c 65 64  ache was enabled
34d80 20 6f 72 20 64 69 73 61 62 6c 65 64 20 73 75 63   or disabled suc
34d90 63 65 73 73 66 75 6c 6c 79 2e 0a 2a 2a 0a 2a 2a  cessfully..**.**
34da0 20 7b 46 31 30 33 33 39 7d 20 53 68 61 72 65 64   {F10339} Shared
34db0 20 63 61 63 68 65 20 69 73 20 64 69 73 61 62 6c   cache is disabl
34dc0 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a  ed by default..*
34dd0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 6e  /.int sqlite3_en
34de0 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68  able_shared_cach
34df0 65 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  e(int);../*.** C
34e00 41 50 49 33 52 45 46 3a 20 20 41 74 74 65 6d 70  API3REF:  Attemp
34e10 74 20 54 6f 20 46 72 65 65 20 48 65 61 70 20 4d  t To Free Heap M
34e20 65 6d 6f 72 79 20 7b 46 31 37 33 34 30 7d 0a 2a  emory {F17340}.*
34e30 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
34e40 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28  _release_memory(
34e50 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65  ) interface atte
34e60 6d 70 74 73 20 74 6f 0a 2a 2a 20 66 72 65 65 20  mpts to.** free 
34e70 4e 20 62 79 74 65 73 20 6f 66 20 68 65 61 70 20  N bytes of heap 
34e80 6d 65 6d 6f 72 79 20 62 79 20 64 65 61 6c 6c 6f  memory by deallo
34e90 63 61 74 69 6e 67 20 6e 6f 6e 2d 65 73 73 65 6e  cating non-essen
34ea0 74 69 61 6c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61  tial memory.** a
34eb0 6c 6c 6f 63 61 74 69 6f 6e 73 20 68 65 6c 64 20  llocations held 
34ec0 62 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20  by the database 
34ed0 6c 69 62 72 61 72 79 2e 20 7b 45 4e 44 7d 20 20  library. {END}  
34ee0 4d 65 6d 6f 72 79 20 75 73 65 64 0a 2a 2a 20 74  Memory used.** t
34ef0 6f 20 63 61 63 68 65 20 64 61 74 61 62 61 73 65  o cache database
34f00 20 70 61 67 65 73 20 74 6f 20 69 6d 70 72 6f 76   pages to improv
34f10 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 69 73  e performance is
34f20 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 0a 2a   an example of.*
34f30 2a 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 20  * non-essential 
34f40 6d 65 6d 6f 72 79 2e 20 20 53 71 6c 69 74 65 33  memory.  Sqlite3
34f50 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28  _release_memory(
34f60 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65  ) returns.** the
34f70 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
34f80 20 61 63 74 75 61 6c 6c 79 20 66 72 65 65 64 2c   actually freed,
34f90 20 77 68 69 63 68 20 6d 69 67 68 74 20 62 65 20   which might be 
34fa0 6d 6f 72 65 20 6f 72 20 6c 65 73 73 0a 2a 2a 20  more or less.** 
34fb0 74 68 61 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20  than the amount 
34fc0 72 65 71 75 65 73 74 65 64 2e 0a 2a 2a 0a 2a 2a  requested..**.**
34fd0 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
34fe0 2a 2a 20 7b 46 31 37 33 34 31 7d 20 54 68 65 20  ** {F17341} The 
34ff0 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65  [sqlite3_release
35000 5f 6d 65 6d 6f 72 79 28 4e 29 5d 20 69 6e 74 65  _memory(N)] inte
35010 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74  rface attempts t
35020 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 72  o.**          fr
35030 65 65 20 4e 20 62 79 74 65 73 20 6f 66 20 68 65  ee N bytes of he
35040 61 70 20 6d 65 6d 6f 72 79 20 62 79 20 64 65 61  ap memory by dea
35050 6c 6c 6f 63 61 74 69 6e 67 20 6e 6f 6e 2d 65 73  llocating non-es
35060 73 65 6e 74 69 61 6c 0a 2a 2a 20 20 20 20 20 20  sential.**      
35070 20 20 20 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63      memory alloc
35080 61 74 69 6f 6e 73 20 68 65 6c 64 20 62 79 20 74  ations held by t
35090 68 65 20 64 61 74 61 62 61 73 65 20 6c 69 62 72  he database libr
350a0 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 33  ary..**.** {F163
350b0 34 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  42} The [sqlite3
350c0 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28  _release_memory(
350d0 4e 29 5d 20 72 65 74 75 72 6e 73 20 74 68 65 20  N)] returns the 
350e0 6e 75 6d 62 65 72 0a 2a 2a 20 20 20 20 20 20 20  number.**       
350f0 20 20 20 6f 66 20 62 79 74 65 73 20 61 63 74 75     of bytes actu
35100 61 6c 6c 79 20 66 72 65 65 64 2c 20 77 68 69 63  ally freed, whic
35110 68 20 6d 69 67 68 74 20 62 65 20 6d 6f 72 65 20  h might be more 
35120 6f 72 20 6c 65 73 73 0a 2a 2a 20 20 20 20 20 20  or less.**      
35130 20 20 20 20 74 68 61 6e 20 74 68 65 20 61 6d 6f      than the amo
35140 75 6e 74 20 72 65 71 75 65 73 74 65 64 2e 0a 2a  unt requested..*
35150 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65  /.int sqlite3_re
35160 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 69 6e 74  lease_memory(int
35170 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
35180 45 46 3a 20 20 49 6d 70 6f 73 65 20 41 20 4c 69  EF:  Impose A Li
35190 6d 69 74 20 4f 6e 20 48 65 61 70 20 53 69 7a 65  mit On Heap Size
351a0 20 7b 46 31 37 33 35 30 7d 0a 2a 2a 0a 2a 2a 20   {F17350}.**.** 
351b0 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 66 74  The sqlite3_soft
351c0 5f 68 65 61 70 5f 6c 69 6d 69 74 28 29 20 69 6e  _heap_limit() in
351d0 74 65 72 66 61 63 65 0a 2a 2a 20 70 6c 61 63 65  terface.** place
351e0 73 20 61 20 22 73 6f 66 74 22 20 6c 69 6d 69 74  s a "soft" limit
351f0 20 6f 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f   on the amount o
35200 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 74 68  f heap memory th
35210 61 74 20 6d 61 79 20 62 65 20 61 6c 6c 6f 63 61  at may be alloca
35220 74 65 64 0a 2a 2a 20 62 79 20 53 51 4c 69 74 65  ted.** by SQLite
35230 2e 20 49 66 20 61 6e 20 69 6e 74 65 72 6e 61 6c  . If an internal
35240 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 72   allocation is r
35250 65 71 75 65 73 74 65 64 20 0a 2a 2a 20 74 68 61  equested .** tha
35260 74 20 77 6f 75 6c 64 20 65 78 63 65 65 64 20 74  t would exceed t
35270 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d  he soft heap lim
35280 69 74 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c  it, [sqlite3_rel
35290 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 69  ease_memory()] i
352a0 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 6f 6e 65  s.** invoked one
352b0 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74   or more times t
352c0 6f 20 66 72 65 65 20 75 70 20 73 6f 6d 65 20 73  o free up some s
352d0 70 61 63 65 20 62 65 66 6f 72 65 20 74 68 65 20  pace before the 
352e0 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 73  allocation.** is
352f0 20 6d 61 64 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   made..**.** The
35300 20 6c 69 6d 69 74 20 69 73 20 63 61 6c 6c 65 64   limit is called
35310 20 22 73 6f 66 74 22 2c 20 62 65 63 61 75 73 65   "soft", because
35320 20 69 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   if.** [sqlite3_
35330 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29  release_memory()
35340 5d 20 63 61 6e 6e 6f 74 0a 2a 2a 20 66 72 65 65  ] cannot.** free
35350 20 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f   sufficient memo
35360 72 79 20 74 6f 20 70 72 65 76 65 6e 74 20 74 68  ry to prevent th
35370 65 20 6c 69 6d 69 74 20 66 72 6f 6d 20 62 65 69  e limit from bei
35380 6e 67 20 65 78 63 65 65 64 65 64 2c 0a 2a 2a 20  ng exceeded,.** 
35390 74 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 61 6c  the memory is al
353a0 6c 6f 63 61 74 65 64 20 61 6e 79 77 61 79 20 61  located anyway a
353b0 6e 64 20 74 68 65 20 63 75 72 72 65 6e 74 20 6f  nd the current o
353c0 70 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64  peration proceed
353d0 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 6e 65 67 61 74  s..**.** A negat
353e0 69 76 65 20 6f 72 20 7a 65 72 6f 20 76 61 6c 75  ive or zero valu
353f0 65 20 66 6f 72 20 4e 20 6d 65 61 6e 73 20 74 68  e for N means th
35400 61 74 20 74 68 65 72 65 20 69 73 20 6e 6f 20 73  at there is no s
35410 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 61  oft heap limit a
35420 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  nd.** [sqlite3_r
35430 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d  elease_memory()]
35440 20 77 69 6c 6c 20 6f 6e 6c 79 20 62 65 20 63 61   will only be ca
35450 6c 6c 65 64 20 77 68 65 6e 20 6d 65 6d 6f 72 79  lled when memory
35460 20 69 73 20 65 78 68 61 75 73 74 65 64 2e 0a 2a   is exhausted..*
35470 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61  * The default va
35480 6c 75 65 20 66 6f 72 20 74 68 65 20 73 6f 66 74  lue for the soft
35490 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20 7a   heap limit is z
354a0 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  ero..**.** SQLit
354b0 65 20 6d 61 6b 65 73 20 61 20 62 65 73 74 20 65  e makes a best e
354c0 66 66 6f 72 74 20 74 6f 20 68 6f 6e 6f 72 20 74  ffort to honor t
354d0 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d  he soft heap lim
354e0 69 74 2e 20 20 0a 2a 2a 20 42 75 74 20 69 66 20  it.  .** But if 
354f0 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69  the soft heap li
35500 6d 69 74 20 63 61 6e 6e 6f 74 20 62 65 20 68 6f  mit cannot be ho
35510 6e 6f 72 65 64 2c 20 65 78 65 63 75 74 69 6f 6e  nored, execution
35520 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 69 6e 75   will.** continu
35530 65 20 77 69 74 68 6f 75 74 20 65 72 72 6f 72 20  e without error 
35540 6f 72 20 6e 6f 74 69 66 69 63 61 74 69 6f 6e 2e  or notification.
35550 20 20 54 68 69 73 20 69 73 20 77 68 79 20 74 68    This is why th
35560 65 20 6c 69 6d 69 74 20 69 73 20 0a 2a 2a 20 63  e limit is .** c
35570 61 6c 6c 65 64 20 61 20 22 73 6f 66 74 22 20 6c  alled a "soft" l
35580 69 6d 69 74 2e 20 20 49 74 20 69 73 20 61 64 76  imit.  It is adv
35590 69 73 6f 72 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a  isory only..**.*
355a0 2a 20 50 72 69 6f 72 20 74 6f 20 53 51 4c 69 74  * Prior to SQLit
355b0 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2c  e version 3.5.0,
355c0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 6f 6e   this routine on
355d0 6c 79 20 63 6f 6e 73 74 72 61 69 6e 65 64 20 74  ly constrained t
355e0 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c  he memory.** all
355f0 6f 63 61 74 65 64 20 62 79 20 61 20 73 69 6e 67  ocated by a sing
35600 6c 65 20 74 68 72 65 61 64 20 2d 20 74 68 65 20  le thread - the 
35610 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77  same thread in w
35620 68 69 63 68 20 74 68 69 73 20 72 6f 75 74 69 6e  hich this routin
35630 65 0a 2a 2a 20 72 75 6e 73 2e 20 20 42 65 67 69  e.** runs.  Begi
35640 6e 6e 69 6e 67 20 77 69 74 68 20 53 51 4c 69 74  nning with SQLit
35650 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2c  e version 3.5.0,
35660 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c   the soft heap l
35670 69 6d 69 74 20 69 73 0a 2a 2a 20 61 70 70 6c 69  imit is.** appli
35680 65 64 20 74 6f 20 61 6c 6c 20 74 68 72 65 61 64  ed to all thread
35690 73 2e 20 54 68 65 20 76 61 6c 75 65 20 73 70 65  s. The value spe
356a0 63 69 66 69 65 64 20 66 6f 72 20 74 68 65 20 73  cified for the s
356b0 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 0a 2a  oft heap limit.*
356c0 2a 20 69 73 20 61 6e 20 75 70 70 65 72 20 62 6f  * is an upper bo
356d0 75 6e 64 20 6f 6e 20 74 68 65 20 74 6f 74 61 6c  und on the total
356e0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
356f0 6f 6e 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 61  on for all threa
35700 64 73 2e 20 49 6e 0a 2a 2a 20 76 65 72 73 69 6f  ds. In.** versio
35710 6e 20 33 2e 35 2e 30 20 74 68 65 72 65 20 69 73  n 3.5.0 there is
35720 20 6e 6f 20 6d 65 63 68 61 6e 69 73 6d 20 66 6f   no mechanism fo
35730 72 20 6c 69 6d 69 74 69 6e 67 20 74 68 65 20 68  r limiting the h
35740 65 61 70 20 75 73 61 67 65 20 66 6f 72 0a 2a 2a  eap usage for.**
35750 20 69 6e 64 69 76 69 64 75 61 6c 20 74 68 72 65   individual thre
35760 61 64 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ads..**.** INVAR
35770 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31  IANTS:.**.** {F1
35780 36 33 35 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  6351} The [sqlit
35790 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d  e3_soft_heap_lim
357a0 69 74 28 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  it(N)] interface
357b0 20 70 6c 61 63 65 73 20 61 20 73 6f 66 74 20 6c   places a soft l
357c0 69 6d 69 74 0a 2a 2a 20 20 20 20 20 20 20 20 20  imit.**         
357d0 20 6f 66 20 4e 20 62 79 74 65 73 20 6f 6e 20 74   of N bytes on t
357e0 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 68 65 61  he amount of hea
357f0 70 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 6d 61  p memory that ma
35800 79 20 62 65 20 61 6c 6c 6f 63 61 74 65 64 0a 2a  y be allocated.*
35810 2a 20 20 20 20 20 20 20 20 20 20 75 73 69 6e 67  *          using
35820 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
35830 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
35840 72 65 61 6c 6c 6f 63 28 29 5d 20 61 74 20 61 6e  realloc()] at an
35850 79 20 70 6f 69 6e 74 0a 2a 2a 20 20 20 20 20 20  y point.**      
35860 20 20 20 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a      in time..**.
35870 2a 2a 20 7b 46 31 36 33 35 32 7d 20 49 66 20 61  ** {F16352} If a
35880 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
35890 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b  3_malloc()] or [
358a0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
358b0 29 5d 20 77 6f 75 6c 64 0a 2a 2a 20 20 20 20 20  )] would.**     
358c0 20 20 20 20 20 63 61 75 73 65 20 74 68 65 20 74       cause the t
358d0 6f 74 61 6c 20 61 6d 6f 75 6e 74 20 6f 66 20 61  otal amount of a
358e0 6c 6c 6f 63 61 74 65 64 20 6d 65 6d 6f 72 79 20  llocated memory 
358f0 74 6f 20 65 78 63 65 65 64 20 74 68 65 0a 2a 2a  to exceed the.**
35900 20 20 20 20 20 20 20 20 20 20 73 6f 66 74 20 68            soft h
35910 65 61 70 20 6c 69 6d 69 74 2c 20 74 68 65 6e 20  eap limit, then 
35920 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65  [sqlite3_release
35930 5f 6d 65 6d 6f 72 79 28 29 5d 20 69 73 20 69 6e  _memory()] is in
35940 76 6f 6b 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  voked.**        
35950 20 20 69 6e 20 61 6e 20 61 74 74 65 6d 70 74 20    in an attempt 
35960 74 6f 20 72 65 64 75 63 65 20 74 68 65 20 6d 65  to reduce the me
35970 6d 6f 72 79 20 75 73 61 67 65 20 70 72 69 6f 72  mory usage prior
35980 20 74 6f 20 70 72 6f 63 65 65 64 69 6e 67 0a 2a   to proceeding.*
35990 2a 20 20 20 20 20 20 20 20 20 20 77 69 74 68 20  *          with 
359a0 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
359b0 61 74 69 6f 6e 20 61 74 74 65 6d 70 74 2e 0a 2a  ation attempt..*
359c0 2a 0a 2a 2a 20 7b 46 31 36 33 35 33 7d 20 43 61  *.** {F16353} Ca
359d0 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
359e0 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71  malloc()] or [sq
359f0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
35a00 20 74 68 61 74 20 74 72 69 67 67 65 72 0a 2a 2a   that trigger.**
35a10 20 20 20 20 20 20 20 20 20 20 61 74 74 65 6d 70            attemp
35a20 74 73 20 74 6f 20 72 65 64 75 63 65 20 6d 65 6d  ts to reduce mem
35a30 6f 72 79 20 75 73 61 67 65 20 74 68 72 6f 75 67  ory usage throug
35a40 68 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20  h the soft heap 
35a50 6c 69 6d 69 74 0a 2a 2a 20 20 20 20 20 20 20 20  limit.**        
35a60 20 20 6d 65 63 68 61 6e 69 73 6d 20 63 6f 6e 74    mechanism cont
35a70 69 6e 75 65 20 65 76 65 6e 20 69 66 20 74 68 65  inue even if the
35a80 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 64 75   attempt to redu
35a90 63 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20 20  ce memory.**    
35aa0 20 20 20 20 20 20 75 73 61 67 65 20 69 73 20 75        usage is u
35ab0 6e 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2a 0a  nsuccessful..**.
35ac0 2a 2a 20 7b 46 31 36 33 35 34 7d 20 41 20 6e 65  ** {F16354} A ne
35ad0 67 61 74 69 76 65 20 6f 72 20 7a 65 72 6f 20 76  gative or zero v
35ae0 61 6c 75 65 20 66 6f 72 20 4e 20 69 6e 20 61 20  alue for N in a 
35af0 63 61 6c 6c 20 74 6f 0a 2a 2a 20 20 20 20 20 20  call to.**      
35b00 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66      [sqlite3_sof
35b10 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 4e 29 5d  t_heap_limit(N)]
35b20 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 72   means that ther
35b30 65 20 69 73 20 6e 6f 20 73 6f 66 74 0a 2a 2a 20  e is no soft.** 
35b40 20 20 20 20 20 20 20 20 20 68 65 61 70 20 6c 69           heap li
35b50 6d 69 74 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  mit and [sqlite3
35b60 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28  _release_memory(
35b70 29 5d 20 77 69 6c 6c 20 6f 6e 6c 79 20 62 65 0a  )] will only be.
35b80 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c  **          call
35b90 65 64 20 77 68 65 6e 20 6d 65 6d 6f 72 79 20 69  ed when memory i
35ba0 73 20 63 6f 6d 70 6c 65 74 65 6c 79 20 65 78 68  s completely exh
35bb0 61 75 73 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46  austed..**.** {F
35bc0 31 36 33 35 35 7d 20 54 68 65 20 64 65 66 61 75  16355} The defau
35bd0 6c 74 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65  lt value for the
35be0 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
35bf0 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20   is zero..**.** 
35c00 7b 46 31 36 33 35 38 7d 20 45 61 63 68 20 63 61  {F16358} Each ca
35c10 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
35c20 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 4e  oft_heap_limit(N
35c30 29 5d 20 6f 76 65 72 72 69 64 65 73 20 74 68 65  )] overrides the
35c40 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c  .**          val
35c50 75 65 73 20 73 65 74 20 62 79 20 61 6c 6c 20 70  ues set by all p
35c60 72 69 6f 72 20 63 61 6c 6c 73 2e 0a 2a 2f 0a 76  rior calls..*/.v
35c70 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 6f 66 74  oid sqlite3_soft
35c80 5f 68 65 61 70 5f 6c 69 6d 69 74 28 69 6e 74 29  _heap_limit(int)
35c90 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
35ca0 46 3a 20 20 45 78 74 72 61 63 74 20 4d 65 74 61  F:  Extract Meta
35cb0 64 61 74 61 20 41 62 6f 75 74 20 41 20 43 6f 6c  data About A Col
35cc0 75 6d 6e 20 4f 66 20 41 20 54 61 62 6c 65 20 7b  umn Of A Table {
35cd0 46 31 32 38 35 30 7d 0a 2a 2a 0a 2a 2a 20 54 68  F12850}.**.** Th
35ce0 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 65  is routine.** re
35cf0 74 75 72 6e 73 20 6d 65 74 61 2d 64 61 74 61 20  turns meta-data 
35d00 61 62 6f 75 74 20 61 20 73 70 65 63 69 66 69 63  about a specific
35d10 20 63 6f 6c 75 6d 6e 20 6f 66 20 61 20 73 70 65   column of a spe
35d20 63 69 66 69 63 20 64 61 74 61 62 61 73 65 0a 2a  cific database.*
35d30 2a 20 74 61 62 6c 65 20 61 63 63 65 73 73 69 62  * table accessib
35d40 6c 65 20 75 73 69 6e 67 20 74 68 65 20 63 6f 6e  le using the con
35d50 6e 65 63 74 69 6f 6e 20 68 61 6e 64 6c 65 20 70  nection handle p
35d60 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72  assed as the fir
35d70 73 74 20 66 75 6e 63 74 69 6f 6e 20 0a 2a 2a 20  st function .** 
35d80 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
35d90 54 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 69 64  The column is id
35da0 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20  entified by the 
35db0 73 65 63 6f 6e 64 2c 20 74 68 69 72 64 20 61 6e  second, third an
35dc0 64 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  d fourth paramet
35dd0 65 72 73 20 74 6f 20 0a 2a 2a 20 74 68 69 73 20  ers to .** this 
35de0 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 73 65  function. The se
35df0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
35e00 73 20 65 69 74 68 65 72 20 74 68 65 20 6e 61 6d  s either the nam
35e10 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  e of the databas
35e20 65 0a 2a 2a 20 28 69 2e 65 2e 20 22 6d 61 69 6e  e.** (i.e. "main
35e30 22 2c 20 22 74 65 6d 70 22 20 6f 72 20 61 6e 20  ", "temp" or an 
35e40 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73  attached databas
35e50 65 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  e) containing th
35e60 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 74  e specified.** t
35e70 61 62 6c 65 20 6f 72 20 4e 55 4c 4c 2e 20 49 66  able or NULL. If
35e80 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65   it is NULL, the
35e90 6e 20 61 6c 6c 20 61 74 74 61 63 68 65 64 20 64  n all attached d
35ea0 61 74 61 62 61 73 65 73 20 61 72 65 20 73 65 61  atabases are sea
35eb0 72 63 68 65 64 0a 2a 2a 20 66 6f 72 20 74 68 65  rched.** for the
35ec0 20 74 61 62 6c 65 20 75 73 69 6e 67 20 74 68 65   table using the
35ed0 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20   same algorithm 
35ee0 61 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  as the database 
35ef0 65 6e 67 69 6e 65 20 75 73 65 73 20 74 6f 20 0a  engine uses to .
35f00 2a 2a 20 72 65 73 6f 6c 76 65 20 75 6e 71 75 61  ** resolve unqua
35f10 6c 69 66 69 65 64 20 74 61 62 6c 65 20 72 65 66  lified table ref
35f20 65 72 65 6e 63 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  erences..**.** T
35f30 68 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75  he third and fou
35f40 72 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74  rth parameters t
35f50 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  o this function 
35f60 61 72 65 20 74 68 65 20 74 61 62 6c 65 20 61 6e  are the table an
35f70 64 20 63 6f 6c 75 6d 6e 20 0a 2a 2a 20 6e 61 6d  d column .** nam
35f80 65 20 6f 66 20 74 68 65 20 64 65 73 69 72 65 64  e of the desired
35f90 20 63 6f 6c 75 6d 6e 2c 20 72 65 73 70 65 63 74   column, respect
35fa0 69 76 65 6c 79 2e 20 4e 65 69 74 68 65 72 20 6f  ively. Neither o
35fb0 66 20 74 68 65 73 65 20 70 61 72 61 6d 65 74 65  f these paramete
35fc0 72 73 20 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55  rs .** may be NU
35fd0 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 4d 65 74 61 20 69  LL..**.** Meta i
35fe0 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65  nformation is re
35ff0 74 75 72 6e 65 64 20 62 79 20 77 72 69 74 69 6e  turned by writin
36000 67 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 20  g to the memory 
36010 6c 6f 63 61 74 69 6f 6e 73 20 70 61 73 73 65 64  locations passed
36020 20 61 73 0a 2a 2a 20 74 68 65 20 35 74 68 20 61   as.** the 5th a
36030 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20 70 61  nd subsequent pa
36040 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 69 73  rameters to this
36050 20 66 75 6e 63 74 69 6f 6e 2e 20 41 6e 79 20 6f   function. Any o
36060 66 20 74 68 65 73 65 20 0a 2a 2a 20 61 72 67 75  f these .** argu
36070 6d 65 6e 74 73 20 6d 61 79 20 62 65 20 4e 55 4c  ments may be NUL
36080 4c 2c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65  L, in which case
36090 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
360a0 6e 67 20 65 6c 65 6d 65 6e 74 20 6f 66 20 6d 65  ng element of me
360b0 74 61 20 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  ta .** informati
360c0 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a  on is omitted..*
360d0 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 50 61  *.** <pre>.** Pa
360e0 72 61 6d 65 74 65 72 20 20 20 20 20 4f 75 74 70  rameter     Outp
360f0 75 74 20 54 79 70 65 20 20 20 20 20 20 44 65 73  ut Type      Des
36100 63 72 69 70 74 69 6f 6e 0a 2a 2a 20 2d 2d 2d 2d  cription.** ----
36110 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
36120 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a  ---------------.
36130 2a 2a 0a 2a 2a 20 20 20 35 74 68 20 20 20 20 20  **.**   5th     
36140 20 20 20 20 63 6f 6e 73 74 20 63 68 61 72 2a 20      const char* 
36150 20 20 20 20 20 44 61 74 61 20 74 79 70 65 0a 2a       Data type.*
36160 2a 20 20 20 36 74 68 20 20 20 20 20 20 20 20 20  *   6th         
36170 63 6f 6e 73 74 20 63 68 61 72 2a 20 20 20 20 20  const char*     
36180 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 64 65 66   Name of the def
36190 61 75 6c 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 73  ault collation s
361a0 65 71 75 65 6e 63 65 20 0a 2a 2a 20 20 20 37 74  equence .**   7t
361b0 68 20 20 20 20 20 20 20 20 20 69 6e 74 20 20 20  h         int   
361c0 20 20 20 20 20 20 20 20 20 20 20 54 72 75 65 20             True 
361d0 69 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 68 61  if the column ha
361e0 73 20 61 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e  s a NOT NULL con
361f0 73 74 72 61 69 6e 74 0a 2a 2a 20 20 20 38 74 68  straint.**   8th
36200 20 20 20 20 20 20 20 20 20 69 6e 74 20 20 20 20           int    
36210 20 20 20 20 20 20 20 20 20 20 54 72 75 65 20 69            True i
36220 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20  f the column is 
36230 70 61 72 74 20 6f 66 20 74 68 65 20 50 52 49 4d  part of the PRIM
36240 41 52 59 20 4b 45 59 0a 2a 2a 20 20 20 39 74 68  ARY KEY.**   9th
36250 20 20 20 20 20 20 20 20 20 69 6e 74 20 20 20 20           int    
36260 20 20 20 20 20 20 20 20 20 20 54 72 75 65 20 69            True i
36270 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20  f the column is 
36280 41 55 54 4f 49 4e 43 52 45 4d 45 4e 54 0a 2a 2a  AUTOINCREMENT.**
36290 20 3c 2f 70 72 65 3e 0a 2a 2a 0a 2a 2a 0a 2a 2a   </pre>.**.**.**
362a0 20 54 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e   The memory poin
362b0 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 63 68  ted to by the ch
362c0 61 72 61 63 74 65 72 20 70 6f 69 6e 74 65 72 73  aracter pointers
362d0 20 72 65 74 75 72 6e 65 64 20 66 6f 72 20 74 68   returned for th
362e0 65 20 0a 2a 2a 20 64 65 63 6c 61 72 61 74 69 6f  e .** declaratio
362f0 6e 20 74 79 70 65 20 61 6e 64 20 63 6f 6c 6c 61  n type and colla
36300 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 69 73  tion sequence is
36310 20 76 61 6c 69 64 20 6f 6e 6c 79 20 75 6e 74 69   valid only unti
36320 6c 20 74 68 65 20 6e 65 78 74 20 0a 2a 2a 20 63  l the next .** c
36330 61 6c 6c 20 74 6f 20 61 6e 79 20 73 71 6c 69 74  all to any sqlit
36340 65 20 41 50 49 20 66 75 6e 63 74 69 6f 6e 2e 0a  e API function..
36350 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 73 70 65  **.** If the spe
36360 63 69 66 69 65 64 20 74 61 62 6c 65 20 69 73 20  cified table is 
36370 61 63 74 75 61 6c 6c 79 20 61 20 76 69 65 77 2c  actually a view,
36380 20 74 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 69   then an error i
36390 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
363a0 2a 20 49 66 20 74 68 65 20 73 70 65 63 69 66 69  * If the specifi
363b0 65 64 20 63 6f 6c 75 6d 6e 20 69 73 20 22 72 6f  ed column is "ro
363c0 77 69 64 22 2c 20 22 6f 69 64 22 20 6f 72 20 22  wid", "oid" or "
363d0 5f 72 6f 77 69 64 5f 22 20 61 6e 64 20 61 6e 20  _rowid_" and an 
363e0 0a 2a 2a 20 49 4e 54 45 47 45 52 20 50 52 49 4d  .** INTEGER PRIM
363f0 41 52 59 20 4b 45 59 20 63 6f 6c 75 6d 6e 20 68  ARY KEY column h
36400 61 73 20 62 65 65 6e 20 65 78 70 6c 69 63 69 74  as been explicit
36410 6c 79 20 64 65 63 6c 61 72 65 64 2c 20 74 68 65  ly declared, the
36420 6e 20 74 68 65 20 6f 75 74 70 75 74 20 0a 2a 2a  n the output .**
36430 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20   parameters are 
36440 73 65 74 20 66 6f 72 20 74 68 65 20 65 78 70 6c  set for the expl
36450 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20  icitly declared 
36460 63 6f 6c 75 6d 6e 2e 20 49 66 20 74 68 65 72 65  column. If there
36470 20 69 73 20 6e 6f 0a 2a 2a 20 65 78 70 6c 69 63   is no.** explic
36480 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 49 50  itly declared IP
36490 4b 20 63 6f 6c 75 6d 6e 2c 20 74 68 65 6e 20 74  K column, then t
364a0 68 65 20 6f 75 74 70 75 74 20 70 61 72 61 6d 65  he output parame
364b0 74 65 72 73 20 61 72 65 20 73 65 74 20 61 73 20  ters are set as 
364c0 0a 2a 2a 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a  .** follows:.**.
364d0 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20  ** <pre>.**     
364e0 64 61 74 61 20 74 79 70 65 3a 20 22 49 4e 54 45  data type: "INTE
364f0 47 45 52 22 0a 2a 2a 20 20 20 20 20 63 6f 6c 6c  GER".**     coll
36500 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 3a 20  ation sequence: 
36510 22 42 49 4e 41 52 59 22 0a 2a 2a 20 20 20 20 20  "BINARY".**     
36520 6e 6f 74 20 6e 75 6c 6c 3a 20 30 0a 2a 2a 20 20  not null: 0.**  
36530 20 20 20 70 72 69 6d 61 72 79 20 6b 65 79 3a 20     primary key: 
36540 31 0a 2a 2a 20 20 20 20 20 61 75 74 6f 20 69 6e  1.**     auto in
36550 63 72 65 6d 65 6e 74 3a 20 30 0a 2a 2a 20 3c 2f  crement: 0.** </
36560 70 72 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  pre>.**.** This 
36570 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 6c 6f 61  function may loa
36580 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 73 63  d one or more sc
36590 68 65 6d 61 73 20 66 72 6f 6d 20 64 61 74 61 62  hemas from datab
365a0 61 73 65 20 66 69 6c 65 73 2e 20 49 66 20 61 6e  ase files. If an
365b0 0a 2a 2a 20 65 72 72 6f 72 20 6f 63 63 75 72 73  .** error occurs
365c0 20 64 75 72 69 6e 67 20 74 68 69 73 20 70 72 6f   during this pro
365d0 63 65 73 73 2c 20 6f 72 20 69 66 20 74 68 65 20  cess, or if the 
365e0 72 65 71 75 65 73 74 65 64 20 74 61 62 6c 65 20  requested table 
365f0 6f 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 63 61 6e  or column.** can
36600 6e 6f 74 20 62 65 20 66 6f 75 6e 64 2c 20 61 6e  not be found, an
36610 20 53 51 4c 49 54 45 20 65 72 72 6f 72 20 63 6f   SQLITE error co
36620 64 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 61  de is returned a
36630 6e 64 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73  nd an error mess
36640 61 67 65 0a 2a 2a 20 6c 65 66 74 20 69 6e 20 74  age.** left in t
36650 68 65 20 64 61 74 61 62 61 73 65 20 68 61 6e 64  he database hand
36660 6c 65 20 28 74 6f 20 62 65 20 72 65 74 72 69 65  le (to be retrie
36670 76 65 64 20 75 73 69 6e 67 20 73 71 6c 69 74 65  ved using sqlite
36680 33 5f 65 72 72 6d 73 67 28 29 29 2e 0a 2a 2a 0a  3_errmsg())..**.
36690 2a 2a 20 54 68 69 73 20 41 50 49 20 69 73 20 6f  ** This API is o
366a0 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66  nly available if
366b0 20 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 73   the library was
366c0 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74   compiled with t
366d0 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 45 4e 41  he.** SQLITE_ENA
366e0 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44  BLE_COLUMN_METAD
366f0 41 54 41 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ATA preprocessor
36700 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e   symbol defined.
36710 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
36720 74 61 62 6c 65 5f 63 6f 6c 75 6d 6e 5f 6d 65 74  table_column_met
36730 61 64 61 74 61 28 0a 20 20 73 71 6c 69 74 65 33  adata(.  sqlite3
36740 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
36750 20 20 20 20 20 2f 2a 20 43 6f 6e 6e 65 63 74 69       /* Connecti
36760 6f 6e 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  on handle */.  c
36770 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 4e 61  onst char *zDbNa
36780 6d 65 2c 20 20 20 20 20 20 20 20 2f 2a 20 44 61  me,        /* Da
36790 74 61 62 61 73 65 20 6e 61 6d 65 20 6f 72 20 4e  tabase name or N
367a0 55 4c 4c 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ULL */.  const c
367b0 68 61 72 20 2a 7a 54 61 62 6c 65 4e 61 6d 65 2c  har *zTableName,
367c0 20 20 20 20 20 2f 2a 20 54 61 62 6c 65 20 6e 61       /* Table na
367d0 6d 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  me */.  const ch
367e0 61 72 20 2a 7a 43 6f 6c 75 6d 6e 4e 61 6d 65 2c  ar *zColumnName,
367f0 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 61      /* Column na
36800 6d 65 20 2a 2f 0a 20 20 63 68 61 72 20 63 6f 6e  me */.  char con
36810 73 74 20 2a 2a 70 7a 44 61 74 61 54 79 70 65 2c  st **pzDataType,
36820 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 44      /* OUTPUT: D
36830 65 63 6c 61 72 65 64 20 64 61 74 61 20 74 79 70  eclared data typ
36840 65 20 2a 2f 0a 20 20 63 68 61 72 20 63 6f 6e 73  e */.  char cons
36850 74 20 2a 2a 70 7a 43 6f 6c 6c 53 65 71 2c 20 20  t **pzCollSeq,  
36860 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 43 6f     /* OUTPUT: Co
36870 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
36880 20 6e 61 6d 65 20 2a 2f 0a 20 20 69 6e 74 20 2a   name */.  int *
36890 70 4e 6f 74 4e 75 6c 6c 2c 20 20 20 20 20 20 20  pNotNull,       
368a0 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54         /* OUTPUT
368b0 3a 20 54 72 75 65 20 69 66 20 4e 4f 54 20 4e 55  : True if NOT NU
368c0 4c 4c 20 63 6f 6e 73 74 72 61 69 6e 74 20 65 78  LL constraint ex
368d0 69 73 74 73 20 2a 2f 0a 20 20 69 6e 74 20 2a 70  ists */.  int *p
368e0 50 72 69 6d 61 72 79 4b 65 79 2c 20 20 20 20 20  PrimaryKey,     
368f0 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a        /* OUTPUT:
36900 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20   True if column 
36910 70 61 72 74 20 6f 66 20 50 4b 20 2a 2f 0a 20 20  part of PK */.  
36920 69 6e 74 20 2a 70 41 75 74 6f 69 6e 63 20 20 20  int *pAutoinc   
36930 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f              /* O
36940 55 54 50 55 54 3a 20 54 72 75 65 20 69 66 20 63  UTPUT: True if c
36950 6f 6c 75 6d 6e 20 69 73 20 61 75 74 6f 2d 69 6e  olumn is auto-in
36960 63 72 65 6d 65 6e 74 20 2a 2f 0a 29 3b 0a 0a 2f  crement */.);../
36970 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c  *.** CAPI3REF: L
36980 6f 61 64 20 41 6e 20 45 78 74 65 6e 73 69 6f 6e  oad An Extension
36990 20 7b 46 31 32 36 30 30 7d 0a 2a 2a 0a 2a 2a 20   {F12600}.**.** 
369a0 7b 46 31 32 36 30 31 7d 20 54 68 65 20 73 71 6c  {F12601} The sql
369b0 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73  ite3_load_extens
369c0 69 6f 6e 28 29 20 69 6e 74 65 72 66 61 63 65 0a  ion() interface.
369d0 2a 2a 20 61 74 74 65 6d 70 74 73 20 74 6f 20 6c  ** attempts to l
369e0 6f 61 64 20 61 6e 20 53 51 4c 69 74 65 20 65 78  oad an SQLite ex
369f0 74 65 6e 73 69 6f 6e 20 6c 69 62 72 61 72 79 20  tension library 
36a00 63 6f 6e 74 61 69 6e 65 64 20 69 6e 20 74 68 65  contained in the
36a10 20 66 69 6c 65 0a 2a 2a 20 7a 46 69 6c 65 2e 20   file.** zFile. 
36a20 7b 46 31 32 36 30 32 7d 20 54 68 65 20 65 6e 74  {F12602} The ent
36a30 72 79 20 70 6f 69 6e 74 20 69 73 20 7a 50 72 6f  ry point is zPro
36a40 63 2e 20 7b 46 31 32 36 30 33 7d 20 7a 50 72 6f  c. {F12603} zPro
36a50 63 20 6d 61 79 20 62 65 20 30 0a 2a 2a 20 69 6e  c may be 0.** in
36a60 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20   which case the 
36a70 6e 61 6d 65 20 6f 66 20 74 68 65 20 65 6e 74 72  name of the entr
36a80 79 20 70 6f 69 6e 74 20 64 65 66 61 75 6c 74 73  y point defaults
36a90 0a 2a 2a 20 74 6f 20 22 73 71 6c 69 74 65 33 5f  .** to "sqlite3_
36aa0 65 78 74 65 6e 73 69 6f 6e 5f 69 6e 69 74 22 2e  extension_init".
36ab0 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36 30 34 7d 20  .**.** {F12604} 
36ac0 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64  The sqlite3_load
36ad0 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e 74  _extension() int
36ae0 65 72 66 61 63 65 20 73 68 61 6c 6c 0a 2a 2a 20  erface shall.** 
36af0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
36b00 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e  K] on success an
36b10 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  d [SQLITE_ERROR]
36b20 20 69 66 20 73 6f 6d 65 74 68 69 6e 67 20 67 6f   if something go
36b30 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 0a 2a 2a 20  es wrong..**.** 
36b40 7b 46 31 32 36 30 35 7d 0a 2a 2a 20 49 66 20 61  {F12605}.** If a
36b50 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 61  n error occurs a
36b60 6e 64 20 70 7a 45 72 72 4d 73 67 20 69 73 20 6e  nd pzErrMsg is n
36b70 6f 74 20 30 2c 20 74 68 65 6e 20 74 68 65 0a 2a  ot 0, then the.*
36b80 2a 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65  * sqlite3_load_e
36b90 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e 74 65 72  xtension() inter
36ba0 66 61 63 65 20 73 68 61 6c 6c 20 61 74 74 65 6d  face shall attem
36bb0 70 74 20 74 6f 20 66 69 6c 6c 20 2a 70 7a 45 72  pt to fill *pzEr
36bc0 72 4d 73 67 20 77 69 74 68 20 0a 2a 2a 20 65 72  rMsg with .** er
36bd0 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78 74  ror message text
36be0 20 73 74 6f 72 65 64 20 69 6e 20 6d 65 6d 6f 72   stored in memor
36bf0 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
36c00 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
36c10 29 5d 2e 0a 2a 2a 20 7b 45 4e 44 7d 20 20 54 68  )]..** {END}  Th
36c20 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69  e calling functi
36c30 6f 6e 20 73 68 6f 75 6c 64 20 66 72 65 65 20 74  on should free t
36c40 68 69 73 20 6d 65 6d 6f 72 79 0a 2a 2a 20 62 79  his memory.** by
36c50 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
36c60 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  3_free()]..**.**
36c70 20 7b 46 31 32 36 30 36 7d 0a 2a 2a 20 45 78 74   {F12606}.** Ext
36c80 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 6d  ension loading m
36c90 75 73 74 20 62 65 20 65 6e 61 62 6c 65 64 20 75  ust be enabled u
36ca0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e  sing [sqlite3_en
36cb0 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73  able_load_extens
36cc0 69 6f 6e 28 29 5d 0a 2a 2a 20 70 72 69 6f 72 20  ion()].** prior 
36cd0 74 6f 20 63 61 6c 6c 69 6e 67 20 74 68 69 73 20  to calling this 
36ce0 41 50 49 20 6f 72 20 61 6e 20 65 72 72 6f 72 20  API or an error 
36cf0 77 69 6c 6c 20 62 65 20 72 65 74 75 72 6e 65 64  will be returned
36d00 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
36d10 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28  _load_extension(
36d20 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
36d30 20 20 20 20 20 20 20 20 20 2f 2a 20 4c 6f 61 64           /* Load
36d40 20 74 68 65 20 65 78 74 65 6e 73 69 6f 6e 20 69   the extension i
36d50 6e 74 6f 20 74 68 69 73 20 64 61 74 61 62 61 73  nto this databas
36d60 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 2a 2f 0a  e connection */.
36d70 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46    const char *zF
36d80 69 6c 65 2c 20 20 20 20 2f 2a 20 4e 61 6d 65 20  ile,    /* Name 
36d90 6f 66 20 74 68 65 20 73 68 61 72 65 64 20 6c 69  of the shared li
36da0 62 72 61 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67  brary containing
36db0 20 65 78 74 65 6e 73 69 6f 6e 20 2a 2f 0a 20 20   extension */.  
36dc0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 72 6f  const char *zPro
36dd0 63 2c 20 20 20 20 2f 2a 20 45 6e 74 72 79 20 70  c,    /* Entry p
36de0 6f 69 6e 74 2e 20 20 44 65 72 69 76 65 64 20 66  oint.  Derived f
36df0 72 6f 6d 20 7a 46 69 6c 65 20 69 66 20 30 20 2a  rom zFile if 0 *
36e00 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72  /.  char **pzErr
36e10 4d 73 67 20 20 20 20 20 20 20 2f 2a 20 50 75 74  Msg       /* Put
36e20 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 68   error message h
36e30 65 72 65 20 69 66 20 6e 6f 74 20 30 20 2a 2f 0a  ere if not 0 */.
36e40 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
36e50 45 46 3a 20 20 45 6e 61 62 6c 65 20 4f 72 20 44  EF:  Enable Or D
36e60 69 73 61 62 6c 65 20 45 78 74 65 6e 73 69 6f 6e  isable Extension
36e70 20 4c 6f 61 64 69 6e 67 20 7b 46 31 32 36 32 30   Loading {F12620
36e80 7d 0a 2a 2a 0a 2a 2a 20 53 6f 20 61 73 20 6e 6f  }.**.** So as no
36e90 74 20 74 6f 20 6f 70 65 6e 20 73 65 63 75 72 69  t to open securi
36ea0 74 79 20 68 6f 6c 65 73 20 69 6e 20 6f 6c 64 65  ty holes in olde
36eb0 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  r applications t
36ec0 68 61 74 20 61 72 65 0a 2a 2a 20 75 6e 70 72 65  hat are.** unpre
36ed0 70 61 72 65 64 20 74 6f 20 64 65 61 6c 20 77 69  pared to deal wi
36ee0 74 68 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61  th extension loa
36ef0 64 69 6e 67 2c 20 61 6e 64 20 61 73 20 61 20 6d  ding, and as a m
36f00 65 61 6e 73 20 6f 66 20 64 69 73 61 62 6c 69 6e  eans of disablin
36f10 67 0a 2a 2a 20 65 78 74 65 6e 73 69 6f 6e 20 6c  g.** extension l
36f20 6f 61 64 69 6e 67 20 77 68 69 6c 65 20 65 76 61  oading while eva
36f30 6c 75 61 74 69 6e 67 20 75 73 65 72 2d 65 6e 74  luating user-ent
36f40 65 72 65 64 20 53 51 4c 2c 20 74 68 65 20 66 6f  ered SQL, the fo
36f50 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 41 50 49 20 69  llowing.** API i
36f60 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20 74 75  s provided to tu
36f70 72 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  rn the [sqlite3_
36f80 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29  load_extension()
36f90 5d 20 6d 65 63 68 61 6e 69 73 6d 20 6f 6e 20 61  ] mechanism on a
36fa0 6e 64 0a 2a 2a 20 6f 66 66 2e 20 20 7b 46 31 32  nd.** off.  {F12
36fb0 36 32 32 7d 20 49 74 20 69 73 20 6f 66 66 20 62  622} It is off b
36fc0 79 20 64 65 66 61 75 6c 74 2e 20 7b 45 4e 44 7d  y default. {END}
36fd0 20 53 65 65 20 74 69 63 6b 65 74 20 23 31 38 36   See ticket #186
36fe0 33 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36 32 31  3..**.** {F12621
36ff0 7d 20 43 61 6c 6c 20 74 68 65 20 73 71 6c 69 74  } Call the sqlit
37000 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65  e3_enable_load_e
37010 78 74 65 6e 73 69 6f 6e 28 29 20 72 6f 75 74 69  xtension() routi
37020 6e 65 0a 2a 2a 20 77 69 74 68 20 6f 6e 6f 66 66  ne.** with onoff
37030 3d 3d 31 20 74 6f 20 74 75 72 6e 20 65 78 74 65  ==1 to turn exte
37040 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 6f 6e  nsion loading on
37050 0a 2a 2a 20 61 6e 64 20 63 61 6c 6c 20 69 74 20  .** and call it 
37060 77 69 74 68 20 6f 6e 6f 66 66 3d 3d 30 20 74 6f  with onoff==0 to
37070 20 74 75 72 6e 20 69 74 20 62 61 63 6b 20 6f 66   turn it back of
37080 66 20 61 67 61 69 6e 2e 20 7b 45 4e 44 7d 0a 2a  f again. {END}.*
37090 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 6e  /.int sqlite3_en
370a0 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73  able_load_extens
370b0 69 6f 6e 28 73 71 6c 69 74 65 33 20 2a 64 62 2c  ion(sqlite3 *db,
370c0 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a   int onoff);../*
370d0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 61  .** CAPI3REF: Ma
370e0 6b 65 20 41 72 72 61 6e 67 65 6d 65 6e 74 73 20  ke Arrangements 
370f0 54 6f 20 41 75 74 6f 6d 61 74 69 63 61 6c 6c 79  To Automatically
37100 20 4c 6f 61 64 20 41 6e 20 45 78 74 65 6e 73 69   Load An Extensi
37110 6f 6e 20 7b 46 31 32 36 34 30 7d 0a 2a 2a 0a 2a  on {F12640}.**.*
37120 2a 20 7b 46 31 32 36 34 31 7d 20 54 68 69 73 20  * {F12641} This 
37130 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 72 65 67 69  function.** regi
37140 73 74 65 72 73 20 61 6e 20 65 78 74 65 6e 73 69  sters an extensi
37150 6f 6e 20 65 6e 74 72 79 20 70 6f 69 6e 74 20 74  on entry point t
37160 68 61 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63  hat is automatic
37170 61 6c 6c 79 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20  ally invoked.** 
37180 77 68 65 6e 65 76 65 72 20 61 20 6e 65 77 20 64  whenever a new d
37190 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
371a0 6f 6e 20 69 73 20 6f 70 65 6e 65 64 20 75 73 69  on is opened usi
371b0 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f  ng.** [sqlite3_o
371c0 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  pen()], [sqlite3
371d0 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72 20 5b  _open16()], or [
371e0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
371f0 29 5d 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20  )]. {END}.**.** 
37200 54 68 69 73 20 41 50 49 20 63 61 6e 20 62 65 20  This API can be 
37210 69 6e 76 6f 6b 65 64 20 61 74 20 70 72 6f 67 72  invoked at progr
37220 61 6d 20 73 74 61 72 74 75 70 20 69 6e 20 6f 72  am startup in or
37230 64 65 72 20 74 6f 20 72 65 67 69 73 74 65 72 0a  der to register.
37240 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 73  ** one or more s
37250 74 61 74 69 63 61 6c 6c 79 20 6c 69 6e 6b 65 64  tatically linked
37260 20 65 78 74 65 6e 73 69 6f 6e 73 20 74 68 61 74   extensions that
37270 20 77 69 6c 6c 20 62 65 20 61 76 61 69 6c 61 62   will be availab
37280 6c 65 0a 2a 2a 20 74 6f 20 61 6c 6c 20 6e 65 77  le.** to all new
37290 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
372a0 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  tions..**.** {F1
372b0 32 36 34 32 7d 20 44 75 70 6c 69 63 61 74 65 20  2642} Duplicate 
372c0 65 78 74 65 6e 73 69 6f 6e 73 20 61 72 65 20 64  extensions are d
372d0 65 74 65 63 74 65 64 20 73 6f 20 63 61 6c 6c 69  etected so calli
372e0 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ng this routine 
372f0 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65  multiple.** time
37300 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20  s with the same 
37310 65 78 74 65 6e 73 69 6f 6e 20 69 73 20 68 61 72  extension is har
37320 6d 6c 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  mless..**.** {F1
37330 32 36 34 33 7d 20 54 68 69 73 20 72 6f 75 74 69  2643} This routi
37340 6e 65 20 73 74 6f 72 65 73 20 61 20 70 6f 69 6e  ne stores a poin
37350 74 65 72 20 74 6f 20 74 68 65 20 65 78 74 65 6e  ter to the exten
37360 73 69 6f 6e 20 69 6e 20 61 6e 20 61 72 72 61 79  sion in an array
37370 0a 2a 2a 20 74 68 61 74 20 69 73 20 6f 62 74 61  .** that is obta
37380 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65  ined from sqlite
37390 5f 6d 61 6c 6c 6f 63 28 29 2e 20 7b 45 4e 44 7d  _malloc(). {END}
373a0 20 49 66 20 79 6f 75 20 72 75 6e 20 61 20 6d 65   If you run a me
373b0 6d 6f 72 79 20 6c 65 61 6b 0a 2a 2a 20 63 68 65  mory leak.** che
373c0 63 6b 65 72 20 6f 6e 20 79 6f 75 72 20 70 72 6f  cker on your pro
373d0 67 72 61 6d 20 61 6e 64 20 69 74 20 72 65 70 6f  gram and it repo
373e0 72 74 73 20 61 20 6c 65 61 6b 20 62 65 63 61 75  rts a leak becau
373f0 73 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 61 72  se of this.** ar
37400 72 61 79 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65  ray, then invoke
37410 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 5f   [sqlite3_reset_
37420 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 29  auto_extension()
37430 5d 20 70 72 69 6f 72 0a 2a 2a 20 74 6f 20 73 68  ] prior.** to sh
37440 75 74 64 6f 77 6e 20 74 6f 20 66 72 65 65 20 74  utdown to free t
37450 68 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 0a 2a 2a  he memory..**.**
37460 20 7b 46 31 32 36 34 34 7d 20 41 75 74 6f 6d 61   {F12644} Automa
37470 74 69 63 20 65 78 74 65 6e 73 69 6f 6e 73 20 61  tic extensions a
37480 70 70 6c 79 20 61 63 72 6f 73 73 20 61 6c 6c 20  pply across all 
37490 74 68 72 65 61 64 73 2e 20 7b 45 4e 44 7d 0a 2a  threads. {END}.*
374a0 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66  *.** This interf
374b0 61 63 65 20 69 73 20 65 78 70 65 72 69 6d 65 6e  ace is experimen
374c0 74 61 6c 20 61 6e 64 20 69 73 20 73 75 62 6a 65  tal and is subje
374d0 63 74 20 74 6f 20 63 68 61 6e 67 65 20 6f 72 0a  ct to change or.
374e0 2a 2a 20 72 65 6d 6f 76 61 6c 20 69 6e 20 66 75  ** removal in fu
374f0 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
37500 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20   SQLite..*/.int 
37510 73 71 6c 69 74 65 33 5f 61 75 74 6f 5f 65 78 74  sqlite3_auto_ext
37520 65 6e 73 69 6f 6e 28 76 6f 69 64 20 2a 78 45 6e  ension(void *xEn
37530 74 72 79 50 6f 69 6e 74 29 3b 0a 0a 0a 2f 2a 0a  tryPoint);.../*.
37540 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73  ** CAPI3REF: Res
37550 65 74 20 41 75 74 6f 6d 61 74 69 63 20 45 78 74  et Automatic Ext
37560 65 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e 67 20 7b  ension Loading {
37570 46 31 32 36 36 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46  F12660}.**.** {F
37580 31 32 36 36 31 7d 20 54 68 69 73 20 66 75 6e 63  12661} This func
37590 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 20 61 6c  tion disables al
375a0 6c 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 67  l previously reg
375b0 69 73 74 65 72 65 64 0a 2a 2a 20 61 75 74 6f 6d  istered.** autom
375c0 61 74 69 63 20 65 78 74 65 6e 73 69 6f 6e 73 2e  atic extensions.
375d0 20 7b 45 4e 44 7d 20 20 54 68 69 73 0a 2a 2a 20   {END}  This.** 
375e0 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74  routine undoes t
375f0 68 65 20 65 66 66 65 63 74 20 6f 66 20 61 6c 6c  he effect of all
37600 20 70 72 69 6f 72 20 5b 73 71 6c 69 74 65 33 5f   prior [sqlite3_
37610 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 29  auto_extension()
37620 5d 0a 2a 2a 20 63 61 6c 6c 73 2e 0a 2a 2a 0a 2a  ].** calls..**.*
37630 2a 20 7b 46 31 32 36 36 32 7d 20 54 68 69 73 20  * {F12662} This 
37640 63 61 6c 6c 20 64 69 73 61 62 6c 65 64 20 61 75  call disabled au
37650 74 6f 6d 61 74 69 63 20 65 78 74 65 6e 73 69 6f  tomatic extensio
37660 6e 73 20 69 6e 20 61 6c 6c 20 74 68 72 65 61 64  ns in all thread
37670 73 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54  s. {END}.**.** T
37680 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73  his interface is
37690 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e   experimental an
376a0 64 20 69 73 20 73 75 62 6a 65 63 74 20 74 6f 20  d is subject to 
376b0 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 72 65 6d  change or.** rem
376c0 6f 76 61 6c 20 69 6e 20 66 75 74 75 72 65 20 72  oval in future r
376d0 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
376e0 65 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  e..*/.void sqlit
376f0 65 33 5f 72 65 73 65 74 5f 61 75 74 6f 5f 65 78  e3_reset_auto_ex
37700 74 65 6e 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 0a  tension(void);..
37710 0a 2f 2a 0a 2a 2a 2a 2a 2a 2a 20 45 58 50 45 52  ./*.****** EXPER
37720 49 4d 45 4e 54 41 4c 20 2d 20 73 75 62 6a 65 63  IMENTAL - subjec
37730 74 20 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68  t to change with
37740 6f 75 74 20 6e 6f 74 69 63 65 20 2a 2a 2a 2a 2a  out notice *****
37750 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2a 0a 2a 2a 20  *********.**.** 
37760 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f  The interface to
37770 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62   the virtual-tab
37780 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 69 73 20  le mechanism is 
37790 63 75 72 72 65 6e 74 6c 79 20 63 6f 6e 73 69 64  currently consid
377a0 65 72 65 64 0a 2a 2a 20 74 6f 20 62 65 20 65 78  ered.** to be ex
377b0 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 54 68 65  perimental.  The
377c0 20 69 6e 74 65 72 66 61 63 65 20 6d 69 67 68 74   interface might
377d0 20 63 68 61 6e 67 65 20 69 6e 20 69 6e 63 6f 6d   change in incom
377e0 70 61 74 69 62 6c 65 20 77 61 79 73 2e 0a 2a 2a  patible ways..**
377f0 20 49 66 20 74 68 69 73 20 69 73 20 61 20 70 72   If this is a pr
37800 6f 62 6c 65 6d 20 66 6f 72 20 79 6f 75 2c 20 64  oblem for you, d
37810 6f 20 6e 6f 74 20 75 73 65 20 74 68 65 20 69 6e  o not use the in
37820 74 65 72 66 61 63 65 20 61 74 20 74 68 69 73 20  terface at this 
37830 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  time..**.** When
37840 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62   the virtual-tab
37850 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 73 74 61  le mechanism sta
37860 62 69 6c 69 7a 65 73 2c 20 77 65 20 77 69 6c 6c  bilizes, we will
37870 20 64 65 63 6c 61 72 65 20 74 68 65 0a 2a 2a 20   declare the.** 
37880 69 6e 74 65 72 66 61 63 65 20 66 69 78 65 64 2c  interface fixed,
37890 20 73 75 70 70 6f 72 74 20 69 74 20 69 6e 64 65   support it inde
378a0 66 69 6e 69 74 65 6c 79 2c 20 61 6e 64 20 72 65  finitely, and re
378b0 6d 6f 76 65 20 74 68 69 73 20 63 6f 6d 6d 65 6e  move this commen
378c0 74 2e 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 53 74 72  t..*/../*.** Str
378d0 75 63 74 75 72 65 73 20 75 73 65 64 20 62 79 20  uctures used by 
378e0 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c  the virtual tabl
378f0 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2f 0a 74  e interface.*/.t
37900 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
37910 6c 69 74 65 33 5f 76 74 61 62 20 73 71 6c 69 74  lite3_vtab sqlit
37920 65 33 5f 76 74 61 62 3b 0a 74 79 70 65 64 65 66  e3_vtab;.typedef
37930 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
37940 69 6e 64 65 78 5f 69 6e 66 6f 20 73 71 6c 69 74  index_info sqlit
37950 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 3b 0a 74  e3_index_info;.t
37960 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
37970 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f  lite3_vtab_curso
37980 72 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63  r sqlite3_vtab_c
37990 75 72 73 6f 72 3b 0a 74 79 70 65 64 65 66 20 73  ursor;.typedef s
379a0 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 6f  truct sqlite3_mo
379b0 64 75 6c 65 20 73 71 6c 69 74 65 33 5f 6d 6f 64  dule sqlite3_mod
379c0 75 6c 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ule;../*.** CAPI
379d0 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61  3REF: Virtual Ta
379e0 62 6c 65 20 4f 62 6a 65 63 74 20 7b 46 31 38 30  ble Object {F180
379f0 30 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  00}.** KEYWORDS:
37a00 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 0a   sqlite3_module.
37a10 2a 2a 0a 2a 2a 20 41 20 6d 6f 64 75 6c 65 20 69  **.** A module i
37a20 73 20 61 20 63 6c 61 73 73 20 6f 66 20 76 69 72  s a class of vir
37a30 74 75 61 6c 20 74 61 62 6c 65 73 2e 20 20 45 61  tual tables.  Ea
37a40 63 68 20 6d 6f 64 75 6c 65 20 69 73 20 64 65 66  ch module is def
37a50 69 6e 65 64 0a 2a 2a 20 62 79 20 61 6e 20 69 6e  ined.** by an in
37a60 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 66 6f  stance of the fo
37a70 6c 6c 6f 77 69 6e 67 20 73 74 72 75 63 74 75 72  llowing structur
37a80 65 2e 20 20 54 68 69 73 20 73 74 72 75 63 74 75  e.  This structu
37a90 72 65 20 63 6f 6e 73 69 73 74 73 0a 2a 2a 20 6d  re consists.** m
37aa0 6f 73 74 6c 79 20 6f 66 20 6d 65 74 68 6f 64 73  ostly of methods
37ab0 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 2e   for the module.
37ac0 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74  .*/.struct sqlit
37ad0 65 33 5f 6d 6f 64 75 6c 65 20 7b 0a 20 20 69 6e  e3_module {.  in
37ae0 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e  t iVersion;.  in
37af0 74 20 28 2a 78 43 72 65 61 74 65 29 28 73 71 6c  t (*xCreate)(sql
37b00 69 74 65 33 2a 2c 20 76 6f 69 64 20 2a 70 41 75  ite3*, void *pAu
37b10 78 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  x,.             
37b20 20 20 69 6e 74 20 61 72 67 63 2c 20 63 6f 6e 73    int argc, cons
37b30 74 20 63 68 61 72 20 2a 63 6f 6e 73 74 2a 61 72  t char *const*ar
37b40 67 76 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  gv,.            
37b50 20 20 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20     sqlite3_vtab 
37b60 2a 2a 70 70 56 54 61 62 2c 20 63 68 61 72 2a 2a  **ppVTab, char**
37b70 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6e 6e  );.  int (*xConn
37b80 65 63 74 29 28 73 71 6c 69 74 65 33 2a 2c 20 76  ect)(sqlite3*, v
37b90 6f 69 64 20 2a 70 41 75 78 2c 0a 20 20 20 20 20  oid *pAux,.     
37ba0 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 61 72            int ar
37bb0 67 63 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  gc, const char *
37bc0 63 6f 6e 73 74 2a 61 72 67 76 2c 0a 20 20 20 20  const*argv,.    
37bd0 20 20 20 20 20 20 20 20 20 20 20 73 71 6c 69 74             sqlit
37be0 65 33 5f 76 74 61 62 20 2a 2a 70 70 56 54 61 62  e3_vtab **ppVTab
37bf0 2c 20 63 68 61 72 2a 2a 29 3b 0a 20 20 69 6e 74  , char**);.  int
37c00 20 28 2a 78 42 65 73 74 49 6e 64 65 78 29 28 73   (*xBestIndex)(s
37c10 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54  qlite3_vtab *pVT
37c20 61 62 2c 20 73 71 6c 69 74 65 33 5f 69 6e 64 65  ab, sqlite3_inde
37c30 78 5f 69 6e 66 6f 2a 29 3b 0a 20 20 69 6e 74 20  x_info*);.  int 
37c40 28 2a 78 44 69 73 63 6f 6e 6e 65 63 74 29 28 73  (*xDisconnect)(s
37c50 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54  qlite3_vtab *pVT
37c60 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65  ab);.  int (*xDe
37c70 73 74 72 6f 79 29 28 73 71 6c 69 74 65 33 5f 76  stroy)(sqlite3_v
37c80 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69  tab *pVTab);.  i
37c90 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69  nt (*xOpen)(sqli
37ca0 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 2c  te3_vtab *pVTab,
37cb0 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75   sqlite3_vtab_cu
37cc0 72 73 6f 72 20 2a 2a 70 70 43 75 72 73 6f 72 29  rsor **ppCursor)
37cd0 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65  ;.  int (*xClose
37ce0 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63  )(sqlite3_vtab_c
37cf0 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28  ursor*);.  int (
37d00 2a 78 46 69 6c 74 65 72 29 28 73 71 6c 69 74 65  *xFilter)(sqlite
37d10 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20  3_vtab_cursor*, 
37d20 69 6e 74 20 69 64 78 4e 75 6d 2c 20 63 6f 6e 73  int idxNum, cons
37d30 74 20 63 68 61 72 20 2a 69 64 78 53 74 72 2c 0a  t char *idxStr,.
37d40 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
37d50 69 6e 74 20 61 72 67 63 2c 20 73 71 6c 69 74 65  int argc, sqlite
37d60 33 5f 76 61 6c 75 65 20 2a 2a 61 72 67 76 29 3b  3_value **argv);
37d70 0a 20 20 69 6e 74 20 28 2a 78 4e 65 78 74 29 28  .  int (*xNext)(
37d80 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72  sqlite3_vtab_cur
37d90 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  sor*);.  int (*x
37da0 45 6f 66 29 28 73 71 6c 69 74 65 33 5f 76 74 61  Eof)(sqlite3_vta
37db0 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e  b_cursor*);.  in
37dc0 74 20 28 2a 78 43 6f 6c 75 6d 6e 29 28 73 71 6c  t (*xColumn)(sql
37dd0 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72  ite3_vtab_cursor
37de0 2a 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  *, sqlite3_conte
37df0 78 74 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74  xt*, int);.  int
37e00 20 28 2a 78 52 6f 77 69 64 29 28 73 71 6c 69 74   (*xRowid)(sqlit
37e10 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c  e3_vtab_cursor*,
37e20 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a   sqlite3_int64 *
37e30 70 52 6f 77 69 64 29 3b 0a 20 20 69 6e 74 20 28  pRowid);.  int (
37e40 2a 78 55 70 64 61 74 65 29 28 73 71 6c 69 74 65  *xUpdate)(sqlite
37e50 33 5f 76 74 61 62 20 2a 2c 20 69 6e 74 2c 20 73  3_vtab *, int, s
37e60 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 2a 2c  qlite3_value **,
37e70 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a   sqlite3_int64 *
37e80 29 3b 0a 20 20 69 6e 74 20 28 2a 78 42 65 67 69  );.  int (*xBegi
37e90 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20  n)(sqlite3_vtab 
37ea0 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28  *pVTab);.  int (
37eb0 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f  *xSync)(sqlite3_
37ec0 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20  vtab *pVTab);.  
37ed0 69 6e 74 20 28 2a 78 43 6f 6d 6d 69 74 29 28 73  int (*xCommit)(s
37ee0 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54  qlite3_vtab *pVT
37ef0 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 6f  ab);.  int (*xRo
37f00 6c 6c 62 61 63 6b 29 28 73 71 6c 69 74 65 33 5f  llback)(sqlite3_
37f10 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20  vtab *pVTab);.  
37f20 69 6e 74 20 28 2a 78 46 69 6e 64 46 75 6e 63 74  int (*xFindFunct
37f30 69 6f 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61  ion)(sqlite3_vta
37f40 62 20 2a 70 56 74 61 62 2c 20 69 6e 74 20 6e 41  b *pVtab, int nA
37f50 72 67 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  rg, const char *
37f60 7a 4e 61 6d 65 2c 0a 20 20 20 20 20 20 20 20 20  zName,.         
37f70 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f                vo
37f80 69 64 20 28 2a 2a 70 78 46 75 6e 63 29 28 73 71  id (**pxFunc)(sq
37f90 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
37fa0 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
37fb0 2a 2a 29 2c 0a 20 20 20 20 20 20 20 20 20 20 20  **),.           
37fc0 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64              void
37fd0 20 2a 2a 70 70 41 72 67 29 3b 0a 0a 20 20 69 6e   **ppArg);..  in
37fe0 74 20 28 2a 78 52 65 6e 61 6d 65 29 28 73 71 6c  t (*xRename)(sql
37ff0 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62  ite3_vtab *pVtab
38000 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
38010 65 77 29 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ew);.};../*.** C
38020 41 50 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c  API3REF: Virtual
38030 20 54 61 62 6c 65 20 49 6e 64 65 78 69 6e 67 20   Table Indexing 
38040 49 6e 66 6f 72 6d 61 74 69 6f 6e 20 7b 46 31 38  Information {F18
38050 31 30 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  100}.** KEYWORDS
38060 3a 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f  : sqlite3_index_
38070 69 6e 66 6f 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  info.**.** The s
38080 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66  qlite3_index_inf
38090 6f 20 73 74 72 75 63 74 75 72 65 20 61 6e 64 20  o structure and 
380a0 69 74 73 20 73 75 62 73 74 72 75 63 74 75 72 65  its substructure
380b0 73 20 69 73 20 75 73 65 64 20 74 6f 0a 2a 2a 20  s is used to.** 
380c0 70 61 73 73 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  pass information
380d0 20 69 6e 74 6f 20 61 6e 64 20 72 65 63 65 69 76   into and receiv
380e0 65 20 74 68 65 20 72 65 70 6c 79 20 66 72 6f 6d  e the reply from
380f0 20 74 68 65 20 78 42 65 73 74 49 6e 64 65 78 0a   the xBestIndex.
38100 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20  ** method of an 
38110 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 2e 20  sqlite3_module. 
38120 20 54 68 65 20 66 69 65 6c 64 73 20 75 6e 64 65   The fields unde
38130 72 20 2a 2a 49 6e 70 75 74 73 2a 2a 20 61 72 65  r **Inputs** are
38140 20 74 68 65 0a 2a 2a 20 69 6e 70 75 74 73 20 74   the.** inputs t
38150 6f 20 78 42 65 73 74 49 6e 64 65 78 20 61 6e 64  o xBestIndex and
38160 20 61 72 65 20 72 65 61 64 2d 6f 6e 6c 79 2e 20   are read-only. 
38170 20 78 42 65 73 74 49 6e 64 65 78 20 69 6e 73 65   xBestIndex inse
38180 72 74 73 20 69 74 73 0a 2a 2a 20 72 65 73 75 6c  rts its.** resul
38190 74 73 20 69 6e 74 6f 20 74 68 65 20 2a 2a 4f 75  ts into the **Ou
381a0 74 70 75 74 73 2a 2a 20 66 69 65 6c 64 73 2e 0a  tputs** fields..
381b0 2a 2a 0a 2a 2a 20 54 68 65 20 61 43 6f 6e 73 74  **.** The aConst
381c0 72 61 69 6e 74 5b 5d 20 61 72 72 61 79 20 72 65  raint[] array re
381d0 63 6f 72 64 73 20 57 48 45 52 45 20 63 6c 61 75  cords WHERE clau
381e0 73 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 6f  se constraints o
381f0 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 3a 0a 2a  f the.** form:.*
38200 2a 0a 2a 2a 20 20 20 20 20 20 20 20 20 63 6f 6c  *.**         col
38210 75 6d 6e 20 4f 50 20 65 78 70 72 0a 2a 2a 0a 2a  umn OP expr.**.*
38220 2a 20 57 68 65 72 65 20 4f 50 20 69 73 20 3d 2c  * Where OP is =,
38230 20 26 6c 74 3b 2c 20 26 6c 74 3b 3d 2c 20 26 67   &lt;, &lt;=, &g
38240 74 3b 2c 20 6f 72 20 26 67 74 3b 3d 2e 20 20 0a  t;, or &gt;=.  .
38250 2a 2a 20 54 68 65 20 70 61 72 74 69 63 75 6c 61  ** The particula
38260 72 20 6f 70 65 72 61 74 6f 72 20 69 73 20 73 74  r operator is st
38270 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 43 6f 6e 73  ored.** in aCons
38280 74 72 61 69 6e 74 5b 5d 2e 6f 70 2e 20 20 54 68  traint[].op.  Th
38290 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63  e index of the c
382a0 6f 6c 75 6d 6e 20 69 73 20 73 74 6f 72 65 64 20  olumn is stored 
382b0 69 6e 20 0a 2a 2a 20 61 43 6f 6e 73 74 72 61 69  in .** aConstrai
382c0 6e 74 5b 5d 2e 69 43 6f 6c 75 6d 6e 2e 20 20 61  nt[].iColumn.  a
382d0 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 75 73 61  Constraint[].usa
382e0 62 6c 65 20 69 73 20 54 52 55 45 20 69 66 20 74  ble is TRUE if t
382f0 68 65 0a 2a 2a 20 65 78 70 72 20 6f 6e 20 74 68  he.** expr on th
38300 65 20 72 69 67 68 74 2d 68 61 6e 64 20 73 69 64  e right-hand sid
38310 65 20 63 61 6e 20 62 65 20 65 76 61 6c 75 61 74  e can be evaluat
38320 65 64 20 28 61 6e 64 20 74 68 75 73 20 74 68 65  ed (and thus the
38330 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 69   constraint.** i
38340 73 20 75 73 61 62 6c 65 29 20 61 6e 64 20 66 61  s usable) and fa
38350 6c 73 65 20 69 66 20 69 74 20 63 61 6e 6e 6f 74  lse if it cannot
38360 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 70 74 69  ..**.** The opti
38370 6d 69 7a 65 72 20 61 75 74 6f 6d 61 74 69 63 61  mizer automatica
38380 6c 6c 79 20 69 6e 76 65 72 74 73 20 74 65 72 6d  lly inverts term
38390 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 65  s of the form "e
383a0 78 70 72 20 4f 50 20 63 6f 6c 75 6d 6e 22 0a 2a  xpr OP column".*
383b0 2a 20 61 6e 64 20 6d 61 6b 65 73 20 6f 74 68 65  * and makes othe
383c0 72 20 73 69 6d 70 6c 69 66 69 63 61 74 69 6f 6e  r simplification
383d0 73 20 74 6f 20 74 68 65 20 57 48 45 52 45 20 63  s to the WHERE c
383e0 6c 61 75 73 65 20 69 6e 20 61 6e 20 61 74 74 65  lause in an atte
383f0 6d 70 74 20 74 6f 0a 2a 2a 20 67 65 74 20 61 73  mpt to.** get as
38400 20 6d 61 6e 79 20 57 48 45 52 45 20 63 6c 61 75   many WHERE clau
38410 73 65 20 74 65 72 6d 73 20 69 6e 74 6f 20 74 68  se terms into th
38420 65 20 66 6f 72 6d 20 73 68 6f 77 6e 20 61 62 6f  e form shown abo
38430 76 65 20 61 73 20 70 6f 73 73 69 62 6c 65 2e 0a  ve as possible..
38440 2a 2a 20 54 68 65 20 61 43 6f 6e 73 74 72 61 69  ** The aConstrai
38450 6e 74 5b 5d 20 61 72 72 61 79 20 6f 6e 6c 79 20  nt[] array only 
38460 72 65 70 6f 72 74 73 20 57 48 45 52 45 20 63 6c  reports WHERE cl
38470 61 75 73 65 20 74 65 72 6d 73 20 69 6e 20 74 68  ause terms in th
38480 65 20 63 6f 72 72 65 63 74 0a 2a 2a 20 66 6f 72  e correct.** for
38490 6d 20 74 68 61 74 20 72 65 66 65 72 20 74 6f 20  m that refer to 
384a0 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 76  the particular v
384b0 69 72 74 75 61 6c 20 74 61 62 6c 65 20 62 65 69  irtual table bei
384c0 6e 67 20 71 75 65 72 69 65 64 2e 0a 2a 2a 0a 2a  ng queried..**.*
384d0 2a 20 49 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62  * Information ab
384e0 6f 75 74 20 74 68 65 20 4f 52 44 45 52 20 42 59  out the ORDER BY
384f0 20 63 6c 61 75 73 65 20 69 73 20 73 74 6f 72 65   clause is store
38500 64 20 69 6e 20 61 4f 72 64 65 72 42 79 5b 5d 2e  d in aOrderBy[].
38510 0a 2a 2a 20 45 61 63 68 20 74 65 72 6d 20 6f 66  .** Each term of
38520 20 61 4f 72 64 65 72 42 79 20 72 65 63 6f 72 64   aOrderBy record
38530 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  s a column of th
38540 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73  e ORDER BY claus
38550 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 42 65  e..**.** The xBe
38560 73 74 49 6e 64 65 78 20 6d 65 74 68 6f 64 20 6d  stIndex method m
38570 75 73 74 20 66 69 6c 6c 20 61 43 6f 6e 73 74 72  ust fill aConstr
38580 61 69 6e 74 55 73 61 67 65 5b 5d 20 77 69 74 68  aintUsage[] with
38590 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20   information.** 
385a0 61 62 6f 75 74 20 77 68 61 74 20 70 61 72 61 6d  about what param
385b0 65 74 65 72 73 20 74 6f 20 70 61 73 73 20 74 6f  eters to pass to
385c0 20 78 46 69 6c 74 65 72 2e 20 20 49 66 20 61 72   xFilter.  If ar
385d0 67 76 49 6e 64 65 78 3e 30 20 74 68 65 6e 0a 2a  gvIndex>0 then.*
385e0 2a 20 74 68 65 20 72 69 67 68 74 2d 68 61 6e 64  * the right-hand
385f0 20 73 69 64 65 20 6f 66 20 74 68 65 20 63 6f 72   side of the cor
38600 72 65 73 70 6f 6e 64 69 6e 67 20 61 43 6f 6e 73  responding aCons
38610 74 72 61 69 6e 74 5b 5d 20 69 73 20 65 76 61 6c  traint[] is eval
38620 75 61 74 65 64 0a 2a 2a 20 61 6e 64 20 62 65 63  uated.** and bec
38630 6f 6d 65 73 20 74 68 65 20 61 72 67 76 49 6e 64  omes the argvInd
38640 65 78 2d 74 68 20 65 6e 74 72 79 20 69 6e 20 61  ex-th entry in a
38650 72 67 76 2e 20 20 49 66 20 61 43 6f 6e 73 74 72  rgv.  If aConstr
38660 61 69 6e 74 55 73 61 67 65 5b 5d 2e 6f 6d 69 74  aintUsage[].omit
38670 0a 2a 2a 20 69 73 20 74 72 75 65 2c 20 74 68 65  .** is true, the
38680 6e 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74  n the constraint
38690 20 69 73 20 61 73 73 75 6d 65 64 20 74 6f 20 62   is assumed to b
386a0 65 20 66 75 6c 6c 79 20 68 61 6e 64 6c 65 64 20  e fully handled 
386b0 62 79 20 74 68 65 0a 2a 2a 20 76 69 72 74 75 61  by the.** virtua
386c0 6c 20 74 61 62 6c 65 20 61 6e 64 20 69 73 20 6e  l table and is n
386d0 6f 74 20 63 68 65 63 6b 65 64 20 61 67 61 69 6e  ot checked again
386e0 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a   by SQLite..**.*
386f0 2a 20 54 68 65 20 69 64 78 4e 75 6d 20 61 6e 64  * The idxNum and
38700 20 69 64 78 50 74 72 20 76 61 6c 75 65 73 20 61   idxPtr values a
38710 72 65 20 72 65 63 6f 72 64 65 64 20 61 6e 64 20  re recorded and 
38720 70 61 73 73 65 64 20 69 6e 74 6f 20 78 46 69 6c  passed into xFil
38730 74 65 72 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ter..** sqlite3_
38740 66 72 65 65 28 29 20 69 73 20 75 73 65 64 20 74  free() is used t
38750 6f 20 66 72 65 65 20 69 64 78 50 74 72 20 69 66  o free idxPtr if
38760 20 6e 65 65 64 54 6f 46 72 65 65 49 64 78 50 74   needToFreeIdxPt
38770 72 20 69 73 20 74 72 75 65 2e 0a 2a 2a 0a 2a 2a  r is true..**.**
38780 20 54 68 65 20 6f 72 64 65 72 42 79 43 6f 6e 73   The orderByCons
38790 75 6d 65 64 20 6d 65 61 6e 73 20 74 68 61 74 20  umed means that 
387a0 6f 75 74 70 75 74 20 66 72 6f 6d 20 78 46 69 6c  output from xFil
387b0 74 65 72 20 77 69 6c 6c 20 6f 63 63 75 72 20 69  ter will occur i
387c0 6e 0a 2a 2a 20 74 68 65 20 63 6f 72 72 65 63 74  n.** the correct
387d0 20 6f 72 64 65 72 20 74 6f 20 73 61 74 69 73 66   order to satisf
387e0 79 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 63  y the ORDER BY c
387f0 6c 61 75 73 65 20 73 6f 20 74 68 61 74 20 6e 6f  lause so that no
38800 20 73 65 70 61 72 61 74 65 0a 2a 2a 20 73 6f 72   separate.** sor
38810 74 69 6e 67 20 73 74 65 70 20 69 73 20 72 65 71  ting step is req
38820 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  uired..**.** The
38830 20 65 73 74 69 6d 61 74 65 64 43 6f 73 74 20 76   estimatedCost v
38840 61 6c 75 65 20 69 73 20 61 6e 20 65 73 74 69 6d  alue is an estim
38850 61 74 65 20 6f 66 20 74 68 65 20 63 6f 73 74 20  ate of the cost 
38860 6f 66 20 64 6f 69 6e 67 20 74 68 65 0a 2a 2a 20  of doing the.** 
38870 70 61 72 74 69 63 75 6c 61 72 20 6c 6f 6f 6b 75  particular looku
38880 70 2e 20 20 41 20 66 75 6c 6c 20 73 63 61 6e 20  p.  A full scan 
38890 6f 66 20 61 20 74 61 62 6c 65 20 77 69 74 68 20  of a table with 
388a0 4e 20 65 6e 74 72 69 65 73 20 73 68 6f 75 6c 64  N entries should
388b0 20 68 61 76 65 0a 2a 2a 20 61 20 63 6f 73 74 20   have.** a cost 
388c0 6f 66 20 4e 2e 20 20 41 20 62 69 6e 61 72 79 20  of N.  A binary 
388d0 73 65 61 72 63 68 20 6f 66 20 61 20 74 61 62 6c  search of a tabl
388e0 65 20 6f 66 20 4e 20 65 6e 74 72 69 65 73 20 73  e of N entries s
388f0 68 6f 75 6c 64 20 68 61 76 65 20 61 0a 2a 2a 20  hould have a.** 
38900 63 6f 73 74 20 6f 66 20 61 70 70 72 6f 78 69 6d  cost of approxim
38910 61 74 65 6c 79 20 6c 6f 67 28 4e 29 2e 0a 2a 2f  ately log(N)..*/
38920 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
38930 69 6e 64 65 78 5f 69 6e 66 6f 20 7b 0a 20 20 2f  index_info {.  /
38940 2a 20 49 6e 70 75 74 73 20 2a 2f 0a 20 20 69 6e  * Inputs */.  in
38950 74 20 6e 43 6f 6e 73 74 72 61 69 6e 74 3b 20 20  t nConstraint;  
38960 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62           /* Numb
38970 65 72 20 6f 66 20 65 6e 74 72 69 65 73 20 69 6e  er of entries in
38980 20 61 43 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a   aConstraint */.
38990 20 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33    struct sqlite3
389a0 5f 69 6e 64 65 78 5f 63 6