/ Hex Artifact Content
Login

Artifact 34368f76fb43122dffb97188c2a5166aa11ad8e5:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 20 0a 2a 2a 20 74 6f  e changes .** to
0390: 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e   experimental in
03a0: 74 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73  terfaces but res
03b0: 65 72 76 65 20 74 6f 20 6d 61 6b 65 20 6d 69 6e  erve to make min
03c0: 6f 72 20 63 68 61 6e 67 65 73 20 69 66 0a 2a 2a  or changes if.**
03d0: 20 65 78 70 65 72 69 65 6e 63 65 20 66 72 6f 6d   experience from
03e0: 20 75 73 65 20 22 69 6e 20 74 68 65 20 77 69 6c   use "in the wil
03f0: 64 22 20 73 75 67 67 65 73 74 20 73 75 63 68 20  d" suggest such 
0400: 63 68 61 6e 67 65 73 20 61 72 65 20 70 72 75 64  changes are prud
0410: 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f  ent..**.** The o
0420: 66 66 69 63 69 61 6c 20 43 2d 6c 61 6e 67 75 61  fficial C-langua
0430: 67 65 20 41 50 49 20 64 6f 63 75 6d 65 6e 74 61  ge API documenta
0440: 74 69 6f 6e 20 66 6f 72 20 53 51 4c 69 74 65 20  tion for SQLite 
0450: 69 73 20 64 65 72 69 76 65 64 0a 2a 2a 20 66 72  is derived.** fr
0460: 6f 6d 20 63 6f 6d 6d 65 6e 74 73 20 69 6e 20 74  om comments in t
0470: 68 69 73 20 66 69 6c 65 2e 20 20 54 68 69 73 20  his file.  This 
0480: 66 69 6c 65 20 69 73 20 74 68 65 20 61 75 74 68  file is the auth
0490: 6f 72 69 74 61 74 69 76 65 20 73 6f 75 72 63 65  oritative source
04a0: 0a 2a 2a 20 6f 6e 20 68 6f 77 20 53 51 4c 69 74  .** on how SQLit
04b0: 65 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  e interfaces are
04c0: 20 73 75 70 70 6f 73 65 20 74 6f 20 6f 70 65 72   suppose to oper
04d0: 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e  ate..**.** The n
04e0: 61 6d 65 20 6f 66 20 74 68 69 73 20 66 69 6c 65  ame of this file
04f0: 20 75 6e 64 65 72 20 63 6f 6e 66 69 67 75 72 61   under configura
0500: 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 20  tion management 
0510: 69 73 20 22 73 71 6c 69 74 65 2e 68 2e 69 6e 22  is "sqlite.h.in"
0520: 2e 0a 2a 2a 20 54 68 65 20 6d 61 6b 65 66 69 6c  ..** The makefil
0530: 65 20 6d 61 6b 65 73 20 73 6f 6d 65 20 6d 69 6e  e makes some min
0540: 6f 72 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  or changes to th
0550: 69 73 20 66 69 6c 65 20 28 73 75 63 68 20 61 73  is file (such as
0560: 20 69 6e 73 65 72 74 69 6e 67 0a 2a 2a 20 74 68   inserting.** th
0570: 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72  e version number
0580: 29 20 61 6e 64 20 63 68 61 6e 67 65 73 20 69 74  ) and changes it
0590: 73 20 6e 61 6d 65 20 74 6f 20 22 73 71 6c 69 74  s name to "sqlit
05a0: 65 33 2e 68 22 20 61 73 0a 2a 2a 20 70 61 72 74  e3.h" as.** part
05b0: 20 6f 66 20 74 68 65 20 62 75 69 6c 64 20 70 72   of the build pr
05c0: 6f 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 40 28 23  ocess..**.** @(#
05d0: 29 20 24 49 64 3a 20 73 71 6c 69 74 65 2e 68 2e  ) $Id: sqlite.h.
05e0: 69 6e 2c 76 20 31 2e 32 39 32 20 32 30 30 38 2f  in,v 1.292 2008/
05f0: 30 33 2f 31 38 20 31 33 3a 34 37 3a 32 31 20 64  03/18 13:47:21 d
0600: 72 68 20 45 78 70 20 24 0a 2a 2f 0a 23 69 66 6e  rh Exp $.*/.#ifn
0610: 64 65 66 20 5f 53 51 4c 49 54 45 33 5f 48 5f 0a  def _SQLITE3_H_.
0620: 23 64 65 66 69 6e 65 20 5f 53 51 4c 49 54 45 33  #define _SQLITE3
0630: 5f 48 5f 0a 23 69 6e 63 6c 75 64 65 20 3c 73 74  _H_.#include <st
0640: 64 61 72 67 2e 68 3e 20 20 20 20 20 2f 2a 20 4e  darg.h>     /* N
0650: 65 65 64 65 64 20 66 6f 72 20 74 68 65 20 64 65  eeded for the de
0660: 66 69 6e 69 74 69 6f 6e 20 6f 66 20 76 61 5f 6c  finition of va_l
0670: 69 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 4d 61  ist */../*.** Ma
0680: 6b 65 20 73 75 72 65 20 77 65 20 63 61 6e 20 63  ke sure we can c
0690: 61 6c 6c 20 74 68 69 73 20 73 74 75 66 66 20 66  all this stuff f
06a0: 72 6f 6d 20 43 2b 2b 2e 0a 2a 2f 0a 23 69 66 64  rom C++..*/.#ifd
06b0: 65 66 20 5f 5f 63 70 6c 75 73 70 6c 75 73 0a 65  ef __cplusplus.e
06c0: 78 74 65 72 6e 20 22 43 22 20 7b 0a 23 65 6e 64  xtern "C" {.#end
06d0: 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20 41 64 64 20 74  if.../*.** Add t
06e0: 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20 6f 76  he ability to ov
06f0: 65 72 72 69 64 65 20 27 65 78 74 65 72 6e 27 0a  erride 'extern'.
0700: 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54  */.#ifndef SQLIT
0710: 45 5f 45 58 54 45 52 4e 0a 23 20 64 65 66 69 6e  E_EXTERN.# defin
0720: 65 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20  e SQLITE_EXTERN 
0730: 65 78 74 65 72 6e 0a 23 65 6e 64 69 66 0a 0a 2f  extern.#endif../
0740: 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 74  *.** Make sure t
0750: 68 65 73 65 20 73 79 6d 62 6f 6c 73 20 77 68 65  hese symbols whe
0760: 72 65 20 6e 6f 74 20 64 65 66 69 6e 65 64 20 62  re not defined b
0770: 79 20 73 6f 6d 65 20 70 72 65 76 69 6f 75 73 20  y some previous 
0780: 68 65 61 64 65 72 0a 2a 2a 20 66 69 6c 65 2e 0a  header.** file..
0790: 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45  */.#ifdef SQLITE
07a0: 5f 56 45 52 53 49 4f 4e 0a 23 20 75 6e 64 65 66  _VERSION.# undef
07b0: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a   SQLITE_VERSION.
07c0: 23 65 6e 64 69 66 0a 23 69 66 64 65 66 20 53 51  #endif.#ifdef SQ
07d0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
07e0: 42 45 52 0a 23 20 75 6e 64 65 66 20 53 51 4c 49  BER.# undef SQLI
07f0: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45  TE_VERSION_NUMBE
0800: 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20  R.#endif../*.** 
0810: 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c  CAPI3REF: Compil
0820: 65 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20 56  e-Time Library V
0830: 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 20 7b  ersion Numbers {
0840: 46 31 30 30 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 68  F10010}.**.** Th
0850: 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  e SQLITE_VERSION
0860: 20 61 6e 64 20 53 51 4c 49 54 45 5f 56 45 52 53   and SQLITE_VERS
0870: 49 4f 4e 5f 4e 55 4d 42 45 52 20 23 64 65 66 69  ION_NUMBER #defi
0880: 6e 65 73 20 69 6e 0a 2a 2a 20 74 68 65 20 73 71  nes in.** the sq
0890: 6c 69 74 65 33 2e 68 20 66 69 6c 65 20 73 70 65  lite3.h file spe
08a0: 63 69 66 79 20 74 68 65 20 76 65 72 73 69 6f 6e  cify the version
08b0: 20 6f 66 20 53 51 4c 69 74 65 20 77 69 74 68 20   of SQLite with 
08c0: 77 68 69 63 68 0a 2a 2a 20 74 68 61 74 20 68 65  which.** that he
08d0: 61 64 65 72 20 66 69 6c 65 20 69 73 20 61 73 73  ader file is ass
08e0: 6f 63 69 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  ociated..**.** T
08f0: 68 65 20 22 76 65 72 73 69 6f 6e 22 20 6f 66 20  he "version" of 
0900: 53 51 4c 69 74 65 20 69 73 20 61 20 73 74 72 69  SQLite is a stri
0910: 6e 67 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22  ng of the form "
0920: 58 2e 59 2e 5a 22 2e 0a 2a 2a 20 54 68 65 20 70  X.Y.Z"..** The p
0930: 68 72 61 73 65 20 22 61 6c 70 68 61 22 20 6f 72  hrase "alpha" or
0940: 20 22 62 65 74 61 22 20 6d 69 67 68 74 20 62 65   "beta" might be
0950: 20 61 70 70 65 6e 64 65 64 20 61 66 74 65 72 20   appended after 
0960: 74 68 65 20 5a 2e 0a 2a 2a 20 54 68 65 20 58 20  the Z..** The X 
0970: 76 61 6c 75 65 20 69 73 20 6d 61 6a 6f 72 20 76  value is major v
0980: 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 61 6c  ersion number al
0990: 77 61 79 73 20 33 20 69 6e 20 53 51 4c 69 74 65  ways 3 in SQLite
09a0: 33 2e 0a 2a 2a 20 54 68 65 20 58 20 76 61 6c 75  3..** The X valu
09b0: 65 20 6f 6e 6c 79 20 63 68 61 6e 67 65 73 20 77  e only changes w
09c0: 68 65 6e 20 20 62 61 63 6b 77 61 72 64 73 20 63  hen  backwards c
09d0: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 69 73 0a  ompatibility is.
09e0: 2a 2a 20 62 72 6f 6b 65 6e 20 61 6e 64 20 77 65  ** broken and we
09f0: 20 69 6e 74 65 6e 64 20 74 6f 20 6e 65 76 65 72   intend to never
0a00: 20 62 72 65 61 6b 0a 2a 2a 20 62 61 63 6b 77 61   break.** backwa
0a10: 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
0a20: 79 2e 20 20 54 68 65 20 59 20 76 61 6c 75 65 20  y.  The Y value 
0a30: 69 73 20 74 68 65 20 6d 69 6e 6f 72 20 76 65 72  is the minor ver
0a40: 73 69 6f 6e 0a 2a 2a 20 6e 75 6d 62 65 72 20 61  sion.** number a
0a50: 6e 64 20 6f 6e 6c 79 20 63 68 61 6e 67 65 73 20  nd only changes 
0a60: 77 68 65 6e 0a 2a 2a 20 74 68 65 72 65 20 61 72  when.** there ar
0a70: 65 20 6d 61 6a 6f 72 20 66 65 61 74 75 72 65 20  e major feature 
0a80: 65 6e 68 61 6e 63 65 6d 65 6e 74 73 20 74 68 61  enhancements tha
0a90: 74 20 61 72 65 20 66 6f 72 77 61 72 64 73 20 63  t are forwards c
0aa0: 6f 6d 70 61 74 69 62 6c 65 0a 2a 2a 20 62 75 74  ompatible.** but
0ab0: 20 6e 6f 74 20 62 61 63 6b 77 61 72 64 73 20 63   not backwards c
0ac0: 6f 6d 70 61 74 69 62 6c 65 2e 20 20 54 68 65 20  ompatible.  The 
0ad0: 5a 20 76 61 6c 75 65 20 69 73 20 72 65 6c 65 61  Z value is relea
0ae0: 73 65 20 6e 75 6d 62 65 72 0a 2a 2a 20 61 6e 64  se number.** and
0af0: 20 69 73 20 69 6e 63 72 65 6d 65 6e 74 65 64 20   is incremented 
0b00: 77 69 74 68 0a 2a 2a 20 65 61 63 68 20 72 65 6c  with.** each rel
0b10: 65 61 73 65 20 62 75 74 20 72 65 73 65 74 73 20  ease but resets 
0b20: 62 61 63 6b 20 74 6f 20 30 20 77 68 65 6e 20 59  back to 0 when Y
0b30: 20 69 73 20 69 6e 63 72 65 6d 65 6e 74 65 64 2e   is incremented.
0b40: 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
0b50: 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72   [sqlite3_libver
0b60: 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  sion()] and [sql
0b70: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f  ite3_libversion_
0b80: 6e 75 6d 62 65 72 28 29 5d 2e 0a 2a 2a 0a 2a 2a  number()]..**.**
0b90: 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
0ba0: 2a 2a 20 7b 46 31 30 30 31 31 7d 20 54 68 65 20  ** {F10011} The 
0bb0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 23  SQLITE_VERSION #
0bc0: 64 65 66 69 6e 65 20 69 6e 20 74 68 65 20 73 71  define in the sq
0bd0: 6c 69 74 65 33 2e 68 20 68 65 61 64 65 72 20 66  lite3.h header f
0be0: 69 6c 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ile.**          
0bf0: 65 76 61 6c 75 61 74 65 73 20 74 6f 20 61 20 73  evaluates to a s
0c00: 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20 74 68  tring literal th
0c10: 61 74 20 69 73 20 74 68 65 20 53 51 4c 69 74 65  at is the SQLite
0c20: 20 76 65 72 73 69 6f 6e 0a 2a 2a 20 20 20 20 20   version.**     
0c30: 20 20 20 20 20 77 69 74 68 20 77 68 69 63 68 20       with which 
0c40: 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65 20  the header file 
0c50: 69 73 20 61 73 73 6f 63 69 61 74 65 64 2e 0a 2a  is associated..*
0c60: 2a 0a 2a 2a 20 7b 46 31 30 30 31 34 7d 20 54 68  *.** {F10014} Th
0c70: 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  e SQLITE_VERSION
0c80: 5f 4e 55 4d 42 45 52 20 23 64 65 66 69 6e 65 20  _NUMBER #define 
0c90: 72 65 73 6f 6c 76 65 73 20 74 6f 20 61 6e 20 69  resolves to an i
0ca0: 6e 74 65 67 65 72 0a 2a 2a 20 20 20 20 20 20 20  nteger.**       
0cb0: 20 20 20 77 69 74 68 20 74 68 65 20 76 61 6c 75     with the valu
0cc0: 65 20 20 28 58 2a 31 30 30 30 30 30 30 20 2b 20  e  (X*1000000 + 
0cd0: 59 2a 31 30 30 30 20 2b 20 5a 29 20 77 68 65 72  Y*1000 + Z) wher
0ce0: 65 20 58 2c 20 59 2c 20 61 6e 64 0a 2a 2a 20 20  e X, Y, and.**  
0cf0: 20 20 20 20 20 20 20 20 5a 20 61 72 65 20 74 68          Z are th
0d00: 65 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 2c  e major version,
0d10: 20 6d 69 6e 6f 72 20 76 65 72 73 69 6f 6e 2c 20   minor version, 
0d20: 61 6e 64 20 72 65 6c 65 61 73 65 20 6e 75 6d 62  and release numb
0d30: 65 72 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  er..*/.#define S
0d40: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 20 20  QLITE_VERSION   
0d50: 20 20 20 20 20 20 22 2d 2d 56 45 52 53 2d 2d 22        "--VERS--"
0d60: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
0d70: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 20  VERSION_NUMBER  
0d80: 2d 2d 56 45 52 53 49 4f 4e 2d 4e 55 4d 42 45 52  --VERSION-NUMBER
0d90: 2d 2d 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  --../*.** CAPI3R
0da0: 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62  EF: Run-Time Lib
0db0: 72 61 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d  rary Version Num
0dc0: 62 65 72 73 20 7b 46 31 30 30 32 30 7d 0a 2a 2a  bers {F10020}.**
0dd0: 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74   KEYWORDS: sqlit
0de0: 65 33 5f 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a  e3_version.**.**
0df0: 20 54 68 65 73 65 20 66 65 61 74 75 72 65 73 20   These features 
0e00: 70 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65  provide the same
0e10: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20   information as 
0e20: 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  the [SQLITE_VERS
0e30: 49 4f 4e 5d 0a 2a 2a 20 61 6e 64 20 5b 53 51 4c  ION].** and [SQL
0e40: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
0e50: 45 52 5d 20 23 64 65 66 69 6e 65 73 20 69 6e 20  ER] #defines in 
0e60: 74 68 65 20 68 65 61 64 65 72 2c 20 62 75 74 20  the header, but 
0e70: 61 72 65 20 61 73 73 6f 63 69 61 74 65 64 0a 2a  are associated.*
0e80: 2a 20 77 69 74 68 20 74 68 65 20 6c 69 62 72 61  * with the libra
0e90: 72 79 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68  ry instead of th
0ea0: 65 20 68 65 61 64 65 72 20 66 69 6c 65 2e 20 20  e header file.  
0eb0: 43 61 75 74 69 6f 75 73 20 70 72 6f 67 72 61 6d  Cautious program
0ec0: 6d 65 72 73 20 6d 69 67 68 74 0a 2a 2a 20 69 6e  mers might.** in
0ed0: 63 6c 75 64 65 20 61 20 63 68 65 63 6b 20 69 6e  clude a check in
0ee0: 20 74 68 65 69 72 20 61 70 70 6c 69 63 61 74 69   their applicati
0ef0: 6f 6e 20 74 6f 20 76 65 72 69 66 79 20 74 68 61  on to verify tha
0f00: 74 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6c 69  t .** sqlite3_li
0f10: 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28  bversion_number(
0f20: 29 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73  ) always returns
0f30: 20 74 68 65 20 76 61 6c 75 65 20 0a 2a 2a 20 5b   the value .** [
0f40: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
0f50: 55 4d 42 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  UMBER]..**.** Th
0f60: 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72  e sqlite3_libver
0f70: 73 69 6f 6e 28 29 20 66 75 6e 63 74 69 6f 6e 20  sion() function 
0f80: 72 65 74 75 72 6e 73 20 74 68 65 20 73 61 6d 65  returns the same
0f90: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20   information as 
0fa0: 69 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 71 6c  is.** in the sql
0fb0: 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73  ite3_version[] s
0fc0: 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 2e 20  tring constant. 
0fd0: 20 54 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73   The function is
0fe0: 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f 72   provided.** for
0ff0: 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69 6e   use in DLLs sin
1000: 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73 75  ce DLL users usu
1010: 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76 65  ally do not have
1020: 20 64 69 72 65 63 74 20 61 63 63 65 73 73 20 74   direct access t
1030: 6f 20 73 74 72 69 6e 67 0a 2a 2a 20 63 6f 6e 73  o string.** cons
1040: 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68 65  tants within the
1050: 20 44 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41   DLL..**.** INVA
1060: 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  RIANTS:.**.** {F
1070: 31 30 30 32 31 7d 20 54 68 65 20 5b 73 71 6c 69  10021} The [sqli
1080: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e  te3_libversion_n
1090: 75 6d 62 65 72 28 29 5d 20 69 6e 74 65 72 66 61  umber()] interfa
10a0: 63 65 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e  ce returns an in
10b0: 74 65 67 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  teger.**        
10c0: 20 20 65 71 75 61 6c 20 74 6f 20 5b 53 51 4c 49    equal to [SQLI
10d0: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45  TE_VERSION_NUMBE
10e0: 52 5d 2e 20 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 30  R]. .**.** {F100
10f0: 32 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  22} The [sqlite3
1100: 5f 76 65 72 73 69 6f 6e 5d 20 73 74 72 69 6e 67  _version] string
1110: 20 63 6f 6e 73 74 61 6e 74 20 63 6f 6e 74 61 69   constant contai
1120: 6e 73 20 74 68 65 20 74 65 78 74 20 6f 66 20 74  ns the text of t
1130: 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
1140: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20  SQLITE_VERSION] 
1150: 73 74 72 69 6e 67 2e 20 0a 2a 2a 0a 2a 2a 20 7b  string. .**.** {
1160: 46 31 30 30 32 33 7d 20 54 68 65 20 5b 73 71 6c  F10023} The [sql
1170: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
1180: 29 5d 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  )] function retu
1190: 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  rns.**          
11a0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
11b0: 20 5b 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f   [sqlite3_versio
11c0: 6e 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61  n] string consta
11d0: 6e 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58  nt..*/.SQLITE_EX
11e0: 54 45 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20  TERN const char 
11f0: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b  sqlite3_version[
1200: 5d 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  ];.const char *s
1210: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1220: 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c  n(void);.int sql
1230: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f  ite3_libversion_
1240: 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a 0a 2f  number(void);../
1250: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
1260: 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54 68  est To See If Th
1270: 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68 72  e Library Is Thr
1280: 65 61 64 73 61 66 65 20 7b 46 31 30 31 30 30 7d  eadsafe {F10100}
1290: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 61  .**.** SQLite ca
12a0: 6e 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 77 69  n be compiled wi
12b0: 74 68 20 6f 72 20 77 69 74 68 6f 75 74 20 6d 75  th or without mu
12c0: 74 65 78 65 73 2e 20 20 57 68 65 6e 0a 2a 2a 20  texes.  When.** 
12d0: 74 68 65 20 53 51 4c 49 54 45 5f 54 48 52 45 41  the SQLITE_THREA
12e0: 44 53 41 46 45 20 43 20 70 72 65 70 72 6f 63 65  DSAFE C preproce
12f0: 73 73 6f 72 20 6d 61 63 72 6f 20 69 73 20 74 72  ssor macro is tr
1300: 75 65 2c 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61  ue, mutexes.** a
1310: 72 65 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 53  re enabled and S
1320: 51 4c 69 74 65 20 69 73 20 74 68 72 65 61 64 73  QLite is threads
1330: 61 66 65 2e 20 20 57 68 65 6e 20 74 68 61 74 20  afe.  When that 
1340: 6d 61 63 72 6f 20 69 73 20 66 61 6c 73 65 2c 0a  macro is false,.
1350: 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73 20 61  ** the mutexes a
1360: 72 65 20 6f 6d 69 74 74 65 64 2e 20 20 57 69 74  re omitted.  Wit
1370: 68 6f 75 74 20 74 68 65 20 6d 75 74 65 78 65 73  hout the mutexes
1380: 2c 20 69 74 20 69 73 20 6e 6f 74 20 73 61 66 65  , it is not safe
1390: 0a 2a 2a 20 74 6f 20 75 73 65 20 53 51 4c 69 74  .** to use SQLit
13a0: 65 20 66 72 6f 6d 20 6d 6f 72 65 20 74 68 61 6e  e from more than
13b0: 20 6f 6e 65 20 74 68 72 65 61 64 2e 0a 2a 2a 0a   one thread..**.
13c0: 2a 2a 20 54 68 65 72 65 20 69 73 20 61 20 6d 65  ** There is a me
13d0: 61 73 75 72 61 62 6c 65 20 70 65 72 66 6f 72 6d  asurable perform
13e0: 61 6e 63 65 20 70 65 6e 61 6c 74 79 20 66 6f 72  ance penalty for
13f0: 20 65 6e 61 62 6c 69 6e 67 20 6d 75 74 65 78 65   enabling mutexe
1400: 73 2e 0a 2a 2a 20 53 6f 20 69 66 20 73 70 65 65  s..** So if spee
1410: 64 20 69 73 20 6f 66 20 75 74 6d 6f 73 74 20 69  d is of utmost i
1420: 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74 20 6d 61  mportance, it ma
1430: 6b 65 73 20 73 65 6e 73 65 20 74 6f 20 64 69 73  kes sense to dis
1440: 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65  able.** the mute
1450: 78 65 73 2e 20 20 42 75 74 20 66 6f 72 20 6d 61  xes.  But for ma
1460: 78 69 6d 75 6d 20 73 61 66 65 74 79 2c 20 6d 75  ximum safety, mu
1470: 74 65 78 65 73 20 73 68 6f 75 6c 64 20 62 65 20  texes should be 
1480: 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 54 68 65 20  enabled..** The 
1490: 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72  default behavior
14a0: 20 69 73 20 66 6f 72 20 6d 75 74 65 78 65 73 20   is for mutexes 
14b0: 74 6f 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a  to be enabled..*
14c0: 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66  *.** This interf
14d0: 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ace can be used 
14e0: 62 79 20 61 20 70 72 6f 67 72 61 6d 20 74 6f 20  by a program to 
14f0: 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 20 74  make sure that t
1500: 68 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66  he.** version of
1510: 20 53 51 4c 69 74 65 20 74 68 61 74 20 69 74 20   SQLite that it 
1520: 69 73 20 6c 69 6e 6b 69 6e 67 20 61 67 61 69 6e  is linking again
1530: 73 74 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20  st was compiled 
1540: 77 69 74 68 0a 2a 2a 20 74 68 65 20 64 65 73 69  with.** the desi
1550: 72 65 64 20 73 65 74 74 69 6e 67 20 6f 66 20 74  red setting of t
1560: 68 65 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44  he SQLITE_THREAD
1570: 53 41 46 45 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a  SAFE macro..**.*
1580: 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
1590: 0a 2a 2a 20 7b 46 31 30 31 30 31 7d 20 54 68 65  .** {F10101} The
15a0: 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64   [sqlite3_thread
15b0: 73 61 66 65 28 29 5d 20 66 75 6e 63 74 69 6f 6e  safe()] function
15c0: 20 72 65 74 75 72 6e 73 20 6e 6f 6e 7a 65 72 6f   returns nonzero
15d0: 20 69 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   if.**          
15e0: 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70 69  SQLite was compi
15f0: 6c 65 64 20 77 69 74 68 20 69 74 73 20 6d 75 74  led with its mut
1600: 65 78 65 73 20 65 6e 61 62 6c 65 64 20 6f 72 20  exes enabled or 
1610: 7a 65 72 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20  zero.**         
1620: 20 69 66 20 53 51 4c 69 74 65 20 77 61 73 20 63   if SQLite was c
1630: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6d 75 74  ompiled with mut
1640: 65 78 65 73 20 64 69 73 61 62 6c 65 64 2e 0a 2a  exes disabled..*
1650: 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 68  /.int sqlite3_th
1660: 72 65 61 64 73 61 66 65 28 76 6f 69 64 29 3b 0a  readsafe(void);.
1670: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1680: 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
1690: 74 69 6f 6e 20 48 61 6e 64 6c 65 20 7b 46 31 32  tion Handle {F12
16a0: 30 30 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  000}.** KEYWORDS
16b0: 3a 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  : {database conn
16c0: 65 63 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 45 61  ection}.**.** Ea
16d0: 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20 64  ch open SQLite d
16e0: 61 74 61 62 61 73 65 20 69 73 20 72 65 70 72 65  atabase is repre
16f0: 73 65 6e 74 65 64 20 62 79 20 70 6f 69 6e 74 65  sented by pointe
1700: 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65  r to an instance
1710: 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 70 61 71 75   of the.** opaqu
1720: 65 20 73 74 72 75 63 74 75 72 65 20 6e 61 6d 65  e structure name
1730: 64 20 22 73 71 6c 69 74 65 33 22 2e 20 20 49 74  d "sqlite3".  It
1740: 20 69 73 20 75 73 65 66 75 6c 20 74 6f 20 74 68   is useful to th
1750: 69 6e 6b 20 6f 66 20 61 6e 20 73 71 6c 69 74 65  ink of an sqlite
1760: 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 61 73 20  3.** pointer as 
1770: 61 6e 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20  an object.  The 
1780: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
1790: 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  , [sqlite3_open1
17a0: 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  6()], and.** [sq
17b0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
17c0: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
17d0: 69 74 73 20 63 6f 6e 73 74 72 75 63 74 6f 72 73  its constructors
17e0: 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
17f0: 5f 63 6c 6f 73 65 28 29 5d 20 69 73 20 69 74 73  _close()] is its
1800: 20 64 65 73 74 72 75 63 74 6f 72 2e 20 20 54 68   destructor.  Th
1810: 65 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68  ere are many oth
1820: 65 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  er interfaces.**
1830: 20 28 73 75 63 68 20 61 73 20 5b 73 71 6c 69 74   (such as [sqlit
1840: 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1850: 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  , [sqlite3_creat
1860: 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61  e_function()], a
1870: 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nd.** [sqlite3_b
1880: 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74  usy_timeout()] t
1890: 6f 20 6e 61 6d 65 20 62 75 74 20 74 68 72 65 65  o name but three
18a0: 29 20 74 68 61 74 20 61 72 65 20 6d 65 74 68 6f  ) that are metho
18b0: 64 73 20 6f 6e 20 74 68 69 73 0a 2a 2a 20 6f 62  ds on this.** ob
18c0: 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  ject..*/.typedef
18d0: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 20   struct sqlite3 
18e0: 73 71 6c 69 74 65 33 3b 0a 0a 0a 2f 2a 0a 2a 2a  sqlite3;.../*.**
18f0: 20 43 41 50 49 33 52 45 46 3a 20 36 34 2d 42 69   CAPI3REF: 64-Bi
1900: 74 20 49 6e 74 65 67 65 72 20 54 79 70 65 73 20  t Integer Types 
1910: 7b 46 31 30 32 30 30 7d 0a 2a 2a 20 4b 45 59 57  {F10200}.** KEYW
1920: 4f 52 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74  ORDS: sqlite_int
1930: 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  64 sqlite_uint64
1940: 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74  .**.** Because t
1950: 68 65 72 65 20 69 73 20 6e 6f 20 63 72 6f 73 73  here is no cross
1960: 2d 70 6c 61 74 66 6f 72 6d 20 77 61 79 20 74 6f  -platform way to
1970: 20 73 70 65 63 69 66 79 20 36 34 2d 62 69 74 20   specify 64-bit 
1980: 69 6e 74 65 67 65 72 20 74 79 70 65 73 0a 2a 2a  integer types.**
1990: 20 53 51 4c 69 74 65 20 69 6e 63 6c 75 64 65 73   SQLite includes
19a0: 20 74 79 70 65 64 65 66 73 20 66 6f 72 20 36 34   typedefs for 64
19b0: 2d 62 69 74 20 73 69 67 6e 65 64 20 61 6e 64 20  -bit signed and 
19c0: 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  unsigned integer
19d0: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  s..**.** The sql
19e0: 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73  ite3_int64 and s
19f0: 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 61 72  qlite3_uint64 ar
1a00: 65 20 74 68 65 20 70 72 65 66 65 72 72 65 64 20  e the preferred 
1a10: 74 79 70 65 0a 2a 2a 20 64 65 66 69 6e 69 74 69  type.** definiti
1a20: 6f 6e 73 2e 20 20 54 68 65 20 73 71 6c 69 74 65  ons.  The sqlite
1a30: 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74  _int64 and sqlit
1a40: 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20 61  e_uint64 types a
1a50: 72 65 0a 2a 2a 20 73 75 70 70 6f 72 74 65 64 20  re.** supported 
1a60: 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f  for backwards co
1a70: 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79  mpatibility only
1a80: 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
1a90: 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 32 30  TS:.**.** {F1020
1aa0: 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 5f 69  1} The [sqlite_i
1ab0: 6e 74 36 34 5d 20 61 6e 64 20 5b 73 71 6c 69 74  nt64] and [sqlit
1ac0: 65 33 5f 69 6e 74 36 34 5d 20 74 79 70 65 73 20  e3_int64] types 
1ad0: 73 70 65 63 69 66 79 20 61 0a 2a 2a 20 20 20 20  specify a.**    
1ae0: 20 20 20 20 20 20 36 34 2d 62 69 74 20 73 69 67        64-bit sig
1af0: 6e 65 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a  ned integer..**.
1b00: 2a 2a 20 7b 46 31 30 32 30 32 7d 20 54 68 65 20  ** {F10202} The 
1b10: 5b 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 5d 20  [sqlite_uint64] 
1b20: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 75 69 6e  and [sqlite3_uin
1b30: 74 36 34 5d 20 74 79 70 65 73 20 73 70 65 63 69  t64] types speci
1b40: 66 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  fy.**          a
1b50: 20 36 34 2d 62 69 74 20 75 6e 73 69 67 6e 65 64   64-bit unsigned
1b60: 20 69 6e 74 65 67 65 72 2e 0a 2a 2f 0a 23 69 66   integer..*/.#if
1b70: 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34  def SQLITE_INT64
1b80: 5f 54 59 50 45 0a 20 20 74 79 70 65 64 65 66 20  _TYPE.  typedef 
1b90: 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50  SQLITE_INT64_TYP
1ba0: 45 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a  E sqlite_int64;.
1bb0: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e    typedef unsign
1bc0: 65 64 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f  ed SQLITE_INT64_
1bd0: 54 59 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74  TYPE sqlite_uint
1be0: 36 34 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e 65  64;.#elif define
1bf0: 64 28 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64  d(_MSC_VER) || d
1c00: 65 66 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44  efined(__BORLAND
1c10: 43 5f 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f  C__).  typedef _
1c20: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e  _int64 sqlite_in
1c30: 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75  t64;.  typedef u
1c40: 6e 73 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20  nsigned __int64 
1c50: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23  sqlite_uint64;.#
1c60: 65 6c 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c  else.  typedef l
1c70: 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c  ong long int sql
1c80: 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70  ite_int64;.  typ
1c90: 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f  edef unsigned lo
1ca0: 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69  ng long int sqli
1cb0: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69  te_uint64;.#endi
1cc0: 66 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65  f.typedef sqlite
1cd0: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69  _int64 sqlite3_i
1ce0: 6e 74 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71  nt64;.typedef sq
1cf0: 6c 69 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69  lite_uint64 sqli
1d00: 74 65 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a  te3_uint64;../*.
1d10: 2a 2a 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20  ** If compiling 
1d20: 66 6f 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20  for a processor 
1d30: 74 68 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74  that lacks float
1d40: 69 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72  ing point suppor
1d50: 74 2c 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65  t,.** substitute
1d60: 20 69 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f   integer for flo
1d70: 61 74 69 6e 67 2d 70 6f 69 6e 74 0a 2a 2f 0a 23  ating-point.*/.#
1d80: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49  ifdef SQLITE_OMI
1d90: 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54  T_FLOATING_POINT
1da0: 0a 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65  .# define double
1db0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23   sqlite3_int64.#
1dc0: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  endif../*.** CAP
1dd0: 49 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41  I3REF: Closing A
1de0: 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
1df0: 74 69 6f 6e 20 7b 46 31 32 30 31 30 7d 0a 2a 2a  tion {F12010}.**
1e00: 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
1e10: 20 69 73 20 74 68 65 20 64 65 73 74 72 75 63 74   is the destruct
1e20: 6f 72 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69  or for the [sqli
1e30: 74 65 33 5d 20 6f 62 6a 65 63 74 2e 20 20 0a 2a  te3] object.  .*
1e40: 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e  *.** Application
1e50: 73 20 73 68 6f 75 6c 64 20 5b 73 71 6c 69 74 65  s should [sqlite
1e60: 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e  3_finalize | fin
1e70: 61 6c 69 7a 65 5d 20 61 6c 6c 0a 2a 2a 20 5b 70  alize] all.** [p
1e80: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1e90: 74 73 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  ts] and.** [sqli
1ea0: 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c  te3_blob_close |
1eb0: 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 73 71 6c   close] all [sql
1ec0: 69 74 65 33 5f 62 6c 6f 62 20 7c 20 42 4c 4f 42  ite3_blob | BLOB
1ed0: 73 5d 20 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65  s] .** associate
1ee0: 64 20 77 69 74 68 20 74 68 65 20 5b 73 71 6c 69  d with the [sqli
1ef0: 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 72 69 6f  te3] object prio
1f00: 72 0a 2a 2a 20 74 6f 20 61 74 74 65 6d 70 74 69  r.** to attempti
1f10: 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65 20  ng to close the 
1f20: 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
1f30: 2e 0a 2a 2a 0a 2a 2a 20 3c 74 6f 64 6f 3e 57 68  ..**.** <todo>Wh
1f40: 61 74 20 68 61 70 70 65 6e 73 20 74 6f 20 70 65  at happens to pe
1f50: 6e 64 69 6e 67 20 74 72 61 6e 73 61 63 74 69 6f  nding transactio
1f60: 6e 73 3f 20 20 41 72 65 20 74 68 65 79 0a 2a 2a  ns?  Are they.**
1f70: 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2c 20 6f 72   rolled back, or
1f80: 20 61 62 61 6e 64 6f 6e 65 64 3f 3c 2f 74 6f 64   abandoned?</tod
1f90: 6f 3e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  o>.**.** INVARIA
1fa0: 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 30  NTS:.**.** {F120
1fb0: 31 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  11} The [sqlite3
1fc0: 5f 63 6c 6f 73 65 28 29 5d 20 69 6e 74 65 72 66  _close()] interf
1fd0: 61 63 65 20 64 65 73 74 72 6f 79 73 20 61 6e 20  ace destroys an 
1fe0: 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
1ff0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c 6c  .**          all
2000: 6f 63 61 74 65 64 20 62 79 20 61 20 70 72 69 6f  ocated by a prio
2010: 72 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  r call to [sqlit
2020: 65 33 5f 6f 70 65 6e 28 29 5d 2c 0a 2a 2a 20 20  e3_open()],.**  
2030: 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
2040: 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72 20 5b  _open16()], or [
2050: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
2060: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 30 31  )]..**.** {F1201
2070: 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  2} The [sqlite3_
2080: 63 6c 6f 73 65 28 29 5d 20 66 75 6e 63 74 69 6f  close()] functio
2090: 6e 20 72 65 6c 65 61 73 65 73 20 61 6c 6c 20 6d  n releases all m
20a0: 65 6d 6f 72 79 20 75 73 65 64 20 62 79 20 74 68  emory used by th
20b0: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f  e.**          co
20c0: 6e 6e 65 63 74 69 6f 6e 20 61 6e 64 20 63 6c 6f  nnection and clo
20d0: 73 65 73 20 61 6c 6c 20 6f 70 65 6e 20 66 69 6c  ses all open fil
20e0: 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 30 31  es..**.** {F1201
20f0: 33 7d 20 49 66 20 74 68 65 20 64 61 74 61 62 61  3} If the databa
2100: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6f  se connection co
2110: 6e 74 61 69 6e 73 0a 2a 2a 20 20 20 20 20 20 20  ntains.**       
2120: 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61     [prepared sta
2130: 74 65 6d 65 6e 74 73 5d 20 74 68 61 74 20 68 61  tements] that ha
2140: 76 65 20 6e 6f 74 20 62 65 65 6e 0a 2a 2a 20 20  ve not been.**  
2150: 20 20 20 20 20 20 20 20 66 69 6e 61 6c 69 7a 65          finalize
2160: 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 69  d by [sqlite3_fi
2170: 6e 61 6c 69 7a 65 28 29 5d 2c 20 74 68 65 6e 20  nalize()], then 
2180: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29  [sqlite3_close()
2190: 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  ].**          re
21a0: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55  turns [SQLITE_BU
21b0: 53 59 5d 20 61 6e 64 20 6c 65 61 76 65 73 20 74  SY] and leaves t
21c0: 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70  he connection op
21d0: 65 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 30 31  en..**.** {F1201
21e0: 34 7d 20 47 69 76 69 6e 67 20 73 71 6c 69 74 65  4} Giving sqlite
21f0: 33 5f 63 6c 6f 73 65 28 29 20 61 20 4e 55 4c 4c  3_close() a NULL
2200: 20 70 6f 69 6e 74 65 72 20 69 73 20 61 20 68 61   pointer is a ha
2210: 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a  rmless no-op..**
2220: 0a 2a 2a 20 4c 49 4d 49 54 41 54 49 4f 4e 53 3a  .** LIMITATIONS:
2230: 0a 2a 2a 0a 2a 2a 20 7b 55 31 32 30 31 35 7d 20  .**.** {U12015} 
2240: 54 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  The parameter to
2250: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
2260: 29 5d 20 6d 75 73 74 20 62 65 20 61 6e 20 5b 73  )] must be an [s
2270: 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 0a 2a  qlite3] object.*
2280: 2a 20 20 20 20 20 20 20 20 20 20 70 6f 69 6e 74  *          point
2290: 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62  er previously ob
22a0: 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
22b0: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 6f 72 20  ite3_open()] or 
22c0: 74 68 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  the .**         
22d0: 20 65 71 75 69 76 61 6c 65 6e 74 2c 20 6f 72 20   equivalent, or 
22e0: 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 55 31 32  NULL..**.** {U12
22f0: 30 31 36 7d 20 54 68 65 20 70 61 72 61 6d 65 74  016} The paramet
2300: 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  er to [sqlite3_c
2310: 6c 6f 73 65 28 29 5d 20 6d 75 73 74 20 6e 6f 74  lose()] must not
2320: 20 68 61 76 65 20 62 65 65 6e 20 70 72 65 76 69   have been previ
2330: 6f 75 73 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20  ously.**        
2340: 20 20 63 6c 6f 73 65 64 2e 0a 2a 2f 0a 69 6e 74    closed..*/.int
2350: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 73   sqlite3_close(s
2360: 71 6c 69 74 65 33 20 2a 29 3b 0a 0a 2f 2a 0a 2a  qlite3 *);../*.*
2370: 2a 20 54 68 65 20 74 79 70 65 20 66 6f 72 20 61  * The type for a
2380: 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
2390: 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 6c  on..** This is l
23a0: 65 67 61 63 79 20 61 6e 64 20 64 65 70 72 65 63  egacy and deprec
23b0: 61 74 65 64 2e 20 20 49 74 20 69 73 20 69 6e 63  ated.  It is inc
23c0: 6c 75 64 65 64 20 66 6f 72 20 68 69 73 74 6f 72  luded for histor
23d0: 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69 62  ical.** compatib
23e0: 69 6c 69 74 79 20 61 6e 64 20 69 73 20 6e 6f 74  ility and is not
23f0: 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a 2f 0a   documented..*/.
2400: 74 79 70 65 64 65 66 20 69 6e 74 20 28 2a 73 71  typedef int (*sq
2410: 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63 6b 29 28  lite3_callback)(
2420: 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a  void*,int,char**
2430: 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a 2a  , char**);../*.*
2440: 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 6e 65 2d  * CAPI3REF: One-
2450: 53 74 65 70 20 51 75 65 72 79 20 45 78 65 63 75  Step Query Execu
2460: 74 69 6f 6e 20 49 6e 74 65 72 66 61 63 65 20 7b  tion Interface {
2470: 46 31 32 31 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68  F12100}.**.** Th
2480: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
2490: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 61 20   interface is a 
24a0: 63 6f 6e 76 65 6e 69 65 6e 74 20 77 61 79 20 6f  convenient way o
24b0: 66 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 6f 6e 65  f running.** one
24c0: 20 6f 72 20 6d 6f 72 65 20 53 51 4c 20 73 74 61   or more SQL sta
24d0: 74 65 6d 65 6e 74 73 20 77 69 74 68 6f 75 74 20  tements without 
24e0: 61 20 6c 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e  a lot of C code.
24f0: 20 20 54 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61    The.** SQL sta
2500: 74 65 6d 65 6e 74 73 20 61 72 65 20 70 61 73 73  tements are pass
2510: 65 64 20 69 6e 20 61 73 20 74 68 65 20 73 65 63  ed in as the sec
2520: 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
2530: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
2540: 28 29 2e 20 20 54 68 65 20 73 74 61 74 65 6d 65  ().  The stateme
2550: 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65  nts are evaluate
2560: 64 20 6f 6e 65 20 62 79 20 6f 6e 65 0a 2a 2a 20  d one by one.** 
2570: 75 6e 74 69 6c 20 65 69 74 68 65 72 20 61 6e 20  until either an 
2580: 65 72 72 6f 72 20 6f 72 20 61 6e 20 69 6e 74 65  error or an inte
2590: 72 72 75 70 74 20 69 73 20 65 6e 63 6f 75 6e 74  rrupt is encount
25a0: 65 72 65 64 20 6f 72 0a 2a 2a 20 75 6e 74 69 6c  ered or.** until
25b0: 20 74 68 65 79 20 61 72 65 20 61 6c 6c 20 64 6f   they are all do
25c0: 6e 65 2e 20 20 54 68 65 20 33 72 64 20 70 61 72  ne.  The 3rd par
25d0: 61 6d 65 74 65 72 20 69 73 20 61 6e 20 6f 70 74  ameter is an opt
25e0: 69 6f 6e 61 6c 0a 2a 2a 20 63 61 6c 6c 62 61 63  ional.** callbac
25f0: 6b 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65  k that is invoke
2600: 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20  d once for each 
2610: 72 6f 77 20 6f 66 20 61 6e 79 20 71 75 65 72 79  row of any query
2620: 20 72 65 73 75 6c 74 73 0a 2a 2a 20 70 72 6f 64   results.** prod
2630: 75 63 65 64 20 62 79 20 74 68 65 20 53 51 4c 20  uced by the SQL 
2640: 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 54 68 65  statements.  The
2650: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
2660: 65 6c 6c 73 20 77 68 65 72 65 0a 2a 2a 20 74 6f  ells where.** to
2670: 20 77 72 69 74 65 20 61 6e 79 20 65 72 72 6f 72   write any error
2680: 20 6d 65 73 73 61 67 65 73 2e 0a 2a 2a 0a 2a 2a   messages..**.**
2690: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65   The sqlite3_exe
26a0: 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  c() interface is
26b0: 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 69 6e 20   implemented in 
26c0: 74 65 72 6d 73 20 6f 66 0a 2a 2a 20 5b 73 71 6c  terms of.** [sql
26d0: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
26e0: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  )], [sqlite3_ste
26f0: 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  p()], and [sqlit
2700: 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a  e3_finalize()]..
2710: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65  ** The sqlite3_e
2720: 78 65 63 28 29 20 72 6f 75 74 69 6e 65 20 64 6f  xec() routine do
2730: 65 73 20 6e 6f 74 68 69 6e 67 20 74 68 61 74 20  es nothing that 
2740: 63 61 6e 6e 6f 74 20 62 65 20 64 6f 6e 65 0a 2a  cannot be done.*
2750: 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72  * by [sqlite3_pr
2760: 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71  epare_v2()], [sq
2770: 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 61  lite3_step()], a
2780: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  nd [sqlite3_fina
2790: 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  lize()]..** The 
27a0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
27b0: 73 20 6a 75 73 74 20 61 20 63 6f 6e 76 65 6e 69  s just a conveni
27c0: 65 6e 74 20 77 72 61 70 70 65 72 2e 0a 2a 2a 0a  ent wrapper..**.
27d0: 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
27e0: 2a 20 0a 2a 2a 20 7b 46 31 32 31 30 31 7d 20 54  * .** {F12101} T
27f0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  he [sqlite3_exec
2800: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 65 76  ()] interface ev
2810: 61 6c 75 61 74 65 73 20 7a 65 72 6f 20 6f 72 20  aluates zero or 
2820: 6d 6f 72 65 20 55 54 46 2d 38 0a 2a 2a 20 20 20  more UTF-8.**   
2830: 20 20 20 20 20 20 20 65 6e 63 6f 64 65 64 2c 20         encoded, 
2840: 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61  semicolon-separa
2850: 74 65 64 2c 20 53 51 4c 20 73 74 61 74 65 6d 65  ted, SQL stateme
2860: 6e 74 73 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20  nts in the.**   
2870: 20 20 20 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d         zero-term
2880: 69 6e 61 74 65 64 20 73 74 72 69 6e 67 20 6f 66  inated string of
2890: 20 69 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74   its 2nd paramet
28a0: 65 72 20 77 69 74 68 69 6e 20 74 68 65 0a 2a 2a  er within the.**
28b0: 20 20 20 20 20 20 20 20 20 20 63 6f 6e 74 65 78            contex
28c0: 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  t of the [sqlite
28d0: 33 5d 20 6f 62 6a 65 63 74 20 67 69 76 65 6e 20  3] object given 
28e0: 69 6e 20 74 68 65 20 31 73 74 20 70 61 72 61 6d  in the 1st param
28f0: 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  eter..**.** {F12
2900: 31 30 34 7d 20 54 68 65 20 72 65 74 75 72 6e 20  104} The return 
2910: 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65  value of [sqlite
2920: 33 5f 65 78 65 63 28 29 5d 20 69 73 20 53 51 4c  3_exec()] is SQL
2930: 49 54 45 5f 4f 4b 20 69 66 20 61 6c 6c 0a 2a 2a  ITE_OK if all.**
2940: 20 20 20 20 20 20 20 20 20 20 53 51 4c 20 73 74            SQL st
2950: 61 74 65 6d 65 6e 74 73 20 72 75 6e 20 73 75 63  atements run suc
2960: 63 65 73 73 66 75 6c 6c 79 2e 0a 2a 2a 0a 2a 2a  cessfully..**.**
2970: 20 7b 46 31 32 31 30 35 7d 20 54 68 65 20 72 65   {F12105} The re
2980: 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 5b 73  turn value of [s
2990: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 69  qlite3_exec()] i
29a0: 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65  s an appropriate
29b0: 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 6f   .**          no
29c0: 6e 2d 7a 65 72 6f 20 65 72 72 6f 72 20 63 6f 64  n-zero error cod
29d0: 65 20 69 66 20 61 6e 79 20 53 51 4c 20 73 74 61  e if any SQL sta
29e0: 74 65 6d 65 6e 74 20 66 61 69 6c 73 2e 0a 2a 2a  tement fails..**
29f0: 0a 2a 2a 20 7b 46 31 32 31 30 37 7d 20 49 66 20  .** {F12107} If 
2a00: 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74  one or more of t
2a10: 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
2a20: 73 20 68 61 6e 64 65 64 20 74 6f 20 5b 73 71 6c  s handed to [sql
2a30: 69 74 65 33 5f 65 78 65 63 28 29 5d 0a 2a 2a 20  ite3_exec()].** 
2a40: 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20           return 
2a50: 72 65 73 75 6c 74 73 20 61 6e 64 20 74 68 65 20  results and the 
2a60: 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  3rd parameter is
2a70: 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 0a   not NULL, then.
2a80: 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
2a90: 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
2aa0: 6e 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  n specified by t
2ab0: 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
2ac0: 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   is.**          
2ad0: 69 6e 76 6f 6b 65 64 20 6f 6e 63 65 20 66 6f 72  invoked once for
2ae0: 20 65 61 63 68 20 72 6f 77 20 6f 66 20 72 65 73   each row of res
2af0: 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31  ult..**.** {F121
2b00: 31 30 7d 20 49 66 20 74 68 65 20 63 61 6c 6c 62  10} If the callb
2b10: 61 63 6b 20 72 65 74 75 72 6e 73 20 61 20 6e 6f  ack returns a no
2b20: 6e 2d 7a 65 72 6f 20 76 61 6c 75 65 20 74 68 65  n-zero value the
2b30: 6e 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  n [sqlite3_exec(
2b40: 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77  )].**          w
2b50: 69 6c 6c 20 61 62 6f 72 74 65 64 20 74 68 65 20  ill aborted the 
2b60: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 74  SQL statement it
2b70: 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 65 76   is currently ev
2b80: 61 6c 75 61 74 69 6e 67 2c 0a 2a 2a 20 20 20 20  aluating,.**    
2b90: 20 20 20 20 20 20 73 6b 69 70 20 61 6c 6c 20 73        skip all s
2ba0: 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20 73 74  ubsequent SQL st
2bb0: 61 74 65 6d 65 6e 74 73 2c 20 61 6e 64 20 72 65  atements, and re
2bc0: 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 41 42 4f  turn [SQLITE_ABO
2bd0: 52 54 5d 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20  RT]..**         
2be0: 20 3c 74 6f 64 6f 3e 57 68 61 74 20 68 61 70 70   <todo>What happ
2bf0: 65 6e 73 20 74 6f 20 2a 65 72 72 6d 73 67 20 68  ens to *errmsg h
2c00: 65 72 65 3f 20 20 44 6f 65 73 20 74 68 65 20 72  ere?  Does the r
2c10: 65 73 75 6c 74 20 63 6f 64 65 20 66 6f 72 0a 2a  esult code for.*
2c20: 2a 20 20 20 20 20 20 20 20 20 20 73 71 6c 69 74  *          sqlit
2c30: 65 33 5f 65 72 72 63 6f 64 65 28 29 20 67 65 74  e3_errcode() get
2c40: 20 73 65 74 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a   set?</todo>.**.
2c50: 2a 2a 20 7b 46 31 32 31 31 33 7d 20 54 68 65 20  ** {F12113} The 
2c60: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
2c70: 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 70 61   routine will pa
2c80: 73 73 20 69 74 73 20 34 74 68 20 70 61 72 61 6d  ss its 4th param
2c90: 65 74 65 72 20 74 68 72 6f 75 67 68 0a 2a 2a 20  eter through.** 
2ca0: 20 20 20 20 20 20 20 20 20 61 73 20 74 68 65 20           as the 
2cb0: 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 6f 66  1st parameter of
2cc0: 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a   the callback..*
2cd0: 2a 0a 2a 2a 20 7b 46 31 32 31 31 36 7d 20 54 68  *.** {F12116} Th
2ce0: 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  e [sqlite3_exec(
2cf0: 29 5d 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20  )] routine sets 
2d00: 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
2d10: 72 20 6f 66 20 69 74 73 0a 2a 2a 20 20 20 20 20  r of its.**     
2d20: 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 20 74 6f       callback to
2d30: 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   be the number o
2d40: 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65  f columns in the
2d50: 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 0a   current row of.
2d60: 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 73 75  **          resu
2d70: 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31 31  lt..**.** {F1211
2d80: 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  9} The [sqlite3_
2d90: 65 78 65 63 28 29 5d 20 72 6f 75 74 69 6e 65 20  exec()] routine 
2da0: 73 65 74 73 20 74 68 65 20 33 72 64 20 70 61 72  sets the 3rd par
2db0: 61 6d 65 74 65 72 20 6f 66 20 69 74 73 20 0a 2a  ameter of its .*
2dc0: 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c 62  *          callb
2dd0: 61 63 6b 20 74 6f 20 62 65 20 61 6e 20 61 72 72  ack to be an arr
2de0: 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74  ay of pointers t
2df0: 6f 20 73 74 72 69 6e 67 73 20 68 6f 6c 64 69 6e  o strings holdin
2e00: 67 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  g the.**        
2e10: 20 20 76 61 6c 75 65 73 20 66 6f 72 20 65 61 63    values for eac
2e20: 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20  h column in the 
2e30: 63 75 72 72 65 6e 74 20 72 65 73 75 6c 74 20 73  current result s
2e40: 65 74 20 72 6f 77 20 61 73 0a 2a 2a 20 20 20 20  et row as.**    
2e50: 20 20 20 20 20 20 6f 62 74 61 69 6e 65 64 20 66        obtained f
2e60: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  rom [sqlite3_col
2e70: 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a  umn_text()]..**.
2e80: 2a 2a 20 7b 46 31 32 31 32 32 7d 20 54 68 65 20  ** {F12122} The 
2e90: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
2ea0: 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 74 68   routine sets th
2eb0: 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
2ec0: 6f 66 20 69 74 73 0a 2a 2a 20 20 20 20 20 20 20  of its.**       
2ed0: 20 20 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 62     callback to b
2ee0: 65 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f  e an array of po
2ef0: 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67  inters to string
2f00: 73 20 68 6f 6c 64 69 6e 67 20 74 68 65 0a 2a 2a  s holding the.**
2f10: 20 20 20 20 20 20 20 20 20 20 6e 61 6d 65 73 20            names 
2f20: 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  of result column
2f30: 73 20 61 73 20 6f 62 74 61 69 6e 65 64 20 66 72  s as obtained fr
2f40: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  om [sqlite3_colu
2f50: 6d 6e 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a  mn_name()]..**.*
2f60: 2a 20 7b 46 31 32 31 32 35 7d 20 49 66 20 74 68  * {F12125} If th
2f70: 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
2f80: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  to [sqlite3_exec
2f90: 28 29 5d 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e  ()] is NULL then
2fa0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
2fb0: 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 6e 65  lite3_exec()] ne
2fc0: 76 65 72 20 69 6e 76 6f 6b 65 73 20 61 20 63 61  ver invokes a ca
2fd0: 6c 6c 62 61 63 6b 2e 20 20 41 6c 6c 20 71 75 65  llback.  All que
2fe0: 72 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  ry.**          r
2ff0: 65 73 75 6c 74 73 20 61 72 65 20 73 69 6c 65 6e  esults are silen
3000: 74 6c 79 20 64 69 73 63 61 72 64 65 64 2e 0a 2a  tly discarded..*
3010: 2a 0a 2a 2a 20 7b 46 31 32 31 32 38 7d 20 49 66  *.** {F12128} If
3020: 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
3030: 20 77 68 69 6c 65 20 70 61 72 73 69 6e 67 20 6f   while parsing o
3040: 72 20 65 76 61 6c 75 61 74 69 6e 67 20 61 6e 79  r evaluating any
3050: 20 6f 66 20 74 68 65 20 53 51 4c 0a 2a 2a 20 20   of the SQL.**  
3060: 20 20 20 20 20 20 20 20 73 74 61 74 65 6d 65 6e          statemen
3070: 74 73 20 68 61 6e 64 65 64 20 74 6f 20 5b 73 71  ts handed to [sq
3080: 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 74 68  lite3_exec()] th
3090: 65 6e 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  en [sqlite3_exec
30a0: 28 29 5d 20 77 69 6c 6c 0a 2a 2a 20 20 20 20 20  ()] will.**     
30b0: 20 20 20 20 20 72 65 74 75 72 6e 20 61 6e 20 5b       return an [
30c0: 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65  error code] othe
30d0: 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f  r than [SQLITE_O
30e0: 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31 33  K]..**.** {F1213
30f0: 31 7d 20 49 66 20 61 6e 20 65 72 72 6f 72 20 6f  1} If an error o
3100: 63 63 75 72 73 20 77 68 69 6c 65 20 70 61 72 73  ccurs while pars
3110: 69 6e 67 20 6f 72 20 65 76 61 6c 75 61 74 69 6e  ing or evaluatin
3120: 67 20 61 6e 79 20 6f 66 20 74 68 65 20 53 51 4c  g any of the SQL
3130: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 68 61 6e  .**          han
3140: 64 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ded to [sqlite3_
3150: 65 78 65 63 28 29 5d 20 61 6e 64 20 69 66 20 74  exec()] and if t
3160: 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
3170: 20 28 65 72 72 6d 73 67 29 0a 2a 2a 20 20 20 20   (errmsg).**    
3180: 20 20 20 20 20 20 74 6f 20 5b 73 71 6c 69 74 65        to [sqlite
3190: 33 5f 65 78 65 63 28 29 5d 20 69 73 20 6e 6f 74  3_exec()] is not
31a0: 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 61 6e 20 65   NULL, then an e
31b0: 72 72 6f 72 20 6d 65 73 73 61 67 65 20 69 73 0a  rror message is.
31c0: 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c 6c 6f  **          allo
31d0: 63 61 74 65 64 20 75 73 69 6e 67 20 74 68 65 20  cated using the 
31e0: 65 71 75 69 76 61 6c 65 6e 74 20 6f 66 20 5b 73  equivalent of [s
31f0: 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29  qlite3_mprintf()
3200: 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20  ] and.**        
3210: 20 20 2a 65 72 72 6d 73 67 20 69 73 20 6d 61 64    *errmsg is mad
3220: 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68  e to point to th
3230: 61 74 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a  at message..**.*
3240: 2a 20 7b 46 31 32 31 33 34 7d 20 54 68 65 20 5b  * {F12134} The [
3250: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20  sqlite3_exec()] 
3260: 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74  routine does not
3270: 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75   change the valu
3280: 65 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20  e of.**         
3290: 20 2a 65 72 72 6d 73 67 20 69 66 20 65 72 72 6d   *errmsg if errm
32a0: 73 67 20 69 73 20 4e 55 4c 4c 20 6f 72 20 69 66  sg is NULL or if
32b0: 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20 65 72   there are no er
32c0: 72 6f 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  rors..**.** {F12
32d0: 31 33 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  137} The [sqlite
32e0: 33 5f 65 78 65 63 28 29 5d 20 66 75 6e 63 74 69  3_exec()] functi
32f0: 6f 6e 20 73 65 74 73 20 74 68 65 20 65 72 72 6f  on sets the erro
3300: 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61  r code and messa
3310: 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  ge.**          a
3320: 63 63 65 73 73 69 62 6c 65 20 76 69 61 20 5b 73  ccessible via [s
3330: 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
3340: 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ], [sqlite3_errm
3350: 73 67 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 20 20  sg()], and.**   
3360: 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
3370: 65 72 72 6d 73 67 31 36 28 29 5d 2e 0a 2a 2a 0a  errmsg16()]..**.
3380: 2a 2a 20 4c 49 4d 49 54 41 54 49 4f 4e 53 3a 0a  ** LIMITATIONS:.
3390: 2a 2a 0a 2a 2a 20 7b 55 31 32 31 34 31 7d 20 54  **.** {U12141} T
33a0: 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
33b0: 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65  er to [sqlite3_e
33c0: 78 65 63 28 29 5d 20 6d 75 73 74 20 62 65 20 61  xec()] must be a
33d0: 6e 20 76 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e  n valid and open
33e0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61  .**          [da
33f0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
3400: 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 55 31 32 31 34  n]..**.** {U1214
3410: 32 7d 20 54 68 65 20 64 61 74 61 62 61 73 65 20  2} The database 
3420: 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20  connection must 
3430: 6e 6f 74 20 62 65 20 63 6c 6f 73 65 64 20 77 68  not be closed wh
3440: 69 6c 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ile.**          
3450: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
3460: 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20   is running..** 
3470: 0a 2a 2a 20 7b 55 31 32 31 34 33 7d 20 54 68 65  .** {U12143} The
3480: 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f   calling functio
3490: 6e 20 69 73 20 73 68 6f 75 6c 64 20 75 73 65 20  n is should use 
34a0: 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
34b0: 20 74 6f 20 66 72 65 65 0a 2a 2a 20 20 20 20 20   to free.**     
34c0: 20 20 20 20 20 74 68 65 20 6d 65 6d 6f 72 79 20       the memory 
34d0: 74 68 61 74 20 2a 65 72 72 6d 73 67 20 69 73 20  that *errmsg is 
34e0: 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 61 74  left pointing at
34f0: 20 6f 6e 63 65 20 74 68 65 20 65 72 72 6f 72 0a   once the error.
3500: 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 65 73 73  **          mess
3510: 61 67 65 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72  age is no longer
3520: 20 6e 65 65 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b   needed..**.** {
3530: 55 31 32 31 34 35 7d 20 54 68 65 20 53 51 4c 20  U12145} The SQL 
3540: 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 69  statement text i
3550: 6e 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  n the 2nd parame
3560: 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
3570: 65 78 65 63 28 29 5d 0a 2a 2a 20 20 20 20 20 20  exec()].**      
3580: 20 20 20 20 6d 75 73 74 20 72 65 6d 61 69 6e 20      must remain 
3590: 75 6e 63 68 61 6e 67 65 64 20 77 68 69 6c 65 20  unchanged while 
35a0: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
35b0: 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a   is running..*/.
35c0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63  int sqlite3_exec
35d0: 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20  (.  sqlite3*,   
35e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
35f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
3600: 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61  * An open databa
3610: 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  se */.  const ch
3620: 61 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20  ar *sql,        
3630: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3640: 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20     /* SQL to be 
3650: 65 76 61 6c 75 74 65 64 20 2a 2f 0a 20 20 69 6e  evaluted */.  in
3660: 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f  t (*callback)(vo
3670: 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63  id*,int,char**,c
3680: 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c  har**),  /* Call
3690: 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f  back function */
36a0: 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20  .  void *,      
36b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
36c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
36d0: 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f   1st argument to
36e0: 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63   callback */.  c
36f0: 68 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20  har **errmsg    
3700: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3710: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72            /* Err
3720: 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68  or msg written h
3730: 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  ere */.);../*.**
3740: 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c   CAPI3REF: Resul
3750: 74 20 43 6f 64 65 73 20 7b 46 31 30 32 31 30 7d  t Codes {F10210}
3760: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51  .** KEYWORDS: SQ
3770: 4c 49 54 45 5f 4f 4b 20 7b 65 72 72 6f 72 20 63  LITE_OK {error c
3780: 6f 64 65 7d 20 7b 65 72 72 6f 72 20 63 6f 64 65  ode} {error code
3790: 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51  s}.**.** Many SQ
37a0: 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20 72  Lite functions r
37b0: 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65 72  eturn an integer
37c0: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72 6f   result code fro
37d0: 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e 0a  m the set shown.
37e0: 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65 72  ** here in order
37f0: 20 74 6f 20 69 6e 64 69 63 61 74 65 73 20 73 75   to indicates su
3800: 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65  ccess or failure
3810: 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
3820: 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  : [SQLITE_IOERR_
3830: 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64 20  READ | extended 
3840: 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 0a 2a 2f  result codes].*/
3850: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3860: 4f 4b 20 20 20 20 20 20 20 20 20 20 20 30 20 20  OK           0  
3870: 20 2f 2a 20 53 75 63 63 65 73 73 66 75 6c 20 72   /* Successful r
3880: 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67 69  esult */./* begi
3890: 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d 63  nning-of-error-c
38a0: 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20  odes */.#define 
38b0: 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 20 20 20  SQLITE_ERROR    
38c0: 20 20 20 20 31 20 20 20 2f 2a 20 53 51 4c 20 65      1   /* SQL e
38d0: 72 72 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67 20  rror or missing 
38e0: 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66  database */.#def
38f0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52  ine SQLITE_INTER
3900: 4e 41 4c 20 20 20 20 20 32 20 20 20 2f 2a 20 49  NAL     2   /* I
3910: 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65 72  nternal logic er
3920: 72 6f 72 20 69 6e 20 53 51 4c 69 74 65 20 2a 2f  ror in SQLite */
3930: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3940: 50 45 52 4d 20 20 20 20 20 20 20 20 20 33 20 20  PERM         3  
3950: 20 2f 2a 20 41 63 63 65 73 73 20 70 65 72 6d 69   /* Access permi
3960: 73 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a  ssion denied */.
3970: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
3980: 42 4f 52 54 20 20 20 20 20 20 20 20 34 20 20 20  BORT        4   
3990: 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75 74  /* Callback rout
39a0: 69 6e 65 20 72 65 71 75 65 73 74 65 64 20 61 6e  ine requested an
39b0: 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69 6e   abort */.#defin
39c0: 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20  e SQLITE_BUSY   
39d0: 20 20 20 20 20 20 35 20 20 20 2f 2a 20 54 68 65        5   /* The
39e0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69   database file i
39f0: 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66  s locked */.#def
3a00: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45  ine SQLITE_LOCKE
3a10: 44 20 20 20 20 20 20 20 36 20 20 20 2f 2a 20 41  D       6   /* A
3a20: 20 74 61 62 6c 65 20 69 6e 20 74 68 65 20 64 61   table in the da
3a30: 74 61 62 61 73 65 20 69 73 20 6c 6f 63 6b 65 64  tabase is locked
3a40: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
3a50: 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20  TE_NOMEM        
3a60: 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63 28  7   /* A malloc(
3a70: 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65 66  ) failed */.#def
3a80: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f  ine SQLITE_READO
3a90: 4e 4c 59 20 20 20 20 20 38 20 20 20 2f 2a 20 41  NLY     8   /* A
3aa0: 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65 20  ttempt to write 
3ab0: 61 20 72 65 61 64 6f 6e 6c 79 20 64 61 74 61 62  a readonly datab
3ac0: 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ase */.#define S
3ad0: 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 20  QLITE_INTERRUPT 
3ae0: 20 20 20 39 20 20 20 2f 2a 20 4f 70 65 72 61 74     9   /* Operat
3af0: 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64 20 62  ion terminated b
3b00: 79 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  y sqlite3_interr
3b10: 75 70 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65 20  upt()*/.#define 
3b20: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 20 20 20  SQLITE_IOERR    
3b30: 20 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65 20     10   /* Some 
3b40: 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f 4f  kind of disk I/O
3b50: 20 65 72 72 6f 72 20 6f 63 63 75 72 72 65 64 20   error occurred 
3b60: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
3b70: 45 5f 43 4f 52 52 55 50 54 20 20 20 20 20 31 31  E_CORRUPT     11
3b80: 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61     /* The databa
3b90: 73 65 20 64 69 73 6b 20 69 6d 61 67 65 20 69 73  se disk image is
3ba0: 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23 64   malformed */.#d
3bb0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
3bc0: 46 4f 55 4e 44 20 20 20 20 31 32 20 20 20 2f 2a  FOUND    12   /*
3bd0: 20 4e 4f 54 20 55 53 45 44 2e 20 54 61 62 6c 65   NOT USED. Table
3be0: 20 6f 72 20 72 65 63 6f 72 64 20 6e 6f 74 20 66   or record not f
3bf0: 6f 75 6e 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ound */.#define 
3c00: 53 51 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20 20  SQLITE_FULL     
3c10: 20 20 20 31 33 20 20 20 2f 2a 20 49 6e 73 65 72     13   /* Inser
3c20: 74 69 6f 6e 20 66 61 69 6c 65 64 20 62 65 63 61  tion failed beca
3c30: 75 73 65 20 64 61 74 61 62 61 73 65 20 69 73 20  use database is 
3c40: 66 75 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20  full */.#define 
3c50: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20  SQLITE_CANTOPEN 
3c60: 20 20 20 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c     14   /* Unabl
3c70: 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61  e to open the da
3c80: 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23  tabase file */.#
3c90: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52  define SQLITE_PR
3ca0: 4f 54 4f 43 4f 4c 20 20 20 20 31 35 20 20 20 2f  OTOCOL    15   /
3cb0: 2a 20 4e 4f 54 20 55 53 45 44 2e 20 44 61 74 61  * NOT USED. Data
3cc0: 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f 63  base lock protoc
3cd0: 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66  ol error */.#def
3ce0: 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50 54 59  ine SQLITE_EMPTY
3cf0: 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 44         16   /* D
3d00: 61 74 61 62 61 73 65 20 69 73 20 65 6d 70 74 79  atabase is empty
3d10: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
3d20: 54 45 5f 53 43 48 45 4d 41 20 20 20 20 20 20 31  TE_SCHEMA      1
3d30: 37 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62  7   /* The datab
3d40: 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67  ase schema chang
3d50: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
3d60: 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 20 20 20  LITE_TOOBIG     
3d70: 20 31 38 20 20 20 2f 2a 20 53 74 72 69 6e 67 20   18   /* String 
3d80: 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 64 73 20  or BLOB exceeds 
3d90: 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23 64  size limit */.#d
3da0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
3db0: 53 54 52 41 49 4e 54 20 20 31 39 20 20 20 2f 2a  STRAINT  19   /*
3dc0: 20 41 62 6f 72 74 20 64 75 65 20 74 6f 20 63 6f   Abort due to co
3dd0: 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69  nstraint violati
3de0: 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  on */.#define SQ
3df0: 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 20 20 20  LITE_MISMATCH   
3e00: 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20 74 79   20   /* Data ty
3e10: 70 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a 23  pe mismatch */.#
3e20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49  define SQLITE_MI
3e30: 53 55 53 45 20 20 20 20 20 20 32 31 20 20 20 2f  SUSE      21   /
3e40: 2a 20 4c 69 62 72 61 72 79 20 75 73 65 64 20 69  * Library used i
3e50: 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23 64  ncorrectly */.#d
3e60: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4c  efine SQLITE_NOL
3e70: 46 53 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a  FS       22   /*
3e80: 20 55 73 65 73 20 4f 53 20 66 65 61 74 75 72 65   Uses OS feature
3e90: 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 64 20  s not supported 
3ea0: 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66 69  on host */.#defi
3eb0: 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48 20 20  ne SQLITE_AUTH  
3ec0: 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 41 75        23   /* Au
3ed0: 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e 69  thorization deni
3ee0: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
3ef0: 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 20 20 20  LITE_FORMAT     
3f00: 20 32 34 20 20 20 2f 2a 20 41 75 78 69 6c 69 61   24   /* Auxilia
3f10: 72 79 20 64 61 74 61 62 61 73 65 20 66 6f 72 6d  ry database form
3f20: 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66  at error */.#def
3f30: 69 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e 47 45  ine SQLITE_RANGE
3f40: 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 32         25   /* 2
3f50: 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
3f60: 73 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75 74  sqlite3_bind out
3f70: 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64 65   of range */.#de
3f80: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 41  fine SQLITE_NOTA
3f90: 44 42 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20  DB      26   /* 
3fa0: 46 69 6c 65 20 6f 70 65 6e 65 64 20 74 68 61 74  File opened that
3fb0: 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61   is not a databa
3fc0: 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69  se file */.#defi
3fd0: 6e 65 20 53 51 4c 49 54 45 5f 52 4f 57 20 20 20  ne SQLITE_ROW   
3fe0: 20 20 20 20 20 20 31 30 30 20 20 2f 2a 20 73 71        100  /* sq
3ff0: 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73  lite3_step() has
4000: 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 72 65 61   another row rea
4010: 64 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  dy */.#define SQ
4020: 4c 49 54 45 5f 44 4f 4e 45 20 20 20 20 20 20 20  LITE_DONE       
4030: 20 31 30 31 20 20 2f 2a 20 73 71 6c 69 74 65 33   101  /* sqlite3
4040: 5f 73 74 65 70 28 29 20 68 61 73 20 66 69 6e 69  _step() has fini
4050: 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 20 2a  shed executing *
4060: 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 6f  /./* end-of-erro
4070: 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a  r-codes */../*.*
4080: 2a 20 43 41 50 49 33 52 45 46 3a 20 45 78 74 65  * CAPI3REF: Exte
4090: 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65  nded Result Code
40a0: 73 20 7b 46 31 30 32 32 30 7d 0a 2a 2a 20 4b 45  s {F10220}.** KE
40b0: 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65  YWORDS: {extende
40c0: 64 20 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65  d error code} {e
40d0: 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f  xtended error co
40e0: 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  des}.** KEYWORDS
40f0: 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75  : {extended resu
4100: 6c 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20  lt codes}.**.** 
4110: 49 6e 20 69 74 73 20 64 65 66 61 75 6c 74 20 63  In its default c
4120: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 53 51  onfiguration, SQ
4130: 4c 69 74 65 20 41 50 49 20 72 6f 75 74 69 6e 65  Lite API routine
4140: 73 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20  s return one of 
4150: 32 36 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53  26 integer.** [S
4160: 51 4c 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c  QLITE_OK | resul
4170: 74 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76  t codes].  Howev
4180: 65 72 2c 20 65 78 70 65 72 69 65 6e 63 65 20 68  er, experience h
4190: 61 73 20 73 68 6f 77 6e 20 74 68 61 74 0a 2a 2a  as shown that.**
41a0: 20 6d 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72   many of these r
41b0: 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20  esult codes are 
41c0: 74 6f 6f 20 63 6f 75 72 73 65 2d 67 72 61 69 6e  too course-grain
41d0: 65 64 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f 74  ed.  They do not
41e0: 20 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d   provide as.** m
41f0: 75 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  uch information 
4200: 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20 61  about problems a
4210: 73 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69  s programmers mi
4220: 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e  ght like.  In an
4230: 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64   effort to.** ad
4240: 64 72 65 73 73 20 74 68 69 73 2c 20 6e 65 77 65  dress this, newe
4250: 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  r versions of SQ
4260: 4c 69 74 65 20 28 76 65 72 73 69 6f 6e 20 33 2e  Lite (version 3.
4270: 33 2e 38 20 61 6e 64 20 6c 61 74 65 72 29 20 69  3.8 and later) i
4280: 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72  nclude.** suppor
4290: 74 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  t for additional
42a0: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 74 68   result codes th
42b0: 61 74 20 70 72 6f 76 69 64 65 20 6d 6f 72 65 20  at provide more 
42c0: 64 65 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61  detailed informa
42d0: 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72  tion.** about er
42e0: 72 6f 72 73 2e 20 54 68 65 20 65 78 74 65 6e 64  rors. The extend
42f0: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ed result codes 
4300: 61 72 65 20 65 6e 61 62 6c 65 64 20 6f 72 20 64  are enabled or d
4310: 69 73 61 62 6c 65 64 0a 2a 2a 20 66 6f 72 20 65  isabled.** for e
4320: 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ach database con
4330: 6e 65 63 74 69 6f 6e 20 75 73 69 6e 67 20 74 68  nection using th
4340: 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  e [sqlite3_exten
4350: 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73  ded_result_codes
4360: 28 29 5d 0a 2a 2a 20 41 50 49 2e 0a 2a 2a 20 0a  ()].** API..** .
4370: 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68 65 20 61  ** Some of the a
4380: 76 61 69 6c 61 62 6c 65 20 65 78 74 65 6e 64 65  vailable extende
4390: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61  d result codes a
43a0: 72 65 20 6c 69 73 74 65 64 20 68 65 72 65 2e 0a  re listed here..
43b0: 2a 2a 20 4f 6e 65 20 6d 61 79 20 65 78 70 65 63  ** One may expec
43c0: 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
43d0: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
43e0: 63 6f 64 65 73 20 77 69 6c 6c 20 62 65 20 65 78  codes will be ex
43f0: 70 61 6e 64 0a 2a 2a 20 6f 76 65 72 20 74 69 6d  pand.** over tim
4400: 65 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61  e.  Software tha
4410: 74 20 75 73 65 73 20 65 78 74 65 6e 64 65 64 20  t uses extended 
4420: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 73 68 6f  result codes sho
4430: 75 6c 64 20 65 78 70 65 63 74 0a 2a 2a 20 74 6f  uld expect.** to
4440: 20 73 65 65 20 6e 65 77 20 72 65 73 75 6c 74 20   see new result 
4450: 63 6f 64 65 73 20 69 6e 20 66 75 74 75 72 65 20  codes in future 
4460: 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
4470: 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  te..**.** The SQ
4480: 4c 49 54 45 5f 4f 4b 20 72 65 73 75 6c 74 20 63  LITE_OK result c
4490: 6f 64 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 62  ode will never b
44a0: 65 20 65 78 74 65 6e 64 65 64 2e 20 20 49 74 20  e extended.  It 
44b0: 77 69 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a 20 62  will always.** b
44c0: 65 20 65 78 61 63 74 6c 79 20 7a 65 72 6f 2e 0a  e exactly zero..
44d0: 2a 2a 20 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  ** .** INVARIANT
44e0: 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 32 32 33  S:.**.** {F10223
44f0: 7d 20 54 68 65 20 73 79 6d 62 6f 6c 69 63 20 6e  } The symbolic n
4500: 61 6d 65 20 66 6f 72 20 61 6e 20 65 78 74 65 6e  ame for an exten
4510: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 20  ded result code 
4520: 61 6c 77 61 79 73 20 63 6f 6e 74 61 69 6e 73 0a  always contains.
4530: 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 72 65  **          a re
4540: 6c 61 74 65 64 20 70 72 69 6d 61 72 79 20 72 65  lated primary re
4550: 73 75 6c 74 20 63 6f 64 65 20 61 73 20 61 20 70  sult code as a p
4560: 72 65 66 69 78 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  refix..**.** {F1
4570: 30 32 32 34 7d 20 50 72 69 6d 61 72 79 20 72 65  0224} Primary re
4580: 73 75 6c 74 20 63 6f 64 65 20 6e 61 6d 65 73 20  sult code names 
4590: 63 6f 6e 74 61 69 6e 20 61 20 73 69 6e 67 6c 65  contain a single
45a0: 20 22 5f 22 20 63 68 61 72 61 63 74 65 72 2e 0a   "_" character..
45b0: 2a 2a 0a 2a 2a 20 7b 46 31 30 32 32 35 7d 20 45  **.** {F10225} E
45c0: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
45d0: 6f 64 65 20 6e 61 6d 65 73 20 63 6f 6e 74 61 69  ode names contai
45e0: 6e 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 22 5f  n two or more "_
45f0: 22 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a  " characters..**
4600: 0a 2a 2a 20 7b 46 31 30 32 32 36 7d 20 54 68 65  .** {F10226} The
4610: 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 6f   numeric value o
4620: 66 20 61 6e 20 65 78 74 65 6e 64 65 64 20 72 65  f an extended re
4630: 73 75 6c 74 20 63 6f 64 65 20 63 6f 6e 74 61 69  sult code contai
4640: 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ns the.**       
4650: 20 20 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65     numeric value
4660: 20 6f 66 20 69 74 73 20 63 6f 72 72 65 73 70 6f   of its correspo
4670: 6e 64 69 6e 67 20 70 72 69 6d 61 72 79 20 72 65  nding primary re
4680: 73 75 6c 74 20 63 6f 64 65 20 69 6e 0a 2a 2a 20  sult code in.** 
4690: 20 20 20 20 20 20 20 20 20 69 74 73 20 6c 65 61           its lea
46a0: 73 74 20 73 69 67 6e 69 66 69 63 61 6e 74 20 38  st significant 8
46b0: 20 62 69 74 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e   bits..*/.#defin
46c0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52  e SQLITE_IOERR_R
46d0: 45 41 44 20 20 20 20 20 20 20 20 20 20 28 53 51  EAD          (SQ
46e0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c  LITE_IOERR | (1<
46f0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
4700: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f  ITE_IOERR_SHORT_
4710: 52 45 41 44 20 20 20 20 28 53 51 4c 49 54 45 5f  READ    (SQLITE_
4720: 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38 29 29 0a  IOERR | (2<<8)).
4730: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4740: 4f 45 52 52 5f 57 52 49 54 45 20 20 20 20 20 20  OERR_WRITE      
4750: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
4760: 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69   | (3<<8)).#defi
4770: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
4780: 46 53 59 4e 43 20 20 20 20 20 20 20 20 20 28 53  FSYNC         (S
4790: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 34  QLITE_IOERR | (4
47a0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
47b0: 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 46  LITE_IOERR_DIR_F
47c0: 53 59 4e 43 20 20 20 20 20 28 53 51 4c 49 54 45  SYNC     (SQLITE
47d0: 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29  _IOERR | (5<<8))
47e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
47f0: 49 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20  IOERR_TRUNCATE  
4800: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4810: 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 66  R | (6<<8)).#def
4820: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4830: 5f 46 53 54 41 54 20 20 20 20 20 20 20 20 20 28  _FSTAT         (
4840: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
4850: 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  7<<8)).#define S
4860: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f  QLITE_IOERR_UNLO
4870: 43 4b 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  CK        (SQLIT
4880: 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c 3c 38 29  E_IOERR | (8<<8)
4890: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
48a0: 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b 20 20 20  _IOERR_RDLOCK   
48b0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
48c0: 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65  RR | (9<<8)).#de
48d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
48e0: 52 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20  R_DELETE        
48f0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4900: 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (10<<8)).#define
4910: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c   SQLITE_IOERR_BL
4920: 4f 43 4b 45 44 20 20 20 20 20 20 20 28 53 51 4c  OCKED       (SQL
4930: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c  ITE_IOERR | (11<
4940: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
4950: 49 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20  ITE_IOERR_NOMEM 
4960: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
4970: 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c 38 29 29  IOERR | (12<<8))
4980: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
4990: 3a 20 46 6c 61 67 73 20 46 6f 72 20 46 69 6c 65  : Flags For File
49a0: 20 4f 70 65 6e 20 4f 70 65 72 61 74 69 6f 6e 73   Open Operations
49b0: 20 7b 46 31 30 32 33 30 7d 0a 2a 2a 0a 2a 2a 20   {F10230}.**.** 
49c0: 54 68 65 73 65 20 62 69 74 20 76 61 6c 75 65 73  These bit values
49d0: 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f   are intended fo
49e0: 72 20 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20  r use in the.** 
49f0: 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
4a00: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70   the [sqlite3_op
4a10: 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61  en_v2()] interfa
4a20: 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65  ce and.** in the
4a30: 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
4a40: 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68  o the xOpen meth
4a50: 6f 64 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  od of the.** [sq
4a60: 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
4a70: 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t..*/.#define SQ
4a80: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
4a90: 4c 59 20 20 20 20 20 20 20 20 20 30 78 30 30 30  LY         0x000
4aa0: 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51  00001.#define SQ
4ab0: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
4ac0: 49 54 45 20 20 20 20 20 20 20 20 30 78 30 30 30  ITE        0x000
4ad0: 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51  00002.#define SQ
4ae0: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
4af0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
4b00: 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51  00004.#define SQ
4b10: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
4b20: 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30  ONCLOSE    0x000
4b30: 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51  00008.#define SQ
4b40: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53  LITE_OPEN_EXCLUS
4b50: 49 56 45 20 20 20 20 20 20 20 20 30 78 30 30 30  IVE        0x000
4b60: 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53 51  00010.#define SQ
4b70: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44  LITE_OPEN_MAIN_D
4b80: 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  B          0x000
4b90: 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00100.#define SQ
4ba0: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44  LITE_OPEN_TEMP_D
4bb0: 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  B          0x000
4bc0: 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00200.#define SQ
4bd0: 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49  LITE_OPEN_TRANSI
4be0: 45 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30 30  ENT_DB     0x000
4bf0: 30 30 34 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00400.#define SQ
4c00: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a  LITE_OPEN_MAIN_J
4c10: 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30  OURNAL     0x000
4c20: 30 30 38 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00800.#define SQ
4c30: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a  LITE_OPEN_TEMP_J
4c40: 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30  OURNAL     0x000
4c50: 30 31 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51  01000.#define SQ
4c60: 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55  LITE_OPEN_SUBJOU
4c70: 52 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30 30  RNAL       0x000
4c80: 30 32 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51  02000.#define SQ
4c90: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52  LITE_OPEN_MASTER
4ca0: 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30  _JOURNAL   0x000
4cb0: 30 34 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  04000../*.** CAP
4cc0: 49 33 52 45 46 3a 20 44 65 76 69 63 65 20 43 68  I3REF: Device Ch
4cd0: 61 72 61 63 74 65 72 69 73 74 69 63 73 20 7b 46  aracteristics {F
4ce0: 31 30 32 34 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  10240}.**.** The
4cf0: 20 78 44 65 76 69 63 65 43 61 70 61 62 69 6c 69   xDeviceCapabili
4d00: 74 69 65 73 20 6d 65 74 68 6f 64 20 6f 66 20 74  ties method of t
4d10: 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  he [sqlite3_io_m
4d20: 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63  ethods].** objec
4d30: 74 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74  t returns an int
4d40: 65 67 65 72 20 77 68 69 63 68 20 69 73 20 61 20  eger which is a 
4d50: 76 65 63 74 6f 72 20 6f 66 20 74 68 65 20 74 68  vector of the th
4d60: 65 73 65 0a 2a 2a 20 62 69 74 20 76 61 6c 75 65  ese.** bit value
4d70: 73 20 65 78 70 72 65 73 73 69 6e 67 20 49 2f 4f  s expressing I/O
4d80: 20 63 68 61 72 61 63 74 65 72 69 73 74 69 63 73   characteristics
4d90: 20 6f 66 20 74 68 65 20 6d 61 73 73 20 73 74 6f   of the mass sto
4da0: 72 61 67 65 0a 2a 2a 20 64 65 76 69 63 65 20 74  rage.** device t
4db0: 68 61 74 20 68 6f 6c 64 73 20 74 68 65 20 66 69  hat holds the fi
4dc0: 6c 65 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c  le that the [sql
4dd0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
4de0: 0a 2a 2a 20 72 65 66 65 72 73 20 74 6f 2e 0a 2a  .** refers to..*
4df0: 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f  *.** The SQLITE_
4e00: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f  IOCAP_ATOMIC pro
4e10: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
4e20: 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a   all writes of.*
4e30: 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61  * any size are a
4e40: 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49  tomic.  The SQLI
4e50: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e  TE_IOCAP_ATOMICn
4e60: 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61  nn values.** mea
4e70: 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 6f 66  n that writes of
4e80: 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65   blocks that are
4e90: 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69   nnn bytes in si
4ea0: 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c  ze and.** are al
4eb0: 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72  igned to an addr
4ec0: 65 73 73 20 77 68 69 63 68 20 69 73 20 61 6e 20  ess which is an 
4ed0: 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65  integer multiple
4ee0: 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61   of.** nnn are a
4ef0: 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49  tomic.  The SQLI
4f00: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50  TE_IOCAP_SAFE_AP
4f10: 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73  PEND value means
4f20: 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61  .** that when da
4f30: 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 20 74  ta is appended t
4f40: 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61  o a file, the da
4f50: 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a  ta is appended.*
4f60: 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 68 65  * first then the
4f70: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c   size of the fil
4f80: 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e  e is extended, n
4f90: 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a  ever the other.*
4fa0: 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54  * way around.  T
4fb0: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
4fc0: 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65  SEQUENTIAL prope
4fd0: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a  rty means that.*
4fe0: 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  * information is
4ff0: 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b   written to disk
5000: 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64   in the same ord
5010: 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74  er as calls.** t
5020: 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2f 0a 23  o xWrite()..*/.#
5030: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5040: 43 41 50 5f 41 54 4f 4d 49 43 20 20 20 20 20 20  CAP_ATOMIC      
5050: 20 20 20 20 30 78 30 30 30 30 30 30 30 31 0a 23      0x00000001.#
5060: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5070: 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 20 20 20  CAP_ATOMIC512   
5080: 20 20 20 20 30 78 30 30 30 30 30 30 30 32 0a 23      0x00000002.#
5090: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
50a0: 43 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20  CAP_ATOMIC1K    
50b0: 20 20 20 20 30 78 30 30 30 30 30 30 30 34 0a 23      0x00000004.#
50c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
50d0: 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20  CAP_ATOMIC2K    
50e0: 20 20 20 20 30 78 30 30 30 30 30 30 30 38 0a 23      0x00000008.#
50f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5100: 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20  CAP_ATOMIC4K    
5110: 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0a 23      0x00000010.#
5120: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5130: 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20  CAP_ATOMIC8K    
5140: 20 20 20 20 30 78 30 30 30 30 30 30 32 30 0a 23      0x00000020.#
5150: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5160: 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20  CAP_ATOMIC16K   
5170: 20 20 20 20 30 78 30 30 30 30 30 30 34 30 0a 23      0x00000040.#
5180: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5190: 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20  CAP_ATOMIC32K   
51a0: 20 20 20 20 30 78 30 30 30 30 30 30 38 30 0a 23      0x00000080.#
51b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
51c0: 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20  CAP_ATOMIC64K   
51d0: 20 20 20 20 30 78 30 30 30 30 30 31 30 30 0a 23      0x00000100.#
51e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
51f0: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
5200: 20 20 20 20 30 78 30 30 30 30 30 32 30 30 0a 23      0x00000200.#
5210: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5220: 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 20  CAP_SEQUENTIAL  
5230: 20 20 20 20 30 78 30 30 30 30 30 34 30 30 0a 0a      0x00000400..
5240: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
5250: 46 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76  File Locking Lev
5260: 65 6c 73 20 7b 46 31 30 32 35 30 7d 0a 2a 2a 0a  els {F10250}.**.
5270: 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 6f  ** SQLite uses o
5280: 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65  ne of these inte
5290: 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68  ger values as th
52a0: 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75  e second.** argu
52b0: 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 74  ment to calls it
52c0: 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78 4c   makes to the xL
52d0: 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63  ock() and xUnloc
52e0: 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f  k() methods.** o
52f0: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f  f an [sqlite3_io
5300: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
5310: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
5320: 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20  ITE_LOCK_NONE   
5330: 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65         0.#define
5340: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41   SQLITE_LOCK_SHA
5350: 52 45 44 20 20 20 20 20 20 20 20 31 0a 23 64 65  RED        1.#de
5360: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
5370: 5f 52 45 53 45 52 56 45 44 20 20 20 20 20 20 32  _RESERVED      2
5380: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5390: 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20  LOCK_PENDING    
53a0: 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c     3.#define SQL
53b0: 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49  ITE_LOCK_EXCLUSI
53c0: 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20  VE     4../*.** 
53d0: 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68 72  CAPI3REF: Synchr
53e0: 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 46  onization Type F
53f0: 6c 61 67 73 20 7b 46 31 30 32 36 30 7d 0a 2a 2a  lags {F10260}.**
5400: 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69 74 65 20  .** When SQLite 
5410: 69 6e 76 6f 6b 65 73 20 74 68 65 20 78 53 79 6e  invokes the xSyn
5420: 63 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e  c() method of an
5430: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  .** [sqlite3_io_
5440: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20  methods] object 
5450: 69 74 20 75 73 65 73 20 61 20 63 6f 6d 62 69 6e  it uses a combin
5460: 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 73  ation of.** thes
5470: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
5480: 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61   as the second a
5490: 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57  rgument..**.** W
54a0: 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 53  hen the SQLITE_S
54b0: 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 66 6c 61  YNC_DATAONLY fla
54c0: 67 20 69 73 20 75 73 65 64 2c 20 69 74 20 6d 65  g is used, it me
54d0: 61 6e 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  ans that the.** 
54e0: 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 20 6f  sync operation o
54f0: 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 66 6c 75  nly needs to flu
5500: 73 68 20 64 61 74 61 20 74 6f 20 6d 61 73 73 20  sh data to mass 
5510: 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f 64 65 0a  storage.  Inode.
5520: 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e  ** information n
5530: 65 65 64 20 6e 6f 74 20 62 65 20 66 6c 75 73 68  eed not be flush
5540: 65 64 2e 20 54 68 65 20 53 51 4c 49 54 45 5f 53  ed. The SQLITE_S
5550: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 66 6c 61 67 20  YNC_NORMAL flag 
5560: 6d 65 61 6e 73 20 0a 2a 2a 20 74 6f 20 75 73 65  means .** to use
5570: 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20   normal fsync() 
5580: 73 65 6d 61 6e 74 69 63 73 2e 20 54 68 65 20 53  semantics. The S
5590: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20  QLITE_SYNC_FULL 
55a0: 66 6c 61 67 20 6d 65 61 6e 73 20 0a 2a 2a 20 74  flag means .** t
55b0: 6f 20 75 73 65 20 4d 61 63 20 4f 53 2d 58 20 73  o use Mac OS-X s
55c0: 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69 6e  tyle fullsync in
55d0: 73 74 65 61 64 20 6f 66 20 66 73 79 6e 63 28 29  stead of fsync()
55e0: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
55f0: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20  ITE_SYNC_NORMAL 
5600: 20 20 20 20 20 20 20 30 78 30 30 30 30 32 0a 23         0x00002.#
5610: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59  define SQLITE_SY
5620: 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 20  NC_FULL         
5630: 20 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e 65   0x00003.#define
5640: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54   SQLITE_SYNC_DAT
5650: 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30 30  AONLY      0x000
5660: 31 30 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  10.../*.** CAPI3
5670: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63  REF: OS Interfac
5680: 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64  e Open File Hand
5690: 6c 65 20 7b 46 31 31 31 31 30 7d 0a 2a 2a 0a 2a  le {F11110}.**.*
56a0: 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69  * An [sqlite3_fi
56b0: 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72 65  le] object repre
56c0: 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66 69  sents an open fi
56d0: 6c 65 20 69 6e 20 74 68 65 20 4f 53 0a 2a 2a 20  le in the OS.** 
56e0: 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 2e  interface layer.
56f0: 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f 53 20    Individual OS 
5700: 69 6e 74 65 72 66 61 63 65 20 69 6d 70 6c 65 6d  interface implem
5710: 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a  entations will.*
5720: 2a 20 77 61 6e 74 20 74 6f 20 73 75 62 63 6c 61  * want to subcla
5730: 73 73 20 74 68 69 73 20 6f 62 6a 65 63 74 20 62  ss this object b
5740: 79 20 61 70 70 65 6e 64 69 6e 67 20 61 64 64 69  y appending addi
5750: 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a 2a  tional fields.**
5760: 20 66 6f 72 20 74 68 65 69 72 20 6f 77 6e 20 75   for their own u
5770: 73 65 2e 20 20 54 68 65 20 70 4d 65 74 68 6f 64  se.  The pMethod
5780: 73 20 65 6e 74 72 79 20 69 73 20 61 20 70 6f 69  s entry is a poi
5790: 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73  nter to an.** [s
57a0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
57b0: 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64  s] object that d
57c0: 65 66 69 6e 65 73 20 6d 65 74 68 6f 64 73 20 66  efines methods f
57d0: 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a  or performing.**
57e0: 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20   I/O operations 
57f0: 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65  on the open file
5800: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
5810: 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  uct sqlite3_file
5820: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b 0a 73   sqlite3_file;.s
5830: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69  truct sqlite3_fi
5840: 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73 74 72  le {.  const str
5850: 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  uct sqlite3_io_m
5860: 65 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f 64 73  ethods *pMethods
5870: 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f  ;  /* Methods fo
5880: 72 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 2a  r an open file *
5890: 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
58a0: 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61  3REF: OS Interfa
58b0: 63 65 20 46 69 6c 65 20 56 69 72 74 75 61 6c 20  ce File Virtual 
58c0: 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63 74 20 7b  Methods Object {
58d0: 46 31 31 31 32 30 7d 0a 2a 2a 0a 2a 2a 20 45 76  F11120}.**.** Ev
58e0: 65 72 79 20 66 69 6c 65 20 6f 70 65 6e 65 64 20  ery file opened 
58f0: 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  by the [sqlite3_
5900: 76 66 73 5d 20 78 4f 70 65 6e 20 6d 65 74 68 6f  vfs] xOpen metho
5910: 64 20 63 6f 6e 74 61 69 6e 73 20 61 20 70 6f 69  d contains a poi
5920: 6e 74 65 72 20 74 6f 0a 2a 2a 20 61 6e 20 69 6e  nter to.** an in
5930: 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
5940: 62 6a 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a  bject.  This obj
5950: 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 0a  ect defines the.
5960: 2a 2a 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20  ** methods used 
5970: 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f  to perform vario
5980: 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 67  us operations ag
5990: 61 69 6e 73 74 20 74 68 65 20 6f 70 65 6e 20 66  ainst the open f
59a0: 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  ile..**.** The f
59b0: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
59c0: 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e   xSync may be on
59d0: 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e  e of [SQLITE_SYN
59e0: 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20  C_NORMAL] or.** 
59f0: 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c  [SQLITE_SYNC_FUL
5a00: 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 63  L].  The first c
5a10: 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72  hoice is the nor
5a20: 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 20 20  mal fsync()..*  
5a30: 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63  The second choic
5a40: 65 20 69 73 20 61 6e 0a 2a 2a 20 4f 53 2d 58 20  e is an.** OS-X 
5a50: 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20  style fullsync. 
5a60: 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43   The SQLITE_SYNC
5a70: 5f 44 41 54 41 20 66 6c 61 67 20 6d 61 79 20 62  _DATA flag may b
5a80: 65 20 4f 52 65 64 20 69 6e 20 74 6f 0a 2a 2a 20  e ORed in to.** 
5a90: 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 6f 6e  indicate that on
5aa0: 6c 79 20 74 68 65 20 64 61 74 61 20 6f 66 20 74  ly the data of t
5ab0: 68 65 20 66 69 6c 65 20 61 6e 64 20 6e 6f 74 20  he file and not 
5ac0: 69 74 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20  its inode needs 
5ad0: 74 6f 20 62 65 0a 2a 2a 20 73 79 6e 63 65 64 2e  to be.** synced.
5ae0: 0a 2a 2a 20 0a 2a 2a 20 54 68 65 20 69 6e 74 65  .** .** The inte
5af0: 67 65 72 20 76 61 6c 75 65 73 20 74 6f 20 78 4c  ger values to xL
5b00: 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63  ock() and xUnloc
5b10: 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f 66 0a 2a  k() are one of.*
5b20: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b  * <ul>.** <li> [
5b30: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45  SQLITE_LOCK_NONE
5b40: 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
5b50: 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c  TE_LOCK_SHARED],
5b60: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
5b70: 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c  _LOCK_RESERVED],
5b80: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
5b90: 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20  _LOCK_PENDING], 
5ba0: 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  or.** <li> [SQLI
5bb0: 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56  TE_LOCK_EXCLUSIV
5bc0: 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20  E]..** </ul>.** 
5bd0: 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65 61 73 65  xLock() increase
5be0: 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c  s the lock. xUnl
5bf0: 6f 63 6b 28 29 20 64 65 63 72 65 61 73 65 73 20  ock() decreases 
5c00: 74 68 65 20 6c 6f 63 6b 2e 20 20 0a 2a 2a 20 54  the lock.  .** T
5c10: 68 65 20 78 43 68 65 63 6b 52 65 73 65 72 76 65  he xCheckReserve
5c20: 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20 6c  dLock() method l
5c30: 6f 6f 6b 73 0a 2a 2a 20 74 6f 20 73 65 65 20 69  ooks.** to see i
5c40: 66 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63  f any database c
5c50: 6f 6e 6e 65 63 74 69 6f 6e 2c 20 65 69 74 68 65  onnection, eithe
5c60: 72 20 69 6e 20 74 68 69 73 0a 2a 2a 20 70 72 6f  r in this.** pro
5c70: 63 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20  cess or in some 
5c80: 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69  other process, i
5c90: 73 20 68 6f 6c 64 69 6e 67 20 61 6e 20 52 45 53  s holding an RES
5ca0: 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e  ERVED,.** PENDIN
5cb0: 47 2c 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20  G, or EXCLUSIVE 
5cc0: 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65  lock on the file
5cd0: 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20 74 72  .  It returns tr
5ce0: 75 65 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20  ue.** if such a 
5cf0: 6c 6f 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20  lock exists and 
5d00: 66 61 6c 73 65 20 69 66 20 6e 6f 74 2e 0a 2a 2a  false if not..**
5d10: 20 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f   .** The xFileCo
5d20: 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69  ntrol() method i
5d30: 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65  s a generic inte
5d40: 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77  rface that allow
5d50: 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20  s custom.** VFS 
5d60: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
5d70: 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74  to directly cont
5d80: 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65  rol an open file
5d90: 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73   using the.** [s
5da0: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
5db0: 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65  rol()] interface
5dc0: 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f  .  The second "o
5dd0: 70 22 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 69  p" argument.** i
5de0: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 70 63  s an integer opc
5df0: 6f 64 65 2e 20 20 20 54 68 65 20 74 68 69 72 64  ode.   The third
5e00: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20  .** argument is 
5e10: 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e 74 65  a generic pointe
5e20: 72 20 77 68 69 63 68 20 69 73 20 69 6e 74 65 6e  r which is inten
5e30: 64 65 64 20 74 6f 20 62 65 20 61 20 70 6f 69 6e  ded to be a poin
5e40: 74 65 72 0a 2a 2a 20 74 6f 20 61 20 73 74 72 75  ter.** to a stru
5e50: 63 74 75 72 65 20 74 68 61 74 20 6d 61 79 20 63  cture that may c
5e60: 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e 74 73  ontain arguments
5e70: 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77 68 69   or space in whi
5e80: 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72  ch to.** write r
5e90: 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20 20 50  eturn values.  P
5ea0: 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20 66 6f  otential uses fo
5eb0: 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29  r xFileControl()
5ec0: 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e   might be.** fun
5ed0: 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65  ctions to enable
5ee0: 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20   blocking locks 
5ef0: 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c 20 74  with timeouts, t
5f00: 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20  o change the.** 
5f10: 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65 67 79  locking strategy
5f20: 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f   (for example to
5f30: 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f   use dot-file lo
5f40: 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69 72 65  cks), to inquire
5f50: 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 73 74  .** about the st
5f60: 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20  atus of a lock, 
5f70: 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74 61 6c  or to break stal
5f80: 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53 51  e locks.  The SQ
5f90: 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73  Lite.** core res
5fa0: 65 72 76 65 73 20 6f 70 63 6f 64 65 73 20 6c 65  erves opcodes le
5fb0: 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20  ss than 100 for 
5fc0: 69 74 73 20 6f 77 6e 20 75 73 65 2e 20 0a 2a 2a  its own use. .**
5fd0: 20 41 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c   A [SQLITE_FCNTL
5fe0: 5f 4c 4f 43 4b 53 54 41 54 45 20 7c 20 6c 69 73  _LOCKSTATE | lis
5ff0: 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65  t of opcodes] le
6000: 73 73 20 74 68 61 6e 20 31 30 30 20 69 73 20 61  ss than 100 is a
6010: 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70  vailable..** App
6020: 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64  lications that d
6030: 65 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78  efine a custom x
6040: 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68  FileControl meth
6050: 6f 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70  od should use op
6060: 63 6f 64 65 73 20 0a 2a 2a 20 67 72 65 61 74 65  codes .** greate
6070: 72 20 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76  r than 100 to av
6080: 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e 0a 2a  oid conflicts..*
6090: 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72  *.** The xSector
60a0: 53 69 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65  Size() method re
60b0: 74 75 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72  turns the sector
60c0: 20 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20   size of the.** 
60d0: 64 65 76 69 63 65 20 74 68 61 74 20 75 6e 64 65  device that unde
60e0: 72 6c 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20  rlies the file. 
60f0: 20 54 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65   The sector size
6100: 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d   is the.** minim
6110: 75 6d 20 77 72 69 74 65 20 74 68 61 74 20 63 61  um write that ca
6120: 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77  n be performed w
6130: 69 74 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e  ithout disturbin
6140: 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73  g.** other bytes
6150: 20 69 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54   in the file.  T
6160: 68 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63  he xDeviceCharac
6170: 74 65 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d  teristics().** m
6180: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20  ethod returns a 
6190: 62 69 74 20 76 65 63 74 6f 72 20 64 65 73 63 72  bit vector descr
61a0: 69 62 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20  ibing behaviors 
61b0: 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c  of the.** underl
61c0: 79 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a  ying device:.**.
61d0: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
61e0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
61f0: 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  OMIC].** <li> [S
6200: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6210: 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC512].** <li> [
6220: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6230: 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  MIC1K].** <li> [
6240: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6250: 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  MIC2K].** <li> [
6260: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6270: 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  MIC4K].** <li> [
6280: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6290: 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  MIC8K].** <li> [
62a0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
62b0: 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC16K].** <li> 
62c0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
62d0: 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC32K].** <li>
62e0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
62f0: 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69  TOMIC64K].** <li
6300: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6310: 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20  SAFE_APPEND].** 
6320: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
6330: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a  AP_SEQUENTIAL].*
6340: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68  * </ul>.**.** Th
6350: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6360: 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d  TOMIC property m
6370: 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72  eans that all wr
6380: 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73  ites of.** any s
6390: 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20  ize are atomic. 
63a0: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
63b0: 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75  P_ATOMICnnn valu
63c0: 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20  es.** mean that 
63d0: 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73  writes of blocks
63e0: 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79   that are nnn by
63f0: 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a  tes in size and.
6400: 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74  ** are aligned t
6410: 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69  o an address whi
6420: 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ch is an integer
6430: 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20   multiple of.** 
6440: 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20  nnn are atomic. 
6450: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
6460: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61  P_SAFE_APPEND va
6470: 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61  lue means.** tha
6480: 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61  t when data is a
6490: 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c  ppended to a fil
64a0: 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61  e, the data is a
64b0: 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74  ppended.** first
64c0: 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f   then the size o
64d0: 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78  f the file is ex
64e0: 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68  tended, never th
64f0: 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61  e other.** way a
6500: 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49  round.  The SQLI
6510: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54  TE_IOCAP_SEQUENT
6520: 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61  IAL property mea
6530: 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72  ns that.** infor
6540: 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65  mation is writte
6550: 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65  n to disk in the
6560: 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63   same order as c
6570: 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74  alls.** to xWrit
6580: 65 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  e()..*/.typedef 
6590: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69  struct sqlite3_i
65a0: 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65  o_methods sqlite
65b0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74  3_io_methods;.st
65c0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f  ruct sqlite3_io_
65d0: 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20  methods {.  int 
65e0: 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20  iVersion;.  int 
65f0: 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65  (*xClose)(sqlite
6600: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  3_file*);.  int 
6610: 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74 65 33  (*xRead)(sqlite3
6620: 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69  _file*, void*, i
6630: 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33  nt iAmt, sqlite3
6640: 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20  _int64 iOfst);. 
6650: 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29 28 73   int (*xWrite)(s
6660: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f  qlite3_file*, co
6670: 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69  nst void*, int i
6680: 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  Amt, sqlite3_int
6690: 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74  64 iOfst);.  int
66a0: 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28 73 71   (*xTruncate)(sq
66b0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c  lite3_file*, sql
66c0: 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a 65 29  ite3_int64 size)
66d0: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29  ;.  int (*xSync)
66e0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
66f0: 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e  int flags);.  in
6700: 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29 28 73  t (*xFileSize)(s
6710: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71  qlite3_file*, sq
6720: 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 53 69  lite3_int64 *pSi
6730: 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f  ze);.  int (*xLo
6740: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
6750: 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28  *, int);.  int (
6760: 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65  *xUnlock)(sqlite
6770: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20  3_file*, int);. 
6780: 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52 65 73   int (*xCheckRes
6790: 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74  ervedLock)(sqlit
67a0: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74  e3_file*);.  int
67b0: 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29   (*xFileControl)
67c0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
67d0: 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41  int op, void *pA
67e0: 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65  rg);.  int (*xSe
67f0: 63 74 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65  ctorSize)(sqlite
6800: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  3_file*);.  int 
6810: 28 2a 78 44 65 76 69 63 65 43 68 61 72 61 63 74  (*xDeviceCharact
6820: 65 72 69 73 74 69 63 73 29 28 73 71 6c 69 74 65  eristics)(sqlite
6830: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 41  3_file*);.  /* A
6840: 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64  dditional method
6850: 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69  s may be added i
6860: 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
6870: 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43  s */.};../*.** C
6880: 41 50 49 33 52 45 46 3a 20 53 74 61 6e 64 61 72  API3REF: Standar
6890: 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f  d File Control O
68a0: 70 63 6f 64 65 73 20 7b 46 31 31 33 31 30 7d 0a  pcodes {F11310}.
68b0: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65  **.** These inte
68c0: 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ger constants ar
68d0: 65 20 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68  e opcodes for th
68e0: 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d  e xFileControl m
68f0: 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20  ethod.** of the 
6900: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
6910: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20  ods] object and 
6920: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
6930: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a  file_control()].
6940: 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  ** interface..**
6950: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
6960: 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d  FCNTL_LOCKSTATE]
6970: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
6980: 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20  for debugging.  
6990: 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63  This.** opcode c
69a0: 61 75 73 65 73 20 74 68 65 20 78 46 69 6c 65 43  auses the xFileC
69b0: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f  ontrol method to
69c0: 20 77 72 69 74 65 20 74 68 65 20 63 75 72 72 65   write the curre
69d0: 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74  nt state of.** t
69e0: 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20  he lock (one of 
69f0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e  [SQLITE_LOCK_NON
6a00: 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  E], [SQLITE_LOCK
6a10: 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51  _SHARED],.** [SQ
6a20: 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56  LITE_LOCK_RESERV
6a30: 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  ED], [SQLITE_LOC
6a40: 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b  K_PENDING], or [
6a50: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c  SQLITE_LOCK_EXCL
6a60: 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20  USIVE]).** into 
6a70: 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74 20  an integer that 
6a80: 74 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e  the pArg argumen
6a90: 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69  t points to. Thi
6aa0: 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20  s capability.** 
6ab0: 69 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 74  is used during t
6ac0: 65 73 74 69 6e 67 20 61 6e 64 20 6f 6e 6c 79 20  esting and only 
6ad0: 6e 65 65 64 73 20 74 6f 20 62 65 20 73 75 70 70  needs to be supp
6ae0: 6f 72 74 65 64 20 77 68 65 6e 20 53 51 4c 49 54  orted when SQLIT
6af0: 45 5f 54 45 53 54 0a 2a 2a 20 69 73 20 64 65 66  E_TEST.** is def
6b00: 69 6e 65 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  ined..*/.#define
6b10: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f   SQLITE_FCNTL_LO
6b20: 43 4b 53 54 41 54 45 20 20 20 20 20 20 20 20 31  CKSTATE        1
6b30: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
6b40: 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 20 7b  : Mutex Handle {
6b50: 46 31 37 31 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 68  F17110}.**.** Th
6b60: 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77  e mutex module w
6b70: 69 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66  ithin SQLite def
6b80: 69 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75  ines [sqlite3_mu
6b90: 74 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a  tex] to be an.**
6ba0: 20 61 62 73 74 72 61 63 74 20 74 79 70 65 20 66   abstract type f
6bb0: 6f 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63  or a mutex objec
6bc0: 74 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63  t.  The SQLite c
6bd0: 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a  ore never looks.
6be0: 2a 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e  ** at the intern
6bf0: 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  al representatio
6c00: 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33  n of an [sqlite3
6c10: 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c  _mutex].  It onl
6c20: 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20  y.** deals with 
6c30: 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20  pointers to the 
6c40: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20  [sqlite3_mutex] 
6c50: 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75  object..**.** Mu
6c60: 74 65 78 65 73 20 61 72 65 20 63 72 65 61 74 65  texes are create
6c70: 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
6c80: 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e  _mutex_alloc()].
6c90: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
6ca0: 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ct sqlite3_mutex
6cb0: 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a   sqlite3_mutex;.
6cc0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
6cd0: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 62   OS Interface Ob
6ce0: 6a 65 63 74 20 7b 46 31 31 31 34 30 7d 0a 2a 2a  ject {F11140}.**
6cf0: 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20  .** An instance 
6d00: 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 64  of this object d
6d10: 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72  efines the inter
6d20: 66 61 63 65 20 62 65 74 77 65 65 6e 20 74 68 65  face between the
6d30: 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f 72 65 20  .** SQLite core 
6d40: 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69  and the underlyi
6d50: 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  ng operating sys
6d60: 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a  tem.  The "vfs".
6d70: 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f  ** in the name o
6d80: 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61  f the object sta
6d90: 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c  nds for "virtual
6da0: 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 0a 2a   file system"..*
6db0: 2a 0a 2a 2a 20 54 68 65 20 69 56 65 72 73 69 6f  *.** The iVersio
6dc0: 6e 20 66 69 65 6c 64 20 69 73 20 69 6e 69 74 69  n field is initi
6dd0: 61 6c 6c 79 20 31 20 62 75 74 20 6d 61 79 20 62  ally 1 but may b
6de0: 65 20 6c 61 72 67 65 72 20 66 6f 72 20 66 75 74  e larger for fut
6df0: 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20  ure.** versions 
6e00: 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 64 64 69  of SQLite.  Addi
6e10: 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61  tional fields ma
6e20: 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 74 6f  y be appended to
6e30: 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20   this.** object 
6e40: 77 68 65 6e 20 74 68 65 20 69 56 65 72 73 69 6f  when the iVersio
6e50: 6e 20 76 61 6c 75 65 20 69 73 20 69 6e 63 72 65  n value is incre
6e60: 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ased..**.** The 
6e70: 73 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69  szOsFile field i
6e80: 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  s the size of th
6e90: 65 20 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71  e subclassed [sq
6ea0: 6c 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73  lite3_file].** s
6eb0: 74 72 75 63 74 75 72 65 20 75 73 65 64 20 62 79  tructure used by
6ec0: 20 74 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61   this VFS.  mxPa
6ed0: 74 68 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61  thname is the ma
6ee0: 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a  ximum length of.
6ef0: 2a 2a 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e  ** a pathname in
6f00: 20 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a   this VFS..**.**
6f10: 20 52 65 67 69 73 74 65 72 65 64 20 73 71 6c 69   Registered sqli
6f20: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20  te3_vfs objects 
6f30: 61 72 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69  are kept on a li
6f40: 6e 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64  nked list formed
6f50: 20 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74   by.** the pNext
6f60: 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b   pointer.  The [
6f70: 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69  sqlite3_vfs_regi
6f80: 73 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b  ster()].** and [
6f90: 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65  sqlite3_vfs_unre
6fa0: 67 69 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66  gister()] interf
6fb0: 61 63 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73  aces manage this
6fc0: 20 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68   list.** in a th
6fd0: 72 65 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20  read-safe way.  
6fe0: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  The [sqlite3_vfs
6ff0: 5f 66 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61  _find()] interfa
7000: 63 65 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74  ce.** searches t
7010: 68 65 20 6c 69 73 74 2e 0a 2a 2a 0a 2a 2a 20 54  he list..**.** T
7020: 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20 69  he pNext field i
7030: 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64  s the only field
7040: 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f   in the sqlite3_
7050: 76 66 73 20 0a 2a 2a 20 73 74 72 75 63 74 75 72  vfs .** structur
7060: 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69  e that SQLite wi
7070: 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20  ll ever modify. 
7080: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c   SQLite will onl
7090: 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d  y access.** or m
70a0: 6f 64 69 66 79 20 74 68 69 73 20 66 69 65 6c 64  odify this field
70b0: 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61   while holding a
70c0: 20 70 61 72 74 69 63 75 6c 61 72 20 73 74 61 74   particular stat
70d0: 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65  ic mutex..** The
70e0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
70f0: 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79  uld never modify
7100: 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e   anything within
7110: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   the sqlite3_vfs
7120: 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20  .** object once 
7130: 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62  the object has b
7140: 65 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a  een registered..
7150: 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20  **.** The zName 
7160: 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20  field holds the 
7170: 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20  name of the VFS 
7180: 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d  module.  The nam
7190: 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69  e must.** be uni
71a0: 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56  que across all V
71b0: 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a  FS modules..**.*
71c0: 2a 20 7b 46 31 31 31 34 31 7d 20 53 51 4c 69 74  * {F11141} SQLit
71d0: 65 20 77 69 6c 6c 20 67 75 61 72 61 6e 74 65 65  e will guarantee
71e0: 20 74 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e   that the zFilen
71f0: 61 6d 65 20 73 74 72 69 6e 67 20 70 61 73 73 65  ame string passe
7200: 64 20 74 6f 0a 2a 2a 20 78 4f 70 65 6e 28 29 20  d to.** xOpen() 
7210: 69 73 20 61 20 66 75 6c 6c 20 70 61 74 68 6e 61  is a full pathna
7220: 6d 65 20 61 73 20 67 65 6e 65 72 61 74 65 64 20  me as generated 
7230: 62 79 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65  by xFullPathname
7240: 28 29 20 61 6e 64 0a 2a 2a 20 74 68 61 74 20 74  () and.** that t
7250: 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62  he string will b
7260: 65 20 76 61 6c 69 64 20 61 6e 64 20 75 6e 63 68  e valid and unch
7270: 61 6e 67 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f  anged until xClo
7280: 73 65 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65  se() is.** calle
7290: 64 2e 20 20 7b 45 4e 44 7d 20 53 6f 20 74 68 65  d.  {END} So the
72a0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
72b0: 63 61 6e 20 73 74 6f 72 65 20 61 20 70 6f 69 6e  can store a poin
72c0: 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69  ter to the.** fi
72d0: 6c 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65  lename if it nee
72e0: 64 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74  ds to remember t
72f0: 68 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20  he filename for 
7300: 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 0a  some reason..**.
7310: 2a 2a 20 7b 46 31 31 31 34 32 7d 20 54 68 65 20  ** {F11142} The 
7320: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
7330: 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64  o xOpen() includ
7340: 65 73 20 61 6c 6c 20 62 69 74 73 20 73 65 74 20  es all bits set 
7350: 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 67 73 20  in.** the flags 
7360: 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c  argument to [sql
7370: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e  ite3_open_v2()].
7380: 20 20 4f 72 20 69 66 20 5b 73 71 6c 69 74 65 33    Or if [sqlite3
7390: 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b  _open()].** or [
73a0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
73b0: 5d 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20  ] is used, then 
73c0: 66 6c 61 67 73 20 69 6e 63 6c 75 64 65 73 20 61  flags includes a
73d0: 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49  t least.** [SQLI
73e0: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
73f0: 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45  E] | [SQLITE_OPE
7400: 4e 5f 43 52 45 41 54 45 5d 2e 20 7b 45 4e 44 7d  N_CREATE]. {END}
7410: 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 6f  .** If xOpen() o
7420: 70 65 6e 73 20 61 20 66 69 6c 65 20 72 65 61 64  pens a file read
7430: 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 65  -only then it se
7440: 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f  ts *pOutFlags to
7450: 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c  .** include [SQL
7460: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
7470: 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 74 73 20  Y].  Other bits 
7480: 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61  in *pOutFlags ma
7490: 79 20 62 65 0a 2a 2a 20 73 65 74 2e 0a 2a 2a 20  y be.** set..** 
74a0: 0a 2a 2a 20 7b 46 31 31 31 34 33 7d 20 53 51 4c  .** {F11143} SQL
74b0: 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64  ite will also ad
74c0: 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c  d one of the fol
74d0: 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20  lowing flags to 
74e0: 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63  the xOpen().** c
74f0: 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f  all, depending o
7500: 6e 20 74 68 65 20 6f 62 6a 65 63 74 20 62 65 69  n the object bei
7510: 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a 20 0a 2a  ng opened:.** .*
7520: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20  * <ul>.** <li>  
7530: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49  [SQLITE_OPEN_MAI
7540: 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  N_DB].** <li>  [
7550: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e  SQLITE_OPEN_MAIN
7560: 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69  _JOURNAL].** <li
7570: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
7580: 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e  TEMP_DB].** <li>
7590: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54    [SQLITE_OPEN_T
75a0: 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  EMP_JOURNAL].** 
75b0: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
75c0: 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 5d  EN_TRANSIENT_DB]
75d0: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
75e0: 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41  E_OPEN_SUBJOURNA
75f0: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
7600: 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f  ITE_OPEN_MASTER_
7610: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c  JOURNAL].** </ul
7620: 3e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68  > {END}.**.** Th
7630: 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65  e file I/O imple
7640: 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73  mentation can us
7650: 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70  e the object typ
7660: 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68  e flags to.** ch
7670: 61 6e 67 65 73 20 74 68 65 20 77 61 79 20 69 74  anges the way it
7680: 20 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c 65   deals with file
7690: 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  s.  For example,
76a0: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a   an application.
76b0: 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74  ** that does not
76c0: 20 63 61 72 65 20 61 62 6f 75 74 20 63 72 61 73   care about cras
76d0: 68 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72 6f  h recovery or ro
76e0: 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b  llback might mak
76f0: 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66  e.** the open of
7700: 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20   a journal file 
7710: 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73  a no-op.  Writes
7720: 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c   to this journal
7730: 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62   would.** also b
7740: 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e  e no-ops, and an
7750: 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61  y attempt to rea
7760: 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f  d the journal wo
7770: 75 6c 64 20 72 65 74 75 72 6e 20 0a 2a 2a 20 53  uld return .** S
7780: 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72  QLITE_IOERR.  Or
7790: 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
77a0: 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e  ion might recogn
77b0: 69 7a 65 20 74 68 61 74 20 61 20 64 61 74 61 62  ize that a datab
77c0: 61 73 65 20 0a 2a 2a 20 66 69 6c 65 20 77 69 6c  ase .** file wil
77d0: 6c 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d  l be doing page-
77e0: 61 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72  aligned sector r
77f0: 65 61 64 73 20 61 6e 64 20 77 72 69 74 65 73 20  eads and writes 
7800: 69 6e 20 61 20 72 61 6e 64 6f 6d 20 0a 2a 2a 20  in a random .** 
7810: 6f 72 64 65 72 20 61 6e 64 20 73 65 74 20 75 70  order and set up
7820: 20 69 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74   its I/O subsyst
7830: 65 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a  em accordingly..
7840: 2a 2a 20 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69  ** .** SQLite mi
7850: 67 68 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65  ght also add one
7860: 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   of the followin
7870: 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78  g flags to the x
7880: 4f 70 65 6e 0a 2a 2a 20 6d 65 74 68 6f 64 3a 0a  Open.** method:.
7890: 2a 2a 20 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  ** .** <ul>.** <
78a0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  li> [SQLITE_OPEN
78b0: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a  _DELETEONCLOSE].
78c0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
78d0: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a  OPEN_EXCLUSIVE].
78e0: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 0a 2a 2a 20  ** </ul>.** .** 
78f0: 7b 46 31 31 31 34 35 7d 20 54 68 65 20 5b 53 51  {F11145} The [SQ
7900: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
7910: 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65  ONCLOSE] flag me
7920: 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f  ans the file sho
7930: 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65  uld be.** delete
7940: 64 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f  d when it is clo
7950: 73 65 64 2e 20 20 7b 46 31 31 31 34 36 7d 20 54  sed.  {F11146} T
7960: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
7970: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a  DELETEONCLOSE].*
7980: 2a 20 77 69 6c 6c 20 62 65 20 73 65 74 20 66 6f  * will be set fo
7990: 72 20 54 45 4d 50 20 20 64 61 74 61 62 61 73 65  r TEMP  database
79a0: 73 2c 20 6a 6f 75 72 6e 61 6c 73 20 61 6e 64 20  s, journals and 
79b0: 66 6f 72 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e  for subjournals.
79c0: 20 0a 2a 2a 20 7b 46 31 31 31 34 37 7d 20 54 68   .** {F11147} Th
79d0: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45  e [SQLITE_OPEN_E
79e0: 58 43 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 6d  XCLUSIVE] flag m
79f0: 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68  eans the file sh
7a00: 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 64 0a 2a  ould be opened.*
7a10: 2a 20 66 6f 72 20 65 78 63 6c 75 73 69 76 65 20  * for exclusive 
7a20: 61 63 63 65 73 73 2e 20 20 54 68 69 73 20 66 6c  access.  This fl
7a30: 61 67 20 69 73 20 73 65 74 20 66 6f 72 20 61 6c  ag is set for al
7a40: 6c 20 66 69 6c 65 73 20 65 78 63 65 70 74 0a 2a  l files except.*
7a50: 2a 20 66 6f 72 20 74 68 65 20 6d 61 69 6e 20 64  * for the main d
7a60: 61 74 61 62 61 73 65 20 66 69 6c 65 2e 20 7b 45  atabase file. {E
7a70: 4e 44 7d 0a 2a 2a 20 0a 2a 2a 20 7b 46 31 31 31  ND}.** .** {F111
7a80: 34 38 7d 20 41 74 20 6c 65 61 73 74 20 73 7a 4f  48} At least szO
7a90: 73 46 69 6c 65 20 62 79 74 65 73 20 6f 66 20 6d  sFile bytes of m
7aa0: 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63 61  emory are alloca
7ab0: 74 65 64 20 62 79 20 53 51 4c 69 74 65 20 0a 2a  ted by SQLite .*
7ac0: 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b  * to hold the  [
7ad0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73 74  sqlite3_file] st
7ae0: 72 75 63 74 75 72 65 20 70 61 73 73 65 64 20 61  ructure passed a
7af0: 73 20 74 68 65 20 74 68 69 72 64 20 0a 2a 2a 20  s the third .** 
7b00: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65  argument to xOpe
7b10: 6e 2e 20 20 7b 45 4e 44 7d 20 20 54 68 65 20 78  n.  {END}  The x
7b20: 4f 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73  Open method does
7b30: 20 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20   not have to.** 
7b40: 61 6c 6c 6f 63 61 74 65 20 74 68 65 20 73 74 72  allocate the str
7b50: 75 63 74 75 72 65 3b 20 69 74 20 73 68 6f 75 6c  ucture; it shoul
7b60: 64 20 6a 75 73 74 20 66 69 6c 6c 20 69 74 20 69  d just fill it i
7b70: 6e 2e 0a 2a 2a 20 0a 2a 2a 20 7b 46 31 31 31 34  n..** .** {F1114
7b80: 39 7d 20 54 68 65 20 66 6c 61 67 73 20 61 72 67  9} The flags arg
7b90: 75 6d 65 6e 74 20 74 6f 20 78 41 63 63 65 73 73  ument to xAccess
7ba0: 28 29 20 6d 61 79 20 62 65 20 5b 53 51 4c 49 54  () may be [SQLIT
7bb0: 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 5d  E_ACCESS_EXISTS]
7bc0: 20 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f 72   .** to test for
7bd0: 20 74 68 65 20 65 78 69 73 74 61 6e 63 65 20 6f   the existance o
7be0: 66 20 61 20 66 69 6c 65 2c 0a 2a 2a 20 6f 72 20  f a file,.** or 
7bf0: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52  [SQLITE_ACCESS_R
7c00: 45 41 44 57 52 49 54 45 5d 20 74 6f 20 74 65 73  EADWRITE] to tes
7c10: 74 20 74 6f 20 73 65 65 0a 2a 2a 20 69 66 20 61  t to see.** if a
7c20: 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c   file is readabl
7c30: 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20  e and writable, 
7c40: 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53  or [SQLITE_ACCES
7c50: 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65  S_READ].** to te
7c60: 73 74 20 74 6f 20 73 65 65 20 69 66 20 61 20 66  st to see if a f
7c70: 69 6c 65 20 69 73 20 61 74 20 6c 65 61 73 74 20  ile is at least 
7c80: 72 65 61 64 61 62 6c 65 2e 20 20 7b 45 4e 44 7d  readable.  {END}
7c90: 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65   The file can be
7ca0: 20 61 20 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79   a .** directory
7cb0: 2e 0a 2a 2a 20 0a 2a 2a 20 7b 46 31 31 31 35 30  ..** .** {F11150
7cc0: 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c  } SQLite will al
7cd0: 77 61 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 74  ways allocate at
7ce0: 20 6c 65 61 73 74 20 6d 78 50 61 74 68 6e 61 6d   least mxPathnam
7cf0: 65 2b 31 20 62 79 74 65 73 20 66 6f 72 0a 2a 2a  e+1 bytes for.**
7d00: 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66   the output buff
7d10: 65 72 73 20 66 6f 72 20 78 47 65 74 54 65 6d 70  ers for xGetTemp
7d20: 6e 61 6d 65 20 61 6e 64 20 78 46 75 6c 6c 50 61  name and xFullPa
7d30: 74 68 6e 61 6d 65 2e 20 7b 46 31 31 31 35 31 7d  thname. {F11151}
7d40: 20 54 68 65 20 65 78 61 63 74 0a 2a 2a 20 73 69   The exact.** si
7d50: 7a 65 20 6f 66 20 74 68 65 20 6f 75 74 70 75 74  ze of the output
7d60: 20 62 75 66 66 65 72 20 69 73 20 61 6c 73 6f 20   buffer is also 
7d70: 70 61 73 73 65 64 20 61 73 20 61 20 70 61 72 61  passed as a para
7d80: 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20 0a 2a  meter to both .*
7d90: 2a 20 6d 65 74 68 6f 64 73 2e 20 7b 45 4e 44 7d  * methods. {END}
7da0: 20 49 66 20 74 68 65 20 6f 75 74 70 75 74 20 62   If the output b
7db0: 75 66 66 65 72 20 69 73 20 6e 6f 74 20 6c 61 72  uffer is not lar
7dc0: 67 65 20 65 6e 6f 75 67 68 2c 20 53 51 4c 49 54  ge enough, SQLIT
7dd0: 45 5f 43 41 4e 54 4f 50 45 4e 0a 2a 2a 20 73 68  E_CANTOPEN.** sh
7de0: 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64  ould be returned
7df0: 2e 20 41 73 20 74 68 69 73 20 69 73 20 68 61 6e  . As this is han
7e00: 64 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c 20  dled as a fatal 
7e10: 65 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c  error by SQLite,
7e20: 0a 2a 2a 20 76 66 73 20 69 6d 70 6c 65 6d 65 6e  .** vfs implemen
7e30: 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 65  tations should e
7e40: 6e 64 65 61 76 6f 72 20 74 6f 20 70 72 65 76 65  ndeavor to preve
7e50: 6e 74 20 74 68 69 73 20 62 79 20 73 65 74 74 69  nt this by setti
7e60: 6e 67 20 0a 2a 2a 20 6d 78 50 61 74 68 6e 61 6d  ng .** mxPathnam
7e70: 65 20 74 6f 20 61 20 73 75 66 66 69 63 69 65 6e  e to a sufficien
7e80: 74 6c 79 20 6c 61 72 67 65 20 76 61 6c 75 65 2e  tly large value.
7e90: 0a 2a 2a 20 0a 2a 2a 20 54 68 65 20 78 52 61 6e  .** .** The xRan
7ea0: 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65 65  domness(), xSlee
7eb0: 70 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65 6e  p(), and xCurren
7ec0: 74 54 69 6d 65 28 29 20 69 6e 74 65 72 66 61 63  tTime() interfac
7ed0: 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 73 74  es.** are not st
7ee0: 72 69 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66  rictly a part of
7ef0: 20 74 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c   the filesystem,
7f00: 20 62 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a   but they are.**
7f10: 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65   included in the
7f20: 20 56 46 53 20 73 74 72 75 63 74 75 72 65 20 66   VFS structure f
7f30: 6f 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e  or completeness.
7f40: 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e  .** The xRandomn
7f50: 65 73 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61  ess() function a
7f60: 74 74 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72  ttempts to retur
7f70: 6e 20 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a  n nBytes bytes.*
7f80: 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74  * of good-qualit
7f90: 79 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74  y randomness int
7fa0: 6f 20 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74  o zOut.  The ret
7fb0: 75 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20  urn value is.** 
7fc0: 74 68 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65  the actual numbe
7fd0: 72 20 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61  r of bytes of ra
7fe0: 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65  ndomness obtaine
7ff0: 64 2e 20 20 54 68 65 0a 2a 2a 20 78 53 6c 65 65  d.  The.** xSlee
8000: 70 28 29 20 6d 65 74 68 6f 64 20 63 61 75 73 65  p() method cause
8010: 73 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68  s the calling th
8020: 72 65 61 64 20 74 6f 20 73 6c 65 65 70 20 66 6f  read to sleep fo
8030: 72 20 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68  r at.** least th
8040: 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63 72  e number of micr
8050: 6f 73 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20  oseconds given. 
8060: 20 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d   The xCurrentTim
8070: 65 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65  e().** method re
8080: 74 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44  turns a Julian D
8090: 61 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68  ay Number for th
80a0: 65 20 63 75 72 72 65 6e 74 20 64 61 74 65 20 61  e current date a
80b0: 6e 64 0a 2a 2a 20 74 69 6d 65 2e 0a 2a 2f 0a 74  nd.** time..*/.t
80c0: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
80d0: 6c 69 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65  lite3_vfs sqlite
80e0: 33 5f 76 66 73 3b 0a 73 74 72 75 63 74 20 73 71  3_vfs;.struct sq
80f0: 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e  lite3_vfs {.  in
8100: 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20 20  t iVersion;     
8110: 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63 74         /* Struct
8120: 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62  ure version numb
8130: 65 72 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73  er */.  int szOs
8140: 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20  File;           
8150: 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63   /* Size of subc
8160: 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66  lassed sqlite3_f
8170: 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50  ile */.  int mxP
8180: 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20  athname;        
8190: 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c    /* Maximum fil
81a0: 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74  e pathname lengt
81b0: 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76  h */.  sqlite3_v
81c0: 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20  fs *pNext;      
81d0: 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65 72  /* Next register
81e0: 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73  ed VFS */.  cons
81f0: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20  t char *zName;  
8200: 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20       /* Name of 
8210: 74 68 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c  this virtual fil
8220: 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f  e system */.  vo
8230: 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20  id *pAppData;   
8240: 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65         /* Pointe
8250: 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e  r to application
8260: 2d 73 70 65 63 69 66 69 63 20 64 61 74 61 20 2a  -specific data *
8270: 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29  /.  int (*xOpen)
8280: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
8290: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
82a0: 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  , sqlite3_file*,
82b0: 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
82c0: 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a  int flags, int *
82d0: 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e  pOutFlags);.  in
82e0: 74 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c  t (*xDelete)(sql
82f0: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
8300: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
8310: 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e  t syncDir);.  in
8320: 74 20 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c  t (*xAccess)(sql
8330: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
8340: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
8350: 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20  t flags);.  int 
8360: 28 2a 78 47 65 74 54 65 6d 70 6e 61 6d 65 29 28  (*xGetTempname)(
8370: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e  sqlite3_vfs*, in
8380: 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f  t nOut, char *zO
8390: 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 75  ut);.  int (*xFu
83a0: 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71 6c 69  llPathname)(sqli
83b0: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
83c0: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74  char *zName, int
83d0: 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f 75   nOut, char *zOu
83e0: 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44  t);.  void *(*xD
83f0: 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76  lOpen)(sqlite3_v
8400: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
8410: 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20 76  *zFilename);.  v
8420: 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72 29 28  oid (*xDlError)(
8430: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e  sqlite3_vfs*, in
8440: 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a  t nByte, char *z
8450: 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64 20  ErrMsg);.  void 
8460: 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c 69 74  *(*xDlSym)(sqlit
8470: 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c 20 63  e3_vfs*,void*, c
8480: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 79 6d 62  onst char *zSymb
8490: 6f 6c 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44  ol);.  void (*xD
84a0: 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f  lClose)(sqlite3_
84b0: 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20  vfs*, void*);.  
84c0: 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73  int (*xRandomnes
84d0: 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  s)(sqlite3_vfs*,
84e0: 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72   int nByte, char
84f0: 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28   *zOut);.  int (
8500: 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 74 65 33  *xSleep)(sqlite3
8510: 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f  _vfs*, int micro
8520: 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20  seconds);.  int 
8530: 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 29 28  (*xCurrentTime)(
8540: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f  sqlite3_vfs*, do
8550: 75 62 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4e 65 77  uble*);.  /* New
8560: 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61   fields may be a
8570: 70 70 65 6e 64 65 64 20 69 6e 20 66 69 67 75 72  ppended in figur
8580: 65 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65  e versions.  The
8590: 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76   iVersion.  ** v
85a0: 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d  alue will increm
85b0: 65 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68 69  ent whenever thi
85c0: 73 20 68 61 70 70 65 6e 73 2e 20 2a 2f 0a 7d 3b  s happens. */.};
85d0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
85e0: 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20  : Flags for the 
85f0: 78 41 63 63 65 73 73 20 56 46 53 20 6d 65 74 68  xAccess VFS meth
8600: 6f 64 20 7b 46 31 31 31 39 30 7d 0a 2a 2a 0a 2a  od {F11190}.**.*
8610: 2a 20 7b 46 31 31 31 39 31 7d 20 54 68 65 73 65  * {F11191} These
8620: 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e   integer constan
8630: 74 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 61  ts can be used a
8640: 73 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  s the third para
8650: 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20  meter to.** the 
8660: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 6f  xAccess method o
8670: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66  f an [sqlite3_vf
8680: 73 5d 20 6f 62 6a 65 63 74 2e 20 7b 45 4e 44 7d  s] object. {END}
8690: 20 20 54 68 65 79 20 64 65 74 65 72 6d 69 6e 65    They determine
86a0: 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f 66  .** what kind of
86b0: 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 68 65   permissions the
86c0: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20   xAccess method 
86d0: 69 73 0a 2a 2a 20 6c 6f 6f 6b 69 6e 67 20 66 6f  is.** looking fo
86e0: 72 2e 20 20 7b 46 31 31 31 39 32 7d 20 57 69 74  r.  {F11192} Wit
86f0: 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  h SQLITE_ACCESS_
8700: 45 58 49 53 54 53 2c 20 74 68 65 20 78 41 63 63  EXISTS, the xAcc
8710: 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69  ess method.** si
8720: 6d 70 6c 79 20 63 68 65 63 6b 73 20 74 6f 20 73  mply checks to s
8730: 65 65 20 69 66 20 74 68 65 20 66 69 6c 65 20 65  ee if the file e
8740: 78 69 73 74 73 2e 20 7b 46 31 31 31 39 33 7d 20  xists. {F11193} 
8750: 57 69 74 68 0a 2a 2a 20 53 51 4c 49 54 45 5f 41  With.** SQLITE_A
8760: 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 2c  CCESS_READWRITE,
8770: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
8780: 68 6f 64 20 63 68 65 63 6b 73 20 74 6f 20 73 65  hod checks to se
8790: 65 0a 2a 2a 20 69 66 20 74 68 65 20 66 69 6c 65  e.** if the file
87a0: 20 69 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c   is both readabl
87b0: 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2e 20  e and writable. 
87c0: 20 7b 46 31 31 31 39 34 7d 20 57 69 74 68 0a 2a   {F11194} With.*
87d0: 2a 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  * SQLITE_ACCESS_
87e0: 52 45 41 44 20 74 68 65 20 78 41 63 63 65 73 73  READ the xAccess
87f0: 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b   method.** check
8800: 73 20 74 6f 20 73 65 65 20 69 66 20 74 68 65 20  s to see if the 
8810: 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65  file is readable
8820: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
8830: 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54  ITE_ACCESS_EXIST
8840: 53 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53  S    0.#define S
8850: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
8860: 44 57 52 49 54 45 20 31 0a 23 64 65 66 69 6e 65  DWRITE 1.#define
8870: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
8880: 45 41 44 20 20 20 20 20 20 32 0a 0a 2f 2a 0a 2a  EAD      2../*.*
8890: 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62  * CAPI3REF: Enab
88a0: 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78  le Or Disable Ex
88b0: 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f  tended Result Co
88c0: 64 65 73 20 7b 46 31 32 32 30 30 7d 0a 2a 2a 0a  des {F12200}.**.
88d0: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65  ** The sqlite3_e
88e0: 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63  xtended_result_c
88f0: 6f 64 65 73 28 29 20 72 6f 75 74 69 6e 65 20 65  odes() routine e
8900: 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c  nables or disabl
8910: 65 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  es the.** [SQLIT
8920: 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 65  E_IOERR_READ | e
8930: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
8940: 6f 64 65 73 5d 20 66 65 61 74 75 72 65 20 6f 66  odes] feature of
8950: 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 54 68 65 20   SQLite..** The 
8960: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
8970: 63 6f 64 65 73 20 61 72 65 20 64 69 73 61 62 6c  codes are disabl
8980: 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 66 6f  ed by default fo
8990: 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20  r historical.** 
89a0: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a  compatibility..*
89b0: 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
89c0: 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 30 31 7d 20  .**.** {F12201} 
89d0: 45 61 63 68 20 6e 65 77 20 5b 64 61 74 61 62 61  Each new [databa
89e0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68  se connection] h
89f0: 61 73 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 20  as the .**      
8a00: 20 20 20 20 5b 65 78 74 65 6e 64 65 64 20 72 65      [extended re
8a10: 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74  sult codes] feat
8a20: 75 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ure.**          
8a30: 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
8a40: 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32  ult..**.** {F122
8a50: 30 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  02} The [sqlite3
8a60: 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74  _extended_result
8a70: 5f 63 6f 64 65 73 28 44 2c 46 29 5d 20 69 6e 74  _codes(D,F)] int
8a80: 65 72 66 61 63 65 20 77 69 6c 6c 20 65 6e 61 62  erface will enab
8a90: 6c 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  le.**          [
8aa0: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
8ab0: 63 6f 64 65 73 5d 20 66 6f 72 20 74 68 65 20 0a  codes] for the .
8ac0: 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61 74  **          [dat
8ad0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
8ae0: 5d 20 44 20 69 66 20 74 68 65 20 46 20 70 61 72  ] D if the F par
8af0: 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20 20 20  ameter.**       
8b00: 20 20 20 69 73 20 74 72 75 65 2c 20 6f 72 20 64     is true, or d
8b10: 69 73 61 62 6c 65 20 74 68 65 6d 20 69 66 20 46  isable them if F
8b20: 20 69 73 20 66 61 6c 73 65 2e 0a 2a 2f 0a 69 6e   is false..*/.in
8b30: 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64  t sqlite3_extend
8b40: 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28  ed_result_codes(
8b50: 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e  sqlite3*, int on
8b60: 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  off);../*.** CAP
8b70: 49 33 52 45 46 3a 20 4c 61 73 74 20 49 6e 73 65  I3REF: Last Inse
8b80: 72 74 20 52 6f 77 69 64 20 7b 46 31 32 32 32 30  rt Rowid {F12220
8b90: 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 65 6e 74  }.**.** Each ent
8ba0: 72 79 20 69 6e 20 61 6e 20 53 51 4c 69 74 65 20  ry in an SQLite 
8bb0: 74 61 62 6c 65 20 68 61 73 20 61 20 75 6e 69 71  table has a uniq
8bc0: 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  ue 64-bit signed
8bd0: 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20  .** integer key 
8be0: 63 61 6c 6c 65 64 20 74 68 65 20 22 72 6f 77 69  called the "rowi
8bf0: 64 22 2e 20 54 68 65 20 72 6f 77 69 64 20 69 73  d". The rowid is
8c00: 20 61 6c 77 61 79 73 20 61 76 61 69 6c 61 62 6c   always availabl
8c10: 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65 63  e.** as an undec
8c20: 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d  lared column nam
8c30: 65 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f  ed ROWID, OID, o
8c40: 72 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e  r _ROWID_ as lon
8c50: 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61  g as those.** na
8c60: 6d 65 73 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f  mes are not also
8c70: 20 75 73 65 64 20 62 79 20 65 78 70 6c 69 63 69   used by explici
8c80: 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c  tly declared col
8c90: 75 6d 6e 73 2e 20 49 66 0a 2a 2a 20 74 68 65 20  umns. If.** the 
8ca0: 74 61 62 6c 65 20 68 61 73 20 61 20 63 6f 6c 75  table has a colu
8cb0: 6d 6e 20 6f 66 20 74 79 70 65 20 49 4e 54 45 47  mn of type INTEG
8cc0: 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 20 74  ER PRIMARY KEY t
8cd0: 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a  hen that column.
8ce0: 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6c  ** is another al
8cf0: 69 61 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69  ias for the rowi
8d00: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  d..**.** This ro
8d10: 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
8d20: 65 20 72 6f 77 69 64 20 6f 66 20 74 68 65 20 6d  e rowid of the m
8d30: 6f 73 74 20 72 65 63 65 6e 74 0a 2a 2a 20 73 75  ost recent.** su
8d40: 63 63 65 73 73 66 75 6c 20 49 4e 53 45 52 54 20  ccessful INSERT 
8d50: 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  into the databas
8d60: 65 20 66 72 6f 6d 20 74 68 65 20 64 61 74 61 62  e from the datab
8d70: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
8d80: 2a 20 73 68 6f 77 6e 20 69 6e 20 74 68 65 20 66  * shown in the f
8d90: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 20 20  irst argument.  
8da0: 49 66 20 6e 6f 20 73 75 63 63 65 73 73 66 75 6c  If no successful
8db0: 20 69 6e 73 65 72 74 73 0a 2a 2a 20 68 61 76 65   inserts.** have
8dc0: 20 65 76 65 72 20 6f 63 63 75 72 72 65 64 20 6f   ever occurred o
8dd0: 6e 20 74 68 69 73 20 64 61 74 61 62 61 73 65 20  n this database 
8de0: 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 7a 65 72 6f  connection, zero
8df0: 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
8e00: 0a 2a 2a 20 49 66 20 61 6e 20 49 4e 53 45 52 54  .** If an INSERT
8e10: 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61   occurs within a
8e20: 20 74 72 69 67 67 65 72 2c 20 74 68 65 6e 20 74   trigger, then t
8e30: 68 65 20 72 6f 77 69 64 20 6f 66 20 74 68 65 0a  he rowid of the.
8e40: 2a 2a 20 69 6e 73 65 72 74 65 64 20 72 6f 77 20  ** inserted row 
8e50: 69 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  is returned by t
8e60: 68 69 73 20 72 6f 75 74 69 6e 65 20 61 73 20 6c  his routine as l
8e70: 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69 67 67  ong as the trigg
8e80: 65 72 0a 2a 2a 20 69 73 20 72 75 6e 6e 69 6e 67  er.** is running
8e90: 2e 20 20 42 75 74 20 6f 6e 63 65 20 74 68 65 20  .  But once the 
8ea0: 74 72 69 67 67 65 72 20 74 65 72 6d 69 6e 61 74  trigger terminat
8eb0: 65 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65  es, the value re
8ec0: 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 74 68 69  turned.** by thi
8ed0: 73 20 72 6f 75 74 69 6e 65 20 72 65 76 65 72 74  s routine revert
8ee0: 73 20 74 6f 20 74 68 65 20 6c 61 73 74 20 76 61  s to the last va
8ef0: 6c 75 65 20 69 6e 73 65 72 74 65 64 20 62 65 66  lue inserted bef
8f00: 6f 72 65 20 74 68 65 0a 2a 2a 20 74 72 69 67 67  ore the.** trigg
8f10: 65 72 20 66 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  er fired..**.** 
8f20: 41 6e 20 49 4e 53 45 52 54 20 74 68 61 74 20 66  An INSERT that f
8f30: 61 69 6c 73 20 64 75 65 20 74 6f 20 61 20 63 6f  ails due to a co
8f40: 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69  nstraint violati
8f50: 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73  on is not a.** s
8f60: 75 63 63 65 73 73 66 75 6c 20 69 6e 73 65 72 74  uccessful insert
8f70: 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68   and does not ch
8f80: 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20 72  ange the value r
8f90: 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a  eturned by this.
8fa0: 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20 54 68 75  ** routine.  Thu
8fb0: 73 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49 4c  s INSERT OR FAIL
8fc0: 2c 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f  , INSERT OR IGNO
8fd0: 52 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 4f  RE, INSERT OR RO
8fe0: 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49  LLBACK,.** and I
8ff0: 4e 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20 6d  NSERT OR ABORT m
9000: 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 74  ake no changes t
9010: 6f 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  o the return val
9020: 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f  ue of this.** ro
9030: 75 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69 72  utine when their
9040: 20 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 73   insertion fails
9050: 2e 20 20 57 68 65 6e 20 49 4e 53 45 52 54 20 4f  .  When INSERT O
9060: 52 20 52 45 50 4c 41 43 45 20 0a 2a 2a 20 65 6e  R REPLACE .** en
9070: 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 74  counters a const
9080: 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c  raint violation,
9090: 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 69   it does not fai
90a0: 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52  l.  The.** INSER
90b0: 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63  T continues to c
90c0: 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 20  ompletion after 
90d0: 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 68  deleting rows th
90e0: 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 65  at caused.** the
90f0: 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f 62   constraint prob
9100: 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f 52  lem so INSERT OR
9110: 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c   REPLACE will al
9120: 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74  ways change.** t
9130: 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
9140: 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  of this interfac
9150: 65 2e 20 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 74 68  e. .**.** For th
9160: 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68  e purposes of th
9170: 69 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 69  is routine, an i
9180: 6e 73 65 72 74 20 69 73 20 63 6f 6e 73 69 64 65  nsert is conside
9190: 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63  red to.** be suc
91a0: 63 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20  cessful even if 
91b0: 69 74 20 69 73 20 73 75 62 73 65 71 75 65 6e 74  it is subsequent
91c0: 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a  ly rolled back..
91d0: 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
91e0: 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 32 31 7d  :.**.** {F12221}
91f0: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61   The [sqlite3_la
9200: 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
9210: 29 5d 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  )] function retu
9220: 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  rns the.**      
9230: 20 20 20 20 72 6f 77 69 64 20 6f 66 20 74 68 65      rowid of the
9240: 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 75 63   most recent suc
9250: 63 65 73 73 66 75 6c 20 69 6e 73 65 72 74 20 64  cessful insert d
9260: 6f 6e 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  one.**          
9270: 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  on the same data
9280: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
9290: 61 6e 64 20 77 69 74 68 69 6e 20 74 68 65 20 73  and within the s
92a0: 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ame.**          
92b0: 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2c  trigger context,
92c0: 20 6f 72 20 7a 65 72 6f 20 69 66 20 74 68 65 72   or zero if ther
92d0: 65 20 68 61 76 65 0a 2a 2a 20 20 20 20 20 20 20  e have.**       
92e0: 20 20 20 62 65 65 6e 20 6e 6f 20 71 75 61 6c 69     been no quali
92f0: 66 79 69 6e 67 20 69 6e 73 65 72 74 73 20 6f 6e  fying inserts on
9300: 20 74 68 61 74 20 63 6f 6e 6e 65 63 74 69 6f 6e   that connection
9310: 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 32 33 7d  ..**.** {F12223}
9320: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61   The [sqlite3_la
9330: 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
9340: 29 5d 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  )] function retu
9350: 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  rns.**          
9360: 73 61 6d 65 20 76 61 6c 75 65 20 77 68 65 6e 20  same value when 
9370: 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
9380: 73 61 6d 65 20 74 72 69 67 67 65 72 20 63 6f 6e  same trigger con
9390: 74 65 78 74 0a 2a 2a 20 20 20 20 20 20 20 20 20  text.**         
93a0: 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 62 65 66   immediately bef
93b0: 6f 72 65 20 61 6e 64 20 61 66 74 65 72 20 61 20  ore and after a 
93c0: 52 4f 4c 4c 42 41 43 4b 2e 0a 2a 2a 0a 2a 2a 20  ROLLBACK..**.** 
93d0: 4c 49 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a  LIMITATIONS:.**.
93e0: 2a 2a 20 7b 55 31 32 32 33 32 7d 20 49 66 20 61  ** {U12232} If a
93f0: 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64   separate thread
9400: 20 64 6f 65 73 20 61 20 6e 65 77 20 69 6e 73 65   does a new inse
9410: 72 74 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a  rt on the same.*
9420: 2a 20 20 20 20 20 20 20 20 20 20 64 61 74 61 62  *          datab
9430: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77  ase connection w
9440: 68 69 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65  hile the [sqlite
9450: 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
9460: 77 69 64 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20  wid()].**       
9470: 20 20 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72     function is r
9480: 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20  unning and thus 
9490: 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74  changes the last
94a0: 20 69 6e 73 65 72 74 20 72 6f 77 69 64 2c 0a 2a   insert rowid,.*
94b0: 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20  *          then 
94c0: 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
94d0: 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c  ed by [sqlite3_l
94e0: 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
94f0: 28 29 5d 20 69 73 0a 2a 2a 20 20 20 20 20 20 20  ()] is.**       
9500: 20 20 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65     unpredictable
9510: 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65   and might not e
9520: 71 75 61 6c 20 65 69 74 68 65 72 20 74 68 65 20  qual either the 
9530: 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a  old or the new.*
9540: 2a 20 20 20 20 20 20 20 20 20 20 6c 61 73 74 20  *          last 
9550: 69 6e 73 65 72 74 20 72 6f 77 69 64 2e 0a 2a 2f  insert rowid..*/
9560: 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
9570: 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
9580: 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33  rt_rowid(sqlite3
9590: 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
95a0: 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e  REF: Count The N
95b0: 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f  umber Of Rows Mo
95c0: 64 69 66 69 65 64 20 7b 46 31 32 32 34 30 7d 0a  dified {F12240}.
95d0: 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74  **.** This funct
95e0: 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  ion returns the 
95f0: 6e 75 6d 62 65 72 20 6f 66 20 64 61 74 61 62 61  number of databa
9600: 73 65 20 72 6f 77 73 20 74 68 61 74 20 77 65 72  se rows that wer
9610: 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 6f 72 20  e changed.** or 
9620: 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65  inserted or dele
9630: 74 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20  ted by the most 
9640: 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74  recently complet
9650: 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ed SQL statement
9660: 0a 2a 2a 20 6f 6e 20 74 68 65 20 63 6f 6e 6e 65  .** on the conne
9670: 63 74 69 6f 6e 20 73 70 65 63 69 66 69 65 64 20  ction specified 
9680: 62 79 20 74 68 65 20 66 69 72 73 74 20 70 61 72  by the first par
9690: 61 6d 65 74 65 72 2e 20 20 4f 6e 6c 79 0a 2a 2a  ameter.  Only.**
96a0: 20 63 68 61 6e 67 65 73 20 74 68 61 74 20 61 72   changes that ar
96b0: 65 20 64 69 72 65 63 74 6c 79 20 73 70 65 63 69  e directly speci
96c0: 66 69 65 64 20 62 79 20 74 68 65 20 49 4e 53 45  fied by the INSE
96d0: 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 0a 2a  RT, UPDATE, or.*
96e0: 2a 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65  * DELETE stateme
96f0: 6e 74 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 20  nt are counted. 
9700: 20 41 75 78 69 6c 69 61 72 79 20 63 68 61 6e 67   Auxiliary chang
9710: 65 73 20 63 61 75 73 65 64 20 62 79 0a 2a 2a 20  es caused by.** 
9720: 74 72 69 67 67 65 72 73 20 61 72 65 20 6e 6f 74  triggers are not
9730: 20 63 6f 75 6e 74 65 64 2e 20 55 73 65 20 74 68   counted. Use th
9740: 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  e [sqlite3_total
9750: 5f 63 68 61 6e 67 65 73 28 29 5d 20 66 75 6e 63  _changes()] func
9760: 74 69 6f 6e 0a 2a 2a 20 74 6f 20 66 69 6e 64 20  tion.** to find 
9770: 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72  the total number
9780: 20 6f 66 20 63 68 61 6e 67 65 73 20 69 6e 63 6c   of changes incl
9790: 75 64 69 6e 67 20 63 68 61 6e 67 65 73 20 63 61  uding changes ca
97a0: 75 73 65 64 20 62 79 20 74 72 69 67 67 65 72 73  used by triggers
97b0: 2e 0a 2a 2a 0a 2a 2a 20 41 20 22 72 6f 77 20 63  ..**.** A "row c
97c0: 68 61 6e 67 65 22 20 69 73 20 61 20 63 68 61 6e  hange" is a chan
97d0: 67 65 20 74 6f 20 61 20 73 69 6e 67 6c 65 20 72  ge to a single r
97e0: 6f 77 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 74  ow of a single t
97f0: 61 62 6c 65 0a 2a 2a 20 63 61 75 73 65 64 20 62  able.** caused b
9800: 79 20 61 6e 20 49 4e 53 45 52 54 2c 20 44 45 4c  y an INSERT, DEL
9810: 45 54 45 2c 20 6f 72 20 55 50 44 41 54 45 20 73  ETE, or UPDATE s
9820: 74 61 74 65 6d 65 6e 74 2e 20 20 52 6f 77 73 20  tatement.  Rows 
9830: 74 68 61 74 0a 2a 2a 20 61 72 65 20 63 68 61 6e  that.** are chan
9840: 67 65 64 20 61 73 20 73 69 64 65 20 65 66 66 65  ged as side effe
9850: 63 74 73 20 6f 66 20 52 45 50 4c 41 43 45 20 63  cts of REPLACE c
9860: 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75  onstraint resolu
9870: 74 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63  tion,.** rollbac
9880: 6b 2c 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73  k, ABORT process
9890: 69 6e 67 2c 20 44 52 4f 50 20 54 41 42 4c 45 2c  ing, DROP TABLE,
98a0: 20 6f 72 20 62 79 20 61 6e 79 20 6f 74 68 65 72   or by any other
98b0: 0a 2a 2a 20 6d 65 63 68 61 6e 69 73 6d 73 20 64  .** mechanisms d
98c0: 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 64  o not count as d
98d0: 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65  irect row change
98e0: 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72 69 67  s..**.** A "trig
98f0: 67 65 72 20 63 6f 6e 74 65 78 74 22 20 69 73 20  ger context" is 
9900: 61 20 73 63 6f 70 65 20 6f 66 20 65 78 65 63 75  a scope of execu
9910: 74 69 6f 6e 20 74 68 61 74 20 62 65 67 69 6e 73  tion that begins
9920: 20 61 6e 64 0a 2a 2a 20 65 6e 64 73 20 77 69 74   and.** ends wit
9930: 68 20 74 68 65 20 73 63 72 69 70 74 20 6f 66 20  h the script of 
9940: 61 20 74 72 69 67 67 65 72 2e 20 20 4d 6f 73 74  a trigger.  Most
9950: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
9960: 61 72 65 0a 2a 2a 20 65 76 61 6c 75 61 74 65 64  are.** evaluated
9970: 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 79 20   outside of any 
9980: 74 72 69 67 67 65 72 2e 20 20 54 68 69 73 20 69  trigger.  This i
9990: 73 20 74 68 65 20 22 74 6f 70 20 6c 65 76 65 6c  s the "top level
99a0: 22 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e  ".** trigger con
99b0: 74 65 78 74 2e 20 20 49 66 20 61 20 74 72 69 67  text.  If a trig
99c0: 67 65 72 20 66 69 72 65 73 20 66 72 6f 6d 20 74  ger fires from t
99d0: 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 61 0a  he top level, a.
99e0: 2a 2a 20 6e 65 77 20 74 72 69 67 67 65 72 20 63  ** new trigger c
99f0: 6f 6e 74 65 78 74 20 69 73 20 65 6e 74 65 72 65  ontext is entere
9a00: 64 20 66 6f 72 20 74 68 65 20 64 75 72 61 74 69  d for the durati
9a10: 6f 6e 20 6f 66 20 74 68 61 74 20 6f 6e 65 0a 2a  on of that one.*
9a20: 2a 20 74 72 69 67 67 65 72 2e 20 20 53 75 62 74  * trigger.  Subt
9a30: 72 69 67 67 65 72 73 20 63 72 65 61 74 65 20 73  riggers create s
9a40: 75 62 63 6f 6e 74 65 78 74 73 20 66 6f 72 20 74  ubcontexts for t
9a50: 68 65 69 72 20 64 75 72 61 74 69 6f 6e 2e 0a 2a  heir duration..*
9a60: 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20 5b 73 71  *.** Calling [sq
9a70: 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 6f 72  lite3_exec()] or
9a80: 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
9a90: 5d 20 72 65 63 75 72 73 69 76 65 6c 79 20 64 6f  ] recursively do
9aa0: 65 73 0a 2a 2a 20 6e 6f 74 20 63 72 65 61 74 65  es.** not create
9ab0: 20 61 20 6e 65 77 20 74 72 69 67 67 65 72 20 63   a new trigger c
9ac0: 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  ontext..**.** Th
9ad0: 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  is function retu
9ae0: 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
9af0: 66 20 64 69 72 65 63 74 20 72 6f 77 20 63 68 61  f direct row cha
9b00: 6e 67 65 73 20 69 6e 20 74 68 65 0a 2a 2a 20 6d  nges in the.** m
9b10: 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52  ost recent INSER
9b20: 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45  T, UPDATE, or DE
9b30: 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77  LETE statement w
9b40: 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 0a 2a  ithin the same.*
9b50: 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78  * trigger contex
9b60: 74 2e 0a 2a 2a 0a 2a 2a 20 53 6f 20 77 68 65 6e  t..**.** So when
9b70: 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
9b80: 20 74 6f 70 20 6c 65 76 65 6c 2c 20 74 68 69 73   top level, this
9b90: 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
9ba0: 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  s the.** number 
9bb0: 6f 66 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68  of changes in th
9bc0: 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e  e most recent IN
9bd0: 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72  SERT, UPDATE, or
9be0: 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20   DELETE.** that 
9bf0: 61 6c 73 6f 20 6f 63 63 75 72 72 65 64 20 61 74  also occurred at
9c00: 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2e 0a   the top level..
9c10: 2a 2a 20 57 69 74 68 69 6e 20 74 68 65 20 62 6f  ** Within the bo
9c20: 64 79 20 6f 66 20 61 20 74 72 69 67 67 65 72 2c  dy of a trigger,
9c30: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61   the sqlite3_cha
9c40: 6e 67 65 73 28 29 20 69 6e 74 65 72 66 61 63 65  nges() interface
9c50: 0a 2a 2a 20 63 61 6e 20 62 65 20 63 61 6c 6c 65  .** can be calle
9c60: 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75  d to find the nu
9c70: 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 6e 67  mber of.** chang
9c80: 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72  es in the most r
9c90: 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65  ecently complete
9ca0: 64 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  d INSERT, UPDATE
9cb0: 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73  , or DELETE.** s
9cc0: 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20  tatement within 
9cd0: 74 68 65 20 62 6f 64 79 20 6f 66 20 74 68 65 20  the body of the 
9ce0: 73 61 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a  same trigger..**
9cf0: 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 6e 75   However, the nu
9d00: 6d 62 65 72 20 72 65 74 75 72 6e 65 64 20 64 6f  mber returned do
9d10: 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 69  es not include i
9d20: 6e 20 63 68 61 6e 67 65 73 0a 2a 2a 20 63 61 75  n changes.** cau
9d30: 73 65 64 20 62 79 20 73 75 62 74 72 69 67 67 65  sed by subtrigge
9d40: 72 73 20 73 69 6e 63 65 20 74 68 65 79 20 68 61  rs since they ha
9d50: 76 65 20 74 68 65 69 72 20 6f 77 6e 20 63 6f 6e  ve their own con
9d60: 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  text..**.** SQLi
9d70: 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68  te implements th
9d80: 65 20 63 6f 6d 6d 61 6e 64 20 22 44 45 4c 45 54  e command "DELET
9d90: 45 20 46 52 4f 4d 20 74 61 62 6c 65 22 20 77 69  E FROM table" wi
9da0: 74 68 6f 75 74 0a 2a 2a 20 61 20 57 48 45 52 45  thout.** a WHERE
9db0: 20 63 6c 61 75 73 65 20 62 79 20 64 72 6f 70 70   clause by dropp
9dc0: 69 6e 67 20 61 6e 64 20 72 65 63 72 65 61 74 69  ing and recreati
9dd0: 6e 67 20 74 68 65 20 74 61 62 6c 65 2e 20 20 28  ng the table.  (
9de0: 54 68 69 73 20 69 73 20 6d 75 63 68 0a 2a 2a 20  This is much.** 
9df0: 66 61 73 74 65 72 20 74 68 61 6e 20 67 6f 69 6e  faster than goin
9e00: 67 20 74 68 72 6f 75 67 68 20 61 6e 64 20 64 65  g through and de
9e10: 6c 65 74 69 6e 67 20 69 6e 64 69 76 69 64 75 61  leting individua
9e20: 6c 20 65 6c 65 6d 65 6e 74 73 20 66 72 6f 6d 20  l elements from 
9e30: 74 68 65 0a 2a 2a 20 74 61 62 6c 65 2e 29 20 20  the.** table.)  
9e40: 42 65 63 61 75 73 65 20 6f 66 20 74 68 69 73 20  Because of this 
9e50: 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 2c 20 74 68  optimization, th
9e60: 65 20 64 65 6c 65 74 69 6f 6e 73 20 69 6e 0a 2a  e deletions in.*
9e70: 2a 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74  * "DELETE FROM t
9e80: 61 62 6c 65 22 20 61 72 65 20 6e 6f 74 20 72 6f  able" are not ro
9e90: 77 20 63 68 61 6e 67 65 73 20 61 6e 64 20 77 69  w changes and wi
9ea0: 6c 6c 20 6e 6f 74 20 62 65 20 63 6f 75 6e 74 65  ll not be counte
9eb0: 64 0a 2a 2a 20 62 79 20 74 68 65 20 73 71 6c 69  d.** by the sqli
9ec0: 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 6f 72  te3_changes() or
9ed0: 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f   [sqlite3_total_
9ee0: 63 68 61 6e 67 65 73 28 29 5d 20 66 75 6e 63 74  changes()] funct
9ef0: 69 6f 6e 73 2e 0a 2a 2a 20 54 6f 20 67 65 74 20  ions..** To get 
9f00: 61 6e 20 61 63 63 75 72 61 74 65 20 63 6f 75 6e  an accurate coun
9f10: 74 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20  t of the number 
9f20: 6f 66 20 72 6f 77 73 20 64 65 6c 65 74 65 64 2c  of rows deleted,
9f30: 20 75 73 65 0a 2a 2a 20 22 44 45 4c 45 54 45 20   use.** "DELETE 
9f40: 46 52 4f 4d 20 74 61 62 6c 65 20 57 48 45 52 45  FROM table WHERE
9f50: 20 31 22 20 69 6e 73 74 65 61 64 2e 0a 2a 2a 0a   1" instead..**.
9f60: 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
9f70: 2a 0a 2a 2a 20 7b 46 31 32 32 34 31 7d 20 54 68  *.** {F12241} Th
9f80: 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  e [sqlite3_chang
9f90: 65 73 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 72  es()] function r
9fa0: 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
9fb0: 72 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20  r of.**         
9fc0: 20 72 6f 77 20 63 68 61 6e 67 65 73 20 63 61 75   row changes cau
9fd0: 73 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20  sed by the most 
9fe0: 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55  recent INSERT, U
9ff0: 50 44 41 54 45 2c 0a 2a 2a 20 20 20 20 20 20 20  PDATE,.**       
a000: 20 20 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61     or DELETE sta
a010: 74 65 6d 65 6e 74 20 6f 6e 20 74 68 65 20 73 61  tement on the sa
a020: 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
a030: 65 63 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 20 20  ection and.**   
a040: 20 20 20 20 20 20 20 77 69 74 68 69 6e 20 74 68         within th
a050: 65 20 73 61 6d 65 20 74 72 69 67 67 65 72 20 63  e same trigger c
a060: 6f 6e 74 65 78 74 2c 20 6f 72 20 7a 65 72 6f 20  ontext, or zero 
a070: 69 66 20 74 68 65 72 65 20 68 61 76 65 0a 2a 2a  if there have.**
a080: 20 20 20 20 20 20 20 20 20 20 6e 6f 74 20 62 65            not be
a090: 65 6e 20 61 6e 79 20 71 75 61 6c 69 66 79 69 6e  en any qualifyin
a0a0: 67 20 72 6f 77 20 63 68 61 6e 67 65 73 2e 0a 2a  g row changes..*
a0b0: 2a 0a 2a 2a 20 4c 49 4d 49 54 41 54 49 4f 4e 53  *.** LIMITATIONS
a0c0: 3a 0a 2a 2a 0a 2a 2a 20 7b 55 31 32 32 35 32 7d  :.**.** {U12252}
a0d0: 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74   If a separate t
a0e0: 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e  hread makes chan
a0f0: 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  ges on the same 
a100: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
a110: 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ion.**          
a120: 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63  while [sqlite3_c
a130: 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e  hanges()] is run
a140: 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61  ning then the va
a150: 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  lue returned.** 
a160: 20 20 20 20 20 20 20 20 20 69 73 20 75 6e 70 72           is unpr
a170: 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 75 6e  edictable and un
a180: 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69  meaningful..*/.i
a190: 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  nt sqlite3_chang
a1a0: 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  es(sqlite3*);../
a1b0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
a1c0: 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52  otal Number Of R
a1d0: 6f 77 73 20 4d 6f 64 69 66 69 65 64 20 7b 46 31  ows Modified {F1
a1e0: 32 32 36 30 7d 0a 2a 2a 2a 0a 2a 2a 20 54 68 69  2260}.***.** Thi
a1f0: 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  s function retur
a200: 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
a210: 20 72 6f 77 20 63 68 61 6e 67 65 73 20 63 61 75   row changes cau
a220: 73 65 64 0a 2a 2a 20 62 79 20 49 4e 53 45 52 54  sed.** by INSERT
a230: 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45  , UPDATE or DELE
a240: 54 45 20 73 74 61 74 65 6d 65 6e 74 73 20 73 69  TE statements si
a250: 6e 63 65 20 74 68 65 20 64 61 74 61 62 61 73 65  nce the database
a260: 20 68 61 6e 64 6c 65 0a 2a 2a 20 77 61 73 20 6f   handle.** was o
a270: 70 65 6e 65 64 2e 20 20 54 68 65 20 63 6f 75 6e  pened.  The coun
a280: 74 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 63  t includes all c
a290: 68 61 6e 67 65 73 20 66 72 6f 6d 20 61 6c 6c 20  hanges from all 
a2a0: 74 72 69 67 67 65 72 0a 2a 2a 20 63 6f 6e 74 65  trigger.** conte
a2b0: 78 74 73 2e 20 20 42 75 74 20 74 68 65 20 63 6f  xts.  But the co
a2c0: 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63  unt does not inc
a2d0: 6c 75 64 65 20 63 68 61 6e 67 65 73 20 75 73 65  lude changes use
a2e0: 64 20 74 6f 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  d to.** implemen
a2f0: 74 20 52 45 50 4c 41 43 45 20 63 6f 6e 73 74 72  t REPLACE constr
a300: 61 69 6e 74 73 2c 20 64 6f 20 72 6f 6c 6c 62 61  aints, do rollba
a310: 63 6b 73 20 6f 72 20 41 42 4f 52 54 20 70 72 6f  cks or ABORT pro
a320: 63 65 73 73 69 6e 67 2c 0a 2a 2a 20 6f 72 20 44  cessing,.** or D
a330: 52 4f 50 20 74 61 62 6c 65 20 70 72 6f 63 65 73  ROP table proces
a340: 73 69 6e 67 2e 0a 2a 2a 20 54 68 65 20 63 68 61  sing..** The cha
a350: 6e 67 65 73 0a 2a 2a 20 61 72 65 20 63 6f 75 6e  nges.** are coun
a360: 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74  ted as soon as t
a370: 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61  he statement tha
a380: 74 20 6d 61 6b 65 73 20 74 68 65 6d 20 69 73 20  t makes them is 
a390: 63 6f 6d 70 6c 65 74 65 64 20 0a 2a 2a 20 28 77  completed .** (w
a3a0: 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e  hen the statemen
a3b0: 74 20 68 61 6e 64 6c 65 20 69 73 20 70 61 73 73  t handle is pass
a3c0: 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  ed to [sqlite3_r
a3d0: 65 73 65 74 28 29 5d 20 6f 72 20 0a 2a 2a 20 5b  eset()] or .** [
a3e0: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
a3f0: 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  ()])..**.** SQLi
a400: 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68  te implements th
a410: 65 20 63 6f 6d 6d 61 6e 64 20 22 44 45 4c 45 54  e command "DELET
a420: 45 20 46 52 4f 4d 20 74 61 62 6c 65 22 20 77 69  E FROM table" wi
a430: 74 68 6f 75 74 0a 2a 2a 20 61 20 57 48 45 52 45  thout.** a WHERE
a440: 20 63 6c 61 75 73 65 20 62 79 20 64 72 6f 70 70   clause by dropp
a450: 69 6e 67 20 61 6e 64 20 72 65 63 72 65 61 74 69  ing and recreati
a460: 6e 67 20 74 68 65 20 74 61 62 6c 65 2e 20 20 28  ng the table.  (
a470: 54 68 69 73 20 69 73 20 6d 75 63 68 0a 2a 2a 20  This is much.** 
a480: 66 61 73 74 65 72 20 74 68 61 6e 20 67 6f 69 6e  faster than goin
a490: 67 0a 2a 2a 20 74 68 72 6f 75 67 68 20 61 6e 64  g.** through and
a4a0: 20 64 65 6c 65 74 69 6e 67 20 69 6e 64 69 76 69   deleting indivi
a4b0: 64 75 61 6c 20 65 6c 65 6d 65 6e 74 73 20 66 72  dual elements fr
a4c0: 6f 6d 20 74 68 65 20 74 61 62 6c 65 2e 29 20 20  om the table.)  
a4d0: 42 65 63 61 75 73 65 20 6f 66 0a 2a 2a 20 74 68  Because of.** th
a4e0: 69 73 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 2c  is optimization,
a4f0: 20 74 68 65 20 63 68 61 6e 67 65 20 63 6f 75 6e   the change coun
a500: 74 20 66 6f 72 20 22 44 45 4c 45 54 45 20 46 52  t for "DELETE FR
a510: 4f 4d 20 74 61 62 6c 65 22 20 77 69 6c 6c 20 62  OM table" will b
a520: 65 0a 2a 2a 20 7a 65 72 6f 20 72 65 67 61 72 64  e.** zero regard
a530: 6c 65 73 73 20 6f 66 20 74 68 65 20 6e 75 6d 62  less of the numb
a540: 65 72 20 6f 66 20 65 6c 65 6d 65 6e 74 73 20 74  er of elements t
a550: 68 61 74 20 77 65 72 65 20 6f 72 69 67 69 6e 61  hat were origina
a560: 6c 6c 79 20 69 6e 20 74 68 65 0a 2a 2a 20 74 61  lly in the.** ta
a570: 62 6c 65 2e 20 54 6f 20 67 65 74 20 61 6e 20 61  ble. To get an a
a580: 63 63 75 72 61 74 65 20 63 6f 75 6e 74 20 6f 66  ccurate count of
a590: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72   the number of r
a5a0: 6f 77 73 20 64 65 6c 65 74 65 64 2c 20 75 73 65  ows deleted, use
a5b0: 0a 2a 2a 20 22 44 45 4c 45 54 45 20 46 52 4f 4d  .** "DELETE FROM
a5c0: 20 74 61 62 6c 65 20 57 48 45 52 45 20 31 22 20   table WHERE 1" 
a5d0: 69 6e 73 74 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 53  instead..**.** S
a5e0: 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c  ee also the [sql
a5f0: 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20  ite3_changes()] 
a600: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
a610: 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 20   INVARIANTS:.** 
a620: 0a 2a 2a 20 7b 46 31 32 32 36 31 7d 20 54 68 65  .** {F12261} The
a630: 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f   [sqlite3_total_
a640: 63 68 61 6e 67 65 73 28 29 5d 20 72 65 74 75 72  changes()] retur
a650: 6e 73 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d  ns the total num
a660: 62 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ber.**          
a670: 6f 66 20 72 6f 77 20 63 68 61 6e 67 65 73 20 63  of row changes c
a680: 61 75 73 65 64 20 62 79 20 49 4e 53 45 52 54 2c  aused by INSERT,
a690: 20 55 50 44 41 54 45 2c 20 61 6e 64 2f 6f 72 20   UPDATE, and/or 
a6a0: 44 45 4c 45 54 45 0a 2a 2a 20 20 20 20 20 20 20  DELETE.**       
a6b0: 20 20 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e     statements on
a6c0: 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62   the same [datab
a6d0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c  ase connection],
a6e0: 20 69 6e 20 61 6e 79 0a 2a 2a 20 20 20 20 20 20   in any.**      
a6f0: 20 20 20 20 74 72 69 67 67 65 72 20 63 6f 6e 74      trigger cont
a700: 65 78 74 2c 20 73 69 6e 63 65 20 74 68 65 20 64  ext, since the d
a710: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
a720: 6f 6e 20 77 61 73 0a 2a 2a 20 20 20 20 20 20 20  on was.**       
a730: 20 20 20 63 72 65 61 74 65 64 2e 0a 2a 2a 0a 2a     created..**.*
a740: 2a 20 4c 49 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a  * LIMITATIONS:.*
a750: 2a 0a 2a 2a 20 7b 55 31 32 32 36 34 7d 20 49 66  *.** {U12264} If
a760: 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65   a separate thre
a770: 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73  ad makes changes
a780: 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74   on the same dat
a790: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
a7a0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68 69  .**          whi
a7b0: 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61  le [sqlite3_tota
a7c0: 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20  l_changes()] is 
a7d0: 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65  running then the
a7e0: 20 76 61 6c 75 65 20 0a 2a 2a 20 20 20 20 20 20   value .**      
a7f0: 20 20 20 20 72 65 74 75 72 6e 65 64 20 69 73 20      returned is 
a800: 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e  unpredictable an
a810: 64 20 75 6e 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a  d unmeaningful..
a820: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74  */.int sqlite3_t
a830: 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c  otal_changes(sql
a840: 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
a850: 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72 75  API3REF: Interru
a860: 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e  pt A Long-Runnin
a870: 67 20 51 75 65 72 79 20 7b 46 31 32 32 37 30 7d  g Query {F12270}
a880: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63  .**.** This func
a890: 74 69 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 20  tion causes any 
a8a0: 70 65 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65  pending database
a8b0: 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 62   operation to ab
a8c0: 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72  ort and.** retur
a8d0: 6e 20 61 74 20 69 74 73 20 65 61 72 6c 69 65 73  n at its earlies
a8e0: 74 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 54  t opportunity. T
a8f0: 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74  his routine is t
a900: 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c  ypically.** call
a910: 65 64 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74  ed in response t
a920: 6f 20 61 20 75 73 65 72 20 61 63 74 69 6f 6e 20  o a user action 
a930: 73 75 63 68 20 61 73 20 70 72 65 73 73 69 6e 67  such as pressing
a940: 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20   "Cancel".** or 
a950: 43 74 72 6c 2d 43 20 77 68 65 72 65 20 74 68 65  Ctrl-C where the
a960: 20 75 73 65 72 20 77 61 6e 74 73 20 61 20 6c 6f   user wants a lo
a970: 6e 67 20 71 75 65 72 79 20 6f 70 65 72 61 74 69  ng query operati
a980: 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d  on to halt.** im
a990: 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a  mediately..**.**
a9a0: 20 49 74 20 69 73 20 73 61 66 65 20 74 6f 20 63   It is safe to c
a9b0: 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65  all this routine
a9c0: 20 66 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64   from a thread d
a9d0: 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68  ifferent from th
a9e0: 65 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74  e.** thread that
a9f0: 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75   is currently ru
aa00: 6e 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 61  nning the databa
aa10: 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42  se operation.  B
aa20: 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20  ut it.** is not 
aa30: 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69  safe to call thi
aa40: 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61  s routine with a
aa50: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
aa60: 74 69 6f 6e 20 74 68 61 74 0a 2a 2a 20 69 73 20  tion that.** is 
aa70: 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20  closed or might 
aa80: 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c  close before sql
aa90: 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
aaa0: 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
aab0: 49 66 20 61 6e 20 53 51 4c 20 69 73 20 76 65 72  If an SQL is ver
aac0: 79 20 6e 65 61 72 6c 79 20 66 69 6e 69 73 68 65  y nearly finishe
aad0: 64 20 61 74 20 74 68 65 20 74 69 6d 65 20 77 68  d at the time wh
aae0: 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  en sqlite3_inter
aaf0: 72 75 70 74 28 29 0a 2a 2a 20 69 73 20 63 61 6c  rupt().** is cal
ab00: 6c 65 64 2c 20 74 68 65 6e 20 69 74 20 6d 69 67  led, then it mig
ab10: 68 74 20 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f  ht not have an o
ab20: 70 70 6f 72 74 75 6e 69 74 79 20 74 6f 20 62 65  pportunity to be
ab30: 20 69 6e 74 65 72 72 75 70 74 65 64 2e 0a 2a 2a   interrupted..**
ab40: 20 49 74 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e   It might contin
ab50: 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e  ue to completion
ab60: 2e 0a 2a 2a 20 41 6e 20 53 51 4c 20 6f 70 65 72  ..** An SQL oper
ab70: 61 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e  ation that is in
ab80: 74 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72  terrupted will r
ab90: 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45  eturn.** [SQLITE
aba0: 5f 49 4e 54 45 52 52 55 50 54 5d 2e 20 20 49 66  _INTERRUPT].  If
abb0: 20 74 68 65 20 69 6e 74 65 72 72 75 70 74 65 64   the interrupted
abc0: 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69   SQL operation i
abd0: 73 20 61 6e 0a 2a 2a 20 49 4e 53 45 52 54 2c 20  s an.** INSERT, 
abe0: 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54  UPDATE, or DELET
abf0: 45 20 74 68 61 74 20 69 73 20 69 6e 73 69 64 65  E that is inside
ac00: 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61   an explicit tra
ac10: 6e 73 61 63 74 69 6f 6e 2c 20 0a 2a 2a 20 74 68  nsaction, .** th
ac20: 65 6e 20 74 68 65 20 65 6e 74 69 72 65 20 74 72  en the entire tr
ac30: 61 6e 73 61 63 74 69 6f 6e 20 77 69 6c 6c 20 62  ansaction will b
ac40: 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75  e rolled back au
ac50: 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 20  tomatically..** 
ac60: 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  A call to sqlite
ac70: 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 68 61  3_interrupt() ha
ac80: 73 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 53  s no effect on S
ac90: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
aca0: 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65   that are starte
acb0: 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f  d after sqlite3_
acc0: 69 6e 74 65 72 72 75 70 74 28 29 20 72 65 74 75  interrupt() retu
acd0: 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  rns..**.** INVAR
ace0: 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31  IANTS:.**.** {F1
acf0: 32 32 37 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  2271} The [sqlit
ad00: 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 20  e3_interrupt()] 
ad10: 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 66  interface will f
ad20: 6f 72 63 65 20 61 6c 6c 20 72 75 6e 6e 69 6e 67  orce all running
ad30: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53 51 4c  .**          SQL
ad40: 20 73 74 61 74 65 6d 65 6e 74 73 20 61 73 73 6f   statements asso
ad50: 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
ad60: 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
ad70: 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20  nnection.**     
ad80: 20 20 20 20 20 74 6f 20 68 61 6c 74 20 61 66 74       to halt aft
ad90: 65 72 20 70 72 6f 63 65 73 73 69 6e 67 20 61 74  er processing at
ada0: 20 6d 6f 73 74 20 6f 6e 65 20 61 64 64 69 74 69   most one additi
adb0: 6f 6e 61 6c 20 72 6f 77 20 6f 66 0a 2a 2a 20 20  onal row of.**  
adc0: 20 20 20 20 20 20 20 20 64 61 74 61 2e 0a 2a 2a          data..**
add0: 0a 2a 2a 20 7b 46 31 32 32 37 32 7d 20 41 6e 79  .** {F12272} Any
ade0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
adf0: 68 61 74 20 69 73 20 69 6e 74 65 72 72 75 70 74  hat is interrupt
ae00: 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 69  ed by [sqlite3_i
ae10: 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 20  nterrupt()].**  
ae20: 20 20 20 20 20 20 20 20 77 69 6c 6c 20 72 65 74          will ret
ae30: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  urn [SQLITE_INTE
ae40: 52 52 55 50 54 5d 2e 0a 2a 2a 0a 2a 2a 20 4c 49  RRUPT]..**.** LI
ae50: 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a  MITATIONS:.**.**
ae60: 20 7b 55 31 32 32 37 39 7d 20 49 66 20 74 68 65   {U12279} If the
ae70: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
ae80: 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c  tion closes whil
ae90: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  e [sqlite3_inter
aea0: 72 75 70 74 28 29 5d 0a 2a 2a 20 20 20 20 20 20  rupt()].**      
aeb0: 20 20 20 20 69 73 20 72 75 6e 6e 69 6e 67 20 74      is running t
aec0: 68 65 6e 20 62 61 64 20 74 68 69 6e 67 73 20 77  hen bad things w
aed0: 69 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70 65  ill likely happe
aee0: 6e 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  n..*/.void sqlit
aef0: 65 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c  e3_interrupt(sql
af00: 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
af10: 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69  API3REF: Determi
af20: 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61  ne If An SQL Sta
af30: 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65  tement Is Comple
af40: 74 65 20 7b 46 31 30 35 31 30 7d 0a 2a 2a 0a 2a  te {F10510}.**.*
af50: 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
af60: 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20   are useful for 
af70: 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70  command-line inp
af80: 75 74 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20  ut to determine 
af90: 69 66 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e  if the.** curren
afa0: 74 6c 79 20 65 6e 74 65 72 65 64 20 74 65 78 74  tly entered text
afb0: 20 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20 63   seems to form c
afc0: 6f 6d 70 6c 65 74 65 20 61 20 53 51 4c 20 73 74  omplete a SQL st
afd0: 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66  atement or.** if
afe0: 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75   additional inpu
aff0: 74 20 69 73 20 6e 65 65 64 65 64 20 62 65 66 6f  t is needed befo
b000: 72 65 20 73 65 6e 64 69 6e 67 20 74 68 65 20 74  re sending the t
b010: 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69  ext into.** SQLi
b020: 74 65 20 66 6f 72 20 70 61 72 73 69 6e 67 2e 20  te for parsing. 
b030: 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
b040: 72 65 74 75 72 6e 20 74 72 75 65 20 69 66 20 74  return true if t
b050: 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 0a  he input string.
b060: 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62 65  ** appears to be
b070: 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20   a complete SQL 
b080: 73 74 61 74 65 6d 65 6e 74 2e 20 20 41 20 73 74  statement.  A st
b090: 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 64 67 65  atement is judge
b0a0: 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c  d to be.** compl
b0b0: 65 74 65 20 69 66 20 69 74 20 65 6e 64 73 20 77  ete if it ends w
b0c0: 69 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20  ith a semicolon 
b0d0: 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74  token and is not
b0e0: 20 61 20 66 72 61 67 6d 65 6e 74 20 6f 66 20 61   a fragment of a
b0f0: 0a 2a 2a 20 43 52 45 41 54 45 20 54 52 49 47 47  .** CREATE TRIGG
b100: 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 53  ER statement.  S
b110: 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61  emicolons that a
b120: 72 65 20 65 6d 62 65 64 64 65 64 20 77 69 74 68  re embedded with
b130: 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74  in.** string lit
b140: 65 72 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20  erals or quoted 
b150: 69 64 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73  identifier names
b160: 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65   or comments are
b170: 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64   not.** independ
b180: 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79  ent tokens (they
b190: 20 61 72 65 20 70 61 72 74 20 6f 66 20 74 68 65   are part of the
b1a0: 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20   token in which 
b1b0: 74 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65  they are.** embe
b1c0: 64 64 65 64 29 20 61 6e 64 20 74 68 75 73 20 64  dded) and thus d
b1d0: 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61  o not count as a
b1e0: 20 73 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69   statement termi
b1f0: 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  nator..**.** The
b200: 73 65 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e  se routines do n
b210: 6f 74 20 70 61 72 73 65 20 74 68 65 20 53 51 4c  ot parse the SQL
b220: 20 61 6e 64 0a 2a 2a 20 73 6f 20 77 69 6c 6c 20   and.** so will 
b230: 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e 74 61  not detect synta
b240: 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65  ctically incorre
b250: 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 49 4e  ct SQL..**.** IN
b260: 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
b270: 7b 46 31 30 35 31 31 7d 20 54 68 65 20 73 71 6c  {F10511} The sql
b280: 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 20  ite3_complete() 
b290: 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  and sqlite3_comp
b2a0: 6c 65 74 65 31 36 28 29 20 66 75 6e 63 74 69 6f  lete16() functio
b2b0: 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  ns.**          r
b2c0: 65 74 75 72 6e 20 74 72 75 65 20 28 6e 6f 6e 2d  eturn true (non-
b2d0: 7a 65 72 6f 29 20 69 66 20 61 6e 64 20 6f 6e 6c  zero) if and onl
b2e0: 79 20 69 66 20 74 68 65 20 6c 61 73 74 0a 2a 2a  y if the last.**
b2f0: 20 20 20 20 20 20 20 20 20 20 6e 6f 6e 2d 77 68            non-wh
b300: 69 74 65 73 70 61 63 65 20 74 6f 6b 65 6e 20 69  itespace token i
b310: 6e 20 74 68 65 69 72 20 69 6e 70 75 74 20 69 73  n their input is
b320: 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 68 61   a semicolon tha
b330: 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73  t.**          is
b340: 20 6e 6f 74 20 69 6e 20 62 65 74 77 65 65 6e 20   not in between 
b350: 74 68 65 20 42 45 47 49 4e 20 61 6e 64 20 45 4e  the BEGIN and EN
b360: 44 20 6f 66 20 61 20 43 52 45 41 54 45 20 54 52  D of a CREATE TR
b370: 49 47 47 45 52 0a 2a 2a 20 20 20 20 20 20 20 20  IGGER.**        
b380: 20 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a    statement..**.
b390: 2a 2a 20 4c 49 4d 49 54 41 54 49 4f 4e 53 3a 0a  ** LIMITATIONS:.
b3a0: 2a 2a 0a 2a 2a 20 7b 55 31 30 35 31 32 7d 20 54  **.** {U10512} T
b3b0: 68 65 20 69 6e 70 75 74 20 74 6f 20 73 71 6c 69  he input to sqli
b3c0: 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 20 6d  te3_complete() m
b3d0: 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65  ust be a zero-te
b3e0: 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 20 20 20 20  rminated.**     
b3f0: 20 20 20 20 20 55 54 46 2d 38 20 73 74 72 69 6e       UTF-8 strin
b400: 67 2e 0a 2a 2a 0a 2a 2a 20 7b 55 31 30 35 31 33  g..**.** {U10513
b410: 7d 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 73  } The input to s
b420: 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
b430: 36 28 29 20 6d 75 73 74 20 62 65 20 61 20 7a 65  6() must be a ze
b440: 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
b450: 20 20 20 20 20 20 20 20 20 20 55 54 46 2d 31 36            UTF-16
b460: 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76   string in nativ
b470: 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f  e byte order..*/
b480: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d  .int sqlite3_com
b490: 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72  plete(const char
b4a0: 20 2a 73 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69   *sql);.int sqli
b4b0: 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63  te3_complete16(c
b4c0: 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b  onst void *sql);
b4d0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
b4e0: 3a 20 52 65 67 69 73 74 65 72 20 41 20 43 61 6c  : Register A Cal
b4f0: 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20  lback To Handle 
b500: 53 51 4c 49 54 45 5f 42 55 53 59 20 45 72 72 6f  SQLITE_BUSY Erro
b510: 72 73 20 7b 46 31 32 33 31 30 7d 0a 2a 2a 0a 2a  rs {F12310}.**.*
b520: 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69  * This routine i
b530: 64 65 6e 74 69 66 69 65 73 20 61 20 63 61 6c 6c  dentifies a call
b540: 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 74 68  back function th
b550: 61 74 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 69  at might be.** i
b560: 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20  nvoked whenever 
b570: 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61  an attempt is ma
b580: 64 65 20 74 6f 20 6f 70 65 6e 20 61 20 64 61 74  de to open a dat
b590: 61 62 61 73 65 20 74 61 62 6c 65 20 0a 2a 2a 20  abase table .** 
b5a0: 74 68 61 74 20 61 6e 6f 74 68 65 72 20 74 68 72  that another thr
b5b0: 65 61 64 20 6f 72 20 70 72 6f 63 65 73 73 20 68  ead or process h
b5c0: 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 20 49 66  as locked..** If
b5d0: 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61   the busy callba
b5e0: 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  ck is NULL, then
b5f0: 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a   [SQLITE_BUSY].*
b600: 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45  * or [SQLITE_IOE
b610: 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69  RR_BLOCKED].** i
b620: 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64  s returned immed
b630: 69 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f  iately upon enco
b640: 75 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63  untering the loc
b650: 6b 2e 0a 2a 2a 20 49 66 20 74 68 65 20 62 75 73  k..** If the bus
b660: 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f  y callback is no
b670: 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65  t NULL, then the
b680: 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 77 69 6c  .** callback wil
b690: 6c 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74  l be invoked wit
b6a0: 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e  h two arguments.
b6b0: 20 20 54 68 65 0a 2a 2a 20 66 69 72 73 74 20 61    The.** first a
b6c0: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 68  rgument to the h
b6d0: 61 6e 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79  andler is a copy
b6e0: 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f   of the void* po
b6f0: 69 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69  inter which.** i
b700: 73 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75  s the third argu
b710: 6d 65 6e 74 20 74 6f 20 74 68 69 73 20 72 6f 75  ment to this rou
b720: 74 69 6e 65 2e 20 20 54 68 65 20 73 65 63 6f 6e  tine.  The secon
b730: 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  d argument to.**
b740: 20 74 68 65 20 68 61 6e 64 6c 65 72 20 69 73 20   the handler is 
b750: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69  the number of ti
b760: 6d 65 73 20 74 68 61 74 20 74 68 65 20 62 75 73  mes that the bus
b770: 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a  y handler has.**
b780: 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 66 6f   been invoked fo
b790: 72 20 74 68 69 73 20 6c 6f 63 6b 69 6e 67 20 65  r this locking e
b7a0: 76 65 6e 74 2e 20 20 20 49 66 20 74 68 65 0a 2a  vent.   If the.*
b7b0: 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  * busy callback 
b7c0: 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20  returns 0, then 
b7d0: 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74  no additional at
b7e0: 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20  tempts are made 
b7f0: 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65  to.** access the
b800: 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53   database and [S
b810: 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b  QLITE_BUSY] or [
b820: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
b830: 43 4b 45 44 5d 20 69 73 20 72 65 74 75 72 6e 65  CKED] is returne
b840: 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 63 61 6c  d..** If the cal
b850: 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f  lback returns no
b860: 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f  n-zero, then ano
b870: 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20  ther attempt.** 
b880: 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20  is made to open 
b890: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 6f 72  the database for
b8a0: 20 72 65 61 64 69 6e 67 20 61 6e 64 20 74 68 65   reading and the
b8b0: 20 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e 0a   cycle repeats..
b8c0: 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 6e  **.** The presen
b8d0: 63 65 20 6f 66 20 61 20 62 75 73 79 20 68 61 6e  ce of a busy han
b8e0: 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 75  dler does not gu
b8f0: 61 72 61 6e 74 65 65 20 74 68 61 74 0a 2a 2a 20  arantee that.** 
b900: 69 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b  it will be invok
b910: 65 64 20 77 68 65 6e 20 74 68 65 72 65 20 69 73  ed when there is
b920: 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e   lock contention
b930: 2e 0a 2a 2a 20 49 66 20 53 51 4c 69 74 65 20 64  ..** If SQLite d
b940: 65 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69  etermines that i
b950: 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79  nvoking the busy
b960: 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72   handler could r
b970: 65 73 75 6c 74 20 69 6e 0a 2a 2a 20 61 20 64 65  esult in.** a de
b980: 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20  adlock, it will 
b990: 67 6f 20 61 68 65 61 64 20 61 6e 64 20 72 65 74  go ahead and ret
b9a0: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  urn [SQLITE_BUSY
b9b0: 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ] or.** [SQLITE_
b9c0: 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69  IOERR_BLOCKED] i
b9d0: 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69  nstead of invoki
b9e0: 6e 67 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 68  ng the.** busy h
b9f0: 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69  andler..** Consi
ba00: 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f 20 77  der a scenario w
ba10: 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 73 73  here one process
ba20: 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65   is holding a re
ba30: 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20  ad lock that.** 
ba40: 69 74 20 69 73 20 74 72 79 69 6e 67 20 74 6f 20  it is trying to 
ba50: 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65 73  promote to a res
ba60: 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a  erved lock and.*
ba70: 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f 63 65  * a second proce
ba80: 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20  ss is holding a 
ba90: 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 74 68  reserved lock th
baa0: 61 74 20 69 74 20 69 73 20 74 72 79 69 6e 67 0a  at it is trying.
bab0: 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f  ** to promote to
bac0: 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c 6f   an exclusive lo
bad0: 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74 20 70  ck.  The first p
bae0: 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 70 72  rocess cannot pr
baf0: 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 73 65  oceed.** because
bb00: 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62   it is blocked b
bb10: 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64  y the second and
bb20: 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63   the second proc
bb30: 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72  ess cannot.** pr
bb40: 6f 63 65 65 64 20 62 65 63 61 75 73 65 20 69 74  oceed because it
bb50: 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74   is blocked by t
bb60: 68 65 20 66 69 72 73 74 2e 20 20 49 66 20 62 6f  he first.  If bo
bb70: 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20  th processes.** 
bb80: 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 79 20  invoke the busy 
bb90: 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68 65  handlers, neithe
bba0: 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20  r will make any 
bbb0: 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65 72 65  progress.  There
bbc0: 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20  fore,.** SQLite 
bbd0: 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
bbe0: 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20 66 69  BUSY] for the fi
bbf0: 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68 6f 70  rst process, hop
bc00: 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a 2a 2a  ing that this.**
bc10: 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 68 65   will induce the
bc20: 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 74   first process t
bc30: 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20 72 65  o release its re
bc40: 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f  ad lock and allo
bc50: 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20  w.** the second 
bc60: 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f 63 65  process to proce
bc70: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65  ed..**.** The de
bc80: 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c 6c 62  fault busy callb
bc90: 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a  ack is NULL..**.
bca0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 42  ** The [SQLITE_B
bcb0: 55 53 59 5d 20 65 72 72 6f 72 20 69 73 20 63 6f  USY] error is co
bcc0: 6e 76 65 72 74 65 64 20 74 6f 20 5b 53 51 4c 49  nverted to [SQLI
bcd0: 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
bce0: 5d 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65  ].** when SQLite
bcf0: 20 69 73 20 69 6e 20 74 68 65 20 6d 69 64 64 6c   is in the middl
bd00: 65 20 6f 66 20 61 20 6c 61 72 67 65 20 74 72 61  e of a large tra
bd10: 6e 73 61 63 74 69 6f 6e 20 77 68 65 72 65 20 61  nsaction where a
bd20: 6c 6c 20 74 68 65 0a 2a 2a 20 63 68 61 6e 67 65  ll the.** change
bd30: 73 20 77 69 6c 6c 20 6e 6f 74 20 66 69 74 20 69  s will not fit i
bd40: 6e 74 6f 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72  nto the in-memor
bd50: 79 20 63 61 63 68 65 2e 20 20 53 51 4c 69 74 65  y cache.  SQLite
bd60: 20 77 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64 79   will.** already
bd70: 20 68 6f 6c 64 20 61 20 52 45 53 45 52 56 45 44   hold a RESERVED
bd80: 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 64 61 74   lock on the dat
bd90: 61 62 61 73 65 20 66 69 6c 65 2c 20 62 75 74 20  abase file, but 
bda0: 69 74 20 6e 65 65 64 73 0a 2a 2a 20 74 6f 20 70  it needs.** to p
bdb0: 72 6f 6d 6f 74 65 20 74 68 69 73 20 6c 6f 63 6b  romote this lock
bdc0: 20 74 6f 20 45 58 43 4c 55 53 49 56 45 20 73 6f   to EXCLUSIVE so
bdd0: 20 74 68 61 74 20 69 74 20 63 61 6e 20 73 70 69   that it can spi
bde0: 6c 6c 20 63 61 63 68 65 0a 2a 2a 20 70 61 67 65  ll cache.** page
bdf0: 73 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62  s into the datab
be00: 61 73 65 20 66 69 6c 65 20 77 69 74 68 6f 75 74  ase file without
be10: 20 68 61 72 6d 20 74 6f 20 63 6f 6e 63 75 72 72   harm to concurr
be20: 65 6e 74 0a 2a 2a 20 72 65 61 64 65 72 73 2e 20  ent.** readers. 
be30: 20 49 66 20 69 74 20 69 73 20 75 6e 61 62 6c 65   If it is unable
be40: 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 65 20   to promote the 
be50: 6c 6f 63 6b 2c 20 74 68 65 6e 20 74 68 65 20 69  lock, then the i
be60: 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61 63 68  n-memory.** cach
be70: 65 20 77 69 6c 6c 20 62 65 20 6c 65 66 74 20 69  e will be left i
be80: 6e 20 61 6e 20 69 6e 63 6f 6e 73 69 73 74 65 6e  n an inconsisten
be90: 74 20 73 74 61 74 65 20 61 6e 64 20 73 6f 20 74  t state and so t
bea0: 68 65 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65  he error.** code
beb0: 20 69 73 20 70 72 6f 6d 6f 74 65 64 20 66 72 6f   is promoted fro
bec0: 6d 20 74 68 65 20 72 65 6c 61 74 69 76 65 6c 79  m the relatively
bed0: 20 62 65 6e 69 67 6e 20 5b 53 51 4c 49 54 45 5f   benign [SQLITE_
bee0: 42 55 53 59 5d 20 74 6f 0a 2a 2a 20 74 68 65 20  BUSY] to.** the 
bef0: 6d 6f 72 65 20 73 65 76 65 72 65 20 5b 53 51 4c  more severe [SQL
bf00: 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45  ITE_IOERR_BLOCKE
bf10: 44 5d 2e 20 20 54 68 69 73 20 65 72 72 6f 72 20  D].  This error 
bf20: 63 6f 64 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a  code promotion.*
bf30: 2a 20 66 6f 72 63 65 73 20 61 6e 20 61 75 74 6f  * forces an auto
bf40: 6d 61 74 69 63 20 72 6f 6c 6c 62 61 63 6b 20 6f  matic rollback o
bf50: 66 20 74 68 65 20 63 68 61 6e 67 65 73 2e 20 20  f the changes.  
bf60: 53 65 65 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72  See the.** <a hr
bf70: 65 66 3d 22 68 74 74 70 3a 2f 2f 77 77 77 2e 73  ef="http://www.s
bf80: 71 6c 69 74 65 2e 6f 72 67 2f 63 76 73 74 72 61  qlite.org/cvstra
bf90: 63 2f 77 69 6b 69 3f 70 3d 43 6f 72 72 75 70 74  c/wiki?p=Corrupt
bfa0: 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79  ionFollowingBusy
bfb0: 45 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72 75  Error">.** Corru
bfc0: 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75  ptionFollowingBu
bfd0: 73 79 45 72 72 6f 72 3c 2f 61 3e 20 77 69 6b 69  syError</a> wiki
bfe0: 20 70 61 67 65 20 66 6f 72 20 61 20 64 69 73 63   page for a disc
bff0: 75 73 73 69 6f 6e 20 6f 66 20 77 68 79 0a 2a 2a  ussion of why.**
c000: 20 74 68 69 73 20 69 73 20 69 6d 70 6f 72 74 61   this is importa
c010: 6e 74 2e 0a 2a 2a 09 0a 2a 2a 20 54 68 65 72 65  nt..**..** There
c020: 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73   can only be a s
c030: 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c  ingle busy handl
c040: 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72 20 65  er defined for e
c050: 61 63 68 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  ach database.** 
c060: 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65 74  connection.  Set
c070: 74 69 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20  ting a new busy 
c080: 68 61 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61  handler clears a
c090: 6e 79 20 70 72 65 76 69 6f 75 73 20 6f 6e 65 2e  ny previous one.
c0a0: 20 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 63   .** Note that c
c0b0: 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
c0c0: 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20  busy_timeout()] 
c0d0: 77 69 6c 6c 20 61 6c 73 6f 20 73 65 74 20 6f 72  will also set or
c0e0: 20 63 6c 65 61 72 0a 2a 2a 20 74 68 65 20 62 75   clear.** the bu
c0f0: 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a  sy handler..**.*
c100: 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
c110: 0a 2a 2a 20 7b 46 31 32 33 31 31 7d 20 54 68 65  .** {F12311} The
c120: 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68   [sqlite3_busy_h
c130: 61 6e 64 6c 65 72 28 29 5d 20 66 75 6e 63 74 69  andler()] functi
c140: 6f 6e 20 72 65 70 6c 61 63 65 73 20 74 68 65 20  on replaces the 
c150: 62 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20  busy handler.** 
c160: 20 20 20 20 20 20 20 20 20 63 61 6c 6c 62 61 63           callbac
c170: 6b 20 69 6e 20 74 68 65 20 64 61 74 61 62 61 73  k in the databas
c180: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 64 65  e connection ide
c190: 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20 31  ntified by the 1
c1a0: 73 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70  st.**          p
c1b0: 61 72 61 6d 65 74 65 72 20 77 69 74 68 20 61 20  arameter with a 
c1c0: 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72  new busy handler
c1d0: 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74   identified by t
c1e0: 68 65 20 32 6e 64 20 61 6e 64 20 33 72 64 0a 2a  he 2nd and 3rd.*
c1f0: 2a 20 20 20 20 20 20 20 20 20 20 70 61 72 61 6d  *          param
c200: 65 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  eters..**.** {F1
c210: 32 33 31 32 7d 20 54 68 65 20 64 65 66 61 75 6c  2312} The defaul
c220: 74 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66  t busy handler f
c230: 6f 72 20 6e 65 77 20 64 61 74 61 62 61 73 65 20  or new database 
c240: 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 69 73 20 4e  connections is N
c250: 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33  ULL..**.** {F123
c260: 31 34 7d 20 57 68 65 6e 20 74 77 6f 20 6f 72 20  14} When two or 
c270: 6d 6f 72 65 20 64 61 74 61 62 61 73 65 20 63 6f  more database co
c280: 6e 6e 65 63 74 69 6f 6e 20 73 68 61 72 65 20 61  nnection share a
c290: 20 63 6f 6d 6d 6f 6e 20 63 61 63 68 65 2c 0a 2a   common cache,.*
c2a0: 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 62  *          the b
c2b0: 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20  usy handler for 
c2c0: 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
c2d0: 6e 65 63 74 69 6f 6e 20 63 75 72 72 65 6e 74 6c  nection currentl
c2e0: 79 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20  y using.**      
c2f0: 20 20 20 20 74 68 65 20 63 61 63 68 65 20 69 73      the cache is
c300: 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 68   invoked when th
c310: 65 20 63 61 63 68 65 20 65 6e 63 6f 75 6e 74 65  e cache encounte
c320: 72 73 20 61 20 6c 6f 63 6b 2e 0a 2a 2a 0a 2a 2a  rs a lock..**.**
c330: 20 7b 46 31 32 33 31 36 7d 20 49 66 20 61 20 62   {F12316} If a b
c340: 75 73 79 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c  usy handler call
c350: 62 61 63 6b 20 72 65 74 75 72 6e 73 20 7a 65 72  back returns zer
c360: 6f 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 69  o, then the SQLi
c370: 74 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  te.**          i
c380: 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 70 72  nterface that pr
c390: 6f 76 6f 6b 65 64 20 74 68 65 20 6c 6f 63 6b 69  ovoked the locki
c3a0: 6e 67 20 65 76 65 6e 74 20 77 69 6c 6c 20 72 65  ng event will re
c3b0: 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  turn.**         
c3c0: 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a   [SQLITE_BUSY]..
c3d0: 2a 2a 0a 2a 2a 20 7b 46 31 32 33 31 38 7d 20 53  **.** {F12318} S
c3e0: 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b  QLite will invok
c3f0: 65 73 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  es the busy hand
c400: 6c 65 72 20 77 69 74 68 20 74 77 6f 20 61 72 67  ler with two arg
c410: 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 20  ument which.**  
c420: 20 20 20 20 20 20 20 20 61 72 65 20 61 20 63 6f          are a co
c430: 70 79 20 6f 66 20 74 68 65 20 70 6f 69 6e 74 65  py of the pointe
c440: 72 20 73 75 70 70 6c 69 65 64 20 62 79 20 74 68  r supplied by th
c450: 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
c460: 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  to.**          [
c470: 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
c480: 64 6c 65 72 28 29 5d 20 61 6e 64 20 61 20 63 6f  dler()] and a co
c490: 75 6e 74 20 6f 66 20 74 68 65 20 6e 75 6d 62 65  unt of the numbe
c4a0: 72 20 6f 66 20 70 72 69 6f 72 0a 2a 2a 20 20 20  r of prior.**   
c4b0: 20 20 20 20 20 20 20 69 6e 76 6f 63 61 74 69 6f         invocatio
c4c0: 6e 73 20 6f 66 20 74 68 65 20 62 75 73 79 20 68  ns of the busy h
c4d0: 61 6e 64 6c 65 72 20 66 6f 72 20 74 68 65 20 73  andler for the s
c4e0: 61 6d 65 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e  ame locking even
c4f0: 74 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49 54 41 54  t..**.** LIMITAT
c500: 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 55 31 32  IONS:.**.** {U12
c510: 33 31 39 7d 20 41 20 62 75 73 79 20 68 61 6e 64  319} A busy hand
c520: 6c 65 72 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63  ler should not c
c530: 61 6c 6c 20 63 6c 6f 73 65 20 74 68 65 20 64 61  all close the da
c540: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
c550: 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  n.**          or
c560: 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
c570: 65 6e 74 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  ent that invoked
c580: 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
c590: 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  r..*/.int sqlite
c5a0: 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 73  3_busy_handler(s
c5b0: 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28  qlite3*, int(*)(
c5c0: 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64  void*,int), void
c5d0: 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
c5e0: 52 45 46 3a 20 53 65 74 20 41 20 42 75 73 79 20  REF: Set A Busy 
c5f0: 54 69 6d 65 6f 75 74 20 7b 46 31 32 33 34 30 7d  Timeout {F12340}
c600: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
c610: 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71 6c 69  ine sets a [sqli
c620: 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
c630: 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 5d   | busy handler]
c640: 0a 2a 2a 20 74 68 61 74 20 73 6c 65 65 70 73 20  .** that sleeps 
c650: 66 6f 72 20 61 20 77 68 69 6c 65 20 77 68 65 6e  for a while when
c660: 20 61 0a 2a 2a 20 74 61 62 6c 65 20 69 73 20 6c   a.** table is l
c670: 6f 63 6b 65 64 2e 20 20 54 68 65 20 68 61 6e 64  ocked.  The hand
c680: 6c 65 72 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d  ler will sleep m
c690: 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 6e  ultiple times un
c6a0: 74 69 6c 20 0a 2a 2a 20 61 74 20 6c 65 61 73 74  til .** at least
c6b0: 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e   "ms" millisecon
c6c0: 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 20 68  ds of sleeping h
c6d0: 61 76 65 20 62 65 65 6e 20 64 6f 6e 65 2e 20 7b  ave been done. {
c6e0: 46 31 32 33 34 33 7d 20 41 66 74 65 72 0a 2a 2a  F12343} After.**
c6f0: 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e   "ms" millisecon
c700: 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c 20  ds of sleeping, 
c710: 74 68 65 20 68 61 6e 64 6c 65 72 20 72 65 74 75  the handler retu
c720: 72 6e 73 20 30 20 77 68 69 63 68 0a 2a 2a 20 63  rns 0 which.** c
c730: 61 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 73  auses [sqlite3_s
c740: 74 65 70 28 29 5d 20 74 6f 20 72 65 74 75 72 6e  tep()] to return
c750: 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f   [SQLITE_BUSY] o
c760: 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  r [SQLITE_IOERR_
c770: 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20  BLOCKED]..**.** 
c780: 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75  Calling this rou
c790: 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67  tine with an arg
c7a0: 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20  ument less than 
c7b0: 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f  or equal to zero
c7c0: 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c  .** turns off al
c7d0: 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e  l busy handlers.
c7e0: 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 63 61 6e  .**.** There can
c7f0: 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c   only be a singl
c800: 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66  e busy handler f
c810: 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  or a particular 
c820: 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
c830: 65 63 74 69 6f 6e 2e 20 20 49 66 20 61 6e 6f 74  ection.  If anot
c840: 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72  her busy handler
c850: 20 77 61 73 20 64 65 66 69 6e 65 64 20 20 0a 2a   was defined  .*
c860: 2a 20 28 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  * (using [sqlite
c870: 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29  3_busy_handler()
c880: 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c  ]) prior to call
c890: 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74  ing.** this rout
c8a0: 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65 72 20  ine, that other 
c8b0: 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20  busy handler is 
c8c0: 63 6c 65 61 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  cleared..**.** I
c8d0: 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
c8e0: 20 7b 46 31 32 33 34 31 7d 20 54 68 65 20 5b 73   {F12341} The [s
c8f0: 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65  qlite3_busy_time
c900: 6f 75 74 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20  out()] function 
c910: 6f 76 65 72 72 69 64 65 73 20 61 6e 79 20 70 72  overrides any pr
c920: 69 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ior.**          
c930: 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69  [sqlite3_busy_ti
c940: 6d 65 6f 75 74 28 29 5d 20 6f 72 20 5b 73 71 6c  meout()] or [sql
c950: 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
c960: 72 28 29 5d 20 73 65 74 74 69 6e 67 0a 2a 2a 20  r()] setting.** 
c970: 20 20 20 20 20 20 20 20 20 6f 6e 20 74 68 65 20           on the 
c980: 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
c990: 6e 6e 65 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  nnection..**.** 
c9a0: 7b 46 31 32 33 34 33 7d 20 49 66 20 74 68 65 20  {F12343} If the 
c9b0: 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  2nd parameter to
c9c0: 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74   [sqlite3_busy_t
c9d0: 69 6d 65 6f 75 74 28 29 5d 20 69 73 20 6c 65 73  imeout()] is les
c9e0: 73 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20 20  s than.**       
c9f0: 20 20 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a     or equal to z
ca00: 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 62 75  ero, then the bu
ca10: 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c  sy handler is cl
ca20: 65 61 72 65 64 20 73 6f 20 74 68 61 74 0a 2a 2a  eared so that.**
ca30: 20 20 20 20 20 20 20 20 20 20 61 6c 6c 20 73 75            all su
ca40: 62 73 65 71 75 65 6e 74 20 6c 6f 63 6b 69 6e 67  bsequent locking
ca50: 20 65 76 65 6e 74 73 20 69 6d 6d 65 64 69 61 74   events immediat
ca60: 65 6c 79 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ely return [SQLI
ca70: 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20  TE_BUSY]..**.** 
ca80: 7b 46 31 32 33 34 34 7d 20 49 66 20 74 68 65 20  {F12344} If the 
ca90: 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  2nd parameter to
caa0: 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74   [sqlite3_busy_t
cab0: 69 6d 65 6f 75 74 28 29 5d 20 69 73 20 61 20 70  imeout()] is a p
cac0: 6f 73 69 74 69 76 65 0a 2a 2a 20 20 20 20 20 20  ositive.**      
cad0: 20 20 20 20 6e 75 6d 62 65 72 20 4e 2c 20 74 68      number N, th
cae0: 65 6e 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65  en a busy handle
caf0: 72 20 69 73 20 73 65 74 20 74 68 61 74 20 72 65  r is set that re
cb00: 70 65 61 74 65 64 6c 79 20 63 61 6c 6c 73 0a 2a  peatedly calls.*
cb10: 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 78  *          the x
cb20: 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20 69  Sleep() method i
cb30: 6e 20 74 68 65 20 56 46 53 20 69 6e 74 65 72 66  n the VFS interf
cb40: 61 63 65 20 75 6e 74 69 6c 20 65 69 74 68 65 72  ace until either
cb50: 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
cb60: 20 6c 6f 63 6b 20 63 6c 65 61 72 73 20 6f 72 20   lock clears or 
cb70: 75 6e 74 69 6c 20 74 68 65 20 63 75 6d 75 6c 61  until the cumula
cb80: 74 69 76 65 20 73 6c 65 65 70 20 74 69 6d 65 20  tive sleep time 
cb90: 72 65 70 6f 72 74 65 64 20 62 61 63 6b 0a 2a 2a  reported back.**
cba0: 20 20 20 20 20 20 20 20 20 20 62 79 20 78 53 6c            by xSl
cbb0: 65 65 70 28 29 20 65 78 63 65 65 64 73 20 4e 20  eep() exceeds N 
cbc0: 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 2e 0a 2a 2f  milliseconds..*/
cbd0: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73  .int sqlite3_bus
cbe0: 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65  y_timeout(sqlite
cbf0: 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a  3*, int ms);../*
cc00: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
cc10: 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e  nvenience Routin
cc20: 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51  es For Running Q
cc30: 75 65 72 69 65 73 20 7b 46 31 32 33 37 30 7d 0a  ueries {F12370}.
cc40: 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e  **.** Definition
cc50: 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74 20 74 61  : A <b>result ta
cc60: 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72  ble</b> is memor
cc70: 79 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65  y data structure
cc80: 20 63 72 65 61 74 65 64 20 62 79 20 74 68 65 0a   created by the.
cc90: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  ** [sqlite3_get_
cca0: 74 61 62 6c 65 28 29 5d 20 69 6e 74 65 72 66 61  table()] interfa
ccb0: 63 65 2e 20 20 41 20 72 65 73 75 6c 74 20 74 61  ce.  A result ta
ccc0: 62 6c 65 20 72 65 63 6f 72 64 73 20 74 68 65 0a  ble records the.
ccd0: 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75 65 72  ** complete quer
cce0: 79 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f  y results from o
ccf0: 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75 65 72 69  ne or more queri
cd00: 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61  es..**.** The ta
cd10: 62 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79  ble conceptually
cd20: 20 68 61 73 20 61 20 6e 75 6d 62 65 72 20 6f 66   has a number of
cd30: 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e   rows and column
cd40: 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65 73 65  s.  But.** these
cd50: 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6e 6f 74   numbers are not
cd60: 20 70 61 72 74 20 6f 66 20 74 68 65 20 72 65 73   part of the res
cd70: 75 6c 74 20 74 61 62 6c 65 20 69 74 73 65 6c 66  ult table itself
cd80: 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62  .  These.** numb
cd90: 65 72 73 20 61 72 65 20 6f 62 74 61 69 6e 65 64  ers are obtained
cda0: 20 73 65 70 61 72 61 74 65 6c 79 2e 20 20 4c 65   separately.  Le
cdb0: 74 20 4e 20 62 65 20 74 68 65 20 6e 75 6d 62 65  t N be the numbe
cdc0: 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64  r of rows.** and
cdd0: 20 4d 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72   M be the number
cde0: 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a   of columns..**.
cdf0: 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c  ** A result tabl
ce00: 65 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  e is an array of
ce10: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65 72   pointers to zer
ce20: 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
ce30: 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 20 20  UTF-8 strings.  
ce40: 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31 29 2a  There are (N+1)*
ce50: 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68  M elements in th
ce60: 65 20 61 72 72 61 79 2e 20 20 0a 2a 2a 20 54 68  e array.  .** Th
ce70: 65 20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65  e first M pointe
ce80: 72 73 20 70 6f 69 6e 74 20 74 6f 20 7a 65 72 6f  rs point to zero
ce90: 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69  -terminated stri
cea0: 6e 67 73 20 74 68 61 74 20 0a 2a 2a 20 63 6f 6e  ngs that .** con
ceb0: 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f  tain the names o
cec0: 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a  f the columns..*
ced0: 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20  * The remaining 
cee0: 65 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e  entries all poin
cef0: 74 20 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c  t to query resul
cf00: 74 73 2e 20 20 4e 55 4c 4c 0a 2a 2a 20 76 61 6c  ts.  NULL.** val
cf10: 75 65 73 20 61 72 65 20 67 69 76 65 20 61 20 4e  ues are give a N
cf20: 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 41 6c  ULL pointer.  Al
cf30: 6c 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61  l other values a
cf40: 72 65 20 69 6e 0a 2a 2a 20 74 68 65 69 72 20 55  re in.** their U
cf50: 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  TF-8 zero-termin
cf60: 61 74 65 64 20 73 74 72 69 6e 67 20 72 65 70 72  ated string repr
cf70: 65 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65  esentation as re
cf80: 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71  turned by.** [sq
cf90: 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
cfa0: 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65  t()]..**.** A re
cfb0: 73 75 6c 74 20 74 61 62 6c 65 20 6d 69 67 68 74  sult table might
cfc0: 20 63 6f 6e 73 69 73 74 73 20 6f 66 20 6f 6e 65   consists of one
cfd0: 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20   or more memory 
cfe0: 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20  allocations..** 
cff0: 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74  It is not safe t
d000: 6f 20 70 61 73 73 20 61 20 72 65 73 75 6c 74 20  o pass a result 
d010: 74 61 62 6c 65 20 64 69 72 65 63 74 6c 79 20 74  table directly t
d020: 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  o [sqlite3_free(
d030: 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20  )]..** A result 
d040: 74 61 62 6c 65 20 73 68 6f 75 6c 64 20 62 65 20  table should be 
d050: 64 65 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e  deallocated usin
d060: 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  g [sqlite3_free_
d070: 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  table()]..**.** 
d080: 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66  As an example of
d090: 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
d0a0: 65 20 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73  e format, suppos
d0b0: 65 20 61 20 71 75 65 72 79 20 72 65 73 75 6c 74  e a query result
d0c0: 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77  .** is as follow
d0d0: 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
d0e0: 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20  uote><pre>.**   
d0f0: 20 20 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20       Name       
d100: 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20   | Age.**       
d110: 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d   ---------------
d120: 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20  --------.**     
d130: 20 20 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c     Alice       |
d140: 20 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f   43.**        Bo
d150: 62 20 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a  b         | 28.*
d160: 2a 20 20 20 20 20 20 20 20 43 69 6e 64 79 20 20  *        Cindy  
d170: 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70       | 21.** </p
d180: 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
d190: 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65  .**.** There are
d1a0: 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d   two column (M==
d1b0: 32 29 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77  2) and three row
d1c0: 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20  s (N==3).  Thus 
d1d0: 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61  the.** result ta
d1e0: 62 6c 65 20 68 61 73 20 38 20 65 6e 74 72 69 65  ble has 8 entrie
d1f0: 73 2e 20 20 53 75 70 70 6f 73 65 20 74 68 65 20  s.  Suppose the 
d200: 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20  result table is 
d210: 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20  stored.** in an 
d220: 61 72 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65  array names azRe
d230: 73 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65  sult.  Then azRe
d240: 73 75 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20  sult holds this 
d250: 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c  content:.**.** <
d260: 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
d270: 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
d280: 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61  ult&#91;0] = "Na
d290: 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  me";.**        a
d2a0: 7a 52 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d  zResult&#91;1] =
d2b0: 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20   "Age";.**      
d2c0: 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32    azResult&#91;2
d2d0: 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20  ] = "Alice";.** 
d2e0: 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
d2f0: 23 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a  #91;3] = "43";.*
d300: 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
d310: 74 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22  t&#91;4] = "Bob"
d320: 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
d330: 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32  sult&#91;5] = "2
d340: 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  8";.**        az
d350: 52 65 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20  Result&#91;6] = 
d360: 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20  "Cindy";.**     
d370: 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
d380: 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f  7] = "21";.** </
d390: 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
d3a0: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  >.**.** The sqli
d3b0: 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20  te3_get_table() 
d3c0: 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74  function evaluat
d3d0: 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a  es one or more.*
d3e0: 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61  * semicolon-sepa
d3f0: 72 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d  rated SQL statem
d400: 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f  ents in the zero
d410: 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
d420: 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69  8.** string of i
d430: 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  ts 2nd parameter
d440: 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20 61 20  .  It returns a 
d450: 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20  result table to 
d460: 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67  the.** pointer g
d470: 69 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20  iven in its 3rd 
d480: 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
d490: 20 41 66 74 65 72 20 74 68 65 20 63 61 6c 6c 69   After the calli
d4a0: 6e 67 20 66 75 6e 63 74 69 6f 6e 20 68 61 73 20  ng function has 
d4b0: 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74  finished using t
d4c0: 68 65 20 72 65 73 75 6c 74 2c 20 69 74 20 73 68  he result, it sh
d4d0: 6f 75 6c 64 20 0a 2a 2a 20 70 61 73 73 20 74 68  ould .** pass th
d4e0: 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  e pointer to the
d4f0: 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f   result table to
d500: 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61   sqlite3_free_ta
d510: 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20 74  ble() in order t
d520: 6f 20 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68  o .** release th
d530: 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61  e memory that wa
d540: 73 20 6d 61 6c 6c 6f 63 2d 65 64 2e 20 20 42 65  s malloc-ed.  Be
d550: 63 61 75 73 65 20 6f 66 20 74 68 65 20 77 61 79  cause of the way
d560: 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65   the .** [sqlite
d570: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70  3_malloc()] happ
d580: 65 6e 73 20 77 69 74 68 69 6e 20 73 71 6c 69 74  ens within sqlit
d590: 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 20  e3_get_table(), 
d5a0: 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66  the calling.** f
d5b0: 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  unction must not
d5c0: 20 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71   try to call [sq
d5d0: 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 64 69  lite3_free()] di
d5e0: 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 20 0a 2a  rectly.  Only .*
d5f0: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  * [sqlite3_free_
d600: 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62 6c 65  table()] is able
d610: 20 74 6f 20 72 65 6c 65 61 73 65 20 74 68 65 20   to release the 
d620: 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79 20  memory properly 
d630: 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a  and safely..**.*
d640: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65  * The sqlite3_ge
d650: 74 5f 74 61 62 6c 65 28 29 20 69 6e 74 65 72 66  t_table() interf
d660: 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74  ace is implement
d670: 65 64 20 61 73 20 61 20 77 72 61 70 70 65 72 20  ed as a wrapper 
d680: 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  around.** [sqlit
d690: 65 33 5f 65 78 65 63 28 29 5d 2e 20 20 54 68 65  e3_exec()].  The
d6a0: 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
d6b0: 6c 65 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65  le() routine doe
d6c0: 73 20 6e 6f 74 20 68 61 76 65 20 61 63 63 65 73  s not have acces
d6d0: 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65  s.** to any inte
d6e0: 72 6e 61 6c 20 64 61 74 61 20 73 74 72 75 63 74  rnal data struct
d6f0: 75 72 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20  ures of SQLite. 
d700: 20 49 74 20 75 73 65 73 20 6f 6e 6c 79 20 74 68   It uses only th
d710: 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65  e public.** inte
d720: 72 66 61 63 65 20 64 65 66 69 6e 65 64 20 68 65  rface defined he
d730: 72 65 2e 20 20 41 73 20 61 20 63 6f 6e 73 65 71  re.  As a conseq
d740: 75 65 6e 63 65 2c 20 65 72 72 6f 72 73 20 74 68  uence, errors th
d750: 61 74 20 6f 63 63 75 72 20 69 6e 20 74 68 65 0a  at occur in the.
d760: 2a 2a 20 77 72 61 70 70 65 72 20 6c 61 79 65 72  ** wrapper layer
d770: 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20   outside of the 
d780: 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65  internal [sqlite
d790: 33 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c 20 61  3_exec()] call a
d7a0: 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63  re not.** reflec
d7b0: 74 65 64 20 69 6e 20 73 75 62 73 65 71 75 65 6e  ted in subsequen
d7c0: 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  t calls to [sqli
d7d0: 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f  te3_errcode()] o
d7e0: 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72  r.** [sqlite3_er
d7f0: 72 6d 73 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49  rmsg()]..**.** I
d800: 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
d810: 20 7b 46 31 32 33 37 31 7d 20 49 66 20 61 20 5b   {F12371} If a [
d820: 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
d830: 65 28 29 5d 20 66 61 69 6c 73 20 61 20 6d 65 6d  e()] fails a mem
d840: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20  ory allocation, 
d850: 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  then.**         
d860: 20 69 74 20 66 72 65 65 73 20 74 68 65 20 72 65   it frees the re
d870: 73 75 6c 74 20 74 61 62 6c 65 20 75 6e 64 65 72  sult table under
d880: 20 63 6f 6e 73 74 72 75 63 74 69 6f 6e 2c 20 61   construction, a
d890: 62 6f 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20  borts the.**    
d8a0: 20 20 20 20 20 20 71 75 65 72 79 20 69 6e 20 70        query in p
d8b0: 72 6f 63 65 73 73 2c 20 73 6b 69 70 73 20 61 6e  rocess, skips an
d8c0: 79 20 73 75 62 73 65 71 75 65 6e 74 20 71 75 65  y subsequent que
d8d0: 72 69 65 73 2c 20 73 65 74 73 20 74 68 65 0a 2a  ries, sets the.*
d8e0: 2a 20 20 20 20 20 20 20 20 20 20 2a 72 65 73 75  *          *resu
d8f0: 6c 74 70 20 6f 75 74 70 75 74 20 70 6f 69 6e 74  ltp output point
d900: 65 72 20 74 6f 20 4e 55 4c 4c 20 61 6e 64 20 72  er to NULL and r
d910: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4e  eturns [SQLITE_N
d920: 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  OMEM]..**.** {F1
d930: 32 33 37 33 7d 20 49 66 20 74 68 65 20 6e 63 6f  2373} If the nco
d940: 6c 75 6d 6e 20 70 61 72 61 6d 65 74 65 72 20 74  lumn parameter t
d950: 6f 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  o [sqlite3_get_t
d960: 61 62 6c 65 28 29 5d 20 69 73 20 6e 6f 74 20 4e  able()] is not N
d970: 55 4c 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ULL.**          
d980: 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 67 65  then [sqlite3_ge
d990: 74 5f 74 61 62 6c 65 28 29 5d 20 77 72 69 74 65  t_table()] write
d9a0: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
d9b0: 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a  olumns in the.**
d9c0: 20 20 20 20 20 20 20 20 20 20 72 65 73 75 6c 74            result
d9d0: 20 73 65 74 20 6f 66 20 74 68 65 20 71 75 65 72   set of the quer
d9e0: 79 20 69 6e 74 6f 20 2a 6e 63 6f 6c 75 6d 6e 20  y into *ncolumn 
d9f0: 69 66 20 74 68 65 20 71 75 65 72 79 20 69 73 0a  if the query is.
da00: 2a 2a 20 20 20 20 20 20 20 20 20 20 73 75 63 63  **          succ
da10: 65 73 73 66 75 6c 20 28 69 66 20 74 68 65 20 66  essful (if the f
da20: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
da30: 53 51 4c 49 54 45 5f 4f 4b 29 2e 0a 2a 2a 0a 2a  SQLITE_OK)..**.*
da40: 2a 20 7b 46 31 32 33 37 34 7d 20 49 66 20 74 68  * {F12374} If th
da50: 65 20 6e 72 6f 77 20 70 61 72 61 6d 65 74 65 72  e nrow parameter
da60: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 67 65 74   to [sqlite3_get
da70: 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 6e 6f 74  _table()] is not
da80: 20 4e 55 4c 4c 0a 2a 2a 20 20 20 20 20 20 20 20   NULL.**        
da90: 20 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f    then [sqlite3_
daa0: 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 77 72 69  get_table()] wri
dab0: 74 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  te the number of
dac0: 20 72 6f 77 73 20 69 6e 20 74 68 65 0a 2a 2a 20   rows in the.** 
dad0: 20 20 20 20 20 20 20 20 20 72 65 73 75 6c 74 20           result 
dae0: 73 65 74 20 6f 66 20 74 68 65 20 71 75 65 72 79  set of the query
daf0: 20 69 6e 74 6f 20 2a 6e 72 6f 77 20 69 66 20 74   into *nrow if t
db00: 68 65 20 71 75 65 72 79 20 69 73 0a 2a 2a 20 20  he query is.**  
db10: 20 20 20 20 20 20 20 20 73 75 63 63 65 73 73 66          successf
db20: 75 6c 20 28 69 66 20 74 68 65 20 66 75 6e 63 74  ul (if the funct
db30: 69 6f 6e 20 72 65 74 75 72 6e 73 20 53 51 4c 49  ion returns SQLI
db40: 54 45 5f 4f 4b 29 2e 0a 2a 2a 0a 2a 2a 20 7b 46  TE_OK)..**.** {F
db50: 31 32 33 37 36 7d 20 54 68 65 20 5b 73 71 6c 69  12376} The [sqli
db60: 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d  te3_get_table()]
db70: 20 66 75 6e 63 74 69 6f 6e 20 73 65 74 73 20 69   function sets i
db80: 74 73 20 2a 6e 63 6f 6c 75 6d 6e 20 76 61 6c 75  ts *ncolumn valu
db90: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f  e.**          to
dba0: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
dbb0: 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65  olumns in the re
dbc0: 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68 65 20  sult set of the 
dbd0: 71 75 65 72 79 20 69 6e 20 74 68 65 0a 2a 2a 20  query in the.** 
dbe0: 20 20 20 20 20 20 20 20 20 73 71 6c 20 70 61 72           sql par
dbf0: 61 6d 65 74 65 72 2c 20 6f 72 20 74 6f 20 7a 65  ameter, or to ze
dc00: 72 6f 20 69 66 20 74 68 65 20 71 75 65 72 79 20  ro if the query 
dc10: 69 6e 20 73 71 6c 20 68 61 73 20 61 6e 20 65 6d  in sql has an em
dc20: 70 74 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  pty.**          
dc30: 72 65 73 75 6c 74 20 73 65 74 2e 0a 2a 2f 0a 69  result set..*/.i
dc40: 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  nt sqlite3_get_t
dc50: 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 2a  able(.  sqlite3*
dc60: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  ,             /*
dc70: 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   An open databas
dc80: 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
dc90: 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 2f 2a 20  r *sql,      /* 
dca0: 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61  SQL to be evalua
dcb0: 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a  ted */.  char **
dcc0: 2a 70 52 65 73 75 6c 74 2c 20 20 20 20 20 20 2f  *pResult,      /
dcd0: 2a 20 52 65 73 75 6c 74 73 20 6f 66 20 74 68 65  * Results of the
dce0: 20 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20   query */.  int 
dcf0: 2a 6e 72 6f 77 2c 20 20 20 20 20 20 20 20 20 20  *nrow,          
dd00: 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72    /* Number of r
dd10: 65 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74 74  esult rows writt
dd20: 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74  en here */.  int
dd30: 20 2a 6e 63 6f 6c 75 6d 6e 2c 20 20 20 20 20 20   *ncolumn,      
dd40: 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20     /* Number of 
dd50: 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77  result columns w
dd60: 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20  ritten here */. 
dd70: 20 63 68 61 72 20 2a 2a 65 72 72 6d 73 67 20 20   char **errmsg  
dd80: 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20         /* Error 
dd90: 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65  msg written here
dda0: 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71 6c 69   */.);.void sqli
ddb0: 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 63  te3_free_table(c
ddc0: 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a  har **result);..
ddd0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
dde0: 46 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e 67  Formatted String
ddf0: 20 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 69   Printing Functi
de00: 6f 6e 73 20 7b 46 31 37 34 30 30 7d 0a 2a 2a 0a  ons {F17400}.**.
de10: 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
de20: 73 20 61 72 65 20 77 6f 72 6b 61 6c 69 6b 65 73  s are workalikes
de30: 20 6f 66 20 74 68 65 20 22 70 72 69 6e 74 66 28   of the "printf(
de40: 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e  )" family of fun
de50: 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74  ctions.** from t
de60: 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
de70: 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  brary..**.** The
de80: 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
de90: 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76  () and sqlite3_v
dea0: 6d 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e  mprintf() routin
deb0: 65 73 20 77 72 69 74 65 20 74 68 65 69 72 0a 2a  es write their.*
dec0: 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d  * results into m
ded0: 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
dee0: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
def0: 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73  loc()]..** The s
df00: 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20  trings returned 
df10: 62 79 20 74 68 65 73 65 20 74 77 6f 20 72 6f 75  by these two rou
df20: 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 0a  tines should be.
df30: 2a 2a 20 72 65 6c 65 61 73 65 64 20 62 79 20 5b  ** released by [
df40: 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e  sqlite3_free()].
df50: 20 20 20 42 6f 74 68 20 72 6f 75 74 69 6e 65 73     Both routines
df60: 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c   return a.** NUL
df70: 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 5b 73 71  L pointer if [sq
df80: 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
df90: 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c  is unable to all
dfa0: 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20  ocate enough.** 
dfb0: 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  memory to hold t
dfc0: 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72  he resulting str
dfd0: 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 73 71  ing..**.** In sq
dfe0: 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
dff0: 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69   routine is simi
e000: 6c 61 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 66  lar to "snprintf
e010: 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20  ()" from.** the 
e020: 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
e030: 72 79 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20  ry.  The result 
e040: 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  is written into 
e050: 74 68 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 75  the.** buffer su
e060: 70 70 6c 69 65 64 20 61 73 20 74 68 65 20 73 65  pplied as the se
e070: 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 77  cond parameter w
e080: 68 6f 73 65 20 73 69 7a 65 20 69 73 20 67 69 76  hose size is giv
e090: 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72  en by.** the fir
e0a0: 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f  st parameter. No
e0b0: 74 65 20 74 68 61 74 20 74 68 65 20 6f 72 64 65  te that the orde
e0c0: 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73  r of the.** firs
e0d0: 74 20 74 77 6f 20 70 61 72 61 6d 65 74 65 72 73  t two parameters
e0e0: 20 69 73 20 72 65 76 65 72 73 65 64 20 66 72 6f   is reversed fro
e0f0: 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e 20 20 54  m snprintf().  T
e100: 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73  his is an.** his
e110: 74 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74  torical accident
e120: 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20   that cannot be 
e130: 66 69 78 65 64 20 77 69 74 68 6f 75 74 20 62 72  fixed without br
e140: 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61  eaking.** backwa
e150: 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
e160: 79 2e 20 20 4e 6f 74 65 20 61 6c 73 6f 20 74 68  y.  Note also th
e170: 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  at sqlite3_snpri
e180: 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73  ntf().** returns
e190: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74   a pointer to it
e1a0: 73 20 62 75 66 66 65 72 20 69 6e 73 74 65 61 64  s buffer instead
e1b0: 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   of the number o
e1c0: 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20  f.** characters 
e1d0: 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e  actually written
e1e0: 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72   into the buffer
e1f0: 2e 20 20 57 65 20 61 64 6d 69 74 20 74 68 61 74  .  We admit that
e200: 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
e210: 66 20 63 68 61 72 61 63 74 65 72 73 20 77 72 69  f characters wri
e220: 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 20  tten would be a 
e230: 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74 75  more useful retu
e240: 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 20  rn.** value but 
e250: 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65  we cannot change
e260: 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
e270: 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73  ion of sqlite3_s
e280: 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77  nprintf().** now
e290: 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e   without breakin
e2a0: 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  g compatibility.
e2b0: 0a 2a 2a 0a 2a 2a 20 41 73 20 6c 6f 6e 67 20 61  .**.** As long a
e2c0: 73 20 74 68 65 20 62 75 66 66 65 72 20 73 69 7a  s the buffer siz
e2d0: 65 20 69 73 20 67 72 65 61 74 65 72 20 74 68 61  e is greater tha
e2e0: 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f  n zero, sqlite3_
e2f0: 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75  snprintf().** gu
e300: 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68  arantees that th
e310: 65 20 62 75 66 66 65 72 20 69 73 20 61 6c 77 61  e buffer is alwa
e320: 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  ys zero-terminat
e330: 65 64 2e 20 20 54 68 65 20 66 69 72 73 74 0a 2a  ed.  The first.*
e340: 2a 20 70 61 72 61 6d 65 74 65 72 20 22 6e 22 20  * parameter "n" 
e350: 69 73 20 74 68 65 20 74 6f 74 61 6c 20 73 69 7a  is the total siz
e360: 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 2c  e of the buffer,
e370: 20 69 6e 63 6c 75 64 69 6e 67 20 73 70 61 63 65   including space
e380: 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f   for.** the zero
e390: 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f   terminator.  So
e3a0: 20 74 68 65 20 6c 6f 6e 67 65 73 74 20 73 74 72   the longest str
e3b0: 69 6e 67 20 74 68 61 74 20 63 61 6e 20 62 65 20  ing that can be 
e3c0: 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72  completely.** wr
e3d0: 69 74 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d  itten will be n-
e3e0: 31 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a  1 characters..**
e3f0: 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
e400: 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74  es all implement
e410: 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c   some additional
e420: 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f   formatting.** o
e430: 70 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20  ptions that are 
e440: 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74  useful for const
e450: 72 75 63 74 69 6e 67 20 53 51 4c 20 73 74 61 74  ructing SQL stat
e460: 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f  ements..** All o
e470: 66 20 74 68 65 20 75 73 75 61 6c 20 70 72 69 6e  f the usual prin
e480: 74 66 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70  tf formatting op
e490: 74 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e  tions apply.  In
e4a0: 20 61 64 64 69 74 69 6f 6e 2c 20 74 68 65 72 65   addition, there
e4b0: 0a 2a 2a 20 69 73 20 61 72 65 20 22 25 71 22 2c  .** is are "%q",
e4c0: 20 22 25 51 22 2c 20 61 6e 64 20 22 25 7a 22 20   "%Q", and "%z" 
e4d0: 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54  options..**.** T
e4e0: 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72  he %q option wor
e4f0: 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68  ks like %s in th
e500: 61 74 20 69 74 20 73 75 62 73 74 69 74 75 74 65  at it substitute
e510: 73 20 61 20 6e 75 6c 6c 2d 74 65 72 6d 69 6e 61  s a null-termina
e520: 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72  ted.** string fr
e530: 6f 6d 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20  om the argument 
e540: 6c 69 73 74 2e 20 20 42 75 74 20 25 71 20 61 6c  list.  But %q al
e550: 73 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 72 79  so doubles every
e560: 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 2e   '\'' character.
e570: 0a 2a 2a 20 25 71 20 69 73 20 64 65 73 69 67 6e  .** %q is design
e580: 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64  ed for use insid
e590: 65 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72  e a string liter
e5a0: 61 6c 2e 20 20 42 79 20 64 6f 75 62 6c 69 6e 67  al.  By doubling
e5b0: 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68   each '\''.** ch
e5c0: 61 72 61 63 74 65 72 20 69 74 20 65 73 63 61 70  aracter it escap
e5d0: 65 73 20 74 68 61 74 20 63 68 61 72 61 63 74 65  es that characte
e5e0: 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20  r and allows it 
e5f0: 74 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20 69  to be inserted i
e600: 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e  nto.** the strin
e610: 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61  g..**.** For exa
e620: 6d 70 6c 65 2c 20 73 6f 20 73 6f 6d 65 20 73 74  mple, so some st
e630: 72 69 6e 67 20 76 61 72 69 61 62 6c 65 20 63 6f  ring variable co
e640: 6e 74 61 69 6e 73 20 74 65 78 74 20 61 73 20 66  ntains text as f
e650: 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
e660: 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
e670: 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65 78 74 20  **  char *zText 
e680: 3d 20 22 49 74 27 73 20 61 20 68 61 70 70 79 20  = "It's a happy 
e690: 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  day!";.** </pre>
e6a0: 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
e6b0: 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65 20  .** One can use 
e6c0: 74 68 69 73 20 74 65 78 74 20 69 6e 20 61 6e 20  this text in an 
e6d0: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73  SQL statement as
e6e0: 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
e6f0: 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
e700: 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c  >.**  char *zSQL
e710: 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e   = sqlite3_mprin
e720: 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20  tf("INSERT INTO 
e730: 74 61 62 6c 65 20 56 41 4c 55 45 53 28 27 25 71  table VALUES('%q
e740: 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20  ')", zText);.** 
e750: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62   sqlite3_exec(db
e760: 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29  , zSQL, 0, 0, 0)
e770: 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72  ;.**  sqlite3_fr
e780: 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70  ee(zSQL);.** </p
e790: 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
e7a0: 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74  .**.** Because t
e7b0: 68 65 20 25 71 20 66 6f 72 6d 61 74 20 73 74 72  he %q format str
e7c0: 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65  ing is used, the
e7d0: 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 20   '\'' character 
e7e0: 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65  in zText.** is e
e7f0: 73 63 61 70 65 64 20 61 6e 64 20 74 68 65 20 53  scaped and the S
e800: 51 4c 20 67 65 6e 65 72 61 74 65 64 20 69 73 20  QL generated is 
e810: 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
e820: 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
e830: 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49  re>.**  INSERT I
e840: 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45  NTO table1 VALUE
e850: 53 28 27 49 74 27 27 73 20 61 20 68 61 70 70 79  S('It''s a happy
e860: 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65   day!').** </pre
e870: 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
e880: 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 63 6f 72  *.** This is cor
e890: 72 65 63 74 2e 20 20 48 61 64 20 77 65 20 75 73  rect.  Had we us
e8a0: 65 64 20 25 73 20 69 6e 73 74 65 61 64 20 6f 66  ed %s instead of
e8b0: 20 25 71 2c 20 74 68 65 20 67 65 6e 65 72 61 74   %q, the generat
e8c0: 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20  ed SQL.** would 
e8d0: 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65  have looked like
e8e0: 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c   this:.**.** <bl
e8f0: 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
e900: 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74  *  INSERT INTO t
e910: 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74  able1 VALUES('It
e920: 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27  's a happy day!'
e930: 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
e940: 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
e950: 54 68 69 73 20 73 65 63 6f 6e 64 20 65 78 61 6d  This second exam
e960: 70 6c 65 20 69 73 20 61 6e 20 53 51 4c 20 73 79  ple is an SQL sy
e970: 6e 74 61 78 20 65 72 72 6f 72 2e 20 20 41 73 20  ntax error.  As 
e980: 61 20 67 65 6e 65 72 61 6c 20 72 75 6c 65 20 79  a general rule y
e990: 6f 75 0a 2a 2a 20 73 68 6f 75 6c 64 20 61 6c 77  ou.** should alw
e9a0: 61 79 73 20 75 73 65 20 25 71 20 69 6e 73 74 65  ays use %q inste
e9b0: 61 64 20 6f 66 20 25 73 20 77 68 65 6e 20 69 6e  ad of %s when in
e9c0: 73 65 72 74 69 6e 67 20 74 65 78 74 20 69 6e 74  serting text int
e9d0: 6f 20 61 20 73 74 72 69 6e 67 20 0a 2a 2a 20 6c  o a string .** l
e9e0: 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68  iteral..**.** Th
e9f0: 65 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b  e %Q option work
ea00: 73 20 6c 69 6b 65 20 25 71 20 65 78 63 65 70 74  s like %q except
ea10: 20 69 74 20 61 6c 73 6f 20 61 64 64 73 20 73 69   it also adds si
ea20: 6e 67 6c 65 20 71 75 6f 74 65 73 20 61 72 6f 75  ngle quotes arou
ea30: 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69 64  nd.** the outsid
ea40: 65 20 6f 66 20 74 68 65 20 74 6f 74 61 6c 20 73  e of the total s
ea50: 74 72 69 6e 67 2e 20 20 4f 72 20 69 66 20 74 68  tring.  Or if th
ea60: 65 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74  e parameter in t
ea70: 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6c  he argument.** l
ea80: 69 73 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ist is a NULL po
ea90: 69 6e 74 65 72 2c 20 25 51 20 73 75 62 73 74 69  inter, %Q substi
eaa0: 74 75 74 65 73 20 74 68 65 20 74 65 78 74 20 22  tutes the text "
eab0: 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75 74 20 73  NULL" (without s
eac0: 69 6e 67 6c 65 0a 2a 2a 20 71 75 6f 74 65 73 29  ingle.** quotes)
ead0: 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65   in place of the
eae0: 20 25 51 20 6f 70 74 69 6f 6e 2e 20 7b 45 4e 44   %Q option. {END
eaf0: 7d 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70  }  So, for examp
eb00: 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61  le, one could sa
eb10: 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  y:.**.** <blockq
eb20: 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63  uote><pre>.**  c
eb30: 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69  har *zSQL = sqli
eb40: 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53  te3_mprintf("INS
eb50: 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56  ERT INTO table V
eb60: 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78  ALUES(%Q)", zTex
eb70: 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  t);.**  sqlite3_
eb80: 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30  exec(db, zSQL, 0
eb90: 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c  , 0, 0);.**  sql
eba0: 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b  ite3_free(zSQL);
ebb0: 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
ebc0: 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
ebd0: 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c  e code above wil
ebe0: 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65  l render a corre
ebf0: 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ct SQL statement
ec00: 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20   in the zSQL.** 
ec10: 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66  variable even if
ec20: 20 74 68 65 20 7a 54 65 78 74 20 76 61 72 69 61   the zText varia
ec30: 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ble is a NULL po
ec40: 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  inter..**.** The
ec50: 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67   "%z" formatting
ec60: 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 65 78   option works ex
ec70: 61 63 74 6c 79 20 6c 69 6b 65 20 22 25 73 22 20  actly like "%s" 
ec80: 77 69 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69  with the.** addi
ec90: 74 69 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20  tion that after 
eca0: 74 68 65 20 73 74 72 69 6e 67 20 68 61 73 20 62  the string has b
ecb0: 65 65 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70  een read and cop
ecc0: 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20  ied into.** the 
ecd0: 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33  result, [sqlite3
ece0: 5f 66 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c  _free()] is call
ecf0: 65 64 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20  ed on the input 
ed00: 73 74 72 69 6e 67 2e 20 7b 45 4e 44 7d 0a 2a 2a  string. {END}.**
ed10: 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
ed20: 2a 2a 0a 2a 2a 20 7b 46 31 37 34 30 33 7d 20 20  **.** {F17403}  
ed30: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72  The [sqlite3_mpr
ed40: 69 6e 74 66 28 29 5d 20 61 6e 64 20 5b 73 71 6c  intf()] and [sql
ed50: 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 5d  ite3_vmprintf()]
ed60: 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 20   interfaces.**  
ed70: 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20           return 
ed80: 65 69 74 68 65 72 20 70 6f 69 6e 74 65 72 73 20  either pointers 
ed90: 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  to zero-terminat
eda0: 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73  ed UTF-8 strings
edb0: 20 68 65 6c 64 20 69 6e 0a 2a 2a 20 20 20 20 20   held in.**     
edc0: 20 20 20 20 20 20 6d 65 6d 6f 72 79 20 6f 62 74        memory obt
edd0: 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
ede0: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72  te3_malloc()] or
edf0: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 69   NULL pointers i
ee00: 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 61  f.**           a
ee10: 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
ee20: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66 61 69 6c  3_malloc()] fail
ee30: 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 34 30 36  s..**.** {F17406
ee40: 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  }  The [sqlite3_
ee50: 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 6e 74 65  snprintf()] inte
ee60: 72 66 61 63 65 20 77 72 69 74 65 73 20 61 20 7a  rface writes a z
ee70: 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
ee80: 2a 20 20 20 20 20 20 20 20 20 20 20 55 54 46 2d  *           UTF-
ee90: 38 20 73 74 72 69 6e 67 20 69 6e 74 6f 20 74 68  8 string into th
eea0: 65 20 62 75 66 66 65 72 20 70 6f 69 6e 74 65 64  e buffer pointed
eeb0: 20 74 6f 20 62 79 20 74 68 65 20 73 65 63 6f 6e   to by the secon
eec0: 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20  d parameter.**  
eed0: 20 20 20 20 20 20 20 20 20 70 72 6f 76 69 64 65           provide
eee0: 64 20 74 68 61 74 20 74 68 65 20 66 69 72 73 74  d that the first
eef0: 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 67 72   parameter is gr
ef00: 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2e  eater than zero.
ef10: 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 34 30 37 7d 20  .**.** {F17407} 
ef20: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 6e   The [sqlite3_sn
ef30: 70 72 69 6e 74 66 28 29 5d 20 69 6e 74 65 72 66  printf()] interf
ef40: 61 63 65 20 64 6f 65 73 20 6e 6f 74 20 77 72 69  ace does not wri
ef50: 74 65 73 20 73 6c 6f 74 73 20 6f 66 0a 2a 2a 20  tes slots of.** 
ef60: 20 20 20 20 20 20 20 20 20 20 69 74 73 20 6f 75            its ou
ef70: 74 70 75 74 20 62 75 66 66 65 72 20 28 74 68 65  tput buffer (the
ef80: 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
ef90: 72 29 20 6f 75 74 73 69 64 65 20 74 68 65 20 72  r) outside the r
efa0: 61 6e 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  ange.**         
efb0: 20 20 6f 66 20 30 20 74 68 72 6f 75 67 68 20 4e    of 0 through N
efc0: 2d 31 20 28 77 68 65 72 65 20 4e 20 69 73 20 74  -1 (where N is t
efd0: 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
efe0: 65 72 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  er).**          
eff0: 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74   regardless of t
f000: 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65  he length of the
f010: 20 73 74 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20   string.**      
f020: 20 20 20 20 20 72 65 71 75 65 73 74 65 64 20 62       requested b
f030: 79 20 74 68 65 20 66 6f 72 6d 61 74 20 73 70 65  y the format spe
f040: 63 69 66 69 63 61 74 69 6f 6e 2e 0a 2a 2a 20 20  cification..**  
f050: 20 0a 2a 2f 0a 63 68 61 72 20 2a 73 71 6c 69 74   .*/.char *sqlit
f060: 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74  e3_mprintf(const
f070: 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61   char*,...);.cha
f080: 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72 69  r *sqlite3_vmpri
f090: 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ntf(const char*,
f0a0: 20 76 61 5f 6c 69 73 74 29 3b 0a 63 68 61 72 20   va_list);.char 
f0b0: 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  *sqlite3_snprint
f0c0: 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73  f(int,char*,cons
f0d0: 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 0a  t char*, ...);..
f0e0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
f0f0: 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f  Memory Allocatio
f100: 6e 20 53 75 62 73 79 73 74 65 6d 20 7b 46 31 37  n Subsystem {F17
f110: 33 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  300}.**.** The S
f120: 51 4c 69 74 65 20 63 6f 72 65 20 20 75 73 65 73  QLite core  uses
f130: 20 74 68 65 73 65 20 74 68 72 65 65 20 72 6f 75   these three rou
f140: 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66  tines for all of
f150: 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65   its own.** inte
f160: 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  rnal memory allo
f170: 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43  cation needs. "C
f180: 6f 72 65 22 20 69 6e 20 74 68 65 20 70 72 65 76  ore" in the prev
f190: 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a  ious sentence.**
f1a0: 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64   does not includ
f1b0: 65 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74  e operating-syst
f1c0: 65 6d 20 73 70 65 63 69 66 69 63 20 56 46 53 20  em specific VFS 
f1d0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20  implementation. 
f1e0: 20 54 68 65 0a 2a 2a 20 77 69 6e 64 6f 77 73 20   The.** windows 
f1f0: 56 46 53 20 75 73 65 73 20 6e 61 74 69 76 65 20  VFS uses native 
f200: 6d 61 6c 6c 6f 63 20 61 6e 64 20 66 72 65 65 20  malloc and free 
f210: 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61 74 69  for some operati
f220: 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ons..**.** The s
f230: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
f240: 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
f250: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 62  a pointer to a b
f260: 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72  lock.** of memor
f270: 79 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74  y at least N byt
f280: 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68  es in length, wh
f290: 65 72 65 20 4e 20 69 73 20 74 68 65 20 70 61 72  ere N is the par
f2a0: 61 6d 65 74 65 72 2e 0a 2a 2a 20 49 66 20 73 71  ameter..** If sq
f2b0: 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69  lite3_malloc() i
f2c0: 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61  s unable to obta
f2d0: 69 6e 20 73 75 66 66 69 63 69 65 6e 74 20 66 72  in sufficient fr
f2e0: 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74  ee.** memory, it
f2f0: 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
f300: 70 6f 69 6e 74 65 72 2e 20 20 49 66 20 74 68 65  pointer.  If the
f310: 20 70 61 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a   parameter N to.
f320: 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  ** sqlite3_mallo
f330: 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e  c() is zero or n
f340: 65 67 61 74 69 76 65 20 74 68 65 6e 20 73 71 6c  egative then sql
f350: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65  ite3_malloc() re
f360: 74 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20  turns.** a NULL 
f370: 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 43  pointer..**.** C
f380: 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66  alling sqlite3_f
f390: 72 65 65 28 29 20 77 69 74 68 20 61 20 70 6f 69  ree() with a poi
f3a0: 6e 74 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20  nter previously 
f3b0: 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73  returned.** by s
f3c0: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
f3d0: 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  or sqlite3_reall
f3e0: 6f 63 28 29 20 72 65 6c 65 61 73 65 73 20 74 68  oc() releases th
f3f0: 61 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20  at memory so.** 
f400: 74 68 61 74 20 69 74 20 6d 69 67 68 74 20 62 65  that it might be
f410: 20 72 65 75 73 65 64 2e 20 20 54 68 65 20 73 71   reused.  The sq
f420: 6c 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75  lite3_free() rou
f430: 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d  tine is.** a no-
f440: 6f 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20  op if is called 
f450: 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  with a NULL poin
f460: 74 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20  ter.  Passing a 
f470: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
f480: 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  to sqlite3_free(
f490: 29 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20  ) is harmless.  
f4a0: 41 66 74 65 72 20 62 65 69 6e 67 20 66 72 65 65  After being free
f4b0: 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f  d, memory.** sho
f4c0: 75 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20 72  uld neither be r
f4d0: 65 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e  ead nor written.
f4e0: 20 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70    Even reading p
f4f0: 72 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a  reviously freed.
f500: 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20  ** memory might 
f510: 72 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d  result in a segm
f520: 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f  entation fault o
f530: 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65  r other severe e
f540: 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20  rror..** Memory 
f550: 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65  corruption, a se
f560: 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74  gmentation fault
f570: 2c 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72  , or other sever
f580: 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74  e error.** might
f590: 20 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74   result if sqlit
f5a0: 65 33 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c  e3_free() is cal
f5b0: 6c 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e  led with a non-N
f5c0: 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74  ULL pointer that
f5d0: 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61  .** was not obta
f5e0: 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65  ined from sqlite
f5f0: 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71  3_malloc() or sq
f600: 6c 69 74 65 33 5f 66 72 65 65 28 29 2e 0a 2a 2a  lite3_free()..**
f610: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
f620: 72 65 61 6c 6c 6f 63 28 29 20 69 6e 74 65 72 66  realloc() interf
f630: 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20  ace attempts to 
f640: 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f  resize a.** prio
f650: 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  r memory allocat
f660: 69 6f 6e 20 74 6f 20 62 65 20 61 74 20 6c 65 61  ion to be at lea
f670: 73 74 20 4e 20 62 79 74 65 73 2c 20 77 68 65 72  st N bytes, wher
f680: 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 73 65  e N is the.** se
f690: 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20  cond parameter. 
f6a0: 20 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   The memory allo
f6b0: 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 72 65 73  cation to be res
f6c0: 69 7a 65 64 20 69 73 20 74 68 65 20 66 69 72 73  ized is the firs
f6d0: 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20  t.** parameter. 
f6e0: 20 49 66 20 74 68 65 20 66 69 72 73 74 20 70 61   If the first pa
f6f0: 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
f700: 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20  e3_realloc().** 
f710: 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
f720: 72 20 74 68 65 6e 20 69 74 73 20 62 65 68 61 76  r then its behav
f730: 69 6f 72 20 69 73 20 69 64 65 6e 74 69 63 61 6c  ior is identical
f740: 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73   to calling.** s
f750: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29  qlite3_malloc(N)
f760: 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20   where N is the 
f770: 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
f780: 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   to sqlite3_real
f790: 6c 6f 63 28 29 2e 0a 2a 2a 20 49 66 20 74 68 65  loc()..** If the
f7a0: 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
f7b0: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61  r to sqlite3_rea
f7c0: 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f  lloc() is zero o
f7d0: 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68  r.** negative th
f7e0: 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
f7f0: 69 73 20 65 78 61 63 74 6c 79 20 74 68 65 20 73  is exactly the s
f800: 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a  ame as calling.*
f810: 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 50  * sqlite3_free(P
f820: 29 20 77 68 65 72 65 20 50 20 69 73 20 74 68 65  ) where P is the
f830: 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
f840: 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   to sqlite3_real
f850: 6c 6f 63 28 29 2e 0a 2a 2a 20 53 71 6c 69 74 65  loc()..** Sqlite
f860: 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75  3_realloc() retu
f870: 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
f880: 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
f890: 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65  tion.** of at le
f8a0: 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73  ast N bytes in s
f8b0: 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 73  ize or NULL if s
f8c0: 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79  ufficient memory
f8d0: 20 69 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e   is unavailable.
f8e0: 0a 2a 2a 20 49 66 20 4d 20 69 73 20 74 68 65 20  .** If M is the 
f8f0: 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f  size of the prio
f900: 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68  r allocation, th
f910: 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65  en min(N,M) byte
f920: 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f  s.** of the prio
f930: 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65  r allocation are
f940: 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65   copied into the
f950: 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75   beginning of bu
f960: 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a  ffer returned.**
f970: 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   by sqlite3_real
f980: 6c 6f 63 28 29 20 61 6e 64 20 74 68 65 20 70 72  loc() and the pr
f990: 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69  ior allocation i
f9a0: 73 20 66 72 65 65 64 2e 0a 2a 2a 20 49 66 20 73  s freed..** If s
f9b0: 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
f9c0: 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74   returns NULL, t
f9d0: 68 65 6e 20 74 68 65 20 70 72 69 6f 72 20 61 6c  hen the prior al
f9e0: 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6e  location.** is n
f9f0: 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20  ot freed..**.** 
fa00: 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72  The memory retur
fa10: 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d  ned by sqlite3_m
fa20: 61 6c 6c 6f 63 28 29 20 61 6e 64 20 73 71 6c 69  alloc() and sqli
fa30: 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a  te3_realloc().**
fa40: 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e   is always align
fa50: 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61  ed to at least a
fa60: 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72  n 8 byte boundar
fa70: 79 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54  y. {END}.**.** T
fa80: 68 65 20 64 65 66 61 75 6c 74 20 69 6d 70 6c 65  he default imple
fa90: 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20  mentation.** of 
faa0: 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
fab0: 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 20  ation subsystem 
fac0: 75 73 65 73 20 74 68 65 20 6d 61 6c 6c 6f 63 28  uses the malloc(
fad0: 29 2c 20 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20  ), realloc().** 
fae0: 61 6e 64 20 66 72 65 65 28 29 20 70 72 6f 76 69  and free() provi
faf0: 64 65 64 20 62 79 20 74 68 65 20 73 74 61 6e 64  ded by the stand
fb00: 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20 7b  ard C library. {
fb10: 46 31 37 33 38 32 7d 20 48 6f 77 65 76 65 72 2c  F17382} However,
fb20: 20 69 66 20 0a 2a 2a 20 53 51 4c 69 74 65 20 69   if .** SQLite i
fb30: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
fb40: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 43 20  the following C 
fb50: 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  preprocessor mac
fb60: 72 6f 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  ro.**.** <blockq
fb70: 75 6f 74 65 3e 20 53 51 4c 49 54 45 5f 4d 45 4d  uote> SQLITE_MEM
fb80: 4f 52 59 5f 53 49 5a 45 3d 3c 69 3e 4e 4e 4e 3c  ORY_SIZE=<i>NNN<
fb90: 2f 69 3e 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  /i> </blockquote
fba0: 3e 0a 2a 2a 0a 2a 2a 20 77 68 65 72 65 20 3c 69  >.**.** where <i
fbb0: 3e 4e 4e 4e 3c 2f 69 3e 20 69 73 20 61 6e 20 69  >NNN</i> is an i
fbc0: 6e 74 65 67 65 72 2c 20 74 68 65 6e 20 53 51 4c  nteger, then SQL
fbd0: 69 74 65 20 63 72 65 61 74 65 20 61 20 73 74 61  ite create a sta
fbe0: 74 69 63 0a 2a 2a 20 61 72 72 61 79 20 6f 66 20  tic.** array of 
fbf0: 61 74 20 6c 65 61 73 74 20 3c 69 3e 4e 4e 4e 3c  at least <i>NNN<
fc00: 2f 69 3e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  /i> bytes in siz
fc10: 65 20 61 6e 64 20 75 73 65 20 74 68 61 74 20 61  e and use that a
fc20: 72 72 61 79 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20  rray.** for all 
fc30: 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d  of its dynamic m
fc40: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
fc50: 20 6e 65 65 64 73 2e 20 7b 45 4e 44 7d 20 20 41   needs. {END}  A
fc60: 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 6d 65 6d  dditional.** mem
fc70: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 6f 70  ory allocator op
fc80: 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64  tions may be add
fc90: 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
fca0: 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20  eases..**.** In 
fcb0: 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
fcc0: 2e 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20  .5.0 and 3.5.1, 
fcd0: 69 74 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20  it was possible 
fce0: 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65  to define.** the
fcf0: 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d   SQLITE_OMIT_MEM
fd00: 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77  ORY_ALLOCATION w
fd10: 68 69 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65  hich would cause
fd20: 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a   the built-in.**
fd30: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
fd40: 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
fd50: 73 20 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e  s to be omitted.
fd60: 20 20 54 68 61 74 20 63 61 70 61 62 69 6c 69 74    That capabilit
fd70: 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65  y.** is no longe
fd80: 72 20 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c  r provided.  Onl
fd90: 79 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72  y built-in memor
fda0: 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e  y allocators can
fdb0: 20 62 65 0a 2a 2a 20 75 73 65 64 2e 0a 2a 2a 0a   be.** used..**.
fdc0: 2a 2a 20 54 68 65 20 77 69 6e 64 6f 77 73 20 4f  ** The windows O
fdd0: 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65  S interface laye
fde0: 72 20 63 61 6c 6c 73 0a 2a 2a 20 74 68 65 20 73  r calls.** the s
fdf0: 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61  ystem malloc() a
fe00: 6e 64 20 66 72 65 65 28 29 20 64 69 72 65 63 74  nd free() direct
fe10: 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65 72 74 69  ly when converti
fe20: 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20  ng.** filenames 
fe30: 62 65 74 77 65 65 6e 20 74 68 65 20 55 54 46 2d  between the UTF-
fe40: 38 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20  8 encoding used 
fe50: 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64  by SQLite.** and
fe60: 20 77 68 61 74 65 76 65 72 20 66 69 6c 65 6e 61   whatever filena
fe70: 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75  me encoding is u
fe80: 73 65 64 20 62 79 20 74 68 65 20 70 61 72 74 69  sed by the parti
fe90: 63 75 6c 61 72 20 77 69 6e 64 6f 77 73 0a 2a 2a  cular windows.**
fea0: 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20   installation.  
feb0: 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  Memory allocatio
fec0: 6e 20 65 72 72 6f 72 73 20 61 72 65 20 64 65 74  n errors are det
fed0: 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68  ected, but.** th
fee0: 65 79 20 61 72 65 20 72 65 70 6f 72 74 65 64 20  ey are reported 
fef0: 62 61 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f  back as [SQLITE_
ff00: 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20  CANTOPEN] or.** 
ff10: 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72  [SQLITE_IOERR] r
ff20: 61 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  ather than [SQLI
ff30: 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a  TE_NOMEM]..**.**
ff40: 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
ff50: 2a 2a 20 7b 46 31 37 33 30 33 7d 20 20 54 68 65  ** {F17303}  The
ff60: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
ff70: 28 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  (N)] interface r
ff80: 65 74 75 72 6e 73 20 65 69 74 68 65 72 20 61 20  eturns either a 
ff90: 70 6f 69 6e 74 65 72 20 74 6f 20 0a 2a 2a 20 20  pointer to .**  
ffa0: 20 20 20 20 20 20 20 20 20 6e 65 77 6c 79 20 63           newly c
ffb0: 68 65 63 6b 65 64 2d 6f 75 74 20 62 6c 6f 63 6b  hecked-out block
ffc0: 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62   of at least N b
ffd0: 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a  ytes of memory.*
ffe0: 2a 20 20 20 20 20 20 20 20 20 20 20 74 68 61 74  *           that
fff0: 20 69 73 20 38 2d 62 79 74 65 20 61 6c 69 67 6e   is 8-byte align
10000 65 64 2c 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  ed, .**         
10010 20 20 6f 72 20 69 74 20 72 65 74 75 72 6e 73 20    or it returns 
10020 4e 55 4c 4c 20 69 66 20 69 74 20 69 73 20 75 6e  NULL if it is un
10030 61 62 6c 65 20 74 6f 20 66 75 6c 66 69 6c 6c 20  able to fulfill 
10040 74 68 65 20 72 65 71 75 65 73 74 2e 0a 2a 2a 0a  the request..**.
10050 2a 2a 20 7b 46 31 37 33 30 34 7d 20 20 54 68 65  ** {F17304}  The
10060 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
10070 28 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  (N)] interface r
10080 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f  eturns a NULL po
10090 69 6e 74 65 72 20 69 66 0a 2a 2a 20 20 20 20 20  inter if.**     
100a0 20 20 20 20 20 20 4e 20 69 73 20 6c 65 73 73 20        N is less 
100b0 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f  than or equal to
100c0 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31   zero..**.** {F1
100d0 37 33 30 35 7d 20 20 54 68 65 20 5b 73 71 6c 69  7305}  The [sqli
100e0 74 65 33 5f 66 72 65 65 28 50 29 5d 20 69 6e 74  te3_free(P)] int
100f0 65 72 66 61 63 65 20 72 65 6c 65 61 73 65 73 20  erface releases 
10100 6d 65 6d 6f 72 79 20 70 72 65 76 69 6f 75 73 6c  memory previousl
10110 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72  y.**           r
10120 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71  eturned from [sq
10130 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
10140 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  or [sqlite3_real
10150 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20  loc()],.**      
10160 20 20 20 20 20 6d 61 6b 69 6e 67 20 69 74 20 61       making it a
10170 76 61 69 6c 61 62 6c 65 20 66 6f 72 20 72 65 75  vailable for reu
10180 73 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 30  se..**.** {F1730
10190 36 7d 20 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73  6}  A call to [s
101a0 71 6c 69 74 65 33 5f 66 72 65 65 28 4e 55 4c 4c  qlite3_free(NULL
101b0 29 5d 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73  )] is a harmless
101c0 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 7b 46   no-op..**.** {F
101d0 31 37 33 31 30 7d 20 20 41 20 63 61 6c 6c 20 74  17310}  A call t
101e0 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  o [sqlite3_reall
101f0 6f 63 28 30 2c 4e 29 5d 20 69 73 20 65 71 75 69  oc(0,N)] is equi
10200 76 61 6c 65 6e 74 20 74 6f 20 61 20 63 61 6c 6c  valent to a call
10210 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 6f  .**           to
10220 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
10230 28 4e 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37  (N)]..**.** {F17
10240 33 31 32 7d 20 20 41 20 63 61 6c 6c 20 74 6f 20  312}  A call to 
10250 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
10260 28 50 2c 30 29 5d 20 69 73 20 65 71 75 69 76 61  (P,0)] is equiva
10270 6c 65 6e 74 20 74 6f 20 61 20 63 61 6c 6c 0a 2a  lent to a call.*
10280 2a 20 20 20 20 20 20 20 20 20 20 20 74 6f 20 5b  *           to [
10290 73 71 6c 69 74 65 33 5f 66 72 65 65 28 50 29 5d  sqlite3_free(P)]
102a0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 31 35 7d  ..**.** {F17315}
102b0 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72    The SQLite cor
102c0 65 20 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f  e uses [sqlite3_
102d0 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69  malloc()], [sqli
102e0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2c 0a  te3_realloc()],.
102f0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 61 6e 64  **           and
10300 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
10310 5d 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73  ] for all of its
10320 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
10330 6f 6e 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20  on and.**       
10340 20 20 20 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e      deallocation
10350 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46   needs..**.** {F
10360 31 37 33 31 38 7d 20 20 54 68 65 20 5b 73 71 6c  17318}  The [sql
10370 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 50 2c 4e  ite3_realloc(P,N
10380 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
10390 75 72 6e 73 20 65 69 74 68 65 72 20 61 20 70 6f  urns either a po
103a0 69 6e 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  inter.**        
103b0 20 20 20 74 6f 20 61 20 62 6c 6f 63 6b 20 6f 66     to a block of
103c0 20 63 68 65 63 6b 65 64 2d 6f 75 74 20 6d 65 6d   checked-out mem
103d0 6f 72 79 20 6f 66 20 61 74 20 6c 65 61 73 74 20  ory of at least 
103e0 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 0a  N bytes in size.
103f0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 68 61  **           tha
10400 74 20 69 73 20 38 2d 62 79 74 65 20 61 6c 69 67  t is 8-byte alig
10410 6e 65 64 2c 20 6f 72 20 61 20 4e 55 4c 4c 20 70  ned, or a NULL p
10420 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46  ointer..**.** {F
10430 31 37 33 32 31 7d 20 20 57 68 65 6e 20 5b 73 71  17321}  When [sq
10440 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 50 2c  lite3_realloc(P,
10450 4e 29 5d 20 72 65 74 75 72 6e 73 20 61 20 6e 6f  N)] returns a no
10460 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  n-NULL pointer, 
10470 69 74 20 66 69 72 73 74 0a 2a 2a 20 20 20 20 20  it first.**     
10480 20 20 20 20 20 20 63 6f 70 69 65 73 20 74 68 65        copies the
10490 20 66 69 72 73 74 20 4b 20 62 79 74 65 73 20 6f   first K bytes o
104a0 66 20 63 6f 6e 74 65 6e 74 20 66 72 6f 6d 20 50  f content from P
104b0 20 69 6e 74 6f 20 74 68 65 20 6e 65 77 6c 79 20   into the newly 
104c0 61 6c 6c 6f 63 61 74 65 64 0a 2a 2a 20 20 20 20  allocated.**    
104d0 20 20 20 20 20 20 20 77 68 65 72 65 20 4b 20 69         where K i
104e0 73 20 74 68 65 20 6c 65 73 73 6f 72 20 6f 66 20  s the lessor of 
104f0 4e 20 61 6e 64 20 74 68 65 20 73 69 7a 65 20 6f  N and the size o
10500 66 20 74 68 65 20 62 75 66 66 65 72 20 50 2e 0a  f the buffer P..
10510 2a 2a 0a 2a 2a 20 7b 46 31 37 33 32 32 7d 20 20  **.** {F17322}  
10520 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65  When [sqlite3_re
10530 61 6c 6c 6f 63 28 50 2c 4e 29 5d 20 72 65 74 75  alloc(P,N)] retu
10540 72 6e 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70  rns a non-NULL p
10550 6f 69 6e 74 65 72 2c 20 69 74 20 66 69 72 73 74  ointer, it first
10560 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72 65  .**           re
10570 6c 65 61 73 65 73 20 74 68 65 20 62 75 66 66 65  leases the buffe
10580 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33  r P..**.** {F173
10590 32 33 7d 20 20 57 68 65 6e 20 5b 73 71 6c 69 74  23}  When [sqlit
105a0 65 33 5f 72 65 61 6c 6c 6f 63 28 50 2c 4e 29 5d  e3_realloc(P,N)]
105b0 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74   returns NULL, t
105c0 68 65 20 62 75 66 66 65 72 20 50 20 69 73 0a 2a  he buffer P is.*
105d0 2a 20 20 20 20 20 20 20 20 20 20 20 6e 6f 74 20  *           not 
105e0 6d 6f 64 69 66 69 65 64 20 6f 72 20 72 65 6c 65  modified or rele
105f0 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49  ased..**.** LIMI
10600 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b  TATIONS:.**.** {
10610 55 31 37 33 35 30 7d 20 20 54 68 65 20 70 6f 69  U17350}  The poi
10620 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74  nter arguments t
10630 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  o [sqlite3_free(
10640 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
10650 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 20 20  realloc()].**   
10660 20 20 20 20 20 20 20 20 6d 75 73 74 20 62 65 20          must be 
10670 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65  either NULL or e
10680 6c 73 65 20 61 20 70 6f 69 6e 74 65 72 20 6f 62  lse a pointer ob
10690 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 70 72  tained from a pr
106a0 69 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ior.**          
106b0 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b   invocation of [
106c0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
106d0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
106e0 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61  alloc()] that ha
106f0 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6e  s.**           n
10700 6f 74 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64  ot been released
10710 2e 0a 2a 2a 0a 2a 2a 20 7b 55 31 37 33 35 31 7d  ..**.** {U17351}
10720 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f    The applicatio
10730 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 64 20  n must not read 
10740 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70 61 72  or write any par
10750 74 20 6f 66 20 0a 2a 2a 20 20 20 20 20 20 20 20  t of .**        
10760 20 20 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65     a block of me
10770 6d 6f 72 79 20 61 66 74 65 72 20 69 74 20 68 61  mory after it ha
10780 73 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 20  s been released 
10790 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20  using.**        
107a0 20 20 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65     [sqlite3_free
107b0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
107c0 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 0a 2a  realloc()]..**.*
107d0 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
107e0 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69  malloc(int);.voi
107f0 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  d *sqlite3_reall
10800 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a  oc(void*, int);.
10810 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65  void sqlite3_fre
10820 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  e(void*);../*.**
10830 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72   CAPI3REF: Memor
10840 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74  y Allocator Stat
10850 69 73 74 69 63 73 20 7b 46 31 37 33 37 30 7d 0a  istics {F17370}.
10860 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f  **.** SQLite pro
10870 76 69 64 65 73 20 74 68 65 73 65 20 74 77 6f 20  vides these two 
10880 69 6e 74 65 72 66 61 63 65 73 20 66 6f 72 20 72  interfaces for r
10890 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65 20  eporting on the 
108a0 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65  status.** of the
108b0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
108c0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72  ()], [sqlite3_fr
108d0 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  ee()], and [sqli
108e0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a  te3_realloc()].*
108f0 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  * the memory all
10900 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65  ocation subsyste
10910 6d 20 69 6e 63 6c 75 64 65 64 20 77 69 74 68 69  m included withi
10920 6e 20 74 68 65 20 53 51 4c 69 74 65 2e 0a 2a 2a  n the SQLite..**
10930 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
10940 2a 2a 0a 2a 2a 20 7b 46 31 37 33 37 31 7d 20 54  **.** {F17371} T
10950 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  he [sqlite3_memo
10960 72 79 5f 75 73 65 64 28 29 5d 20 72 6f 75 74 69  ry_used()] routi
10970 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a  ne returns the.*
10980 2a 20 20 20 20 20 20 20 20 20 20 6e 75 6d 62 65  *          numbe
10990 72 20 6f 66 20 62 79 74 65 73 20 6f 66 20 6d 65  r of bytes of me
109a0 6d 6f 72 79 20 63 75 72 72 65 6e 74 6c 79 20 6f  mory currently o
109b0 75 74 73 74 61 6e 64 69 6e 67 20 0a 2a 2a 20 20  utstanding .**  
109c0 20 20 20 20 20 20 20 20 28 6d 61 6c 6c 6f 63 65          (malloce
109d0 64 20 62 75 74 20 6e 6f 74 20 66 72 65 65 64 29  d but not freed)
109e0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 37 33 7d  ..**.** {F17373}
109f0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65   The [sqlite3_me
10a00 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
10a10 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ] routine return
10a20 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a  s the maximum.**
10a30 20 20 20 20 20 20 20 20 20 20 76 61 6c 75 65 20            value 
10a40 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  of [sqlite3_memo
10a50 72 79 5f 75 73 65 64 28 29 5d 20 0a 2a 2a 20 20  ry_used()] .**  
10a60 20 20 20 20 20 20 20 20 73 69 6e 63 65 20 74 68          since th
10a70 65 20 68 69 67 68 77 61 74 65 72 20 6d 61 72 6b  e highwater mark
10a80 20 77 61 73 20 6c 61 73 74 20 72 65 73 65 74 2e   was last reset.
10a90 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 37 34 7d 20  .**.** {F17374} 
10aa0 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72  The values retur
10ab0 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
10ac0 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 61  memory_used()] a
10ad0 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  nd.**          [
10ae0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
10af0 69 67 68 77 61 74 65 72 28 29 5d 20 69 6e 63 6c  ighwater()] incl
10b00 75 64 65 20 61 6e 79 20 6f 76 65 72 68 65 61 64  ude any overhead
10b10 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 64 64  .**          add
10b20 65 64 20 62 79 20 53 51 4c 69 74 65 20 69 6e 20  ed by SQLite in 
10b30 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  its implementati
10b40 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d  on of [sqlite3_m
10b50 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 20 20 20  alloc()],.**    
10b60 20 20 20 20 20 20 62 75 74 20 6e 6f 74 20 6f 76        but not ov
10b70 65 72 68 65 61 64 20 61 64 64 65 64 20 62 79 20  erhead added by 
10b80 74 68 65 20 61 6e 79 20 75 6e 64 65 72 6c 79 69  the any underlyi
10b90 6e 67 20 73 79 73 74 65 6d 20 6c 69 62 72 61 72  ng system librar
10ba0 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 6f  y.**          ro
10bb0 75 74 69 6e 65 73 20 74 68 61 74 20 5b 73 71 6c  utines that [sql
10bc0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d  ite3_malloc()] m
10bd0 61 79 20 63 61 6c 6c 2e 0a 2a 2a 20 0a 2a 2a 20  ay call..** .** 
10be0 7b 46 31 37 33 37 35 7d 20 54 68 65 20 6d 65 6d  {F17375} The mem
10bf0 6f 72 79 20 68 69 67 68 77 61 74 65 72 20 6d 61  ory highwater ma
10c00 72 6b 20 69 73 20 72 65 73 65 74 20 74 6f 20 74  rk is reset to t
10c10 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65  he current value
10c20 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   of.**          
10c30 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
10c40 75 73 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f  used()] if and o
10c50 6e 6c 79 20 69 66 20 74 68 65 20 70 61 72 61 6d  nly if the param
10c60 65 74 65 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20  eter to.**      
10c70 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d      [sqlite3_mem
10c80 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
10c90 20 69 73 20 74 72 75 65 2e 20 20 54 68 65 20 76   is true.  The v
10ca0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a  alue returned.**
10cb0 20 20 20 20 20 20 20 20 20 20 62 79 20 5b 73 71            by [sq
10cc0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
10cd0 68 77 61 74 65 72 28 31 29 5d 20 69 73 20 74 68  hwater(1)] is th
10ce0 65 20 68 69 67 68 77 61 74 65 72 20 6d 61 72 6b  e highwater mark
10cf0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 72 69  .**          pri
10d00 6f 72 20 74 6f 20 74 68 65 20 72 65 73 65 74 2e  or to the reset.
10d10 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  .*/.sqlite3_int6
10d20 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79  4 sqlite3_memory
10d30 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 73 71 6c  _used(void);.sql
10d40 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
10d50 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
10d60 74 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c 61  ter(int resetFla
10d70 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  g);../*.** CAPI3
10d80 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d  REF: Compile-Tim
10d90 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20  e Authorization 
10da0 43 61 6c 6c 62 61 63 6b 73 20 7b 46 31 32 35 30  Callbacks {F1250
10db0 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  0}.**.** This ro
10dc0 75 74 69 6e 65 20 72 65 67 69 73 74 65 72 73 20  utine registers 
10dd0 61 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  a authorizer cal
10de0 6c 62 61 63 6b 20 77 69 74 68 20 61 20 70 61 72  lback with a par
10df0 74 69 63 75 6c 61 72 0a 2a 2a 20 64 61 74 61 62  ticular.** datab
10e00 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20  ase connection, 
10e10 73 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65 20  supplied in the 
10e20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a  first argument..
10e30 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65  ** The authorize
10e40 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  r callback is in
10e50 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61  voked as SQL sta
10e60 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69 6e  tements are bein
10e70 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79  g compiled.** by
10e80 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
10e90 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69  e()] or its vari
10ea0 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 72  ants [sqlite3_pr
10eb0 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20  epare_v2()],.** 
10ec0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
10ed0 31 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  16()] and [sqlit
10ee0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
10ef0 29 5d 2e 20 20 41 74 20 76 61 72 69 6f 75 73 0a  )].  At various.
10f00 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67  ** points during
10f10 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e   the compilation
10f20 20 70 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67   process, as log
10f30 69 63 20 69 73 20 62 65 69 6e 67 20 63 72 65 61  ic is being crea
10f40 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72  ted.** to perfor
10f50 6d 20 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e  m various action
10f60 73 2c 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  s, the authorize
10f70 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  r callback is in
10f80 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20  voked to.** see 
10f90 69 66 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73  if those actions
10fa0 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 54   are allowed.  T
10fb0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
10fc0 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a  llback should.**
10fd0 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f   return SQLITE_O
10fe0 4b 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61  K to allow the a
10ff0 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49  ction, [SQLITE_I
11000 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c  GNORE] to disall
11010 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66  ow the.** specif
11020 69 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c  ic action but al
11030 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61 74  low the SQL stat
11040 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75  ement to continu
11050 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69  e to be.** compi
11060 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  led, or [SQLITE_
11070 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 74  DENY] to cause t
11080 68 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73 74  he entire SQL st
11090 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a  atement to be.**
110a0 20 72 65 6a 65 63 74 65 64 20 77 69 74 68 20 61   rejected with a
110b0 6e 20 65 72 72 6f 72 2e 20 20 20 49 66 20 74 68  n error.   If th
110c0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
110d0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a  lback returns.**
110e0 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72   any value other
110f0 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47   than [SQLITE_IG
11100 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f  NORE], [SQLITE_O
11110 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  K], or [SQLITE_D
11120 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 5b 73 71  ENY].** then [sq
11130 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
11140 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e  ()] or equivalen
11150 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67  t call that trig
11160 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 75 74  gered.** the aut
11170 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69  horizer will fai
11180 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20  l with an error 
11190 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57  message..**.** W
111a0 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
111b0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
111c0 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73  _OK], that means
111d0 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a   the operation.*
111e0 2a 20 72 65 71 75 65 73 74 65 64 20 69 73 20 6f  * requested is o
111f0 6b 2e 20 20 57 68 65 6e 20 74 68 65 20 63 61 6c  k.  When the cal
11200 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53  lback returns [S
11210 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65  QLITE_DENY], the
11220 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
11230 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71  pare_v2()] or eq
11240 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68  uivalent call th
11250 61 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65  at triggered the
11260 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 77  .** authorizer w
11270 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e  ill fail with an
11280 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 65   error message e
11290 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a  xplaining that.*
112a0 2a 20 61 63 63 65 73 73 20 69 73 20 64 65 6e 69  * access is deni
112b0 65 64 2e 20 20 49 66 20 74 68 65 20 61 75 74 68  ed.  If the auth
112c0 6f 72 69 7a 65 72 20 63 6f 64 65 20 69 73 20 5b  orizer code is [
112d0 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20  SQLITE_READ].** 
112e0 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  and the callback
112f0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
11300 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68  _IGNORE] then th
11310 65 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74  e prepared.** st
11320 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74  atement is const
11330 72 75 63 74 65 64 20 74 6f 20 69 6e 73 65 72 74  ructed to insert
11340 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e   a NULL value in
11350 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65   place of.** the
11360 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68   table column th
11370 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a  at would have.**
11380 20 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53   been read if [S
11390 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65  QLITE_OK] had be
113a0 65 6e 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68  en returned.  Th
113b0 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  e [SQLITE_IGNORE
113c0 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e 20  ].** return can 
113d0 62 65 20 75 73 65 64 20 74 6f 20 64 65 6e 79 20  be used to deny 
113e0 61 6e 20 75 6e 74 72 75 73 74 65 64 20 75 73 65  an untrusted use
113f0 72 20 61 63 63 65 73 73 20 74 6f 20 69 6e 64 69  r access to indi
11400 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e  vidual.** column
11410 73 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a  s of a table..**
11420 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61  .** The first pa
11430 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61  rameter to the a
11440 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
11450 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 0a  ck is a copy of.
11460 2a 2a 20 74 68 65 20 74 68 69 72 64 20 70 61 72  ** the third par
11470 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
11480 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
11490 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61 63 65  izer() interface
114a0 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
114b0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
114c0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
114d0 69 6e 74 65 67 65 72 20 0a 2a 2a 20 5b 53 51 4c  integer .** [SQL
114e0 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f  ITE_COPY | actio
114f0 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65  n code] that spe
11500 63 69 66 69 65 73 20 74 68 65 20 70 61 72 74 69  cifies the parti
11510 63 75 6c 61 72 20 61 63 74 69 6f 6e 0a 2a 2a 20  cular action.** 
11520 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64  to be authorized
11530 2e 20 54 68 65 20 74 68 69 72 64 20 74 68 72 6f  . The third thro
11540 75 67 68 20 73 69 78 74 68 0a 2a 2a 20 70 61 72  ugh sixth.** par
11550 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20 63  ameters to the c
11560 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65 72 6f  allback are zero
11570 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69  -terminated stri
11580 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e  ngs that contain
11590 20 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20   .** additional 
115a0 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68  details about th
115b0 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  e action to be a
115c0 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a  uthorized..**.**
115d0 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 69   An authorizer i
115e0 73 20 75 73 65 64 20 77 68 65 6e 20 70 72 65 70  s used when prep
115f0 61 72 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d  aring SQL statem
11600 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74  ents from an unt
11610 72 75 73 74 65 64 0a 2a 2a 20 73 6f 75 72 63 65  rusted.** source
11620 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74  , to ensure that
11630 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
11640 6e 74 73 20 64 6f 20 6e 6f 74 20 74 72 79 20 74  nts do not try t
11650 6f 20 61 63 63 65 73 73 20 64 61 74 61 0a 2a 2a  o access data.**
11660 20 74 68 61 74 20 74 68 65 79 20 61 72 65 20 6e   that they are n
11670 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65  ot allowed to se
11680 65 2c 20 6f 72 20 74 68 61 74 20 74 68 65 79 20  e, or that they 
11690 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 0a 2a 2a  do not try to.**
116a0 20 65 78 65 63 75 74 65 20 6d 61 6c 69 63 69 6f   execute malicio
116b0 75 73 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68  us statements th
116c0 61 74 20 64 61 6d 61 67 65 20 74 68 65 20 64 61  at damage the da
116d0 74 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20  tabase.  For.** 
116e0 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c  example, an appl
116f0 69 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f  ication may allo
11700 77 20 61 20 75 73 65 72 20 74 6f 20 65 6e 74 65  w a user to ente
11710 72 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 53  r arbitrary.** S
11720 51 4c 20 71 75 65 72 69 65 73 20 66 6f 72 20 65  QL queries for e
11730 76 61 6c 75 61 74 69 6f 6e 20 62 79 20 61 20 64  valuation by a d
11740 61 74 61 62 61 73 65 2e 20 20 42 75 74 20 74 68  atabase.  But th
11750 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f  e application do
11760 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74  es.** not want t
11770 68 65 20 75 73 65 72 20 74 6f 20 62 65 20 61 62  he user to be ab
11780 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72 62 69 74  le to make arbit
11790 72 61 72 79 20 63 68 61 6e 67 65 73 20 74 6f 20  rary changes to 
117a0 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e  the.** database.
117b0 20 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20    An authorizer 
117c0 63 6f 75 6c 64 20 74 68 65 6e 20 62 65 20 70 75  could then be pu
117d0 74 20 69 6e 20 70 6c 61 63 65 20 77 68 69 6c 65  t in place while
117e0 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74   the.** user-ent
117f0 65 72 65 64 20 53 51 4c 20 69 73 20 62 65 69 6e  ered SQL is bein
11800 67 20 70 72 65 70 61 72 65 64 20 74 68 61 74 20  g prepared that 
11810 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74  disallows everyt
11820 68 69 6e 67 0a 2a 2a 20 65 78 63 65 70 74 20 53  hing.** except S
11830 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 73  ELECT statements
11840 2e 20 20 0a 2a 2a 0a 2a 2a 20 4f 6e 6c 79 20 61  .  .**.** Only a
11850 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a   single authoriz
11860 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61  er can be in pla
11870 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65  ce on a database
11880 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61   connection.** a
11890 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20  t a time.  Each 
118a0 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
118b0 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f  set_authorizer o
118c0 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20  verrides the.** 
118d0 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 20 20  previous call.  
118e0 44 69 73 61 62 6c 65 20 74 68 65 20 61 75 74 68  Disable the auth
118f0 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 74 61 6c  orizer by instal
11900 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c  ling a NULL call
11910 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74  back..** The aut
11920 68 6f 72 69 7a 65 72 20 69 73 20 64 69 73 61 62  horizer is disab
11930 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a  led by default..
11940 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
11950 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
11960 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
11970 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 20 0a  ed only during .
11980 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
11990 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61  are()] or its va
119a0 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f 72 69  riants.  Authori
119b0 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a  zation is not.**
119c0 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69 6e   performed durin
119d0 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61 6c  g statement eval
119e0 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74  uation in [sqlit
119f0 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a  e3_step()]..**.*
11a00 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
11a10 0a 2a 2a 20 7b 46 31 32 35 30 31 7d 20 54 68 65  .** {F12501} The
11a20 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
11a30 74 68 6f 72 69 7a 65 72 28 44 2c 2e 2e 2e 29 5d  thorizer(D,...)]
11a40 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73   interface regis
11a50 74 65 72 73 20 61 0a 2a 2a 20 20 20 20 20 20 20  ters a.**       
11a60 20 20 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61     authorizer ca
11a70 6c 6c 62 61 63 6b 20 77 69 74 68 20 64 61 74 61  llback with data
11a80 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
11a90 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 30 32  D..**.** {F12502
11aa0 7d 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72  } The authorizer
11ab0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
11ac0 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61 74  oked as SQL stat
11ad0 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a 20 20 20  ements are.**   
11ae0 20 20 20 20 20 20 20 62 65 69 6e 67 20 63 6f 6d         being com
11af0 70 69 6c 65 64 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  piled.**.** {F12
11b00 35 30 33 7d 20 49 66 20 74 68 65 20 61 75 74 68  503} If the auth
11b10 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
11b20 72 65 74 75 72 6e 73 20 61 6e 79 20 76 61 6c 75  returns any valu
11b30 65 20 6f 74 68 65 72 20 74 68 61 6e 0a 2a 2a 20  e other than.** 
11b40 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45           [SQLITE
11b50 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54  _IGNORE], [SQLIT
11b60 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  E_OK], or [SQLIT
11b70 45 5f 44 45 4e 59 5d 20 74 68 65 6e 0a 2a 2a 20  E_DENY] then.** 
11b80 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 73 71           the [sq
11b90 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
11ba0 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e  ()] or equivalen
11bb0 74 20 63 61 6c 6c 20 74 68 61 74 20 63 61 75 73  t call that caus
11bc0 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  ed.**          t
11bd0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
11be0 6c 6c 62 61 63 6b 20 74 6f 20 72 75 6e 20 73 68  llback to run sh
11bf0 61 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e  all fail with an
11c00 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51  .**          [SQ
11c10 4c 49 54 45 5f 45 52 52 4f 52 5d 20 65 72 72 6f  LITE_ERROR] erro
11c20 72 20 63 6f 64 65 20 61 6e 64 20 61 6e 20 61 70  r code and an ap
11c30 70 72 6f 70 72 69 61 74 65 20 65 72 72 6f 72 20  propriate error 
11c40 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 7b  message..**.** {
11c50 46 31 32 35 30 34 7d 20 57 68 65 6e 20 74 68 65  F12504} When the
11c60 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
11c70 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51  back returns [SQ
11c80 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 65 20 6f 70  LITE_OK], the op
11c90 65 72 61 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20  eration.**      
11ca0 20 20 20 20 64 65 73 63 72 69 62 65 64 20 69 73      described is
11cb0 20 63 6f 64 65 64 20 6e 6f 72 6d 61 6c 6c 79 2e   coded normally.
11cc0 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 30 35 7d 20  .**.** {F12505} 
11cd0 57 68 65 6e 20 74 68 65 20 61 75 74 68 6f 72 69  When the authori
11ce0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  zer callback ret
11cf0 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e  urns [SQLITE_DEN
11d00 59 5d 2c 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  Y], the.**      
11d10 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65      [sqlite3_pre
11d20 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71  pare_v2()] or eq
11d30 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68  uivalent call th
11d40 61 74 20 63 61 75 73 65 64 20 74 68 65 0a 2a 2a  at caused the.**
11d50 20 20 20 20 20 20 20 20 20 20 61 75 74 68 6f 72            author
11d60 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 74 6f  izer callback to
11d70 20 72 75 6e 20 73 68 61 6c 6c 20 66 61 69 6c 0a   run shall fail.
11d80 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69 74 68  **          with
11d90 20 61 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f   an [SQLITE_ERRO
11da0 52 5d 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e  R] error code an
11db0 64 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61  d an error messa
11dc0 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65  ge.**          e
11dd0 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 20 61  xplaining that a
11de0 63 63 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e  ccess is denied.
11df0 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 30 36 7d 20  .**.** {F12506} 
11e00 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  If the authorize
11e10 72 20 63 6f 64 65 20 28 74 68 65 20 32 6e 64 20  r code (the 2nd 
11e20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
11e30 20 61 75 74 68 6f 72 69 7a 65 72 0a 2a 2a 20 20   authorizer.**  
11e40 20 20 20 20 20 20 20 20 63 61 6c 6c 62 61 63 6b          callback
11e50 29 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41  ) is [SQLITE_REA
11e60 44 5d 20 61 6e 64 20 74 68 65 20 61 75 74 68 6f  D] and the autho
11e70 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72  rizer callback r
11e80 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20  eturns.**       
11e90 20 20 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52     [SQLITE_IGNOR
11ea0 45 5d 20 74 68 65 6e 20 74 68 65 20 70 72 65 70  E] then the prep
11eb0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69  ared statement i
11ec0 73 20 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f  s constructed to
11ed0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 73  .**          ins
11ee0 65 72 74 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65  ert a NULL value
11ef0 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65   in place of the
11f00 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68   table column th
11f10 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a  at would have.**
11f20 20 20 20 20 20 20 20 20 20 20 62 65 65 6e 20 72            been r
11f30 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f  ead if [SQLITE_O
11f40 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74 75  K] had been retu
11f50 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  rned..**.** {F12
11f60 35 30 37 7d 20 49 66 20 74 68 65 20 61 75 74 68  507} If the auth
11f70 6f 72 69 7a 65 72 20 63 6f 64 65 20 28 74 68 65  orizer code (the
11f80 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74   2nd parameter t
11f90 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  o the authorizer
11fa0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c  .**          cal
11fb0 6c 62 61 63 6b 29 20 69 73 20 61 6e 79 74 68 69  lback) is anythi
11fc0 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  ng other than [S
11fd0 51 4c 49 54 45 5f 52 45 41 44 5d 2c 20 74 68 65  QLITE_READ], the
11fe0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20  n.**          a 
11ff0 72 65 74 75 72 6e 20 6f 66 20 5b 53 51 4c 49 54  return of [SQLIT
12000 45 5f 49 47 4e 4f 52 45 5d 20 68 61 73 20 74 68  E_IGNORE] has th
12010 65 20 73 61 6d 65 20 65 66 66 65 63 74 20 61 73  e same effect as
12020 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2e 20   [SQLITE_DENY]. 
12030 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 31 30 7d 20  .**.** {F12510} 
12040 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
12050 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f  ter to the autho
12060 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
12070 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 20  s a copy of.**  
12080 20 20 20 20 20 20 20 20 74 68 65 20 74 68 69 72          the thir
12090 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
120a0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  he [sqlite3_set_
120b0 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e  authorizer()] in
120c0 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 7b  terface..**.** {
120d0 46 31 32 35 31 31 7d 20 54 68 65 20 73 65 63 6f  F12511} The seco
120e0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
120f0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  the callback is 
12100 61 6e 20 69 6e 74 65 67 65 72 20 0a 2a 2a 20 20  an integer .**  
12110 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f          [SQLITE_
12120 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f  COPY | action co
12130 64 65 5d 20 74 68 61 74 20 73 70 65 63 69 66 69  de] that specifi
12140 65 73 20 74 68 65 20 70 61 72 74 69 63 75 6c 61  es the particula
12150 72 20 61 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20  r action.**     
12160 20 20 20 20 20 74 6f 20 62 65 20 61 75 74 68 6f       to be autho
12170 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  rized..**.** {F1
12180 32 35 31 32 7d 20 54 68 65 20 74 68 69 72 64 20  2512} The third 
12190 74 68 72 6f 75 67 68 20 73 69 78 74 68 20 70 61  through sixth pa
121a0 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20  rameters to the 
121b0 63 61 6c 6c 62 61 63 6b 20 61 72 65 0a 2a 2a 20  callback are.** 
121c0 20 20 20 20 20 20 20 20 20 7a 65 72 6f 2d 74 65           zero-te
121d0 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73  rminated strings
121e0 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 0a 2a   that contain .*
121f0 2a 20 20 20 20 20 20 20 20 20 20 61 64 64 69 74  *          addit
12200 69 6f 6e 61 6c 20 64 65 74 61 69 6c 73 20 61 62  ional details ab
12210 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20 74  out the action t
12220 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e  o be authorized.
12230 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 32 30 7d 20  .**.** {F12520} 
12240 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71  Each call to [sq
12250 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
12260 69 7a 65 72 28 29 5d 20 6f 76 65 72 72 69 64 65  izer()] override
12270 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
12280 20 20 61 6e 79 20 70 72 65 76 69 6f 75 73 6c 79    any previously
12290 20 69 6e 73 74 61 6c 6c 65 64 20 61 75 74 68 6f   installed autho
122a0 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  rizer..**.** {F1
122b0 32 35 32 31 7d 20 41 20 4e 55 4c 4c 20 61 75 74  2521} A NULL aut
122c0 68 6f 72 69 7a 65 72 20 6d 65 61 6e 73 20 74 68  horizer means th
122d0 61 74 20 6e 6f 20 61 75 74 68 6f 72 69 7a 61 74  at no authorizat
122e0 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ion.**          
122f0 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
12300 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35  ked..**.** {F125
12310 32 32 7d 20 54 68 65 20 64 65 66 61 75 6c 74 20  22} The default 
12320 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 4e 55  authorizer is NU
12330 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  LL..*/.int sqlit
12340 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
12350 72 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20  r(.  sqlite3*,. 
12360 20 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76 6f   int (*xAuth)(vo
12370 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68  id*,int,const ch
12380 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ar*,const char*,
12390 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73  const char*,cons
123a0 74 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64  t char*),.  void
123b0 20 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a   *pUserData.);..
123c0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
123d0 41 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75 72  Authorizer Retur
123e0 6e 20 43 6f 64 65 73 20 7b 46 31 32 35 39 30 7d  n Codes {F12590}
123f0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  .**.** The [sqli
12400 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
12410 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20  er | authorizer 
12420 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
12430 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72  n] must.** retur
12440 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45  n either [SQLITE
12450 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74  _OK] or one of t
12460 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e  hese two constan
12470 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74  ts in order.** t
12480 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 20  o signal SQLite 
12490 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
124a0 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65 72  he action is per
124b0 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74 68 65  mitted.  See the
124c0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  .** [sqlite3_set
124d0 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75  _authorizer | au
124e0 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e  thorizer documen
124f0 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69  tation] for addi
12500 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d  tional.** inform
12510 61 74 69 6f 6e 2e 0a 2a 2f 0a 23 64 65 66 69 6e  ation..*/.#defin
12520 65 20 53 51 4c 49 54 45 5f 44 45 4e 59 20 20 20  e SQLITE_DENY   
12530 31 20 20 20 2f 2a 20 41 62 6f 72 74 20 74 68 65  1   /* Abort the
12540 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77   SQL statement w
12550 69 74 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a  ith an error */.
12560 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
12570 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e  GNORE 2   /* Don
12580 27 74 20 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c  't allow access,
12590 20 62 75 74 20 64 6f 6e 27 74 20 67 65 6e 65 72   but don't gener
125a0 61 74 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a  ate an error */.
125b0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
125c0 20 41 75 74 68 6f 72 69 7a 65 72 20 41 63 74 69   Authorizer Acti
125d0 6f 6e 20 43 6f 64 65 73 20 7b 46 31 32 35 35 30  on Codes {F12550
125e0 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  }.**.** The [sql
125f0 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
12600 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65  zer()] interface
12610 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c   registers a cal
12620 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a  lback function.*
12630 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65  * that is invoke
12640 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 72 20  d to authorizer 
12650 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74  certain SQL stat
12660 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20  ement actions.  
12670 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61  The.** second pa
12680 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63  rameter to the c
12690 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e  allback is an in
126a0 74 65 67 65 72 20 63 6f 64 65 20 74 68 61 74 20  teger code that 
126b0 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61  specifies.** wha
126c0 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e  t action is bein
126d0 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54  g authorized.  T
126e0 68 65 73 65 20 61 72 65 20 74 68 65 20 69 6e 74  hese are the int
126f0 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65  eger action code
12700 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75  s that.** the au
12710 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
12720 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e  k may be passed.
12730 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74  .**.** These act
12740 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20  ion code values 
12750 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e  signify what kin
12760 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69  d of operation i
12770 73 20 74 6f 20 62 65 20 0a 2a 2a 20 61 75 74 68  s to be .** auth
12780 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64  orized.  The 3rd
12790 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74   and 4th paramet
127a0 65 72 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f  ers to the autho
127b0 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c  rization.** call
127c0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69  back function wi
127d0 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72 73  ll be parameters
127e0 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69   or NULL dependi
127f0 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74  ng on which of t
12800 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73  hese.** codes is
12810 20 75 73 65 64 20 61 73 20 74 68 65 20 73 65 63   used as the sec
12820 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20  ond parameter.  
12830 54 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  The 5th paramete
12840 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68  r to the.** auth
12850 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
12860 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
12870 68 65 20 64 61 74 61 62 61 73 65 20 28 22 6d 61  he database ("ma
12880 69 6e 22 2c 20 22 74 65 6d 70 22 2c 20 0a 2a 2a  in", "temp", .**
12890 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63   etc.) if applic
128a0 61 62 6c 65 2e 20 20 54 68 65 20 36 74 68 20 70  able.  The 6th p
128b0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
128c0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
128d0 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61  ack.** is the na
128e0 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d  me of the inner-
128f0 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72 20  most trigger or 
12900 76 69 65 77 20 74 68 61 74 20 69 73 20 72 65 73  view that is res
12910 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20  ponsible for.** 
12920 74 68 65 20 61 63 63 65 73 73 20 61 74 74 65 6d  the access attem
12930 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68  pt or NULL if th
12940 69 73 20 61 63 63 65 73 73 20 61 74 74 65 6d 70  is access attemp
12950 74 20 69 73 20 64 69 72 65 63 74 6c 79 20 66 72  t is directly fr
12960 6f 6d 20 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c  om .** top-level
12970 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a   SQL code..**.**
12980 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
12990 2a 2a 20 7b 46 31 32 35 35 31 7d 20 54 68 65 20  ** {F12551} The 
129a0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
129b0 20 74 6f 20 61 6e 20 0a 2a 2a 20 20 20 20 20 20   to an .**      
129c0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 65 74      [sqlite3_set
129d0 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75  _authorizer | au
129e0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
129f0 6b 20 69 73 20 61 6c 77 61 79 73 20 61 6e 20 69  k is always an i
12a00 6e 74 65 67 65 72 0a 2a 2a 20 20 20 20 20 20 20  nteger.**       
12a10 20 20 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20     [SQLITE_COPY 
12a20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 64  | authorizer cod
12a30 65 5d 20 74 68 61 74 20 73 70 65 63 69 66 69 65  e] that specifie
12a40 73 20 77 68 61 74 20 61 63 74 69 6f 6e 0a 2a 2a  s what action.**
12a50 20 20 20 20 20 20 20 20 20 20 69 73 20 62 65 69            is bei
12a60 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a  ng authorized..*
12a70 2a 0a 2a 2a 20 7b 46 31 32 35 35 32 7d 20 54 68  *.** {F12552} Th
12a80 65 20 33 72 64 20 61 6e 64 20 34 74 68 20 70 61  e 3rd and 4th pa
12a90 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20  rameters to the 
12aa0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
12ab0 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
12ac0 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 61  izer | authoriza
12ad0 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 20 66 75  tion callback fu
12ae0 6e 63 74 69 6f 6e 5d 0a 2a 2a 20 20 20 20 20 20  nction].**      
12af0 20 20 20 20 77 69 6c 6c 20 62 65 20 70 61 72 61      will be para
12b00 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64  meters or NULL d
12b10 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63  epending on whic
12b20 68 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  h .**          [
12b30 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 75  SQLITE_COPY | au
12b40 74 68 6f 72 69 7a 65 72 20 63 6f 64 65 5d 20 69  thorizer code] i
12b50 73 20 75 73 65 64 20 61 73 20 74 68 65 20 73 65  s used as the se
12b60 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 0a  cond parameter..
12b70 2a 2a 0a 2a 2a 20 7b 46 31 32 35 35 33 7d 20 54  **.** {F12553} T
12b80 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
12b90 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   to the.**      
12ba0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 65 74      [sqlite3_set
12bb0 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75  _authorizer | au
12bc0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
12bd0 6b 5d 20 69 73 20 74 68 65 20 6e 61 6d 65 0a 2a  k] is the name.*
12be0 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 74 68  *          of th
12bf0 65 20 64 61 74 61 62 61 73 65 20 28 65 78 61 6d  e database (exam
12c00 70 6c 65 3a 20 22 6d 61 69 6e 22 2c 20 22 74 65  ple: "main", "te
12c10 6d 70 22 2c 20 65 74 63 2e 29 20 69 66 20 61 70  mp", etc.) if ap
12c20 70 6c 69 63 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20  plicable..**.** 
12c30 7b 46 31 32 35 35 34 7d 20 54 68 65 20 36 74 68  {F12554} The 6th
12c40 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
12c50 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  e.**          [s
12c60 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
12c70 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a  rizer | authoriz
12c80 65 72 20 63 61 6c 6c 62 61 63 6b 5d 20 69 73 20  er callback] is 
12c90 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 20 20 20 20  the name.**     
12ca0 20 20 20 20 20 6f 66 20 74 68 65 20 69 6e 6e 65       of the inne
12cb0 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f  r-most trigger o
12cc0 72 20 76 69 65 77 20 74 68 61 74 20 69 73 20 72  r view that is r
12cd0 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a  esponsible for.*
12ce0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 61  *          the a
12cf0 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72  ccess attempt or
12d00 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63   NULL if this ac
12d10 63 65 73 73 20 61 74 74 65 6d 70 74 20 69 73 20  cess attempt is 
12d20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 20 0a 2a  directly from .*
12d30 2a 20 20 20 20 20 20 20 20 20 20 74 6f 70 2d 6c  *          top-l
12d40 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a  evel SQL code..*
12d50 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  /./*************
12d60 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
12d70 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33  ************** 3
12d80 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20  rd ************ 
12d90 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f  4th ***********/
12da0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
12db0 43 52 45 41 54 45 5f 49 4e 44 45 58 20 20 20 20  CREATE_INDEX    
12dc0 20 20 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 64        1   /* Ind
12dd0 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62  ex Name      Tab
12de0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
12df0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
12e00 52 45 41 54 45 5f 54 41 42 4c 45 20 20 20 20 20  REATE_TABLE     
12e10 20 20 20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c       2   /* Tabl
12e20 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
12e30 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
12e40 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
12e50 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20  EATE_TEMP_INDEX 
12e60 20 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 78      3   /* Index
12e70 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
12e80 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
12e90 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
12ea0 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20  ATE_TEMP_TABLE  
12eb0 20 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20     4   /* Table 
12ec0 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
12ed0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
12ee0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
12ef0 54 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20  TE_TEMP_TRIGGER 
12f00 20 20 35 20 20 20 2f 2a 20 54 72 69 67 67 65 72    5   /* Trigger
12f10 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e   Name    Table N
12f20 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
12f30 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
12f40 45 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20  E_TEMP_VIEW     
12f50 20 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d   6   /* View Nam
12f60 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  e       NULL    
12f70 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
12f80 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
12f90 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20  _TRIGGER        
12fa0 37 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  7   /* Trigger N
12fb0 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
12fc0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
12fd0 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
12fe0 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20 38  VIEW           8
12ff0 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
13000 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
13010 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
13020 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 20   SQLITE_DELETE  
13030 20 20 20 20 20 20 20 20 20 20 20 20 20 20 39 20                9 
13040 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
13050 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
13060 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
13070 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45  SQLITE_DROP_INDE
13080 58 20 20 20 20 20 20 20 20 20 20 20 31 30 20 20  X           10  
13090 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
130a0 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
130b0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
130c0 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45  QLITE_DROP_TABLE
130d0 20 20 20 20 20 20 20 20 20 20 20 31 31 20 20 20             11   
130e0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
130f0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
13100 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
13110 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49  LITE_DROP_TEMP_I
13120 4e 44 45 58 20 20 20 20 20 20 31 32 20 20 20 2f  NDEX      12   /
13130 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
13140 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
13150 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
13160 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41  ITE_DROP_TEMP_TA
13170 42 4c 45 20 20 20 20 20 20 31 33 20 20 20 2f 2a  BLE      13   /*
13180 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
13190 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
131a0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
131b0 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49  TE_DROP_TEMP_TRI
131c0 47 47 45 52 20 20 20 20 31 34 20 20 20 2f 2a 20  GGER    14   /* 
131d0 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
131e0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
131f0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
13200 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57  E_DROP_TEMP_VIEW
13210 20 20 20 20 20 20 20 31 35 20 20 20 2f 2a 20 56         15   /* V
13220 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
13230 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
13240 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
13250 5f 44 52 4f 50 5f 54 52 49 47 47 45 52 20 20 20  _DROP_TRIGGER   
13260 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 54 72        16   /* Tr
13270 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
13280 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
13290 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
132a0 44 52 4f 50 5f 56 49 45 57 20 20 20 20 20 20 20  DROP_VIEW       
132b0 20 20 20 20 20 31 37 20 20 20 2f 2a 20 56 69 65       17   /* Vie
132c0 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
132d0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
132e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
132f0 4e 53 45 52 54 20 20 20 20 20 20 20 20 20 20 20  NSERT           
13300 20 20 20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c      18   /* Tabl
13310 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
13320 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
13330 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52  define SQLITE_PR
13340 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20  AGMA            
13350 20 20 20 31 39 20 20 20 2f 2a 20 50 72 61 67 6d     19   /* Pragm
13360 61 20 4e 61 6d 65 20 20 20 20 20 31 73 74 20 61  a Name     1st a
13370 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64  rg or NULL */.#d
13380 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
13390 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  D               
133a0 20 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20    20   /* Table 
133b0 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e  Name      Column
133c0 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
133d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c 45  fine SQLITE_SELE
133e0 43 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CT              
133f0 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20   21   /* NULL   
13400 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20           NULL   
13410 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
13420 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53  ine SQLITE_TRANS
13430 41 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20  ACTION          
13440 32 32 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20  22   /* NULL    
13450 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20          NULL    
13460 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
13470 6e 65 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45  ne SQLITE_UPDATE
13480 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
13490 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  3   /* Table Nam
134a0 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61  e      Column Na
134b0 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
134c0 65 20 53 51 4c 49 54 45 5f 41 54 54 41 43 48 20  e SQLITE_ATTACH 
134d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 34                24
134e0 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20     /* Filename  
134f0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
13500 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
13510 20 53 51 4c 49 54 45 5f 44 45 54 41 43 48 20 20   SQLITE_DETACH  
13520 20 20 20 20 20 20 20 20 20 20 20 20 20 32 35 20               25 
13530 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61    /* Database Na
13540 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20  me   NULL       
13550 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
13560 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 42  SQLITE_ALTER_TAB
13570 4c 45 20 20 20 20 20 20 20 20 20 20 32 36 20 20  LE          26  
13580 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d   /* Database Nam
13590 65 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20  e   Table Name  
135a0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
135b0 51 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 20 20  QLITE_REINDEX   
135c0 20 20 20 20 20 20 20 20 20 20 20 32 37 20 20 20             27   
135d0 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
135e0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
135f0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
13600 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20  LITE_ANALYZE    
13610 20 20 20 20 20 20 20 20 20 20 32 38 20 20 20 2f            28   /
13620 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
13630 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
13640 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
13650 49 54 45 5f 43 52 45 41 54 45 5f 56 54 41 42 4c  ITE_CREATE_VTABL
13660 45 20 20 20 20 20 20 20 20 32 39 20 20 20 2f 2a  E        29   /*
13670 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
13680 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20   Module Name    
13690 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
136a0 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 20  TE_DROP_VTABLE  
136b0 20 20 20 20 20 20 20 20 33 30 20 20 20 2f 2a 20          30   /* 
136c0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
136d0 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20  Module Name     
136e0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
136f0 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 20  E_FUNCTION      
13700 20 20 20 20 20 20 20 33 31 20 20 20 2f 2a 20 46         31   /* F
13710 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 4e  unction Name   N
13720 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
13730 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
13740 5f 43 4f 50 59 20 20 20 20 20 20 20 20 20 20 20  _COPY           
13750 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f         0   /* No
13760 20 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a   longer used */.
13770 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
13780 20 54 72 61 63 69 6e 67 20 41 6e 64 20 50 72 6f   Tracing And Pro
13790 66 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73  filing Functions
137a0 20 7b 46 31 32 32 38 30 7d 0a 2a 2a 0a 2a 2a 20   {F12280}.**.** 
137b0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
137c0 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b  egister callback
137d0 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20   functions that 
137e0 63 61 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a  can be used for.
137f0 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70  ** tracing and p
13800 72 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65  rofiling the exe
13810 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74  cution of SQL st
13820 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  atements..**.** 
13830 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  The callback fun
13840 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64  ction registered
13850 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63   by sqlite3_trac
13860 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61  e() is invoked a
13870 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d  t.** various tim
13880 65 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73  es when an SQL s
13890 74 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e  tatement is bein
138a0 67 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65  g run by [sqlite
138b0 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 54 68  3_step()]..** Th
138c0 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
138d0 6e 73 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65  ns a UTF-8 rende
138e0 72 69 6e 67 20 6f 66 20 74 68 65 20 53 51 4c 20  ring of the SQL 
138f0 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 0a 2a  statement text.*
13900 2a 20 61 73 20 74 68 65 20 73 74 61 74 65 6d 65  * as the stateme
13910 6e 74 20 66 69 72 73 74 20 62 65 67 69 6e 73 20  nt first begins 
13920 65 78 65 63 75 74 69 6e 67 2e 20 20 41 64 64 69  executing.  Addi
13930 74 69 6f 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73  tional callbacks
13940 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65 61 63   occur.** as eac
13950 68 20 74 72 69 67 67 65 72 73 75 62 70 72 6f 67  h triggersubprog
13960 72 61 6d 20 69 73 20 65 6e 74 65 72 65 64 2e 20  ram is entered. 
13970 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 20 66   The callbacks f
13980 6f 72 20 74 72 69 67 67 65 72 73 0a 2a 2a 20 63  or triggers.** c
13990 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 20 53  ontain a UTF-8 S
139a0 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20  QL comment that 
139b0 69 64 65 6e 74 69 66 69 65 73 20 74 68 65 20 74  identifies the t
139c0 72 69 67 67 65 72 2e 0a 2a 2a 20 0a 2a 2a 20 54  rigger..** .** T
139d0 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  he callback func
139e0 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20  tion registered 
139f0 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69  by sqlite3_profi
13a00 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a  le() is invoked.
13a10 2a 2a 20 61 73 20 65 61 63 68 20 53 51 4c 20 73  ** as each SQL s
13a20 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65  tatement finishe
13a30 73 2e 20 20 54 68 65 20 70 72 6f 66 69 6c 65 20  s.  The profile 
13a40 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e  callback contain
13a50 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61  s.** the origina
13a60 6c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74  l statement text
13a70 20 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65   and an estimate
13a80 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74   of wall-clock t
13a90 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f  ime.** of how lo
13aa0 6e 67 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e  ng that statemen
13ab0 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 0a 2a  t took to run..*
13ac0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
13ad0 5f 70 72 6f 66 69 6c 65 28 29 20 41 50 49 20 69  _profile() API i
13ae0 73 20 63 75 72 72 65 6e 74 6c 79 20 63 6f 6e 73  s currently cons
13af0 69 64 65 72 65 64 20 65 78 70 65 72 69 6d 65 6e  idered experimen
13b00 74 61 6c 20 61 6e 64 0a 2a 2a 20 69 73 20 73 75  tal and.** is su
13b10 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20  bject to change 
13b20 6f 72 20 72 65 6d 6f 76 61 6c 20 69 6e 20 61 20  or removal in a 
13b30 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 2e 0a  future release..
13b40 2a 2a 0a 2a 2a 20 54 68 65 20 74 72 69 67 67 65  **.** The trigge
13b50 72 20 72 65 70 6f 72 74 69 6e 67 20 66 65 61 74  r reporting feat
13b60 75 72 65 20 6f 66 20 74 68 65 20 74 72 61 63 65  ure of the trace
13b70 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 63 6f 6e   callback is con
13b80 73 69 64 65 72 65 64 0a 2a 2a 20 65 78 70 65 72  sidered.** exper
13b90 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 20 73  imental and is s
13ba0 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65  ubject to change
13bb0 20 6f 72 20 72 65 6d 6f 76 61 6c 20 69 6e 20 66   or removal in f
13bc0 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a  uture releases..
13bd0 2a 2a 20 46 75 74 75 72 65 20 76 65 72 73 69 6f  ** Future versio
13be0 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67  ns of SQLite mig
13bf0 68 74 20 61 6c 73 6f 20 61 64 64 20 6e 65 77 20  ht also add new 
13c00 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 20 0a  trace callback .
13c10 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 2e 0a  ** invocations..
13c20 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
13c30 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 38 31 7d  :.**.** {F12281}
13c40 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75   The callback fu
13c50 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65  nction registere
13c60 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 74 72  d by [sqlite3_tr
13c70 61 63 65 28 29 5d 20 69 73 0a 2a 2a 20 20 20 20  ace()] is.**    
13c80 20 20 20 20 20 20 77 68 65 6e 65 76 65 72 20 61        whenever a
13c90 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  n SQL statement 
13ca0 66 69 72 73 74 20 62 65 67 69 6e 73 20 74 6f 20  first begins to 
13cb0 65 78 65 63 75 74 65 20 61 6e 64 0a 2a 2a 20 20  execute and.**  
13cc0 20 20 20 20 20 20 20 20 77 68 65 6e 65 76 65 72          whenever
13cd0 20 61 20 74 72 69 67 67 65 72 20 73 75 62 70 72   a trigger subpr
13ce0 6f 67 72 61 6d 20 66 69 72 73 74 20 62 65 67 69  ogram first begi
13cf0 6e 73 20 74 6f 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a  ns to run..**.**
13d00 20 7b 46 31 32 32 38 32 7d 20 45 61 63 68 20 63   {F12282} Each c
13d10 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
13d20 74 72 61 63 65 28 29 5d 20 6f 76 65 72 72 69 64  trace()] overrid
13d30 65 73 20 74 68 65 20 70 72 65 76 69 6f 75 73 6c  es the previousl
13d40 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  y.**          re
13d50 67 69 73 74 65 72 65 64 20 74 72 61 63 65 20 63  gistered trace c
13d60 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b  allback..**.** {
13d70 46 31 32 32 38 33 7d 20 41 20 4e 55 4c 4c 20 74  F12283} A NULL t
13d80 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 20 64 69  race callback di
13d90 73 61 62 6c 65 73 20 74 72 61 63 69 6e 67 2e 0a  sables tracing..
13da0 2a 2a 0a 2a 2a 20 7b 46 31 32 32 38 34 7d 20 54  **.** {F12284} T
13db0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
13dc0 74 20 74 6f 20 74 68 65 20 74 72 61 63 65 20 63  t to the trace c
13dd0 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70  allback is a cop
13de0 79 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20  y of.**         
13df0 20 74 68 65 20 70 6f 69 6e 74 65 72 20 77 68 69   the pointer whi
13e00 63 68 20 77 61 73 20 74 68 65 20 33 72 64 20 61  ch was the 3rd a
13e10 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69  rgument to [sqli
13e20 74 65 33 5f 74 72 61 63 65 28 29 5d 2e 0a 2a 2a  te3_trace()]..**
13e30 0a 2a 2a 20 7b 46 31 32 32 38 35 7d 20 54 68 65  .** {F12285} The
13e40 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
13e50 20 74 6f 20 74 68 65 20 74 72 61 63 65 20 63 61   to the trace ca
13e60 6c 6c 62 61 63 6b 20 69 73 20 61 0a 2a 2a 20 20  llback is a.**  
13e70 20 20 20 20 20 20 20 20 7a 65 72 6f 2d 74 65 72          zero-ter
13e80 6d 69 6e 61 74 65 64 20 55 54 46 38 20 73 74 72  minated UTF8 str
13e90 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  ing containing t
13ea0 68 65 20 6f 72 69 67 69 6e 61 6c 20 74 65 78 74  he original text
13eb0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20  .**          of 
13ec0 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
13ed0 74 20 61 73 20 69 74 20 77 61 73 20 70 61 73 73  t as it was pass
13ee0 65 64 20 69 6e 74 6f 20 5b 73 71 6c 69 74 65 33  ed into [sqlite3
13ef0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 0a 2a  _prepare_v2()].*
13f00 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 74 68  *          or th
13f10 65 20 65 71 75 69 76 61 6c 65 6e 74 2c 20 6f 72  e equivalent, or
13f20 20 61 6e 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20   an SQL comment 
13f30 69 6e 64 69 63 61 74 69 6e 67 20 74 68 65 20 62  indicating the b
13f40 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 20 20 20 20  eginning.**     
13f50 20 20 20 20 20 6f 66 20 61 20 74 72 69 67 67 65       of a trigge
13f60 72 20 73 75 62 70 72 6f 67 72 61 6d 2e 0a 2a 2a  r subprogram..**
13f70 0a 2a 2a 20 7b 46 31 32 32 38 37 7d 20 54 68 65  .** {F12287} The
13f80 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
13f90 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79  on registered by
13fa0 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c   [sqlite3_profil
13fb0 65 28 29 5d 20 69 73 20 69 6e 76 6f 6b 65 64 0a  e()] is invoked.
13fc0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 73 20 65  **          as e
13fd0 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ach SQL statemen
13fe0 74 20 66 69 6e 69 73 68 65 73 2e 0a 2a 2a 0a 2a  t finishes..**.*
13ff0 2a 20 7b 46 31 32 32 38 38 7d 20 54 68 65 20 66  * {F12288} The f
14000 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
14010 6f 20 74 68 65 20 70 72 6f 66 69 6c 65 20 63 61  o the profile ca
14020 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79  llback is a copy
14030 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   of.**          
14040 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  the 3rd paramete
14050 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72  r to [sqlite3_pr
14060 6f 66 69 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  ofile()]..**.** 
14070 7b 46 31 32 32 38 39 7d 20 54 68 65 20 73 65 63  {F12289} The sec
14080 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
14090 20 74 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c   the profile cal
140a0 6c 62 61 63 6b 20 69 73 20 61 0a 2a 2a 20 20 20  lback is a.**   
140b0 20 20 20 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d         zero-term
140c0 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72  inated UTF-8 str
140d0 69 6e 67 20 74 68 61 74 20 63 6f 6e 74 61 69 6e  ing that contain
140e0 73 20 74 68 65 20 63 6f 6d 70 6c 65 74 65 20 74  s the complete t
140f0 65 78 74 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20  ext of.**       
14100 20 20 20 74 68 65 20 53 51 4c 20 73 74 61 74 65     the SQL state
14110 6d 65 6e 74 20 61 73 20 69 74 20 77 61 73 20 70  ment as it was p
14120 72 6f 63 65 73 73 65 64 20 62 79 20 5b 73 71 6c  rocessed by [sql
14130 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
14140 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  )].**          o
14150 72 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74  r the equivalent
14160 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 39 30 7d  ..**.** {F12290}
14170 20 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   The third param
14180 65 74 65 72 20 74 6f 20 74 68 65 20 70 72 6f 66  eter to the prof
14190 69 6c 65 20 20 63 61 6c 6c 62 61 63 6b 20 69 73  ile  callback is
141a0 20 61 6e 20 65 73 74 69 6d 61 74 65 0a 2a 2a 20   an estimate.** 
141b0 20 20 20 20 20 20 20 20 20 6f 66 20 74 68 65 20           of the 
141c0 6e 75 6d 62 65 72 20 6f 66 20 6e 61 6e 6f 73 65  number of nanose
141d0 63 6f 6e 64 73 20 6f 66 20 77 61 6c 6c 2d 63 6c  conds of wall-cl
141e0 6f 63 6b 20 74 69 6d 65 20 72 65 71 75 69 72 65  ock time require
141f0 64 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20  d to.**         
14200 20 72 75 6e 20 74 68 65 20 53 51 4c 20 73 74 61   run the SQL sta
14210 74 65 6d 65 6e 74 20 66 72 6f 6d 20 73 74 61 72  tement from star
14220 74 20 74 6f 20 66 69 6e 69 73 68 2e 0a 2a 2f 0a  t to finish..*/.
14230 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 74 72  void *sqlite3_tr
14240 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f  ace(sqlite3*, vo
14250 69 64 28 2a 78 54 72 61 63 65 29 28 76 6f 69 64  id(*xTrace)(void
14260 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20  *,const char*), 
14270 76 6f 69 64 2a 29 3b 0a 76 6f 69 64 20 2a 73 71  void*);.void *sq
14280 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 71  lite3_profile(sq
14290 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28  lite3*,.   void(
142a0 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a  *xProfile)(void*
142b0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c  ,const char*,sql
142c0 69 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f  ite3_uint64), vo
142d0 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
142e0 49 33 52 45 46 3a 20 51 75 65 72 79 20 50 72 6f  I3REF: Query Pro
142f0 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 20  gress Callbacks 
14300 7b 46 31 32 39 31 30 7d 0a 2a 2a 0a 2a 2a 20 54  {F12910}.**.** T
14310 68 69 73 20 72 6f 75 74 69 6e 65 20 63 6f 6e 66  his routine conf
14320 69 67 75 72 65 73 20 61 20 63 61 6c 6c 62 61 63  igures a callbac
14330 6b 20 66 75 6e 63 74 69 6f 6e 20 2d 20 74 68 65  k function - the
14340 0a 2a 2a 20 70 72 6f 67 72 65 73 73 20 63 61 6c  .** progress cal
14350 6c 62 61 63 6b 20 2d 20 74 68 61 74 20 69 73 20  lback - that is 
14360 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63  invoked periodic
14370 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67  ally during long
14380 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c  .** running call
14390 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78  s to [sqlite3_ex
143a0 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  ec()], [sqlite3_
143b0 73 74 65 70 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b  step()] and.** [
143c0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
143d0 65 28 29 5d 2e 20 20 20 41 6e 20 65 78 61 6d 70  e()].   An examp
143e0 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69 73 20  le use for this 
143f0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73  .** interface is
14400 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75   to keep a GUI u
14410 70 64 61 74 65 64 20 64 75 72 69 6e 67 20 61 20  pdated during a 
14420 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a  large query..**.
14430 2a 2a 20 49 66 20 74 68 65 20 70 72 6f 67 72 65  ** If the progre
14440 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  ss callback retu
14450 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68  rns non-zero, th
14460 65 20 6f 70 65 72 74 69 6f 6e 20 69 73 0a 2a 2a  e opertion is.**
14470 20 69 6e 74 65 72 72 75 70 74 65 64 2e 20 20 54   interrupted.  T
14480 68 69 73 20 66 65 61 74 75 72 65 20 63 61 6e 20  his feature can 
14490 62 65 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65  be used to imple
144a0 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65  ment a.** "Cance
144b0 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47  l" button on a G
144c0 55 49 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a  UI dialog box..*
144d0 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
144e0 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 31 31 7d 20  .**.** {F12911} 
144f0 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  The callback fun
14500 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64  ction registered
14510 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f   by [sqlite3_pro
14520 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 29 5d  gress_handler()]
14530 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20  .**          is 
14540 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63  invoked periodic
14550 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67  ally during long
14560 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74   running calls t
14570 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  o.**          [s
14580 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a  qlite3_step()]..
14590 2a 2a 0a 2a 2a 20 7b 46 31 32 39 31 32 7d 20 54  **.** {F12912} T
145a0 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c  he progress call
145b0 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
145c0 6f 6e 63 65 20 66 6f 72 20 65 76 65 72 79 20 4e  once for every N
145d0 20 76 69 72 74 75 61 6c 0a 2a 2a 20 20 20 20 20   virtual.**     
145e0 20 20 20 20 20 6d 61 63 68 69 6e 65 20 6f 70 63       machine opc
145f0 6f 64 65 73 2c 20 77 68 65 72 65 20 4e 20 69 73  odes, where N is
14600 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
14610 6d 65 6e 74 20 74 6f 20 0a 2a 2a 20 20 20 20 20  ment to .**     
14620 20 20 20 20 20 74 68 65 20 5b 73 71 6c 69 74 65       the [sqlite
14630 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c  3_progress_handl
14640 65 72 28 29 5d 20 63 61 6c 6c 20 74 68 61 74 20  er()] call that 
14650 72 65 67 69 73 74 65 72 65 64 0a 2a 2a 20 20 20  registered.**   
14660 20 20 20 20 20 20 20 74 68 65 20 63 61 6c 6c 62         the callb
14670 61 63 6b 2e 20 20 3c 74 6f 64 6f 3e 57 68 61 74  ack.  <todo>What
14680 20 69 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68   if N is less th
14690 61 6e 20 31 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a  an 1?</todo>.**.
146a0 2a 2a 20 7b 46 31 32 39 31 33 7d 20 54 68 65 20  ** {F12913} The 
146b0 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63  progress callbac
146c0 6b 20 69 74 73 65 6c 66 20 69 73 20 69 64 65 6e  k itself is iden
146d0 74 69 66 69 65 64 20 62 79 20 74 68 65 20 74 68  tified by the th
146e0 69 72 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ird.**          
146f0 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c  argument to [sql
14700 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61  ite3_progress_ha
14710 6e 64 6c 65 72 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  ndler()]..**.** 
14720 7b 46 31 32 39 31 34 7d 20 54 68 65 20 66 6f 75  {F12914} The fou
14730 72 74 68 20 61 72 67 75 6d 65 6e 74 20 5b 73 71  rth argument [sq
14740 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68  lite3_progress_h
14750 61 6e 64 6c 65 72 28 29 5d 20 69 73 20 61 0a 2a  andler()] is a.*
14760 2a 2a 20 20 20 20 20 20 20 20 20 76 6f 69 64 20  **         void 
14770 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64 20 74  pointer passed t
14780 6f 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 63  o the progress c
14790 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20  allback.**      
147a0 20 20 20 20 66 75 6e 63 74 69 6f 6e 20 65 61 63      function eac
147b0 68 20 74 69 6d 65 20 69 74 20 69 73 20 69 6e 76  h time it is inv
147c0 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  oked..**.** {F12
147d0 39 31 35 7d 20 49 66 20 61 20 63 61 6c 6c 20 74  915} If a call t
147e0 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
147f0 29 5d 20 72 65 73 75 6c 74 73 20 69 6e 20 66 65  )] results in fe
14800 77 65 72 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20  wer than.**     
14810 20 20 20 20 20 4e 20 6f 70 63 6f 64 65 73 20 62       N opcodes b
14820 65 69 6e 67 20 65 78 65 63 75 74 65 64 2c 0a 2a  eing executed,.*
14830 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20  *          then 
14840 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c  the progress cal
14850 6c 62 61 63 6b 20 69 73 20 6e 65 76 65 72 20 69  lback is never i
14860 6e 76 6f 6b 65 64 2e 20 7b 45 4e 44 7d 0a 2a 2a  nvoked. {END}.**
14870 20 0a 2a 2a 20 7b 46 31 32 39 31 36 7d 20 45 76   .** {F12916} Ev
14880 65 72 79 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ery call to [sql
14890 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61  ite3_progress_ha
148a0 6e 64 6c 65 72 28 29 5d 0a 2a 2a 20 20 20 20 20  ndler()].**     
148b0 20 20 20 20 20 6f 76 65 72 77 72 69 74 65 73 20       overwrites 
148c0 61 6e 79 20 70 72 65 76 69 6f 75 73 6c 79 20 72  any previously r
148d0 65 67 69 73 74 65 72 65 20 70 72 6f 67 72 65 73  egistere progres
148e0 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a  s handler..**.**
148f0 20 7b 46 31 32 39 31 37 7d 20 49 66 20 74 68 65   {F12917} If the
14900 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
14910 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55  r callback is NU
14920 4c 4c 20 74 68 65 6e 20 6e 6f 20 70 72 6f 67 72  LL then no progr
14930 65 73 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ess.**          
14940 68 61 6e 64 6c 65 72 20 69 73 20 69 6e 76 6f 6b  handler is invok
14950 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 31  ed..**.** {F1291
14960 38 7d 20 49 66 20 74 68 65 20 70 72 6f 67 72 65  8} If the progre
14970 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  ss callback retu
14980 72 6e 73 20 61 20 72 65 73 75 6c 74 20 6f 74 68  rns a result oth
14990 65 72 20 74 68 61 6e 20 30 2c 20 74 68 65 6e 0a  er than 0, then.
149a0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
149b0 62 65 68 61 76 69 6f 72 20 69 73 20 61 20 69 66  behavior is a if
149c0 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72   [sqlite3_interr
149d0 75 70 74 28 29 5d 20 68 61 64 20 62 65 65 6e 20  upt()] had been 
149e0 63 61 6c 6c 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20  called..*/.void 
149f0 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73  sqlite3_progress
14a00 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33  _handler(sqlite3
14a10 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76  *, int, int(*)(v
14a20 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a  oid*), void*);..
14a30 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
14a40 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61  Opening A New Da
14a50 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
14a60 6e 20 7b 46 31 32 37 30 30 7d 0a 2a 2a 0a 2a 2a  n {F12700}.**.**
14a70 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
14a80 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64  open an SQLite d
14a90 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 68 6f  atabase file who
14aa0 73 65 20 6e 61 6d 65 0a 2a 2a 20 69 73 20 67 69  se name.** is gi
14ab0 76 65 6e 20 62 79 20 74 68 65 20 66 69 6c 65 6e  ven by the filen
14ac0 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  ame argument..**
14ad0 20 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72   The filename ar
14ae0 67 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70  gument is interp
14af0 72 65 74 65 64 20 61 73 20 55 54 46 2d 38 0a 2a  reted as UTF-8.*
14b00 2a 20 66 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f  * for [sqlite3_o
14b10 70 65 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  pen()] and [sqli
14b20 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 61  te3_open_v2()] a
14b30 6e 64 20 61 73 20 55 54 46 2d 31 36 0a 2a 2a 20  nd as UTF-16.** 
14b40 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79  in the native by
14b50 74 65 20 6f 72 64 65 72 20 66 6f 72 20 5b 73 71  te order for [sq
14b60 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e  lite3_open16()].
14b70 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 2a  .** An [sqlite3*
14b80 5d 20 68 61 6e 64 6c 65 20 69 73 20 75 73 75 61  ] handle is usua
14b90 6c 6c 79 20 72 65 74 75 72 6e 65 64 20 69 6e 20  lly returned in 
14ba0 2a 70 70 44 62 2c 20 65 76 65 6e 0a 2a 2a 20 69  *ppDb, even.** i
14bb0 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  f an error occur
14bc0 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65 78 63  s.  The only exc
14bd0 65 70 74 69 6f 6e 20 69 73 20 69 66 20 53 51 4c  eption is if SQL
14be0 69 74 65 20 69 73 20 75 6e 61 62 6c 65 0a 2a 2a  ite is unable.**
14bf0 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d   to allocate mem
14c00 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ory to hold the 
14c10 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
14c20 2c 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 0a 2a 2a  , a NULL will.**
14c30 20 62 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f   be written into
14c40 20 2a 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f   *ppDb instead o
14c50 66 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  f a pointer to t
14c60 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a  he [sqlite3] obj
14c70 65 63 74 2e 0a 2a 2a 20 49 66 20 74 68 65 20 64  ect..** If the d
14c80 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
14c90 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 65  d (and/or create
14ca0 64 29 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c  d).** successful
14cb0 6c 79 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45  ly, then [SQLITE
14cc0 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64  _OK] is returned
14cd0 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e 0a  .  Otherwise an.
14ce0 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73  ** error code is
14cf0 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 0a   returned.  The.
14d00 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ** [sqlite3_errm
14d10 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  sg()] or [sqlite
14d20 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 20 72  3_errmsg16()]  r
14d30 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75  outines can be u
14d40 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a  sed to obtain.**
14d50 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67   an English lang
14d60 75 61 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e  uage description
14d70 20 6f 66 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a   of the error..*
14d80 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74  *.** The default
14d90 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 74 68   encoding for th
14da0 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  e database will 
14db0 62 65 20 55 54 46 2d 38 20 69 66 0a 2a 2a 20 5b  be UTF-8 if.** [
14dc0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20  sqlite3_open()] 
14dd0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  or [sqlite3_open
14de0 5f 76 32 28 29 5d 20 69 73 20 63 61 6c 6c 65 64  _v2()] is called
14df0 20 61 6e 64 0a 2a 2a 20 55 54 46 2d 31 36 20 69   and.** UTF-16 i
14e00 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74  n the native byt
14e10 65 20 6f 72 64 65 72 20 69 66 20 5b 73 71 6c 69  e order if [sqli
14e20 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73  te3_open16()] is
14e30 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 57 68 65   used..**.** Whe
14e40 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65  ther or not an e
14e50 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 65 6e  rror occurs when
14e60 20 69 74 20 69 73 20 6f 70 65 6e 65 64 2c 20 72   it is opened, r
14e70 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f  esources.** asso
14e80 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
14e90 5b 73 71 6c 69 74 65 33 2a 5d 20 68 61 6e 64 6c  [sqlite3*] handl
14ea0 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65  e should be rele
14eb0 61 73 65 64 20 62 79 20 70 61 73 73 69 6e 67 20  ased by passing 
14ec0 69 74 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65  it.** to [sqlite
14ed0 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20  3_close()] when 
14ee0 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20  it is no longer 
14ef0 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  required..**.** 
14f00 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  The [sqlite3_ope
14f10 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63  n_v2()] interfac
14f20 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 5b 73 71  e works like [sq
14f30 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 0a 2a  lite3_open()] .*
14f40 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74  * except that it
14f50 20 61 63 63 63 65 70 74 73 20 74 77 6f 20 61 64   acccepts two ad
14f60 64 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74  ditional paramet
14f70 65 72 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  ers for addition
14f80 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76  al control.** ov
14f90 65 72 20 74 68 65 20 6e 65 77 20 64 61 74 61 62  er the new datab
14fa0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  ase connection. 
14fb0 20 54 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d   The flags param
14fc0 65 74 65 72 20 63 61 6e 20 62 65 0a 2a 2a 20 6f  eter can be.** o
14fd0 6e 65 20 6f 66 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c  ne of:.**.** <ol
14fe0 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  >.** <li>  [SQLI
14ff0 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
15000 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
15010 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
15020 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  E].** <li>  [SQL
15030 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
15040 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50  TE] | [SQLITE_OP
15050 45 4e 5f 43 52 45 41 54 45 5d 0a 2a 2a 20 3c 2f  EN_CREATE].** </
15060 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  ol>.**.** The fi
15070 72 73 74 20 76 61 6c 75 65 20 6f 70 65 6e 73 20  rst value opens 
15080 74 68 65 20 64 61 74 61 62 61 73 65 20 72 65 61  the database rea
15090 64 2d 6f 6e 6c 79 2e 20 0a 2a 2a 20 49 66 20 74  d-only. .** If t
150a0 68 65 20 64 61 74 61 62 61 73 65 20 64 6f 65 73  he database does
150b0 20 6e 6f 74 20 70 72 65 76 69 6f 75 73 6c 79 20   not previously 
150c0 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20  exist, an error 
150d0 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20  is returned..** 
150e0 54 68 65 20 73 65 63 6f 6e 64 20 6f 70 74 69 6f  The second optio
150f0 6e 20 6f 70 65 6e 73 0a 2a 2a 20 74 68 65 20 64  n opens.** the d
15100 61 74 61 62 61 73 65 20 66 6f 72 20 72 65 61 64  atabase for read
15110 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20  ing and writing 
15120 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20  if possible, or 
15130 72 65 61 64 69 6e 67 20 6f 6e 6c 79 20 69 66 0a  reading only if.
15140 2a 2a 20 69 66 20 74 68 65 20 66 69 6c 65 20 69  ** if the file i
15150 73 20 77 72 69 74 65 20 70 72 6f 74 65 63 74 65  s write protecte
15160 64 2e 20 20 49 6e 20 65 69 74 68 65 72 20 63 61  d.  In either ca
15170 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  se the database.
15180 2a 2a 20 6d 75 73 74 20 61 6c 72 65 61 64 79 20  ** must already 
15190 65 78 69 73 74 20 6f 72 20 61 6e 20 65 72 72 6f  exist or an erro
151a0 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  r is returned.  
151b0 54 68 65 20 74 68 69 72 64 20 6f 70 74 69 6f 6e  The third option
151c0 0a 2a 2a 20 6f 70 65 6e 73 20 74 68 65 20 64 61  .** opens the da
151d0 74 61 62 61 73 65 20 66 6f 72 20 72 65 61 64 69  tabase for readi
151e0 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20 61  ng and writing a
151f0 6e 64 20 63 72 65 61 74 65 73 20 69 74 20 69 66  nd creates it if
15200 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20   it does.** not 
15210 61 6c 72 65 61 64 79 20 65 78 69 73 74 2e 0a 2a  already exist..*
15220 2a 20 54 68 65 20 74 68 69 72 64 20 6f 70 74 69  * The third opti
15230 6f 6e 73 20 69 73 20 62 65 68 61 76 69 6f 72 20  ons is behavior 
15240 74 68 61 74 20 69 73 20 61 6c 77 61 79 73 20 75  that is always u
15250 73 65 64 20 66 6f 72 20 5b 73 71 6c 69 74 65 33  sed for [sqlite3
15260 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20  _open()].** and 
15270 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
15280 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  )]..**.** If the
15290 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d   filename is ":m
152a0 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 6e  emory:", then an
152b0 20 70 72 69 76 61 74 65 0a 2a 2a 20 69 6e 2d 6d   private.** in-m
152c0 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20 69  emory database i
152d0 73 20 63 72 65 61 74 65 64 20 66 6f 72 20 74 68  s created for th
152e0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54  e connection.  T
152f0 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a  his in-memory.**
15300 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76   database will v
15310 61 6e 69 73 68 20 77 68 65 6e 20 74 68 65 20 64  anish when the d
15320 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
15330 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 46  on is closed.  F
15340 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e  uture.** version
15350 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74   of SQLite might
15360 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 61 64 64   make use of add
15370 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20  itional special 
15380 66 69 6c 65 6e 61 6d 65 73 0a 2a 2a 20 74 68 61  filenames.** tha
15390 74 20 62 65 67 69 6e 20 77 69 74 68 20 74 68 65  t begin with the
153a0 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e 20   ":" character. 
153b0 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64   It is recommend
153c0 65 64 20 74 68 61 74 20 0a 2a 2a 20 77 68 65 6e  ed that .** when
153d0 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65   a database file
153e0 6e 61 6d 65 20 72 65 61 6c 6c 79 20 64 6f 65 73  name really does
153f0 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 22   begin with.** "
15400 3a 22 20 74 68 61 74 20 79 6f 75 20 70 72 65 66  :" that you pref
15410 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  ix the filename 
15420 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20  with a pathname 
15430 6c 69 6b 65 20 22 2e 2f 22 20 74 6f 0a 2a 2a 20  like "./" to.** 
15440 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79 2e  avoid ambiguity.
15450 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66 69  .**.** If the fi
15460 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d 70  lename is an emp
15470 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20  ty string, then 
15480 61 20 70 72 69 76 61 74 65 20 74 65 6d 70 6f 72  a private tempor
15490 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64  ary.** on-disk d
154a0 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20  atabase will be 
154b0 63 72 65 61 74 65 64 2e 20 20 54 68 69 73 20 70  created.  This p
154c0 72 69 76 61 74 65 20 64 61 74 61 62 61 73 65 20  rivate database 
154d0 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d  will be.** autom
154e0 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64  atically deleted
154f0 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20   as soon as the 
15500 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
15510 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a  ion is closed..*
15520 2a 0a 2a 2a 20 54 68 65 20 66 6f 75 72 74 68 20  *.** The fourth 
15530 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
15540 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
15550 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
15560 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66  e.** [sqlite3_vf
15570 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64  s] object that d
15580 65 66 69 6e 65 73 20 74 68 65 20 6f 70 65 72 61  efines the opera
15590 74 69 6e 67 20 73 79 73 74 65 6d 20 0a 2a 2a 20  ting system .** 
155a0 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 74  interface that t
155b0 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20  he new database 
155c0 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c  connection shoul
155d0 64 20 75 73 65 2e 20 20 49 66 20 74 68 65 0a 2a  d use.  If the.*
155e0 2a 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  * fourth paramet
155f0 65 72 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  er is a NULL poi
15600 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20 64 65  nter then the de
15610 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76  fault [sqlite3_v
15620 66 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 69 73  fs].** object is
15630 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e   used..**.** <b>
15640 4e 6f 74 65 20 74 6f 20 77 69 6e 64 6f 77 73 20  Note to windows 
15650 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20  users:</b>  The 
15660 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 66 6f  encoding used fo
15670 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61  r the filename a
15680 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 5b 73  rgument.** of [s
15690 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 61  qlite3_open()] a
156a0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  nd [sqlite3_open
156b0 5f 76 32 28 29 5d 20 6d 75 73 74 20 62 65 20 55  _v2()] must be U
156c0 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 76  TF-8, not whatev
156d0 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 69  er.** codepage i
156e0 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69  s currently defi
156f0 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20  ned.  Filenames 
15700 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 72  containing inter
15710 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72  national.** char
15720 61 63 74 65 72 73 20 6d 75 73 74 20 62 65 20 63  acters must be c
15730 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54 46 2d  onverted to UTF-
15740 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73 73 69  8 prior to passi
15750 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20  ng them into.** 
15760 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
15770 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   or [sqlite3_ope
15780 6e 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49  n_v2()]..**.** I
15790 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
157a0 20 7b 46 31 32 37 30 31 7d 20 54 68 65 20 5b 73   {F12701} The [s
157b0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
157c0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
157d0 29 5d 2c 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20  )], and.**      
157e0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65      [sqlite3_ope
157f0 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63  n_v2()] interfac
15800 65 73 20 63 72 65 61 74 65 20 61 20 6e 65 77 0a  es create a new.
15810 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61 74  **          [dat
15820 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
15830 5d 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  ] associated wit
15840 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  h.**          th
15850 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
15860 67 69 76 65 6e 20 69 6e 20 74 68 65 69 72 20 66  given in their f
15870 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 0a  irst parameter..
15880 2a 2a 0a 2a 2a 20 7b 46 31 32 37 30 32 7d 20 54  **.** {F12702} T
15890 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  he filename argu
158a0 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70 72 65  ment is interpre
158b0 74 65 64 20 61 73 20 55 54 46 2d 38 0a 2a 2a 20  ted as UTF-8.** 
158c0 20 20 20 20 20 20 20 20 20 66 6f 72 20 5b 73 71           for [sq
158d0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 61 6e  lite3_open()] an
158e0 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  d [sqlite3_open_
158f0 76 32 28 29 5d 20 61 6e 64 20 61 73 20 55 54 46  v2()] and as UTF
15900 2d 31 36 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  -16.**          
15910 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79  in the native by
15920 74 65 20 6f 72 64 65 72 20 66 6f 72 20 5b 73 71  te order for [sq
15930 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e  lite3_open16()].
15940 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 30 33 7d 20  .**.** {F12703} 
15950 41 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e 76  A successful inv
15960 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69  ocation of [sqli
15970 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
15980 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c  lite3_open16()],
15990 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72   .**          or
159a0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
159b0 32 28 29 5d 20 77 72 69 74 65 73 20 61 20 70 6f  2()] writes a po
159c0 69 6e 74 65 72 20 74 6f 20 61 20 6e 65 77 0a 2a  inter to a new.*
159d0 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61 74 61  *          [data
159e0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
159f0 20 69 6e 74 6f 20 2a 70 70 44 62 2e 0a 2a 2a 0a   into *ppDb..**.
15a00 2a 2a 20 7b 46 31 32 37 30 34 7d 20 54 68 65 20  ** {F12704} The 
15a10 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
15a20 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  , [sqlite3_open1
15a30 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 20 20 20  6()], and.**    
15a40 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f        [sqlite3_o
15a50 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66  pen_v2()] interf
15a60 61 63 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c  aces return [SQL
15a70 49 54 45 5f 4f 4b 5d 20 75 70 6f 6e 20 73 75 63  ITE_OK] upon suc
15a80 63 65 73 73 2c 0a 2a 2a 20 20 20 20 20 20 20 20  cess,.**        
15a90 20 20 6f 72 20 61 6e 20 61 70 70 72 6f 70 72 69    or an appropri
15aa0 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ate [error code]
15ab0 20 6f 6e 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a   on failure..**.
15ac0 2a 2a 20 7b 46 31 32 37 30 36 7d 20 54 68 65 20  ** {F12706} The 
15ad0 64 65 66 61 75 6c 74 20 74 65 78 74 20 65 6e 63  default text enc
15ae0 6f 64 69 6e 67 20 66 6f 72 20 61 20 6e 65 77 20  oding for a new 
15af0 64 61 74 61 62 61 73 65 20 63 72 65 61 74 65 64  database created
15b00 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20   using.**       
15b10 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e     [sqlite3_open
15b20 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
15b30 6f 70 65 6e 5f 76 32 28 29 5d 20 77 69 6c 6c 20  open_v2()] will 
15b40 62 65 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20  be UTF-8..**.** 
15b50 7b 46 31 32 37 30 37 7d 20 54 68 65 20 64 65 66  {F12707} The def
15b60 61 75 6c 74 20 74 65 78 74 20 65 6e 63 6f 64 69  ault text encodi
15b70 6e 67 20 66 6f 72 20 61 20 6e 65 77 20 64 61 74  ng for a new dat
15b80 61 62 61 73 65 20 63 72 65 61 74 65 64 20 75 73  abase created us
15b90 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ing.**          
15ba0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
15bb0 29 5d 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 31  )] will be UTF-1
15bc0 36 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 30 39  6..**.** {F12709
15bd0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f  } The [sqlite3_o
15be0 70 65 6e 28 46 2c 44 29 5d 20 69 6e 74 65 72 66  pen(F,D)] interf
15bf0 61 63 65 20 69 73 20 65 71 75 69 76 61 6c 65 6e  ace is equivalen
15c00 74 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20  t to.**         
15c10 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
15c20 32 28 46 2c 44 2c 47 2c 30 29 5d 20 77 68 65 72  2(F,D,G,0)] wher
15c30 65 20 74 68 65 20 47 20 70 61 72 61 6d 65 74 65  e the G paramete
15c40 72 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  r is.**         
15c50 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
15c60 41 44 57 52 49 54 45 5d 7c 5b 53 51 4c 49 54 45  ADWRITE]|[SQLITE
15c70 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 0a 2a  _OPEN_CREATE]..*
15c80 2a 0a 2a 2a 20 7b 46 31 32 37 31 31 7d 20 49 66  *.** {F12711} If
15c90 20 74 68 65 20 47 20 70 61 72 61 6d 65 74 65 72   the G parameter
15ca0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
15cb0 6e 5f 76 32 28 46 2c 44 2c 47 2c 56 29 5d 20 63  n_v2(F,D,G,V)] c
15cc0 6f 6e 74 61 69 6e 73 20 74 68 65 0a 2a 2a 20 20  ontains the.**  
15cd0 20 20 20 20 20 20 20 20 62 69 74 20 76 61 6c 75          bit valu
15ce0 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  e [SQLITE_OPEN_R
15cf0 45 41 44 4f 4e 4c 59 5d 20 74 68 65 6e 20 74 68  EADONLY] then th
15d00 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
15d10 65 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  ened.**         
15d20 20 66 6f 72 20 72 65 61 64 69 6e 67 20 6f 6e 6c   for reading onl
15d30 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 31 32  y..**.** {F12712
15d40 7d 20 49 66 20 74 68 65 20 47 20 70 61 72 61 6d  } If the G param
15d50 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
15d60 5f 6f 70 65 6e 5f 76 32 28 46 2c 44 2c 47 2c 56  _open_v2(F,D,G,V
15d70 29 5d 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 0a  )] contains the.
15d80 2a 2a 20 20 20 20 20 20 20 20 20 20 62 69 74 20  **          bit 
15d90 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 4f 50  value [SQLITE_OP
15da0 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 74 68  EN_READWRITE] th
15db0 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
15dc0 69 73 20 6f 70 65 6e 65 64 0a 2a 2a 20 20 20 20  is opened.**    
15dd0 20 20 20 20 20 20 72 65 61 64 69 6e 67 20 61 6e        reading an
15de0 64 20 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73  d writing if pos
15df0 73 69 62 6c 65 2c 20 6f 72 20 66 6f 72 20 72 65  sible, or for re
15e00 61 64 69 6e 67 20 6f 6e 6c 79 20 69 66 20 74 68  ading only if th
15e10 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69  e.**          fi
15e20 6c 65 20 69 73 20 77 72 69 74 65 20 70 72 6f 74  le is write prot
15e30 65 63 74 65 64 20 62 79 20 74 68 65 20 6f 70 65  ected by the ope
15e40 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 0a 2a  rating system..*
15e50 2a 0a 2a 2a 20 7b 46 31 32 37 31 33 7d 20 49 66  *.** {F12713} If
15e60 20 74 68 65 20 47 20 70 61 72 61 6d 65 74 65 72   the G parameter
15e70 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
15e80 6e 28 76 32 28 46 2c 44 2c 47 2c 56 29 5d 20 6f  n(v2(F,D,G,V)] o
15e90 6d 69 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  mits the.**     
15ea0 20 20 20 20 20 62 69 74 20 76 61 6c 75 65 20 5b       bit value [
15eb0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
15ec0 54 45 5d 20 61 6e 64 20 74 68 65 20 64 61 74 61  TE] and the data
15ed0 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a  base does not.**
15ee0 20 20 20 20 20 20 20 20 20 20 70 72 65 76 69 6f            previo
15ef0 75 73 6c 79 20 65 78 69 73 74 2c 20 61 6e 20 65  usly exist, an e
15f00 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
15f10 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 31 34 7d  ..**.** {F12714}
15f20 20 49 66 20 74 68 65 20 47 20 70 61 72 61 6d 65   If the G parame
15f30 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
15f40 6f 70 65 6e 28 76 32 28 46 2c 44 2c 47 2c 56 29  open(v2(F,D,G,V)
15f50 5d 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 0a 2a  ] contains the.*
15f60 2a 20 20 20 20 20 20 20 20 20 20 62 69 74 20 76  *          bit v
15f70 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  alue [SQLITE_OPE
15f80 4e 5f 43 52 45 41 54 45 5d 20 61 6e 64 20 74 68  N_CREATE] and th
15f90 65 20 64 61 74 61 62 61 73 65 20 64 6f 65 73 20  e database does 
15fa0 6e 6f 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  not.**          
15fb0 70 72 65 76 69 6f 75 73 6c 79 20 65 78 69 73 74  previously exist
15fc0 2c 20 74 68 65 6e 20 61 6e 20 61 74 74 65 6d 70  , then an attemp
15fd0 74 20 69 73 20 6d 61 64 65 20 74 6f 20 63 72 65  t is made to cre
15fe0 61 74 65 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20  ate and.**      
15ff0 20 20 20 20 69 6e 69 74 69 61 6c 69 7a 65 20 74      initialize t
16000 68 65 20 64 61 74 61 62 61 73 65 2e 0a 2a 2a 0a  he database..**.
16010 2a 2a 20 7b 46 31 32 37 31 37 7d 20 49 66 20 74  ** {F12717} If t
16020 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  he filename argu
16030 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  ment to [sqlite3
16040 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
16050 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 0a 2a 2a  e3_open16()],.**
16060 20 20 20 20 20 20 20 20 20 20 6f 72 20 5b 73 71            or [sq
16070 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
16080 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20   is ":memory:", 
16090 74 68 65 6e 20 61 6e 20 70 72 69 76 61 74 65 2c  then an private,
160a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 70 68  .**          eph
160b0 65 6d 65 72 61 6c 2c 20 69 6e 2d 6d 65 6d 6f 72  emeral, in-memor
160c0 79 20 64 61 74 61 62 61 73 65 20 69 73 20 63 72  y database is cr
160d0 65 61 74 65 64 20 66 6f 72 20 74 68 65 20 63 6f  eated for the co
160e0 6e 6e 65 63 74 69 6f 6e 2e 0a 2a 2a 20 20 20 20  nnection..**    
160f0 20 20 20 20 20 20 3c 74 6f 64 6f 3e 49 73 20 53        <todo>Is S
16100 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
16110 45 7c 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  E|SQLITE_OPEN_RE
16120 41 44 57 52 49 54 45 20 72 65 71 75 69 72 65 64  ADWRITE required
16130 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20  .**          in 
16140 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
16150 29 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20  )?</todo>.**.** 
16160 7b 46 31 32 37 31 39 7d 20 49 66 20 74 68 65 20  {F12719} If the 
16170 66 69 6c 65 6e 61 6d 65 20 69 73 20 4e 55 4c 4c  filename is NULL
16180 20 6f 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72   or an empty str
16190 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 69 76  ing, then a priv
161a0 61 74 65 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ate,.**         
161b0 20 65 70 68 65 72 6d 65 72 61 6c 20 6f 6e 2d 64   ephermeral on-d
161c0 69 73 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c  isk database wil
161d0 6c 20 62 65 20 63 72 65 61 74 65 64 2e 0a 2a 2a  l be created..**
161e0 20 20 20 20 20 20 20 20 20 20 3c 74 6f 64 6f 3e            <todo>
161f0 49 73 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  Is SQLITE_OPEN_C
16200 52 45 41 54 45 7c 53 51 4c 49 54 45 5f 4f 50 45  REATE|SQLITE_OPE
16210 4e 5f 52 45 41 44 57 52 49 54 45 20 72 65 71 75  N_READWRITE requ
16220 69 72 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  ired.**         
16230 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   in sqlite3_open
16240 5f 76 32 28 29 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a  _v2()?</todo>.**
16250 0a 2a 2a 20 7b 46 31 32 37 32 31 7d 20 54 68 65  .** {F12721} The
16260 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
16270 63 74 69 6f 6e 5d 20 63 72 65 61 74 65 64 20 62  ction] created b
16280 79 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  y .**          [
16290 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
162a0 46 2c 44 2c 47 2c 56 29 5d 20 77 69 6c 6c 20 75  F,D,G,V)] will u
162b0 73 65 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  se the.**       
162c0 20 20 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d     [sqlite3_vfs]
162d0 20 6f 62 6a 65 63 74 20 69 64 65 6e 74 69 66 69   object identifi
162e0 65 64 20 62 79 20 74 68 65 20 56 20 70 61 72 61  ed by the V para
162f0 6d 65 74 65 72 2c 20 6f 72 0a 2a 2a 20 20 20 20  meter, or.**    
16300 20 20 20 20 20 20 74 68 65 20 64 65 66 61 75 6c        the defaul
16310 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  t [sqlite3_vfs] 
16320 6f 62 6a 65 63 74 20 69 73 20 56 20 69 73 20 61  object is V is a
16330 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
16340 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70  /.int sqlite3_op
16350 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  en(.  const char
16360 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a   *filename,   /*
16370 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   Database filena
16380 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20  me (UTF-8) */.  
16390 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20  sqlite3 **ppDb  
163a0 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20          /* OUT: 
163b0 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65  SQLite db handle
163c0 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
163d0 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e  e3_open16(.  con
163e0 73 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d  st void *filenam
163f0 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  e,   /* Database
16400 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31   filename (UTF-1
16410 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20  6) */.  sqlite3 
16420 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20  **ppDb          
16430 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64  /* OUT: SQLite d
16440 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69  b handle */.);.i
16450 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  nt sqlite3_open_
16460 76 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  v2(.  const char
16470 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a   *filename,   /*
16480 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   Database filena
16490 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20  me (UTF-8) */.  
164a0 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20  sqlite3 **ppDb, 
164b0 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20          /* OUT: 
164c0 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65  SQLite db handle
164d0 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c   */.  int flags,
164e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
164f0 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73   Flags */.  cons
16500 74 20 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20  t char *zVfs    
16510 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56      /* Name of V
16520 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65  FS module to use
16530 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.);../*.** CA
16540 50 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f  PI3REF: Error Co
16550 64 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73  des And Messages
16560 20 7b 46 31 32 38 30 30 7d 0a 2a 2a 0a 2a 2a 20   {F12800}.**.** 
16570 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63  The sqlite3_errc
16580 6f 64 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ode() interface 
16590 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65  returns the nume
165a0 72 69 63 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  ric.** [SQLITE_O
165b0 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 5d  K | result code]
165c0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52   or [SQLITE_IOER
165d0 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65  R_READ | extende
165e0 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 0a 2a  d result code].*
165f0 2a 20 66 6f 72 20 74 68 65 20 6d 6f 73 74 20 72  * for the most r
16600 65 63 65 6e 74 20 66 61 69 6c 65 64 20 73 71 6c  ecent failed sql
16610 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 20  ite3_* API call 
16620 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69  associated.** wi
16630 74 68 20 5b 73 71 6c 69 74 65 33 5d 20 68 61 6e  th [sqlite3] han
16640 64 6c 65 20 27 64 62 27 2e 20 49 66 20 61 20 70  dle 'db'. If a p
16650 72 69 6f 72 20 41 50 49 20 63 61 6c 6c 20 66 61  rior API call fa
16660 69 6c 65 64 20 62 75 74 20 74 68 65 0a 2a 2a 20  iled but the.** 
16670 6d 6f 73 74 20 72 65 63 65 6e 74 20 41 50 49 20  most recent API 
16680 63 61 6c 6c 20 73 75 63 63 65 65 64 65 64 2c 20  call succeeded, 
16690 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
166a0 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 65 72   from sqlite3_er
166b0 72 63 6f 64 65 28 29 0a 2a 2a 20 69 73 20 75 6e  rcode().** is un
166c0 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  defined..**.** T
166d0 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  he sqlite3_errms
166e0 67 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  g() and sqlite3_
166f0 65 72 72 6d 73 67 31 36 28 29 20 72 65 74 75 72  errmsg16() retur
16700 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61  n English-langua
16710 67 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20  ge.** text that 
16720 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72  describes the er
16730 72 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20 55  ror, as either U
16740 54 46 38 20 6f 72 20 55 54 46 31 36 20 72 65 73  TF8 or UTF16 res
16750 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 4d 65  pectively..** Me
16760 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
16770 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
16780 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64  tring is managed
16790 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20   internally..** 
167a0 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
167b0 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
167c0 20 77 6f 72 72 79 20 77 69 74 68 20 66 72 65 65   worry with free
167d0 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e 0a  ing the result..
167e0 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20  ** However, the 
167f0 65 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69 67  error string mig
16800 68 74 20 62 65 20 6f 76 65 72 77 72 69 74 74 65  ht be overwritte
16810 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 64  n or deallocated
16820 20 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e   by.** subsequen
16830 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72  t calls to other
16840 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
16850 65 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a  e functions..**.
16860 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
16870 2a 0a 2a 2a 20 7b 46 31 32 38 30 31 7d 20 54 68  *.** {F12801} Th
16880 65 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  e [sqlite3_errco
16890 64 65 28 44 29 5d 20 69 6e 74 65 72 66 61 63 65  de(D)] interface
168a0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
168b0 65 72 69 63 0a 2a 2a 20 20 20 20 20 20 20 20 20  eric.**         
168c0 20 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 72 65   [SQLITE_OK | re
168d0 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a  sult code] or.**
168e0 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54            [SQLIT
168f0 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 65  E_IOERR_READ | e
16900 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
16910 6f 64 65 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ode].**         
16920 20 66 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 65   for the most re
16930 63 65 6e 74 6c 79 20 66 61 69 6c 65 64 20 69 6e  cently failed in
16940 74 65 72 66 61 63 65 20 63 61 6c 6c 20 61 73 73  terface call ass
16950 6f 63 69 61 74 65 64 0a 2a 2a 20 20 20 20 20 20  ociated.**      
16960 20 20 20 20 77 69 74 68 20 5b 64 61 74 61 62 61      with [databa
16970 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
16980 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 38 30 33 7d  ..**.** {F12803}
16990 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 72   The [sqlite3_er
169a0 72 6d 73 67 28 44 29 5d 20 61 6e 64 20 5b 73 71  rmsg(D)] and [sq
169b0 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 44  lite3_errmsg16(D
169c0 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  )].**          i
169d0 6e 74 65 72 66 61 63 65 73 20 72 65 74 75 72 6e  nterfaces return
169e0 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67   English-languag
169f0 65 20 74 65 78 74 20 74 68 61 74 20 64 65 73 63  e text that desc
16a00 72 69 62 65 73 0a 2a 2a 20 20 20 20 20 20 20 20  ribes.**        
16a10 20 20 74 68 65 20 65 72 72 6f 72 20 69 6e 20 74    the error in t
16a20 68 65 20 6d 6f 73 74 6c 79 20 72 65 63 65 6e 74  he mostly recent
16a30 6c 79 20 66 61 69 6c 65 64 20 69 6e 74 65 72 66  ly failed interf
16a40 61 63 65 20 63 61 6c 6c 2c 0a 2a 2a 20 20 20 20  ace call,.**    
16a50 20 20 20 20 20 20 65 6e 63 6f 64 65 64 20 61 73        encoded as
16a60 20 65 69 74 68 65 72 20 55 54 46 38 20 6f 72 20   either UTF8 or 
16a70 55 54 46 31 36 20 72 65 73 70 65 63 74 69 76 65  UTF16 respective
16a80 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 38 30  ly..**.** {F1280
16a90 37 7d 20 54 68 65 20 73 74 72 69 6e 67 73 20 72  7} The strings r
16aa0 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
16ab0 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 61 6e  te3_errmsg()] an
16ac0 64 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  d [sqlite3_errms
16ad0 67 31 36 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20  g16()].**       
16ae0 20 20 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74     are valid unt
16af0 69 6c 20 74 68 65 20 6e 65 78 74 20 53 51 4c 69  il the next SQLi
16b00 74 65 20 69 6e 74 65 72 66 61 63 65 20 63 61 6c  te interface cal
16b10 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 38 30 38  l..**.** {F12808
16b20 7d 20 43 61 6c 6c 73 20 74 6f 20 41 50 49 20 72  } Calls to API r
16b30 6f 75 74 69 6e 65 73 20 74 68 61 74 20 64 6f 20  outines that do 
16b40 6e 6f 74 20 72 65 74 75 72 6e 20 61 6e 20 65 72  not return an er
16b50 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 20 20 20 20  ror code.**     
16b60 20 20 20 20 20 28 65 78 61 6d 70 6c 65 3a 20 5b       (example: [
16b70 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
16b80 6e 74 28 29 5d 29 20 64 6f 20 6e 6f 74 0a 2a 2a  nt()]) do not.**
16b90 20 20 20 20 20 20 20 20 20 20 63 68 61 6e 67 65            change
16ba0 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20   the error code 
16bb0 6f 72 20 6d 65 73 73 61 67 65 20 72 65 74 75 72  or message retur
16bc0 6e 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20  ned by.**       
16bd0 20 20 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63     [sqlite3_errc
16be0 6f 64 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  ode()], [sqlite3
16bf0 5f 65 72 72 6d 73 67 28 29 5d 2c 20 6f 72 20 5b  _errmsg()], or [
16c00 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
16c10 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 38  ()]..**.** {F128
16c20 30 39 7d 20 49 6e 74 65 72 66 61 63 65 73 20 74  09} Interfaces t
16c30 68 61 74 20 61 72 65 20 6e 6f 74 20 61 73 73 6f  hat are not asso
16c40 63 69 61 74 65 64 20 77 69 74 68 20 61 20 73 70  ciated with a sp
16c50 65 63 69 66 69 63 0a 2a 2a 20 20 20 20 20 20 20  ecific.**       
16c60 20 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e     [database con
16c70 6e 65 63 74 69 6f 6e 5d 20 28 65 78 61 6d 70 6c  nection] (exampl
16c80 65 73 3a 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  es:.**          
16c90 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66  [sqlite3_mprintf
16ca0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
16cb0 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61  enable_shared_ca
16cc0 63 68 65 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20  che()].**       
16cd0 20 20 20 64 6f 20 6e 6f 74 20 63 68 61 6e 67 65     do not change
16ce0 20 74 68 65 20 76 61 6c 75 65 73 20 72 65 74 75   the values retu
16cf0 72 6e 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20  rned by.**      
16d00 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 65 72 72      [sqlite3_err
16d10 63 6f 64 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65  code()], [sqlite
16d20 33 5f 65 72 72 6d 73 67 28 29 5d 2c 20 6f 72 20  3_errmsg()], or 
16d30 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31  [sqlite3_errmsg1
16d40 36 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  6()]..*/.int sql
16d50 69 74 65 33 5f 65 72 72 63 6f 64 65 28 73 71 6c  ite3_errcode(sql
16d60 69 74 65 33 20 2a 64 62 29 3b 0a 63 6f 6e 73 74  ite3 *db);.const
16d70 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65   char *sqlite3_e
16d80 72 72 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b  rrmsg(sqlite3*);
16d90 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
16da0 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 73 71  ite3_errmsg16(sq
16db0 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
16dc0 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 53 74  CAPI3REF: SQL St
16dd0 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 20 7b  atement Object {
16de0 46 31 33 30 30 30 7d 0a 2a 2a 20 4b 45 59 57 4f  F13000}.** KEYWO
16df0 52 44 53 3a 20 7b 70 72 65 70 61 72 65 64 20 73  RDS: {prepared s
16e00 74 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61  tatement} {prepa
16e10 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a  red statements}.
16e20 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63  **.** An instanc
16e30 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
16e40 20 72 65 70 72 65 73 65 6e 74 20 73 69 6e 67 6c   represent singl
16e50 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
16e60 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 62 6a 65 63  .  This.** objec
16e70 74 20 69 73 20 76 61 72 69 6f 75 73 6c 79 20 6b  t is variously k
16e80 6e 6f 77 6e 20 61 73 20 61 20 22 70 72 65 70 61  nown as a "prepa
16e90 72 65 64 20 73 74 61 74 65 6d 65 6e 74 22 20 6f  red statement" o
16ea0 72 20 61 20 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65  r a .** "compile
16eb0 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 22  d SQL statement"
16ec0 20 6f 72 20 73 69 6d 70 6c 79 20 61 73 20 61 20   or simply as a 
16ed0 22 73 74 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a 20  "statement"..** 
16ee0 0a 2a 2a 20 54 68 65 20 6c 69 66 65 20 6f 66 20  .** The life of 
16ef0 61 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65  a statement obje
16f00 63 74 20 67 6f 65 73 20 73 6f 6d 65 74 68 69 6e  ct goes somethin
16f10 67 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a  g like this:.**.
16f20 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ol>.** <li> 
16f30 43 72 65 61 74 65 20 74 68 65 20 6f 62 6a 65 63  Create the objec
16f40 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
16f50 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
16f60 72 20 61 20 72 65 6c 61 74 65 64 0a 2a 2a 20 20  r a related.**  
16f70 20 20 20 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a      function..**
16f80 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75 65   <li> Bind value
16f90 73 20 74 6f 20 68 6f 73 74 20 70 61 72 61 6d 65  s to host parame
16fa0 74 65 72 73 20 75 73 69 6e 67 0a 2a 2a 20 20 20  ters using.**   
16fb0 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64     [sqlite3_bind
16fc0 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f  _blob | sqlite3_
16fd0 62 69 6e 64 5f 2a 20 69 6e 74 65 72 66 61 63 65  bind_* interface
16fe0 73 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20  s]..** <li> Run 
16ff0 74 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c 69  the SQL by calli
17000 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ng [sqlite3_step
17010 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  ()] one or more 
17020 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52  times..** <li> R
17030 65 73 65 74 20 74 68 65 20 73 74 61 74 65 6d 65  eset the stateme
17040 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  nt using [sqlite
17050 33 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e 20  3_reset()] then 
17060 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20  go back.**      
17070 74 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20 74  to step 2.  Do t
17080 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65  his zero or more
17090 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20   times..** <li> 
170a0 44 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a 65  Destroy the obje
170b0 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ct using [sqlite
170c0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a  3_finalize()]..*
170d0 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65  * </ol>.**.** Re
170e0 66 65 72 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61  fer to documenta
170f0 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75  tion on individu
17100 61 6c 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65  al methods above
17110 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a   for additional.
17120 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  ** information..
17130 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
17140 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 73  t sqlite3_stmt s
17150 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a  qlite3_stmt;../*
17160 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
17170 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53  mpiling An SQL S
17180 74 61 74 65 6d 65 6e 74 20 7b 46 31 33 30 31 30  tatement {F13010
17190 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75  }.**.** To execu
171a0 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c  te an SQL query,
171b0 20 69 74 20 6d 75 73 74 20 66 69 72 73 74 20 62   it must first b
171c0 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20  e compiled into 
171d0 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70  a byte-code.** p
171e0 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65  rogram using one
171f0 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
17200 65 73 2e 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  es. .**.** The f
17210 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 22 64  irst argument "d
17220 62 22 20 69 73 20 61 6e 20 5b 64 61 74 61 62 61  b" is an [databa
17230 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 0a  se connection] .
17240 2a 2a 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ** obtained from
17250 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f   a prior call to
17260 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
17270 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
17280 5f 76 32 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71  _v2()].** or [sq
17290 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e  lite3_open16()].
172a0 20 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20   .** The second 
172b0 61 72 67 75 6d 65 6e 74 20 22 7a 53 71 6c 22 20  argument "zSql" 
172c0 69 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  is the statement
172d0 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c   to be compiled,
172e0 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65   encoded.** as e
172f0 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55  ither UTF-8 or U
17300 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69  TF-16.  The sqli
17310 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e  te3_prepare() an
17320 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
17330 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66  e_v2().** interf
17340 61 63 65 73 20 75 73 65 73 20 55 54 46 2d 38 20  aces uses UTF-8 
17350 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
17360 61 72 65 31 36 28 29 20 61 6e 64 20 73 71 6c 69  are16() and sqli
17370 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
17380 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 36  ().** use UTF-16
17390 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 49 66  . {END}.**.** If
173a0 20 74 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d   the nByte argum
173b0 65 6e 74 20 69 73 20 6c 65 73 73 0a 2a 2a 20 74  ent is less.** t
173c0 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65 6e 20 7a  han zero, then z
173d0 53 71 6c 20 69 73 20 72 65 61 64 20 75 70 20 74  Sql is read up t
173e0 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f  o the first zero
173f0 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20   terminator..** 
17400 49 66 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d  If nByte is non-
17410 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 69  negative, then i
17420 74 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d  t is the maximum
17430 20 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 62   number of .** b
17440 79 74 65 73 20 72 65 61 64 20 66 72 6f 6d 20 7a  ytes read from z
17450 53 71 6c 2e 20 20 57 68 65 6e 20 6e 42 79 74 65  Sql.  When nByte
17460 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
17470 2c 20 74 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 74  , the.** zSql st
17480 72 69 6e 67 20 65 6e 64 73 20 61 74 20 65 69 74  ring ends at eit
17490 68 65 72 20 74 68 65 20 66 69 72 73 74 20 27 5c  her the first '\
174a0 30 30 30 27 20 6f 72 20 27 5c 75 30 30 30 30 27  000' or '\u0000'
174b0 20 63 68 61 72 61 63 74 65 72 20 6f 72 20 0a 2a   character or .*
174c0 2a 20 75 6e 74 69 6c 20 74 68 65 20 6e 42 79 74  * until the nByt
174d0 65 2d 74 68 20 62 79 74 65 2c 20 77 68 69 63 68  e-th byte, which
174e0 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74  ever comes first
174f0 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 2a 70  . {END}.**.** *p
17500 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f  zTail is made to
17510 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 66 69   point to the fi
17520 72 73 74 20 62 79 74 65 20 70 61 73 74 20 74 68  rst byte past th
17530 65 20 65 6e 64 20 6f 66 20 74 68 65 0a 2a 2a 20  e end of the.** 
17540 66 69 72 73 74 20 53 51 4c 20 73 74 61 74 65 6d  first SQL statem
17550 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68  ent in zSql.  Th
17560 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c  ese routines onl
17570 79 20 63 6f 6d 70 69 6c 65 73 20 74 68 65 20 66  y compiles the f
17580 69 72 73 74 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  irst.** statemen
17590 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70  t in zSql, so *p
175a0 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f  zTail is left po
175b0 69 6e 74 69 6e 67 20 74 6f 20 77 68 61 74 20 72  inting to what r
175c0 65 6d 61 69 6e 73 0a 2a 2a 20 75 6e 63 6f 6d 70  emains.** uncomp
175d0 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 2a 70 70 53  iled..**.** *ppS
175e0 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f 69 6e  tmt is left poin
175f0 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c  ting to a compil
17600 65 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ed [prepared sta
17610 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63 61 6e  tement] that can
17620 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 64 20   be.** executed 
17630 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73  using [sqlite3_s
17640 74 65 70 28 29 5d 2e 20 20 4f 72 20 69 66 20 74  tep()].  Or if t
17650 68 65 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72  here is an error
17660 2c 20 2a 70 70 53 74 6d 74 20 69 73 0a 2a 2a 20  , *ppStmt is.** 
17670 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 20 20 49 66  set to NULL.  If
17680 20 74 68 65 20 69 6e 70 75 74 20 74 65 78 74 20   the input text 
17690 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20  contains no SQL 
176a0 28 69 66 20 74 68 65 20 69 6e 70 75 74 0a 2a 2a  (if the input.**
176b0 20 69 73 20 61 6e 64 20 65 6d 70 74 79 20 73 74   is and empty st
176c0 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e  ring or a commen
176d0 74 29 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20  t) then *ppStmt 
176e0 69 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a  is set to NULL..
176f0 2a 2a 20 7b 55 31 33 30 31 38 7d 20 54 68 65 20  ** {U13018} The 
17700 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72  calling procedur
17710 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65  e is responsible
17720 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68   for deleting th
17730 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 53 51  e.** compiled SQ
17740 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 75  L statement.** u
17750 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69  sing [sqlite3_fi
17760 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74 65 72 20  nalize()] after 
17770 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  it has finished 
17780 77 69 74 68 20 69 74 2e 0a 2a 2a 0a 2a 2a 20 4f  with it..**.** O
17790 6e 20 73 75 63 63 65 73 73 2c 20 5b 53 51 4c 49  n success, [SQLI
177a0 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e  TE_OK] is return
177b0 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61  ed.  Otherwise a
177c0 6e 20 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64  n .** [error cod
177d0 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  e] is returned..
177e0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
177f0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 61  3_prepare_v2() a
17800 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
17810 72 65 31 36 5f 76 32 28 29 20 69 6e 74 65 72 66  re16_v2() interf
17820 61 63 65 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f  aces are.** reco
17830 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20  mmended for all 
17840 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 20 54 68  new programs. Th
17850 65 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65  e two older inte
17860 72 66 61 63 65 73 20 61 72 65 20 72 65 74 61 69  rfaces are retai
17870 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77  ned.** for backw
17880 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
17890 74 79 2c 20 62 75 74 20 74 68 65 69 72 20 75 73  ty, but their us
178a0 65 20 69 73 20 64 69 73 63 6f 75 72 61 67 65 64  e is discouraged
178b0 2e 0a 2a 2a 20 49 6e 20 74 68 65 20 22 76 32 22  ..** In the "v2"
178c0 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65   interfaces, the
178d0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
178e0 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 20 72  ent.** that is r
178f0 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b 73 71  eturned (the [sq
17900 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65  lite3_stmt] obje
17910 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 20 63  ct) contains a c
17920 6f 70 79 20 6f 66 20 74 68 65 20 0a 2a 2a 20 6f  opy of the .** o
17930 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74  riginal SQL text
17940 2e 20 7b 45 4e 44 7d 20 54 68 69 73 20 63 61 75  . {END} This cau
17950 73 65 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ses the [sqlite3
17960 5f 73 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61  _step()] interfa
17970 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20  ce to.** behave 
17980 61 20 64 69 66 66 65 72 65 6e 74 6c 79 20 69 6e  a differently in
17990 20 74 77 6f 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a   two ways:.**.**
179a0 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a   <ol>.** <li>.**
179b0 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65   If the database
179c0 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 73 2c   schema changes,
179d0 20 69 6e 73 74 65 61 64 20 6f 66 20 72 65 74 75   instead of retu
179e0 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43  rning [SQLITE_SC
179f0 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61  HEMA] as it.** a
17a00 6c 77 61 79 73 20 75 73 65 64 20 74 6f 20 64 6f  lways used to do
17a10 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
17a20 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69  )] will automati
17a30 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20  cally recompile 
17a40 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65  the SQL.** state
17a50 6d 65 6e 74 20 61 6e 64 20 74 72 79 20 74 6f 20  ment and try to 
17a60 72 75 6e 20 69 74 20 61 67 61 69 6e 2e 20 20 49  run it again.  I
17a70 66 20 74 68 65 20 73 63 68 65 6d 61 20 68 61 73  f the schema has
17a80 20 63 68 61 6e 67 65 64 20 69 6e 0a 2a 2a 20 61   changed in.** a
17a90 20 77 61 79 20 74 68 61 74 20 6d 61 6b 65 73 20   way that makes 
17aa0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 6e 6f  the statement no
17ab0 20 6c 6f 6e 67 65 72 20 76 61 6c 69 64 2c 20 5b   longer valid, [
17ac0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
17ad0 77 69 6c 6c 20 73 74 69 6c 6c 0a 2a 2a 20 72 65  will still.** re
17ae0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48  turn [SQLITE_SCH
17af0 45 4d 41 5d 2e 20 20 42 75 74 20 75 6e 6c 69 6b  EMA].  But unlik
17b00 65 20 74 68 65 20 6c 65 67 61 63 79 20 62 65 68  e the legacy beh
17b10 61 76 69 6f 72 2c 20 0a 2a 2a 20 5b 53 51 4c 49  avior, .** [SQLI
17b20 54 45 5f 53 43 48 45 4d 41 5d 20 69 73 20 6e 6f  TE_SCHEMA] is no
17b30 77 20 61 20 66 61 74 61 6c 20 65 72 72 6f 72 2e  w a fatal error.
17b40 20 20 43 61 6c 6c 69 6e 67 0a 2a 2a 20 5b 73 71    Calling.** [sq
17b50 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
17b60 28 29 5d 20 61 67 61 69 6e 20 77 69 6c 6c 20 6e  ()] again will n
17b70 6f 74 20 6d 61 6b 65 20 74 68 65 0a 2a 2a 20 65  ot make the.** e
17b80 72 72 6f 72 20 67 6f 20 61 77 61 79 2e 20 20 4e  rror go away.  N
17b90 6f 74 65 3a 20 75 73 65 20 5b 73 71 6c 69 74 65  ote: use [sqlite
17ba0 33 5f 65 72 72 6d 73 67 28 29 5d 20 74 6f 20 66  3_errmsg()] to f
17bb0 69 6e 64 20 74 68 65 20 74 65 78 74 0a 2a 2a 20  ind the text.** 
17bc0 6f 66 20 74 68 65 20 70 61 72 73 69 6e 67 20 65  of the parsing e
17bd0 72 72 6f 72 20 74 68 61 74 20 72 65 73 75 6c 74  rror that result
17be0 73 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f  s in an [SQLITE_
17bf0 53 43 48 45 4d 41 5d 20 72 65 74 75 72 6e 2e 20  SCHEMA] return. 
17c00 7b 45 4e 44 7d 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a  {END}.** </li>.*
17c10 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 57 68 65  *.** <li>.** Whe
17c20 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  n an error occur
17c30 73 2c 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  s, .** [sqlite3_
17c40 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74  step()] will ret
17c50 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64  urn one of the d
17c60 65 74 61 69 6c 65 64 20 0a 2a 2a 20 5b 65 72 72  etailed .** [err
17c70 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78  or codes] or [ex
17c80 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64  tended error cod
17c90 65 73 5d 2e 20 0a 2a 2a 20 54 68 65 20 6c 65 67  es]. .** The leg
17ca0 61 63 79 20 62 65 68 61 76 69 6f 72 20 77 61 73  acy behavior was
17cb0 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 73   that [sqlite3_s
17cc0 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c  tep()] would onl
17cd0 79 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65 72  y return a gener
17ce0 69 63 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52  ic.** [SQLITE_ER
17cf0 52 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f 64 65  ROR] result code
17d00 20 61 6e 64 20 79 6f 75 20 77 6f 75 6c 64 20 68   and you would h
17d10 61 76 65 20 74 6f 20 6d 61 6b 65 20 61 20 73 65  ave to make a se
17d20 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  cond call to.** 
17d30 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
17d40 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69  ] in order to fi
17d50 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  nd the underlyin
17d60 67 20 63 61 75 73 65 20 6f 66 20 74 68 65 20 70  g cause of the p
17d70 72 6f 62 6c 65 6d 2e 0a 2a 2a 20 57 69 74 68 20  roblem..** With 
17d80 74 68 65 20 22 76 32 22 20 70 72 65 70 61 72 65  the "v2" prepare
17d90 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65   interfaces, the
17da0 20 75 6e 64 65 72 6c 79 69 6e 67 20 72 65 61 73   underlying reas
17db0 6f 6e 20 66 6f 72 20 74 68 65 20 65 72 72 6f 72  on for the error
17dc0 20 69 73 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20   is.** returned 
17dd0 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20  immediately..** 
17de0 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a  </li>.** </ol>.*
17df0 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
17e00 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 30 31 31 7d 20  .**.** {F13011} 
17e10 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  The [sqlite3_pre
17e20 70 61 72 65 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e  pare(db,zSql,...
17e30 29 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20  )] and.**       
17e40 20 20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70     [sqlite3_prep
17e50 61 72 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 2e  are_v2(db,zSql,.
17e60 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20  ..)] interfaces 
17e70 69 6e 74 65 72 70 72 65 74 20 74 68 65 0a 2a 2a  interpret the.**
17e80 20 20 20 20 20 20 20 20 20 20 74 65 78 74 20 69            text i
17e90 6e 20 74 68 65 69 72 20 7a 53 71 6c 20 70 61 72  n their zSql par
17ea0 61 6d 65 74 65 72 20 61 73 20 55 54 46 2d 38 2e  ameter as UTF-8.
17eb0 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 30 31 32 7d 20  .**.** {F13012} 
17ec0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  The [sqlite3_pre
17ed0 70 61 72 65 31 36 28 64 62 2c 7a 53 71 6c 2c 2e  pare16(db,zSql,.
17ee0 2e 2e 29 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 20  ..)] and.**     
17ef0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 70 72       [sqlite3_pr
17f00 65 70 61 72 65 31 36 5f 76 32 28 64 62 2c 7a 53  epare16_v2(db,zS
17f10 71 6c 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61  ql,...)] interfa
17f20 63 65 73 20 69 6e 74 65 72 70 72 65 74 20 74 68  ces interpret th
17f30 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 65  e.**          te
17f40 78 74 20 69 6e 20 74 68 65 69 72 20 7a 53 71 6c  xt in their zSql
17f50 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 55 54   parameter as UT
17f60 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69  F-16 in the nati
17f70 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a  ve byte order..*
17f80 2a 0a 2a 2a 20 7b 46 31 33 30 31 33 7d 20 49 66  *.** {F13013} If
17f90 20 74 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d   the nByte argum
17fa0 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ent to [sqlite3_
17fb0 70 72 65 70 61 72 65 5f 76 32 28 64 62 2c 7a 53  prepare_v2(db,zS
17fc0 71 6c 2c 6e 42 79 74 65 2c 2e 2e 2e 29 5d 0a 2a  ql,nByte,...)].*
17fd0 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64 20 69  *          and i
17fe0 74 73 20 76 61 72 69 61 6e 74 73 20 69 73 20 6c  ts variants is l
17ff0 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20 74  ess than zero, t
18000 68 65 6e 20 53 51 4c 20 74 65 78 74 20 69 73 0a  hen SQL text is.
18010 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 61 64  **          read
18020 20 66 72 6f 6d 20 7a 53 71 6c 20 69 73 20 72 65   from zSql is re
18030 61 64 20 75 70 20 74 6f 20 74 68 65 20 66 69 72  ad up to the fir
18040 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  st zero terminat
18050 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 30 31  or..**.** {F1301
18060 34 7d 20 49 66 20 74 68 65 20 6e 42 79 74 65 20  4} If the nByte 
18070 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c  argument to [sql
18080 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
18090 64 62 2c 7a 53 71 6c 2c 6e 42 79 74 65 2c 2e 2e  db,zSql,nByte,..
180a0 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  .)].**          
180b0 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73  and its variants
180c0 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
180d0 2c 20 74 68 65 6e 20 6e 42 79 74 65 73 20 62 79  , then nBytes by
180e0 74 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  tes.**          
180f0 53 51 4c 20 74 65 78 74 20 69 73 20 72 65 61 64  SQL text is read
18100 20 66 72 6f 6d 20 7a 53 71 6c 2e 0a 2a 2a 0a 2a   from zSql..**.*
18110 2a 20 7b 46 31 33 30 31 35 7d 20 49 6e 20 5b 73  * {F13015} In [s
18120 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
18130 32 28 64 62 2c 7a 53 71 6c 2c 4e 2c 50 2c 70 7a  2(db,zSql,N,P,pz
18140 54 61 69 6c 29 5d 20 61 6e 64 20 69 74 73 20 76  Tail)] and its v
18150 61 72 69 61 6e 74 73 0a 2a 2a 20 20 20 20 20 20  ariants.**      
18160 20 20 20 20 69 66 20 74 68 65 20 7a 53 71 6c 20      if the zSql 
18170 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61  input text conta
18180 69 6e 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  ins more than on
18190 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a  e SQL statement.
181a0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64 20  **          and 
181b0 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55  pzTail is not NU
181c0 4c 4c 2c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c  LL, then *pzTail
181d0 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e   is made to poin
181e0 74 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20  t to the.**     
181f0 20 20 20 20 20 66 69 72 73 74 20 62 79 74 65 20       first byte 
18200 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20  past the end of 
18210 74 68 65 20 66 69 72 73 74 20 53 51 4c 20 73 74  the first SQL st
18220 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e  atement in zSql.
18230 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 3c 74 6f  .**          <to
18240 64 6f 3e 57 68 61 74 20 64 6f 65 73 20 2a 70 7a  do>What does *pz
18250 54 61 69 6c 20 70 6f 69 6e 74 20 74 6f 20 69 66  Tail point to if
18260 20 74 68 65 72 65 20 69 73 20 6f 6e 65 20 73 74   there is one st
18270 61 74 65 6d 65 6e 74 3f 3c 2f 74 6f 64 6f 3e 0a  atement?</todo>.
18280 2a 2a 0a 2a 2a 20 7b 46 31 33 30 31 36 7d 20 41  **.** {F13016} A
18290 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c   successful call
182a0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   to [sqlite3_pre
182b0 70 61 72 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c  pare_v2(db,zSql,
182c0 4e 2c 70 70 53 74 6d 74 2c 2e 2e 2e 29 5d 0a 2a  N,ppStmt,...)].*
182d0 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 6f 6e  *          or on
182e0 65 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74  e of its variant
182f0 73 20 77 72 69 74 65 73 20 69 6e 74 6f 20 2a 70  s writes into *p
18300 70 53 74 6d 74 20 61 20 70 6f 69 6e 74 65 72 20  pStmt a pointer 
18310 74 6f 20 61 20 6e 65 77 0a 2a 2a 20 20 20 20 20  to a new.**     
18320 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73       [prepared s
18330 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20 61 20 70  tatement] or a p
18340 6f 69 6e 74 65 72 20 74 6f 20 4e 55 4c 4c 0a 2a  ointer to NULL.*
18350 2a 20 20 20 20 20 20 20 20 20 20 69 66 20 7a 53  *          if zS
18360 71 6c 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 74 68  ql contains noth
18370 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 77  ing other than w
18380 68 69 74 65 73 70 61 63 65 20 6f 72 20 63 6f 6d  hitespace or com
18390 6d 65 6e 74 73 2e 20 0a 2a 2a 0a 2a 2a 20 7b 46  ments. .**.** {F
183a0 31 33 30 31 39 7d 20 54 68 65 20 5b 73 71 6c 69  13019} The [sqli
183b0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
183c0 5d 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64 20  ] interface and 
183d0 69 74 73 20 76 61 72 69 61 6e 74 73 20 72 65 74  its variants ret
183e0 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  urn.**          
183f0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 61  [SQLITE_OK] or a
18400 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65  n appropriate [e
18410 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 20  rror code] upon 
18420 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 7b  failure..**.** {
18430 46 31 33 30 32 31 7d 20 42 65 66 6f 72 65 20 5b  F13021} Before [
18440 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
18450 64 62 2c 7a 53 71 6c 2c 6e 42 79 74 65 2c 70 70  db,zSql,nByte,pp
18460 53 74 6d 74 2c 70 7a 54 61 69 6c 29 5d 20 6f 72  Stmt,pzTail)] or
18470 20 69 74 73 0a 2a 2a 20 20 20 20 20 20 20 20 20   its.**         
18480 20 76 61 72 69 61 6e 74 73 20 72 65 74 75 72 6e   variants return
18490 73 20 61 6e 20 65 72 72 6f 72 20 28 61 6e 79 20  s an error (any 
184a0 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e  value other than
184b0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 29 0a 2a 2a   [SQLITE_OK]).**
184c0 20 20 20 20 20 20 20 20 20 20 69 74 20 66 69 72            it fir
184d0 73 74 20 73 65 74 73 20 2a 70 70 53 74 6d 74 20  st sets *ppStmt 
184e0 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20  to NULL..*/.int 
184f0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
18500 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
18510 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
18520 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
18530 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
18540 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
18550 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
18560 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  -8 encoded */.  
18570 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
18580 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
18590 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
185a0 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
185b0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
185c0 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
185d0 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
185e0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
185f0 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  r **pzTail     /
18600 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
18610 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
18620 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69   of zSql */.);.i
18630 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
18640 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  re_v2(.  sqlite3
18650 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
18660 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
18670 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
18680 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  har *zSql,      
18690 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
186a0 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64  t, UTF-8 encoded
186b0 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
186c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
186d0 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
186e0 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
186f0 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
18700 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
18710 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
18720 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
18730 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c  st char **pzTail
18740 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
18750 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
18760 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
18770 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
18780 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20 73 71  _prepare16(.  sq
18790 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
187a0 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
187b0 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
187c0 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20  nst void *zSql, 
187d0 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
187e0 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65  tement, UTF-16 e
187f0 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
18800 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
18810 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
18820 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
18830 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
18840 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
18850 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
18860 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
18870 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a  .  const void **
18880 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
18890 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
188a0 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
188b0 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  zSql */.);.int s
188c0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
188d0 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v2(.  sqlite3 *
188e0 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
188f0 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
18900 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
18910 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  d *zSql,       /
18920 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
18930 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20   UTF-16 encoded 
18940 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
18950 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
18960 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
18970 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
18980 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
18990 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
189a0 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
189b0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
189c0 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20  t void **pzTail 
189d0 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
189e0 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
189f0 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
18a00 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 52  .);../*.** CAPIR
18a10 45 46 3a 20 52 65 74 72 69 65 76 69 6e 67 20 53  EF: Retrieving S
18a20 74 61 74 65 6d 65 6e 74 20 53 51 4c 20 7b 46 31  tatement SQL {F1
18a30 33 31 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73  3100}.**.** This
18a40 20 69 6e 74 65 72 65 66 61 63 65 20 63 61 6e 20   intereface can 
18a50 62 65 20 75 73 65 64 20 74 6f 20 72 65 74 72 69  be used to retri
18a60 65 76 65 20 61 20 73 61 76 65 64 20 63 6f 70 79  eve a saved copy
18a70 20 6f 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c   of the original
18a80 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65  .** SQL text use
18a90 64 20 74 6f 20 63 72 65 61 74 65 20 61 20 5b 70  d to create a [p
18aa0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
18ab0 74 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  t]..**.** INVARI
18ac0 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  ANTS:.**.** {F13
18ad0 31 30 31 7d 20 49 66 20 74 68 65 20 5b 70 72 65  101} If the [pre
18ae0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
18af0 20 70 61 73 73 65 64 20 61 73 20 0a 2a 2a 20 20   passed as .**  
18b00 20 20 20 20 20 20 20 20 74 68 65 20 61 6e 20 61          the an a
18b10 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69  rgument to [sqli
18b20 74 65 33 5f 73 71 6c 28 29 5d 20 77 61 73 20 63  te3_sql()] was c
18b30 6f 6d 70 69 6c 65 64 0a 2a 2a 20 20 20 20 20 20  ompiled.**      
18b40 20 20 20 20 63 6f 6d 70 69 6c 65 64 20 75 73 69      compiled usi
18b50 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74  ng either [sqlit
18b60 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
18b70 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   or.**          
18b80 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
18b90 31 36 5f 76 32 28 29 5d 2c 0a 2a 2a 20 20 20 20  16_v2()],.**    
18ba0 20 20 20 20 20 20 74 68 65 6e 20 5b 73 71 6c 69        then [sqli
18bb0 74 65 33 5f 73 71 6c 28 29 5d 20 66 75 6e 63 74  te3_sql()] funct
18bc0 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ion returns a po
18bd0 69 6e 74 65 72 20 74 6f 20 61 0a 2a 2a 20 20 20  inter to a.**   
18be0 20 20 20 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d         zero-term
18bf0 69 6e 61 74 65 64 20 73 74 72 69 6e 67 20 63 6f  inated string co
18c00 6e 74 61 69 6e 69 6e 67 20 61 20 55 54 46 2d 38  ntaining a UTF-8
18c10 20 72 65 6e 64 65 72 69 6e 67 0a 2a 2a 20 20 20   rendering.**   
18c20 20 20 20 20 20 20 20 6f 66 20 74 68 65 20 6f 72         of the or
18c30 69 67 69 6e 61 6c 20 53 51 4c 20 73 74 61 74 65  iginal SQL state
18c40 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  ment..**.** {F13
18c50 31 30 32 7d 20 49 66 20 74 68 65 20 5b 70 72 65  102} If the [pre
18c60 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
18c70 20 70 61 73 73 65 64 20 61 73 20 0a 2a 2a 20 20   passed as .**  
18c80 20 20 20 20 20 20 20 20 74 68 65 20 61 6e 20 61          the an a
18c90 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69  rgument to [sqli
18ca0 74 65 33 5f 73 71 6c 28 29 5d 20 77 61 73 20 63  te3_sql()] was c
18cb0 6f 6d 70 69 6c 65 64 0a 2a 2a 20 20 20 20 20 20  ompiled.**      
18cc0 20 20 20 20 63 6f 6d 70 69 6c 65 64 20 75 73 69      compiled usi
18cd0 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74  ng either [sqlit
18ce0 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72  e3_prepare()] or
18cf0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
18d00 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
18d10 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  )],.**          
18d20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 73 71  then [sqlite3_sq
18d30 6c 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 72 65  l()] function re
18d40 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69  turns a NULL poi
18d50 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  nter..**.** {F13
18d60 31 30 33 7d 20 54 68 65 20 73 74 72 69 6e 67 20  103} The string 
18d70 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
18d80 69 74 65 33 5f 73 71 6c 28 53 29 5d 20 69 73 20  ite3_sql(S)] is 
18d90 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 0a  valid until the.
18da0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65  **          [pre
18db0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
18dc0 20 53 20 69 73 20 64 65 6c 65 74 65 64 20 75 73   S is deleted us
18dd0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  ing [sqlite3_fin
18de0 61 6c 69 7a 65 28 53 29 5d 2e 0a 2a 2f 0a 63 6f  alize(S)]..*/.co
18df0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
18e00 33 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74  3_sql(sqlite3_st
18e10 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
18e20 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 44 79  ** CAPI3REF:  Dy
18e30 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70 65 64 20  namically Typed 
18e40 56 61 6c 75 65 20 4f 62 6a 65 63 74 20 20 7b 46  Value Object  {F
18e50 31 35 30 30 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52  15000}.** KEYWOR
18e60 44 53 3a 20 7b 70 72 6f 74 65 63 74 65 64 20 73  DS: {protected s
18e70 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75  qlite3_value} {u
18e80 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
18e90 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20  e3_value}.**.** 
18ea0 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20  SQLite uses the 
18eb0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
18ec0 6a 65 63 74 20 74 6f 20 72 65 70 72 65 73 65 6e  ject to represen
18ed0 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20  t all values.** 
18ee0 74 68 61 74 20 63 61 6e 20 62 65 20 73 74 6f 72  that can be stor
18ef0 65 64 20 69 6e 20 61 20 64 61 74 61 62 61 73 65  ed in a database
18f00 20 74 61 62 6c 65 2e 0a 2a 2a 20 53 51 4c 69 74   table..** SQLit
18f10 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 74  e uses dynamic t
18f20 79 70 69 6e 67 20 66 6f 72 20 74 68 65 20 76 61  yping for the va
18f30 6c 75 65 73 20 69 74 20 73 74 6f 72 65 73 2e 20  lues it stores. 
18f40 20 0a 2a 2a 20 56 61 6c 75 65 73 20 73 74 6f 72   .** Values stor
18f50 65 64 20 69 6e 20 73 71 6c 69 74 65 33 5f 76 61  ed in sqlite3_va
18f60 6c 75 65 20 6f 62 6a 65 63 74 73 20 63 61 6e 20  lue objects can 
18f70 62 65 0a 2a 2a 20 62 65 20 69 6e 74 65 67 65 72  be.** be integer
18f80 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  s, floating poin
18f90 74 20 76 61 6c 75 65 73 2c 20 73 74 72 69 6e 67  t values, string
18fa0 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c  s, BLOBs, or NUL
18fb0 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69  L..**.** An sqli
18fc0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
18fd0 20 6d 61 79 20 62 65 20 65 69 74 68 65 72 20 22   may be either "
18fe0 70 72 6f 74 65 63 74 65 64 22 20 6f 72 20 22 75  protected" or "u
18ff0 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20  nprotected"..** 
19000 53 6f 6d 65 20 69 6e 74 65 72 66 61 63 65 73 20  Some interfaces 
19010 72 65 71 75 69 72 65 20 61 20 70 72 6f 74 65 63  require a protec
19020 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
19030 65 2e 20 20 4f 74 68 65 72 20 69 6e 74 65 72 66  e.  Other interf
19040 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63  aces.** will acc
19050 65 70 74 20 65 69 74 68 65 72 20 61 20 70 72 6f  ept either a pro
19060 74 65 63 74 65 64 20 6f 72 20 61 6e 20 75 6e 70  tected or an unp
19070 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
19080 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79  _value..** Every
19090 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20   interface that 
190a0 61 63 63 65 70 74 73 20 73 71 6c 69 74 65 33 5f  accepts sqlite3_
190b0 76 61 6c 75 65 20 61 72 67 75 6d 65 6e 74 73 20  value arguments 
190c0 73 70 65 63 69 66 69 65 73 20 0a 2a 2a 20 77 68  specifies .** wh
190d0 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 20  ether or not it 
190e0 72 65 71 75 69 72 65 73 20 61 20 70 72 6f 74 65  requires a prote
190f0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
19100 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65  ue..**.** The te
19110 72 6d 73 20 22 70 72 6f 74 65 63 74 65 64 22 20  rms "protected" 
19120 61 6e 64 20 22 75 6e 70 72 6f 74 65 63 74 65 64  and "unprotected
19130 22 20 72 65 66 65 72 20 74 6f 20 77 68 65 74 68  " refer to wheth
19140 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d  er or not.** a m
19150 75 74 65 78 20 69 73 20 68 65 6c 64 2e 20 20 41  utex is held.  A
19160 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20   internal mutex 
19170 69 73 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72  is held for a pr
19180 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74  otected.** sqlit
19190 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
191a0 62 75 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20  but no mutex is 
191b0 68 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72  held for an unpr
191c0 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74  otected.** sqlit
191d0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e  e3_value object.
191e0 20 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 63    If SQLite is c
191f0 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69  ompiled to be si
19200 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a  ngle-threaded.**
19210 20 28 77 69 74 68 20 53 51 4c 49 54 45 5f 54 48   (with SQLITE_TH
19220 52 45 41 44 53 41 46 45 3d 30 20 61 6e 64 20 77  READSAFE=0 and w
19230 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 72  ith [sqlite3_thr
19240 65 61 64 73 61 66 65 28 29 5d 20 72 65 74 75 72  eadsafe()] retur
19250 6e 69 6e 67 20 30 29 0a 2a 2a 20 74 68 65 6e 20  ning 0).** then 
19260 74 68 65 72 65 20 69 73 20 6e 6f 20 64 69 73 74  there is no dist
19270 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a  inction between.
19280 2a 2a 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64  ** protected and
19290 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c   unprotected sql
192a0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
192b0 74 73 20 61 6e 64 20 74 68 65 79 20 63 61 6e 20  ts and they can 
192c0 62 65 0a 2a 2a 20 75 73 65 64 20 69 6e 74 65 72  be.** used inter
192d0 63 68 61 6e 67 61 62 6c 65 2e 20 20 48 6f 77 65  changable.  Howe
192e0 76 65 72 2c 20 66 6f 72 20 6d 61 78 69 6d 75 6d  ver, for maximum
192f0 20 63 6f 64 65 20 70 6f 72 74 61 62 69 6c 69 74   code portabilit
19300 79 20 69 74 0a 2a 2a 20 69 73 20 72 65 63 6f 6d  y it.** is recom
19310 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c  mended that appl
19320 69 63 61 74 69 6f 6e 73 20 6d 61 6b 65 20 74 68  ications make th
19330 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65  e distinction be
19340 74 77 65 65 6e 0a 2a 2a 20 62 65 74 77 65 65 6e  tween.** between
19350 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75   protected and u
19360 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
19370 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
19380 20 65 76 65 6e 20 69 66 0a 2a 2a 20 74 68 65 79   even if.** they
19390 20 61 72 65 20 73 69 6e 67 6c 65 20 74 68 72 65   are single thre
193a0 61 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  aded..**.** The 
193b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
193c0 6a 65 63 74 73 20 74 68 61 74 20 61 72 65 20 70  jects that are p
193d0 61 73 73 65 64 20 61 73 20 70 61 72 61 6d 65 74  assed as paramet
193e0 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20  ers into the.** 
193f0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
19400 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  f application-de
19410 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
19420 6f 6e 73 20 61 72 65 20 70 72 6f 74 65 63 74 65  ons are protecte
19430 64 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  d..** The sqlite
19440 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72  3_value object r
19450 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73  eturned by.** [s
19460 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
19470 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74  lue()] is unprot
19480 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74  ected..** Unprot
19490 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
194a0 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20  lue objects may 
194b0 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74  only be used wit
194c0 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  h.** [sqlite3_re
194d0 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e  sult_value()] an
194e0 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  d [sqlite3_bind_
194f0 76 61 6c 75 65 28 29 5d 2e 20 20 41 6c 6c 20 6f  value()].  All o
19500 74 68 65 72 0a 2a 2a 20 69 6e 74 65 72 66 61 63  ther.** interfac
19510 65 73 20 74 68 61 74 20 75 73 65 20 73 71 6c 69  es that use sqli
19520 74 65 33 5f 76 61 6c 75 65 20 72 65 71 75 69 72  te3_value requir
19530 65 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  e protected sqli
19540 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
19550 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  s..*/.typedef st
19560 72 75 63 74 20 4d 65 6d 20 73 71 6c 69 74 65 33  ruct Mem sqlite3
19570 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43  _value;../*.** C
19580 41 50 49 33 52 45 46 3a 20 20 53 51 4c 20 46 75  API3REF:  SQL Fu
19590 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f  nction Context O
195a0 62 6a 65 63 74 20 7b 46 31 36 30 30 31 7d 0a 2a  bject {F16001}.*
195b0 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78 74  *.** The context
195c0 20 69 6e 20 77 68 69 63 68 20 61 6e 20 53 51 4c   in which an SQL
195d0 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 63 75 74   function execut
195e0 65 73 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20  es is stored in 
195f0 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  an.** sqlite3_co
19600 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e 20 20 41  ntext object.  A
19610 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 73   pointer to an s
19620 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a  qlite3_context.*
19630 2a 20 6f 62 6a 65 63 74 20 69 73 20 61 6c 77 61  * object is alwa
19640 79 73 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  ys first paramet
19650 65 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f  er to applicatio
19660 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
19670 6e 63 74 69 6f 6e 73 2e 0a 2a 2f 0a 74 79 70 65  nctions..*/.type
19680 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
19690 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74  e3_context sqlit
196a0 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a  e3_context;../*.
196b0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 42 69  ** CAPI3REF:  Bi
196c0 6e 64 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20  nding Values To 
196d0 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
196e0 6e 74 73 20 7b 46 31 33 35 30 30 7d 0a 2a 2a 0a  nts {F13500}.**.
196f0 2a 2a 20 49 6e 20 74 68 65 20 53 51 4c 20 73 74  ** In the SQL st
19700 72 69 6e 67 73 20 69 6e 70 75 74 20 74 6f 20 5b  rings input to [
19710 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
19720 76 32 28 29 5d 20 61 6e 64 20 69 74 73 0a 2a 2a  v2()] and its.**
19730 20 76 61 72 69 61 6e 74 73 2c 20 6c 69 74 65 72   variants, liter
19740 61 6c 73 20 6d 61 79 20 62 65 20 72 65 70 6c 61  als may be repla
19750 63 65 20 62 79 20 61 20 70 61 72 61 6d 65 74 65  ce by a paramete
19760 72 20 69 6e 20 6f 6e 65 0a 2a 2a 20 6f 66 20 74  r in one.** of t
19770 68 65 73 65 20 66 6f 72 6d 73 3a 0a 2a 2a 0a 2a  hese forms:.**.*
19780 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20  * <ul>.** <li>  
19790 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a  ?.** <li>  ?NNN.
197a0 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a  ** <li>  :VVV.**
197b0 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c   <li>  @VVV.** <
197c0 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75  li>  $VVV.** </u
197d0 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20  l>.**.** In the 
197e0 70 61 72 61 6d 65 74 65 72 20 66 6f 72 6d 73 20  parameter forms 
197f0 73 68 6f 77 6e 20 61 62 6f 76 65 20 4e 4e 4e 20  shown above NNN 
19800 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69  is an integer li
19810 74 65 72 61 6c 2c 0a 2a 2a 20 56 56 56 20 61 6c  teral,.** VVV al
19820 70 68 61 2d 6e 75 6d 65 72 69 63 20 70 61 72 61  pha-numeric para
19830 6d 65 74 65 72 20 6e 61 6d 65 2e 0a 2a 2a 20 54  meter name..** T
19840 68 65 20 76 61 6c 75 65 73 20 6f 66 20 74 68 65  he values of the
19850 73 65 20 70 61 72 61 6d 65 74 65 72 73 20 28 61  se parameters (a
19860 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74  lso called "host
19870 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73   parameter names
19880 22 0a 2a 2a 20 6f 72 20 22 53 51 4c 20 70 61 72  ".** or "SQL par
19890 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e  ameters").** can
198a0 20 62 65 20 73 65 74 20 75 73 69 6e 67 20 74 68   be set using th
198b0 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
198c0 28 29 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69  () routines defi
198d0 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20  ned here..**.** 
198e0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
198f0 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  nt to the sqlite
19900 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
19910 6e 65 73 20 61 6c 77 61 79 73 0a 2a 2a 20 69 73  nes always.** is
19920 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
19930 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d  e [sqlite3_stmt]
19940 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
19950 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65   from.** [sqlite
19960 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
19970 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e  or its variants.
19980 20 54 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61   The second.** a
19990 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69  rgument is the i
199a0 6e 64 65 78 20 6f 66 20 74 68 65 20 70 61 72 61  ndex of the para
199b0 6d 65 74 65 72 20 74 6f 20 62 65 20 73 65 74 2e  meter to be set.
199c0 20 54 68 65 0a 2a 2a 20 66 69 72 73 74 20 70 61   The.** first pa
199d0 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69  rameter has an i
199e0 6e 64 65 78 20 6f 66 20 31 2e 20 20 57 68 65 6e  ndex of 1.  When
199f0 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a   the same named.
19a00 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  ** parameter is 
19a10 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f  used more than o
19a20 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20  nce, second and 
19a30 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63  subsequent.** oc
19a40 63 75 72 72 65 6e 63 65 73 20 68 61 76 65 20 74  currences have t
19a50 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20 61 73  he same index as
19a60 20 74 68 65 20 66 69 72 73 74 20 6f 63 63 75 72   the first occur
19a70 72 65 6e 63 65 2e 20 0a 2a 2a 20 54 68 65 20 69  rence. .** The i
19a80 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 20 70  ndex for named p
19a90 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20 62 65  arameters can be
19aa0 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e 67   looked up using
19ab0 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
19ac0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
19ad0 6e 61 6d 65 28 29 5d 20 41 50 49 20 69 66 20 64  name()] API if d
19ae0 65 73 69 72 65 64 2e 20 20 54 68 65 20 69 6e 64  esired.  The ind
19af0 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22  ex.** for "?NNN"
19b00 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 74   parameters is t
19b10 68 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e  he value of NNN.
19b20 0a 2a 2a 20 54 68 65 20 4e 4e 4e 20 76 61 6c 75  .** The NNN valu
19b30 65 20 6d 75 73 74 20 62 65 20 62 65 74 77 65 65  e must be betwee
19b40 6e 20 31 20 61 6e 64 20 74 68 65 20 63 6f 6d 70  n 1 and the comp
19b50 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 70 61 72 61  ile-time.** para
19b60 6d 65 74 65 72 20 53 51 4c 49 54 45 5f 4d 41 58  meter SQLITE_MAX
19b70 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52  _VARIABLE_NUMBER
19b80 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a   (default value:
19b90 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   999)..**.** The
19ba0 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
19bb0 69 73 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20  is the value to 
19bc0 62 69 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61  bind to the para
19bd0 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20  meter..**.** In 
19be0 74 68 6f 73 65 0a 2a 2a 20 72 6f 75 74 69 6e 65  those.** routine
19bf0 73 20 74 68 61 74 20 68 61 76 65 20 61 20 66 6f  s that have a fo
19c00 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69  urth argument, i
19c10 74 73 20 76 61 6c 75 65 20 69 73 20 74 68 65 20  ts value is the 
19c20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a  number of bytes.
19c30 2a 2a 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65  ** in the parame
19c40 74 65 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61  ter.  To be clea
19c50 72 3a 20 74 68 65 20 76 61 6c 75 65 20 69 73 20  r: the value is 
19c60 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75  the number of <u
19c70 3e 62 79 74 65 73 3c 2f 75 3e 0a 2a 2a 20 69 6e  >bytes</u>.** in
19c80 20 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20   the value, not 
19c90 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  the number of ch
19ca0 61 72 61 63 74 65 72 73 2e 20 20 20 54 68 65 20  aracters.   The 
19cb0 6e 75 6d 62 65 72 0a 2a 2a 20 6f 66 20 62 79 74  number.** of byt
19cc0 65 73 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c  es does not incl
19cd0 75 64 65 20 74 68 65 20 7a 65 72 6f 2d 74 65 72  ude the zero-ter
19ce0 6d 69 6e 61 74 6f 72 20 61 74 20 74 68 65 20 65  minator at the e
19cf0 6e 64 20 6f 66 20 73 74 72 69 6e 67 73 2e 0a 2a  nd of strings..*
19d00 2a 20 49 66 20 74 68 65 20 66 6f 75 72 74 68 20  * If the fourth 
19d10 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 65 67  parameter is neg
19d20 61 74 69 76 65 2c 20 74 68 65 20 6c 65 6e 67 74  ative, the lengt
19d30 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 20  h of the string 
19d40 69 73 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  is.** number of 
19d50 62 79 74 65 73 20 75 70 20 74 6f 20 74 68 65 20  bytes up to the 
19d60 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69  first zero termi
19d70 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  nator..**.** The
19d80 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20   fifth argument 
19d90 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
19da0 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f  blob(), sqlite3_
19db0 62 69 6e 64 5f 74 65 78 74 28 29 2c 20 61 6e 64  bind_text(), and
19dc0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  .** sqlite3_bind
19dd0 5f 74 65 78 74 31 36 28 29 20 69 73 20 61 20 64  _text16() is a d
19de0 65 73 74 72 75 63 74 6f 72 20 75 73 65 64 20 74  estructor used t
19df0 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65  o dispose of the
19e00 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69   BLOB or.** stri
19e10 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74 65 20  ng after SQLite 
19e20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74  has finished wit
19e30 68 20 69 74 2e 20 49 66 20 74 68 65 20 66 69 66  h it. If the fif
19e40 74 68 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a  th argument is.*
19e50 2a 20 74 68 65 20 73 70 65 63 69 61 6c 20 76 61  * the special va
19e60 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41 54  lue [SQLITE_STAT
19e70 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  IC], then SQLite
19e80 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68   assumes that th
19e90 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  e.** information
19ea0 20 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20 75   is in static, u
19eb0 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20 61  nmanaged space a
19ec0 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  nd does not need
19ed0 20 74 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a   to be freed..**
19ee0 20 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72   If the fifth ar
19ef0 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65 20 76  gument has the v
19f00 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54 52 41  alue [SQLITE_TRA
19f10 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a  NSIENT], then.**
19f20 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 69 74   SQLite makes it
19f30 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f  s own private co
19f40 70 79 20 6f 66 20 74 68 65 20 64 61 74 61 20 69  py of the data i
19f50 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f  mmediately, befo
19f60 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65  re.** the sqlite
19f70 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
19f80 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a  ne returns..**.*
19f90 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69  * The sqlite3_bi
19fa0 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f  nd_zeroblob() ro
19fb0 75 74 69 6e 65 20 62 69 6e 64 73 20 61 20 42 4c  utine binds a BL
19fc0 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74  OB of length N t
19fd0 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64  hat.** is filled
19fe0 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20 41 20   with zeros.  A 
19ff0 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73 20 61 20  zeroblob uses a 
1a000 66 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20  fixed amount of 
1a010 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20  memory.** (just 
1a020 61 6e 20 69 6e 74 65 67 65 72 20 74 6f 20 68 6f  an integer to ho
1a030 6c 64 20 69 74 20 73 69 7a 65 29 20 77 68 69 6c  ld it size) whil
1a040 65 20 69 74 20 69 73 20 62 65 69 6e 67 20 70 72  e it is being pr
1a050 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f  ocessed..** Zero
1a060 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 65 6e 64  blobs are intend
1a070 65 64 20 74 6f 20 73 65 72 76 65 20 61 73 20 70  ed to serve as p
1a080 6c 61 63 65 2d 68 6f 6c 64 65 72 73 20 66 6f 72  lace-holders for
1a090 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20   BLOBs whose.** 
1a0a0 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74 65 72  content is later
1a0b0 20 77 72 69 74 74 65 6e 20 75 73 69 6e 67 20 0a   written using .
1a0c0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  ** [sqlite3_blob
1a0d0 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e  _open | incremen
1a0e0 74 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74  t BLOB I/O] rout
1a0f0 69 6e 65 73 2e 20 41 20 6e 65 67 61 74 69 76 65  ines. A negative
1a100 0a 2a 2a 20 76 61 6c 75 65 20 66 6f 72 20 74 68  .** value for th
1a110 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c  e zeroblob resul
1a120 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e  ts in a zero-len
1a130 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20  gth BLOB..**.** 
1a140 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  The sqlite3_bind
1a150 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 6d 75  _*() routines mu
1a160 73 74 20 62 65 20 63 61 6c 6c 65 64 20 61 66 74  st be called aft
1a170 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  er.** [sqlite3_p
1a180 72 65 70 61 72 65 5f 76 32 28 29 5d 20 28 61 6e  repare_v2()] (an
1a190 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 20  d its variants) 
1a1a0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  or [sqlite3_rese
1a1b0 74 28 29 5d 20 61 6e 64 0a 2a 2a 20 62 65 66 6f  t()] and.** befo
1a1c0 72 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  re [sqlite3_step
1a1d0 28 29 5d 2e 0a 2a 2a 20 42 69 6e 64 69 6e 67 73  ()]..** Bindings
1a1e0 20 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 64   are not cleared
1a1f0 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33   by the [sqlite3
1a200 5f 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69 6e  _reset()] routin
1a210 65 2e 0a 2a 2a 20 55 6e 62 6f 75 6e 64 20 70 61  e..** Unbound pa
1a220 72 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74  rameters are int
1a230 65 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c  erpreted as NULL
1a240 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
1a250 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53  utines return [S
1a260 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63  QLITE_OK] on suc
1a270 63 65 73 73 20 6f 72 20 61 6e 20 65 72 72 6f 72  cess or an error
1a280 20 63 6f 64 65 20 69 66 0a 2a 2a 20 61 6e 79 74   code if.** anyt
1a290 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e  hing goes wrong.
1a2a0 20 20 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d    [SQLITE_RANGE]
1a2b0 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20   is returned if 
1a2c0 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  the parameter.**
1a2d0 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66   index is out of
1a2e0 20 72 61 6e 67 65 2e 20 20 5b 53 51 4c 49 54 45   range.  [SQLITE
1a2f0 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75 72  _NOMEM] is retur
1a300 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 20 66 61  ned if malloc fa
1a310 69 6c 73 2e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ils..** [SQLITE_
1a320 4d 49 53 55 53 45 5d 20 6d 69 67 68 74 20 62 65  MISUSE] might be
1a330 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 65   returned if the
1a340 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
1a350 63 61 6c 6c 65 64 20 6f 6e 20 61 0a 2a 2a 20 76  called on a.** v
1a360 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 74  irtual machine t
1a370 68 61 74 20 69 73 20 74 68 65 20 77 72 6f 6e 67  hat is the wrong
1a380 20 73 74 61 74 65 20 6f 72 20 77 68 69 63 68 20   state or which 
1a390 68 61 73 20 61 6c 72 65 61 64 79 20 62 65 65 6e  has already been
1a3a0 20 66 69 6e 61 6c 69 7a 65 64 2e 0a 2a 2a 20 44   finalized..** D
1a3b0 65 74 65 63 74 69 6f 6e 20 6f 66 20 6d 69 73 75  etection of misu
1a3c0 73 65 20 69 73 20 75 6e 72 65 6c 69 61 62 6c 65  se is unreliable
1a3d0 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  .  Applications 
1a3e0 73 68 6f 75 6c 64 20 6e 6f 74 20 64 65 70 65 6e  should not depen
1a3f0 64 0a 2a 2a 20 6f 6e 20 53 51 4c 49 54 45 5f 4d  d.** on SQLITE_M
1a400 49 53 55 53 45 20 72 65 74 75 72 6e 73 2e 20 20  ISUSE returns.  
1a410 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 69 73  SQLITE_MISUSE is
1a420 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 69 6e 64   intended to ind
1a430 69 63 61 74 65 20 61 0a 2a 2a 20 61 20 6c 6f 67  icate a.** a log
1a440 69 63 20 65 72 72 6f 72 20 69 6e 20 74 68 65 20  ic error in the 
1a450 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 46 75  application.  Fu
1a460 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
1a470 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a   SQLite might.**
1a480 20 70 61 6e 69 63 20 72 61 74 68 65 72 20 74 68   panic rather th
1a490 61 6e 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45  an return SQLITE
1a4a0 5f 4d 49 53 55 53 45 2e 0a 2a 2a 0a 2a 2a 20 53  _MISUSE..**.** S
1a4b0 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
1a4c0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
1a4d0 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73  _count()],.** [s
1a4e0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
1a4f0 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61  meter_name()], a
1a500 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nd.** [sqlite3_b
1a510 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
1a520 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e  dex()]..**.** IN
1a530 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
1a540 7b 46 31 33 35 30 36 7d 20 54 68 65 20 5b 73 71  {F13506} The [sq
1a550 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20  lite3_prepare | 
1a560 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f  SQL statement co
1a570 6d 70 69 6c 65 72 5d 20 72 65 63 6f 67 6e 69 7a  mpiler] recogniz
1a580 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  es.**          t
1a590 6f 6b 65 6e 73 20 6f 66 20 74 68 65 20 66 6f 72  okens of the for
1a5a0 6d 73 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20  ms "?", "?NNN", 
1a5b0 22 24 56 56 56 22 2c 20 22 3a 56 56 56 22 2c 20  "$VVV", ":VVV", 
1a5c0 61 6e 64 20 22 40 56 56 56 22 0a 2a 2a 20 20 20  and "@VVV".**   
1a5d0 20 20 20 20 20 20 20 61 73 20 53 51 4c 20 70 61         as SQL pa
1a5e0 72 61 6d 65 74 65 72 73 2c 20 77 68 65 72 65 20  rameters, where 
1a5f0 4e 4e 4e 20 69 73 20 61 6e 79 20 73 65 71 75 65  NNN is any seque
1a600 6e 63 65 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f  nce of one or mo
1a610 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64  re.**          d
1a620 69 67 69 74 73 20 61 6e 64 20 77 68 65 72 65 20  igits and where 
1a630 56 56 56 20 69 73 20 61 6e 79 20 73 65 71 75 65  VVV is any seque
1a640 6e 63 65 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f  nce of one or mo
1a650 72 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  re .**          
1a660 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 63 68 61  alphanumeric cha
1a670 72 61 63 74 65 72 73 20 6f 72 20 22 3a 3a 22 20  racters or "::" 
1a680 6f 70 74 69 6f 6e 61 6c 6c 79 20 66 6f 6c 6c 6f  optionally follo
1a690 77 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20  wed by.**       
1a6a0 20 20 20 61 20 73 74 72 69 6e 67 20 63 6f 6e 74     a string cont
1a6b0 61 69 6e 69 6e 67 20 6e 6f 20 73 70 61 63 65 73  aining no spaces
1a6c0 20 61 6e 64 20 63 6f 6e 74 61 69 6e 65 64 20 77   and contained w
1a6d0 69 74 68 69 6e 20 70 61 72 65 6e 74 68 65 73 65  ithin parenthese
1a6e0 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 30 39  s..**.** {F13509
1a6f0 7d 20 54 68 65 20 69 6e 69 74 69 61 6c 20 76 61  } The initial va
1a700 6c 75 65 20 6f 66 20 61 6e 20 53 51 4c 20 70 61  lue of an SQL pa
1a710 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 2e  rameter is NULL.
1a720 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 31 32 7d 20  .**.** {F13512} 
1a730 54 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20  The index of an 
1a740 22 3f 22 20 53 51 4c 20 70 61 72 61 6d 65 74 65  "?" SQL paramete
1a750 72 20 69 73 20 6f 6e 65 20 6c 61 72 67 65 72 20  r is one larger 
1a760 74 68 61 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20  than the.**     
1a770 20 20 20 20 20 6c 61 72 67 65 73 74 20 69 6e 64       largest ind
1a780 65 78 20 6f 66 20 53 51 4c 20 70 61 72 61 6d 65  ex of SQL parame
1a790 74 65 72 20 74 6f 20 74 68 65 20 6c 65 66 74 2c  ter to the left,
1a7a0 20 6f 72 20 31 20 69 66 0a 2a 2a 20 20 20 20 20   or 1 if.**     
1a7b0 20 20 20 20 20 74 68 65 20 22 3f 22 20 69 73 20       the "?" is 
1a7c0 74 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c  the leftmost SQL
1a7d0 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
1a7e0 2a 20 7b 46 31 33 35 31 35 7d 20 54 68 65 20 69  * {F13515} The i
1a7f0 6e 64 65 78 20 6f 66 20 61 6e 20 22 3f 4e 4e 4e  ndex of an "?NNN
1a800 22 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  " SQL parameter 
1a810 69 73 20 74 68 65 20 69 6e 74 65 67 65 72 20 4e  is the integer N
1a820 4e 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 31  NN..**.** {F1351
1a830 38 7d 20 54 68 65 20 69 6e 64 65 78 20 6f 66 20  8} The index of 
1a840 61 6e 20 22 3a 56 56 56 22 2c 20 22 24 56 56 56  an ":VVV", "$VVV
1a850 22 2c 20 6f 72 20 22 40 56 56 56 22 20 53 51 4c  ", or "@VVV" SQL
1a860 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a   parameter is.**
1a870 20 20 20 20 20 20 20 20 20 20 74 68 65 20 73 61            the sa
1a880 6d 65 20 61 73 20 74 68 65 20 69 6e 64 65 78 20  me as the index 
1a890 6f 66 20 6c 65 66 74 6d 6f 73 74 20 6f 63 63 75  of leftmost occu
1a8a0 72 61 6e 63 65 73 20 6f 66 20 74 68 65 20 73 61  rances of the sa
1a8b0 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70  me.**          p
1a8c0 61 72 61 6d 65 74 65 72 2c 20 6f 72 20 6f 6e 65  arameter, or one
1a8d0 20 6d 6f 72 65 20 74 68 61 6e 20 74 68 65 20 6c   more than the l
1a8e0 61 72 67 65 73 74 20 69 6e 64 65 78 20 6f 76 65  argest index ove
1a8f0 72 20 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20  r all.**        
1a900 20 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20    parameters to 
1a910 74 68 65 20 6c 65 66 74 20 69 66 20 74 68 69 73  the left if this
1a920 20 69 73 20 74 68 65 20 66 69 72 73 74 20 6f 63   is the first oc
1a930 63 75 72 72 61 6e 63 65 0a 2a 2a 20 20 20 20 20  currance.**     
1a940 20 20 20 20 20 6f 66 20 74 68 69 73 20 70 61 72       of this par
1a950 61 6d 65 74 65 72 2c 20 6f 72 20 31 20 69 66 20  ameter, or 1 if 
1a960 74 68 69 73 20 69 73 20 74 68 65 20 6c 65 66 74  this is the left
1a970 6d 6f 73 74 20 70 61 72 61 6d 65 74 65 72 2e 0a  most parameter..
1a980 2a 2a 0a 2a 2a 20 7b 46 31 33 35 32 31 7d 20 54  **.** {F13521} T
1a990 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  he [sqlite3_prep
1a9a0 61 72 65 20 7c 20 53 51 4c 20 73 74 61 74 65 6d  are | SQL statem
1a9b0 65 6e 74 20 63 6f 6d 70 69 6c 65 72 5d 20 66 61  ent compiler] fa
1a9c0 69 6c 20 77 69 74 68 0a 2a 2a 20 20 20 20 20 20  il with.**      
1a9d0 20 20 20 20 61 6e 20 5b 53 51 4c 49 54 45 5f 52      an [SQLITE_R
1a9e0 41 4e 47 45 5d 20 65 72 72 6f 72 20 69 66 20 74  ANGE] error if t
1a9f0 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53  he index of an S
1aa00 51 4c 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  QL parameter.** 
1aa10 20 20 20 20 20 20 20 20 20 69 73 20 6c 65 73 73           is less
1aa20 20 74 68 61 6e 20 31 20 6f 72 20 67 72 65 61 74   than 1 or great
1aa30 65 72 20 74 68 61 6e 20 53 51 4c 49 54 45 5f 4d  er than SQLITE_M
1aa40 41 58 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42  AX_VARIABLE_NUMB
1aa50 45 52 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 32  ER..**.** {F1352
1aa60 34 7d 20 43 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  4} Calls to [sql
1aa70 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c  ite3_bind_text |
1aa80 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 53 2c   sqlite3_bind(S,
1aa90 4e 2c 56 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20  N,V,...)].**    
1aaa0 20 20 20 20 20 20 61 73 73 6f 63 69 61 74 65 20        associate 
1aab0 74 68 65 20 76 61 6c 75 65 20 56 20 77 69 74 68  the value V with
1aac0 20 61 6c 6c 20 53 51 4c 20 70 61 72 61 6d 65 74   all SQL paramet
1aad0 65 72 73 20 68 61 76 69 6e 67 20 61 6e 0a 2a 2a  ers having an.**
1aae0 20 20 20 20 20 20 20 20 20 20 69 6e 64 65 78 20            index 
1aaf0 6f 66 20 4e 20 69 6e 20 74 68 65 20 5b 70 72 65  of N in the [pre
1ab00 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
1ab10 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 32   S..**.** {F1352
1ab20 37 7d 20 43 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  7} Calls to [sql
1ab30 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c  ite3_bind_text |
1ab40 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 53 2c   sqlite3_bind(S,
1ab50 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20  N,...)].**      
1ab60 20 20 20 20 6f 76 65 72 72 69 64 65 20 70 72 69      override pri
1ab70 6f 72 20 63 61 6c 6c 73 20 77 69 74 68 20 74 68  or calls with th
1ab80 65 20 73 61 6d 65 20 76 61 6c 75 65 73 20 6f 66  e same values of
1ab90 20 53 20 61 6e 64 20 4e 2e 0a 2a 2a 0a 2a 2a 20   S and N..**.** 
1aba0 7b 46 31 33 35 33 30 7d 20 42 69 6e 64 69 6e 67  {F13530} Binding
1abb0 73 20 65 73 74 61 62 6c 69 73 68 65 64 20 62 79  s established by
1abc0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74   [sqlite3_bind_t
1abd0 65 78 74 20 7c 20 73 71 6c 69 74 65 33 5f 62 69  ext | sqlite3_bi
1abe0 6e 64 28 53 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20  nd(S,...)].**   
1abf0 20 20 20 20 20 20 20 70 65 72 73 69 73 74 20 61         persist a
1ac00 63 72 6f 73 73 20 63 61 6c 6c 73 20 74 6f 20 5b  cross calls to [
1ac10 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
1ac20 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 33 33  ]..**.** {F13533
1ac30 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73  } In calls to [s
1ac40 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
1ac50 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a  (S,N,V,L,D)],.**
1ac60 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
1ac70 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 53 2c 4e  e3_bind_text(S,N
1ac80 2c 56 2c 4c 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20  ,V,L,D)], or.** 
1ac90 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
1aca0 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 53 2c  3_bind_text16(S,
1acb0 4e 2c 56 2c 4c 2c 44 29 5d 20 53 51 4c 69 74 65  N,V,L,D)] SQLite
1acc0 20 62 69 6e 64 73 20 74 68 65 20 66 69 72 73 74   binds the first
1acd0 20 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62   L.**          b
1ace0 79 74 65 73 20 6f 66 20 74 68 65 20 62 6c 6f 62  ytes of the blob
1acf0 20 6f 72 20 73 74 72 69 6e 67 20 70 6f 69 6e 74   or string point
1ad00 65 64 20 74 6f 20 62 79 20 56 2c 20 77 68 65 6e  ed to by V, when
1ad10 20 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69   L.**          i
1ad20 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2e 0a  s non-negative..
1ad30 2a 2a 0a 2a 2a 20 7b 46 31 33 35 33 36 7d 20 49  **.** {F13536} I
1ad40 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  n calls to [sqli
1ad50 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 53 2c  te3_bind_text(S,
1ad60 4e 2c 56 2c 4c 2c 44 29 5d 20 6f 72 0a 2a 2a 20  N,V,L,D)] or.** 
1ad70 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
1ad80 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 53 2c  3_bind_text16(S,
1ad90 4e 2c 56 2c 4c 2c 44 29 5d 20 53 51 4c 69 74 65  N,V,L,D)] SQLite
1ada0 20 62 69 6e 64 73 20 63 68 61 72 61 63 74 65 72   binds character
1adb0 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 72  s.**          fr
1adc0 6f 6d 20 56 20 74 68 72 6f 75 67 68 20 74 68 65  om V through the
1add0 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72   first zero char
1ade0 61 63 74 65 72 20 77 68 65 6e 20 4c 20 69 73 20  acter when L is 
1adf0 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20  negative..**.** 
1ae00 7b 46 31 33 35 33 39 7d 20 49 6e 20 63 61 6c 6c  {F13539} In call
1ae10 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69  s to [sqlite3_bi
1ae20 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 2c  nd_blob(S,N,V,L,
1ae30 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  D)],.**         
1ae40 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74   [sqlite3_bind_t
1ae50 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c  ext(S,N,V,L,D)],
1ae60 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   or.**          
1ae70 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65  [sqlite3_bind_te
1ae80 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d  xt16(S,N,V,L,D)]
1ae90 20 77 68 65 6e 20 44 20 69 73 20 74 68 65 20 73   when D is the s
1aea0 70 65 63 69 61 6c 0a 2a 2a 20 20 20 20 20 20 20  pecial.**       
1aeb0 20 20 20 63 6f 6e 73 74 61 6e 74 20 5b 53 51 4c     constant [SQL
1aec0 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 53 51 4c  ITE_STATIC], SQL
1aed0 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 74  ite assumes that
1aee0 20 74 68 65 20 76 61 6c 75 65 20 56 0a 2a 2a 20   the value V.** 
1aef0 20 20 20 20 20 20 20 20 20 69 73 20 68 65 6c 64           is held
1af00 20 69 6e 20 73 74 61 74 69 63 20 75 6e 6d 61 6e   in static unman
1af10 61 67 65 64 20 73 70 61 63 65 20 74 68 61 74 20  aged space that 
1af20 77 69 6c 6c 20 6e 6f 74 20 63 68 61 6e 67 65 0a  will not change.
1af30 2a 2a 20 20 20 20 20 20 20 20 20 20 64 75 72 69  **          duri
1af40 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20  ng the lifetime 
1af50 6f 66 20 74 68 65 20 62 69 6e 64 69 6e 67 2e 0a  of the binding..
1af60 2a 2a 0a 2a 2a 20 7b 46 31 33 35 34 32 7d 20 49  **.** {F13542} I
1af70 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  n calls to [sqli
1af80 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 53 2c  te3_bind_blob(S,
1af90 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20  N,V,L,D)],.**   
1afa0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
1afb0 62 69 6e 64 5f 74 65 78 74 28 53 2c 4e 2c 56 2c  bind_text(S,N,V,
1afc0 4c 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20  L,D)], or.**    
1afd0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62        [sqlite3_b
1afe0 69 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e 2c 56  ind_text16(S,N,V
1aff0 2c 4c 2c 44 29 5d 20 77 68 65 6e 20 44 20 69 73  ,L,D)] when D is
1b000 20 74 68 65 20 73 70 65 63 69 61 6c 0a 2a 2a 20   the special.** 
1b010 20 20 20 20 20 20 20 20 20 63 6f 6e 73 74 61 6e           constan
1b020 74 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  t [SQLITE_TRANSI
1b030 45 4e 54 5d 2c 20 74 68 65 20 72 6f 75 74 69 6e  ENT], the routin
1b040 65 20 6d 61 6b 65 73 20 61 20 0a 2a 2a 20 20 20  e makes a .**   
1b050 20 20 20 20 20 20 20 70 72 69 76 61 74 65 20 63         private c
1b060 6f 70 79 20 6f 66 20 56 20 76 61 6c 75 65 20 62  opy of V value b
1b070 65 66 6f 72 65 20 69 74 20 72 65 74 75 72 6e 73  efore it returns
1b080 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 34 35 7d  ..**.** {F13545}
1b090 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71   In calls to [sq
1b0a0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
1b0b0 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20  S,N,V,L,D)],.** 
1b0c0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
1b0d0 33 5f 62 69 6e 64 5f 74 65 78 74 28 53 2c 4e 2c  3_bind_text(S,N,
1b0e0 56 2c 4c 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20  V,L,D)], or.**  
1b0f0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
1b100 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e  _bind_text16(S,N
1b110 2c 56 2c 4c 2c 44 29 5d 20 77 68 65 6e 20 44 20  ,V,L,D)] when D 
1b120 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a  is a pointer to.
1b130 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 66 75  **          a fu
1b140 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 69  nction, SQLite i
1b150 6e 76 6f 6b 65 73 20 74 68 61 74 20 66 75 6e 63  nvokes that func
1b160 74 69 6f 6e 20 74 6f 20 64 65 73 74 72 6f 79 20  tion to destroy 
1b170 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
1b180 56 20 76 61 6c 75 65 20 61 66 74 65 72 20 69 74  V value after it
1b190 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 75 73   has finished us
1b1a0 69 6e 67 20 74 68 65 20 56 20 76 61 6c 75 65 2e  ing the V value.
1b1b0 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 34 38 7d 20  .**.** {F13548} 
1b1c0 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  In calls to [sql
1b1d0 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c  ite3_bind_zerobl
1b1e0 6f 62 28 53 2c 4e 2c 56 2c 4c 29 5d 20 74 68 65  ob(S,N,V,L)] the
1b1f0 20 76 61 6c 75 65 20 62 6f 75 6e 64 0a 2a 2a 20   value bound.** 
1b200 20 20 20 20 20 20 20 20 20 69 73 20 61 20 62 6c           is a bl
1b210 6f 62 20 6f 66 20 4c 20 62 79 74 65 73 2c 20 6f  ob of L bytes, o
1b220 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20  r a zero-length 
1b230 62 6c 6f 62 20 69 66 20 4c 20 69 73 20 6e 65 67  blob if L is neg
1b240 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  ative..**.** {F1
1b250 33 35 35 31 7d 20 49 6e 20 63 61 6c 6c 73 20 74  3551} In calls t
1b260 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  o [sqlite3_bind_
1b270 76 61 6c 75 65 28 53 2c 4e 2c 56 29 5d 20 74 68  value(S,N,V)] th
1b280 65 20 56 20 61 72 67 75 6d 65 6e 74 20 6d 61 79  e V argument may
1b290 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 65 20  .**          be 
1b2a0 65 69 74 68 65 72 20 61 20 5b 70 72 6f 74 65 63  either a [protec
1b2b0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
1b2c0 65 5d 20 6f 62 6a 65 63 74 20 6f 72 20 61 6e 0a  e] object or an.
1b2d0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 75 6e 70  **          [unp
1b2e0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
1b2f0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 0a  _value] object..
1b300 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
1b310 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  ind_blob(sqlite3
1b320 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
1b330 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c  st void*, int n,
1b340 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
1b350 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
1b360 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65  nd_double(sqlite
1b370 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f  3_stmt*, int, do
1b380 75 62 6c 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74  uble);.int sqlit
1b390 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69  e3_bind_int(sqli
1b3a0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
1b3b0 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  int);.int sqlite
1b3c0 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c  3_bind_int64(sql
1b3d0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
1b3e0 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b   sqlite3_int64);
1b3f0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
1b400 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73  d_null(sqlite3_s
1b410 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20  tmt*, int);.int 
1b420 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
1b430 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  t(sqlite3_stmt*,
1b440 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 72   int, const char
1b450 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a  *, int n, void(*
1b460 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73  )(void*));.int s
1b470 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
1b480 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
1b490 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69  , int, const voi
1b4a0 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  d*, int, void(*)
1b4b0 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71  (void*));.int sq
1b4c0 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65  lite3_bind_value
1b4d0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
1b4e0 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74  int, const sqlit
1b4f0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
1b500 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72  sqlite3_bind_zer
1b510 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74  oblob(sqlite3_st
1b520 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29  mt*, int, int n)
1b530 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1b540 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c  F: Number Of SQL
1b550 20 50 61 72 61 6d 65 74 65 72 73 20 7b 46 31 33   Parameters {F13
1b560 36 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  600}.**.** This 
1b570 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 75  routine can be u
1b580 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20  sed to find the 
1b590 6e 75 6d 62 65 72 20 6f 66 20 53 51 4c 20 70 61  number of SQL pa
1b5a0 72 61 6d 65 74 65 72 73 0a 2a 2a 20 69 6e 20 61  rameters.** in a
1b5b0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
1b5c0 65 6e 74 2e 20 20 53 51 4c 20 70 61 72 61 6d 65  ent.  SQL parame
1b5d0 74 65 72 73 20 61 72 65 20 74 6f 6b 65 6e 73 20  ters are tokens 
1b5e0 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22  of the.** form "
1b5f0 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41  ?", "?NNN", ":AA
1b600 41 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 20 22  A", "$AAA", or "
1b610 40 41 41 41 22 20 74 68 61 74 20 73 65 72 76 65  @AAA" that serve
1b620 20 61 73 0a 2a 2a 20 70 6c 61 63 65 2d 68 6f 6c   as.** place-hol
1b630 64 65 72 73 20 66 6f 72 20 76 61 6c 75 65 73 20  ders for values 
1b640 74 68 61 74 20 61 72 65 20 5b 73 71 6c 69 74 65  that are [sqlite
1b650 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f  3_bind_blob | bo
1b660 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70  und].** to the p
1b670 61 72 61 6d 65 74 65 72 73 20 61 74 20 61 20 6c  arameters at a l
1b680 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a  ater time..**.**
1b690 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 61 63   This routine ac
1b6a0 74 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74  tually returns t
1b6b0 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20  he index of the 
1b6c0 6c 61 72 67 65 73 74 20 70 61 72 61 6d 65 74 65  largest paramete
1b6d0 72 2e 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 66 6f  r..** For all fo
1b6e0 72 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c  rms except ?NNN,
1b6f0 20 74 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65   this will corre
1b700 73 70 6f 6e 64 20 74 6f 20 74 68 65 20 6e 75 6d  spond to the num
1b710 62 65 72 20 6f 66 0a 2a 2a 20 75 6e 69 71 75 65  ber of.** unique
1b720 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66   parameters.  If
1b730 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74   parameters of t
1b740 68 65 20 3f 4e 4e 4e 20 61 72 65 20 75 73 65 64  he ?NNN are used
1b750 2c 20 74 68 65 72 65 20 6d 61 79 0a 2a 2a 20 62  , there may.** b
1b760 65 20 67 61 70 73 20 69 6e 20 74 68 65 20 6c 69  e gaps in the li
1b770 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  st..**.** See al
1b780 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  so: [sqlite3_bin
1b790 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62  d_blob|sqlite3_b
1b7a0 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ind()],.** [sqli
1b7b0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
1b7c0 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a  er_name()], and.
1b7d0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
1b7e0 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
1b7f0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ()]..**.** INVAR
1b800 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31  IANTS:.**.** {F1
1b810 33 36 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  3601} The [sqlit
1b820 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
1b830 72 5f 63 6f 75 6e 74 28 53 29 5d 20 69 6e 74 65  r_count(S)] inte
1b840 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a  rface returns.**
1b850 20 20 20 20 20 20 20 20 20 20 74 68 65 20 6c 61            the la
1b860 72 67 65 73 74 20 69 6e 64 65 78 20 6f 66 20 61  rgest index of a
1b870 6c 6c 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  ll SQL parameter
1b880 73 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20  s in the.**     
1b890 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73       [prepared s
1b8a0 74 61 74 65 6d 65 6e 74 5d 20 53 2c 20 6f 72 20  tatement] S, or 
1b8b0 30 20 69 66 20 53 0a 2a 2a 20 20 20 20 20 20 20  0 if S.**       
1b8c0 20 20 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53     contains no S
1b8d0 51 4c 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a  QL parameters..*
1b8e0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  /.int sqlite3_bi
1b8f0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
1b900 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  nt(sqlite3_stmt*
1b910 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1b920 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f  EF: Name Of A Ho
1b930 73 74 20 50 61 72 61 6d 65 74 65 72 20 7b 46 31  st Parameter {F1
1b940 33 36 32 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73  3620}.**.** This
1b950 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
1b960 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
1b970 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6e 2d  e name of the n-
1b980 74 68 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65  th.** SQL parame
1b990 74 65 72 20 69 6e 20 61 20 5b 70 72 65 70 61 72  ter in a [prepar
1b9a0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
1b9b0 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73  * SQL parameters
1b9c0 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3a 41   of the form ":A
1b9d0 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72  AA" or "@AAA" or
1b9e0 20 22 24 41 41 41 22 20 68 61 76 65 20 61 20 6e   "$AAA" have a n
1b9f0 61 6d 65 0a 2a 2a 20 77 68 69 63 68 20 69 73 20  ame.** which is 
1ba00 74 68 65 20 73 74 72 69 6e 67 20 22 3a 41 41 41  the string ":AAA
1ba10 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22  " or "@AAA" or "
1ba20 24 56 56 56 22 2e 20 0a 2a 2a 20 49 6e 20 6f 74  $VVV". .** In ot
1ba30 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69  her words, the i
1ba40 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24  nitial ":" or "$
1ba50 22 20 6f 72 20 22 40 22 0a 2a 2a 20 69 73 20 69  " or "@".** is i
1ba60 6e 63 6c 75 64 65 64 20 61 73 20 70 61 72 74 20  ncluded as part 
1ba70 6f 66 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 20  of the name..** 
1ba80 50 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68  Parameters of th
1ba90 65 20 66 6f 72 6d 20 22 3f 22 20 6f 72 20 22 3f  e form "?" or "?
1baa0 4e 4e 4e 22 20 68 61 76 65 20 6e 6f 20 6e 61 6d  NNN" have no nam
1bab0 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  e..**.** The fir
1bac0 73 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65  st host paramete
1bad0 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f  r has an index o
1bae0 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a  f 1, not 0..**.*
1baf0 2a 20 49 66 20 74 68 65 20 76 61 6c 75 65 20 6e  * If the value n
1bb00 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
1bb10 20 6f 72 20 69 66 20 74 68 65 20 6e 2d 74 68 20   or if the n-th 
1bb20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20  parameter is.** 
1bb30 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e  nameless, then N
1bb40 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ULL is returned.
1bb50 20 20 54 68 65 20 72 65 74 75 72 6e 65 64 20 73    The returned s
1bb60 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61  tring is.** alwa
1bb70 79 73 20 69 6e 20 74 68 65 20 55 54 46 2d 38 20  ys in the UTF-8 
1bb80 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20 69 66  encoding even if
1bb90 20 74 68 65 20 6e 61 6d 65 64 20 70 61 72 61 6d   the named param
1bba0 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67  eter was.** orig
1bbb0 69 6e 61 6c 6c 79 20 73 70 65 63 69 66 69 65 64  inally specified
1bbc0 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 5b 73   as UTF-16 in [s
1bbd0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
1bbe0 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
1bbf0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
1bc00 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  )]..**.** See al
1bc10 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  so: [sqlite3_bin
1bc20 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62  d_blob|sqlite3_b
1bc30 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ind()],.** [sqli
1bc40 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
1bc50 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64  er_count()], and
1bc60 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
1bc70 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
1bc80 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  x()]..**.** INVA
1bc90 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  RIANTS:.**.** {F
1bca0 31 33 36 32 31 7d 20 54 68 65 20 5b 73 71 6c 69  13621} The [sqli
1bcb0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
1bcc0 65 72 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 69 6e  er_name(S,N)] in
1bcd0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a  terface returns.
1bce0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 55 54  **          a UT
1bcf0 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66  F-8 rendering of
1bd00 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
1bd10 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69   SQL parameter i
1bd20 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  n.**          [p
1bd30 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1bd40 74 5d 20 53 20 68 61 76 69 6e 67 20 69 6e 64 65  t] S having inde
1bd50 78 20 4e 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20  x N, or.**      
1bd60 20 20 20 20 4e 55 4c 4c 20 69 66 20 74 68 65 72      NULL if ther
1bd70 65 20 69 73 20 6e 6f 20 53 51 4c 20 70 61 72 61  e is no SQL para
1bd80 6d 65 74 65 72 20 77 69 74 68 20 69 6e 64 65 78  meter with index
1bd90 20 4e 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20   N or if the.** 
1bda0 20 20 20 20 20 20 20 20 20 70 61 72 61 6d 65 74           paramet
1bdb0 65 72 20 77 69 74 68 20 69 6e 64 65 78 20 4e 20  er with index N 
1bdc0 69 73 20 61 6e 20 61 6e 6f 6e 79 6d 6f 75 73 20  is an anonymous 
1bdd0 70 61 72 61 6d 65 74 65 72 20 22 3f 22 20 6f 72  parameter "?" or
1bde0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 6e  .**          a n
1bdf0 75 6d 62 65 72 65 64 20 70 61 72 61 6d 65 74 65  umbered paramete
1be00 72 20 22 3f 4e 4e 4e 22 2e 0a 2a 2f 0a 63 6f 6e  r "?NNN"..*/.con
1be10 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
1be20 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
1be30 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
1be40 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  t*, int);../*.**
1be50 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78   CAPI3REF: Index
1be60 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72 20   Of A Parameter 
1be70 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d  With A Given Nam
1be80 65 20 7b 46 31 33 36 34 30 7d 0a 2a 2a 0a 2a 2a  e {F13640}.**.**
1be90 20 52 65 74 75 72 6e 20 74 68 65 20 69 6e 64 65   Return the inde
1bea0 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61  x of an SQL para
1beb0 6d 65 74 65 72 20 67 69 76 65 6e 20 69 74 73 20  meter given its 
1bec0 6e 61 6d 65 2e 20 20 54 68 65 0a 2a 2a 20 69 6e  name.  The.** in
1bed0 64 65 78 20 76 61 6c 75 65 20 72 65 74 75 72 6e  dex value return
1bee0 65 64 20 69 73 20 73 75 69 74 61 62 6c 65 20 66  ed is suitable f
1bef0 6f 72 20 75 73 65 20 61 73 20 74 68 65 20 73 65  or use as the se
1bf00 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65  cond.** paramete
1bf10 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69  r to [sqlite3_bi
1bf20 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f  nd_blob|sqlite3_
1bf30 62 69 6e 64 28 29 5d 2e 20 20 41 20 7a 65 72 6f  bind()].  A zero
1bf40 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20  .** is returned 
1bf50 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70  if no matching p
1bf60 61 72 61 6d 65 74 65 72 20 69 73 20 66 6f 75 6e  arameter is foun
1bf70 64 2e 20 20 54 68 65 20 70 61 72 61 6d 65 74 65  d.  The paramete
1bf80 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62  r.** name must b
1bf90 65 20 67 69 76 65 6e 20 69 6e 20 55 54 46 2d 38  e given in UTF-8
1bfa0 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 72 69   even if the ori
1bfb0 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a  ginal statement.
1bfc0 2a 2a 20 77 61 73 20 70 72 65 70 61 72 65 64 20  ** was prepared 
1bfd0 66 72 6f 6d 20 55 54 46 2d 31 36 20 74 65 78 74  from UTF-16 text
1bfe0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
1bff0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
1c000 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
1c010 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
1c020 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
1c030 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
1c040 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
1c050 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a  count()], and.**
1c060 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
1c070 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
1c080 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  ]..**.** INVARIA
1c090 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 36  NTS:.**.** {F136
1c0a0 34 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  41} The [sqlite3
1c0b0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
1c0c0 69 6e 64 65 78 28 53 2c 4e 29 5d 20 69 6e 74 65  index(S,N)] inte
1c0d0 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a  rface returns.**
1c0e0 20 20 20 20 20 20 20 20 20 20 74 68 65 20 69 6e            the in
1c0f0 64 65 78 20 6f 66 20 53 51 4c 20 70 61 72 61 6d  dex of SQL param
1c100 65 74 65 72 20 69 6e 20 5b 70 72 65 70 61 72 65  eter in [prepare
1c110 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
1c120 20 20 20 20 20 20 20 20 20 53 20 77 68 6f 73 65           S whose
1c130 20 6e 61 6d 65 20 6d 61 74 63 68 65 73 20 74 68   name matches th
1c140 65 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 4e  e UTF-8 string N
1c150 2c 20 6f 72 20 30 20 69 66 20 74 68 65 72 65 20  , or 0 if there 
1c160 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e  is.**          n
1c170 6f 20 6d 61 74 63 68 2e 0a 2a 2f 0a 69 6e 74 20  o match..*/.int 
1c180 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
1c190 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 73 71 6c  ameter_index(sql
1c1a0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73  ite3_stmt*, cons
1c1b0 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a  t char *zName);.
1c1c0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1c1d0 20 52 65 73 65 74 20 41 6c 6c 20 42 69 6e 64 69   Reset All Bindi
1c1e0 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 61 72 65  ngs On A Prepare
1c1f0 64 20 53 74 61 74 65 6d 65 6e 74 20 7b 46 31 33  d Statement {F13
1c200 36 36 30 7d 0a 2a 2a 0a 2a 2a 20 43 6f 6e 74 72  660}.**.** Contr
1c210 61 72 79 20 74 6f 20 74 68 65 20 69 6e 74 75 69  ary to the intui
1c220 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73  tion of many, [s
1c230 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
1c240 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 72 65 73 65  does not.** rese
1c250 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  t the [sqlite3_b
1c260 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69  ind_blob | bindi
1c270 6e 67 73 5d 20 6f 6e 20 61 20 0a 2a 2a 20 5b 70  ngs] on a .** [p
1c280 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1c290 74 5d 2e 20 20 55 73 65 20 74 68 69 73 20 72 6f  t].  Use this ro
1c2a0 75 74 69 6e 65 20 74 6f 0a 2a 2a 20 72 65 73 65  utine to.** rese
1c2b0 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d  t all host param
1c2c0 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a  eters to NULL..*
1c2d0 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
1c2e0 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 36 36 31 7d 20  .**.** {F13661} 
1c2f0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65  The [sqlite3_cle
1c300 61 72 5f 62 69 6e 64 69 6e 67 73 28 53 29 5d 20  ar_bindings(S)] 
1c310 69 6e 74 65 72 66 61 63 65 20 72 65 73 65 74 73  interface resets
1c320 20 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20   all.**         
1c330 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 62   SQL parameter b
1c340 69 6e 64 69 6e 67 73 20 69 6e 20 5b 70 72 65 70  indings in [prep
1c350 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
1c360 53 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 61  S.**          ba
1c370 63 6b 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69  ck to NULL..*/.i
1c380 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 72  nt sqlite3_clear
1c390 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65  _bindings(sqlite
1c3a0 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  3_stmt*);../*.**
1c3b0 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65   CAPI3REF: Numbe
1c3c0 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20  r Of Columns In 
1c3d0 41 20 52 65 73 75 6c 74 20 53 65 74 20 7b 46 31  A Result Set {F1
1c3e0 33 37 31 30 7d 0a 2a 2a 0a 2a 2a 20 52 65 74 75  3710}.**.** Retu
1c3f0 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  rn the number of
1c400 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20   columns in the 
1c410 72 65 73 75 6c 74 20 73 65 74 20 72 65 74 75 72  result set retur
1c420 6e 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 5b  ned by the .** [
1c430 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1c440 6e 74 5d 2e 20 54 68 69 73 20 72 6f 75 74 69 6e  nt]. This routin
1c450 65 20 72 65 74 75 72 6e 73 20 30 0a 2a 2a 20 69  e returns 0.** i
1c460 66 20 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51  f pStmt is an SQ
1c470 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74  L statement that
1c480 20 64 6f 65 73 20 6e 6f 74 20 72 65 74 75 72 6e   does not return
1c490 20 64 61 74 61 20 28 66 6f 72 20 0a 2a 2a 20 65   data (for .** e
1c4a0 78 61 6d 70 6c 65 20 61 6e 20 55 50 44 41 54 45  xample an UPDATE
1c4b0 29 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  )..**.** INVARIA
1c4c0 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37  NTS:.**.** {F137
1c4d0 31 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  11} The [sqlite3
1c4e0 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 53 29  _column_count(S)
1c4f0 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
1c500 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
1c510 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f  f.**          co
1c520 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73  lumns in the res
1c530 75 6c 74 20 73 65 74 20 67 65 6e 65 72 61 74 65  ult set generate
1c540 64 20 62 79 20 74 68 65 0a 2a 2a 20 20 20 20 20  d by the.**     
1c550 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73       [prepared s
1c560 74 61 74 65 6d 65 6e 74 5d 20 53 2c 20 6f 72 20  tatement] S, or 
1c570 30 20 69 66 20 53 20 64 6f 65 73 20 6e 6f 74 20  0 if S does not 
1c580 67 65 6e 65 72 61 74 65 0a 2a 2a 20 20 20 20 20  generate.**     
1c590 20 20 20 20 20 61 20 72 65 73 75 6c 74 20 73 65       a result se
1c5a0 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  t..*/.int sqlite
1c5b0 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73  3_column_count(s
1c5c0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
1c5d0 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
1c5e0 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d  3REF: Column Nam
1c5f0 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53  es In A Result S
1c600 65 74 20 7b 46 31 33 37 32 30 7d 0a 2a 2a 0a 2a  et {F13720}.**.*
1c610 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
1c620 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65   return the name
1c630 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70   assigned to a p
1c640 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e  articular column
1c650 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c  .** in the resul
1c660 74 20 73 65 74 20 6f 66 20 61 20 53 45 4c 45 43  t set of a SELEC
1c670 54 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 54 68  T statement.  Th
1c680 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
1c690 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72  _name().** inter
1c6a0 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70  face returns a p
1c6b0 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f  ointer to a zero
1c6c0 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 38  -terminated UTF8
1c6d0 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73   string.** and s
1c6e0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
1c6f0 6d 65 31 36 28 29 20 72 65 74 75 72 6e 73 20 61  me16() returns a
1c700 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65   pointer to a ze
1c710 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
1c720 20 55 54 46 31 36 20 73 74 72 69 6e 67 2e 20 20   UTF16 string.  
1c730 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
1c740 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 70  ter is the.** [p
1c750 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1c760 74 5d 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  t] that implemen
1c770 74 73 20 74 68 65 20 53 45 4c 45 43 54 20 73 74  ts the SELECT st
1c780 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20  atement..** The 
1c790 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
1c7a0 20 69 73 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e   is the column n
1c7b0 75 6d 62 65 72 2e 20 20 54 68 65 20 6c 65 66 74  umber.  The left
1c7c0 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 0a  -most column is.
1c7d0 2a 2a 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a  ** number 0..**.
1c7e0 2a 2a 20 54 68 65 20 72 65 74 75 72 6e 65 64 20  ** The returned 
1c7f0 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 69  string pointer i
1c800 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 65 69  s valid until ei
1c810 74 68 65 72 20 74 68 65 20 0a 2a 2a 20 5b 70 72  ther the .** [pr
1c820 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1c830 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64 20 62  ] is destroyed b
1c840 79 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  y [sqlite3_final
1c850 69 7a 65 28 29 5d 0a 2a 2a 20 6f 72 20 75 6e 74  ize()].** or unt
1c860 69 6c 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c  il the next call
1c870 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
1c880 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65  name() or sqlite
1c890 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
1c8a0 29 0a 2a 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65  ).** on the same
1c8b0 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 49   column..**.** I
1c8c0 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  f sqlite3_malloc
1c8d0 28 29 20 66 61 69 6c 73 20 64 75 72 69 6e 67 20  () fails during 
1c8e0 74 68 65 20 70 72 6f 63 65 73 73 69 6e 67 20 6f  the processing o
1c8f0 66 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65  f either routine
1c900 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  .** (for example
1c910 20 64 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 72   during a conver
1c920 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20  sion from UTF-8 
1c930 74 6f 20 55 54 46 2d 31 36 29 20 74 68 65 6e 20  to UTF-16) then 
1c940 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  a.** NULL pointe
1c950 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  r is returned..*
1c960 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66  *.** The name of
1c970 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e   a result column
1c980 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66   is the value of
1c990 20 74 68 65 20 22 41 53 22 20 63 6c 61 75 73 65   the "AS" clause
1c9a0 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c   for.** that col
1c9b0 75 6d 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73  umn, if there is
1c9c0 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20   an AS clause.  
1c9d0 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41  If there is no A
1c9e0 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e  S clause.** then
1c9f0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
1ca00 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65   column is unspe
1ca10 63 69 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63  cified and may c
1ca20 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e  hange from.** on
1ca30 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c  e release of SQL
1ca40 69 74 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e  ite to the next.
1ca50 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
1ca60 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 32 31  S:.**.** {F13721
1ca70 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 69  } A successful i
1ca80 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 65  nvocation of the
1ca90 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
1caa0 5f 6e 61 6d 65 28 53 2c 4e 29 5d 0a 2a 2a 20 20  _name(S,N)].**  
1cab0 20 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 63          interfac
1cac0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 61  e returns the na
1cad0 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  me.**          o
1cae0 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  f the Nth column
1caf0 20 28 77 68 65 72 65 20 30 20 69 73 20 74 68 65   (where 0 is the
1cb00 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d   left-most colum
1cb10 6e 29 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20  n) for the.**   
1cb20 20 20 20 20 20 20 20 72 65 73 75 6c 74 20 73 65         result se
1cb30 74 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73  t of [prepared s
1cb40 74 61 74 65 6d 65 6e 74 5d 20 53 20 61 73 20 61  tatement] S as a
1cb50 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72  .**          zer
1cb60 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
1cb70 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  -8 string..**.**
1cb80 20 7b 46 31 33 37 32 33 7d 20 41 20 73 75 63 63   {F13723} A succ
1cb90 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f  essful invocatio
1cba0 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  n of the [sqlite
1cbb0 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
1cbc0 53 2c 4e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  S,N)].**        
1cbd0 20 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75    interface retu
1cbe0 72 6e 73 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20  rns the name.** 
1cbf0 20 20 20 20 20 20 20 20 20 6f 66 20 74 68 65 20           of the 
1cc00 4e 74 68 20 63 6f 6c 75 6d 6e 20 28 77 68 65 72  Nth column (wher
1cc10 65 20 30 20 69 73 20 74 68 65 20 6c 65 66 74 2d  e 0 is the left-
1cc20 6d 6f 73 74 20 63 6f 6c 75 6d 6e 29 20 66 6f 72  most column) for
1cc30 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
1cc40 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 5b   result set of [
1cc50 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1cc60 6e 74 5d 20 53 20 61 73 20 61 0a 2a 2a 20 20 20  nt] S as a.**   
1cc70 20 20 20 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d         zero-term
1cc80 69 6e 61 74 65 64 20 55 54 46 2d 31 36 20 73 74  inated UTF-16 st
1cc90 72 69 6e 67 20 69 6e 20 74 68 65 20 6e 61 74 69  ring in the nati
1cca0 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a  ve byte order..*
1ccb0 2a 0a 2a 2a 20 7b 46 31 33 37 32 34 7d 20 54 68  *.** {F13724} Th
1ccc0 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
1ccd0 6e 5f 6e 61 6d 65 28 29 5d 20 61 6e 64 20 5b 73  n_name()] and [s
1cce0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
1ccf0 6d 65 31 36 28 29 5d 0a 2a 2a 20 20 20 20 20 20  me16()].**      
1cd00 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 20 72      interfaces r
1cd10 65 74 75 72 6e 20 61 20 4e 55 4c 4c 20 70 6f 69  eturn a NULL poi
1cd20 6e 74 65 72 20 69 66 20 74 68 65 79 20 61 72 65  nter if they are
1cd30 20 75 6e 61 62 6c 65 20 74 6f 0a 2a 2a 20 20 20   unable to.**   
1cd40 20 20 20 20 20 20 20 61 6c 6c 6f 63 61 74 65 20         allocate 
1cd50 6d 65 6d 6f 72 79 20 6d 65 6d 6f 72 79 20 74 6f  memory memory to
1cd60 20 68 6f 6c 64 20 74 68 65 72 65 20 6e 6f 72 6d   hold there norm
1cd70 61 6c 20 72 65 74 75 72 6e 20 73 74 72 69 6e 67  al return string
1cd80 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 32 35  s..**.** {F13725
1cd90 7d 20 49 66 20 74 68 65 20 4e 20 70 61 72 61 6d  } If the N param
1cda0 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
1cdb0 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 53 2c 4e  _column_name(S,N
1cdc0 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  )] or.**        
1cdd0 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d    [sqlite3_colum
1cde0 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20 69  n_name16(S,N)] i
1cdf0 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 20  s out of range, 
1ce00 74 68 65 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20  then the.**     
1ce10 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 20       interfaces 
1ce20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70  returns a NULL p
1ce30 6f 69 6e 74 65 72 2e 0a 2a 2a 20 0a 2a 2a 20 7b  ointer..** .** {
1ce40 46 31 33 37 32 36 7d 20 54 68 65 20 73 74 72 69  F13726} The stri
1ce50 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ngs returned by 
1ce60 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
1ce70 6e 61 6d 65 28 53 2c 4e 29 5d 20 61 6e 64 0a 2a  name(S,N)] and.*
1ce80 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
1ce90 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
1cea0 36 28 53 2c 4e 29 5d 20 61 72 65 20 76 61 6c 69  6(S,N)] are vali
1ceb0 64 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74  d until the next
1cec0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c  .**          cal
1ced0 6c 20 74 6f 20 65 69 74 68 65 72 20 72 6f 75 74  l to either rout
1cee0 69 6e 65 20 77 69 74 68 20 74 68 65 20 73 61 6d  ine with the sam
1cef0 65 20 53 20 61 6e 64 20 4e 20 70 61 72 61 6d 65  e S and N parame
1cf00 74 65 72 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  ters.**         
1cf10 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74   or until [sqlit
1cf20 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 5d 20  e3_finalize(S)] 
1cf30 69 73 20 63 61 6c 6c 65 64 2e 0a 2a 2a 0a 2a 2a  is called..**.**
1cf40 20 7b 46 31 33 37 32 37 7d 20 57 68 65 6e 20 61   {F13727} When a
1cf50 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f   result column o
1cf60 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  f a [SELECT] sta
1cf70 74 65 6d 65 6e 74 20 63 6f 6e 74 61 69 6e 73 0a  tement contains.
1cf80 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 20 41  **          an A
1cf90 53 20 63 6c 61 75 73 65 2c 20 74 68 65 20 6e 61  S clause, the na
1cfa0 6d 65 20 6f 66 20 74 68 61 74 20 63 6f 6c 75 6d  me of that colum
1cfb0 6e 20 69 73 20 74 68 65 20 69 6e 64 65 6e 74 69  n is the indenti
1cfc0 66 69 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  fier.**         
1cfd0 20 74 6f 20 74 68 65 20 72 69 67 68 74 20 6f 66   to the right of
1cfe0 20 74 68 65 20 41 53 20 6b 65 79 77 6f 72 64 2e   the AS keyword.
1cff0 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
1d000 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
1d010 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
1d020 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74  *, int N);.const
1d030 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
1d040 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c  olumn_name16(sql
1d050 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
1d060 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  N);../*.** CAPI3
1d070 52 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 44  REF: Source Of D
1d080 61 74 61 20 49 6e 20 41 20 51 75 65 72 79 20 52  ata In A Query R
1d090 65 73 75 6c 74 20 7b 46 31 33 37 34 30 7d 0a 2a  esult {F13740}.*
1d0a0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
1d0b0 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65  nes provide a me
1d0c0 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65  ans to determine
1d0d0 20 77 68 61 74 20 63 6f 6c 75 6d 6e 20 6f 66 20   what column of 
1d0e0 77 68 61 74 0a 2a 2a 20 74 61 62 6c 65 20 69 6e  what.** table in
1d0f0 20 77 68 69 63 68 20 64 61 74 61 62 61 73 65 20   which database 
1d100 61 20 72 65 73 75 6c 74 20 6f 66 20 61 20 53 45  a result of a SE
1d110 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 20 63  LECT statement c
1d120 6f 6d 65 73 20 66 72 6f 6d 2e 0a 2a 2a 20 54 68  omes from..** Th
1d130 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61  e name of the da
1d140 74 61 62 61 73 65 20 6f 72 20 74 61 62 6c 65 20  tabase or table 
1d150 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65  or column can be
1d160 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20   returned as.** 
1d170 65 69 74 68 65 72 20 61 20 55 54 46 38 20 6f 72  either a UTF8 or
1d180 20 55 54 46 31 36 20 73 74 72 69 6e 67 2e 20 20   UTF16 string.  
1d190 54 68 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72  The _database_ r
1d1a0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a  outines return.*
1d1b0 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e  * the database n
1d1c0 61 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f  ame, the _table_
1d1d0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
1d1e0 20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c   the table name,
1d1f0 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67   and.** the orig
1d200 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74  in_ routines ret
1d210 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e  urn the column n
1d220 61 6d 65 2e 0a 2a 2a 20 54 68 65 20 72 65 74 75  ame..** The retu
1d230 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 76  rned string is v
1d240 61 6c 69 64 20 75 6e 74 69 6c 0a 2a 2a 20 74 68  alid until.** th
1d250 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
1d260 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f  ement] is destro
1d270 79 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  yed using.** [sq
1d280 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
1d290 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73  ] or until the s
1d2a0 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  ame information 
1d2b0 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a 2a 20  is requested.** 
1d2c0 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66 66 65  again in a diffe
1d2d0 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a  rent encoding..*
1d2e0 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 73 20 72  *.** The names r
1d2f0 65 74 75 72 6e 65 64 20 61 72 65 20 74 68 65 20  eturned are the 
1d300 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61  original un-alia
1d310 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 65  sed names of the
1d320 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 74 61  .** database, ta
1d330 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e  ble, and column.
1d340 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
1d350 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
1d360 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 6c 6c 73   following calls
1d370 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20   is a [prepared 
1d380 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 54  statement]..** T
1d390 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72  hese functions r
1d3a0 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f  eturn informatio
1d3b0 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74 68 20  n about the Nth 
1d3c0 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20  column returned 
1d3d0 62 79 20 0a 2a 2a 20 74 68 65 20 73 74 61 74 65  by .** the state
1d3e0 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 69 73  ment, where N is
1d3f0 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63   the second func
1d400 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  tion argument..*
1d410 2a 0a 2a 2a 20 49 66 20 74 68 65 20 4e 74 68 20  *.** If the Nth 
1d420 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20  column returned 
1d430 62 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  by the statement
1d440 20 69 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f   is an expressio
1d450 6e 0a 2a 2a 20 6f 72 20 73 75 62 71 75 65 72 79  n.** or subquery
1d460 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 6f   and is not a co
1d470 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e  lumn value, then
1d480 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 75   all of these fu
1d490 6e 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 74 75 72  nctions.** retur
1d4a0 6e 20 4e 55 4c 4c 2e 20 20 54 68 65 73 65 20 72  n NULL.  These r
1d4b0 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 61 6c 73  outine might als
1d4c0 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66  o return NULL if
1d4d0 20 61 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c   a memory.** all
1d4e0 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63  ocation error oc
1d4f0 63 75 72 73 2e 20 20 4f 74 68 65 72 77 69 73 65  curs.  Otherwise
1d500 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20 74 68  , they return th
1d510 65 20 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20 74 68  e .** name of th
1d520 65 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62  e attached datab
1d530 61 73 65 2c 20 74 61 62 6c 65 20 61 6e 64 20 63  ase, table and c
1d540 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79  olumn that query
1d550 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d   result.** colum
1d560 6e 20 77 61 73 20 65 78 74 72 61 63 74 65 64 20  n was extracted 
1d570 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 77  from..**.** As w
1d580 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51  ith all other SQ
1d590 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65  Lite APIs, those
1d5a0 20 70 6f 73 74 66 69 78 65 64 20 77 69 74 68 20   postfixed with 
1d5b0 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55  "16" return.** U
1d5c0 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 74  TF-16 encoded st
1d5d0 72 69 6e 67 73 2c 20 74 68 65 20 6f 74 68 65 72  rings, the other
1d5e0 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72   functions retur
1d5f0 6e 20 55 54 46 2d 38 2e 20 7b 45 4e 44 7d 0a 2a  n UTF-8. {END}.*
1d600 2a 0a 2a 2a 20 54 68 65 73 65 20 41 50 49 73 20  *.** These APIs 
1d610 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62  are only availab
1d620 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 72  le if the librar
1d630 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77  y was compiled w
1d640 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49  ith the .** SQLI
1d650 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e  TE_ENABLE_COLUMN
1d660 5f 4d 45 54 41 44 41 54 41 20 70 72 65 70 72 6f  _METADATA prepro
1d670 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 20 64 65  cessor symbol de
1d680 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 55 31  fined..**.** {U1
1d690 33 37 35 31 7d 0a 2a 2a 20 49 66 20 74 77 6f 20  3751}.** If two 
1d6a0 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20  or more threads 
1d6b0 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  call one or more
1d6c0 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
1d6d0 65 73 20 61 67 61 69 6e 73 74 20 74 68 65 20 73  es against the s
1d6e0 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20  ame.** prepared 
1d6f0 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f  statement and co
1d700 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d 65  lumn at the same
1d710 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72   time then the r
1d720 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e  esults are.** un
1d730 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  defined..**.** I
1d740 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
1d750 20 7b 46 31 33 37 34 31 7d 20 54 68 65 20 5b 73   {F13741} The [s
1d760 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61  qlite3_column_da
1d770 74 61 62 61 73 65 5f 6e 61 6d 65 28 53 2c 4e 29  tabase_name(S,N)
1d780 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
1d790 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20  rns either.**   
1d7a0 20 20 20 20 20 20 20 74 68 65 20 55 54 46 2d 38         the UTF-8
1d7b0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1d7c0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74   name of the dat
1d7d0 61 62 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68  abase from which
1d7e0 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 20 20 20   the .**        
1d7f0 20 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c    Nth result col
1d800 75 6d 6e 20 6f 66 20 5b 70 72 65 70 61 72 65 64  umn of [prepared
1d810 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 0a 2a   statement] S .*
1d820 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 65 78  *          is ex
1d830 74 72 61 63 74 65 64 2c 20 6f 72 20 4e 55 4c 4c  tracted, or NULL
1d840 20 69 66 20 74 68 65 20 74 68 65 20 4e 74 68 20   if the the Nth 
1d850 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20 61  column of S is a
1d860 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 67 65 6e  .**          gen
1d870 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e 20  eral expression 
1d880 6f 72 20 69 66 20 75 6e 61 62 6c 65 20 74 6f 20  or if unable to 
1d890 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 0a  allocate memory.
1d8a0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 73  **          to s
1d8b0 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a  tore the name..*
1d8c0 2a 20 20 20 20 20 20 20 20 20 20 0a 2a 2a 20 7b  *          .** {
1d8d0 46 31 33 37 34 32 7d 20 54 68 65 20 5b 73 71 6c  F13742} The [sql
1d8e0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61  ite3_column_data
1d8f0 62 61 73 65 5f 6e 61 6d 65 31 36 28 53 2c 4e 29  base_name16(S,N)
1d900 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
1d910 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20  rns either.**   
1d920 20 20 20 20 20 20 20 74 68 65 20 55 54 46 2d 31         the UTF-1
1d930 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  6 native byte or
1d940 64 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  der.**          
1d950 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
1d960 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61  name of the data
1d970 62 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68 20  base from which 
1d980 74 68 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  the .**         
1d990 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75   Nth result colu
1d9a0 6d 6e 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20  mn of [prepared 
1d9b0 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 0a 2a 2a  statement] S .**
1d9c0 20 20 20 20 20 20 20 20 20 20 69 73 20 65 78 74            is ext
1d9d0 72 61 63 74 65 64 2c 20 6f 72 20 4e 55 4c 4c 20  racted, or NULL 
1d9e0 69 66 20 74 68 65 20 74 68 65 20 4e 74 68 20 63  if the the Nth c
1d9f0 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20 61 0a  olumn of S is a.
1da00 2a 2a 20 20 20 20 20 20 20 20 20 20 67 65 6e 65  **          gene
1da10 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e 20 6f  ral expression o
1da20 72 20 69 66 20 75 6e 61 62 6c 65 20 74 6f 20 61  r if unable to a
1da30 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 0a 2a  llocate memory.*
1da40 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 73 74  *          to st
1da50 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a  ore the name..**
1da60 20 20 20 20 20 20 20 20 20 20 0a 2a 2a 20 7b 46            .** {F
1da70 31 33 37 34 33 7d 20 54 68 65 20 5b 73 71 6c 69  13743} The [sqli
1da80 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65  te3_column_table
1da90 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 69 6e 74 65  _name(S,N)] inte
1daa0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 65 69  rface returns ei
1dab0 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  ther.**         
1dac0 20 74 68 65 20 55 54 46 2d 38 20 7a 65 72 6f 2d   the UTF-8 zero-
1dad0 74 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20  terminated name 
1dae0 6f 66 20 74 68 65 20 74 61 62 6c 65 20 66 72 6f  of the table fro
1daf0 6d 20 77 68 69 63 68 20 74 68 65 20 0a 2a 2a 20  m which the .** 
1db00 20 20 20 20 20 20 20 20 20 4e 74 68 20 72 65 73           Nth res
1db10 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 5b 70  ult column of [p
1db20 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1db30 74 5d 20 53 20 0a 2a 2a 20 20 20 20 20 20 20 20  t] S .**        
1db40 20 20 69 73 20 65 78 74 72 61 63 74 65 64 2c 20    is extracted, 
1db50 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 74  or NULL if the t
1db60 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66  he Nth column of
1db70 20 53 20 69 73 20 61 0a 2a 2a 20 20 20 20 20 20   S is a.**      
1db80 20 20 20 20 67 65 6e 65 72 61 6c 20 65 78 70 72      general expr
1db90 65 73 73 69 6f 6e 20 6f 72 20 69 66 20 75 6e 61  ession or if una
1dba0 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ble to allocate 
1dbb0 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20 20 20 20 20  memory.**       
1dbc0 20 20 20 74 6f 20 73 74 6f 72 65 20 74 68 65 20     to store the 
1dbd0 6e 61 6d 65 2e 0a 2a 2a 20 20 20 20 20 20 20 20  name..**        
1dbe0 20 20 0a 2a 2a 20 7b 46 31 33 37 34 34 7d 20 54    .** {F13744} T
1dbf0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
1dc00 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28  mn_table_name16(
1dc10 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  S,N)] interface 
1dc20 72 65 74 75 72 6e 73 20 65 69 74 68 65 72 0a 2a  returns either.*
1dc30 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 55  *          the U
1dc40 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74  TF-16 native byt
1dc50 65 20 6f 72 64 65 72 0a 2a 2a 20 20 20 20 20 20  e order.**      
1dc60 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61      zero-termina
1dc70 74 65 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  ted name of the 
1dc80 74 61 62 6c 65 20 66 72 6f 6d 20 77 68 69 63 68  table from which
1dc90 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 20 20 20   the .**        
1dca0 20 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c    Nth result col
1dcb0 75 6d 6e 20 6f 66 20 5b 70 72 65 70 61 72 65 64  umn of [prepared
1dcc0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 0a 2a   statement] S .*
1dcd0 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 65 78  *          is ex
1dce0 74 72 61 63 74 65 64 2c 20 6f 72 20 4e 55 4c 4c  tracted, or NULL
1dcf0 20 69 66 20 74 68 65 20 74 68 65 20 4e 74 68 20   if the the Nth 
1dd00 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20 61  column of S is a
1dd10 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 67 65 6e  .**          gen
1dd20 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e 20  eral expression 
1dd30 6f 72 20 69 66 20 75 6e 61 62 6c 65 20 74 6f 20  or if unable to 
1dd40 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 0a  allocate memory.
1dd50 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 73  **          to s
1dd60 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a  tore the name..*
1dd70 2a 20 20 20 20 20 20 20 20 20 20 0a 2a 2a 20 7b  *          .** {
1dd80 46 31 33 37 34 35 7d 20 54 68 65 20 5b 73 71 6c  F13745} The [sql
1dd90 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67  ite3_column_orig
1dda0 69 6e 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 69 6e  in_name(S,N)] in
1ddb0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
1ddc0 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20  either.**       
1ddd0 20 20 20 74 68 65 20 55 54 46 2d 38 20 7a 65 72     the UTF-8 zer
1dde0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d  o-terminated nam
1ddf0 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63  e of the table c
1de00 6f 6c 75 6d 6e 20 66 72 6f 6d 20 77 68 69 63 68  olumn from which
1de10 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 20 20 20   the .**        
1de20 20 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c    Nth result col
1de30 75 6d 6e 20 6f 66 20 5b 70 72 65 70 61 72 65 64  umn of [prepared
1de40 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 0a 2a   statement] S .*
1de50 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 65 78  *          is ex
1de60 74 72 61 63 74 65 64 2c 20 6f 72 20 4e 55 4c 4c  tracted, or NULL
1de70 20 69 66 20 74 68 65 20 74 68 65 20 4e 74 68 20   if the the Nth 
1de80 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20 61  column of S is a
1de90 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 67 65 6e  .**          gen
1dea0 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e 20  eral expression 
1deb0 6f 72 20 69 66 20 75 6e 61 62 6c 65 20 74 6f 20  or if unable to 
1dec0 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 0a  allocate memory.
1ded0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 73  **          to s
1dee0 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a  tore the name..*
1def0 2a 20 20 20 20 20 20 20 20 20 20 0a 2a 2a 20 7b  *          .** {
1df00 46 31 33 37 34 36 7d 20 54 68 65 20 5b 73 71 6c  F13746} The [sql
1df10 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67  ite3_column_orig
1df20 69 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20  in_name16(S,N)] 
1df30 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
1df40 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20  s either.**     
1df50 20 20 20 20 20 74 68 65 20 55 54 46 2d 31 36 20       the UTF-16 
1df60 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
1df70 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65  r.**          ze
1df80 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e 61  ro-terminated na
1df90 6d 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20  me of the table 
1dfa0 63 6f 6c 75 6d 6e 20 66 72 6f 6d 20 77 68 69 63  column from whic
1dfb0 68 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 20 20  h the .**       
1dfc0 20 20 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f     Nth result co
1dfd0 6c 75 6d 6e 20 6f 66 20 5b 70 72 65 70 61 72 65  lumn of [prepare
1dfe0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 0a  d statement] S .
1dff0 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 65  **          is e
1e000 78 74 72 61 63 74 65 64 2c 20 6f 72 20 4e 55 4c  xtracted, or NUL
1e010 4c 20 69 66 20 74 68 65 20 74 68 65 20 4e 74 68  L if the the Nth
1e020 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20   column of S is 
1e030 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 67 65  a.**          ge
1e040 6e 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e  neral expression
1e050 20 6f 72 20 69 66 20 75 6e 61 62 6c 65 20 74 6f   or if unable to
1e060 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79   allocate memory
1e070 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20  .**          to 
1e080 73 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a  store the name..
1e090 2a 2a 20 20 20 20 20 20 20 20 20 20 0a 2a 2a 20  **          .** 
1e0a0 7b 46 31 33 37 34 38 7d 20 54 68 65 20 72 65 74  {F13748} The ret
1e0b0 75 72 6e 20 76 61 6c 75 65 73 20 66 72 6f 6d 0a  urn values from.
1e0c0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
1e0d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61  ite3_column_data
1e0e0 62 61 73 65 5f 6e 61 6d 65 7c 63 6f 6c 75 6d 6e  base_name|column
1e0f0 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72 66   metadata interf
1e100 61 63 65 73 5d 0a 2a 2a 20 20 20 20 20 20 20 20  aces].**        
1e110 20 20 61 72 65 20 76 61 6c 69 64 0a 2a 2a 20 20    are valid.**  
1e120 20 20 20 20 20 20 20 20 66 6f 72 20 74 68 65 20          for the 
1e130 6c 69 66 65 74 69 6d 65 20 6f 66 20 74 68 65 20  lifetime of the 
1e140 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
1e150 65 6e 74 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ent].**         
1e160 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 65 6e   or until the en
1e170 63 6f 64 69 6e 67 20 69 73 20 63 68 61 6e 67 65  coding is change
1e180 64 20 62 79 20 61 6e 6f 74 68 65 72 20 6d 65 74  d by another met
1e190 61 64 61 74 61 0a 2a 2a 20 20 20 20 20 20 20 20  adata.**        
1e1a0 20 20 69 6e 74 65 72 66 61 63 65 20 63 61 6c 6c    interface call
1e1b0 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 70 72   for the same pr
1e1c0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1e1d0 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a   and column..**.
1e1e0 2a 2a 20 4c 49 4d 49 54 41 54 49 4f 4e 53 3a 0a  ** LIMITATIONS:.
1e1f0 2a 2a 0a 2a 2a 20 7b 55 31 33 37 35 31 7d 20 49  **.** {U13751} I
1e200 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68  f two or more th
1e210 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f  reads call one o
1e220 72 20 6d 6f 72 65 0a 2a 2a 20 20 20 20 20 20 20  r more.**       
1e230 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75     [sqlite3_colu
1e240 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
1e250 7c 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61  |column metadata
1e260 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20   interfaces].** 
1e270 20 20 20 20 20 20 20 20 20 74 68 65 20 73 61 6d           the sam
1e280 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
1e290 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c  ement] and resul
1e2a0 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 20 20 20 20  t column.**     
1e2b0 20 20 20 20 20 61 74 20 74 68 65 20 73 61 6d 65       at the same
1e2c0 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72   time then the r
1e2d0 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
1e2e0 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63  ined..*/.const c
1e2f0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
1e300 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d  umn_database_nam
1e310 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
1e320 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  int);.const void
1e330 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
1e340 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36  _database_name16
1e350 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
1e360 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20  nt);.const char 
1e370 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
1e380 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74  table_name(sqlit
1e390 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
1e3a0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
1e3b0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f  e3_column_table_
1e3c0 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73  name16(sqlite3_s
1e3d0 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
1e3e0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
1e3f0 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d  olumn_origin_nam
1e400 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
1e410 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  int);.const void
1e420 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
1e430 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73  _origin_name16(s
1e440 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
1e450 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1e460 45 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61 74  EF: Declared Dat
1e470 61 74 79 70 65 20 4f 66 20 41 20 51 75 65 72 79  atype Of A Query
1e480 20 52 65 73 75 6c 74 20 7b 46 31 33 37 36 30 7d   Result {F13760}
1e490 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
1e4a0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
1e4b0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
1e4c0 65 6e 74 5d 2e 20 0a 2a 2a 20 49 66 20 74 68 69  ent]. .** If thi
1e4d0 73 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  s statement is a
1e4e0 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e   SELECT statemen
1e4f0 74 20 61 6e 64 20 74 68 65 20 4e 74 68 20 63 6f  t and the Nth co
1e500 6c 75 6d 6e 20 6f 66 20 74 68 65 20 0a 2a 2a 20  lumn of the .** 
1e510 72 65 74 75 72 6e 65 64 20 72 65 73 75 6c 74 20  returned result 
1e520 73 65 74 20 6f 66 20 74 68 61 74 20 53 45 4c 45  set of that SELE
1e530 43 54 20 69 73 20 61 20 74 61 62 6c 65 20 63 6f  CT is a table co
1e540 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20  lumn (not an.** 
1e550 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75  expression or su
1e560 62 71 75 65 72 79 29 20 74 68 65 6e 20 74 68 65  bquery) then the
1e570 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f   declared type o
1e580 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63  f the table.** c
1e590 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75 72 6e 65  olumn is returne
1e5a0 64 2e 20 20 49 66 20 74 68 65 20 4e 74 68 20 63  d.  If the Nth c
1e5b0 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73  olumn of the res
1e5c0 75 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a  ult set is an.**
1e5d0 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73   expression or s
1e5e0 75 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20  ubquery, then a 
1e5f0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20  NULL pointer is 
1e600 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 54 68 65  returned..** The
1e610 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
1e620 20 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38   is always UTF-8
1e630 20 65 6e 63 6f 64 65 64 2e 20 20 7b 45 4e 44 7d   encoded.  {END}
1e640 20 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65   .** For example
1e650 2c 20 69 6e 20 74 68 65 20 64 61 74 61 62 61 73  , in the databas
1e660 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20  e schema:.**.** 
1e670 43 52 45 41 54 45 20 54 41 42 4c 45 20 74 31 28  CREATE TABLE t1(
1e680 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a  c1 VARIANT);.**.
1e690 2a 2a 20 41 6e 64 20 74 68 65 20 66 6f 6c 6c 6f  ** And the follo
1e6a0 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63  wing statement c
1e6b0 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53  ompiled:.**.** S
1e6c0 45 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 63 31  ELECT c1 + 1, c1
1e6d0 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20   FROM t1;.**.** 
1e6e0 54 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e  Then this routin
1e6f0 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74  e would return t
1e700 68 65 20 73 74 72 69 6e 67 20 22 56 41 52 49 41  he string "VARIA
1e710 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f  NT" for the seco
1e720 6e 64 0a 2a 2a 20 72 65 73 75 6c 74 20 63 6f 6c  nd.** result col
1e730 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20  umn (i==1), and 
1e740 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66  a NULL pointer f
1e750 6f 72 20 74 68 65 20 66 69 72 73 74 20 72 65 73  or the first res
1e760 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 28 69  ult column.** (i
1e770 3d 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  ==0)..**.** SQLi
1e780 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20  te uses dynamic 
1e790 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e  run-time typing.
1e7a0 20 20 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73    So just becaus
1e7b0 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73  e a column.** is
1e7c0 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e   declared to con
1e7d0 74 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61  tain a particula
1e7e0 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20  r type does not 
1e7f0 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a  mean that the.**
1e800 20 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20   data stored in 
1e810 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f  that column is o
1e820 66 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74  f the declared t
1e830 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a  ype.  SQLite is.
1e840 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65  ** strongly type
1e850 64 2c 20 62 75 74 20 74 68 65 20 74 79 70 69 6e  d, but the typin
1e860 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74  g is dynamic not
1e870 20 73 74 61 74 69 63 2e 20 20 54 79 70 65 0a 2a   static.  Type.*
1e880 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20  * is associated 
1e890 77 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c 20  with individual 
1e8a0 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 68  values, not with
1e8b0 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a   the containers.
1e8c0 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20  ** used to hold 
1e8d0 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2a  those values..**
1e8e0 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
1e8f0 2a 2a 0a 2a 2a 20 7b 46 31 33 37 36 31 7d 20 20  **.** {F13761}  
1e900 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  A successful cal
1e910 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  l to [sqlite3_co
1e920 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 53 2c  lumn_decltype(S,
1e930 4e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  N)].**          
1e940 20 72 65 74 75 72 6e 73 20 61 20 7a 65 72 6f 2d   returns a zero-
1e950 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
1e960 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69   string containi
1e970 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ng the.**       
1e980 20 20 20 20 74 68 65 20 64 65 63 6c 61 72 65 64      the declared
1e990 20 64 61 74 61 74 79 70 65 20 6f 66 20 74 68 65   datatype of the
1e9a0 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68   table column th
1e9b0 61 74 20 61 70 70 65 61 72 73 0a 2a 2a 20 20 20  at appears.**   
1e9c0 20 20 20 20 20 20 20 20 61 73 20 74 68 65 20 4e          as the N
1e9d0 74 68 20 63 6f 6c 75 6d 6e 20 28 6e 75 6d 62 65  th column (numbe
1e9e0 72 65 64 20 66 72 6f 6d 20 30 29 20 6f 66 20 74  red from 0) of t
1e9f0 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 74 6f  he result set to
1ea00 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
1ea10 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74    [prepared stat
1ea20 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20  ement] S..**.** 
1ea30 7b 46 31 33 37 36 32 7d 20 20 41 20 73 75 63 63  {F13762}  A succ
1ea40 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b  essful call to [
1ea50 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
1ea60 65 63 6c 74 79 70 65 31 36 28 53 2c 4e 29 5d 0a  ecltype16(S,N)].
1ea70 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72 65 74  **           ret
1ea80 75 72 6e 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d  urns a zero-term
1ea90 69 6e 61 74 65 64 20 55 54 46 2d 31 36 20 6e 61  inated UTF-16 na
1eaa0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
1eab0 73 74 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20  string.**       
1eac0 20 20 20 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74      containing t
1ead0 68 65 20 64 65 63 6c 61 72 65 64 20 64 61 74 61  he declared data
1eae0 74 79 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c  type of the tabl
1eaf0 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 61 70  e column that ap
1eb00 70 65 61 72 73 0a 2a 2a 20 20 20 20 20 20 20 20  pears.**        
1eb10 20 20 20 61 73 20 74 68 65 20 4e 74 68 20 63 6f     as the Nth co
1eb20 6c 75 6d 6e 20 28 6e 75 6d 62 65 72 65 64 20 66  lumn (numbered f
1eb30 72 6f 6d 20 30 29 20 6f 66 20 74 68 65 20 72 65  rom 0) of the re
1eb40 73 75 6c 74 20 73 65 74 20 74 6f 20 74 68 65 0a  sult set to the.
1eb50 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 70 72  **           [pr
1eb60 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1eb70 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37  ] S..**.** {F137
1eb80 36 33 7d 20 20 49 66 20 4e 20 69 73 20 6c 65 73  63}  If N is les
1eb90 73 20 74 68 61 6e 20 30 20 6f 72 20 4e 20 69 73  s than 0 or N is
1eba0 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 6f 72   greater than or
1ebb0 20 65 71 75 61 6c 20 74 6f 0a 2a 2a 20 20 20 20   equal to.**    
1ebc0 20 20 20 20 20 20 20 74 68 65 20 6e 75 6d 62 65         the numbe
1ebd0 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
1ebe0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
1ebf0 65 6e 74 5d 20 53 0a 2a 2a 20 20 20 20 20 20 20  ent] S.**       
1ec00 20 20 20 20 6f 72 20 69 66 20 74 68 65 20 4e 74      or if the Nt
1ec10 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73  h column of S is
1ec20 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f   an expression o
1ec30 72 20 73 75 62 71 75 65 72 79 20 72 61 74 68 65  r subquery rathe
1ec40 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74  r.**           t
1ec50 68 61 6e 20 61 20 74 61 62 6c 65 20 63 6f 6c 75  han a table colu
1ec60 6d 6e 20 6f 72 20 69 66 20 61 20 6d 65 6d 6f 72  mn or if a memor
1ec70 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69  y allocation fai
1ec80 6c 75 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  lure.**         
1ec90 20 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20    occurs during 
1eca0 65 6e 63 6f 64 69 6e 67 20 63 6f 6e 76 65 72 73  encoding convers
1ecb0 69 6f 6e 73 2c 20 74 68 65 6e 0a 2a 2a 20 20 20  ions, then.**   
1ecc0 20 20 20 20 20 20 20 20 63 61 6c 6c 73 20 74 6f          calls to
1ecd0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
1ece0 5f 64 65 63 6c 74 79 70 65 28 53 2c 4e 29 5d 20  _decltype(S,N)] 
1ecf0 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  or.**           
1ed00 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
1ed10 64 65 63 6c 74 79 70 65 31 36 28 53 2c 4e 29 5d  decltype16(S,N)]
1ed20 20 72 65 74 75 72 6e 20 4e 55 4c 4c 2e 0a 2a 2f   return NULL..*/
1ed30 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
1ed40 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c  ite3_column_decl
1ed50 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  type(sqlite3_stm
1ed60 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76  t*,int);.const v
1ed70 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
1ed80 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 73  umn_decltype16(s
1ed90 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
1eda0 29 3b 0a 0a 2f 2a 20 0a 2a 2a 20 43 41 50 49 33  );../* .** CAPI3
1edb0 52 45 46 3a 20 20 45 76 61 6c 75 61 74 65 20 41  REF:  Evaluate A
1edc0 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20  n SQL Statement 
1edd0 7b 46 31 33 32 30 30 7d 0a 2a 2a 0a 2a 2a 20 41  {F13200}.**.** A
1ede0 66 74 65 72 20 61 6e 20 5b 70 72 65 70 61 72 65  fter an [prepare
1edf0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 68 61 73  d statement] has
1ee00 20 62 65 65 6e 20 70 72 65 70 61 72 65 64 20 77   been prepared w
1ee10 69 74 68 20 61 20 63 61 6c 6c 0a 2a 2a 20 74 6f  ith a call.** to
1ee20 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33   either [sqlite3
1ee30 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
1ee40 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
1ee50 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 6f  re16_v2()] or to
1ee60 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c   one of.** the l
1ee70 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 73  egacy interfaces
1ee80 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1ee90 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  e()] or [sqlite3
1eea0 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c 0a 2a  _prepare16()],.*
1eeb0 2a 20 74 68 65 6e 20 74 68 69 73 20 66 75 6e 63  * then this func
1eec0 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 63 61 6c  tion must be cal
1eed0 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  led one or more 
1eee0 74 69 6d 65 73 20 74 6f 20 65 76 61 6c 75 61 74  times to evaluat
1eef0 65 20 74 68 65 20 0a 2a 2a 20 73 74 61 74 65 6d  e the .** statem
1ef00 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64  ent..**.** The d
1ef10 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65  etails of the be
1ef20 68 61 76 69 6f 72 20 6f 66 20 74 68 69 73 20 73  havior of this s
1ef30 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e  qlite3_step() in
1ef40 74 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a  terface depend.*
1ef50 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65  * on whether the
1ef60 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70   statement was p
1ef70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 74 68  repared using th
1ef80 65 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e 74  e newer "v2" int
1ef90 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74  erface.** [sqlit
1efa0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1efb0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
1efc0 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72  epare16_v2()] or
1efd0 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 63   the older legac
1efe0 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 5b  y.** interface [
1eff0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
1f000 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
1f010 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20 54  prepare16()].  T
1f020 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a  he use of the.**
1f030 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72 66   new "v2" interf
1f040 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64  ace is recommend
1f050 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c 69  ed for new appli
1f060 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65 20  cations but the 
1f070 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66  legacy.** interf
1f080 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75  ace will continu
1f090 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65  e to be supporte
1f0a0 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20  d..**.** In the 
1f0b0 6c 61 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  lagacy interface
1f0c0 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  , the return val
1f0d0 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74 68 65  ue will be eithe
1f0e0 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c  r [SQLITE_BUSY],
1f0f0 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e   .** [SQLITE_DON
1f100 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  E], [SQLITE_ROW]
1f110 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  , [SQLITE_ERROR]
1f120 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53  , or [SQLITE_MIS
1f130 55 53 45 5d 2e 0a 2a 2a 20 57 69 74 68 20 74 68  USE]..** With th
1f140 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
1f150 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f 74 68  , any of the oth
1f160 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c 20  er [SQLITE_OK | 
1f170 72 65 73 75 6c 74 20 63 6f 64 65 5d 0a 2a 2a 20  result code].** 
1f180 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  or [SQLITE_IOERR
1f190 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64  _READ | extended
1f1a0 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6d 69   result code] mi
1f1b0 67 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 20  ght be returned 
1f1c0 61 73 0a 2a 2a 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a  as.** well..**.*
1f1d0 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  * [SQLITE_BUSY] 
1f1e0 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 64  means that the d
1f1f0 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20 77  atabase engine w
1f200 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 63 71  as unable to acq
1f210 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 74 61  uire the.** data
1f220 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65  base locks it ne
1f230 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f  eds to do its jo
1f240 62 2e 20 20 49 66 20 74 68 65 20 73 74 61 74 65  b.  If the state
1f250 6d 65 6e 74 20 69 73 20 61 20 43 4f 4d 4d 49 54  ment is a COMMIT
1f260 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f 75  .** or occurs ou
1f270 74 73 69 64 65 20 6f 66 20 61 6e 20 65 78 70 6c  tside of an expl
1f280 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  icit transaction
1f290 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 6e 20 72  , then you can r
1f2a0 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 74 61 74  etry the.** stat
1f2b0 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 65 20 73  ement.  If the s
1f2c0 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20  tatement is not 
1f2d0 61 20 43 4f 4d 4d 49 54 20 61 6e 64 20 6f 63 63  a COMMIT and occ
1f2e0 75 72 73 20 77 69 74 68 69 6e 20 61 0a 2a 2a 20  urs within a.** 
1f2f0 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63  explicit transac
1f300 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73 68  tion then you sh
1f310 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68  ould rollback th
1f320 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65  e transaction be
1f330 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69  fore.** continui
1f340 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54  ng..**.** [SQLIT
1f350 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68  E_DONE] means th
1f360 61 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  at the statement
1f370 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 78   has finished ex
1f380 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65  ecuting.** succe
1f390 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65  ssfully.  sqlite
1f3a0 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20  3_step() should 
1f3b0 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67  not be called ag
1f3c0 61 69 6e 20 6f 6e 20 74 68 69 73 20 76 69 72 74  ain on this virt
1f3d0 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77  ual.** machine w
1f3e0 69 74 68 6f 75 74 20 66 69 72 73 74 20 63 61 6c  ithout first cal
1f3f0 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  ling [sqlite3_re
1f400 73 65 74 28 29 5d 20 74 6f 20 72 65 73 65 74 20  set()] to reset 
1f410 74 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d  the virtual.** m
1f420 61 63 68 69 6e 65 20 62 61 63 6b 20 74 6f 20 69  achine back to i
1f430 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65  ts initial state
1f440 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53  ..**.** If the S
1f450 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 62 65 69  QL statement bei
1f460 6e 67 20 65 78 65 63 75 74 65 64 20 72 65 74 75  ng executed retu
1f470 72 6e 73 20 61 6e 79 20 64 61 74 61 2c 20 74 68  rns any data, th
1f480 65 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 52  en .** [SQLITE_R
1f490 4f 57 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  OW] is returned 
1f4a0 65 61 63 68 20 74 69 6d 65 20 61 20 6e 65 77 20  each time a new 
1f4b0 72 6f 77 20 6f 66 20 64 61 74 61 20 69 73 20 72  row of data is r
1f4c0 65 61 64 79 0a 2a 2a 20 66 6f 72 20 70 72 6f 63  eady.** for proc
1f4d0 65 73 73 69 6e 67 20 62 79 20 74 68 65 20 63 61  essing by the ca
1f4e0 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c 75 65 73  ller. The values
1f4f0 20 6d 61 79 20 62 65 20 61 63 63 65 73 73 65 64   may be accessed
1f500 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73   using.** the [s
1f510 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e  qlite3_column_in
1f520 74 20 7c 20 63 6f 6c 75 6d 6e 20 61 63 63 65 73  t | column acces
1f530 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a  s functions]..**
1f540 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
1f550 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20  is called again 
1f560 74 6f 20 72 65 74 72 69 65 76 65 20 74 68 65 20  to retrieve the 
1f570 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61  next row of data
1f580 2e 0a 2a 2a 20 0a 2a 2a 20 5b 53 51 4c 49 54 45  ..** .** [SQLITE
1f590 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68  _ERROR] means th
1f5a0 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72  at a run-time er
1f5b0 72 6f 72 20 28 73 75 63 68 20 61 73 20 61 20 63  ror (such as a c
1f5c0 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f  onstraint.** vio
1f5d0 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75  lation) has occu
1f5e0 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73  rred.  sqlite3_s
1f5f0 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74  tep() should not
1f600 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e   be called again
1f610 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d   on.** the VM. M
1f620 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  ore information 
1f630 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20  may be found by 
1f640 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
1f650 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 57  _errmsg()]..** W
1f660 69 74 68 20 74 68 65 20 6c 65 67 61 63 79 20 69  ith the legacy i
1f670 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 65  nterface, a more
1f680 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20   specific error 
1f690 63 6f 64 65 20 28 65 78 61 6d 70 6c 65 3a 0a 2a  code (example:.*
1f6a0 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  * [SQLITE_INTERR
1f6b0 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43  UPT], [SQLITE_SC
1f6c0 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43  HEMA], [SQLITE_C
1f6d0 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20  ORRUPT], and so 
1f6e0 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65  forth).** can be
1f6f0 20 6f 62 74 61 69 6e 65 64 20 62 79 20 63 61 6c   obtained by cal
1f700 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  ling [sqlite3_re
1f710 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a  set()] on the.**
1f720 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1f730 6d 65 6e 74 5d 2e 20 20 49 6e 20 74 68 65 20 22  ment].  In the "
1f740 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a  v2" interface,.*
1f750 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69  * the more speci
1f760 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 69  fic error code i
1f770 73 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63  s returned direc
1f780 74 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 73  tly by sqlite3_s
1f790 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51  tep()..**.** [SQ
1f7a0 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61  LITE_MISUSE] mea
1f7b0 6e 73 20 74 68 61 74 20 74 68 65 20 74 68 69 73  ns that the this
1f7c0 20 72 6f 75 74 69 6e 65 20 77 61 73 20 63 61 6c   routine was cal
1f7d0 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 69 61 74  led inappropriat
1f7e0 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20  ely..** Perhaps 
1f7f0 69 74 20 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e  it was called on
1f800 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
1f810 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73  tement] that has
1f820 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62 65 65 6e  .** already been
1f830 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
1f840 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20  ze | finalized] 
1f850 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68  or on one that h
1f860 61 64 20 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  ad .** previousl
1f870 79 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49  y returned [SQLI
1f880 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51  TE_ERROR] or [SQ
1f890 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20  LITE_DONE].  Or 
1f8a0 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74  it could.** be t
1f8b0 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65  he case that the
1f8c0 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
1f8d0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62 65 69  onnection is bei
1f8e0 6e 67 20 75 73 65 64 20 62 79 20 74 77 6f 20 6f  ng used by two o
1f8f0 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61 64  r.** more thread
1f900 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 6d 6f  s at the same mo
1f910 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a  ment in time..**
1f920 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74  .** <b>Goofy Int
1f930 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62  erface Alert:</b
1f940 3e 0a 2a 2a 20 49 6e 20 74 68 65 20 6c 65 67 61  >.** In the lega
1f950 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 0a 2a  cy interface, .*
1f960 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74  * the sqlite3_st
1f970 65 70 28 29 20 41 50 49 20 61 6c 77 61 79 73 20  ep() API always 
1f980 72 65 74 75 72 6e 73 20 61 20 67 65 6e 65 72 69  returns a generi
1f990 63 20 65 72 72 6f 72 20 63 6f 64 65 2c 0a 2a 2a  c error code,.**
1f9a0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c   [SQLITE_ERROR],
1f9b0 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 65   following any e
1f9c0 72 72 6f 72 20 6f 74 68 65 72 20 74 68 61 6e 20  rror other than 
1f9d0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a  [SQLITE_BUSY].**
1f9e0 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53   and [SQLITE_MIS
1f9f0 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20  USE].  You must 
1fa00 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 72 65  call [sqlite3_re
1fa10 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  set()] or.** [sq
1fa20 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
1fa30 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69  ] in order to fi
1fa40 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 73 70  nd one of the sp
1fa50 65 63 69 66 69 63 0a 2a 2a 20 5b 65 72 72 6f 72  ecific.** [error
1fa60 20 63 6f 64 65 73 5d 20 74 68 61 74 20 62 65 74   codes] that bet
1fa70 74 65 72 20 64 65 73 63 72 69 62 65 73 20 74 68  ter describes th
1fa80 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61  e error..** We a
1fa90 64 6d 69 74 20 74 68 61 74 20 74 68 69 73 20 69  dmit that this i
1faa0 73 20 61 20 67 6f 6f 66 79 20 64 65 73 69 67 6e  s a goofy design
1fab0 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 68  .  The problem h
1fac0 61 73 20 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a  as been fixed.**
1fad0 20 77 69 74 68 20 74 68 65 20 22 76 32 22 20 69   with the "v2" i
1fae0 6e 74 65 72 66 61 63 65 2e 20 20 49 66 20 79 6f  nterface.  If yo
1faf0 75 20 70 72 65 70 61 72 65 20 61 6c 6c 20 6f 66  u prepare all of
1fb00 20 79 6f 75 72 20 53 51 4c 20 73 74 61 74 65 6d   your SQL statem
1fb10 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69  ents.** using ei
1fb20 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ther [sqlite3_pr
1fb30 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b  epare_v2()] or [
1fb40 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1fb50 36 5f 76 32 28 29 5d 20 69 6e 73 74 65 61 64 0a  6_v2()] instead.
1fb60 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79  ** of the legacy
1fb70 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1fb80 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
1fb90 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20  3_prepare16()], 
1fba0 74 68 65 6e 20 74 68 65 20 0a 2a 2a 20 6d 6f 72  then the .** mor
1fbb0 65 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f  e specific [erro
1fbc0 72 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74  r codes] are ret
1fbd0 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a  urned directly.*
1fbe0 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65  * by sqlite3_ste
1fbf0 70 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66  p().  The use of
1fc00 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
1fc10 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64  ace is recommend
1fc20 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  ed..**.** INVARI
1fc30 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  ANTS:.**.** {F13
1fc40 32 30 32 7d 20 20 49 66 20 5b 70 72 65 70 61 72  202}  If [prepar
1fc50 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
1fc60 69 73 20 72 65 61 64 79 20 74 6f 20 62 65 0a 2a  is ready to be.*
1fc70 2a 20 20 20 20 20 20 20 20 20 20 20 72 75 6e 2c  *           run,
1fc80 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 73   then [sqlite3_s
1fc90 74 65 70 28 53 29 5d 20 61 64 76 61 6e 63 65 73  tep(S)] advances
1fca0 20 74 68 61 74 20 70 72 65 70 61 72 65 64 20 73   that prepared s
1fcb0 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 20 20 20 20  tatement.**     
1fcc0 20 20 20 20 20 20 75 6e 74 69 6c 20 74 6f 20 63        until to c
1fcd0 6f 6d 70 6c 65 74 69 6f 6e 20 6f 72 20 75 6e 74  ompletion or unt
1fce0 69 6c 20 69 74 20 69 73 20 72 65 61 64 79 20 74  il it is ready t
1fcf0 6f 20 72 65 74 75 72 6e 20 61 6e 6f 74 68 65 72  o return another
1fd00 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72 6f  .**           ro
1fd10 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  w of the result 
1fd20 73 65 74 20 6f 72 20 61 6e 20 69 6e 74 65 72 72  set or an interr
1fd30 75 70 74 20 6f 72 20 72 75 6e 2d 74 69 6d 65 20  upt or run-time 
1fd40 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a  error occurs..**
1fd50 0a 2a 2a 20 7b 46 31 35 33 30 34 7d 20 20 57 68  .** {F15304}  Wh
1fd60 65 6e 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71  en a call to [sq
1fd70 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 63  lite3_step(S)] c
1fd80 61 75 73 65 73 20 74 68 65 20 0a 2a 2a 20 20 20  auses the .**   
1fd90 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65          [prepare
1fda0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 74  d statement] S t
1fdb0 6f 20 72 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74  o run to complet
1fdc0 69 6f 6e 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ion,.**         
1fdd0 20 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 72    the function r
1fde0 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44  eturns [SQLITE_D
1fdf0 4f 4e 45 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35  ONE]..**.** {F15
1fe00 33 30 36 7d 20 20 57 68 65 6e 20 61 20 63 61 6c  306}  When a cal
1fe10 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
1fe20 65 70 28 53 29 5d 20 73 74 6f 70 73 20 62 65 63  ep(S)] stops bec
1fe30 61 75 73 65 20 69 74 20 69 73 20 72 65 61 64 79  ause it is ready
1fe40 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 6f  .**           to
1fe50 20 72 65 74 75 72 6e 20 61 6e 6f 74 68 65 72 20   return another 
1fe60 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c  row of the resul
1fe70 74 20 73 65 74 2c 20 69 74 20 72 65 74 75 72 6e  t set, it return
1fe80 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b  s.**           [
1fe90 53 51 4c 49 54 45 5f 52 4f 57 5d 2e 0a 2a 2a 0a  SQLITE_ROW]..**.
1fea0 2a 2a 20 7b 46 31 35 33 30 38 7d 20 20 49 66 20  ** {F15308}  If 
1feb0 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  a call to [sqlit
1fec0 65 33 5f 73 74 65 70 28 53 29 5d 20 65 6e 63 6f  e3_step(S)] enco
1fed0 75 6e 74 65 72 73 20 61 6e 0a 2a 2a 20 20 20 20  unters an.**    
1fee0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
1fef0 69 6e 74 65 72 72 75 70 74 7c 69 6e 74 65 72 72  interrupt|interr
1ff00 75 70 74 5d 20 6f 72 20 61 20 72 75 6e 2d 74 69  upt] or a run-ti
1ff10 6d 65 20 65 72 72 6f 72 2c 0a 2a 2a 20 20 20 20  me error,.**    
1ff20 20 20 20 20 20 20 20 69 74 20 72 65 74 75 72 6e         it return
1ff30 73 20 61 6e 20 61 70 70 72 6f 70 72 61 69 74 65  s an appropraite
1ff40 20 65 72 72 6f 72 20 63 6f 64 65 20 74 68 61 74   error code that
1ff50 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 0a 2a   is not one of.*
1ff60 2a 20 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c  *           [SQL
1ff70 49 54 45 5f 4f 4b 5d 2c 20 5b 53 51 4c 49 54 45  ITE_OK], [SQLITE
1ff80 5f 52 4f 57 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  _ROW], or [SQLIT
1ff90 45 5f 44 4f 4e 45 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  E_DONE]..**.** {
1ffa0 46 31 35 33 31 30 7d 20 20 49 66 20 61 6e 20 5b  F15310}  If an [
1ffb0 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
1ffc0 74 7c 69 6e 74 65 72 72 75 70 74 5d 20 6f 72 20  t|interrupt] or 
1ffd0 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 0a 2a  run-time error.*
1ffe0 2a 20 20 20 20 20 20 20 20 20 20 20 6f 63 63 75  *           occu
1fff0 72 73 20 64 75 72 69 6e 67 20 61 20 63 61 6c 6c  rs during a call
20000 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
20010 70 28 53 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  p(S)].**        
20020 20 20 20 66 6f 72 20 61 20 5b 70 72 65 70 61 72     for a [prepar
20030 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
20040 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a  created using.**
20050 20 20 20 20 20 20 20 20 20 20 20 6c 65 67 61 63             legac
20060 79 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71  y interfaces [sq
20070 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
20080 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   or.**          
20090 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
200a0 65 31 36 28 29 5d 20 74 68 65 6e 20 74 68 65 20  e16()] then the 
200b0 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
200c0 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20   either.**      
200d0 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 45 52 52       [SQLITE_ERR
200e0 4f 52 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53  OR], [SQLITE_BUS
200f0 59 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d  Y], or [SQLITE_M
20100 49 53 55 53 45 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  ISUSE]..*/.int s
20110 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69  qlite3_step(sqli
20120 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
20130 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d  ** CAPI3REF: Num
20140 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
20150 6e 20 61 20 72 65 73 75 6c 74 20 73 65 74 20 7b  n a result set {
20160 46 31 33 37 37 30 7d 0a 2a 2a 0a 2a 2a 20 52 65  F13770}.**.** Re
20170 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20  turn the number 
20180 6f 66 20 76 61 6c 75 65 73 20 69 6e 20 74 68 65  of values in the
20190 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20   current row of 
201a0 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 2e 0a  the result set..
201b0 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
201c0 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 37 31 7d  :.**.** {F13771}
201d0 20 20 41 66 74 65 72 20 61 20 63 61 6c 6c 20 74    After a call t
201e0 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
201f0 53 29 5d 20 74 68 61 74 20 72 65 74 75 72 6e 73  S)] that returns
20200 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 53  .**           [S
20210 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20  QLITE_ROW], the 
20220 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f  [sqlite3_data_co
20230 75 6e 74 28 53 29 5d 20 72 6f 75 74 69 6e 65 0a  unt(S)] routine.
20240 2a 2a 20 20 20 20 20 20 20 20 20 20 20 77 69 6c  **           wil
20250 6c 20 72 65 74 75 72 6e 20 74 68 65 20 73 61 6d  l return the sam
20260 65 20 76 61 6c 75 65 20 61 73 20 74 68 65 0a 2a  e value as the.*
20270 2a 20 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  *           [sql
20280 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e  ite3_column_coun
20290 74 28 53 29 5d 20 66 75 6e 63 74 69 6f 6e 2e 0a  t(S)] function..
202a0 2a 2a 0a 2a 2a 20 7b 46 31 33 37 37 32 7d 20 20  **.** {F13772}  
202b0 41 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73  After [sqlite3_s
202c0 74 65 70 28 53 29 5d 20 68 61 73 20 72 65 74 75  tep(S)] has retu
202d0 72 6e 65 64 20 61 6e 79 20 76 61 6c 75 65 20 6f  rned any value o
202e0 74 68 65 72 20 74 68 61 6e 0a 2a 2a 20 20 20 20  ther than.**    
202f0 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 52         [SQLITE_R
20300 4f 57 5d 20 6f 72 20 62 65 66 6f 72 65 20 5b 73  OW] or before [s
20310 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
20320 68 61 73 20 62 65 65 6e 20 0a 2a 2a 20 20 20 20  has been .**    
20330 20 20 20 20 20 20 20 63 61 6c 6c 65 64 20 6f 6e         called on
20340 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
20350 74 61 74 65 6d 65 6e 74 5d 20 66 6f 72 0a 2a 2a  tatement] for.**
20360 20 20 20 20 20 20 20 20 20 20 20 74 68 65 20 66             the f
20370 69 72 73 74 20 74 69 6d 65 20 73 69 6e 63 65 20  irst time since 
20380 69 74 20 77 61 73 20 5b 73 71 6c 69 74 65 33 5f  it was [sqlite3_
20390 70 72 65 70 61 72 65 7c 70 72 65 70 61 72 65 64  prepare|prepared
203a0 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6f  ].**           o
203b0 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  r [sqlite3_reset
203c0 7c 72 65 73 65 74 5d 2c 20 74 68 65 20 5b 73 71  |reset], the [sq
203d0 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
203e0 28 53 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  (S)].**         
203f0 20 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e    routine return
20400 73 20 7a 65 72 6f 2e 0a 2a 2f 0a 69 6e 74 20 73  s zero..*/.int s
20410 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
20420 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  t(sqlite3_stmt *
20430 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
20440 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65  API3REF: Fundame
20450 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73 20 7b  ntal Datatypes {
20460 46 31 30 32 36 35 7d 0a 2a 2a 20 4b 45 59 57 4f  F10265}.** KEYWO
20470 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 54  RDS: SQLITE_TEXT
20480 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 32 36 36 7d 45  .**.** {F10266}E
20490 76 65 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51  very value in SQ
204a0 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20  Lite has one of 
204b0 66 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c  five fundamental
204c0 20 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a   datatypes:.**.*
204d0 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36  * <ul>.** <li> 6
204e0 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  4-bit signed int
204f0 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d  eger.** <li> 64-
20500 62 69 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e  bit IEEE floatin
20510 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a  g point number.*
20520 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a  * <li> string.**
20530 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c   <li> BLOB.** <l
20540 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e  i> NULL.** </ul>
20550 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65   {END}.**.** The
20560 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  se constants are
20570 20 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68 20   codes for each 
20580 6f 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e 0a  of those types..
20590 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
205a0 74 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20  the SQLITE_TEXT 
205b0 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c 73  constant was als
205c0 6f 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74 65  o used in SQLite
205d0 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f   version 2.** fo
205e0 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64  r a completely d
205f0 69 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67  ifferent meaning
20600 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74  .  Software that
20610 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 62   links against b
20620 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65  oth.** SQLite ve
20630 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69  rsion 2 and SQLi
20640 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68 6f  te version 3 sho
20650 75 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33 5f  uld use SQLITE3_
20660 54 45 58 54 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49  TEXT not.** SQLI
20670 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66  TE_TEXT..*/.#def
20680 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 47  ine SQLITE_INTEG
20690 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51  ER  1.#define SQ
206a0 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a  LITE_FLOAT    2.
206b0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42  #define SQLITE_B
206c0 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66 69 6e  LOB     4.#defin
206d0 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20  e SQLITE_NULL   
206e0 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c 49 54    5.#ifdef SQLIT
206f0 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66 20 53  E_TEXT.# undef S
20700 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 65  QLITE_TEXT.#else
20710 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45  .# define SQLITE
20720 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65 6e 64  _TEXT     3.#end
20730 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  if.#define SQLIT
20740 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a 0a 2f  E3_TEXT     3../
20750 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
20760 65 73 75 6c 74 73 20 56 61 6c 75 65 73 20 46 72  esults Values Fr
20770 6f 6d 20 41 20 51 75 65 72 79 20 7b 46 31 33 38  om A Query {F138
20780 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  00}.**.** These 
20790 72 6f 75 74 69 6e 65 73 20 66 6f 72 6d 20 74 68  routines form th
207a0 65 20 22 72 65 73 75 6c 74 20 73 65 74 20 71 75  e "result set qu
207b0 65 72 79 22 20 69 6e 74 65 72 66 61 63 65 2e 0a  ery" interface..
207c0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
207d0 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f  ines return info
207e0 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 0a 2a 2a  rmation about.**
207f0 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e   a single column
20800 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 20   of the current 
20810 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20  result row of a 
20820 71 75 65 72 79 2e 20 20 49 6e 20 65 76 65 72 79  query.  In every
20830 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 66 69 72  .** case the fir
20840 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  st argument is a
20850 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
20860 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
20870 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 73  atement] that is
20880 20 62 65 69 6e 67 0a 2a 2a 20 65 76 61 6c 75 61   being.** evalua
20890 74 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65  ted (the [sqlite
208a0 33 5f 73 74 6d 74 2a 5d 20 74 68 61 74 20 77 61  3_stmt*] that wa
208b0 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20  s returned from 
208c0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
208d0 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e  pare_v2()] or on
208e0 65 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74  e of its variant
208f0 73 29 20 61 6e 64 0a 2a 2a 20 74 68 65 20 73 65  s) and.** the se
20900 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
20910 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68   the index of th
20920 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69  e column for whi
20930 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 0a  ch information .
20940 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74  ** should be ret
20950 75 72 6e 65 64 2e 20 20 54 68 65 20 6c 65 66 74  urned.  The left
20960 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20  -most column of 
20970 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 0a 2a  the result set.*
20980 2a 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f  * has an index o
20990 66 20 30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  f 0..**.** If th
209a0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
209b0 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79  is not currently
209c0 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69   point to a vali
209d0 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65  d row, or if the
209e0 0a 2a 2a 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69  .** the column i
209f0 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72  ndex is out of r
20a00 61 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c 74  ange, the result
20a10 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 0a   is undefined. .
20a20 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
20a30 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61  s may only be ca
20a40 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f  lled when the mo
20a50 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74  st recent call t
20a60 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74  o.** [sqlite3_st
20a70 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e  ep()] has return
20a80 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20  ed [SQLITE_ROW] 
20a90 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b  and neither.** [
20aa0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
20ab0 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69   nor [sqlite3_fi
20ac0 6e 61 6c 69 7a 65 28 29 5d 20 68 61 73 20 62 65  nalize()] has be
20ad0 65 6e 20 63 61 6c 6c 20 73 75 62 73 65 71 75 65  en call subseque
20ae0 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20  ntly..** If any 
20af0 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
20b00 73 20 61 72 65 20 63 61 6c 6c 65 64 20 61 66 74  s are called aft
20b10 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  er [sqlite3_rese
20b20 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  t()] or.** [sqli
20b30 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
20b40 6f 72 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65  or after [sqlite
20b50 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65  3_step()] has re
20b60 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68  turned.** someth
20b70 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  ing other than [
20b80 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65  SQLITE_ROW], the
20b90 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
20ba0 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73  efined..** If [s
20bb0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f  qlite3_step()] o
20bc0 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  r [sqlite3_reset
20bd0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
20be0 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61  finalize()].** a
20bf0 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61  re called from a
20c00 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61   different threa
20c10 64 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 74  d while any of t
20c20 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a  hese routines.**
20c30 20 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 68   are pending, th
20c40 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  en the results a
20c50 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 0a  re undefined.  .
20c60 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
20c70 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20  3_column_type() 
20c80 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
20c90 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  .** [SQLITE_INTE
20ca0 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 20 63  GER | datatype c
20cb0 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 69 6e 69  ode] for the ini
20cc0 74 69 61 6c 20 64 61 74 61 20 74 79 70 65 0a 2a  tial data type.*
20cd0 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  * of the result 
20ce0 63 6f 6c 75 6d 6e 2e 20 20 54 68 65 20 72 65 74  column.  The ret
20cf0 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73 20 6f  urned value is o
20d00 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e  ne of [SQLITE_IN
20d10 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  TEGER],.** [SQLI
20d20 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49  TE_FLOAT], [SQLI
20d30 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54  TE_TEXT], [SQLIT
20d40 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c  E_BLOB], or [SQL
20d50 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20  ITE_NULL].  The 
20d60 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65  value.** returne
20d70 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
20d80 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 6f 6e  umn_type() is on
20d90 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66  ly meaningful if
20da0 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76   no type.** conv
20db0 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f 63 63  ersions have occ
20dc0 75 72 72 65 64 20 61 73 20 64 65 73 63 72 69 62  urred as describ
20dd0 65 64 20 62 65 6c 6f 77 2e 20 20 41 66 74 65 72  ed below.  After
20de0 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69   a type conversi
20df0 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65  on,.** the value
20e00 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
20e10 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
20e20 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  () is undefined.
20e30 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73    Future.** vers
20e40 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ions of SQLite m
20e50 61 79 20 63 68 61 6e 67 65 20 74 68 65 20 62 65  ay change the be
20e60 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65  havior of sqlite
20e70 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a  3_column_type().
20e80 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74  ** following a t
20e90 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a  ype conversion..
20ea0 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 73  **.** If the res
20eb0 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72  ult is a BLOB or
20ec0 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68   UTF-8 string th
20ed0 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  en the sqlite3_c
20ee0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 0a 2a  olumn_bytes() .*
20ef0 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  * routine return
20f00 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
20f10 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c  bytes in that BL
20f20 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a  OB or string..**
20f30 20 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69   If the result i
20f40 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e  s a UTF-16 strin
20f50 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  g, then sqlite3_
20f60 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 63  column_bytes() c
20f70 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73  onverts.** the s
20f80 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 38 20 61  tring to UTF-8 a
20f90 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20  nd then returns 
20fa0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
20fb0 74 65 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 72  tes..** If the r
20fc0 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72  esult is a numer
20fd0 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71  ic value then sq
20fe0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
20ff0 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71  es() uses.** [sq
21000 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
21010 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61  ] to convert tha
21020 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46  t value to a UTF
21030 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65  -8 string and re
21040 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d  turns.** the num
21050 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
21060 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20  that string..** 
21070 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  The value return
21080 65 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c  ed does not incl
21090 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65 72  ude the zero ter
210a0 6d 69 6e 61 74 6f 72 20 61 74 20 74 68 65 20 65  minator at the e
210b0 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72  nd.** of the str
210c0 69 6e 67 2e 20 20 46 6f 72 20 63 6c 61 72 69 74  ing.  For clarit
210d0 79 3a 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  y: the value ret
210e0 75 72 6e 65 64 20 69 73 20 74 68 65 20 6e 75 6d  urned is the num
210f0 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20  ber of.** bytes 
21100 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e  in the string, n
21110 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ot the number of
21120 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a   characters..**.
21130 2a 2a 20 53 74 72 69 6e 67 73 20 72 65 74 75 72  ** Strings retur
21140 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
21150 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64  olumn_text() and
21160 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
21170 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65  text16(),.** eve
21180 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c  n empty strings,
21190 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f   are always zero
211a0 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 54 68   terminated.  Th
211b0 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75  e return.** valu
211c0 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63  e from sqlite3_c
211d0 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72  olumn_blob() for
211e0 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 62   a zero-length b
211f0 6c 6f 62 20 69 73 20 61 6e 20 61 72 62 69 74 72  lob is an arbitr
21200 61 72 79 0a 2a 2a 20 70 6f 69 6e 74 65 72 2c 20  ary.** pointer, 
21210 70 6f 73 73 69 62 6c 79 20 65 76 65 6e 20 61 20  possibly even a 
21220 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
21230 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
21240 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
21250 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69   routine is simi
21260 6c 61 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lar to sqlite3_c
21270 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a  olumn_bytes().**
21280 20 62 75 74 20 6c 65 61 76 65 73 20 74 68 65 20   but leaves the 
21290 72 65 73 75 6c 74 20 69 6e 20 55 54 46 2d 31 36  result in UTF-16
212a0 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20   in native byte 
212b0 6f 72 64 65 72 20 69 6e 73 74 65 61 64 20 6f 66  order instead of
212c0 20 55 54 46 2d 38 2e 20 20 0a 2a 2a 20 54 68 65   UTF-8.  .** The
212d0 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
212e0 20 69 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 64   is not included
212f0 20 69 6e 20 74 68 69 73 20 63 6f 75 6e 74 2e 0a   in this count..
21300 2a 2a 0a 2a 2a 20 54 68 65 20 6f 62 6a 65 63 74  **.** The object
21310 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
21320 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
21330 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b  ue()] is an.** [
21340 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
21350 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
21360 74 2e 20 20 41 6e 20 75 6e 70 72 6f 74 65 63 74  t.  An unprotect
21370 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
21380 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 6f   object.** may o
21390 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68  nly be used with
213a0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76   [sqlite3_bind_v
213b0 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  alue()] and [sql
213c0 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
213d0 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20  e()]..** If the 
213e0 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
213f0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
21400 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  ct returned by.*
21410 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
21420 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 73  n_value()] is us
21430 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20  ed in any other 
21440 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63  way, including c
21450 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69  alls.** to routi
21460 6e 65 73 20 6c 69 6b 65 20 0a 2a 2a 20 5b 73 71  nes like .** [sq
21470 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28  lite3_value_int(
21480 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  )], [sqlite3_val
21490 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72 20 5b  ue_text()], or [
214a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
214b0 74 65 73 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20  tes()],.** then 
214c0 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
214d0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
214e0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
214f0 61 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65  attempt to conve
21500 72 74 20 74 68 65 20 76 61 6c 75 65 20 77 68 65  rt the value whe
21510 72 65 20 61 70 70 72 6f 70 72 69 61 74 65 2e 20  re appropriate. 
21520 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c   For.** example,
21530 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c   if the internal
21540 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20   representation 
21550 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74  is FLOAT and a t
21560 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73  ext result.** is
21570 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c   requested, [sql
21580 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
21590 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61   is used interna
215a0 6c 6c 79 20 74 6f 20 64 6f 20 74 68 65 20 63 6f  lly to do the co
215b0 6e 76 65 72 73 69 6f 6e 0a 2a 2a 20 61 75 74 6f  nversion.** auto
215c0 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54 68 65 20  matically.  The 
215d0 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20  following table 
215e0 64 65 74 61 69 6c 73 20 74 68 65 20 63 6f 6e 76  details the conv
215f0 65 72 73 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20  ersions that.** 
21600 61 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a  are applied:.**.
21610 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  ** <blockquote>.
21620 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72  ** <table border
21630 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68  ="1">.** <tr><th
21640 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79  > Internal<br>Ty
21650 70 65 20 3c 74 68 3e 20 52 65 71 75 65 73 74 65  pe <th> Requeste
21660 64 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20  d<br>Type <th>  
21670 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a  Conversion.**.**
21680 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
21690 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
216a0 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
216b0 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20   0.** <tr><td>  
216c0 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c  NULL    <td>  FL
216d0 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75  OAT    <td> Resu
216e0 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72  lt is 0.0.** <tr
216f0 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
21700 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
21710 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c  d> Result is NUL
21720 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72  L pointer.** <tr
21730 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
21740 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
21750 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c  d> Result is NUL
21760 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72  L pointer.** <tr
21770 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c  ><td> INTEGER  <
21780 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
21790 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20  d> Convert from 
217a0 69 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 74  integer to float
217b0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54  .** <tr><td> INT
217c0 45 47 45 52 20 20 3c 74 64 3e 20 20 20 54 45 58  EGER  <td>   TEX
217d0 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20  T    <td> ASCII 
217e0 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65  rendering of the
217f0 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e   integer.** <tr>
21800 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74  <td> INTEGER  <t
21810 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
21820 3e 20 53 61 6d 65 20 61 73 20 66 6f 72 20 49 4e  > Same as for IN
21830 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c  TEGER->TEXT.** <
21840 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  tr><td>  FLOAT  
21850 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
21860 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f  <td> Convert fro
21870 6d 20 66 6c 6f 61 74 20 74 6f 20 69 6e 74 65 67  m float to integ
21880 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  er.** <tr><td>  
21890 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 54  FLOAT   <td>   T
218a0 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49  EXT    <td> ASCI
218b0 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74  I rendering of t
218c0 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e  he float.** <tr>
218d0 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74  <td>  FLOAT   <t
218e0 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
218f0 3e 20 53 61 6d 65 20 61 73 20 46 4c 4f 41 54 2d  > Same as FLOAT-
21900 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64  >TEXT.** <tr><td
21910 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20  >  TEXT    <td> 
21920 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 55  INTEGER   <td> U
21930 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72  se atoi().** <tr
21940 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c  ><td>  TEXT    <
21950 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
21960 64 3e 20 55 73 65 20 61 74 6f 66 28 29 0a 2a 2a  d> Use atof().**
21970 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20   <tr><td>  TEXT 
21980 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20     <td>   BLOB  
21990 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65    <td> No change
219a0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c  .** <tr><td>  BL
219b0 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  OB    <td> INTEG
219c0 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72  ER   <td> Conver
219d0 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75  t to TEXT then u
219e0 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72  se atoi().** <tr
219f0 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c  ><td>  BLOB    <
21a00 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
21a10 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45  d> Convert to TE
21a20 58 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f 66  XT then use atof
21a30 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ().** <tr><td>  
21a40 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 54  BLOB    <td>   T
21a50 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64 20  EXT    <td> Add 
21a60 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  a zero terminato
21a70 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c  r if needed.** <
21a80 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f  /table>.** </blo
21a90 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
21aa0 68 65 20 74 61 62 6c 65 20 61 62 6f 76 65 20 6d  he table above m
21ab0 61 6b 65 73 20 72 65 66 65 72 65 6e 63 65 20 74  akes reference t
21ac0 6f 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  o standard C lib
21ad0 72 61 72 79 20 66 75 6e 63 74 69 6f 6e 73 20 61  rary functions a
21ae0 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74 6f  toi().** and ato
21af0 66 28 29 2e 20 20 53 51 4c 69 74 65 20 64 6f 65  f().  SQLite doe
21b00 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73 65  s not really use
21b10 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
21b20 2e 20 20 49 74 20 68 61 73 20 69 74 73 0a 2a 2a  .  It has its.**
21b30 20 6f 6e 20 65 71 75 61 76 61 6c 65 6e 74 20 69   on equavalent i
21b40 6e 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e 65 73  nternal routines
21b50 2e 20 20 54 68 65 20 61 74 6f 69 28 29 20 61 6e  .  The atoi() an
21b60 64 20 61 74 6f 66 28 29 20 6e 61 6d 65 73 20 61  d atof() names a
21b70 72 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20 74 68  re.** used in th
21b80 65 20 74 61 62 6c 65 20 66 6f 72 20 62 72 65 76  e table for brev
21b90 69 74 79 20 61 6e 64 20 62 65 63 61 75 73 65 20  ity and because 
21ba0 74 68 65 79 20 61 72 65 20 66 61 6d 69 6c 69 61  they are familia
21bb0 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20 70  r to most.** C p
21bc0 72 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a  rogrammers..**.*
21bd0 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e  * Note that when
21be0 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
21bf0 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72  s occur, pointer
21c00 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 70 72  s returned by pr
21c10 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20  ior.** calls to 
21c20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
21c30 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63  lob(), sqlite3_c
21c40 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e  olumn_text(), an
21c50 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  d/or.** sqlite3_
21c60 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
21c70 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74  may be invalidat
21c80 65 64 2e 20 0a 2a 2a 20 54 79 70 65 20 63 6f 6e  ed. .** Type con
21c90 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69  versions and poi
21ca0 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f  nter invalidatio
21cb0 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a  ns might occur.*
21cc0 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69  * in the followi
21cd0 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20  ng cases:.**.** 
21ce0 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 3c 70 3e 20  <ul>.** <li><p> 
21cf0 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e   The initial con
21d00 74 65 6e 74 20 69 73 20 61 20 42 4c 4f 42 20 61  tent is a BLOB a
21d10 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
21d20 6e 5f 74 65 78 74 28 29 20 0a 2a 2a 20 20 20 20  n_text() .**    
21d30 20 20 20 20 20 20 6f 72 20 73 71 6c 69 74 65 33        or sqlite3
21d40 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
21d50 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a   is called.  A z
21d60 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d  ero-terminator m
21d70 69 67 68 74 0a 2a 2a 20 20 20 20 20 20 20 20 20  ight.**         
21d80 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64 65   need to be adde
21d90 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67 2e  d to the string.
21da0 3c 2f 70 3e 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20  </p></li>.**.** 
21db0 3c 6c 69 3e 3c 70 3e 20 20 54 68 65 20 69 6e 69  <li><p>  The ini
21dc0 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20  tial content is 
21dd0 55 54 46 2d 38 20 74 65 78 74 20 61 6e 64 20 73  UTF-8 text and s
21de0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
21df0 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20  tes16() or.**   
21e00 20 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63         sqlite3_c
21e10 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69  olumn_text16() i
21e20 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63  s called.  The c
21e30 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63  ontent must be c
21e40 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20  onverted.**     
21e50 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c       to UTF-16.<
21e60 2f 70 3e 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c  /p></li>.**.** <
21e70 6c 69 3e 3c 70 3e 20 20 54 68 65 20 69 6e 69 74  li><p>  The init
21e80 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55  ial content is U
21e90 54 46 2d 31 36 20 74 65 78 74 20 61 6e 64 20 73  TF-16 text and s
21ea0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
21eb0 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20  tes() or.**     
21ec0 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c       sqlite3_col
21ed0 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61  umn_text() is ca
21ee0 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65  lled.  The conte
21ef0 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65  nt must be conve
21f00 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  rted.**         
21f10 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 70 3e 3c 2f   to UTF-8.</p></
21f20 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  li>.** </ul>.**.
21f30 2a 2a 20 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62  ** Conversions b
21f40 65 74 77 65 65 6e 20 55 54 46 2d 31 36 62 65 20  etween UTF-16be 
21f50 61 6e 64 20 55 54 46 2d 31 36 6c 65 20 61 72 65  and UTF-16le are
21f60 20 61 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e 20   always done in 
21f70 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20  place and do.** 
21f80 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74 65 20 61  not invalidate a
21f90 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20   prior pointer, 
21fa0 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 65  though of course
21fb0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
21fc0 74 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 74 68  the buffer.** th
21fd0 61 74 20 74 68 65 20 70 72 69 6f 72 20 70 6f 69  at the prior poi
21fe0 6e 74 65 72 20 70 6f 69 6e 74 73 20 74 6f 20 77  nter points to w
21ff0 69 6c 6c 20 68 61 76 65 20 62 65 65 6e 20 6d 6f  ill have been mo
22000 64 69 66 69 65 64 2e 20 20 4f 74 68 65 72 20 6b  dified.  Other k
22010 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65  inds.** of conve
22020 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69  rsion are done i
22030 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 69 74 20  n place when it 
22040 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 62 75 74  is possible, but
22050 20 73 6f 6d 65 74 69 6d 65 20 69 74 20 69 73 0a   sometime it is.
22060 2a 2a 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  ** not possible 
22070 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73  and in those cas
22080 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72  es prior pointer
22090 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65  s are invalidate
220a0 64 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  d.  .**.** The s
220b0 61 66 65 73 74 20 61 6e 64 20 65 61 73 69 65 73  afest and easies
220c0 74 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 70 6f  t to remember po
220d0 6c 69 63 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b  licy is to invok
220e0 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  e these routines
220f0 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68  .** in one of th
22100 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73  e following ways
22110 3a 0a 2a 2a 0a 2a 2a 20 20 3c 75 6c 3e 0a 2a 2a  :.**.**  <ul>.**
22120 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f    <li>sqlite3_co
22130 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c  lumn_text() foll
22140 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  owed by sqlite3_
22150 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f  column_bytes()</
22160 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69  li>.**  <li>sqli
22170 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
22180 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71  ) followed by sq
22190 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
221a0 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c  es()</li>.**  <l
221b0 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  i>sqlite3_column
221c0 5f 74 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77  _text16() follow
221d0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
221e0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f  lumn_bytes16()</
221f0 6c 69 3e 0a 2a 2a 20 20 3c 2f 75 6c 3e 0a 2a 2a  li>.**  </ul>.**
22200 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  .** In other wor
22210 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20 63  ds, you should c
22220 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  all sqlite3_colu
22230 6d 6e 5f 74 65 78 74 28 29 2c 20 73 71 6c 69 74  mn_text(), sqlit
22240 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
22250 2c 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  ,.** or sqlite3_
22260 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
22270 66 69 72 73 74 20 74 6f 20 66 6f 72 63 65 20 74  first to force t
22280 68 65 20 72 65 73 75 6c 74 20 69 6e 74 6f 20 74  he result into t
22290 68 65 20 64 65 73 69 72 65 64 0a 2a 2a 20 66 6f  he desired.** fo
222a0 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b  rmat, then invok
222b0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
222c0 5f 62 79 74 65 73 28 29 20 6f 72 20 73 71 6c 69  _bytes() or sqli
222d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
222e0 31 36 28 29 20 74 6f 0a 2a 2a 20 66 69 6e 64 20  16() to.** find 
222f0 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
22300 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20  result.  Do not 
22310 6d 69 78 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  mix call to sqli
22320 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
22330 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ) or.** sqlite3_
22340 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69  column_blob() wi
22350 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  th calls to sqli
22360 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
22370 31 36 28 29 2e 20 20 41 6e 64 20 64 6f 20 6e 6f  16().  And do no
22380 74 0a 2a 2a 20 6d 69 78 20 63 61 6c 6c 73 20 74  t.** mix calls t
22390 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
223a0 5f 74 65 78 74 31 36 28 29 20 77 69 74 68 20 63  _text16() with c
223b0 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
223c0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a  column_bytes()..
223d0 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65  **.** The pointe
223e0 72 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20  rs returned are 
223f0 76 61 6c 69 64 20 75 6e 74 69 6c 20 61 20 74 79  valid until a ty
22400 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63  pe conversion oc
22410 63 75 72 73 20 61 73 0a 2a 2a 20 64 65 73 63 72  curs as.** descr
22420 69 62 65 64 20 61 62 6f 76 65 2c 20 6f 72 20 75  ibed above, or u
22430 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74  ntil [sqlite3_st
22440 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ep()] or [sqlite
22450 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a  3_reset()] or.**
22460 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
22470 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e  ze()] is called.
22480 20 20 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 61    The memory spa
22490 63 65 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20  ce used to hold 
224a0 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 62  strings.** and b
224b0 6c 6f 62 73 20 69 73 20 66 72 65 65 64 20 61 75  lobs is freed au
224c0 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f  tomatically.  Do
224d0 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 73   <b>not</b> pass
224e0 20 74 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65   the pointers re
224f0 74 75 72 6e 65 64 0a 2a 2a 20 5b 73 71 6c 69 74  turned.** [sqlit
22500 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
22510 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ], [sqlite3_colu
22520 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 2e  mn_text()], etc.
22530 20 69 6e 74 6f 20 0a 2a 2a 20 5b 73 71 6c 69 74   into .** [sqlit
22540 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a  e3_free()]..**.*
22550 2a 20 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c  * If a memory al
22560 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f  location error o
22570 63 63 75 72 73 20 64 75 72 69 6e 67 20 74 68 65  ccurs during the
22580 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61   evaluation of a
22590 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 72  ny.** of these r
225a0 6f 75 74 69 6e 65 73 2c 20 61 20 64 65 66 61 75  outines, a defau
225b0 6c 74 20 76 61 6c 75 65 20 69 73 20 72 65 74 75  lt value is retu
225c0 72 6e 65 64 2e 20 20 54 68 65 20 64 65 66 61 75  rned.  The defau
225d0 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65  lt value.** is e
225e0 69 74 68 65 72 20 74 68 65 20 69 6e 74 65 67 65  ither the intege
225f0 72 20 30 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e  r 0, the floatin
22600 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30  g point number 0
22610 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a  .0, or a NULL.**
22620 20 70 6f 69 6e 74 65 72 2e 20 20 53 75 62 73 65   pointer.  Subse
22630 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b  quent calls to [
22640 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
22650 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a  )] will return.*
22660 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d  * [SQLITE_NOMEM]
22670 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
22680 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 30  TS:.**.** {F1380
22690 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  3} The [sqlite3_
226a0 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 53 2c 4e 29  column_blob(S,N)
226b0 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76  ] interface conv
226c0 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  erts the.**     
226d0 20 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20       Nth column 
226e0 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72  in the current r
226f0 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ow of the result
22700 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20   set for.**     
22710 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73       [prepared s
22720 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f  tatement] S into
22730 20 61 20 62 6c 6f 62 20 61 6e 64 20 74 68 65 6e   a blob and then
22740 20 72 65 74 75 72 6e 73 20 61 0a 2a 2a 20 20 20   returns a.**   
22750 20 20 20 20 20 20 20 70 6f 69 6e 74 65 72 20 74         pointer t
22760 6f 20 74 68 65 20 63 6f 6e 76 65 72 74 65 64 20  o the converted 
22770 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  value..**.** {F1
22780 33 38 30 36 7d 20 54 68 65 20 5b 73 71 6c 69 74  3806} The [sqlit
22790 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
227a0 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  S,N)] interface 
227b0 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20  returns the.**  
227c0 20 20 20 20 20 20 20 20 6e 75 6d 62 65 72 20 6f          number o
227d0 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 62  f bytes in the b
227e0 6c 6f 62 20 6f 72 20 73 74 72 69 6e 67 20 28 65  lob or string (e
227f0 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65 0a  xclusive of the.
22800 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f  **          zero
22810 20 74 65 72 6d 69 6e 61 74 6f 72 20 6f 6e 20 74   terminator on t
22820 68 65 20 73 74 72 69 6e 67 29 20 74 68 61 74 20  he string) that 
22830 77 61 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  was returned by 
22840 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
22850 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c  most recent call
22860 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   to [sqlite3_col
22870 75 6d 6e 5f 62 6c 6f 62 28 53 2c 4e 29 5d 20 6f  umn_blob(S,N)] o
22880 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  r.**          [s
22890 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
228a0 78 74 28 53 2c 4e 29 5d 2e 0a 2a 2a 0a 2a 2a 20  xt(S,N)]..**.** 
228b0 7b 46 31 33 38 30 39 7d 20 54 68 65 20 5b 73 71  {F13809} The [sq
228c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
228d0 65 73 31 36 28 53 2c 4e 29 5d 20 69 6e 74 65 72  es16(S,N)] inter
228e0 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
228f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 75 6d  .**          num
22900 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
22910 74 68 65 20 73 74 72 69 6e 67 20 28 65 78 63 6c  the string (excl
22920 75 73 69 76 65 20 6f 66 20 74 68 65 0a 2a 2a 20  usive of the.** 
22930 20 20 20 20 20 20 20 20 20 7a 65 72 6f 20 74 65           zero te
22940 72 6d 69 6e 61 74 6f 72 20 6f 6e 20 74 68 65 20  rminator on the 
22950 73 74 72 69 6e 67 29 20 74 68 61 74 20 77 61 73  string) that was
22960 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
22970 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 6f 73  .**          mos
22980 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f  t recent call to
22990 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
229a0 5f 74 65 78 74 31 36 28 53 2c 4e 29 5d 2e 0a 2a  _text16(S,N)]..*
229b0 2a 0a 2a 2a 20 7b 46 31 33 38 31 32 7d 20 54 68  *.** {F13812} Th
229c0 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
229d0 6e 5f 64 6f 75 62 6c 65 28 53 2c 4e 29 5d 20 69  n_double(S,N)] i
229e0 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74  nterface convert
229f0 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
22a00 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20    Nth column in 
22a10 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20  the current row 
22a20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
22a30 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  t for.**        
22a40 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74    [prepared stat
22a50 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20  ement] S into a 
22a60 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76  floating point v
22a70 61 6c 75 65 20 61 6e 64 0a 2a 2a 20 20 20 20 20  alue and.**     
22a80 20 20 20 20 20 72 65 74 75 72 6e 73 20 61 20 63       returns a c
22a90 6f 70 79 20 6f 66 20 74 68 61 74 20 76 61 6c 75  opy of that valu
22aa0 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 31 35  e..**.** {F13815
22ab0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
22ac0 6f 6c 75 6d 6e 5f 69 6e 74 28 53 2c 4e 29 5d 20  olumn_int(S,N)] 
22ad0 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72  interface conver
22ae0 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ts the.**       
22af0 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e     Nth column in
22b00 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77   the current row
22b10 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
22b20 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20  et for.**       
22b30 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61     [prepared sta
22b40 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61  tement] S into a
22b50 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69   64-bit signed i
22b60 6e 74 65 67 65 72 20 61 6e 64 0a 2a 2a 20 20 20  nteger and.**   
22b70 20 20 20 20 20 20 20 72 65 74 75 72 6e 73 20 74         returns t
22b80 68 65 20 6c 6f 77 65 72 20 33 32 20 62 69 74 73  he lower 32 bits
22b90 20 6f 66 20 74 68 61 74 20 69 6e 74 65 67 65 72   of that integer
22ba0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 31 38 7d  ..**.** {F13818}
22bb0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
22bc0 6c 75 6d 6e 5f 69 6e 74 36 34 28 53 2c 4e 29 5d  lumn_int64(S,N)]
22bd0 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65   interface conve
22be0 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  rts the.**      
22bf0 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69      Nth column i
22c00 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f  n the current ro
22c10 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  w of the result 
22c20 73 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20  set for.**      
22c30 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74      [prepared st
22c40 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20  atement] S into 
22c50 61 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  a 64-bit signed 
22c60 69 6e 74 65 67 65 72 20 61 6e 64 0a 2a 2a 20 20  integer and.**  
22c70 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 73 20          returns 
22c80 61 20 63 6f 70 79 20 6f 66 20 74 68 61 74 20 69  a copy of that i
22c90 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46  nteger..**.** {F
22ca0 31 33 38 32 31 7d 20 54 68 65 20 5b 73 71 6c 69  13821} The [sqli
22cb0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
22cc0 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  S,N)] interface 
22cd0 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20  converts the.** 
22ce0 20 20 20 20 20 20 20 20 20 4e 74 68 20 63 6f 6c           Nth col
22cf0 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65  umn in the curre
22d00 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65  nt row of the re
22d10 73 75 6c 74 20 73 65 74 20 66 6f 72 0a 2a 2a 20  sult set for.** 
22d20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72           [prepar
22d30 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
22d40 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d  into a zero-term
22d50 69 6e 61 74 65 64 20 55 54 46 2d 38 20 0a 2a 2a  inated UTF-8 .**
22d60 20 20 20 20 20 20 20 20 20 20 73 74 72 69 6e 67            string
22d70 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70   and returns a p
22d80 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20 73  ointer to that s
22d90 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  tring..**.** {F1
22da0 33 38 32 34 7d 20 54 68 65 20 5b 73 71 6c 69 74  3824} The [sqlit
22db0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
22dc0 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  (S,N)] interface
22dd0 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a   converts the.**
22de0 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 63 6f            Nth co
22df0 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72  lumn in the curr
22e00 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72  ent row of the r
22e10 65 73 75 6c 74 20 73 65 74 20 66 6f 72 0a 2a 2a  esult set for.**
22e20 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61            [prepa
22e30 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
22e40 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72   into a zero-ter
22e50 6d 69 6e 61 74 65 64 20 32 2d 62 79 74 65 0a 2a  minated 2-byte.*
22e60 2a 20 20 20 20 20 20 20 20 20 20 61 6c 69 67 6e  *          align
22e70 65 64 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65  ed UTF-16 native
22e80 20 62 79 74 65 20 6f 72 64 65 72 0a 2a 2a 20 20   byte order.**  
22e90 20 20 20 20 20 20 20 20 73 74 72 69 6e 67 20 61          string a
22ea0 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  nd returns a poi
22eb0 6e 74 65 72 20 74 6f 20 74 68 61 74 20 73 74 72  nter to that str
22ec0 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38  ing..**.** {F138
22ed0 32 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  27} The [sqlite3
22ee0 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 53 2c 4e  _column_type(S,N
22ef0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
22f00 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  urns.**         
22f10 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f   one of [SQLITE_
22f20 4e 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49  NULL], [SQLITE_I
22f30 4e 54 45 47 45 52 5d 2c 20 5b 53 51 4c 49 54 45  NTEGER], [SQLITE
22f40 5f 46 4c 4f 41 54 5d 2c 0a 2a 2a 20 20 20 20 20  _FLOAT],.**     
22f50 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 54 45 58       [SQLITE_TEX
22f60 54 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 42  T], or [SQLITE_B
22f70 4c 4f 42 5d 20 61 73 20 61 70 70 72 6f 70 72 69  LOB] as appropri
22f80 61 74 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20  ate for.**      
22f90 20 20 20 20 74 68 65 20 4e 74 68 20 63 6f 6c 75      the Nth colu
22fa0 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e  mn in the curren
22fb0 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73  t row of the res
22fc0 75 6c 74 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20  ult set for.**  
22fd0 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65          [prepare
22fe0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a  d statement] S..
22ff0 2a 2a 0a 2a 2a 20 7b 46 31 33 38 33 30 7d 20 54  **.** {F13830} T
23000 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
23010 6d 6e 5f 76 61 6c 75 65 28 53 2c 4e 29 5d 20 69  mn_value(S,N)] i
23020 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
23030 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70   a.**          p
23040 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b 75 6e  ointer to an [un
23050 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
23060 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
23070 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  for the.**      
23080 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69      Nth column i
23090 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f  n the current ro
230a0 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  w of the result 
230b0 73 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20  set for.**      
230c0 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74      [prepared st
230d0 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 63  atement] S..*/.c
230e0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
230f0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73  e3_column_blob(s
23100 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
23110 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c  t iCol);.int sql
23120 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
23130 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  s(sqlite3_stmt*,
23140 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20   int iCol);.int 
23150 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
23160 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 73  ytes16(sqlite3_s
23170 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
23180 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f  .double sqlite3_
23190 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71  column_double(sq
231a0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
231b0 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69   iCol);.int sqli
231c0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73  te3_column_int(s
231d0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
231e0 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33  t iCol);.sqlite3
231f0 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 63  _int64 sqlite3_c
23200 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69  olumn_int64(sqli
23210 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
23220 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69  Col);.const unsi
23230 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74  gned char *sqlit
23240 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73  e3_column_text(s
23250 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
23260 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76  t iCol);.const v
23270 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
23280 75 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c 69 74  umn_text16(sqlit
23290 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
232a0 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ol);.int sqlite3
232b0 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c  _column_type(sql
232c0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
232d0 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 76  iCol);.sqlite3_v
232e0 61 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f  alue *sqlite3_co
232f0 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74  lumn_value(sqlit
23300 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
23310 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ol);../*.** CAPI
23320 33 52 45 46 3a 20 44 65 73 74 72 6f 79 20 41 20  3REF: Destroy A 
23330 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
23340 6e 74 20 4f 62 6a 65 63 74 20 7b 46 31 33 33 30  nt Object {F1330
23350 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  0}.**.** The sql
23360 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20  ite3_finalize() 
23370 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c  function is call
23380 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20 0a  ed to delete a .
23390 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
233a0 74 65 6d 65 6e 74 5d 2e 20 49 66 20 74 68 65 20  tement]. If the 
233b0 73 74 61 74 65 6d 65 6e 74 20 77 61 73 0a 2a 2a  statement was.**
233c0 20 65 78 65 63 75 74 65 64 20 73 75 63 63 65 73   executed succes
233d0 73 66 75 6c 6c 79 2c 20 6f 72 20 6e 6f 74 20 65  sfully, or not e
233e0 78 65 63 75 74 65 64 20 61 74 20 61 6c 6c 2c 20  xecuted at all, 
233f0 74 68 65 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69  then SQLITE_OK i
23400 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 49  s returned..** I
23410 66 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74  f execution of t
23420 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 61 69  he statement fai
23430 6c 65 64 20 74 68 65 6e 20 61 6e 20 0a 2a 2a 20  led then an .** 
23440 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 20  [error code] or 
23450 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  [extended error 
23460 63 6f 64 65 5d 0a 2a 2a 20 69 73 20 72 65 74 75  code].** is retu
23470 72 6e 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 54 68 69  rned. .**.** Thi
23480 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65  s routine can be
23490 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 70   called at any p
234a0 6f 69 6e 74 20 64 75 72 69 6e 67 20 74 68 65 20  oint during the 
234b0 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65  execution of the
234c0 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
234d0 61 74 65 6d 65 6e 74 5d 2e 20 20 49 66 20 74 68  atement].  If th
234e0 65 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e  e virtual machin
234f0 65 20 68 61 73 20 6e 6f 74 20 0a 2a 2a 20 63 6f  e has not .** co
23500 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74 69 6f  mpleted executio
23510 6e 20 77 68 65 6e 20 74 68 69 73 20 72 6f 75 74  n when this rout
23520 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 2c 20 74  ine is called, t
23530 68 61 74 20 69 73 20 6c 69 6b 65 0a 2a 2a 20 65  hat is like.** e
23540 6e 63 6f 75 6e 74 65 72 69 6e 67 20 61 6e 20 65  ncountering an e
23550 72 72 6f 72 20 6f 72 20 61 6e 20 69 6e 74 65 72  rror or an inter
23560 72 75 70 74 2e 20 20 28 53 65 65 20 5b 73 71 6c  rupt.  (See [sql
23570 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
23580 5d 2e 29 20 0a 2a 2a 20 49 6e 63 6f 6d 70 6c 65  ].) .** Incomple
23590 74 65 20 75 70 64 61 74 65 73 20 6d 61 79 20 62  te updates may b
235a0 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 6e  e rolled back an
235b0 64 20 74 72 61 6e 73 61 63 74 69 6f 6e 73 20 63  d transactions c
235c0 61 6e 63 65 6c 6c 65 64 2c 20 20 0a 2a 2a 20 64  ancelled,  .** d
235d0 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
235e0 63 69 72 63 75 6d 73 74 61 6e 63 65 73 2c 20 61  circumstances, a
235f0 6e 64 20 74 68 65 20 0a 2a 2a 20 5b 65 72 72 6f  nd the .** [erro
23600 72 20 63 6f 64 65 5d 20 72 65 74 75 72 6e 65 64  r code] returned
23610 20 77 69 6c 6c 20 62 65 20 5b 53 51 4c 49 54 45   will be [SQLITE
23620 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20 49  _ABORT]..**.** I
23630 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
23640 20 7b 46 31 31 33 30 32 7d 20 54 68 65 20 5b 73   {F11302} The [s
23650 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
23660 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64 65  S)] interface de
23670 73 74 72 6f 79 73 20 74 68 65 0a 2a 2a 20 20 20  stroys the.**   
23680 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64         [prepared
23690 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 61 6e   statement] S an
236a0 64 20 72 65 6c 65 61 73 65 73 20 61 6c 6c 0a 2a  d releases all.*
236b0 2a 20 20 20 20 20 20 20 20 20 20 6d 65 6d 6f 72  *          memor
236c0 79 20 61 6e 64 20 66 69 6c 65 20 72 65 73 6f 75  y and file resou
236d0 72 63 65 73 20 68 65 6c 64 20 62 79 20 74 68 61  rces held by tha
236e0 74 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20  t object..**.** 
236f0 7b 46 31 31 33 30 34 7d 20 49 66 20 74 68 65 20  {F11304} If the 
23700 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c  most recent call
23710 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
23720 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a  p(S)] for the.**
23730 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61            [prepa
23740 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
23750 20 72 65 74 75 72 6e 65 64 20 61 6e 20 65 72 72   returned an err
23760 6f 72 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  or,.**          
23770 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69  then [sqlite3_fi
23780 6e 61 6c 69 7a 65 28 53 29 5d 20 72 65 74 75 72  nalize(S)] retur
23790 6e 73 20 74 68 61 74 20 73 61 6d 65 20 65 72 72  ns that same err
237a0 6f 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  or..*/.int sqlit
237b0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69  e3_finalize(sqli
237c0 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
237d0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
237e0 46 3a 20 52 65 73 65 74 20 41 20 50 72 65 70 61  F: Reset A Prepa
237f0 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62  red Statement Ob
23800 6a 65 63 74 20 7b 46 31 33 33 33 30 7d 0a 2a 2a  ject {F13330}.**
23810 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
23820 72 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e  reset() function
23830 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65   is called to re
23840 73 65 74 20 61 20 0a 2a 2a 20 5b 70 72 65 70 61  set a .** [prepa
23850 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f  red statement] o
23860 62 6a 65 63 74 2e 0a 2a 2a 20 62 61 63 6b 20 74  bject..** back t
23870 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74  o its initial st
23880 61 74 65 2c 20 72 65 61 64 79 20 74 6f 20 62 65  ate, ready to be
23890 20 72 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a   re-executed..**
238a0 20 41 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65   Any SQL stateme
238b0 6e 74 20 76 61 72 69 61 62 6c 65 73 20 74 68 61  nt variables tha
238c0 74 20 68 61 64 20 76 61 6c 75 65 73 20 62 6f 75  t had values bou
238d0 6e 64 20 74 6f 20 74 68 65 6d 20 75 73 69 6e 67  nd to them using
238e0 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33  .** the [sqlite3
238f0 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c  _bind_blob | sql
23900 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50  ite3_bind_*() AP
23910 49 5d 20 72 65 74 61 69 6e 20 74 68 65 69 72 20  I] retain their 
23920 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b  values..** Use [
23930 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69  sqlite3_clear_bi
23940 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20 72 65 73  ndings()] to res
23950 65 74 20 74 68 65 20 62 69 6e 64 69 6e 67 73 2e  et the bindings.
23960 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 33 33 32 7d 20  .**.** {F11332} 
23970 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
23980 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65  et(S)] interface
23990 20 72 65 73 65 74 73 20 74 68 65 20 5b 70 72 65   resets the [pre
239a0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
239b0 20 53 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62   S.**          b
239c0 61 63 6b 20 74 6f 20 74 68 65 20 62 65 67 69 6e  ack to the begin
239d0 6e 69 6e 67 20 6f 66 20 69 74 73 20 70 72 6f 67  ning of its prog
239e0 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 33  ram..**.** {F113
239f0 33 34 7d 20 49 66 20 74 68 65 20 6d 6f 73 74 20  34} If the most 
23a00 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b  recent call to [
23a10 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
23a20 20 66 6f 72 20 0a 2a 2a 20 20 20 20 20 20 20 20   for .**        
23a30 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74    [prepared stat
23a40 65 6d 65 6e 74 5d 20 53 20 72 65 74 75 72 6e 65  ement] S returne
23a50 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f  d [SQLITE_ROW] o
23a60 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c  r [SQLITE_DONE],
23a70 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
23a80 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  if [sqlite3_step
23a90 28 53 29 5d 20 68 61 73 20 6e 65 76 65 72 20 62  (S)] has never b
23aa0 65 66 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c 65  efore been calle
23ab0 64 20 6f 6e 20 53 2c 0a 2a 2a 20 20 20 20 20 20  d on S,.**      
23ac0 20 20 20 20 74 68 65 6e 20 5b 73 71 6c 69 74 65      then [sqlite
23ad0 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75  3_reset(S)] retu
23ae0 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e  rns [SQLITE_OK].
23af0 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 33 33 36 7d 20  .**.** {F11336} 
23b00 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
23b10 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  nt call to [sqli
23b20 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72  te3_step(S)] for
23b30 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
23b40 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
23b50 5d 20 53 20 69 6e 64 69 63 61 74 65 64 20 61 6e  ] S indicated an
23b60 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20   error, then.** 
23b70 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
23b80 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75  3_reset(S)] retu
23b90 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61  rns an appropria
23ba0 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e  te [error code].
23bb0 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 33 33 38 7d 20  .**.** {F11338} 
23bc0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
23bd0 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65  et(S)] interface
23be0 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65   does not change
23bf0 20 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 20   the values.**  
23c00 20 20 20 20 20 20 20 20 6f 66 20 61 6e 79 20 5b          of any [
23c10 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
23c20 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 5b  b|bindings] on [
23c30 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
23c40 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71  nt] S..*/.int sq
23c50 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71 6c 69  lite3_reset(sqli
23c60 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
23c70 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
23c80 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52 65 64  F: Create Or Red
23c90 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 74 69  efine SQL Functi
23ca0 6f 6e 73 20 7b 46 31 36 31 30 30 7d 0a 2a 2a 20  ons {F16100}.** 
23cb0 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74  KEYWORDS: {funct
23cc0 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75  ion creation rou
23cd0 74 69 6e 65 73 7d 20 0a 2a 2a 0a 2a 2a 20 54 68  tines} .**.** Th
23ce0 65 73 65 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e  ese two function
23cf0 73 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20  s (collectively 
23d00 6b 6e 6f 77 6e 20 61 73 0a 2a 2a 20 22 66 75 6e  known as.** "fun
23d10 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72  ction creation r
23d20 6f 75 74 69 6e 65 73 22 29 20 61 72 65 20 75 73  outines") are us
23d30 65 64 20 74 6f 20 61 64 64 20 53 51 4c 20 66 75  ed to add SQL fu
23d40 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65  nctions or aggre
23d50 67 61 74 65 73 0a 2a 2a 20 6f 72 20 74 6f 20 72  gates.** or to r
23d60 65 64 65 66 69 6e 65 20 74 68 65 20 62 65 68 61  edefine the beha
23d70 76 69 6f 72 20 6f 66 20 65 78 69 73 74 69 6e 67  vior of existing
23d80 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f   SQL functions o
23d90 72 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 54  r aggregates.  T
23da0 68 65 0a 2a 2a 20 64 69 66 66 65 72 65 6e 63 65  he.** difference
23db0 20 6f 6e 6c 79 20 62 65 74 77 65 65 6e 20 74 68   only between th
23dc0 65 20 74 77 6f 20 69 73 20 74 68 61 74 20 74 68  e two is that th
23dd0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
23de0 65 72 2c 20 74 68 65 0a 2a 2a 20 6e 61 6d 65 20  er, the.** name 
23df0 6f 66 20 74 68 65 20 28 73 63 61 6c 61 72 29 20  of the (scalar) 
23e00 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72  function or aggr
23e10 65 67 61 74 65 2c 20 69 73 20 65 6e 63 6f 64 65  egate, is encode
23e20 64 20 69 6e 20 55 54 46 2d 38 20 66 6f 72 0a 2a  d in UTF-8 for.*
23e30 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  * sqlite3_create
23e40 5f 66 75 6e 63 74 69 6f 6e 28 29 20 61 6e 64 20  _function() and 
23e50 55 54 46 2d 31 36 20 66 6f 72 20 73 71 6c 69 74  UTF-16 for sqlit
23e60 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
23e70 6f 6e 31 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  on16()..**.** Th
23e80 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
23e90 72 20 69 73 20 74 68 65 20 5b 64 61 74 61 62 61  r is the [databa
23ea0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74  se connection] t
23eb0 6f 20 77 68 69 63 68 20 74 68 65 20 53 51 4c 0a  o which the SQL.
23ec0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74  ** function is t
23ed0 6f 20 62 65 20 61 64 64 65 64 2e 20 20 49 66 20  o be added.  If 
23ee0 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 70 72 6f 67  a single.** prog
23ef0 72 61 6d 20 75 73 65 73 20 6d 6f 72 65 20 74 68  ram uses more th
23f00 61 6e 20 6f 6e 65 20 5b 64 61 74 61 62 61 73 65  an one [database
23f10 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 6e 74   connection] int
23f20 65 72 6e 61 6c 6c 79 2c 20 74 68 65 6e 20 53 51  ernally, then SQ
23f30 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 6d  L.** functions m
23f40 75 73 74 20 62 65 20 61 64 64 65 64 20 69 6e 64  ust be added ind
23f50 69 76 69 64 75 61 6c 6c 79 20 74 6f 20 65 61 63  ividually to eac
23f60 68 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  h [database conn
23f70 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 54  ection]..**.** T
23f80 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
23f90 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20  ter is the name 
23fa0 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  of the SQL funct
23fb0 69 6f 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65  ion to be create
23fc0 64 0a 2a 2a 20 6f 72 20 72 65 64 65 66 69 6e 65  d.** or redefine
23fd0 64 2e 0a 2a 2a 20 54 68 65 20 6c 65 6e 67 74 68  d..** The length
23fe0 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 69 73 20   of the name is 
23ff0 6c 69 6d 69 74 65 64 20 74 6f 20 32 35 35 20 62  limited to 255 b
24000 79 74 65 73 2c 20 65 78 63 6c 75 73 69 76 65 20  ytes, exclusive 
24010 6f 66 20 74 68 65 20 0a 2a 2a 20 7a 65 72 6f 2d  of the .** zero-
24020 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 4e 6f 74  terminator.  Not
24030 65 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65 20  e that the name 
24040 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20  length limit is 
24050 69 6e 20 62 79 74 65 73 2c 20 6e 6f 74 0a 2a 2a  in bytes, not.**
24060 20 63 68 61 72 61 63 74 65 72 73 2e 20 20 41 6e   characters.  An
24070 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63 72 65  y attempt to cre
24080 61 74 65 20 61 20 66 75 6e 63 74 69 6f 6e 20 77  ate a function w
24090 69 74 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d  ith a longer nam
240a0 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74  e.** will result
240b0 20 69 6e 20 61 6e 20 53 51 4c 49 54 45 5f 45 52   in an SQLITE_ER
240c0 52 4f 52 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a  ROR error..**.**
240d0 20 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   The third param
240e0 65 74 65 72 20 69 73 20 74 68 65 20 6e 75 6d 62  eter is the numb
240f0 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20  er of arguments 
24100 74 68 61 74 20 74 68 65 20 53 51 4c 20 66 75 6e  that the SQL fun
24110 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72  ction or.** aggr
24120 65 67 61 74 65 20 74 61 6b 65 73 2e 20 49 66 20  egate takes. If 
24130 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 69  this parameter i
24140 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  s negative, then
24150 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
24160 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74  n or.** aggregat
24170 65 20 6d 61 79 20 74 61 6b 65 20 61 6e 79 20 6e  e may take any n
24180 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e  umber of argumen
24190 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f  ts..**.** The fo
241a0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20  urth parameter, 
241b0 65 54 65 78 74 52 65 70 2c 20 73 70 65 63 69 66  eTextRep, specif
241c0 69 65 73 20 77 68 61 74 20 0a 2a 2a 20 5b 53 51  ies what .** [SQ
241d0 4c 49 54 45 5f 55 54 46 38 20 7c 20 74 65 78 74  LITE_UTF8 | text
241e0 20 65 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73 20   encoding] this 
241f0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72 65  SQL function pre
24200 66 65 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20  fers for.** its 
24210 70 61 72 61 6d 65 74 65 72 73 2e 20 20 41 6e 79  parameters.  Any
24220 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d   SQL function im
24230 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f  plementation sho
24240 75 6c 64 20 62 65 20 61 62 6c 65 20 74 6f 20 77  uld be able to w
24250 6f 72 6b 0a 2a 2a 20 77 6f 72 6b 20 77 69 74 68  ork.** work with
24260 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 6c 65   UTF-8, UTF-16le
24270 2c 20 6f 72 20 55 54 46 2d 31 36 62 65 2e 20 20  , or UTF-16be.  
24280 42 75 74 20 73 6f 6d 65 20 69 6d 70 6c 65 6d 65  But some impleme
24290 6e 74 61 74 69 6f 6e 73 20 6d 61 79 20 62 65 0a  ntations may be.
242a0 2a 2a 20 6d 6f 72 65 20 65 66 66 69 63 69 65 6e  ** more efficien
242b0 74 20 77 69 74 68 20 6f 6e 65 20 65 6e 63 6f 64  t with one encod
242c0 69 6e 67 20 74 68 61 6e 20 61 6e 6f 74 68 65 72  ing than another
242d0 2e 20 20 49 74 20 69 73 20 61 6c 6c 6f 77 65 64  .  It is allowed
242e0 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71   to.** invoke sq
242f0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
24300 63 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c 69 74  ction() or sqlit
24310 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
24320 6f 6e 31 36 28 29 20 6d 75 6c 74 69 70 6c 65 0a  on16() multiple.
24330 2a 2a 20 74 69 6d 65 73 20 77 69 74 68 20 74 68  ** times with th
24340 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20  e same function 
24350 62 75 74 20 77 69 74 68 20 64 69 66 66 65 72 65  but with differe
24360 6e 74 20 76 61 6c 75 65 73 20 6f 66 20 65 54 65  nt values of eTe
24370 78 74 52 65 70 2e 0a 2a 2a 20 57 68 65 6e 20 6d  xtRep..** When m
24380 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e  ultiple implemen
24390 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  tations of the s
243a0 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 65  ame function are
243b0 20 61 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69   available, SQLi
243c0 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20  te.** will pick 
243d0 74 68 65 20 6f 6e 65 20 74 68 61 74 20 69 6e 76  the one that inv
243e0 6f 6c 76 65 73 20 74 68 65 20 6c 65 61 73 74 20  olves the least 
243f0 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 63  amount of data c
24400 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 49 66  onversion..** If
24410 20 74 68 65 72 65 20 69 73 20 6f 6e 6c 79 20 61   there is only a
24420 20 73 69 6e 67 6c 65 20 69 6d 70 6c 65 6d 65 6e   single implemen
24430 74 61 74 69 6f 6e 20 77 68 69 63 68 20 64 6f 65  tation which doe
24440 73 20 6e 6f 74 20 63 61 72 65 20 77 68 61 74 0a  s not care what.
24450 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  ** text encoding
24460 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20 74   is used, then t
24470 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
24480 6e 74 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20  nt should be.** 
24490 5b 53 51 4c 49 54 45 5f 41 4e 59 5d 2e 0a 2a 2a  [SQLITE_ANY]..**
244a0 0a 2a 2a 20 54 68 65 20 66 69 66 74 68 20 70 61  .** The fifth pa
244b0 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72  rameter is an ar
244c0 62 69 74 72 61 72 79 20 70 6f 69 6e 74 65 72 2e  bitrary pointer.
244d0 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61    The implementa
244e0 74 69 6f 6e 0a 2a 2a 20 6f 66 20 74 68 65 20 66  tion.** of the f
244f0 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e  unction can gain
24500 20 61 63 63 65 73 73 20 74 6f 20 74 68 69 73 20   access to this 
24510 70 6f 69 6e 74 65 72 20 75 73 69 6e 67 0a 2a 2a  pointer using.**
24520 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64   [sqlite3_user_d
24530 61 74 61 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  ata()]..**.** Th
24540 65 20 73 65 76 65 6e 74 68 2c 20 65 69 67 68 74  e seventh, eight
24550 68 20 61 6e 64 20 6e 69 6e 74 68 20 70 61 72 61  h and ninth para
24560 6d 65 74 65 72 73 2c 20 78 46 75 6e 63 2c 20 78  meters, xFunc, x
24570 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c  Step and xFinal,
24580 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73   are.** pointers
24590 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20 66   to C-language f
245a0 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 69 6d  unctions that im
245b0 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 0a  plement the SQL.
245c0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61  ** function or a
245d0 67 67 72 65 67 61 74 65 2e 20 41 20 73 63 61 6c  ggregate. A scal
245e0 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ar SQL function 
245f0 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c  requires an impl
24600 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 0a 2a 2a  ementation of.**
24610 20 74 68 65 20 78 46 75 6e 63 20 63 61 6c 6c 62   the xFunc callb
24620 61 63 6b 20 6f 6e 6c 79 2c 20 4e 55 4c 4c 20 70  ack only, NULL p
24630 6f 69 6e 74 65 72 73 20 73 68 6f 75 6c 64 20 62  ointers should b
24640 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
24650 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69  xStep.** and xFi
24660 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73 2e 20  nal parameters. 
24670 41 6e 20 61 67 67 72 65 67 61 74 65 20 53 51 4c  An aggregate SQL
24680 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72   function requir
24690 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  es an implementa
246a0 74 69 6f 6e 0a 2a 2a 20 6f 66 20 78 53 74 65 70  tion.** of xStep
246b0 20 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64 20   and xFinal and 
246c0 4e 55 4c 4c 20 73 68 6f 75 6c 64 20 62 65 20 70  NULL should be p
246d0 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63 2e  assed for xFunc.
246e0 20 54 6f 20 64 65 6c 65 74 65 20 61 6e 0a 2a 2a   To delete an.**
246f0 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75   existing SQL fu
24700 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67  nction or aggreg
24710 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 66  ate, pass NULL f
24720 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 66 75 6e  or all three fun
24730 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63  ction.** callbac
24740 6b 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 70  k..**.** It is p
24750 65 72 6d 69 74 74 65 64 20 74 6f 20 72 65 67 69  ermitted to regi
24760 73 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d  ster multiple im
24770 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66  plementations of
24780 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e   the same.** fun
24790 63 74 69 6f 6e 73 20 77 69 74 68 20 74 68 65 20  ctions with the 
247a0 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 69  same name but wi
247b0 74 68 20 65 69 74 68 65 72 20 64 69 66 66 65 72  th either differ
247c0 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a  ing numbers of.*
247d0 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 64  * arguments or d
247e0 69 66 66 65 72 69 6e 67 20 70 65 72 66 65 72 72  iffering perferr
247f0 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  ed text encoding
24800 73 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  s.  SQLite will 
24810 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65  use.** the imple
24820 6d 65 6e 74 61 74 69 6f 6e 20 6d 6f 73 74 20 63  mentation most c
24830 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74  losely matches t
24840 68 65 20 77 61 79 20 69 6e 20 77 68 69 63 68 20  he way in which 
24850 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74  the.** SQL funct
24860 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a  ion is used..**.
24870 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
24880 2a 0a 2a 2a 20 7b 46 31 36 31 30 33 7d 20 54 68  *.** {F16103} Th
24890 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
248a0 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20  e_function16()] 
248b0 69 6e 74 65 72 66 61 63 65 20 62 65 68 61 76 65  interface behave
248c0 73 20 65 78 61 63 74 6c 79 0a 2a 2a 20 20 20 20  s exactly.**    
248d0 20 20 20 20 20 20 6c 69 6b 65 20 5b 73 71 6c 69        like [sqli
248e0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
248f0 69 6f 6e 28 29 5d 20 69 6e 20 65 76 65 72 79 20  ion()] in every 
24900 77 61 79 20 65 78 63 65 70 74 20 74 68 61 74 20  way except that 
24910 69 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  it.**          i
24920 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 7a 46  nterprets the zF
24930 75 6e 63 74 69 6f 6e 4e 61 6d 65 20 61 72 67 75  unctionName argu
24940 6d 65 6e 74 20 61 73 0a 2a 2a 20 20 20 20 20 20  ment as.**      
24950 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61      zero-termina
24960 74 65 64 20 55 54 46 2d 31 36 20 6e 61 74 69 76  ted UTF-16 nativ
24970 65 20 62 79 74 65 20 6f 72 64 65 72 20 69 6e 73  e byte order ins
24980 74 65 61 64 20 6f 66 20 61 73 20 61 0a 2a 2a 20  tead of as a.** 
24990 20 20 20 20 20 20 20 20 20 7a 65 72 6f 2d 74 65           zero-te
249a0 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 2e 0a  rminated UTF-8..
249b0 2a 2a 0a 2a 2a 20 7b 46 31 36 31 30 36 7d 20 41  **.** {F16106} A
249c0 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f   successful invo
249d0 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 20 20 20  cation of.**    
249e0 20 20 20 20 20 20 74 68 65 20 5b 73 71 6c 69 74        the [sqlit
249f0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
24a00 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 2e 2e 2e 29 5d  on(D,X,N,E,...)]
24a10 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73   interface regis
24a20 74 65 72 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  ters.**         
24a30 20 6f 72 20 72 65 70 6c 61 63 65 73 20 63 61 6c   or replaces cal
24a40 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20  lback functions 
24a50 69 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  in [database con
24a60 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 20 20  nection] D.**   
24a70 20 20 20 20 20 20 20 75 73 65 64 20 74 6f 20 69         used to i
24a80 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c  mplement the SQL
24a90 20 66 75 6e 63 74 69 6f 6e 20 6e 61 6d 65 64 20   function named 
24aa0 58 20 77 69 74 68 20 4e 20 70 61 72 61 6d 65 74  X with N paramet
24ab0 65 72 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ers.**          
24ac0 61 6e 64 20 68 61 76 69 6e 67 20 61 20 70 65 72  and having a per
24ad0 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f  ferred text enco
24ae0 64 69 6e 67 20 6f 66 20 45 2e 0a 2a 2a 0a 2a 2a  ding of E..**.**
24af0 20 7b 46 31 36 31 30 39 7d 20 41 20 73 75 63 63   {F16109} A succ
24b00 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b  essful call to [
24b10 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
24b20 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c  unction(D,X,N,E,
24b30 50 2c 46 2c 53 2c 4c 29 5d 0a 2a 2a 20 20 20 20  P,F,S,L)].**    
24b40 20 20 20 20 20 20 72 65 70 6c 61 63 65 73 20 74        replaces t
24b50 68 65 20 50 2c 20 46 2c 20 53 2c 20 61 6e 64 20  he P, F, S, and 
24b60 4c 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 61 6e  L values from an
24b70 79 20 70 72 69 6f 72 20 63 61 6c 6c 73 20 77 69  y prior calls wi
24b80 74 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  th.**          t
24b90 68 65 20 73 61 6d 65 20 44 2c 20 58 2c 20 4e 2c  he same D, X, N,
24ba0 20 61 6e 64 20 45 20 76 61 6c 75 65 73 2e 0a 2a   and E values..*
24bb0 2a 0a 2a 2a 20 7b 46 31 36 31 31 32 7d 20 54 68  *.** {F16112} Th
24bc0 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
24bd0 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 2e  e_function(D,X,.
24be0 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 66  ..)] interface f
24bf0 61 69 6c 73 20 77 69 74 68 0a 2a 2a 20 20 20 20  ails with.**    
24c00 20 20 20 20 20 20 61 20 72 65 74 75 72 6e 20 63        a return c
24c10 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 45  ode of [SQLITE_E
24c20 52 52 4f 52 5d 20 69 66 20 74 68 65 20 53 51 4c  RROR] if the SQL
24c30 20 66 75 6e 63 74 69 6f 6e 20 6e 61 6d 65 20 58   function name X
24c40 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   is.**          
24c50 6c 6f 6e 67 65 72 20 74 68 61 6e 20 32 35 35 20  longer than 255 
24c60 62 79 74 65 73 20 65 78 63 6c 75 73 69 76 65 20  bytes exclusive 
24c70 6f 66 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d  of the zero term
24c80 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46  inator..**.** {F
24c90 31 36 31 31 38 7d 20 45 69 74 68 65 72 20 46 20  16118} Either F 
24ca0 6d 75 73 74 20 62 65 20 4e 55 4c 4c 20 61 6e 64  must be NULL and
24cb0 20 53 20 61 6e 64 20 4c 20 61 72 65 20 6e 6f 6e   S and L are non
24cc0 2d 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 46 0a  -NULL or else F.
24cd0 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 6e  **          is n
24ce0 6f 6e 2d 4e 55 4c 4c 20 61 6e 64 20 53 20 61 6e  on-NULL and S an
24cf0 64 20 4c 20 61 72 65 20 4e 55 4c 4c 2c 20 6f 74  d L are NULL, ot
24d00 68 65 72 77 69 73 65 0a 2a 2a 20 20 20 20 20 20  herwise.**      
24d10 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 72 65      [sqlite3_cre
24d20 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58  ate_function(D,X
24d30 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 20 72  ,N,E,P,F,S,L)] r
24d40 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 45  eturns [SQLITE_E
24d50 52 52 4f 52 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  RROR]..**.** {F1
24d60 36 31 32 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  6121} The [sqlit
24d70 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
24d80 6f 6e 28 44 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72  on(D,...)] inter
24d90 66 61 63 65 20 66 61 69 6c 73 20 77 69 74 68 20  face fails with 
24da0 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65  an.**          e
24db0 72 72 6f 72 20 63 6f 64 65 20 6f 66 20 5b 53 51  rror code of [SQ
24dc0 4c 49 54 45 5f 42 55 53 59 5d 20 69 66 20 74 68  LITE_BUSY] if th
24dd0 65 72 65 20 65 78 69 73 74 20 5b 70 72 65 70 61  ere exist [prepa
24de0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 0a  red statements].
24df0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 73 73 6f  **          asso
24e00 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
24e10 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
24e20 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b  tion] D..**.** {
24e30 46 31 36 31 32 34 7d 20 54 68 65 20 5b 73 71 6c  F16124} The [sql
24e40 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
24e50 74 69 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d  tion(D,X,N,...)]
24e60 20 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73   interface fails
24e70 20 77 69 74 68 20 61 6e 0a 2a 2a 20 20 20 20 20   with an.**     
24e80 20 20 20 20 20 65 72 72 6f 72 20 63 6f 64 65 20       error code 
24e90 6f 66 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  of [SQLITE_ERROR
24ea0 5d 20 69 66 20 70 61 72 61 6d 65 74 65 72 20 4e  ] if parameter N
24eb0 20 28 73 70 65 63 69 66 79 69 6e 67 20 74 68 65   (specifying the
24ec0 20 6e 75 6d 62 65 72 0a 2a 2a 20 20 20 20 20 20   number.**      
24ed0 20 20 20 20 6f 66 20 61 72 67 75 6d 65 6e 74 73      of arguments
24ee0 20 74 6f 20 74 68 65 20 53 51 4c 20 66 75 6e 63   to the SQL func
24ef0 74 69 6f 6e 20 62 65 69 6e 67 20 72 65 67 69 73  tion being regis
24f00 74 65 72 65 64 29 20 69 73 20 6c 65 73 73 0a 2a  tered) is less.*
24f10 2a 20 20 20 20 20 20 20 20 20 20 74 68 61 6e 20  *          than 
24f20 2d 31 20 6f 72 20 67 72 65 61 74 65 72 20 74 68  -1 or greater th
24f30 61 6e 20 31 32 37 2e 0a 2a 2a 0a 2a 2a 20 7b 46  an 127..**.** {F
24f40 31 36 31 32 37 7d 20 57 68 65 6e 20 4e 20 69 73  16127} When N is
24f50 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74   non-negative, t
24f60 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  he [sqlite3_crea
24f70 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c  te_function(D,X,
24f80 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20  N,...)].**      
24f90 20 20 20 20 69 6e 74 65 72 66 61 63 65 20 63 61      interface ca
24fa0 75 73 65 73 20 63 61 6c 6c 62 61 63 6b 73 20 74  uses callbacks t
24fb0 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 66 6f 72  o be invoked for
24fc0 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
24fd0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 61  n.**          na
24fe0 6d 65 64 20 58 20 77 68 65 6e 20 74 68 65 20 6e  med X when the n
24ff0 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e  umber of argumen
25000 74 73 20 74 6f 20 74 68 65 20 53 51 4c 20 66 75  ts to the SQL fu
25010 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20  nction is.**    
25020 20 20 20 20 20 20 65 78 61 63 74 6c 79 20 4e 2e        exactly N.
25030 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 33 30 7d 20  .**.** {F16130} 
25040 57 68 65 6e 20 4e 20 69 73 20 2d 31 2c 20 74 68  When N is -1, th
25050 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
25060 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e  e_function(D,X,N
25070 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ,...)].**       
25080 20 20 20 69 6e 74 65 72 66 61 63 65 20 63 61 75     interface cau
25090 73 65 73 20 63 61 6c 6c 62 61 63 6b 73 20 74 6f  ses callbacks to
250a0 20 62 65 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20   be invoked for 
250b0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
250c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 61 6d  .**          nam
250d0 65 64 20 58 20 77 69 74 68 20 61 6e 79 20 6e 75  ed X with any nu
250e0 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
250f0 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 33 33  s..**.** {F16133
25100 7d 20 57 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20  } When calls to 
25110 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
25120 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 2e  function(D,X,N,.
25130 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ..)].**         
25140 20 73 70 65 63 69 66 79 20 6d 75 6c 74 69 70 6c   specify multipl
25150 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
25160 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75  s of the same fu
25170 6e 63 74 69 6f 6e 20 58 0a 2a 2a 20 20 20 20 20  nction X.**     
25180 20 20 20 20 20 61 6e 64 20 77 68 65 6e 20 6f 6e       and when on
25190 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
251a0 20 68 61 73 20 4e 3e 3d 30 20 61 6e 64 20 74 68   has N>=0 and th
251b0 65 20 6f 74 68 65 72 20 68 61 73 20 4e 3d 28 2d  e other has N=(-
251c0 31 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  1).**          t
251d0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
251e0 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a 65 72  n with a non-zer
251f0 6f 20 4e 20 69 73 20 70 72 65 66 65 72 72 65 64  o N is preferred
25200 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 33 36 7d  ..**.** {F16136}
25210 20 57 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20 5b   When calls to [
25220 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
25230 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c  unction(D,X,N,E,
25240 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  ...)].**        
25250 20 20 73 70 65 63 69 66 79 20 6d 75 6c 74 69 70    specify multip
25260 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
25270 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66  ns of the same f
25280 75 6e 63 74 69 6f 6e 20 58 20 77 69 74 68 0a 2a  unction X with.*
25290 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 73  *          the s
252a0 61 6d 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72  ame number of ar
252b0 67 75 6d 65 6e 74 73 20 4e 20 62 75 74 20 77 69  guments N but wi
252c0 74 68 20 64 69 66 66 65 72 65 6e 74 0a 2a 2a 20  th different.** 
252d0 20 20 20 20 20 20 20 20 20 65 6e 63 6f 64 69 6e           encodin
252e0 67 73 20 45 2c 20 74 68 65 6e 20 74 68 65 20 69  gs E, then the i
252f0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68  mplementation wh
25300 65 72 65 20 45 20 6d 61 74 63 68 65 73 20 74 68  ere E matches th
25310 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 61  e.**          da
25320 74 61 62 61 73 65 20 65 6e 63 6f 64 69 6e 67 20  tabase encoding 
25330 69 73 20 70 72 65 66 65 72 72 65 64 2e 0a 2a 2a  is preferred..**
25340 0a 2a 2a 20 7b 46 31 36 31 33 39 7d 20 46 6f 72  .** {F16139} For
25350 20 61 6e 20 61 67 67 72 65 67 61 74 65 20 53 51   an aggregate SQ
25360 4c 20 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74  L function creat
25370 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20  ed using.**     
25380 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 72       [sqlite3_cr
25390 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c  eate_function(D,
253a0 58 2c 4e 2c 45 2c 50 2c 30 2c 53 2c 4c 29 5d 20  X,N,E,P,0,S,L)] 
253b0 74 68 65 20 66 69 6e 69 61 6c 69 7a 65 72 0a 2a  the finializer.*
253c0 2a 20 20 20 20 20 20 20 20 20 20 66 75 6e 63 74  *          funct
253d0 69 6f 6e 20 4c 20 77 69 6c 6c 20 61 6c 77 61 79  ion L will alway
253e0 73 20 62 65 20 69 6e 76 6f 6b 65 64 20 65 78 61  s be invoked exa
253f0 63 74 6c 79 20 6f 6e 63 65 20 69 66 20 74 68 65  ctly once if the
25400 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 65  .**          ste
25410 70 20 66 75 6e 63 74 69 6f 6e 20 53 20 69 73 20  p function S is 
25420 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f  called one or mo
25430 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 0a 2a 2a 20  re times..**.** 
25440 7b 46 31 36 31 34 32 7d 20 57 68 65 6e 20 53 51  {F16142} When SQ
25450 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 65 69 74  Lite invokes eit
25460 68 65 72 20 74 68 65 20 78 46 75 6e 63 20 6f 72  her the xFunc or
25470 20 78 53 74 65 70 20 66 75 6e 63 74 69 6f 6e 20   xStep function 
25480 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  of.**          a
25490 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
254a0 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
254b0 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 20  on or aggregate 
254c0 63 72 65 61 74 65 64 0a 2a 2a 20 20 20 20 20 20  created.**      
254d0 20 20 20 20 62 79 20 5b 73 71 6c 69 74 65 33 5f      by [sqlite3_
254e0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
254f0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63  )] or [sqlite3_c
25500 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
25510 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ()],.**         
25520 20 74 68 65 6e 20 74 68 65 20 61 72 72 61 79 20   then the array 
25530 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  of [sqlite3_valu
25540 65 5d 20 6f 62 6a 65 63 74 73 20 70 61 73 73 65  e] objects passe
25550 64 20 61 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  d as the.**     
25560 20 20 20 20 20 74 68 69 72 64 20 70 61 72 61 6d       third param
25570 65 74 65 72 20 61 72 65 20 61 6c 77 61 79 73 20  eter are always 
25580 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
25590 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
255a0 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  s..*/.int sqlite
255b0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
255c0 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  n(.  sqlite3 *db
255d0 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  ,.  const char *
255e0 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20  zFunctionName,. 
255f0 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74   int nArg,.  int
25600 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69   eTextRep,.  voi
25610 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20  d *pApp,.  void 
25620 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33  (*xFunc)(sqlite3
25630 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
25640 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
25650 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28    void (*xStep)(
25660 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
25670 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
25680 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
25690 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f  xFinal)(sqlite3_
256a0 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74  context*).);.int
256b0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
256c0 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73 71  function16(.  sq
256d0 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e  lite3 *db,.  con
256e0 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69  st void *zFuncti
256f0 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41  onName,.  int nA
25700 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52  rg,.  int eTextR
25710 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70  ep,.  void *pApp
25720 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63  ,.  void (*xFunc
25730 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
25740 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
25750 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
25760 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33  (*xStep)(sqlite3
25770 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
25780 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
25790 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29    void (*xFinal)
257a0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
257b0 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  *).);../*.** CAP
257c0 49 33 52 45 46 3a 20 54 65 78 74 20 45 6e 63 6f  I3REF: Text Enco
257d0 64 69 6e 67 73 20 7b 46 31 30 32 36 37 7d 0a 2a  dings {F10267}.*
257e0 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
257f0 61 6e 74 20 64 65 66 69 6e 65 20 69 6e 74 65 67  ant define integ
25800 65 72 20 63 6f 64 65 73 20 74 68 61 74 20 72 65  er codes that re
25810 70 72 65 73 65 6e 74 20 74 68 65 20 76 61 72 69  present the vari
25820 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f  ous.** text enco
25830 64 69 6e 67 73 20 73 75 70 70 6f 72 74 65 64 20  dings supported 
25840 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64  by SQLite..*/.#d
25850 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46  efine SQLITE_UTF
25860 38 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64  8           1.#d
25870 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46  efine SQLITE_UTF
25880 31 36 4c 45 20 20 20 20 20 20 20 20 32 0a 23 64  16LE        2.#d
25890 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46  efine SQLITE_UTF
258a0 31 36 42 45 20 20 20 20 20 20 20 20 33 0a 23 64  16BE        3.#d
258b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46  efine SQLITE_UTF
258c0 31 36 20 20 20 20 20 20 20 20 20 20 34 20 20 20  16          4   
258d0 20 2f 2a 20 55 73 65 20 6e 61 74 69 76 65 20 62   /* Use native b
258e0 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65  yte order */.#de
258f0 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59 20  fine SQLITE_ANY 
25900 20 20 20 20 20 20 20 20 20 20 20 35 20 20 20 20             5    
25910 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  /* sqlite3_creat
25920 65 5f 66 75 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20  e_function only 
25930 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
25940 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 20  E_UTF16_ALIGNED 
25950 20 38 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33   8    /* sqlite3
25960 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
25970 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  n only */../*.**
25980 20 43 41 50 49 33 52 45 46 3a 20 4f 62 73 6f 6c   CAPI3REF: Obsol
25990 65 74 65 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  ete Functions.**
259a0 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69  .** These functi
259b0 6f 6e 73 20 61 72 65 20 61 6c 6c 20 6e 6f 77 20  ons are all now 
259c0 6f 62 73 6f 6c 65 74 65 2e 20 20 49 6e 20 6f 72  obsolete.  In or
259d0 64 65 72 20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a  der to maintain.
259e0 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  ** backwards com
259f0 70 61 74 69 62 69 6c 69 74 79 20 77 69 74 68 20  patibility with 
25a00 6f 6c 64 65 72 20 63 6f 64 65 2c 20 77 65 20 63  older code, we c
25a10 6f 6e 74 69 6e 75 65 20 74 6f 20 73 75 70 70 6f  ontinue to suppo
25a20 72 74 0a 2a 2a 20 74 68 65 73 65 20 66 75 6e 63  rt.** these func
25a30 74 69 6f 6e 73 2e 20 20 48 6f 77 65 76 65 72 2c  tions.  However,
25a40 20 6e 65 77 20 64 65 76 65 6c 6f 70 6d 65 6e 74   new development
25a50 20 70 72 6f 6a 65 63 74 73 20 73 68 6f 75 6c 64   projects should
25a60 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73   avoid.** the us
25a70 65 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74  e of these funct
25a80 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70 20 65  ions.  To help e
25a90 6e 63 6f 75 72 61 67 65 20 70 65 6f 70 6c 65 20  ncourage people 
25aa0 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73 69 6e  to avoid.** usin
25ab0 67 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  g these function
25ac0 73 2c 20 77 65 20 61 72 65 20 6e 6f 74 20 67 6f  s, we are not go
25ad0 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f 75 20  ing to tell you 
25ae0 77 61 6e 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f  want they do..*/
25af0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 67 67  .int sqlite3_agg
25b00 72 65 67 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c  regate_count(sql
25b10 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
25b20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 70 69  int sqlite3_expi
25b30 72 65 64 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  red(sqlite3_stmt
25b40 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
25b50 74 72 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67  transfer_binding
25b60 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  s(sqlite3_stmt*,
25b70 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b   sqlite3_stmt*);
25b80 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f  .int sqlite3_glo
25b90 62 61 6c 5f 72 65 63 6f 76 65 72 28 76 6f 69 64  bal_recover(void
25ba0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
25bb0 74 68 72 65 61 64 5f 63 6c 65 61 6e 75 70 28 76  thread_cleanup(v
25bc0 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  oid);.int sqlite
25bd0 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76  3_memory_alarm(v
25be0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c  oid(*)(void*,sql
25bf0 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c  ite3_int64,int),
25c00 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e  void*,sqlite3_in
25c10 74 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  t64);../*.** CAP
25c20 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67  I3REF: Obtaining
25c30 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 50 61   SQL Function Pa
25c40 72 61 6d 65 74 65 72 20 56 61 6c 75 65 73 20 7b  rameter Values {
25c50 46 31 35 31 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68  F15100}.**.** Th
25c60 65 20 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70  e C-language imp
25c70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53  lementation of S
25c80 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64  QL functions and
25c90 20 61 67 67 72 65 67 61 74 65 73 20 75 73 65 73   aggregates uses
25ca0 0a 2a 2a 20 74 68 69 73 20 73 65 74 20 6f 66 20  .** this set of 
25cb0 69 6e 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e  interface routin
25cc0 65 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65  es to access the
25cd0 20 70 61 72 61 6d 65 74 65 72 20 76 61 6c 75 65   parameter value
25ce0 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63  s on.** the func
25cf0 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74  tion or aggregat
25d00 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75  e..**.** The xFu
25d10 6e 63 20 28 66 6f 72 20 73 63 61 6c 61 72 20 66  nc (for scalar f
25d20 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78 53 74  unctions) or xSt
25d30 65 70 20 28 66 6f 72 20 61 67 67 72 65 67 61 74  ep (for aggregat
25d40 65 73 29 20 70 61 72 61 6d 65 74 65 72 73 0a 2a  es) parameters.*
25d50 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72  * to [sqlite3_cr
25d60 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
25d70 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72   and [sqlite3_cr
25d80 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
25d90 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c  )].** define cal
25da0 6c 62 61 63 6b 73 20 74 68 61 74 20 69 6d 70 6c  lbacks that impl
25db0 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75  ement the SQL fu
25dc0 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72  nctions and aggr
25dd0 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20 34  egates..** The 4
25de0 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
25df0 74 68 65 73 65 20 63 61 6c 6c 62 61 63 6b 73 20  these callbacks 
25e00 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
25e10 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70  ointers to.** [p
25e20 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
25e30 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e  _value] objects.
25e40 20 20 54 68 65 72 65 20 69 73 20 6f 6e 65 20 5b    There is one [
25e50 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
25e60 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63  bject for.** eac
25e70 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
25e80 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e  he SQL function.
25e90 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73    These routines
25ea0 20 61 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20   are used to.** 
25eb0 65 78 74 72 61 63 74 20 76 61 6c 75 65 73 20 66  extract values f
25ec0 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33  rom the [sqlite3
25ed0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e  _value] objects.
25ee0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
25ef0 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20  tines work only 
25f00 77 69 74 68 20 5b 70 72 6f 74 65 63 74 65 64 20  with [protected 
25f10 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
25f20 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61  bjects..** Any a
25f30 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68  ttempt to use th
25f40 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20  ese routines on 
25f50 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  an [unprotected 
25f60 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a  sqlite3_value].*
25f70 2a 20 6f 62 6a 65 63 74 20 72 65 73 75 6c 74 73  * object results
25f80 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65   in undefined be
25f90 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  havior..**.** Th
25fa0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72  ese routines wor
25fb0 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 20  k just like the 
25fc0 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 0a 2a  corresponding .*
25fd0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
25fe0 6e 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33  n_blob | sqlite3
25ff0 5f 63 6f 6c 75 6d 6e 5f 2a 20 72 6f 75 74 69 6e  _column_* routin
26000 65 73 5d 20 65 78 63 65 70 74 20 74 68 61 74 20  es] except that 
26010 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75 74 69 6e  .** these routin
26020 65 73 20 74 61 6b 65 20 61 20 73 69 6e 67 6c 65  es take a single
26030 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
26040 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
26050 74 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 69 6e 73  t pointer.** ins
26060 74 65 61 64 20 6f 66 20 61 6e 20 5b 73 71 6c 69  tead of an [sqli
26070 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74  te3_stmt*] point
26080 65 72 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 65  er and an intege
26090 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e  r column number.
260a0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
260b0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
260c0 29 20 69 6e 74 65 72 66 61 63 65 20 65 78 74 72  ) interface extr
260d0 61 63 74 73 20 61 20 55 54 46 31 36 20 73 74 72  acts a UTF16 str
260e0 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61  ing.** in the na
260f0 74 69 76 65 20 62 79 74 65 2d 6f 72 64 65 72 20  tive byte-order 
26100 6f 66 20 74 68 65 20 68 6f 73 74 20 6d 61 63 68  of the host mach
26110 69 6e 65 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c  ine.  The.** sql
26120 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
26130 36 62 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  6be() and sqlite
26140 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65  3_value_text16le
26150 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  () interfaces.**
26160 20 65 78 74 72 61 63 74 20 55 54 46 31 36 20 73   extract UTF16 s
26170 74 72 69 6e 67 73 20 61 73 20 62 69 67 2d 65 6e  trings as big-en
26180 64 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d  dian and little-
26190 65 6e 64 69 61 6e 20 72 65 73 70 65 63 74 69 76  endian respectiv
261a0 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ely..**.** The s
261b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d  qlite3_value_num
261c0 65 72 69 63 5f 74 79 70 65 28 29 20 69 6e 74 65  eric_type() inte
261d0 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74  rface attempts t
261e0 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72  o apply.** numer
261f0 69 63 20 61 66 66 69 6e 69 74 79 20 74 6f 20 74  ic affinity to t
26200 68 65 20 76 61 6c 75 65 2e 20 20 54 68 69 73 20  he value.  This 
26210 6d 65 61 6e 73 20 74 68 61 74 20 61 6e 20 61 74  means that an at
26220 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65  tempt is.** made
26230 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20   to convert the 
26240 76 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74 65  value to an inte
26250 67 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20  ger or floating 
26260 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75  point.  If.** su
26270 63 68 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20  ch a conversion 
26280 69 73 20 70 6f 73 73 69 62 6c 65 20 77 69 74 68  is possible with
26290 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f  out loss of info
262a0 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65  rmation (in othe
262b0 72 0a 2a 2a 20 77 6f 72 64 73 20 69 66 20 74 68  r.** words if th
262c0 65 20 76 61 6c 75 65 20 69 73 20 61 20 73 74 72  e value is a str
262d0 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c  ing that looks l
262e0 69 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a  ike a number).**
262f0 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 76 65 72   then the conver
26300 73 69 6f 6e 20 69 73 20 64 6f 6e 65 2e 20 20 4f  sion is done.  O
26310 74 68 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76  therwise no conv
26320 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e 20 20  ersion occurs.  
26330 54 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  The .** [SQLITE_
26340 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79  INTEGER | dataty
26350 70 65 5d 20 61 66 74 65 72 20 63 6f 6e 76 65 72  pe] after conver
26360 73 69 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 64  sion is returned
26370 2e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70  ..**.** Please p
26380 61 79 20 70 61 72 74 69 63 75 6c 61 72 20 61 74  ay particular at
26390 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20 66  tention to the f
263a0 61 63 74 20 74 68 61 74 20 74 68 65 20 70 6f 69  act that the poi
263b0 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20  nter that.** is 
263c0 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73  returned from [s
263d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f  qlite3_value_blo
263e0 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76  b()], [sqlite3_v
263f0 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72  alue_text()], or
26400 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  .** [sqlite3_val
26410 75 65 5f 74 65 78 74 31 36 28 29 5d 20 63 61 6e  ue_text16()] can
26420 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 20   be invalidated 
26430 62 79 20 61 20 73 75 62 73 65 71 75 65 6e 74 20  by a subsequent 
26440 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
26450 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28  te3_value_bytes(
26460 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  )], [sqlite3_val
26470 75 65 5f 62 79 74 65 73 31 36 28 29 5d 2c 20 5b  ue_bytes16()], [
26480 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
26490 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71  xt()],.** or [sq
264a0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
264b0 31 36 28 29 5d 2e 20 20 0a 2a 2a 0a 2a 2a 20 54  16()].  .**.** T
264c0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75  hese routines mu
264d0 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f  st be called fro
264e0 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  m the same threa
264f0 64 20 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20  d as.** the SQL 
26500 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 73 75  function that su
26510 70 70 6c 69 65 64 20 74 68 65 20 5b 73 71 6c 69  pplied the [sqli
26520 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72 61  te3_value*] para
26530 6d 65 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 0a 2a 2a  meters..**.**.**
26540 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
26550 2a 2a 20 7b 46 31 35 31 30 33 7d 20 54 68 65 20  ** {F15103} The 
26560 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
26570 6c 6f 62 28 56 29 5d 20 69 6e 74 65 72 66 61 63  lob(V)] interfac
26580 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a  e converts the.*
26590 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74  *          [prot
265a0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
265b0 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e  lue] object V in
265c0 74 6f 20 61 20 62 6c 6f 62 20 61 6e 64 20 74 68  to a blob and th
265d0 65 6e 20 72 65 74 75 72 6e 73 20 61 0a 2a 2a 20  en returns a.** 
265e0 20 20 20 20 20 20 20 20 20 70 6f 69 6e 74 65 72           pointer
265f0 20 74 6f 20 74 68 65 20 63 6f 6e 76 65 72 74 65   to the converte
26600 64 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b  d value..**.** {
26610 46 31 35 31 30 36 7d 20 54 68 65 20 5b 73 71 6c  F15106} The [sql
26620 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
26630 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  (V)] interface r
26640 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20  eturns the.**   
26650 20 20 20 20 20 20 20 6e 75 6d 62 65 72 20 6f 66         number of
26660 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 62 6c   bytes in the bl
26670 6f 62 20 6f 72 20 73 74 72 69 6e 67 20 28 65 78  ob or string (ex
26680 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65 0a 2a  clusive of the.*
26690 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 20  *          zero 
266a0 74 65 72 6d 69 6e 61 74 6f 72 20 6f 6e 20 74 68  terminator on th
266b0 65 20 73 74 72 69 6e 67 29 20 74 68 61 74 20 77  e string) that w
266c0 61 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  as returned by t
266d0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d  he.**          m
266e0 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
266f0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  to [sqlite3_valu
26700 65 5f 62 6c 6f 62 28 56 29 5d 20 6f 72 0a 2a 2a  e_blob(V)] or.**
26710 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
26720 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 56 29  e3_value_text(V)
26730 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31 30 39  ]..**.** {F15109
26740 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  } The [sqlite3_v
26750 61 6c 75 65 5f 62 79 74 65 73 31 36 28 56 29 5d  alue_bytes16(V)]
26760 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
26770 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ns the.**       
26780 20 20 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74     number of byt
26790 65 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67  es in the string
267a0 20 28 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74   (exclusive of t
267b0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a  he.**          z
267c0 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 6f  ero terminator o
267d0 6e 20 74 68 65 20 73 74 72 69 6e 67 29 20 74 68  n the string) th
267e0 61 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 20  at was returned 
267f0 62 79 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  by the.**       
26800 20 20 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63     most recent c
26810 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
26820 76 61 6c 75 65 5f 74 65 78 74 31 36 28 56 29 5d  value_text16(V)]
26830 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  ,.**          [s
26840 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
26850 74 31 36 62 65 28 56 29 5d 2c 20 6f 72 20 5b 73  t16be(V)], or [s
26860 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
26870 74 31 36 6c 65 28 56 29 5d 2e 0a 2a 2a 0a 2a 2a  t16le(V)]..**.**
26880 20 7b 46 31 35 31 31 32 7d 20 54 68 65 20 5b 73   {F15112} The [s
26890 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75  qlite3_value_dou
268a0 62 6c 65 28 56 29 5d 20 69 6e 74 65 72 66 61 63  ble(V)] interfac
268b0 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a  e converts the.*
268c0 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74  *          [prot
268d0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
268e0 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e  lue] object V in
268f0 74 6f 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f  to a floating po
26900 69 6e 74 20 76 61 6c 75 65 20 61 6e 64 0a 2a 2a  int value and.**
26910 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e            return
26920 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 61 74  s a copy of that
26930 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46   value..**.** {F
26940 31 35 31 31 35 7d 20 54 68 65 20 5b 73 71 6c 69  15115} The [sqli
26950 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 56 29  te3_value_int(V)
26960 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76  ] interface conv
26970 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  erts the.**     
26980 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20       [protected 
26990 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
269a0 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20 36  bject V into a 6
269b0 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  4-bit signed int
269c0 65 67 65 72 20 61 6e 64 0a 2a 2a 20 20 20 20 20  eger and.**     
269d0 20 20 20 20 20 72 65 74 75 72 6e 73 20 74 68 65       returns the
269e0 20 6c 6f 77 65 72 20 33 32 20 62 69 74 73 20 6f   lower 32 bits o
269f0 66 20 74 68 61 74 20 69 6e 74 65 67 65 72 2e 0a  f that integer..
26a00 2a 2a 0a 2a 2a 20 7b 46 31 35 31 31 38 7d 20 54  **.** {F15118} T
26a10 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
26a20 65 5f 69 6e 74 36 34 28 56 29 5d 20 69 6e 74 65  e_int64(V)] inte
26a30 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74  rface converts t
26a40 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
26a50 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
26a60 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
26a70 56 20 69 6e 74 6f 20 61 20 36 34 2d 62 69 74 20  V into a 64-bit 
26a80 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61  signed integer a
26a90 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  nd.**          r
26aa0 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66  eturns a copy of
26ab0 20 74 68 61 74 20 69 6e 74 65 67 65 72 2e 0a 2a   that integer..*
26ac0 2a 0a 2a 2a 20 7b 46 31 35 31 32 31 7d 20 54 68  *.** {F15121} Th
26ad0 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
26ae0 5f 74 65 78 74 28 56 29 5d 20 69 6e 74 65 72 66  _text(V)] interf
26af0 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65  ace converts the
26b00 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
26b10 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
26b20 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20  value] object V 
26b30 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d  into a zero-term
26b40 69 6e 61 74 65 64 20 55 54 46 2d 38 20 0a 2a 2a  inated UTF-8 .**
26b50 20 20 20 20 20 20 20 20 20 20 73 74 72 69 6e 67            string
26b60 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70   and returns a p
26b70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20 73  ointer to that s
26b80 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  tring..**.** {F1
26b90 35 31 32 34 7d 20 54 68 65 20 5b 73 71 6c 69 74  5124} The [sqlit
26ba0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
26bb0 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f  V)] interface co
26bc0 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20  nverts the.**   
26bd0 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65         [protecte
26be0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
26bf0 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61   object V into a
26c00 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
26c10 20 32 2d 62 79 74 65 0a 2a 2a 20 20 20 20 20 20   2-byte.**      
26c20 20 20 20 20 61 6c 69 67 6e 65 64 20 55 54 46 2d      aligned UTF-
26c30 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  16 native byte o
26c40 72 64 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  rder.**         
26c50 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75   string and retu
26c60 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
26c70 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a   that string..**
26c80 0a 2a 2a 20 7b 46 31 35 31 32 37 7d 20 54 68 65  .** {F15127} The
26c90 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
26ca0 74 65 78 74 31 36 62 65 28 56 29 5d 20 69 6e 74  text16be(V)] int
26cb0 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20  erface converts 
26cc0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
26cd0 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
26ce0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
26cf0 20 56 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74   V into a zero-t
26d00 65 72 6d 69 6e 61 74 65 64 20 32 2d 62 79 74 65  erminated 2-byte
26d10 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c 69  .**          ali
26d20 67 6e 65 64 20 55 54 46 2d 31 36 20 62 69 67 2d  gned UTF-16 big-
26d30 65 6e 64 69 61 6e 0a 2a 2a 20 20 20 20 20 20 20  endian.**       
26d40 20 20 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65     string and re
26d50 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
26d60 74 6f 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a  to that string..
26d70 2a 2a 0a 2a 2a 20 7b 46 31 35 31 33 30 7d 20 54  **.** {F15130} T
26d80 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
26d90 65 5f 74 65 78 74 31 36 6c 65 28 56 29 5d 20 69  e_text16le(V)] i
26da0 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74  nterface convert
26db0 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
26dc0 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c    [protected sql
26dd0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
26de0 63 74 20 56 20 69 6e 74 6f 20 61 20 7a 65 72 6f  ct V into a zero
26df0 2d 74 65 72 6d 69 6e 61 74 65 64 20 32 2d 62 79  -terminated 2-by
26e00 74 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  te.**          a
26e10 6c 69 67 6e 65 64 20 55 54 46 2d 31 36 20 6c 69  ligned UTF-16 li
26e20 74 74 6c 65 2d 65 6e 64 69 61 6e 0a 2a 2a 20 20  ttle-endian.**  
26e30 20 20 20 20 20 20 20 20 73 74 72 69 6e 67 20 61          string a
26e40 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  nd returns a poi
26e50 6e 74 65 72 20 74 6f 20 74 68 61 74 20 73 74 72  nter to that str
26e60 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31  ing..**.** {F151
26e70 33 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  33} The [sqlite3
26e80 5f 76 61 6c 75 65 5f 74 79 70 65 28 56 29 5d 20  _value_type(V)] 
26e90 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
26ea0 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 6e  s.**          on
26eb0 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4e 55 4c  e of [SQLITE_NUL
26ec0 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  L], [SQLITE_INTE
26ed0 47 45 52 5d 2c 20 5b 53 51 4c 49 54 45 5f 46 4c  GER], [SQLITE_FL
26ee0 4f 41 54 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  OAT],.**        
26ef0 20 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c    [SQLITE_TEXT],
26f00 20 6f 72 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42   or [SQLITE_BLOB
26f10 5d 20 61 73 20 61 70 70 72 6f 70 72 69 61 74 65  ] as appropriate
26f20 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20   for.**         
26f30 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   the [sqlite3_va
26f40 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 2e 0a 2a  lue] object V..*
26f50 2a 0a 2a 2a 20 7b 46 31 35 31 33 36 7d 20 54 68  *.** {F15136} Th
26f60 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
26f70 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 56 29  _numeric_type(V)
26f80 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76  ] interface conv
26f90 65 72 74 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  erts.**         
26fa0 20 74 68 65 20 5b 70 72 6f 74 65 63 74 65 64 20   the [protected 
26fb0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
26fc0 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 65 69 74  bject V into eit
26fd0 68 65 72 20 61 6e 20 69 6e 74 65 67 65 72 20 6f  her an integer o
26fe0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20  r.**          a 
26ff0 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76  floating point v
27000 61 6c 75 65 20 69 66 20 69 74 20 63 61 6e 20 64  alue if it can d
27010 6f 20 73 6f 20 77 69 74 68 6f 75 74 20 6c 6f 73  o so without los
27020 73 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20  s of.**         
27030 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2c 20 61 6e   information, an
27040 64 20 72 65 74 75 72 6e 73 20 6f 6e 65 20 6f 66  d returns one of
27050 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2c 0a   [SQLITE_NULL],.
27060 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c  **          [SQL
27070 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 20 5b 53  ITE_INTEGER], [S
27080 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53  QLITE_FLOAT], [S
27090 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 6f 72 0a  QLITE_TEXT], or.
270a0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c  **          [SQL
270b0 49 54 45 5f 42 4c 4f 42 5d 20 61 73 20 61 70 70  ITE_BLOB] as app
270c0 72 6f 70 72 69 61 74 65 20 66 6f 72 0a 2a 2a 20  ropriate for.** 
270d0 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 70 72           the [pr
270e0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
270f0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20  value] object V 
27100 61 66 74 65 72 20 74 68 65 20 63 6f 6e 76 65 72  after the conver
27110 73 69 6f 6e 20 61 74 74 65 6d 70 74 2e 0a 2a 2f  sion attempt..*/
27120 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
27130 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28  ite3_value_blob(
27140 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
27150 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  .int sqlite3_val
27160 75 65 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33  ue_bytes(sqlite3
27170 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
27180 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
27190 73 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  s16(sqlite3_valu
271a0 65 2a 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69  e*);.double sqli
271b0 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65  te3_value_double
271c0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
271d0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  ;.int sqlite3_va
271e0 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  lue_int(sqlite3_
271f0 76 61 6c 75 65 2a 29 3b 0a 73 71 6c 69 74 65 33  value*);.sqlite3
27200 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 76  _int64 sqlite3_v
27210 61 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c 69 74  alue_int64(sqlit
27220 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73  e3_value*);.cons
27230 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20  t unsigned char 
27240 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  *sqlite3_value_t
27250 65 78 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ext(sqlite3_valu
27260 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  e*);.const void 
27270 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  *sqlite3_value_t
27280 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 76 61  ext16(sqlite3_va
27290 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  lue*);.const voi
272a0 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  d *sqlite3_value
272b0 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65  _text16le(sqlite
272c0 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74  3_value*);.const
272d0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76   void *sqlite3_v
272e0 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 73 71  alue_text16be(sq
272f0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
27300 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
27310 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61  _type(sqlite3_va
27320 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
27330 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63  e3_value_numeric
27340 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61  _type(sqlite3_va
27350 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  lue*);../*.** CA
27360 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41  PI3REF: Obtain A
27370 67 67 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f  ggregate Functio
27380 6e 20 43 6f 6e 74 65 78 74 20 7b 46 31 36 32 31  n Context {F1621
27390 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6d 70  0}.**.** The imp
273a0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61  lementation of a
273b0 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e  ggregate SQL fun
273c0 63 74 69 6f 6e 73 20 75 73 65 20 74 68 69 73 20  ctions use this 
273d0 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63  routine to alloc
273e0 61 74 65 0a 2a 2a 20 61 20 73 74 72 75 63 74 75  ate.** a structu
273f0 72 65 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 74  re for storing t
27400 68 65 69 72 20 73 74 61 74 65 2e 20 20 0a 2a 2a  heir state.  .**
27410 20 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20   The first time 
27420 74 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72  the sqlite3_aggr
27430 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20  egate_context() 
27440 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20 69 73  routine is.** is
27450 20 63 61 6c 6c 65 64 20 66 6f 72 20 61 20 70 61   called for a pa
27460 72 74 69 63 75 6c 61 72 20 61 67 67 72 65 67 61  rticular aggrega
27470 74 65 2c 20 53 51 4c 69 74 65 20 61 6c 6c 6f 63  te, SQLite alloc
27480 61 74 65 73 20 6e 42 79 74 65 73 20 6f 66 20 6d  ates nBytes of m
27490 65 6d 6f 72 79 0a 2a 2a 20 7a 65 72 6f 73 20 74  emory.** zeros t
274a0 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20  hat memory, and 
274b0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
274c0 72 20 74 6f 20 69 74 2e 0a 2a 2a 20 4f 6e 20 73  r to it..** On s
274d0 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71  econd and subseq
274e0 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 73 71  uent calls to sq
274f0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
27500 63 6f 6e 74 65 78 74 28 29 0a 2a 2a 20 66 6f 72  context().** for
27510 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67   the same aggreg
27520 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 64  ate function ind
27530 65 78 2c 20 74 68 65 20 73 61 6d 65 20 62 75 66  ex, the same buf
27540 66 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  fer is returned.
27550 0a 2a 2a 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e  .** The implemen
27560 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 74 68 65  tation.** of the
27570 20 61 67 67 72 65 67 61 74 65 20 63 61 6e 20 75   aggregate can u
27580 73 65 20 74 68 65 20 72 65 74 75 72 6e 65 64 20  se the returned 
27590 62 75 66 66 65 72 20 74 6f 20 61 63 63 75 6d 75  buffer to accumu
275a0 6c 61 74 65 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a  late data..**.**
275b0 20 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69   SQLite automati
275c0 63 61 6c 6c 79 20 66 72 65 65 73 20 74 68 65 20  cally frees the 
275d0 61 6c 6c 6f 63 61 74 65 64 20 62 75 66 66 65 72  allocated buffer
275e0 20 77 68 65 6e 20 74 68 65 20 61 67 67 72 65 67   when the aggreg
275f0 61 74 65 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6e  ate.** query con
27600 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  cludes..**.** Th
27610 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
27620 72 20 73 68 6f 75 6c 64 20 62 65 20 61 20 63 6f  r should be a co
27630 70 79 20 6f 66 20 74 68 65 20 0a 2a 2a 20 5b 73  py of the .** [s
27640 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c  qlite3_context |
27650 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f   SQL function co
27660 6e 74 65 78 74 5d 20 74 68 61 74 20 69 73 20 74  ntext] that is t
27670 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61  he first.** para
27680 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c  meter to the cal
27690 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74 68  lback routine th
276a0 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68  at implements th
276b0 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 66  e aggregate.** f
276c0 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  unction..**.** T
276d0 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74  his routine must
276e0 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
276f0 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
27700 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20  in which.** the 
27710 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75  aggregate SQL fu
27720 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
27730 67 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  g..**.** INVARIA
27740 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32  NTS:.**.** {F162
27750 31 31 7d 20 54 68 65 20 66 69 72 73 74 20 69 6e  11} The first in
27760 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c  vocation of [sql
27770 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
27780 6f 6e 74 65 78 74 28 43 2c 4e 29 5d 20 66 6f 72  ontext(C,N)] for
27790 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 70  .**          a p
277a0 61 72 74 69 63 75 6c 61 72 20 69 6e 73 74 61 6e  articular instan
277b0 63 65 20 6f 66 20 61 6e 20 61 67 67 72 65 67 61  ce of an aggrega
277c0 74 65 20 66 75 6e 63 74 69 6f 6e 20 28 66 6f 72  te function (for
277d0 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a   a particular.**
277e0 20 20 20 20 20 20 20 20 20 20 63 6f 6e 74 65 78            contex
277f0 74 20 43 29 20 63 61 75 73 65 73 20 53 51 4c 69  t C) causes SQLi
27800 74 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e  te to allocation
27810 20 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f   N bytes of memo
27820 72 79 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ry,.**          
27830 7a 65 72 6f 20 74 68 61 74 20 6d 65 6d 6f 72 79  zero that memory
27840 2c 20 61 6e 64 20 72 65 74 75 72 6e 20 61 20 70  , and return a p
27850 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 61 6c  ointer to the al
27860 6c 6f 63 61 74 69 6f 6e 65 64 0a 2a 2a 20 20 20  locationed.**   
27870 20 20 20 20 20 20 20 6d 65 6d 6f 72 79 2e 0a 2a         memory..*
27880 2a 0a 2a 2a 20 7b 46 31 36 32 31 33 7d 20 49 66  *.** {F16213} If
27890 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
278a0 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  tion error occur
278b0 73 20 64 75 72 69 6e 67 0a 2a 2a 20 20 20 20 20  s during.**     
278c0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 61 67       [sqlite3_ag
278d0 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
278e0 43 2c 4e 29 5d 20 74 68 65 6e 20 74 68 65 20 66  C,N)] then the f
278f0 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
27900 30 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32 31 35  0..**.** {F16215
27910 7d 20 53 65 63 6f 6e 64 20 61 6e 64 20 73 75 62  } Second and sub
27920 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69  sequent invocati
27930 6f 6e 73 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20  ons of.**       
27940 20 20 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72     [sqlite3_aggr
27950 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c  egate_context(C,
27960 4e 29 5d 20 66 6f 72 20 74 68 65 20 73 61 6d 65  N)] for the same
27970 20 63 6f 6e 74 65 78 74 20 70 6f 69 6e 74 65 72   context pointer
27980 20 43 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69   C.**          i
27990 67 6e 6f 72 65 20 74 68 65 20 4e 20 70 61 72 61  gnore the N para
279a0 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e  meter and return
279b0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
279c0 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20  e same.**       
279d0 20 20 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f     block of memo
279e0 72 79 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  ry returned by t
279f0 68 65 20 66 69 72 73 74 20 69 6e 76 6f 63 61 74  he first invocat
27a00 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32  ion..**.** {F162
27a10 31 37 7d 20 54 68 65 20 6d 65 6d 6f 72 79 20 61  17} The memory a
27a20 6c 6c 6f 63 61 74 65 64 20 62 79 20 5b 73 71 6c  llocated by [sql
27a30 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
27a40 6f 6e 74 65 78 74 28 43 2c 4e 29 5d 20 69 73 0a  ontext(C,N)] is.
27a50 2a 2a 20 20 20 20 20 20 20 20 20 20 61 75 74 6f  **          auto
27a60 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65 64 20  matically freed 
27a70 6f 6e 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c  on the next call
27a80 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
27a90 65 74 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  et()].**        
27aa0 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69    or [sqlite3_fi
27ab0 6e 61 6c 69 7a 65 28 29 5d 20 66 6f 72 20 74 68  nalize()] for th
27ac0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
27ad0 65 6d 65 6e 74 5d 20 63 6f 6e 74 61 69 6e 69 6e  ement] containin
27ae0 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  g.**          th
27af0 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  e aggregate func
27b00 74 69 6f 6e 20 61 73 73 6f 63 69 61 74 65 64 20  tion associated 
27b10 77 69 74 68 20 63 6f 6e 74 65 78 74 20 43 2e 0a  with context C..
27b20 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
27b30 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
27b40 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  xt(sqlite3_conte
27b50 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73 29  xt*, int nBytes)
27b60 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
27b70 46 3a 20 55 73 65 72 20 44 61 74 61 20 46 6f 72  F: User Data For
27b80 20 46 75 6e 63 74 69 6f 6e 73 20 7b 46 31 36 32   Functions {F162
27b90 34 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  40}.**.** The sq
27ba0 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
27bb0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
27bc0 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a  rns a copy of.**
27bd0 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 68 61   the pointer tha
27be0 74 20 77 61 73 20 74 68 65 20 70 55 73 65 72 44  t was the pUserD
27bf0 61 74 61 20 70 61 72 61 6d 65 74 65 72 20 28 74  ata parameter (t
27c00 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
27c10 29 0a 2a 2a 20 6f 66 20 74 68 65 20 74 68 65 20  ).** of the the 
27c20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
27c30 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61  function()].** a
27c40 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
27c50 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
27c60 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f   routines that o
27c70 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67  riginally.** reg
27c80 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c  istered the appl
27c90 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20  ication defined 
27ca0 66 75 6e 63 74 69 6f 6e 2e 20 7b 45 4e 44 7d 0a  function. {END}.
27cb0 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
27cc0 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  ne must be calle
27cd0 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
27ce0 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a  thread in which.
27cf0 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
27d00 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
27d10 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ion is running..
27d20 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
27d30 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32 34 33 7d  :.**.** {F16243}
27d40 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 75 73   The [sqlite3_us
27d50 65 72 5f 64 61 74 61 28 43 29 5d 20 69 6e 74 65  er_data(C)] inte
27d60 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
27d70 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 20  copy of the.**  
27d80 20 20 20 20 20 20 20 20 50 20 70 6f 69 6e 74 65          P pointe
27d90 72 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69  r from the [sqli
27da0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
27db0 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c  ion(D,X,N,E,P,F,
27dc0 53 2c 4c 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  S,L)].**        
27dd0 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63 72    or [sqlite3_cr
27de0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
27df0 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29  D,X,N,E,P,F,S,L)
27e00 5d 20 63 61 6c 6c 20 74 68 61 74 0a 2a 2a 20 20  ] call that.**  
27e10 20 20 20 20 20 20 20 20 72 65 67 69 73 74 65 72          register
27e20 65 64 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  ed the SQL funct
27e30 69 6f 6e 20 61 73 73 6f 63 69 61 74 65 64 20 77  ion associated w
27e40 69 74 68 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  ith .**         
27e50 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   [sqlite3_contex
27e60 74 5d 20 43 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73  t] C..*/.void *s
27e70 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61  qlite3_user_data
27e80 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
27e90 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
27ea0 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75  REF: Function Au
27eb0 78 69 6c 69 61 72 79 20 44 61 74 61 20 7b 46 31  xiliary Data {F1
27ec0 36 32 37 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20  6270}.**.** The 
27ed0 66 6f 6c 6c 6f 77 69 6e 67 20 74 77 6f 20 66 75  following two fu
27ee0 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 75  nctions may be u
27ef0 73 65 64 20 62 79 20 73 63 61 6c 61 72 20 53 51  sed by scalar SQ
27f00 4c 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a  L functions to.*
27f10 2a 20 61 73 73 6f 63 69 61 74 65 20 6d 65 74 61  * associate meta
27f20 2d 64 61 74 61 20 77 69 74 68 20 61 72 67 75 6d  -data with argum
27f30 65 6e 74 20 76 61 6c 75 65 73 2e 20 49 66 20 74  ent values. If t
27f40 68 65 20 73 61 6d 65 20 76 61 6c 75 65 20 69 73  he same value is
27f50 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 6d 75   passed to.** mu
27f60 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61 74 69 6f  ltiple invocatio
27f70 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 53  ns of the same S
27f80 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64 75 72 69  QL function duri
27f90 6e 67 20 71 75 65 72 79 20 65 78 65 63 75 74 69  ng query executi
27fa0 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d  on, under.** som
27fb0 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20  e circumstances 
27fc0 74 68 65 20 61 73 73 6f 63 69 61 74 65 64 20 6d  the associated m
27fd0 65 74 61 2d 64 61 74 61 20 6d 61 79 20 62 65 20  eta-data may be 
27fe0 70 72 65 73 65 72 76 65 64 2e 20 54 68 69 73 20  preserved. This 
27ff0 6d 61 79 0a 2a 2a 20 62 65 20 75 73 65 64 2c 20  may.** be used, 
28000 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74 6f 20  for example, to 
28010 61 64 64 20 61 20 72 65 67 75 6c 61 72 2d 65 78  add a regular-ex
28020 70 72 65 73 73 69 6f 6e 20 6d 61 74 63 68 69 6e  pression matchin
28030 67 20 73 63 61 6c 61 72 0a 2a 2a 20 66 75 6e 63  g scalar.** func
28040 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70 69 6c  tion. The compil
28050 65 64 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68  ed version of th
28060 65 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73  e regular expres
28070 73 69 6f 6e 20 69 73 20 73 74 6f 72 65 64 20 61  sion is stored a
28080 73 0a 2a 2a 20 6d 65 74 61 2d 64 61 74 61 20 61  s.** meta-data a
28090 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
280a0 68 65 20 53 51 4c 20 76 61 6c 75 65 20 70 61 73  he SQL value pas
280b0 73 65 64 20 61 73 20 74 68 65 20 72 65 67 75 6c  sed as the regul
280c0 61 72 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a  ar expression.**
280d0 20 70 61 74 74 65 72 6e 2e 20 20 54 68 65 20 63   pattern.  The c
280e0 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c 61 72 20  ompiled regular 
280f0 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20 62  expression can b
28100 65 20 72 65 75 73 65 64 20 6f 6e 20 6d 75 6c 74  e reused on mult
28110 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69  iple.** invocati
28120 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ons of the same 
28130 66 75 6e 63 74 69 6f 6e 20 73 6f 20 74 68 61 74  function so that
28140 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 70 61   the original pa
28150 74 74 65 72 6e 20 73 74 72 69 6e 67 0a 2a 2a 20  ttern string.** 
28160 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
28170 20 62 65 20 72 65 63 6f 6d 70 69 6c 65 64 20 6f   be recompiled o
28180 6e 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f  n each invocatio
28190 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  n..**.** The sql
281a0 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
281b0 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
281c0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
281d0 6f 20 74 68 65 20 6d 65 74 61 2d 64 61 74 61 0a  o the meta-data.
281e0 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 62 79  ** associated by
281f0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74   the sqlite3_set
28200 5f 61 75 78 64 61 74 61 28 29 20 66 75 6e 63 74  _auxdata() funct
28210 69 6f 6e 20 77 69 74 68 20 74 68 65 20 4e 74 68  ion with the Nth
28220 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c   argument.** val
28230 75 65 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63  ue to the applic
28240 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
28250 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 49 66 20 6e 6f  nction..** If no
28260 20 6d 65 74 61 2d 64 61 74 61 20 68 61 73 20 62   meta-data has b
28270 65 65 6e 20 65 76 65 72 20 62 65 65 6e 20 73 65  een ever been se
28280 74 20 66 6f 72 20 74 68 65 20 4e 74 68 0a 2a 2a  t for the Nth.**
28290 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65   argument of the
282a0 20 66 75 6e 63 74 69 6f 6e 2c 20 6f 72 20 69 66   function, or if
282b0 20 74 68 65 20 63 6f 6f 72 65 73 70 6f 6e 64 69   the coorespondi
282c0 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61  ng function para
282d0 6d 65 74 65 72 0a 2a 2a 20 68 61 73 20 63 68 61  meter.** has cha
282e0 6e 67 65 64 20 73 69 6e 63 65 20 74 68 65 20 6d  nged since the m
282f0 65 74 61 2d 64 61 74 61 20 77 61 73 20 73 65 74  eta-data was set
28300 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 67  , then sqlite3_g
28310 65 74 5f 61 75 78 64 61 74 61 28 29 0a 2a 2a 20  et_auxdata().** 
28320 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70  returns a NULL p
28330 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  ointer..**.** Th
28340 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  e sqlite3_set_au
28350 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63  xdata() interfac
28360 65 20 73 61 76 65 73 20 74 68 65 20 6d 65 74 61  e saves the meta
28370 2d 64 61 74 61 0a 2a 2a 20 70 6f 69 6e 74 65 64  -data.** pointed
28380 20 74 6f 20 62 79 20 69 74 73 20 33 72 64 20 70   to by its 3rd p
28390 61 72 61 6d 65 74 65 72 20 61 73 20 74 68 65 20  arameter as the 
283a0 6d 65 74 61 2d 64 61 74 61 20 66 6f 72 20 74 68  meta-data for th
283b0 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65  e N-th.** argume
283c0 6e 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  nt of the applic
283d0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
283e0 6e 63 74 69 6f 6e 2e 20 20 53 75 62 73 65 71 75  nction.  Subsequ
283f0 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20  ent.** calls to 
28400 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
28410 61 74 61 28 29 20 6d 69 67 68 74 20 72 65 74 75  ata() might retu
28420 72 6e 20 74 68 69 73 20 64 61 74 61 2c 20 69 66  rn this data, if
28430 20 69 74 20 68 61 73 0a 2a 2a 20 6e 6f 74 20 62   it has.** not b
28440 65 65 6e 20 64 65 73 74 72 6f 79 65 64 2e 20 0a  een destroyed. .
28450 2a 2a 20 49 66 20 69 74 20 69 73 20 6e 6f 74 20  ** If it is not 
28460 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c  NULL, SQLite wil
28470 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73  l invoke the des
28480 74 72 75 63 74 6f 72 20 0a 2a 2a 20 66 75 6e 63  tructor .** func
28490 74 69 6f 6e 20 67 69 76 65 6e 20 62 79 20 74 68  tion given by th
284a0 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
284b0 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  to sqlite3_set_a
284c0 75 78 64 61 74 61 28 29 20 6f 6e 0a 2a 2a 20 74  uxdata() on.** t
284d0 68 65 20 6d 65 74 61 2d 64 61 74 61 20 77 68 65  he meta-data whe
284e0 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  n the correspond
284f0 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70 61 72  ing function par
28500 61 6d 65 74 65 72 20 63 68 61 6e 67 65 73 0a 2a  ameter changes.*
28510 2a 20 6f 72 20 77 68 65 6e 20 74 68 65 20 53 51  * or when the SQ
28520 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70  L statement comp
28530 6c 65 74 65 73 2c 20 77 68 69 63 68 65 76 65 72  letes, whichever
28540 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 0a 2a 2a   comes first..**
28550 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73 20 66 72  .** SQLite is fr
28560 65 65 20 74 6f 20 63 61 6c 6c 20 74 68 65 20 64  ee to call the d
28570 65 73 74 72 75 63 74 6f 72 20 61 6e 64 20 64 72  estructor and dr
28580 6f 70 20 6d 65 74 61 2d 64 61 74 61 20 6f 6e 0a  op meta-data on.
28590 2a 2a 20 61 6e 79 20 70 61 72 61 6d 65 74 65 72  ** any parameter
285a0 20 6f 66 20 61 6e 79 20 66 75 6e 63 74 69 6f 6e   of any function
285b0 20 61 74 20 61 6e 79 20 74 69 6d 65 2e 20 20 54   at any time.  T
285c0 68 65 20 6f 6e 6c 79 20 67 75 61 72 61 6e 74 65  he only guarante
285d0 65 0a 2a 2a 20 69 73 20 74 68 61 74 20 74 68 65  e.** is that the
285e0 20 64 65 73 74 72 75 63 74 6f 72 20 77 69 6c 6c   destructor will
285f0 20 62 65 20 63 61 6c 6c 65 64 20 62 65 66 6f 72   be called befor
28600 65 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 69  e the metadata i
28610 73 0a 2a 2a 20 64 72 6f 70 70 65 64 2e 0a 2a 2a  s.** dropped..**
28620 0a 2a 2a 20 49 6e 20 70 72 61 63 74 69 63 65 2c  .** In practice,
28630 20 6d 65 74 61 2d 64 61 74 61 20 69 73 20 70 72   meta-data is pr
28640 65 73 65 72 76 65 64 20 62 65 74 77 65 65 6e 20  eserved between 
28650 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20 66  function calls f
28660 6f 72 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e  or.** expression
28670 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 73 74  s that are const
28680 61 6e 74 20 61 74 20 63 6f 6d 70 69 6c 65 20 74  ant at compile t
28690 69 6d 65 2e 20 54 68 69 73 20 69 6e 63 6c 75 64  ime. This includ
286a0 65 73 20 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 61  es literal.** va
286b0 6c 75 65 73 20 61 6e 64 20 53 51 4c 20 76 61 72  lues and SQL var
286c0 69 61 62 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  iables..**.** Th
286d0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73  ese routines mus
286e0 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
286f0 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
28700 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65   in which.** the
28710 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73   SQL function is
28720 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20   running..**.** 
28730 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
28740 2a 20 7b 46 31 36 32 37 32 7d 20 54 68 65 20 5b  * {F16272} The [
28750 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
28760 61 74 61 28 43 2c 4e 29 5d 20 69 6e 74 65 72 66  ata(C,N)] interf
28770 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
28780 69 6e 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  inter.**        
28790 20 20 74 6f 20 6d 65 74 61 64 61 74 61 20 61 73    to metadata as
287a0 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
287b0 65 20 4e 74 68 20 70 61 72 61 6d 65 74 65 72 20  e Nth parameter 
287c0 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  of the SQL funct
287d0 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ion.**          
287e0 77 68 6f 73 65 20 63 6f 6e 74 65 78 74 20 69 73  whose context is
287f0 20 43 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74   C, or NULL if t
28800 68 65 72 65 20 69 73 20 6e 6f 20 6d 65 74 61 64  here is no metad
28810 61 74 61 20 61 73 73 6f 63 69 61 74 65 64 0a 2a  ata associated.*
28820 2a 20 20 20 20 20 20 20 20 20 20 77 69 74 68 20  *          with 
28830 74 68 61 74 20 70 61 72 61 6d 65 74 65 72 2e 0a  that parameter..
28840 2a 2a 0a 2a 2a 20 7b 46 31 36 32 37 34 7d 20 54  **.** {F16274} T
28850 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  he [sqlite3_set_
28860 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 44 29  auxdata(C,N,P,D)
28870 5d 20 69 6e 74 65 72 66 61 63 65 20 61 73 73 69  ] interface assi
28880 67 6e 73 20 61 20 6d 65 74 61 64 61 74 61 0a 2a  gns a metadata.*
28890 2a 20 20 20 20 20 20 20 20 20 20 70 6f 69 6e 74  *          point
288a0 65 72 20 50 20 74 6f 20 74 68 65 20 4e 74 68 20  er P to the Nth 
288b0 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65  parameter of the
288c0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 77 69   SQL function wi
288d0 74 68 20 63 6f 6e 74 65 78 74 0a 2a 2a 20 20 20  th context.**   
288e0 20 20 20 20 20 20 20 43 2e 0a 2a 2a 0a 2a 2a 20         C..**.** 
288f0 7b 46 31 36 32 37 36 7d 20 53 51 4c 69 74 65 20  {F16276} SQLite 
28900 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20  will invoke the 
28910 64 65 73 74 72 75 63 74 6f 72 20 44 20 77 69 74  destructor D wit
28920 68 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  h a single argum
28930 65 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ent.**          
28940 77 68 69 63 68 20 69 73 20 74 68 65 20 6d 65 74  which is the met
28950 61 64 61 74 61 20 70 6f 69 6e 74 65 72 20 50 20  adata pointer P 
28960 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c  following a call
28970 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   to.**          
28980 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78  [sqlite3_set_aux
28990 64 61 74 61 28 43 2c 4e 2c 50 2c 44 29 5d 20 77  data(C,N,P,D)] w
289a0 68 65 6e 20 53 51 4c 69 74 65 20 63 65 61 73 65  hen SQLite cease
289b0 73 20 74 6f 20 68 6f 6c 64 0a 2a 2a 20 20 20 20  s to hold.**    
289c0 20 20 20 20 20 20 74 68 65 20 6d 65 74 61 64 61        the metada
289d0 74 61 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32 37  ta..**.** {F1627
289e0 37 7d 20 53 51 4c 69 74 65 20 63 65 61 73 65 73  7} SQLite ceases
289f0 20 74 6f 20 68 6f 6c 64 20 6d 65 74 61 64 61 74   to hold metadat
28a00 61 20 66 6f 72 20 61 6e 20 53 51 4c 20 66 75 6e  a for an SQL fun
28a10 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 0a  ction parameter.
28a20 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68 65 6e  **          when
28a30 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
28a40 61 74 20 70 61 72 61 6d 65 74 65 72 20 63 68 61  at parameter cha
28a50 6e 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  nges..**.** {F16
28a60 32 37 38 7d 20 57 68 65 6e 20 5b 73 71 6c 69 74  278} When [sqlit
28a70 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43  e3_set_auxdata(C
28a80 2c 4e 2c 50 2c 44 29 5d 20 69 73 20 69 6e 76 6f  ,N,P,D)] is invo
28a90 6b 65 64 2c 20 74 68 65 20 64 65 73 74 72 75 63  ked, the destruc
28aa0 74 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  tor.**          
28ab0 69 73 20 63 61 6c 6c 65 64 20 66 6f 72 20 61 6e  is called for an
28ac0 79 20 70 72 69 6f 72 20 6d 65 74 61 64 61 74 61  y prior metadata
28ad0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
28ae0 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69   the same functi
28af0 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63  on.**          c
28b00 6f 6e 74 65 78 74 20 43 20 61 6e 64 20 70 61 72  ontext C and par
28b10 61 6d 65 74 65 72 20 4e 2e 0a 2a 2a 0a 2a 2a 20  ameter N..**.** 
28b20 7b 46 31 36 32 37 39 7d 20 53 51 4c 69 74 65 20  {F16279} SQLite 
28b30 77 69 6c 6c 20 63 61 6c 6c 20 64 65 73 74 72 75  will call destru
28b40 63 74 6f 72 73 20 66 6f 72 20 61 6e 79 20 6d 65  ctors for any me
28b50 74 61 64 61 74 61 20 69 74 20 69 73 20 68 6f 6c  tadata it is hol
28b60 64 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20  ding.**         
28b70 20 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72   in a particular
28b80 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
28b90 6d 65 6e 74 5d 20 53 20 77 68 65 6e 20 65 69 74  ment] S when eit
28ba0 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  her.**          
28bb0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
28bc0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  )] or [sqlite3_f
28bd0 69 6e 61 6c 69 7a 65 28 53 29 5d 20 69 73 20 63  inalize(S)] is c
28be0 61 6c 6c 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  alled..*/.void *
28bf0 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
28c00 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ata(sqlite3_cont
28c10 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 76 6f  ext*, int N);.vo
28c20 69 64 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  id sqlite3_set_a
28c30 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63  uxdata(sqlite3_c
28c40 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20  ontext*, int N, 
28c50 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28  void*, void (*)(
28c60 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a  void*));.../*.**
28c70 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 73 74   CAPI3REF: Const
28c80 61 6e 74 73 20 44 65 66 69 6e 69 6e 67 20 53 70  ants Defining Sp
28c90 65 63 69 61 6c 20 44 65 73 74 72 75 63 74 6f 72  ecial Destructor
28ca0 20 42 65 68 61 76 69 6f 72 20 7b 46 31 30 32 38   Behavior {F1028
28cb0 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61  0}.**.** These a
28cc0 72 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65  re special value
28cd0 20 66 6f 72 20 74 68 65 20 64 65 73 74 72 75 63   for the destruc
28ce0 74 6f 72 20 74 68 61 74 20 69 73 20 70 61 73 73  tor that is pass
28cf0 65 64 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20  ed in as the.** 
28d00 66 69 6e 61 6c 20 61 72 67 75 6d 65 6e 74 20 74  final argument t
28d10 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20  o routines like 
28d20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
28d30 62 6c 6f 62 28 29 5d 2e 20 20 49 66 20 74 68 65  blob()].  If the
28d40 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61   destructor.** a
28d50 72 67 75 6d 65 6e 74 20 69 73 20 53 51 4c 49 54  rgument is SQLIT
28d60 45 5f 53 54 41 54 49 43 2c 20 69 74 20 6d 65 61  E_STATIC, it mea
28d70 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74  ns that the cont
28d80 65 6e 74 20 70 6f 69 6e 74 65 72 20 69 73 20 63  ent pointer is c
28d90 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77  onstant.** and w
28da0 69 6c 6c 20 6e 65 76 65 72 20 63 68 61 6e 67 65  ill never change
28db0 2e 20 20 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e  .  It does not n
28dc0 65 65 64 20 74 6f 20 62 65 20 64 65 73 74 72 6f  eed to be destro
28dd0 79 65 64 2e 20 20 54 68 65 20 0a 2a 2a 20 53 51  yed.  The .** SQ
28de0 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 76  LITE_TRANSIENT v
28df0 61 6c 75 65 20 6d 65 61 6e 73 20 74 68 61 74 20  alue means that 
28e00 74 68 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c  the content will
28e10 20 6c 69 6b 65 6c 79 20 63 68 61 6e 67 65 20 69   likely change i
28e20 6e 0a 2a 2a 20 74 68 65 20 6e 65 61 72 20 66 75  n.** the near fu
28e30 74 75 72 65 20 61 6e 64 20 74 68 61 74 20 53 51  ture and that SQ
28e40 4c 69 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65  Lite should make
28e50 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65   its own private
28e60 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20   copy of.** the 
28e70 63 6f 6e 74 65 6e 74 20 62 65 66 6f 72 65 20 72  content before r
28e80 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  eturning..**.** 
28e90 54 68 65 20 74 79 70 65 64 65 66 20 69 73 20 6e  The typedef is n
28ea0 65 63 65 73 73 61 72 79 20 74 6f 20 77 6f 72 6b  ecessary to work
28eb0 20 61 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73   around problems
28ec0 20 69 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43   in certain.** C
28ed0 2b 2b 20 63 6f 6d 70 69 6c 65 72 73 2e 20 20 53  ++ compilers.  S
28ee0 65 65 20 74 69 63 6b 65 74 20 23 32 31 39 31 2e  ee ticket #2191.
28ef0 0a 2a 2f 0a 74 79 70 65 64 65 66 20 76 6f 69 64  .*/.typedef void
28f00 20 28 2a 73 71 6c 69 74 65 33 5f 64 65 73 74 72   (*sqlite3_destr
28f10 75 63 74 6f 72 5f 74 79 70 65 29 28 76 6f 69 64  uctor_type)(void
28f20 2a 29 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  *);.#define SQLI
28f30 54 45 5f 53 54 41 54 49 43 20 20 20 20 20 20 28  TE_STATIC      (
28f40 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63  (sqlite3_destruc
28f50 74 6f 72 5f 74 79 70 65 29 30 29 0a 23 64 65 66  tor_type)0).#def
28f60 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53  ine SQLITE_TRANS
28f70 49 45 4e 54 20 20 20 28 28 73 71 6c 69 74 65 33  IENT   ((sqlite3
28f80 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65  _destructor_type
28f90 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  )-1)../*.** CAPI
28fa0 33 52 45 46 3a 20 53 65 74 74 69 6e 67 20 54 68  3REF: Setting Th
28fb0 65 20 52 65 73 75 6c 74 20 4f 66 20 41 6e 20 53  e Result Of An S
28fc0 51 4c 20 46 75 6e 63 74 69 6f 6e 20 7b 46 31 36  QL Function {F16
28fd0 34 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  400}.**.** These
28fe0 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73   routines are us
28ff0 65 64 20 62 79 20 74 68 65 20 78 46 75 6e 63 20  ed by the xFunc 
29000 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61  or xFinal callba
29010 63 6b 73 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c  cks that.** impl
29020 65 6d 65 6e 74 20 53 51 4c 20 66 75 6e 63 74 69  ement SQL functi
29030 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74  ons and aggregat
29040 65 73 2e 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c  es.  See.** [sql
29050 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
29060 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  tion()] and [sql
29070 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
29080 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72  tion16()].** for
29090 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   additional info
290a0 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  rmation..**.** T
290b0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 77  hese functions w
290c0 6f 72 6b 20 76 65 72 79 20 6d 75 63 68 20 6c 69  ork very much li
290d0 6b 65 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69  ke the .** [sqli
290e0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20  te3_bind_blob | 
290f0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 5d 20  sqlite3_bind_*] 
29100 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69  family of functi
29110 6f 6e 73 20 75 73 65 64 0a 2a 2a 20 74 6f 20 62  ons used.** to b
29120 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f  ind values to ho
29130 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e  st parameters in
29140 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
29150 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74  ents..** Refer t
29160 6f 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  o the.** [sqlite
29170 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71  3_bind_blob | sq
29180 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 64 6f 63  lite3_bind_* doc
29190 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 0a  umentation] for.
291a0 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  ** additional in
291b0 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
291c0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
291d0 75 6c 74 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72  ult_blob() inter
291e0 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
291f0 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20  sult from.** an 
29200 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69  application defi
29210 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
29220 62 65 20 74 68 65 20 42 4c 4f 42 20 77 68 6f 73  be the BLOB whos
29230 65 20 63 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69  e content is poi
29240 6e 74 65 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68  nted.** to by th
29250 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
29260 65 72 20 61 6e 64 20 77 68 69 63 68 20 69 73 20  er and which is 
29270 4e 20 62 79 74 65 73 20 6c 6f 6e 67 20 77 68 65  N bytes long whe
29280 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74  re N is the.** t
29290 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e 20  hird parameter. 
292a0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
292b0 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28  result_zeroblob(
292c0 29 20 69 6e 65 72 66 61 63 65 73 20 73 65 74 20  ) inerfaces set 
292d0 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a  the result of.**
292e0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
292f0 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f   defined functio
29300 6e 20 74 6f 20 62 65 20 61 20 42 4c 4f 42 20 63  n to be a BLOB c
29310 6f 6e 74 61 69 6e 69 6e 67 20 61 6c 6c 20 7a 65  ontaining all ze
29320 72 6f 0a 2a 2a 20 62 79 74 65 73 20 61 6e 64 20  ro.** bytes and 
29330 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 2c  N bytes in size,
29340 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20   where N is the 
29350 76 61 6c 75 65 20 6f 66 20 74 68 65 20 32 6e 64  value of the 2nd
29360 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
29370 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
29380 73 75 6c 74 5f 64 6f 75 62 6c 65 28 29 20 69 6e  sult_double() in
29390 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
293a0 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20   result from.** 
293b0 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  an application d
293c0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
293d0 74 6f 20 62 65 20 61 20 66 6c 6f 61 74 69 6e 67  to be a floating
293e0 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 73 70 65   point value spe
293f0 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 69 74 73  cified.** by its
29400 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a   2nd argument..*
29410 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
29420 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20  _result_error() 
29430 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  and sqlite3_resu
29440 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 66 75 6e  lt_error16() fun
29450 63 74 69 6f 6e 73 0a 2a 2a 20 63 61 75 73 65 20  ctions.** cause 
29460 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20  the implemented 
29470 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  SQL function to 
29480 74 68 72 6f 77 20 61 6e 20 65 78 63 65 70 74 69  throw an excepti
29490 6f 6e 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73  on..** SQLite us
294a0 65 73 20 74 68 65 20 73 74 72 69 6e 67 20 70 6f  es the string po
294b0 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 0a  inted to by the.
294c0 2a 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  ** 2nd parameter
294d0 20 6f 66 20 73 71 6c 69 74 65 33 5f 72 65 73 75   of sqlite3_resu
294e0 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 20 73 71  lt_error() or sq
294f0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
29500 6f 72 31 36 28 29 0a 2a 2a 20 61 73 20 74 68 65  or16().** as the
29510 20 74 65 78 74 20 6f 66 20 61 6e 20 65 72 72 6f   text of an erro
29520 72 20 6d 65 73 73 61 67 65 2e 20 20 53 51 4c 69  r message.  SQLi
29530 74 65 20 69 6e 74 65 72 70 72 65 74 73 20 74 68  te interprets th
29540 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61  e error.** messa
29550 67 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73  ge string from s
29560 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
29570 72 6f 72 28 29 20 61 73 20 55 54 46 38 2e 20 53  ror() as UTF8. S
29580 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72  QLite.** interpr
29590 65 74 73 20 74 68 65 20 73 74 72 69 6e 67 20 66  ets the string f
295a0 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75  rom sqlite3_resu
295b0 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 61 73 20  lt_error16() as 
295c0 55 54 46 31 36 20 69 6e 20 6e 61 74 69 76 65 0a  UTF16 in native.
295d0 2a 2a 20 62 79 74 65 20 6f 72 64 65 72 2e 20 20  ** byte order.  
295e0 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72  If the third par
295f0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
29600 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
29610 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  .** or sqlite3_r
29620 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20  esult_error16() 
29630 69 73 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e  is negative then
29640 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 61 73   SQLite takes as
29650 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65   the error.** me
29660 73 73 61 67 65 20 61 6c 6c 20 74 65 78 74 20 75  ssage all text u
29670 70 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69  p through the fi
29680 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74  rst zero charact
29690 65 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 74 68  er..** If the th
296a0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
296b0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
296c0 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 73 71  error() or.** sq
296d0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
296e0 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d 6e 65  or16() is non-ne
296f0 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69  gative then SQLi
29700 74 65 20 74 61 6b 65 73 20 74 68 61 74 20 6d 61  te takes that ma
29710 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e 6f 74  ny.** bytes (not
29720 20 63 68 61 72 61 63 74 65 72 73 29 20 66 72 6f   characters) fro
29730 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  m the 2nd parame
29740 74 65 72 20 61 73 20 74 68 65 20 65 72 72 6f 72  ter as the error
29750 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 54 68 65   message..** The
29760 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
29770 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69  error() and sqli
29780 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
29790 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  16().** routines
297a0 20 6d 61 6b 65 20 61 20 63 6f 70 79 20 70 72 69   make a copy pri
297b0 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65  vate copy of the
297c0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74   error message t
297d0 65 78 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68  ext before.** th
297e0 65 79 20 72 65 74 75 72 6e 2e 20 20 48 65 6e 63  ey return.  Henc
297f0 65 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66  e, the calling f
29800 75 6e 63 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c  unction can deal
29810 6c 6f 63 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64  locate or.** mod
29820 69 66 79 20 74 68 65 20 74 65 78 74 20 61 66 74  ify the text aft
29830 65 72 20 74 68 65 79 20 72 65 74 75 72 6e 20 77  er they return w
29840 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20  ithout harm..** 
29850 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
29860 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29 20  lt_error_code() 
29870 66 75 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65 73  function changes
29880 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 0a   the error code.
29890 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 53  ** returned by S
298a0 51 4c 69 74 65 20 61 73 20 61 20 72 65 73 75 6c  QLite as a resul
298b0 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 69 6e  t of an error in
298c0 20 61 20 66 75 6e 63 74 69 6f 6e 2e 20 20 42 79   a function.  By
298d0 20 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 65   default,.** the
298e0 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 53   error code is S
298f0 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 0a 2a 2a  QLITE_ERROR. .**
29900 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
29910 72 65 73 75 6c 74 5f 74 6f 6f 62 69 67 28 29 20  result_toobig() 
29920 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73  interface causes
29930 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 74 68   SQLite.** to th
29940 72 6f 77 20 61 6e 20 65 72 72 6f 72 20 69 6e 64  row an error ind
29950 69 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 73  icating that a s
29960 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73  tring or BLOB is
29970 20 74 6f 20 6c 6f 6e 67 0a 2a 2a 20 74 6f 20 72   to long.** to r
29980 65 70 72 65 73 65 6e 74 2e 20 20 54 68 65 20 73  epresent.  The s
29990 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 6f  qlite3_result_no
299a0 6d 65 6d 28 29 20 69 6e 74 65 72 66 61 63 65 0a  mem() interface.
299b0 2a 2a 20 63 61 75 73 65 73 20 53 51 4c 69 74 65  ** causes SQLite
299c0 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 78 63   to throw an exc
299d0 65 70 74 69 6f 6e 20 69 6e 64 69 63 61 74 69 6e  eption indicatin
299e0 67 20 74 68 61 74 20 74 68 65 20 61 0a 2a 2a 20  g that the a.** 
299f0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
29a00 6e 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20  n failed..**.** 
29a10 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
29a20 6c 74 5f 69 6e 74 28 29 20 69 6e 74 65 72 66 61  lt_int() interfa
29a30 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75  ce sets the retu
29a40 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74  rn value.** of t
29a50 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
29a60 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
29a70 74 6f 20 62 65 20 74 68 65 20 33 32 2d 62 69 74  to be the 32-bit
29a80 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a   signed integer.
29a90 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69  ** value given i
29aa0 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65  n the 2nd argume
29ab0 6e 74 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  nt..** The sqlit
29ac0 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28  e3_result_int64(
29ad0 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
29ae0 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
29af0 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c  e.** of the appl
29b00 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
29b10 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74  function to be t
29b20 68 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  he 64-bit signed
29b30 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75   integer.** valu
29b40 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32  e given in the 2
29b50 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  nd argument..**.
29b60 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
29b70 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e 74  esult_null() int
29b80 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
29b90 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20  return value.** 
29ba0 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
29bb0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
29bc0 69 6f 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a  ion to be NULL..
29bd0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
29be0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 29 2c  3_result_text(),
29bf0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
29c00 74 65 78 74 31 36 28 29 2c 20 0a 2a 2a 20 73 71  text16(), .** sq
29c10 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
29c20 74 31 36 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c  t16le(), and sql
29c30 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
29c40 31 36 62 65 28 29 20 69 6e 74 65 72 66 61 63 65  16be() interface
29c50 73 0a 2a 2a 20 73 65 74 20 74 68 65 20 72 65 74  s.** set the ret
29c60 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65  urn value of the
29c70 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
29c80 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
29c90 20 62 65 0a 2a 2a 20 61 20 74 65 78 74 20 73 74   be.** a text st
29ca0 72 69 6e 67 20 77 68 69 63 68 20 69 73 20 72 65  ring which is re
29cb0 70 72 65 73 65 6e 74 65 64 20 61 73 20 55 54 46  presented as UTF
29cc0 2d 38 2c 20 55 54 46 2d 31 36 20 6e 61 74 69 76  -8, UTF-16 nativ
29cd0 65 20 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a  e byte order,.**
29ce0 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 20 65   UTF-16 little e
29cf0 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36  ndian, or UTF-16
29d00 20 62 69 67 20 65 6e 64 69 61 6e 2c 20 72 65 73   big endian, res
29d10 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 53 51  pectively..** SQ
29d20 4c 69 74 65 20 74 61 6b 65 73 20 74 68 65 20 74  Lite takes the t
29d30 65 78 74 20 72 65 73 75 6c 74 20 66 72 6f 6d 20  ext result from 
29d40 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
29d50 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20  from.** the 2nd 
29d60 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65  parameter of the
29d70 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
29d80 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
29d90 2e 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20  ..** If the 3rd 
29da0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
29db0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
29dc0 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
29dd0 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c  .** is negative,
29de0 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b   then SQLite tak
29df0 65 73 20 72 65 73 75 6c 74 20 74 65 78 74 20 66  es result text f
29e00 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61  rom the 2nd para
29e10 6d 65 74 65 72 20 0a 2a 2a 20 74 68 72 6f 75 67  meter .** throug
29e20 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f  h the first zero
29e30 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49   character..** I
29e40 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65  f the 3rd parame
29e50 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
29e60 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
29e70 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73  interfaces.** is
29e80 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74   non-negative, t
29e90 68 65 6e 20 61 73 20 6d 61 6e 79 20 62 79 74 65  hen as many byte
29ea0 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72  s (not character
29eb0 73 29 20 6f 66 20 74 68 65 20 74 65 78 74 0a 2a  s) of the text.*
29ec0 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20  * pointed to by 
29ed0 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
29ee0 72 20 61 72 65 20 74 61 6b 65 6e 20 61 73 20 74  r are taken as t
29ef0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
29f00 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 69  efined.** functi
29f10 6f 6e 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 49 66  on result..** If
29f20 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74   the 4th paramet
29f30 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
29f40 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
29f50 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20  nterfaces.** or 
29f60 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
29f70 6c 6f 62 20 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c  lob is a non-NUL
29f80 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20  L pointer, then 
29f90 53 51 4c 69 74 65 20 63 61 6c 6c 73 20 74 68 61  SQLite calls tha
29fa0 74 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 61 73  t.** function as
29fb0 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
29fc0 6f 6e 20 74 68 65 20 74 65 78 74 20 6f 72 20 62  on the text or b
29fd0 6c 6f 62 20 72 65 73 75 6c 74 20 77 68 65 6e 20  lob result when 
29fe0 69 74 20 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68  it has.** finish
29ff0 65 64 20 75 73 69 6e 67 20 74 68 61 74 20 72 65  ed using that re
2a000 73 75 6c 74 2e 0a 2a 2a 20 49 66 20 74 68 65 20  sult..** If the 
2a010 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
2a020 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
2a030 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
2a040 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  aces.** or sqlit
2a050 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69  e3_result_blob i
2a060 73 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f  s the special co
2a070 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 53 54  nstant SQLITE_ST
2a080 41 54 49 43 2c 20 74 68 65 6e 0a 2a 2a 20 53 51  ATIC, then.** SQ
2a090 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 61  Lite assumes tha
2a0a0 74 20 74 68 65 20 74 65 78 74 20 6f 72 20 62 6c  t the text or bl
2a0b0 6f 62 20 72 65 73 75 6c 74 20 69 73 20 63 6f 6e  ob result is con
2a0c0 73 74 61 6e 74 20 73 70 61 63 65 20 61 6e 64 0a  stant space and.
2a0d0 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 63 6f 70 79  ** does not copy
2a0e0 20 74 68 65 20 73 70 61 63 65 20 6f 72 20 63 61   the space or ca
2a0f0 6c 6c 20 61 20 64 65 73 74 72 75 63 74 6f 72 20  ll a destructor 
2a100 77 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20 66  when it has.** f
2a110 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68  inished using th
2a120 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 49 66  at result..** If
2a130 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74   the 4th paramet
2a140 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
2a150 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
2a160 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20  nterfaces.** or 
2a170 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
2a180 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65 63 69  lob is the speci
2a190 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49  al constant SQLI
2a1a0 54 45 5f 54 52 41 4e 53 49 45 4e 54 0a 2a 2a 20  TE_TRANSIENT.** 
2a1b0 74 68 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65  then SQLite make
2a1c0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
2a1d0 72 65 73 75 6c 74 20 69 6e 74 6f 20 73 70 61 63  result into spac
2a1e0 65 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a  e obtained from.
2a1f0 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ** from [sqlite3
2a200 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 65 66 6f 72  _malloc()] befor
2a210 65 20 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  e it returns..**
2a220 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
2a230 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69  result_value() i
2a240 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
2a250 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74  e result of.** t
2a260 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
2a270 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
2a280 74 6f 20 62 65 20 61 20 63 6f 70 79 20 74 68 65  to be a copy the
2a290 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64  .** [unprotected
2a2a0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
2a2b0 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 64  object specified
2a2c0 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61   by the 2nd para
2a2d0 6d 65 74 65 72 2e 20 20 54 68 65 0a 2a 2a 20 73  meter.  The.** s
2a2e0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
2a2f0 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  lue() interface 
2a300 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20  makes a copy of 
2a310 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  the [sqlite3_val
2a320 75 65 5d 0a 2a 2a 20 73 6f 20 74 68 61 74 20 5b  ue].** so that [
2a330 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 73  sqlite3_value] s
2a340 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20  pecified in the 
2a350 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 63 68  parameter may ch
2a360 61 6e 67 65 20 6f 72 0a 2a 2a 20 62 65 20 64 65  ange or.** be de
2a370 61 6c 6c 6f 63 61 74 65 64 20 61 66 74 65 72 20  allocated after 
2a380 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
2a390 61 6c 75 65 28 29 20 72 65 74 75 72 6e 73 20 77  alue() returns w
2a3a0 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20  ithout harm..** 
2a3b0 41 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  A [protected sql
2a3c0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
2a3d0 63 74 20 6d 61 79 20 61 6c 77 61 79 73 20 62 65  ct may always be
2a3e0 20 75 73 65 64 20 77 68 65 72 65 20 61 6e 0a 2a   used where an.*
2a3f0 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  * [unprotected s
2a400 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
2a410 6a 65 63 74 20 69 73 20 72 65 71 75 69 72 65 64  ject is required
2a420 2c 20 73 6f 20 65 69 74 68 65 72 0a 2a 2a 20 6b  , so either.** k
2a430 69 6e 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ind of [sqlite3_
2a440 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 63 61  value] object ca
2a450 6e 20 62 65 20 75 73 65 64 20 77 69 74 68 20 74  n be used with t
2a460 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  his interface..*
2a470 2a 0a 2a 2a 20 49 66 20 74 68 65 73 65 20 72 6f  *.** If these ro
2a480 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65  utines are calle
2a490 64 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 74 68  d from within th
2a4a0 65 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65  e different thre
2a4b0 61 64 20 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20  ad .** than the 
2a4c0 6f 6e 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  one containing t
2a4d0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
2a4e0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
2a4f0 74 68 61 74 20 72 65 63 69 65 76 65 64 0a 2a 2a  that recieved.**
2a500 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
2a510 6e 74 65 78 74 5d 20 70 6f 69 6e 74 65 72 2c 20  ntext] pointer, 
2a520 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
2a530 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
2a540 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
2a550 2a 2a 20 7b 46 31 36 34 30 33 7d 20 54 68 65 20  ** {F16403} The 
2a560 64 65 66 61 75 6c 74 20 72 65 74 75 72 6e 20 76  default return v
2a570 61 6c 75 65 20 66 72 6f 6d 20 61 6e 79 20 53 51  alue from any SQ
2a580 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 4e 55  L function is NU
2a590 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 30  LL..**.** {F1640
2a5a0 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  6} The [sqlite3_
2a5b0 72 65 73 75 6c 74 5f 62 6c 6f 62 28 43 2c 56 2c  result_blob(C,V,
2a5c0 4e 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20  N,D)] interface 
2a5d0 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20  changes the.**  
2a5e0 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 76          return v
2a5f0 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e  alue of function
2a600 20 43 20 74 6f 20 62 65 20 61 20 62 6c 6f 62 20   C to be a blob 
2a610 74 68 61 74 20 69 73 20 4e 20 62 79 74 65 73 0a  that is N bytes.
2a620 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 6c  **          in l
2a630 65 6e 67 74 68 20 61 6e 64 20 77 69 74 68 20 63  ength and with c
2a640 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65 64 20 74  ontent pointed t
2a650 6f 20 62 79 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 46  o by V..**.** {F
2a660 31 36 34 30 39 7d 20 54 68 65 20 5b 73 71 6c 69  16409} The [sqli
2a670 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c  te3_result_doubl
2a680 65 28 43 2c 56 29 5d 20 69 6e 74 65 72 66 61 63  e(C,V)] interfac
2a690 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a  e changes the.**
2a6a0 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e            return
2a6b0 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69   value of functi
2a6c0 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65 20 66  on C to be the f
2a6d0 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61  loating point va
2a6e0 6c 75 65 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  lue V..**.** {F1
2a6f0 36 34 31 32 7d 20 54 68 65 20 5b 73 71 6c 69 74  6412} The [sqlit
2a700 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
2a710 43 2c 56 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63  C,V,N)] interfac
2a720 65 20 63 68 61 6e 67 65 73 20 74 68 65 20 72 65  e changes the re
2a730 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  turn.**         
2a740 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69   value of functi
2a750 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e 20 65 78  on C to be an ex
2a760 63 65 70 74 69 6f 6e 20 77 69 74 68 20 65 72 72  ception with err
2a770 6f 72 20 63 6f 64 65 0a 2a 2a 20 20 20 20 20 20  or code.**      
2a780 20 20 20 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f      [SQLITE_ERRO
2a790 52 5d 20 61 6e 64 20 61 20 55 54 46 38 20 65 72  R] and a UTF8 er
2a7a0 72 6f 72 20 6d 65 73 73 61 67 65 20 63 6f 70 69  ror message copi
2a7b0 65 64 20 66 72 6f 6d 20 56 20 75 70 20 74 6f 20  ed from V up to 
2a7c0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
2a7d0 66 69 72 73 74 20 7a 65 72 6f 20 62 79 74 65 20  first zero byte 
2a7e0 6f 72 20 75 6e 74 69 6c 20 4e 20 62 79 74 65 73  or until N bytes
2a7f0 20 61 72 65 20 72 65 61 64 20 69 66 20 4e 20 69   are read if N i
2a800 73 20 70 6f 73 69 74 69 76 65 2e 0a 2a 2a 0a 2a  s positive..**.*
2a810 2a 20 7b 46 31 36 34 31 35 7d 20 54 68 65 20 5b  * {F16415} The [
2a820 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
2a830 72 72 6f 72 31 36 28 43 2c 56 2c 4e 29 5d 20 69  rror16(C,V,N)] i
2a840 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73  nterface changes
2a850 20 74 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 20   the return.**  
2a860 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 6f 66          value of
2a870 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62   function C to b
2a880 65 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 77  e an exception w
2a890 69 74 68 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a  ith error code.*
2a8a0 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49  *          [SQLI
2a8b0 54 45 5f 45 52 52 4f 52 5d 20 61 6e 64 20 61 20  TE_ERROR] and a 
2a8c0 55 54 46 31 36 20 6e 61 74 69 76 65 20 62 79 74  UTF16 native byt
2a8d0 65 20 6f 72 64 65 72 20 65 72 72 6f 72 20 6d 65  e order error me
2a8e0 73 73 61 67 65 0a 2a 2a 20 20 20 20 20 20 20 20  ssage.**        
2a8f0 20 20 63 6f 70 69 65 64 20 66 72 6f 6d 20 56 20    copied from V 
2a900 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  up to the first 
2a910 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20  zero terminator 
2a920 6f 72 20 75 6e 74 69 6c 20 4e 20 62 79 74 65 73  or until N bytes
2a930 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 72 65  .**          are
2a940 20 72 65 61 64 20 69 66 20 4e 20 69 73 20 70 6f   read if N is po
2a950 73 69 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46  sitive..**.** {F
2a960 31 36 34 31 38 7d 20 54 68 65 20 5b 73 71 6c 69  16418} The [sqli
2a970 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
2a980 5f 74 6f 6f 62 69 67 28 43 29 5d 20 69 6e 74 65  _toobig(C)] inte
2a990 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68  rface changes th
2a9a0 65 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20  e return.**     
2a9b0 20 20 20 20 20 76 61 6c 75 65 20 6f 66 20 74 68       value of th
2a9c0 65 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20  e function C to 
2a9d0 62 65 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20  be an exception 
2a9e0 77 69 74 68 20 65 72 72 6f 72 20 63 6f 64 65 0a  with error code.
2a9f0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c  **          [SQL
2aa00 49 54 45 5f 54 4f 4f 42 49 47 5d 20 61 6e 64 20  ITE_TOOBIG] and 
2aa10 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 65  an appropriate e
2aa20 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a  rror message..**
2aa30 0a 2a 2a 20 7b 46 31 36 34 32 31 7d 20 54 68 65  .** {F16421} The
2aa40 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
2aa50 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 43 29 5d  _error_nomem(C)]
2aa60 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67   interface chang
2aa70 65 73 20 74 68 65 20 72 65 74 75 72 6e 0a 2a 2a  es the return.**
2aa80 20 20 20 20 20 20 20 20 20 20 76 61 6c 75 65 20            value 
2aa90 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  of the function 
2aaa0 43 20 74 6f 20 62 65 20 61 6e 20 65 78 63 65 70  C to be an excep
2aab0 74 69 6f 6e 20 77 69 74 68 20 65 72 72 6f 72 20  tion with error 
2aac0 63 6f 64 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  code.**         
2aad0 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20   [SQLITE_NOMEM] 
2aae0 61 6e 64 20 61 6e 20 61 70 70 72 6f 70 72 69 61  and an appropria
2aaf0 74 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  te error message
2ab00 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 32 34 7d  ..**.** {F16424}
2ab10 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   The [sqlite3_re
2ab20 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28  sult_error_code(
2ab30 43 2c 45 29 5d 20 69 6e 74 65 72 66 61 63 65 20  C,E)] interface 
2ab40 63 68 61 6e 67 65 73 20 74 68 65 20 72 65 74 75  changes the retu
2ab50 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76  rn.**          v
2ab60 61 6c 75 65 20 6f 66 20 74 68 65 20 66 75 6e 63  alue of the func
2ab70 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e 20  tion C to be an 
2ab80 65 78 63 65 70 74 69 6f 6e 20 77 69 74 68 20 65  exception with e
2ab90 72 72 6f 72 20 63 6f 64 65 20 45 2e 0a 2a 2a 20  rror code E..** 
2aba0 20 20 20 20 20 20 20 20 20 54 68 65 20 65 72 72           The err
2abb0 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78 74 20  or message text 
2abc0 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a  is unchanged..**
2abd0 0a 2a 2a 20 7b 46 31 36 34 32 37 7d 20 54 68 65  .** {F16427} The
2abe0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
2abf0 5f 69 6e 74 28 43 2c 56 29 5d 20 69 6e 74 65 72  _int(C,V)] inter
2ac00 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65  face changes the
2ac10 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74  .**          ret
2ac20 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e  urn value of fun
2ac30 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68  ction C to be th
2ac40 65 20 33 32 2d 62 69 74 20 69 6e 74 65 67 65 72  e 32-bit integer
2ac50 20 76 61 6c 75 65 20 56 2e 0a 2a 2a 0a 2a 2a 20   value V..**.** 
2ac60 7b 46 31 36 34 33 30 7d 20 54 68 65 20 5b 73 71  {F16430} The [sq
2ac70 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
2ac80 36 34 28 43 2c 56 29 5d 20 69 6e 74 65 72 66 61  64(C,V)] interfa
2ac90 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a  ce changes the.*
2aca0 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72  *          retur
2acb0 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74  n value of funct
2acc0 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65 20  ion C to be the 
2acd0 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 76  64-bit integer v
2ace0 61 6c 75 65 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 46  alue V..**.** {F
2acf0 31 36 34 33 33 7d 20 54 68 65 20 5b 73 71 6c 69  16433} The [sqli
2ad00 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28  te3_result_null(
2ad10 43 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68  C)] interface ch
2ad20 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20  anges the.**    
2ad30 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c        return val
2ad40 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43  ue of function C
2ad50 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a   to be NULL..**.
2ad60 2a 2a 20 7b 46 31 36 34 33 36 7d 20 54 68 65 20  ** {F16436} The 
2ad70 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
2ad80 74 65 78 74 28 43 2c 56 2c 4e 2c 44 29 5d 20 69  text(C,V,N,D)] i
2ad90 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73  nterface changes
2ada0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
2adb0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
2adc0 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62   function C to b
2add0 65 20 74 68 65 20 55 54 46 38 20 73 74 72 69 6e  e the UTF8 strin
2ade0 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 56 20  g.**          V 
2adf0 75 70 20 74 68 72 6f 75 67 68 20 74 68 65 20 66  up through the f
2ae00 69 72 73 74 20 7a 65 72 6f 20 6f 72 20 75 6e 74  irst zero or unt
2ae10 69 6c 20 4e 20 62 79 74 65 73 20 61 72 65 20 72  il N bytes are r
2ae20 65 61 64 20 69 66 20 4e 0a 2a 2a 20 20 20 20 20  ead if N.**     
2ae30 20 20 20 20 20 69 73 20 70 6f 73 69 74 69 76 65       is positive
2ae40 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 33 39 7d  ..**.** {F16439}
2ae50 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   The [sqlite3_re
2ae60 73 75 6c 74 5f 74 65 78 74 31 36 28 43 2c 56 2c  sult_text16(C,V,
2ae70 4e 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20  N,D)] interface 
2ae80 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20  changes the.**  
2ae90 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 76          return v
2aea0 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e  alue of function
2aeb0 20 43 20 74 6f 20 62 65 20 74 68 65 20 55 54 46   C to be the UTF
2aec0 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  16 native byte o
2aed0 72 64 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  rder.**         
2aee0 20 73 74 72 69 6e 67 20 20 56 20 75 70 20 74 68   string  V up th
2aef0 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20  rough the first 
2af00 7a 65 72 6f 20 6f 72 20 75 6e 74 69 6c 20 4e 20  zero or until N 
2af10 62 79 74 65 73 20 61 72 65 20 72 65 61 64 20 69  bytes are read i
2af20 66 20 4e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  f N.**          
2af30 69 73 20 70 6f 73 69 74 69 76 65 2e 0a 2a 2a 0a  is positive..**.
2af40 2a 2a 20 7b 46 31 36 34 34 32 7d 20 54 68 65 20  ** {F16442} The 
2af50 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
2af60 74 65 78 74 31 36 62 65 28 43 2c 56 2c 4e 2c 44  text16be(C,V,N,D
2af70 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61  )] interface cha
2af80 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  nges the.**     
2af90 20 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75       return valu
2afa0 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20  e of function C 
2afb0 74 6f 20 62 65 20 74 68 65 20 55 54 46 31 36 20  to be the UTF16 
2afc0 62 69 67 2d 65 6e 64 69 61 6e 0a 2a 2a 20 20 20  big-endian.**   
2afd0 20 20 20 20 20 20 20 73 74 72 69 6e 67 20 20 56         string  V
2afe0 20 75 70 20 74 68 72 6f 75 67 68 20 74 68 65 20   up through the 
2aff0 66 69 72 73 74 20 7a 65 72 6f 20 6f 72 20 75 6e  first zero or un
2b000 74 69 6c 20 4e 20 62 79 74 65 73 20 61 72 65 20  til N bytes are 
2b010 72 65 61 64 20 69 66 20 4e 0a 2a 2a 20 20 20 20  read if N.**    
2b020 20 20 20 20 20 20 69 73 20 70 6f 73 69 74 69 76        is positiv
2b030 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 34 35  e..**.** {F16445
2b040 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  } The [sqlite3_r
2b050 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 43  esult_text16le(C
2b060 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74 65 72 66 61  ,V,N,D)] interfa
2b070 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a  ce changes the.*
2b080 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72  *          retur
2b090 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74  n value of funct
2b0a0 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65 20  ion C to be the 
2b0b0 55 54 46 31 36 20 6c 69 74 74 6c 65 2d 65 6e 64  UTF16 little-end
2b0c0 69 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ian.**          
2b0d0 73 74 72 69 6e 67 20 20 56 20 75 70 20 74 68 72  string  V up thr
2b0e0 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a  ough the first z
2b0f0 65 72 6f 20 6f 72 20 75 6e 74 69 6c 20 4e 20 62  ero or until N b
2b100 79 74 65 73 20 61 72 65 20 72 65 61 64 20 69 66  ytes are read if
2b110 20 4e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69   N.**          i
2b120 73 20 70 6f 73 69 74 69 76 65 2e 0a 2a 2a 0a 2a  s positive..**.*
2b130 2a 20 7b 46 31 36 34 34 38 7d 20 54 68 65 20 5b  * {F16448} The [
2b140 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
2b150 61 6c 75 65 28 43 2c 56 29 5d 20 69 6e 74 65 72  alue(C,V)] inter
2b160 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65  face changes the
2b170 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74  .**          ret
2b180 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e  urn value of fun
2b190 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 5b 75  ction C to be [u
2b1a0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
2b1b0 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 20 20 20  e3_value].**    
2b1c0 20 20 20 20 20 20 6f 62 6a 65 63 74 20 56 2e 0a        object V..
2b1d0 2a 2a 0a 2a 2a 20 7b 46 31 36 34 35 31 7d 20 54  **.** {F16451} T
2b1e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  he [sqlite3_resu
2b1f0 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 43 2c 4e 29  lt_zeroblob(C,N)
2b200 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e  ] interface chan
2b210 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  ges the.**      
2b220 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65      return value
2b230 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74   of function C t
2b240 6f 20 62 65 20 61 6e 20 4e 2d 62 79 74 65 20 62  o be an N-byte b
2b250 6c 6f 62 20 6f 66 20 61 6c 6c 20 7a 65 72 6f 73  lob of all zeros
2b260 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 35 34 7d  ..**.** {F16454}
2b270 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   The [sqlite3_re
2b280 73 75 6c 74 5f 65 72 72 6f 72 28 29 5d 20 61 6e  sult_error()] an
2b290 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  d [sqlite3_resul
2b2a0 74 5f 65 72 72 6f 72 31 36 28 29 5d 0a 2a 2a 20  t_error16()].** 
2b2b0 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 66 61           interfa
2b2c0 63 65 73 20 6d 61 6b 65 20 61 20 63 6f 70 79 20  ces make a copy 
2b2d0 6f 66 20 74 68 65 69 72 20 65 72 72 6f 72 20 6d  of their error m
2b2e0 65 73 73 61 67 65 20 73 74 72 69 6e 67 73 20 62  essage strings b
2b2f0 65 66 6f 72 65 0a 2a 2a 20 20 20 20 20 20 20 20  efore.**        
2b300 20 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a    returning..**.
2b310 2a 2a 20 7b 46 31 36 34 35 37 7d 20 49 66 20 74  ** {F16457} If t
2b320 68 65 20 44 20 64 65 73 74 72 75 63 74 6f 72 20  he D destructor 
2b330 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
2b340 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
2b350 62 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20  b(C,V,N,D)],.** 
2b360 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
2b370 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 43 2c  3_result_text(C,
2b380 56 2c 4e 2c 44 29 5d 2c 20 5b 73 71 6c 69 74 65  V,N,D)], [sqlite
2b390 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28  3_result_text16(
2b3a0 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20  C,V,N,D)],.**   
2b3b0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
2b3c0 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28  result_text16be(
2b3d0 43 2c 56 2c 4e 2c 44 29 5d 2c 20 6f 72 0a 2a 2a  C,V,N,D)], or.**
2b3e0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
2b3f0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
2b400 6c 65 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 73 20  le(C,V,N,D)] is 
2b410 74 68 65 20 63 6f 6e 73 74 61 6e 74 20 5b 53 51  the constant [SQ
2b420 4c 49 54 45 5f 53 54 41 54 49 43 5d 0a 2a 2a 20  LITE_STATIC].** 
2b430 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 6e 6f           then no
2b440 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 65   destructor is e
2b450 76 65 72 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68  ver called on th
2b460 65 20 70 6f 69 6e 74 65 72 20 56 20 61 6e 64 20  e pointer V and 
2b470 53 51 4c 69 74 65 0a 2a 2a 20 20 20 20 20 20 20  SQLite.**       
2b480 20 20 20 61 73 73 75 6d 65 73 20 74 68 61 74 20     assumes that 
2b490 56 20 69 73 20 69 6d 6d 75 74 61 62 6c 65 2e 0a  V is immutable..
2b4a0 2a 2a 0a 2a 2a 20 7b 46 31 36 34 36 30 7d 20 49  **.** {F16460} I
2b4b0 66 20 74 68 65 20 44 20 64 65 73 74 72 75 63 74  f the D destruct
2b4c0 6f 72 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  or parameter to 
2b4d0 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
2b4e0 62 6c 6f 62 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a  blob(C,V,N,D)],.
2b4f0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
2b500 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
2b510 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 5b 73 71 6c  (C,V,N,D)], [sql
2b520 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
2b530 31 36 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a  16(C,V,N,D)],.**
2b540 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
2b550 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
2b560 62 65 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 6f 72  be(C,V,N,D)], or
2b570 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
2b580 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
2b590 74 31 36 6c 65 28 43 2c 56 2c 4e 2c 44 29 5d 20  t16le(C,V,N,D)] 
2b5a0 69 73 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 0a  is the constant.
2b5b0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c  **          [SQL
2b5c0 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 20 74  ITE_TRANSIENT] t
2b5d0 68 65 6e 20 74 68 65 20 69 6e 74 65 72 66 61 63  hen the interfac
2b5e0 65 73 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20  es makes a copy 
2b5f0 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  of the.**       
2b600 20 20 20 63 6f 6e 74 65 6e 74 20 6f 66 20 56 20     content of V 
2b610 61 6e 64 20 72 65 74 61 69 6e 73 20 74 68 65 20  and retains the 
2b620 63 6f 70 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  copy..**.** {F16
2b630 34 36 33 7d 20 49 66 20 74 68 65 20 44 20 64 65  463} If the D de
2b640 73 74 72 75 63 74 6f 72 20 70 61 72 61 6d 65 74  structor paramet
2b650 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  er to [sqlite3_r
2b660 65 73 75 6c 74 5f 62 6c 6f 62 28 43 2c 56 2c 4e  esult_blob(C,V,N
2b670 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  ,D)],.**        
2b680 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c    [sqlite3_resul
2b690 74 5f 74 65 78 74 28 43 2c 56 2c 4e 2c 44 29 5d  t_text(C,V,N,D)]
2b6a0 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  , [sqlite3_resul
2b6b0 74 5f 74 65 78 74 31 36 28 43 2c 56 2c 4e 2c 44  t_text16(C,V,N,D
2b6c0 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  )],.**          
2b6d0 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
2b6e0 74 65 78 74 31 36 62 65 28 43 2c 56 2c 4e 2c 44  text16be(C,V,N,D
2b6f0 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20  )], or.**       
2b700 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75     [sqlite3_resu
2b710 6c 74 5f 74 65 78 74 31 36 6c 65 28 43 2c 56 2c  lt_text16le(C,V,
2b720 4e 2c 44 29 5d 20 69 73 20 73 6f 6d 65 20 76 61  N,D)] is some va
2b730 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e 0a 2a  lue other than.*
2b740 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 63  *          the c
2b750 6f 6e 73 74 61 6e 74 73 20 5b 53 51 4c 49 54 45  onstants [SQLITE
2b760 5f 53 54 41 54 49 43 5d 20 61 6e 64 20 5b 53 51  _STATIC] and [SQ
2b770 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 20  LITE_TRANSIENT] 
2b780 74 68 65 6e 20 0a 2a 2a 20 20 20 20 20 20 20 20  then .**        
2b790 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e    SQLite will in
2b7a0 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75 63  voke the destruc
2b7b0 74 6f 72 20 44 20 77 69 74 68 20 56 20 61 73 20  tor D with V as 
2b7c0 69 74 73 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e  its only argumen
2b7d0 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68  t.**          wh
2b7e0 65 6e 20 69 74 20 68 61 73 20 66 69 6e 69 73 68  en it has finish
2b7f0 65 64 20 77 69 74 68 20 74 68 65 20 56 20 76 61  ed with the V va
2b800 6c 75 65 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  lue..*/.void sql
2b810 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
2b820 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2b830 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
2b840 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
2b850 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  d*));.void sqlit
2b860 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65  e3_result_double
2b870 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2b880 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a 76 6f 69 64  *, double);.void
2b890 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2b8a0 65 72 72 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f  error(sqlite3_co
2b8b0 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68  ntext*, const ch
2b8c0 61 72 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20  ar*, int);.void 
2b8d0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
2b8e0 72 72 6f 72 31 36 28 73 71 6c 69 74 65 33 5f 63  rror16(sqlite3_c
2b8f0 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
2b900 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64  oid*, int);.void
2b910 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2b920 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 73 71 6c  error_toobig(sql
2b930 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
2b940 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
2b950 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28  ult_error_nomem(
2b960 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2b970 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
2b980 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64  result_error_cod
2b990 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
2b9a0 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73  t*, int);.void s
2b9b0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
2b9c0 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t(sqlite3_contex
2b9d0 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73  t*, int);.void s
2b9e0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
2b9f0 74 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  t64(sqlite3_cont
2ba00 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ext*, sqlite3_in
2ba10 74 36 34 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  t64);.void sqlit
2ba20 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 73  e3_result_null(s
2ba30 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
2ba40 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
2ba50 65 73 75 6c 74 5f 74 65 78 74 28 73 71 6c 69 74  esult_text(sqlit
2ba60 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
2ba70 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 2c 20 76  st char*, int, v
2ba80 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
2ba90 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
2baa0 75 6c 74 5f 74 65 78 74 31 36 28 73 71 6c 69 74  ult_text16(sqlit
2bab0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
2bac0 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76  st void*, int, v
2bad0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
2bae0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
2baf0 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 73 71 6c  ult_text16le(sql
2bb00 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
2bb10 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
2bb20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
2bb30 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
2bb40 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 73 71  sult_text16be(sq
2bb50 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
2bb60 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
2bb70 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29  ,void(*)(void*))
2bb80 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
2bb90 65 73 75 6c 74 5f 76 61 6c 75 65 28 73 71 6c 69  esult_value(sqli
2bba0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71  te3_context*, sq
2bbb0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 76  lite3_value*);.v
2bbc0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
2bbd0 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69  lt_zeroblob(sqli
2bbe0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
2bbf0 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  t n);../*.** CAP
2bc00 49 33 52 45 46 3a 20 44 65 66 69 6e 65 20 4e 65  I3REF: Define Ne
2bc10 77 20 43 6f 6c 6c 61 74 69 6e 67 20 53 65 71 75  w Collating Sequ
2bc20 65 6e 63 65 73 20 7b 46 31 36 36 30 30 7d 0a 2a  ences {F16600}.*
2bc30 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74  *.** These funct
2bc40 69 6f 6e 73 20 61 72 65 20 75 73 65 64 20 74 6f  ions are used to
2bc50 20 61 64 64 20 6e 65 77 20 63 6f 6c 6c 61 74 69   add new collati
2bc60 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 74 6f 20  on sequences to 
2bc70 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 2a  the.** [sqlite3*
2bc80 5d 20 68 61 6e 64 6c 65 20 73 70 65 63 69 66 69  ] handle specifi
2bc90 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20  ed as the first 
2bca0 61 72 67 75 6d 65 6e 74 2e 20 0a 2a 2a 0a 2a 2a  argument. .**.**
2bcb0 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   The name of the
2bcc0 20 6e 65 77 20 63 6f 6c 6c 61 74 69 6f 6e 20 73   new collation s
2bcd0 65 71 75 65 6e 63 65 20 69 73 20 73 70 65 63 69  equence is speci
2bce0 66 69 65 64 20 61 73 20 61 20 55 54 46 2d 38 20  fied as a UTF-8 
2bcf0 73 74 72 69 6e 67 0a 2a 2a 20 66 6f 72 20 73 71  string.** for sq
2bd00 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
2bd10 6c 61 74 69 6f 6e 28 29 20 61 6e 64 20 73 71 6c  lation() and sql
2bd20 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
2bd30 61 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e  ation_v2().** an
2bd40 64 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e  d a UTF-16 strin
2bd50 67 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72  g for sqlite3_cr
2bd60 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36  eate_collation16
2bd70 28 29 2e 20 49 6e 20 61 6c 6c 20 63 61 73 65 73  (). In all cases
2bd80 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 69 73 20  .** the name is 
2bd90 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65  passed as the se
2bda0 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72  cond function ar
2bdb0 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  gument..**.** Th
2bdc0 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
2bdd0 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66 20 74   may be one of t
2bde0 68 65 20 63 6f 6e 73 74 61 6e 74 73 20 5b 53 51  he constants [SQ
2bdf0 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 5b  LITE_UTF8],.** [
2be00 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 20  SQLITE_UTF16LE] 
2be10 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  or [SQLITE_UTF16
2be20 42 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 20  BE], indicating 
2be30 74 68 61 74 20 74 68 65 20 75 73 65 72 2d 73 75  that the user-su
2be40 70 70 6c 69 65 64 0a 2a 2a 20 72 6f 75 74 69 6e  pplied.** routin
2be50 65 20 65 78 70 65 63 74 73 20 74 6f 20 62 65 20  e expects to be 
2be60 70 61 73 73 65 64 20 70 6f 69 6e 74 65 72 73 20  passed pointers 
2be70 74 6f 20 73 74 72 69 6e 67 73 20 65 6e 63 6f 64  to strings encod
2be80 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38 2c 0a  ed using UTF-8,.
2be90 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65  ** UTF-16 little
2bea0 2d 65 6e 64 69 61 6e 20 6f 72 20 55 54 46 2d 31  -endian or UTF-1
2beb0 36 20 62 69 67 2d 65 6e 64 69 61 6e 20 72 65 73  6 big-endian res
2bec0 70 65 63 74 69 76 65 6c 79 2e 20 54 68 65 0a 2a  pectively. The.*
2bed0 2a 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  * third argument
2bee0 20 6d 69 67 68 74 20 61 6c 73 6f 20 62 65 20 5b   might also be [
2bef0 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49  SQLITE_UTF16_ALI
2bf00 47 4e 45 44 5d 20 74 6f 20 69 6e 64 69 63 61 74  GNED] to indicat
2bf10 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 72 6f  e that.** the ro
2bf20 75 74 69 6e 65 20 65 78 70 65 63 74 73 20 70 6f  utine expects po
2bf30 69 6e 74 65 72 73 20 74 6f 20 31 36 2d 62 69 74  inters to 16-bit
2bf40 20 77 6f 72 64 20 61 6c 69 67 6e 65 64 20 73 74   word aligned st
2bf50 72 69 6e 67 73 0a 2a 2a 20 6f 66 20 55 54 46 31  rings.** of UTF1
2bf60 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20  6 in the native 
2bf70 62 79 74 65 20 6f 72 64 65 72 20 6f 66 20 74 68  byte order of th
2bf80 65 20 68 6f 73 74 20 63 6f 6d 70 75 74 65 72 2e  e host computer.
2bf90 0a 2a 2a 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72  .**.** A pointer
2bfa0 20 74 6f 20 74 68 65 20 75 73 65 72 20 73 75 70   to the user sup
2bfb0 70 6c 69 65 64 20 72 6f 75 74 69 6e 65 20 6d 75  plied routine mu
2bfc0 73 74 20 62 65 20 70 61 73 73 65 64 20 61 73 20  st be passed as 
2bfd0 74 68 65 20 66 69 66 74 68 0a 2a 2a 20 61 72 67  the fifth.** arg
2bfe0 75 6d 65 6e 74 2e 20 20 49 66 20 69 74 20 69 73  ument.  If it is
2bff0 20 4e 55 4c 4c 2c 20 74 68 69 73 20 69 73 20 74   NULL, this is t
2c000 68 65 20 73 61 6d 65 20 61 73 20 64 65 6c 65 74  he same as delet
2c010 69 6e 67 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f  ing the collatio
2c020 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 28 73  n.** sequence (s
2c030 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61  o that SQLite ca
2c040 6e 6e 6f 74 20 63 61 6c 6c 20 69 74 20 61 6e 79  nnot call it any
2c050 6d 6f 72 65 29 2e 0a 2a 2a 20 45 61 63 68 20 74  more)..** Each t
2c060 69 6d 65 20 74 68 65 20 61 70 70 6c 69 63 61 74  ime the applicat
2c070 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20  ion.** supplied 
2c080 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f  function is invo
2c090 6b 65 64 2c 20 69 74 20 69 73 20 70 61 73 73 65  ked, it is passe
2c0a0 64 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  d a copy of the 
2c0b0 76 6f 69 64 2a 20 70 61 73 73 65 64 20 61 73 0a  void* passed as.
2c0c0 2a 2a 20 74 68 65 20 66 6f 75 72 74 68 20 61 72  ** the fourth ar
2c0d0 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
2c0e0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
2c0f0 6f 6e 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74  on() or.** sqlit
2c100 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
2c110 69 6f 6e 31 36 28 29 20 61 73 20 69 74 73 20 66  ion16() as its f
2c120 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 0a  irst parameter..
2c130 2a 2a 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e  **.** The remain
2c140 69 6e 67 20 61 72 67 75 6d 65 6e 74 73 20 74 6f  ing arguments to
2c150 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
2c160 2d 73 75 70 70 6c 69 65 64 20 72 6f 75 74 69 6e  -supplied routin
2c170 65 20 61 72 65 20 74 77 6f 20 73 74 72 69 6e 67  e are two string
2c180 73 2c 0a 2a 2a 20 65 61 63 68 20 72 65 70 72 65  s,.** each repre
2c190 73 65 6e 74 65 64 20 62 79 20 61 20 28 6c 65 6e  sented by a (len
2c1a0 67 74 68 2c 20 64 61 74 61 29 20 70 61 69 72 20  gth, data) pair 
2c1b0 61 6e 64 20 65 6e 63 6f 64 65 64 20 69 6e 20 74  and encoded in t
2c1c0 68 65 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 74  he encoding.** t
2c1d0 68 61 74 20 77 61 73 20 70 61 73 73 65 64 20 61  hat was passed a
2c1e0 73 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75  s the third argu
2c1f0 6d 65 6e 74 20 77 68 65 6e 20 74 68 65 20 63 6f  ment when the co
2c200 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
2c210 20 77 61 73 0a 2a 2a 20 72 65 67 69 73 74 65 72   was.** register
2c220 65 64 2e 20 7b 45 4e 44 7d 20 54 68 65 20 61 70  ed. {END} The ap
2c230 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65  plication define
2c240 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 72 6f 75 74  d collation rout
2c250 69 6e 65 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65  ine should.** re
2c260 74 75 72 6e 20 6e 65 67 61 74 69 76 65 2c 20 7a  turn negative, z
2c270 65 72 6f 20 6f 72 20 70 6f 73 69 74 69 76 65 20  ero or positive 
2c280 69 66 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20  if.** the first 
2c290 73 74 72 69 6e 67 20 69 73 20 6c 65 73 73 20 74  string is less t
2c2a0 68 61 6e 2c 20 65 71 75 61 6c 20 74 6f 2c 20 6f  han, equal to, o
2c2b0 72 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 74  r greater than t
2c2c0 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 73 74 72  he second.** str
2c2d0 69 6e 67 2e 20 69 2e 65 2e 20 28 53 54 52 49 4e  ing. i.e. (STRIN
2c2e0 47 31 20 2d 20 53 54 52 49 4e 47 32 29 2e 0a 2a  G1 - STRING2)..*
2c2f0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
2c300 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
2c310 6e 5f 76 32 28 29 20 77 6f 72 6b 73 20 6c 69 6b  n_v2() works lik
2c320 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  e sqlite3_create
2c330 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20  _collation().** 
2c340 65 78 63 61 70 74 20 74 68 61 74 20 69 74 20 74  excapt that it t
2c350 61 6b 65 73 20 61 6e 20 65 78 74 72 61 20 61 72  akes an extra ar
2c360 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
2c370 61 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72  a destructor for
2c380 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f  .** the collatio
2c390 6e 2e 20 20 54 68 65 20 64 65 73 74 72 75 63 74  n.  The destruct
2c3a0 6f 72 20 69 73 20 63 61 6c 6c 65 64 20 77 68 65  or is called whe
2c3b0 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20  n the collation 
2c3c0 69 73 0a 2a 2a 20 64 65 73 74 72 6f 79 65 64 20  is.** destroyed 
2c3d0 61 6e 64 20 69 73 20 70 61 73 73 65 64 20 61 20  and is passed a 
2c3e0 63 6f 70 79 20 6f 66 20 74 68 65 20 66 6f 75 72  copy of the four
2c3f0 74 68 20 70 61 72 61 6d 65 74 65 72 20 76 6f 69  th parameter voi
2c400 64 2a 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 6f 66  d* pointer.** of
2c410 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65   the sqlite3_cre
2c420 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
2c430 28 29 2e 0a 2a 2a 20 43 6f 6c 6c 61 74 69 6f 6e  ()..** Collation
2c440 73 20 61 72 65 20 64 65 73 74 72 6f 79 65 64 20  s are destroyed 
2c450 77 68 65 6e 0a 2a 2a 20 74 68 65 79 20 61 72 65  when.** they are
2c460 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20 6c   overridden by l
2c470 61 74 65 72 20 63 61 6c 6c 73 20 74 6f 20 74 68  ater calls to th
2c480 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 72 65 61  e collation crea
2c490 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 0a 2a  tion functions.*
2c4a0 2a 20 6f 72 20 77 68 65 6e 20 74 68 65 20 5b 73  * or when the [s
2c4b0 71 6c 69 74 65 33 2a 5d 20 64 61 74 61 62 61 73  qlite3*] databas
2c4c0 65 20 68 61 6e 64 6c 65 20 69 73 20 63 6c 6f 73  e handle is clos
2c4d0 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
2c4e0 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a  3_close()]..**.*
2c4f0 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
2c500 0a 2a 2a 20 7b 46 31 36 36 30 33 7d 20 41 20 73  .** {F16603} A s
2c510 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74  uccessful call t
2c520 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  o the.**        
2c530 20 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74    [sqlite3_creat
2c540 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42  e_collation_v2(B
2c550 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 20 69 6e 74  ,X,E,P,F,D)] int
2c560 65 72 66 61 63 65 0a 2a 2a 20 20 20 20 20 20 20  erface.**       
2c570 20 20 20 72 65 67 69 73 74 65 72 73 20 66 75 6e     registers fun
2c580 63 74 69 6f 6e 20 46 20 61 73 20 74 68 65 20 63  ction F as the c
2c590 6f 6d 70 61 72 69 73 6f 6e 20 66 75 6e 63 74 69  omparison functi
2c5a0 6f 6e 20 75 73 65 64 20 74 6f 0a 2a 2a 20 20 20  on used to.**   
2c5b0 20 20 20 20 20 20 20 69 6d 70 6c 65 6d 65 6e 74         implement
2c5c0 20 63 6f 6c 6c 61 74 69 6f 6e 20 58 20 6f 6e 20   collation X on 
2c5d0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2c5e0 74 69 6f 6e 5d 20 42 20 66 6f 72 0a 2a 2a 20 20  tion] B for.**  
2c5f0 20 20 20 20 20 20 20 20 64 61 74 61 62 61 73 65          database
2c600 73 20 68 61 76 69 6e 67 20 65 6e 63 6f 64 69 6e  s having encodin
2c610 67 20 45 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36  g E..**.** {F166
2c620 30 34 7d 20 53 51 4c 69 74 65 20 75 6e 64 65 72  04} SQLite under
2c630 73 74 61 6e 64 73 20 74 68 65 20 58 20 70 61 72  stands the X par
2c640 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 20 20 20  ameter to.**    
2c650 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63        [sqlite3_c
2c660 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
2c670 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d  v2(B,X,E,P,F,D)]
2c680 20 61 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   as a zero-termi
2c690 6e 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  nated.**        
2c6a0 20 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 69    UTF-8 string i
2c6b0 6e 20 77 68 69 63 68 20 63 61 73 65 20 69 73 20  n which case is 
2c6c0 69 67 6e 6f 72 65 64 20 66 6f 72 20 41 53 43 49  ignored for ASCI
2c6d0 49 20 63 68 61 72 61 63 74 65 72 73 20 61 6e 64  I characters and
2c6e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20  .**          is 
2c6f0 73 69 67 6e 69 66 69 63 61 6e 74 20 66 6f 72 20  significant for 
2c700 6e 6f 6e 2d 41 53 43 49 49 20 63 68 61 72 61 63  non-ASCII charac
2c710 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  ters..**.** {F16
2c720 36 30 36 7d 20 53 75 63 63 65 73 73 69 76 65 20  606} Successive 
2c730 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
2c740 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
2c750 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c  on_v2(B,X,E,P,F,
2c760 44 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  D)].**          
2c770 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 76 61  with the same va
2c780 6c 75 65 73 20 66 6f 72 20 42 2c 20 58 2c 20 61  lues for B, X, a
2c790 6e 64 20 45 2c 20 6f 76 65 72 72 69 64 65 20 70  nd E, override p
2c7a0 72 69 6f 72 20 76 61 6c 75 65 73 0a 2a 2a 20 20  rior values.**  
2c7b0 20 20 20 20 20 20 20 20 6f 66 20 50 2c 20 46 2c          of P, F,
2c7c0 20 61 6e 64 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46   and D..**.** {F
2c7d0 31 36 36 30 39 7d 20 54 68 65 20 64 65 73 74 72  16609} The destr
2c7e0 75 63 74 6f 72 20 44 20 69 6e 20 5b 73 71 6c 69  uctor D in [sqli
2c7f0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
2c800 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c  tion_v2(B,X,E,P,
2c810 46 2c 44 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  F,D)].**        
2c820 20 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68    is not NULL th
2c830 65 6e 20 69 74 20 69 73 20 63 61 6c 6c 65 64 20  en it is called 
2c840 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 50 20  with argument P 
2c850 77 68 65 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20  when the.**     
2c860 20 20 20 20 20 63 6f 6c 6c 61 74 69 6e 67 20 66       collating f
2c870 75 6e 63 74 69 6f 6e 20 69 73 20 64 72 6f 70 70  unction is dropp
2c880 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2a  ed by SQLite..**
2c890 0a 2a 2a 20 7b 46 31 36 36 31 32 7d 20 41 20 63  .** {F16612} A c
2c8a0 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
2c8b0 6e 20 69 73 20 64 72 6f 70 70 65 64 20 77 68 65  n is dropped whe
2c8c0 6e 20 69 74 20 69 73 20 6f 76 65 72 6c 6f 61 64  n it is overload
2c8d0 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36 31  ed..**.** {F1661
2c8e0 35 7d 20 41 20 63 6f 6c 6c 61 74 69 6e 67 20 66  5} A collating f
2c8f0 75 6e 63 74 69 6f 6e 20 69 73 20 64 72 6f 70 70  unction is dropp
2c900 65 64 20 77 68 65 6e 20 74 68 65 20 64 61 74 61  ed when the data
2c910 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
2c920 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 63  **          is c
2c930 6c 6f 73 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  losed using [sql
2c940 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a  ite3_close()]..*
2c950 2a 0a 2a 2a 20 7b 46 31 36 36 31 38 7d 20 54 68  *.** {F16618} Th
2c960 65 20 70 6f 69 6e 74 65 72 20 50 20 69 6e 20 5b  e pointer P in [
2c970 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
2c980 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c  ollation_v2(B,X,
2c990 45 2c 50 2c 46 2c 44 29 5d 0a 2a 2a 20 20 20 20  E,P,F,D)].**    
2c9a0 20 20 20 20 20 20 69 73 20 70 61 73 73 65 64 20        is passed 
2c9b0 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 66  through as the f
2c9c0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
2c9d0 6f 20 74 68 65 20 63 6f 6d 70 61 72 69 73 6f 6e  o the comparison
2c9e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 75 6e  .**          fun
2c9f0 63 74 69 6f 6e 20 46 20 66 6f 72 20 61 6c 6c 20  ction F for all 
2ca00 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63  subsequent invoc
2ca10 61 74 69 6f 6e 73 20 6f 66 20 46 2e 0a 2a 2a 0a  ations of F..**.
2ca20 2a 2a 20 7b 46 31 36 36 32 31 7d 20 41 20 63 61  ** {F16621} A ca
2ca30 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
2ca40 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
2ca50 42 2c 58 2c 45 2c 50 2c 46 29 5d 20 69 73 20 65  B,X,E,P,F)] is e
2ca60 78 61 63 74 6c 79 0a 2a 2a 20 20 20 20 20 20 20  xactly.**       
2ca70 20 20 20 74 68 65 20 73 61 6d 65 20 61 73 20 61     the same as a
2ca80 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
2ca90 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
2caa0 6f 6e 5f 76 32 28 29 5d 20 77 69 74 68 0a 2a 2a  on_v2()] with.**
2cab0 20 20 20 20 20 20 20 20 20 20 74 68 65 20 73 61            the sa
2cac0 6d 65 20 70 61 72 61 6d 65 74 65 72 73 20 61 6e  me parameters an
2cad0 64 20 61 20 4e 55 4c 4c 20 64 65 73 74 72 75 63  d a NULL destruc
2cae0 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36  tor..**.** {F166
2caf0 32 34 7d 20 46 6f 6c 6c 6f 77 69 6e 67 20 61 20  24} Following a 
2cb00 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2cb10 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c 58  collation_v2(B,X
2cb20 2c 45 2c 50 2c 46 2c 44 29 5d 2c 0a 2a 2a 20 20  ,E,P,F,D)],.**  
2cb30 20 20 20 20 20 20 20 20 53 51 4c 69 74 65 20 75          SQLite u
2cb40 73 65 73 20 74 68 65 20 63 6f 6d 70 61 72 69 73  ses the comparis
2cb50 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 46 20 66 6f  on function F fo
2cb60 72 20 61 6c 6c 20 74 65 78 74 20 63 6f 6d 70 61  r all text compa
2cb70 72 69 73 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20  rison.**        
2cb80 20 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20    operations on 
2cb90 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2cba0 74 69 6f 6e 5d 20 42 20 6f 6e 20 74 65 78 74 20  tion] B on text 
2cbb0 76 61 6c 75 65 73 20 74 68 61 74 0a 2a 2a 20 20  values that.**  
2cbc0 20 20 20 20 20 20 20 20 75 73 65 20 74 68 65 20          use the 
2cbd0 63 6f 6c 6c 61 74 69 6e 67 20 73 65 71 75 65 6e  collating sequen
2cbe0 63 65 20 6e 61 6d 65 20 58 2e 0a 2a 2a 0a 2a 2a  ce name X..**.**
2cbf0 20 7b 46 31 36 36 32 37 7d 20 54 68 65 20 5b 73   {F16627} The [s
2cc00 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
2cc10 6c 6c 61 74 69 6f 6e 31 36 28 42 2c 58 2c 45 2c  llation16(B,X,E,
2cc20 50 2c 46 29 5d 20 77 6f 72 6b 73 20 74 68 65 20  P,F)] works the 
2cc30 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  same.**         
2cc40 20 61 73 20 5b 73 71 6c 69 74 65 33 5f 63 72 65   as [sqlite3_cre
2cc50 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 42 2c  ate_collation(B,
2cc60 58 2c 45 2c 50 2c 46 29 5d 20 65 78 63 65 70 74  X,E,P,F)] except
2cc70 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 20 20 20   that the.**    
2cc80 20 20 20 20 20 20 63 6f 6c 6c 61 74 69 6f 6e 20        collation 
2cc90 6e 61 6d 65 20 58 20 69 73 20 75 6e 64 65 72 73  name X is unders
2cca0 74 6f 6f 64 20 61 73 20 55 54 46 2d 31 36 20 69  tood as UTF-16 i
2ccb0 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  n native byte or
2ccc0 64 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  der.**          
2ccd0 69 6e 73 74 65 61 64 20 6f 66 20 55 54 46 2d 38  instead of UTF-8
2cce0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36 33 30 7d  ..**.** {F16630}
2ccf0 20 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 63   When multiple c
2cd00 6f 6d 70 61 72 69 73 6f 6e 20 66 75 6e 63 74 69  omparison functi
2cd10 6f 6e 73 20 61 72 65 20 61 76 61 69 6c 61 62 6c  ons are availabl
2cd20 65 20 66 6f 72 20 74 68 65 20 73 61 6d 65 0a 2a  e for the same.*
2cd30 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6c 6c 61  *          colla
2cd40 74 69 6e 67 20 73 65 71 75 65 6e 63 65 2c 20 53  ting sequence, S
2cd50 51 4c 69 74 65 20 63 68 6f 6f 73 65 73 20 74 68  QLite chooses th
2cd60 65 20 6f 6e 65 20 77 68 6f 73 65 20 74 65 78 74  e one whose text
2cd70 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 20 20 20   encoding.**    
2cd80 20 20 20 20 20 20 72 65 71 75 69 72 65 73 20 74        requires t
2cd90 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20  he least amount 
2cda0 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72  of conversion fr
2cdb0 6f 6d 20 74 68 65 20 64 65 66 61 75 6c 74 0a 2a  om the default.*
2cdc0 2a 20 20 20 20 20 20 20 20 20 20 74 65 78 74 20  *          text 
2cdd0 65 6e 63 6f 64 69 6e 67 20 6f 66 20 74 68 65 20  encoding of the 
2cde0 64 61 74 61 62 61 73 65 2e 0a 2a 2f 0a 69 6e 74  database..*/.int
2cdf0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2ce00 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20 73 71 6c  collation(.  sql
2ce10 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20  ite3*, .  const 
2ce20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20  char *zName, .  
2ce30 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20  int eTextRep, . 
2ce40 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78   void*,.  int(*x
2ce50 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69  Compare)(void*,i
2ce60 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69  nt,const void*,i
2ce70 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a  nt,const void*).
2ce80 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
2ce90 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
2cea0 76 32 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  v2(.  sqlite3*, 
2ceb0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
2cec0 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65  Name, .  int eTe
2ced0 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c  xtRep, .  void*,
2cee0 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65  .  int(*xCompare
2cef0 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
2cf00 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  t void*,int,cons
2cf10 74 20 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64  t void*),.  void
2cf20 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64  (*xDestroy)(void
2cf30 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  *).);.int sqlite
2cf40 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
2cf50 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a  on16(.  sqlite3*
2cf60 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  , .  const char 
2cf70 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65  *zName, .  int e
2cf80 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64  TextRep, .  void
2cf90 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61  *,.  int(*xCompa
2cfa0 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  re)(void*,int,co
2cfb0 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  nst void*,int,co
2cfc0 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f  nst void*).);../
2cfd0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
2cfe0 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65 64 65 64 20  ollation Needed 
2cff0 43 61 6c 6c 62 61 63 6b 73 20 7b 46 31 36 37 30  Callbacks {F1670
2d000 30 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 61 76 6f 69  0}.**.** To avoi
2d010 64 20 68 61 76 69 6e 67 20 74 6f 20 72 65 67 69  d having to regi
2d020 73 74 65 72 20 61 6c 6c 20 63 6f 6c 6c 61 74 69  ster all collati
2d030 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 62 65 66  on sequences bef
2d040 6f 72 65 20 61 20 64 61 74 61 62 61 73 65 0a 2a  ore a database.*
2d050 2a 20 63 61 6e 20 62 65 20 75 73 65 64 2c 20 61  * can be used, a
2d060 20 73 69 6e 67 6c 65 20 63 61 6c 6c 62 61 63 6b   single callback
2d070 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65   function may be
2d080 20 72 65 67 69 73 74 65 72 65 64 20 77 69 74 68   registered with
2d090 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
2d0a0 20 68 61 6e 64 6c 65 20 74 6f 20 62 65 20 63 61   handle to be ca
2d0b0 6c 6c 65 64 20 77 68 65 6e 65 76 65 72 20 61 6e  lled whenever an
2d0c0 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61   undefined colla
2d0d0 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 69 73  tion sequence is
2d0e0 0a 2a 2a 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a  .** required..**
2d0f0 0a 2a 2a 20 49 66 20 74 68 65 20 66 75 6e 63 74  .** If the funct
2d100 69 6f 6e 20 69 73 20 72 65 67 69 73 74 65 72 65  ion is registere
2d110 64 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69  d using the sqli
2d120 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
2d130 65 64 65 64 28 29 20 41 50 49 2c 0a 2a 2a 20 74  eded() API,.** t
2d140 68 65 6e 20 69 74 20 69 73 20 70 61 73 73 65 64  hen it is passed
2d150 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 75 6e   the names of un
2d160 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f  defined collatio
2d170 6e 20 73 65 71 75 65 6e 63 65 73 20 61 73 20 73  n sequences as s
2d180 74 72 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64 65  trings.** encode
2d190 64 20 69 6e 20 55 54 46 2d 38 2e 20 7b 46 31 36  d in UTF-8. {F16
2d1a0 37 30 33 7d 20 49 66 20 73 71 6c 69 74 65 33 5f  703} If sqlite3_
2d1b0 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
2d1c0 31 36 28 29 20 69 73 20 75 73 65 64 2c 20 74 68  16() is used, th
2d1d0 65 20 6e 61 6d 65 73 0a 2a 2a 20 61 72 65 20 70  e names.** are p
2d1e0 61 73 73 65 64 20 61 73 20 55 54 46 2d 31 36 20  assed as UTF-16 
2d1f0 69 6e 20 6d 61 63 68 69 6e 65 20 6e 61 74 69 76  in machine nativ
2d200 65 20 62 79 74 65 20 6f 72 64 65 72 2e 20 41 20  e byte order. A 
2d210 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72 0a 2a  call to either.*
2d220 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 70 6c 61  * function repla
2d230 63 65 73 20 61 6e 79 20 65 78 69 73 74 69 6e 67  ces any existing
2d240 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a   callback..**.**
2d250 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61   When the callba
2d260 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74  ck is invoked, t
2d270 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
2d280 74 20 70 61 73 73 65 64 20 69 73 20 61 20 63 6f  t passed is a co
2d290 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 65 63  py.** of the sec
2d2a0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
2d2b0 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
2d2c0 6e 5f 6e 65 65 64 65 64 28 29 20 6f 72 0a 2a 2a  n_needed() or.**
2d2d0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
2d2e0 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 2e 20 20  on_needed16().  
2d2f0 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
2d300 65 6e 74 20 69 73 20 74 68 65 20 64 61 74 61 62  ent is the datab
2d310 61 73 65 0a 2a 2a 20 68 61 6e 64 6c 65 2e 20 20  ase.** handle.  
2d320 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
2d330 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51  nt is one of [SQ
2d340 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 5b  LITE_UTF8],.** [
2d350 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c  SQLITE_UTF16BE],
2d360 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31   or [SQLITE_UTF1
2d370 36 4c 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67  6LE], indicating
2d380 20 74 68 65 20 6d 6f 73 74 0a 2a 2a 20 64 65 73   the most.** des
2d390 69 72 61 62 6c 65 20 66 6f 72 6d 20 6f 66 20 74  irable form of t
2d3a0 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  he collation seq
2d3b0 75 65 6e 63 65 20 66 75 6e 63 74 69 6f 6e 20 72  uence function r
2d3c0 65 71 75 69 72 65 64 2e 0a 2a 2a 20 54 68 65 20  equired..** The 
2d3d0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
2d3e0 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
2d3f0 74 68 65 0a 2a 2a 20 72 65 71 75 69 72 65 64 20  the.** required 
2d400 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
2d410 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61  ce..**.** The ca
2d420 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
2d430 73 68 6f 75 6c 64 20 72 65 67 69 73 74 65 72 20  should register 
2d440 74 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c 6c  the desired coll
2d450 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b  ation using.** [
2d460 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
2d470 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b 73 71  ollation()], [sq
2d480 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
2d490 6c 61 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a  lation16()], or.
2d4a0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ** [sqlite3_crea
2d4b0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
2d4c0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  )]..**.** INVARI
2d4d0 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  ANTS:.**.** {F16
2d4e0 37 30 32 7d 20 41 20 73 75 63 63 65 73 73 66 75  702} A successfu
2d4f0 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  l call to [sqlit
2d500 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
2d510 64 65 64 28 44 2c 50 2c 46 29 5d 0a 2a 2a 20 20  ded(D,P,F)].**  
2d520 20 20 20 20 20 20 20 20 6f 72 20 5b 73 71 6c 69          or [sqli
2d530 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
2d540 65 64 65 64 31 36 28 44 2c 50 2c 46 29 5d 20 63  eded16(D,P,F)] c
2d550 61 75 73 65 73 0a 2a 2a 20 20 20 20 20 20 20 20  auses.**        
2d560 20 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20    the [database 
2d570 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 74 6f  connection] D to
2d580 20 69 6e 76 6f 6b 65 20 63 61 6c 6c 62 61 63 6b   invoke callback
2d590 20 46 20 77 69 74 68 20 66 69 72 73 74 0a 2a 2a   F with first.**
2d5a0 20 20 20 20 20 20 20 20 20 20 70 61 72 61 6d 65            parame
2d5b0 74 65 72 20 50 20 77 68 65 6e 65 76 65 72 20 69  ter P whenever i
2d5c0 74 20 6e 65 65 64 73 20 61 20 63 6f 6d 70 61 72  t needs a compar
2d5d0 69 73 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 66 6f  ison function fo
2d5e0 72 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  r a.**          
2d5f0 63 6f 6c 6c 61 74 69 6e 67 20 73 65 71 75 65 6e  collating sequen
2d600 63 65 20 74 68 61 74 20 69 74 20 64 6f 65 73 20  ce that it does 
2d610 6e 6f 74 20 6b 6e 6f 77 20 61 62 6f 75 74 2e 0a  not know about..
2d620 2a 2a 0a 2a 2a 20 7b 46 31 36 37 30 34 7d 20 45  **.** {F16704} E
2d630 61 63 68 20 73 75 63 63 65 73 73 66 75 6c 20 63  ach successful c
2d640 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
2d650 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
2d660 28 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20  ()] or.**       
2d670 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c     [sqlite3_coll
2d680 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29  ation_needed16()
2d690 5d 20 6f 76 65 72 72 69 64 65 73 20 74 68 65 20  ] overrides the 
2d6a0 63 61 6c 6c 62 61 63 6b 20 72 65 67 69 73 74 65  callback registe
2d6b0 72 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  red.**          
2d6c0 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74  on the same [dat
2d6d0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2d6e0 5d 20 62 79 20 70 72 69 6f 72 20 63 61 6c 6c 73  ] by prior calls
2d6f0 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 20 20   to either.**   
2d700 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65         interface
2d710 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 37 30 36 7d  ..**.** {F16706}
2d720 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   The name of the
2d730 20 72 65 71 75 65 73 74 65 64 20 63 6f 6c 6c 61   requested colla
2d740 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70 61  ting function pa
2d750 73 73 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 20  ssed in the.**  
2d760 20 20 20 20 20 20 20 20 34 74 68 20 70 61 72 61          4th para
2d770 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c  meter to the cal
2d780 6c 62 61 63 6b 20 69 73 20 69 6e 20 55 54 46 2d  lback is in UTF-
2d790 38 20 69 66 20 74 68 65 20 63 61 6c 6c 62 61 63  8 if the callbac
2d7a0 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 61  k.**          wa
2d7b0 73 20 72 65 67 69 73 74 65 72 65 64 20 75 73 69  s registered usi
2d7c0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  ng [sqlite3_coll
2d7d0 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d 20  ation_needed()] 
2d7e0 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  and.**          
2d7f0 69 73 20 69 6e 20 55 54 46 2d 31 36 20 6e 61 74  is in UTF-16 nat
2d800 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 69  ive byte order i
2d810 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 77  f the callback w
2d820 61 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  as.**          r
2d830 65 67 69 73 74 65 72 65 64 20 75 73 69 6e 67 20  egistered using 
2d840 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69  [sqlite3_collati
2d850 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 5d 2e 0a  on_needed16()]..
2d860 2a 2a 0a 2a 2a 20 0a 2a 2f 0a 69 6e 74 20 73 71  **.** .*/.int sq
2d870 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
2d880 6e 65 65 64 65 64 28 0a 20 20 73 71 6c 69 74 65  needed(.  sqlite
2d890 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 20 0a 20  3*, .  void*, . 
2d8a0 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73   void(*)(void*,s
2d8b0 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78  qlite3*,int eTex
2d8c0 74 52 65 70 2c 63 6f 6e 73 74 20 63 68 61 72 2a  tRep,const char*
2d8d0 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ).);.int sqlite3
2d8e0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
2d8f0 64 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  d16(.  sqlite3*,
2d900 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f 69   .  void*,.  voi
2d910 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74  d(*)(void*,sqlit
2d920 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70  e3*,int eTextRep
2d930 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b  ,const void*).);
2d940 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20  ../*.** Specify 
2d950 74 68 65 20 6b 65 79 20 66 6f 72 20 61 6e 20 65  the key for an e
2d960 6e 63 72 79 70 74 65 64 20 64 61 74 61 62 61 73  ncrypted databas
2d970 65 2e 20 20 54 68 69 73 20 72 6f 75 74 69 6e 65  e.  This routine
2d980 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 63 61   should be.** ca
2d990 6c 6c 65 64 20 72 69 67 68 74 20 61 66 74 65 72  lled right after
2d9a0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 2e   sqlite3_open().
2d9b0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20  .**.** The code 
2d9c0 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69  to implement thi
2d9d0 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61  s API is not ava
2d9e0 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75  ilable in the pu
2d9f0 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20  blic release.** 
2da00 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e  of SQLite..*/.in
2da10 74 20 73 71 6c 69 74 65 33 5f 6b 65 79 28 0a 20  t sqlite3_key(. 
2da20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
2da30 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2da40 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62  /* Database to b
2da50 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63  e rekeyed */.  c
2da60 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c  onst void *pKey,
2da70 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a   int nKey     /*
2da80 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a   The key */.);..
2da90 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65 20 74 68 65  /*.** Change the
2daa0 20 6b 65 79 20 6f 6e 20 61 6e 20 6f 70 65 6e 20   key on an open 
2dab0 64 61 74 61 62 61 73 65 2e 20 20 49 66 20 74 68  database.  If th
2dac0 65 20 63 75 72 72 65 6e 74 20 64 61 74 61 62 61  e current databa
2dad0 73 65 20 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63  se is not.** enc
2dae0 72 79 70 74 65 64 2c 20 74 68 69 73 20 72 6f 75  rypted, this rou
2daf0 74 69 6e 65 20 77 69 6c 6c 20 65 6e 63 72 79 70  tine will encryp
2db00 74 20 69 74 2e 20 20 49 66 20 70 4e 65 77 3d 3d  t it.  If pNew==
2db10 30 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20 74 68  0 or nNew==0, th
2db20 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 69 73  e.** database is
2db30 20 64 65 63 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a   decrypted..**.*
2db40 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d  * The code to im
2db50 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49  plement this API
2db60 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c   is not availabl
2db70 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20  e in the public 
2db80 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51  release.** of SQ
2db90 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  Lite..*/.int sql
2dba0 69 74 65 33 5f 72 65 6b 65 79 28 0a 20 20 73 71  ite3_rekey(.  sq
2dbb0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
2dbc0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
2dbd0 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72  Database to be r
2dbe0 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73  ekeyed */.  cons
2dbf0 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e  t void *pKey, in
2dc00 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68  t nKey     /* Th
2dc10 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a  e new key */.);.
2dc20 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2dc30 20 20 53 75 73 70 65 6e 64 20 45 78 65 63 75 74    Suspend Execut
2dc40 69 6f 6e 20 46 6f 72 20 41 20 53 68 6f 72 74 20  ion For A Short 
2dc50 54 69 6d 65 20 7b 46 31 30 35 33 30 7d 0a 2a 2a  Time {F10530}.**
2dc60 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
2dc70 73 6c 65 65 70 28 29 20 66 75 6e 63 74 69 6f 6e  sleep() function
2dc80 0a 2a 2a 20 63 61 75 73 65 73 20 74 68 65 20 63  .** causes the c
2dc90 75 72 72 65 6e 74 20 74 68 72 65 61 64 20 74 6f  urrent thread to
2dca0 20 73 75 73 70 65 6e 64 20 65 78 65 63 75 74 69   suspend executi
2dcb0 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74 20 6c 65 61  on.** for at lea
2dcc0 73 74 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 6d  st a number of m
2dcd0 69 6c 6c 69 73 65 63 6f 6e 64 73 20 73 70 65 63  illiseconds spec
2dce0 69 66 69 65 64 20 69 6e 20 69 74 73 20 70 61 72  ified in its par
2dcf0 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66  ameter..**.** If
2dd00 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
2dd10 79 73 74 65 6d 20 64 6f 65 73 20 6e 6f 74 20 73  ystem does not s
2dd20 75 70 70 6f 72 74 20 73 6c 65 65 70 20 72 65 71  upport sleep req
2dd30 75 65 73 74 73 20 77 69 74 68 20 0a 2a 2a 20 6d  uests with .** m
2dd40 69 6c 6c 69 73 65 63 6f 6e 64 20 74 69 6d 65 20  illisecond time 
2dd50 72 65 73 6f 6c 75 74 69 6f 6e 2c 20 74 68 65 6e  resolution, then
2dd60 20 74 68 65 20 74 69 6d 65 20 77 69 6c 6c 20 62   the time will b
2dd70 65 20 72 6f 75 6e 64 65 64 20 75 70 20 74 6f 20  e rounded up to 
2dd80 0a 2a 2a 20 74 68 65 20 6e 65 61 72 65 73 74 20  .** the nearest 
2dd90 73 65 63 6f 6e 64 2e 20 54 68 65 20 6e 75 6d 62  second. The numb
2dda0 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e  er of millisecon
2ddb0 64 73 20 6f 66 20 73 6c 65 65 70 20 61 63 74 75  ds of sleep actu
2ddc0 61 6c 6c 79 20 0a 2a 2a 20 72 65 71 75 65 73 74  ally .** request
2ddd0 65 64 20 66 72 6f 6d 20 74 68 65 20 6f 70 65 72  ed from the oper
2dde0 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 73 20  ating system is 
2ddf0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
2de00 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74  SQLite implement
2de10 73 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  s this interface
2de20 20 62 79 20 63 61 6c 6c 69 6e 67 20 74 68 65 20   by calling the 
2de30 78 53 6c 65 65 70 28 29 0a 2a 2a 20 6d 65 74 68  xSleep().** meth
2de40 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c  od of the defaul
2de50 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  t [sqlite3_vfs] 
2de60 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 4e  object..**.** IN
2de70 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
2de80 7b 46 31 30 35 33 33 7d 20 54 68 65 20 5b 73 71  {F10533} The [sq
2de90 6c 69 74 65 33 5f 73 6c 65 65 70 28 4d 29 5d 20  lite3_sleep(M)] 
2dea0 69 6e 74 65 72 66 61 63 65 20 69 6e 76 6f 6b 65  interface invoke
2deb0 73 20 74 68 65 20 78 53 6c 65 65 70 0a 2a 2a 20  s the xSleep.** 
2dec0 20 20 20 20 20 20 20 20 20 6d 65 74 68 6f 64 20           method 
2ded0 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b  of the default [
2dee0 73 71 6c 69 74 65 33 5f 76 66 73 7c 56 46 53 5d  sqlite3_vfs|VFS]
2def0 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20   in order to.** 
2df00 20 20 20 20 20 20 20 20 20 73 75 73 70 65 6e 64           suspend
2df10 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68   execution of th
2df20 65 20 63 75 72 72 65 6e 74 20 74 68 72 65 61 64  e current thread
2df30 20 66 6f 72 20 61 74 20 6c 65 61 73 74 0a 2a 2a   for at least.**
2df40 20 20 20 20 20 20 20 20 20 20 4d 20 6d 69 6c 6c            M mill
2df50 69 73 65 63 6f 6e 64 73 2e 0a 2a 2a 0a 2a 2a 20  iseconds..**.** 
2df60 7b 46 31 30 35 33 36 7d 20 54 68 65 20 5b 73 71  {F10536} The [sq
2df70 6c 69 74 65 33 5f 73 6c 65 65 70 28 4d 29 5d 20  lite3_sleep(M)] 
2df80 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2df90 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  s the number of.
2dfa0 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 69 6c 6c  **          mill
2dfb0 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65  iseconds of slee
2dfc0 70 20 61 63 74 75 61 6c 6c 79 20 72 65 71 75 65  p actually reque
2dfd0 73 74 65 64 20 6f 66 20 74 68 65 20 6f 70 65 72  sted of the oper
2dfe0 61 74 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20  ating.**        
2dff0 20 20 73 79 73 74 65 6d 2c 20 77 68 69 63 68 20    system, which 
2e000 6d 69 67 68 74 20 62 65 20 6c 61 72 67 65 72 20  might be larger 
2e010 74 68 61 6e 20 74 68 65 20 70 61 72 61 6d 65 74  than the paramet
2e020 65 72 20 4d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  er M..*/.int sql
2e030 69 74 65 33 5f 73 6c 65 65 70 28 69 6e 74 29 3b  ite3_sleep(int);
2e040 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2e050 3a 20 20 4e 61 6d 65 20 4f 66 20 54 68 65 20 46  :  Name Of The F
2e060 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20 54 65  older Holding Te
2e070 6d 70 6f 72 61 72 79 20 46 69 6c 65 73 20 7b 46  mporary Files {F
2e080 31 30 33 31 30 7d 0a 2a 2a 0a 2a 2a 20 49 66 20  10310}.**.** If 
2e090 74 68 69 73 20 67 6c 6f 62 61 6c 20 76 61 72 69  this global vari
2e0a0 61 62 6c 65 20 69 73 20 6d 61 64 65 20 74 6f 20  able is made to 
2e0b0 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e  point to a strin
2e0c0 67 20 77 68 69 63 68 20 69 73 0a 2a 2a 20 74 68  g which is.** th
2e0d0 65 20 6e 61 6d 65 20 6f 66 20 61 20 66 6f 6c 64  e name of a fold
2e0e0 65 72 20 28 61 2e 6b 61 2e 20 64 69 72 65 63 74  er (a.ka. direct
2e0f0 6f 72 79 29 2c 20 74 68 65 6e 20 61 6c 6c 20 74  ory), then all t
2e100 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 0a 2a  emporary files.*
2e110 2a 20 63 72 65 61 74 65 64 20 62 79 20 53 51 4c  * created by SQL
2e120 69 74 65 20 77 69 6c 6c 20 62 65 20 70 6c 61 63  ite will be plac
2e130 65 64 20 69 6e 20 74 68 61 74 20 64 69 72 65 63  ed in that direc
2e140 74 6f 72 79 2e 20 20 49 66 20 74 68 69 73 20 76  tory.  If this v
2e150 61 72 69 61 62 6c 65 0a 2a 2a 20 69 73 20 4e 55  ariable.** is NU
2e160 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e  LL pointer, then
2e170 20 53 51 4c 69 74 65 20 64 6f 65 73 20 61 20 73   SQLite does a s
2e180 65 61 72 63 68 20 66 6f 72 20 61 6e 20 61 70 70  earch for an app
2e190 72 6f 70 72 69 61 74 65 20 74 65 6d 70 6f 72 61  ropriate tempora
2e1a0 72 79 0a 2a 2a 20 66 69 6c 65 20 64 69 72 65 63  ry.** file direc
2e1b0 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69  tory..**.** It i
2e1c0 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 6d 6f  s not safe to mo
2e1d0 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62  dify this variab
2e1e0 6c 65 20 6f 6e 63 65 20 61 20 64 61 74 61 62 61  le once a databa
2e1f0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
2e200 20 68 61 73 20 62 65 65 6e 20 6f 70 65 6e 65 64   has been opened
2e210 2e 20 20 49 74 20 69 73 20 69 6e 74 65 6e 64 65  .  It is intende
2e220 64 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69  d that this vari
2e230 61 62 6c 65 20 62 65 20 73 65 74 20 6f 6e 63 65  able be set once
2e240 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20 70  .** as part of p
2e250 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a  rocess initializ
2e260 61 74 69 6f 6e 20 61 6e 64 20 62 65 66 6f 72 65  ation and before
2e270 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65   any SQLite inte
2e280 72 66 61 63 65 0a 2a 2a 20 72 6f 75 74 69 6e 65  rface.** routine
2e290 73 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c  s have been call
2e2a0 20 61 6e 64 20 72 65 6d 61 69 6e 20 75 6e 63 68   and remain unch
2e2b0 61 6e 67 65 64 20 74 68 65 72 65 61 66 74 65 72  anged thereafter
2e2c0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45  ..*/.SQLITE_EXTE
2e2d0 52 4e 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  RN char *sqlite3
2e2e0 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 3b  _temp_directory;
2e2f0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2e300 3a 20 20 54 65 73 74 20 54 6f 20 53 65 65 20 49  :  Test To See I
2e310 66 20 54 68 65 20 44 61 74 61 62 61 73 65 20 49  f The Database I
2e320 73 20 49 6e 20 41 75 74 6f 2d 43 6f 6d 6d 69 74  s In Auto-Commit
2e330 20 4d 6f 64 65 20 7b 46 31 32 39 33 30 7d 0a 2a   Mode {F12930}.*
2e340 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
2e350 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28  _get_autocommit(
2e360 29 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 74  ) interfaces ret
2e370 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72  urns non-zero or
2e380 0a 2a 2a 20 7a 65 72 6f 20 69 66 20 74 68 65 20  .** zero if the 
2e390 67 69 76 65 6e 20 64 61 74 61 62 61 73 65 20 63  given database c
2e3a0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 72 20  onnection is or 
2e3b0 69 73 20 6e 6f 74 20 69 6e 20 61 75 74 6f 63 6f  is not in autoco
2e3c0 6d 6d 69 74 20 6d 6f 64 65 2c 0a 2a 2a 20 72 65  mmit mode,.** re
2e3d0 73 70 65 63 74 69 76 65 6c 79 2e 20 20 20 41 75  spectively.   Au
2e3e0 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73  tocommit mode is
2e3f0 20 6f 6e 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c   on.** by defaul
2e400 74 2e 20 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d  t.  Autocommit m
2e410 6f 64 65 20 69 73 20 64 69 73 61 62 6c 65 64 20  ode is disabled 
2e420 62 79 20 61 20 5b 42 45 47 49 4e 5d 20 73 74 61  by a [BEGIN] sta
2e430 74 65 6d 65 6e 74 2e 0a 2a 2a 20 41 75 74 6f 63  tement..** Autoc
2e440 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 72 65  ommit mode is re
2e450 65 6e 61 62 6c 65 64 20 62 79 20 61 20 5b 43 4f  enabled by a [CO
2e460 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41  MMIT] or [ROLLBA
2e470 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 63 65  CK]..**.** If ce
2e480 72 74 61 69 6e 20 6b 69 6e 64 73 20 6f 66 20 65  rtain kinds of e
2e490 72 72 6f 72 73 20 6f 63 63 75 72 20 6f 6e 20 61  rrors occur on a
2e4a0 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69   statement withi
2e4b0 6e 20 61 20 6d 75 6c 74 69 2d 73 74 61 74 65 6d  n a multi-statem
2e4c0 65 6e 74 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69  ent.** transacti
2e4d0 6f 6e 73 20 28 65 72 72 6f 72 73 20 69 6e 63 6c  ons (errors incl
2e4e0 75 64 69 6e 67 20 5b 53 51 4c 49 54 45 5f 46 55  uding [SQLITE_FU
2e4f0 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4f 45  LL], [SQLITE_IOE
2e500 52 52 5d 2c 20 0a 2a 2a 20 5b 53 51 4c 49 54 45  RR], .** [SQLITE
2e510 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53 51 4c 49 54 45  _NOMEM], [SQLITE
2e520 5f 42 55 53 59 5d 2c 20 61 6e 64 20 5b 53 51 4c  _BUSY], and [SQL
2e530 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 29 20  ITE_INTERRUPT]) 
2e540 74 68 65 6e 20 74 68 65 0a 2a 2a 20 74 72 61 6e  then the.** tran
2e550 73 61 63 74 69 6f 6e 20 6d 69 67 68 74 20 62 65  saction might be
2e560 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74   rolled back aut
2e570 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54 68 65  omatically.  The
2e580 20 6f 6e 6c 79 20 77 61 79 20 74 6f 0a 2a 2a 20   only way to.** 
2e590 66 69 6e 64 20 6f 75 74 20 69 66 20 53 51 4c 69  find out if SQLi
2e5a0 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  te automatically
2e5b0 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 74 68 65   rolled back the
2e5c0 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 61 66 74   transaction aft
2e5d0 65 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 69  er.** an error i
2e5e0 73 20 74 6f 20 75 73 65 20 74 68 69 73 20 66 75  s to use this fu
2e5f0 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 4e  nction..**.** IN
2e600 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
2e610 7b 46 31 32 39 33 31 7d 20 54 68 65 20 5b 73 71  {F12931} The [sq
2e620 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f  lite3_get_autoco
2e630 6d 6d 69 74 28 44 29 5d 20 69 6e 74 65 72 66 61  mmit(D)] interfa
2e640 63 65 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  ce returns non-z
2e650 65 72 6f 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20  ero or.**       
2e660 20 20 20 7a 65 72 6f 20 69 66 20 74 68 65 20 5b     zero if the [
2e670 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2e680 69 6f 6e 5d 20 44 20 69 73 20 6f 72 20 69 73 20  ion] D is or is 
2e690 6e 6f 74 20 69 6e 20 61 75 74 6f 63 6f 6d 6d 69  not in autocommi
2e6a0 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 6f  t.**          mo
2e6b0 64 65 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79  de, respectively
2e6c0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 33 32 7d  ..**.** {F12932}
2e6d0 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65   Autocommit mode
2e6e0 20 69 73 20 6f 6e 20 62 79 20 64 65 66 61 75 6c   is on by defaul
2e6f0 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 33 33  t..**.** {F12933
2e700 7d 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64  } Autocommit mod
2e710 65 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79  e is disabled by
2e720 20 61 20 73 75 63 63 65 73 73 66 75 6c 20 5b 42   a successful [B
2e730 45 47 49 4e 5d 20 73 74 61 74 65 6d 65 6e 74 2e  EGIN] statement.
2e740 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 33 34 7d 20  .**.** {F12934} 
2e750 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20  Autocommit mode 
2e760 69 73 20 65 6e 61 62 6c 65 64 20 62 79 20 61 20  is enabled by a 
2e770 73 75 63 63 65 73 73 66 75 6c 20 5b 43 4f 4d 4d  successful [COMM
2e780 49 54 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41 43 4b  IT] or [ROLLBACK
2e790 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74  ].**          st
2e7a0 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 0a 2a 2a 0a  atement..** .**.
2e7b0 2a 2a 20 4c 49 4d 49 54 41 54 49 4f 4e 53 3a 0a  ** LIMITATIONS:.
2e7c0 2a 2a 2a 0a 2a 2a 20 7b 55 31 32 39 33 36 7d 20  ***.** {U12936} 
2e7d0 49 66 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61  If another threa
2e7e0 64 20 63 68 61 6e 67 65 73 20 74 68 65 20 61 75  d changes the au
2e7f0 74 6f 63 6f 6d 6d 69 74 20 73 74 61 74 75 73 20  tocommit status 
2e800 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  of the database.
2e810 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e 6e  **          conn
2e820 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 69  ection while thi
2e830 73 20 72 6f 75 74 69 6e 65 20 69 73 20 72 75 6e  s routine is run
2e840 6e 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72  ning, then the r
2e850 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 20  eturn value.**  
2e860 20 20 20 20 20 20 20 20 69 73 20 75 6e 64 65 66          is undef
2e870 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ined..*/.int sql
2e880 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d  ite3_get_autocom
2e890 6d 69 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  mit(sqlite3*);..
2e8a0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2e8b0 20 46 69 6e 64 20 54 68 65 20 44 61 74 61 62 61   Find The Databa
2e8c0 73 65 20 48 61 6e 64 6c 65 20 4f 66 20 41 20 50  se Handle Of A P
2e8d0 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
2e8e0 74 20 7b 46 31 33 31 32 30 7d 0a 2a 2a 0a 2a 2a  t {F13120}.**.**
2e8f0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f   The sqlite3_db_
2e900 68 61 6e 64 6c 65 20 69 6e 74 65 72 66 61 63 65  handle interface
2e910 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20  .** returns the 
2e920 5b 73 71 6c 69 74 65 33 2a 5d 20 64 61 74 61 62  [sqlite3*] datab
2e930 61 73 65 20 68 61 6e 64 6c 65 20 74 6f 20 77 68  ase handle to wh
2e940 69 63 68 20 61 0a 2a 2a 20 5b 70 72 65 70 61 72  ich a.** [prepar
2e950 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 62 65  ed statement] be
2e960 6c 6f 6e 67 73 2e 0a 2a 2a 20 54 68 65 20 64 61  longs..** The da
2e970 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 72 65  tabase handle re
2e980 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
2e990 33 5f 64 62 5f 68 61 6e 64 6c 65 0a 2a 2a 20 69  3_db_handle.** i
2e9a0 73 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  s the same datab
2e9b0 61 73 65 20 68 61 6e 64 6c 65 20 74 68 61 74 20  ase handle that 
2e9c0 77 61 73 0a 2a 2a 20 74 68 65 20 66 69 72 73 74  was.** the first
2e9d0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
2e9e0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2e9f0 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76  e_v2()] or its v
2ea00 61 72 69 61 6e 74 73 0a 2a 2a 20 74 68 61 74 20  ariants.** that 
2ea10 77 61 73 20 75 73 65 64 20 74 6f 20 63 72 65 61  was used to crea
2ea20 74 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  te the statement
2ea30 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 70 6c   in the first pl
2ea40 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ace..**.** INVAR
2ea50 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31  IANTS:.**.** {F1
2ea60 33 31 32 33 7d 20 54 68 65 20 5b 73 71 6c 69 74  3123} The [sqlit
2ea70 65 33 5f 64 62 5f 68 61 6e 64 6c 65 28 53 29 5d  e3_db_handle(S)]
2ea80 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2ea90 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  ns a pointer.** 
2eaa0 20 20 20 20 20 20 20 20 20 74 6f 20 74 68 65 20           to the 
2eab0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2eac0 74 69 6f 6e 5d 20 61 73 73 6f 63 69 61 74 65 64  tion] associated
2ead0 20 77 69 74 68 0a 2a 2a 20 20 20 20 20 20 20 20   with.**        
2eae0 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74    [prepared stat
2eaf0 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 73 71 6c  ement] S..*/.sql
2eb00 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 64 62  ite3 *sqlite3_db
2eb10 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f  _handle(sqlite3_
2eb20 73 74 6d 74 2a 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20  stmt*);.../*.** 
2eb30 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 6d 69 74  CAPI3REF: Commit
2eb40 20 41 6e 64 20 52 6f 6c 6c 62 61 63 6b 20 4e 6f   And Rollback No
2eb50 74 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62  tification Callb
2eb60 61 63 6b 73 20 7b 46 31 32 39 35 30 7d 0a 2a 2a  acks {F12950}.**
2eb70 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
2eb80 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 20 69 6e  commit_hook() in
2eb90 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72  terface register
2eba0 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  s a callback.** 
2ebb0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69  function to be i
2ebc0 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20  nvoked whenever 
2ebd0 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73  a transaction is
2ebe0 20 63 6f 6d 6d 69 74 74 65 64 2e 0a 2a 2a 20 41   committed..** A
2ebf0 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20  ny callback set 
2ec00 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61  by a previous ca
2ec10 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ll to sqlite3_co
2ec20 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66  mmit_hook().** f
2ec30 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  or the same data
2ec40 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
2ec50 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a  is overridden..*
2ec60 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 6f  * The sqlite3_ro
2ec70 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 20 69 6e  llback_hook() in
2ec80 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72  terface register
2ec90 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  s a callback.** 
2eca0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69  function to be i
2ecb0 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20  nvoked whenever 
2ecc0 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73  a transaction is
2ecd0 20 63 6f 6d 6d 69 74 74 65 64 2e 0a 2a 2a 20 41   committed..** A
2ece0 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20  ny callback set 
2ecf0 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61  by a previous ca
2ed00 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ll to sqlite3_co
2ed10 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66  mmit_hook().** f
2ed20 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  or the same data
2ed30 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
2ed40 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a  is overridden..*
2ed50 2a 20 54 68 65 20 70 41 72 67 20 61 72 67 75 6d  * The pArg argum
2ed60 65 6e 74 20 69 73 20 70 61 73 73 65 64 20 74 68  ent is passed th
2ed70 72 6f 75 67 68 0a 2a 2a 20 74 6f 20 74 68 65 20  rough.** to the 
2ed80 63 61 6c 6c 62 61 63 6b 2e 20 20 49 66 20 74 68  callback.  If th
2ed90 65 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 20 61 20  e callback on a 
2eda0 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 66 75 6e 63  commit hook func
2edb0 74 69 6f 6e 20 0a 2a 2a 20 72 65 74 75 72 6e 73  tion .** returns
2edc0 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20   non-zero, then 
2edd0 74 68 65 20 63 6f 6d 6d 69 74 20 69 73 20 63 6f  the commit is co
2ede0 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20 72  nverted into a r
2edf0 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49  ollback..**.** I
2ee00 66 20 61 6e 6f 74 68 65 72 20 66 75 6e 63 74 69  f another functi
2ee10 6f 6e 20 77 61 73 20 70 72 65 76 69 6f 75 73 6c  on was previousl
2ee20 79 20 72 65 67 69 73 74 65 72 65 64 2c 20 69 74  y registered, it
2ee30 73 0a 2a 2a 20 70 41 72 67 20 76 61 6c 75 65 20  s.** pArg value 
2ee40 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74  is returned.  Ot
2ee50 68 65 72 77 69 73 65 20 4e 55 4c 4c 20 69 73 20  herwise NULL is 
2ee60 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
2ee70 52 65 67 69 73 74 65 72 69 6e 67 20 61 20 4e 55  Registering a NU
2ee80 4c 4c 20 66 75 6e 63 74 69 6f 6e 20 64 69 73 61  LL function disa
2ee90 62 6c 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63  bles the callbac
2eea0 6b 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 74 68 65  k..**.** For the
2eeb0 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69   purposes of thi
2eec0 73 20 41 50 49 2c 20 61 20 74 72 61 6e 73 61 63  s API, a transac
2eed0 74 69 6f 6e 20 69 73 20 73 61 69 64 20 74 6f 20  tion is said to 
2eee0 68 61 76 65 20 62 65 65 6e 20 0a 2a 2a 20 72 6f  have been .** ro
2eef0 6c 6c 65 64 20 62 61 63 6b 20 69 66 20 61 6e 20  lled back if an 
2ef00 65 78 70 6c 69 63 69 74 20 22 52 4f 4c 4c 42 41  explicit "ROLLBA
2ef10 43 4b 22 20 73 74 61 74 65 6d 65 6e 74 20 69 73  CK" statement is
2ef20 20 65 78 65 63 75 74 65 64 2c 20 6f 72 0a 2a 2a   executed, or.**
2ef30 20 61 6e 20 65 72 72 6f 72 20 6f 72 20 63 6f 6e   an error or con
2ef40 73 74 72 61 69 6e 74 20 63 61 75 73 65 73 20 61  straint causes a
2ef50 6e 20 69 6d 70 6c 69 63 69 74 20 72 6f 6c 6c 62  n implicit rollb
2ef60 61 63 6b 20 74 6f 20 6f 63 63 75 72 2e 0a 2a 2a  ack to occur..**
2ef70 20 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 63 61   The rollback ca
2ef80 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e  llback is not in
2ef90 76 6f 6b 65 64 20 69 66 20 61 20 74 72 61 6e 73  voked if a trans
2efa0 61 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 61 75 74  action is.** aut
2efb0 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65  omatically rolle
2efc0 64 20 62 61 63 6b 20 62 65 63 61 75 73 65 20 74  d back because t
2efd0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
2efe0 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64  ection is closed
2eff0 2e 0a 2a 2a 20 54 68 65 20 72 6f 6c 6c 62 61 63  ..** The rollbac
2f000 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f  k callback is no
2f010 74 20 69 6e 76 6f 6b 65 64 20 69 66 20 61 20 74  t invoked if a t
2f020 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 0a 2a 2a  ransaction is.**
2f030 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62 65 63   rolled back bec
2f040 61 75 73 65 20 61 20 63 6f 6d 6d 69 74 20 63 61  ause a commit ca
2f050 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 65 64 20  llback returned 
2f060 6e 6f 6e 2d 7a 65 72 6f 2e 0a 2a 2a 20 3c 74 6f  non-zero..** <to
2f070 64 6f 3e 20 43 68 65 63 6b 20 6f 6e 20 74 68 69  do> Check on thi
2f080 73 20 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20  s </todo>.**.** 
2f090 54 68 65 73 65 20 61 72 65 20 65 78 70 65 72 69  These are experi
2f0a0 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66 61 63 65  mental interface
2f0b0 73 20 61 6e 64 20 61 72 65 20 73 75 62 6a 65 63  s and are subjec
2f0c0 74 20 74 6f 20 63 68 61 6e 67 65 2e 0a 2a 2a 0a  t to change..**.
2f0d0 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
2f0e0 2a 0a 2a 2a 20 7b 46 31 32 39 35 31 7d 20 54 68  *.** {F12951} Th
2f0f0 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69  e [sqlite3_commi
2f100 74 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69  t_hook(D,F,P)] i
2f110 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65  nterface registe
2f120 72 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  rs the.**       
2f130 20 20 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63     callback func
2f140 74 69 6f 6e 20 46 20 74 6f 20 62 65 20 69 6e 76  tion F to be inv
2f150 6f 6b 65 64 20 77 69 74 68 20 61 72 67 75 6d 65  oked with argume
2f160 6e 74 20 50 20 77 68 65 6e 65 76 65 72 0a 2a 2a  nt P whenever.**
2f170 20 20 20 20 20 20 20 20 20 20 61 20 74 72 61 6e            a tran
2f180 73 61 63 74 69 6f 6e 20 63 6f 6d 6d 69 74 73 20  saction commits 
2f190 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  on [database con
2f1a0 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a  nection] D..**.*
2f1b0 2a 20 7b 46 31 32 39 35 32 7d 20 54 68 65 20 5b  * {F12952} The [
2f1c0 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68  sqlite3_commit_h
2f1d0 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 6e 74 65  ook(D,F,P)] inte
2f1e0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
2f1f0 65 20 50 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  e P.**          
2f200 61 72 67 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68  argument from th
2f210 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  e previous call 
2f220 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 0a 2a  with the same .*
2f230 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61 74 61  *          [data
2f240 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
2f250 5d 20 44 20 2c 20 6f 72 20 4e 55 4c 4c 20 6f 6e  ] D , or NULL on
2f260 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 0a   the first call.
2f270 2a 2a 20 20 20 20 20 20 20 20 20 20 66 6f 72 20  **          for 
2f280 61 20 70 61 72 74 69 63 75 6c 61 72 20 5b 64 61  a particular [da
2f290 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2f2a0 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  n] D..**.** {F12
2f2b0 39 35 33 7d 20 45 61 63 68 20 63 61 6c 6c 20 74  953} Each call t
2f2c0 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69  o [sqlite3_commi
2f2d0 74 5f 68 6f 6f 6b 28 29 5d 20 6f 76 65 72 77 72  t_hook()] overwr
2f2e0 69 74 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63  ites the callbac
2f2f0 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  k.**          re
2f300 67 69 73 74 65 72 65 64 20 62 79 20 70 72 69 6f  gistered by prio
2f310 72 20 63 61 6c 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b  r calls..**.** {
2f320 46 31 32 39 35 34 7d 20 49 66 20 74 68 65 20 46  F12954} If the F
2f330 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71   argument to [sq
2f340 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f  lite3_commit_hoo
2f350 6b 28 44 2c 46 2c 50 29 5d 20 69 73 20 4e 55 4c  k(D,F,P)] is NUL
2f360 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  L.**          th
2f370 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 68 6f  en the commit ho
2f380 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 63  ok callback is c
2f390 61 6e 63 65 6c 6c 65 64 20 61 6e 64 20 6e 6f 20  ancelled and no 
2f3a0 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20  callback.**     
2f3b0 20 20 20 20 20 69 73 20 69 6e 76 6f 6b 65 64 20       is invoked 
2f3c0 77 68 65 6e 20 61 20 74 72 61 6e 73 61 63 74 69  when a transacti
2f3d0 6f 6e 20 63 6f 6d 6d 69 74 73 2e 0a 2a 2a 0a 2a  on commits..**.*
2f3e0 2a 20 7b 46 31 32 39 35 35 7d 20 49 66 20 74 68  * {F12955} If th
2f3f0 65 20 63 6f 6d 6d 69 74 20 63 61 6c 6c 62 61 63  e commit callbac
2f400 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  k returns non-ze
2f410 72 6f 20 74 68 65 6e 20 74 68 65 20 63 6f 6d 6d  ro then the comm
2f420 69 74 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20  it is.**        
2f430 20 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f    converted into
2f440 20 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a   a rollback..**.
2f450 2a 2a 20 7b 46 31 32 39 36 31 7d 20 54 68 65 20  ** {F12961} The 
2f460 5b 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63  [sqlite3_rollbac
2f470 6b 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69  k_hook(D,F,P)] i
2f480 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65  nterface registe
2f490 72 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  rs the.**       
2f4a0 20 20 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63     callback func
2f4b0 74 69 6f 6e 20 46 20 74 6f 20 62 65 20 69 6e 76  tion F to be inv
2f4c0 6f 6b 65 64 20 77 69 74 68 20 61 72 67 75 6d 65  oked with argume
2f4d0 6e 74 20 50 20 77 68 65 6e 65 76 65 72 0a 2a 2a  nt P whenever.**
2f4e0 20 20 20 20 20 20 20 20 20 20 61 20 74 72 61 6e            a tran
2f4f0 73 61 63 74 69 6f 6e 20 72 6f 6c 6c 73 20 62 61  saction rolls ba
2f500 63 6b 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20  ck on [database 
2f510 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a  connection] D..*
2f520 2a 0a 2a 2a 20 7b 46 31 32 39 36 32 7d 20 54 68  *.** {F12962} Th
2f530 65 20 5b 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62  e [sqlite3_rollb
2f540 61 63 6b 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d  ack_hook(D,F,P)]
2f550 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2f560 6e 73 20 74 68 65 20 50 0a 2a 2a 20 20 20 20 20  ns the P.**     
2f570 20 20 20 20 20 61 72 67 75 6d 65 6e 74 20 66 72       argument fr
2f580 6f 6d 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  om the previous 
2f590 63 61 6c 6c 20 77 69 74 68 20 74 68 65 20 73 61  call with the sa
2f5a0 6d 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  me .**          
2f5b0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2f5c0 74 69 6f 6e 20 5d 20 44 20 2c 20 6f 72 20 4e 55  tion ] D , or NU
2f5d0 4c 4c 20 6f 6e 20 74 68 65 20 66 69 72 73 74 20  LL on the first 
2f5e0 63 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20  call.**         
2f5f0 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61   for a particula
2f600 72 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  r [database conn
2f610 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a  ection] D..**.**
2f620 20 7b 46 31 32 39 36 33 7d 20 45 61 63 68 20 63   {F12963} Each c
2f630 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
2f640 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 5d  rollback_hook()]
2f650 20 6f 76 65 72 77 72 69 74 65 73 20 74 68 65 20   overwrites the 
2f660 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20  callback.**     
2f670 20 20 20 20 20 72 65 67 69 73 74 65 72 65 64 20       registered 
2f680 62 79 20 70 72 69 6f 72 20 63 61 6c 6c 73 2e 0a  by prior calls..
2f690 2a 2a 0a 2a 2a 20 7b 46 31 32 39 36 34 7d 20 49  **.** {F12964} I
2f6a0 66 20 74 68 65 20 46 20 61 72 67 75 6d 65 6e 74  f the F argument
2f6b0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 6f 6c   to [sqlite3_rol
2f6c0 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c 46 2c 50  lback_hook(D,F,P
2f6d0 29 5d 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20 20 20  )] is NULL.**   
2f6e0 20 20 20 20 20 20 20 74 68 65 6e 20 74 68 65 20         then the 
2f6f0 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 63 61  rollback hook ca
2f700 6c 6c 62 61 63 6b 20 69 73 20 63 61 6e 63 65 6c  llback is cancel
2f710 6c 65 64 20 61 6e 64 20 6e 6f 20 63 61 6c 6c 62  led and no callb
2f720 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ack.**          
2f730 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20  is invoked when 
2f740 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 72 6f  a transaction ro
2f750 6c 6c 73 20 62 61 63 6b 2e 0a 2a 2f 0a 76 6f 69  lls back..*/.voi
2f760 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69  d *sqlite3_commi
2f770 74 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c  t_hook(sqlite3*,
2f780 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20   int(*)(void*), 
2f790 76 6f 69 64 2a 29 3b 0a 76 6f 69 64 20 2a 73 71  void*);.void *sq
2f7a0 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68  lite3_rollback_h
2f7b0 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f  ook(sqlite3*, vo
2f7c0 69 64 28 2a 29 28 76 6f 69 64 20 2a 29 2c 20 76  id(*)(void *), v
2f7d0 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
2f7e0 50 49 33 52 45 46 3a 20 44 61 74 61 20 43 68 61  PI3REF: Data Cha
2f7f0 6e 67 65 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e  nge Notification
2f800 20 43 61 6c 6c 62 61 63 6b 73 20 7b 46 31 32 39   Callbacks {F129
2f810 37 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  70}.**.** The sq
2f820 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f  lite3_update_hoo
2f830 6b 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  k() interface.**
2f840 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c   registers a cal
2f850 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77  lback function w
2f860 69 74 68 20 74 68 65 20 64 61 74 61 62 61 73 65  ith the database
2f870 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 64 65 6e   connection iden
2f880 74 69 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a  tified by the .*
2f890 2a 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  * first argument
2f8a0 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77   to be invoked w
2f8b0 68 65 6e 65 76 65 72 20 61 20 72 6f 77 20 69 73  henever a row is
2f8c0 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72 74   updated, insert
2f8d0 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a  ed or deleted..*
2f8e0 2a 20 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73  * Any callback s
2f8f0 65 74 20 62 79 20 61 20 70 72 65 76 69 6f 75 73  et by a previous
2f900 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 66 75   call to this fu
2f910 6e 63 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 73  nction for the s
2f920 61 6d 65 20 0a 2a 2a 20 64 61 74 61 62 61 73 65  ame .** database
2f930 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f   connection is o
2f940 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 0a 2a 2a  verridden..**.**
2f950 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
2f960 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
2f970 72 20 74 6f 20 74 68 65 20 66 75 6e 63 74 69 6f  r to the functio
2f980 6e 20 74 6f 20 69 6e 76 6f 6b 65 20 77 68 65 6e  n to invoke when
2f990 20 61 20 0a 2a 2a 20 72 6f 77 20 69 73 20 75 70   a .** row is up
2f9a0 64 61 74 65 64 2c 20 69 6e 73 65 72 74 65 64 20  dated, inserted 
2f9b0 6f 72 20 64 65 6c 65 74 65 64 2e 20 0a 2a 2a 20  or deleted. .** 
2f9c0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
2f9d0 6e 74 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  nt to the callba
2f9e0 63 6b 20 69 73 0a 2a 2a 20 61 20 63 6f 70 79 20  ck is.** a copy 
2f9f0 6f 66 20 74 68 65 20 74 68 69 72 64 20 61 72 67  of the third arg
2fa00 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
2fa10 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 2e 0a  _update_hook()..
2fa20 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 63 61  ** The second ca
2fa30 6c 6c 62 61 63 6b 20 0a 2a 2a 20 61 72 67 75 6d  llback .** argum
2fa40 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53  ent is one of [S
2fa50 51 4c 49 54 45 5f 49 4e 53 45 52 54 5d 2c 20 5b  QLITE_INSERT], [
2fa60 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 6f  SQLITE_DELETE] o
2fa70 72 20 5b 53 51 4c 49 54 45 5f 55 50 44 41 54 45  r [SQLITE_UPDATE
2fa80 5d 2c 0a 2a 2a 20 64 65 70 65 6e 64 69 6e 67 20  ],.** depending 
2fa90 6f 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  on the operation
2faa0 20 74 68 61 74 20 63 61 75 73 65 64 20 74 68 65   that caused the
2fab0 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 62 65 20   callback to be 
2fac0 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 54 68 65 20  invoked..** The 
2fad0 74 68 69 72 64 20 61 6e 64 20 0a 2a 2a 20 66 6f  third and .** fo
2fae0 75 72 74 68 20 61 72 67 75 6d 65 6e 74 73 20 74  urth arguments t
2faf0 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 63  o the callback c
2fb00 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65 72 73 20  ontain pointers 
2fb10 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20  to the database 
2fb20 61 6e 64 20 0a 2a 2a 20 74 61 62 6c 65 20 6e 61  and .** table na
2fb30 6d 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  me containing th
2fb40 65 20 61 66 66 65 63 74 65 64 20 72 6f 77 2e 0a  e affected row..
2fb50 2a 2a 20 54 68 65 20 66 69 6e 61 6c 20 63 61 6c  ** The final cal
2fb60 6c 62 61 63 6b 20 70 61 72 61 6d 65 74 65 72 20  lback parameter 
2fb70 69 73 20 0a 2a 2a 20 74 68 65 20 72 6f 77 69 64  is .** the rowid
2fb80 20 6f 66 20 74 68 65 20 72 6f 77 2e 0a 2a 2a 20   of the row..** 
2fb90 49 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20 61  In the case of a
2fba0 6e 20 75 70 64 61 74 65 2c 20 74 68 69 73 20 69  n update, this i
2fbb0 73 20 74 68 65 20 72 6f 77 69 64 20 61 66 74 65  s the rowid afte
2fbc0 72 20 0a 2a 2a 20 74 68 65 20 75 70 64 61 74 65  r .** the update
2fbd0 20 74 61 6b 65 73 20 70 6c 61 63 65 2e 0a 2a 2a   takes place..**
2fbe0 0a 2a 2a 20 54 68 65 20 75 70 64 61 74 65 20 68  .** The update h
2fbf0 6f 6f 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b  ook is not invok
2fc00 65 64 20 77 68 65 6e 20 69 6e 74 65 72 6e 61 6c  ed when internal
2fc10 20 73 79 73 74 65 6d 20 74 61 62 6c 65 73 20 61   system tables a
2fc20 72 65 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 20 28  re.** modified (
2fc30 69 2e 65 2e 20 73 71 6c 69 74 65 5f 6d 61 73 74  i.e. sqlite_mast
2fc40 65 72 20 61 6e 64 20 73 71 6c 69 74 65 5f 73 65  er and sqlite_se
2fc50 71 75 65 6e 63 65 29 2e 0a 2a 2a 0a 2a 2a 20 49  quence)..**.** I
2fc60 66 20 61 6e 6f 74 68 65 72 20 66 75 6e 63 74 69  f another functi
2fc70 6f 6e 20 77 61 73 20 70 72 65 76 69 6f 75 73 6c  on was previousl
2fc80 79 20 72 65 67 69 73 74 65 72 65 64 2c 20 69 74  y registered, it
2fc90 73 20 70 41 72 67 20 76 61 6c 75 65 0a 2a 2a 20  s pArg value.** 
2fca0 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74  is returned.  Ot
2fcb0 68 65 72 77 69 73 65 20 4e 55 4c 4c 20 69 73 20  herwise NULL is 
2fcc0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
2fcd0 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
2fce0 2a 20 7b 46 31 32 39 37 31 7d 20 54 68 65 20 5b  * {F12971} The [
2fcf0 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68  sqlite3_update_h
2fd00 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 6e 74 65  ook(D,F,P)] inte
2fd10 72 66 61 63 65 20 63 61 75 73 65 73 20 63 61 6c  rface causes cal
2fd20 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20  lback.**        
2fd30 20 20 66 75 6e 63 74 69 6f 6e 20 46 20 74 6f 20    function F to 
2fd40 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  be invoked with 
2fd50 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
2fd60 50 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 20 20  P whenever.**   
2fd70 20 20 20 20 20 20 20 61 20 74 61 62 6c 65 20 72         a table r
2fd80 6f 77 20 69 73 20 6d 6f 64 69 66 69 65 64 2c 20  ow is modified, 
2fd90 69 6e 73 65 72 74 65 64 2c 20 6f 72 20 64 65 6c  inserted, or del
2fda0 65 74 65 64 20 6f 6e 0a 2a 2a 20 20 20 20 20 20  eted on.**      
2fdb0 20 20 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f      [database co
2fdc0 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a  nnection] D..**.
2fdd0 2a 2a 20 7b 46 31 32 39 37 33 7d 20 54 68 65 20  ** {F12973} The 
2fde0 5b 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f  [sqlite3_update_
2fdf0 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 6e 74  hook(D,F,P)] int
2fe00 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
2fe10 68 65 20 76 61 6c 75 65 0a 2a 2a 20 20 20 20 20  he value.**     
2fe20 20 20 20 20 20 6f 66 20 50 20 66 6f 72 20 74 68       of P for th
2fe30 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  e previous call 
2fe40 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74  on the same [dat
2fe50 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2fe60 5d 20 44 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ] D,.**         
2fe70 20 6f 72 20 4e 55 4c 4c 20 66 6f 72 20 74 68 65   or NULL for the
2fe80 20 66 69 72 73 74 20 63 61 6c 6c 2e 0a 2a 2a 0a   first call..**.
2fe90 2a 2a 20 7b 46 31 32 39 37 35 7d 20 49 66 20 74  ** {F12975} If t
2fea0 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 20 63  he update hook c
2feb0 61 6c 6c 62 61 63 6b 20 46 20 69 6e 20 5b 73 71  allback F in [sq
2fec0 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f  lite3_update_hoo
2fed0 6b 28 44 2c 46 2c 50 29 5d 0a 2a 2a 20 20 20 20  k(D,F,P)].**    
2fee0 20 20 20 20 20 20 69 73 20 4e 55 4c 4c 20 74 68        is NULL th
2fef0 65 6e 20 74 68 65 20 6e 6f 20 75 70 64 61 74 65  en the no update
2ff00 20 63 61 6c 6c 62 61 63 6b 73 20 61 72 65 20 6d   callbacks are m
2ff10 61 64 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39  ade..**.** {F129
2ff20 37 37 7d 20 45 61 63 68 20 63 61 6c 6c 20 74 6f  77} Each call to
2ff30 20 5b 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65   [sqlite3_update
2ff40 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 6f 76  _hook(D,F,P)] ov
2ff50 65 72 72 69 64 65 73 20 70 72 69 6f 72 20 63 61  errides prior ca
2ff60 6c 6c 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  lls.**          
2ff70 74 6f 20 74 68 65 20 73 61 6d 65 20 69 6e 74 65  to the same inte
2ff80 72 66 61 63 65 20 6f 6e 20 74 68 65 20 73 61 6d  rface on the sam
2ff90 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
2ffa0 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a  ection] D..**.**
2ffb0 20 7b 46 31 32 39 37 39 7d 20 54 68 65 20 75 70   {F12979} The up
2ffc0 64 61 74 65 20 68 6f 6f 6b 20 63 61 6c 6c 62 61  date hook callba
2ffd0 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65  ck is not invoke
2ffe0 64 20 77 68 65 6e 20 69 6e 74 65 72 6e 61 6c 20  d when internal 
2fff0 73 79 73 74 65 6d 0a 2a 2a 20 20 20 20 20 20 20  system.**       
30000 20 20 20 74 61 62 6c 65 73 20 73 75 63 68 20 61     tables such a
30010 73 20 73 71 6c 69 74 65 5f 6d 61 73 74 65 72 20  s sqlite_master 
30020 61 6e 64 20 73 71 6c 69 74 65 5f 73 65 71 75 65  and sqlite_seque
30030 6e 63 65 20 61 72 65 20 6d 6f 64 69 66 69 65 64  nce are modified
30040 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 38 31 7d  ..**.** {F12981}
30050 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
30060 6d 65 74 65 72 20 74 6f 20 74 68 65 20 75 70 64  meter to the upd
30070 61 74 65 20 63 61 6c 6c 62 61 63 6b 20 0a 2a 2a  ate callback .**
30080 20 20 20 20 20 20 20 20 20 20 69 73 20 6f 6e 65            is one
30090 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 53 45   of [SQLITE_INSE
300a0 52 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 44 45 4c  RT], [SQLITE_DEL
300b0 45 54 45 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ETE] or [SQLITE_
300c0 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 20 20 20 20  UPDATE],.**     
300d0 20 20 20 20 20 64 65 70 65 6e 64 69 6e 67 20 6f       depending o
300e0 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20  n the operation 
300f0 74 68 61 74 20 63 61 75 73 65 64 20 74 68 65 20  that caused the 
30100 63 61 6c 6c 62 61 63 6b 20 74 6f 20 62 65 20 69  callback to be i
30110 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46  nvoked..**.** {F
30120 31 32 39 38 33 7d 20 54 68 65 20 74 68 69 72 64  12983} The third
30130 20 61 6e 64 20 66 6f 75 72 74 68 20 61 72 67 75   and fourth argu
30140 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 63 61 6c  ments to the cal
30150 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 20 70 6f  lback contain po
30160 69 6e 74 65 72 73 0a 2a 2a 20 20 20 20 20 20 20  inters.**       
30170 20 20 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69     to zero-termi
30180 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69  nated UTF-8 stri
30190 6e 67 73 20 77 68 69 63 68 20 61 72 65 20 74 68  ngs which are th
301a0 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a  e names of the.*
301b0 2a 20 20 20 20 20 20 20 20 20 20 64 61 74 61 62  *          datab
301c0 61 73 65 20 61 6e 64 20 74 61 62 6c 65 20 74 68  ase and table th
301d0 61 74 20 69 73 20 62 65 69 6e 67 20 75 70 64 61  at is being upda
301e0 74 65 64 2e 0a 0a 2a 2a 20 7b 46 31 32 39 38 35  ted...** {F12985
301f0 7d 20 54 68 65 20 66 69 6e 61 6c 20 63 61 6c 6c  } The final call
30200 62 61 63 6b 20 70 61 72 61 6d 65 74 65 72 20 69  back parameter i
30210 73 20 74 68 65 20 72 6f 77 69 64 20 6f 66 20 74  s the rowid of t
30220 68 65 20 72 6f 77 20 61 66 74 65 72 0a 2a 2a 20  he row after.** 
30230 20 20 20 20 20 20 20 20 20 74 68 65 20 63 68 61           the cha
30240 6e 67 65 20 6f 63 63 75 72 73 2e 0a 2a 2f 0a 76  nge occurs..*/.v
30250 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 70 64  oid *sqlite3_upd
30260 61 74 65 5f 68 6f 6f 6b 28 0a 20 20 73 71 6c 69  ate_hook(.  sqli
30270 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29  te3*, .  void(*)
30280 28 76 6f 69 64 20 2a 2c 69 6e 74 20 2c 63 68 61  (void *,int ,cha
30290 72 20 63 6f 6e 73 74 20 2a 2c 63 68 61 72 20 63  r const *,char c
302a0 6f 6e 73 74 20 2a 2c 73 71 6c 69 74 65 33 5f 69  onst *,sqlite3_i
302b0 6e 74 36 34 29 2c 0a 20 20 76 6f 69 64 2a 0a 29  nt64),.  void*.)
302c0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
302d0 46 3a 20 20 45 6e 61 62 6c 65 20 4f 72 20 44 69  F:  Enable Or Di
302e0 73 61 62 6c 65 20 53 68 61 72 65 64 20 50 61 67  sable Shared Pag
302f0 65 72 20 43 61 63 68 65 20 7b 46 31 30 33 33 30  er Cache {F10330
30300 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  }.**.** This rou
30310 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20  tine enables or 
30320 64 69 73 61 62 6c 65 73 20 74 68 65 20 73 68 61  disables the sha
30330 72 69 6e 67 20 6f 66 20 74 68 65 20 64 61 74 61  ring of the data
30340 62 61 73 65 20 63 61 63 68 65 0a 2a 2a 20 61 6e  base cache.** an
30350 64 20 73 63 68 65 6d 61 20 64 61 74 61 20 73 74  d schema data st
30360 72 75 63 74 75 72 65 73 20 62 65 74 77 65 65 6e  ructures between
30370 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 74 6f 20   connections to 
30380 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
30390 65 2e 0a 2a 2a 20 53 68 61 72 69 6e 67 20 69 73  e..** Sharing is
303a0 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20   enabled if the 
303b0 61 72 67 75 6d 65 6e 74 20 69 73 20 74 72 75 65  argument is true
303c0 20 61 6e 64 20 64 69 73 61 62 6c 65 64 20 69 66   and disabled if
303d0 20 74 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a   the argument.**
303e0 20 69 73 20 66 61 6c 73 65 2e 0a 2a 2a 0a 2a 2a   is false..**.**
303f0 20 43 61 63 68 65 20 73 68 61 72 69 6e 67 20 69   Cache sharing i
30400 73 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 64 69  s enabled and di
30410 73 61 62 6c 65 64 0a 2a 2a 20 66 6f 72 20 61 6e  sabled.** for an
30420 20 65 6e 74 69 72 65 20 70 72 6f 63 65 73 73 2e   entire process.
30430 20 7b 45 4e 44 7d 20 54 68 69 73 20 69 73 20 61   {END} This is a
30440 20 63 68 61 6e 67 65 20 61 73 20 6f 66 20 53 51   change as of SQ
30450 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35  Lite version 3.5
30460 2e 30 2e 0a 2a 2a 20 49 6e 20 70 72 69 6f 72 20  .0..** In prior 
30470 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
30480 74 65 2c 20 73 68 61 72 69 6e 67 20 77 61 73 0a  te, sharing was.
30490 2a 2a 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69  ** enabled or di
304a0 73 61 62 6c 65 64 20 66 6f 72 20 65 61 63 68 20  sabled for each 
304b0 74 68 72 65 61 64 20 73 65 70 61 72 61 74 65 6c  thread separatel
304c0 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 63  y..**.** The cac
304d0 68 65 20 73 68 61 72 69 6e 67 20 6d 6f 64 65 20  he sharing mode 
304e0 73 65 74 20 62 79 20 74 68 69 73 20 69 6e 74 65  set by this inte
304f0 72 66 61 63 65 20 65 66 66 65 63 74 73 20 61 6c  rface effects al
30500 6c 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20  l subsequent.** 
30510 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
30520 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
30530 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20  te3_open_v2()], 
30540 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  and [sqlite3_ope
30550 6e 31 36 28 29 5d 2e 0a 2a 2a 20 45 78 69 73 74  n16()]..** Exist
30560 69 6e 67 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ing database con
30570 6e 65 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75  nections continu
30580 65 20 75 73 65 20 74 68 65 20 73 68 61 72 69 6e  e use the sharin
30590 67 20 6d 6f 64 65 0a 2a 2a 20 74 68 61 74 20 77  g mode.** that w
305a0 61 73 20 69 6e 20 65 66 66 65 63 74 20 61 74 20  as in effect at 
305b0 74 68 65 20 74 69 6d 65 20 74 68 65 79 20 77 65  the time they we
305c0 72 65 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a  re opened..**.**
305d0 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20   Virtual tables 
305e0 63 61 6e 6e 6f 74 20 62 65 20 75 73 65 64 20 77  cannot be used w
305f0 69 74 68 20 61 20 73 68 61 72 65 64 20 63 61 63  ith a shared cac
30600 68 65 2e 20 20 20 57 68 65 6e 20 73 68 61 72 65  he.   When share
30610 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e  d.** cache is en
30620 61 62 6c 65 64 2c 20 74 68 65 20 5b 73 71 6c 69  abled, the [sqli
30630 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c  te3_create_modul
30640 65 28 29 5d 20 41 50 49 20 75 73 65 64 20 74 6f  e()] API used to
30650 20 72 65 67 69 73 74 65 72 0a 2a 2a 20 76 69 72   register.** vir
30660 74 75 61 6c 20 74 61 62 6c 65 73 20 77 69 6c 6c  tual tables will
30670 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20 61   always return a
30680 6e 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54  n error..**.** T
30690 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75  his routine retu
306a0 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  rns [SQLITE_OK] 
306b0 69 66 20 73 68 61 72 65 64 20 63 61 63 68 65 20  if shared cache 
306c0 77 61 73 0a 2a 2a 20 65 6e 61 62 6c 65 64 20 6f  was.** enabled o
306d0 72 20 64 69 73 61 62 6c 65 64 20 73 75 63 63 65  r disabled succe
306e0 73 73 66 75 6c 6c 79 2e 20 20 41 6e 20 5b 65 72  ssfully.  An [er
306f0 72 6f 72 20 63 6f 64 65 5d 0a 2a 2a 20 69 73 20  ror code].** is 
30700 72 65 74 75 72 6e 65 64 20 6f 74 68 65 72 77 69  returned otherwi
30710 73 65 2e 0a 2a 2a 0a 2a 2a 20 53 68 61 72 65 64  se..**.** Shared
30720 20 63 61 63 68 65 20 69 73 20 64 69 73 61 62 6c   cache is disabl
30730 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 20 42  ed by default. B
30740 75 74 20 74 68 69 73 20 6d 69 67 68 74 20 63 68  ut this might ch
30750 61 6e 67 65 20 69 6e 0a 2a 2a 20 66 75 74 75 72  ange in.** futur
30760 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
30770 4c 69 74 65 2e 20 20 41 70 70 6c 69 63 61 74 69  Lite.  Applicati
30780 6f 6e 73 20 74 68 61 74 20 63 61 72 65 20 61 62  ons that care ab
30790 6f 75 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61  out shared.** ca
307a0 63 68 65 20 73 65 74 74 69 6e 67 20 73 68 6f 75  che setting shou
307b0 6c 64 20 73 65 74 20 69 74 20 65 78 70 6c 69 63  ld set it explic
307c0 69 74 6c 79 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  itly..**.** INVA
307d0 52 49 41 4e 54 53 3a 0a 2a 2a 20 0a 2a 2a 20 7b  RIANTS:.** .** {
307e0 46 31 30 33 33 31 7d 20 41 20 73 75 63 63 65 73  F10331} A succes
307f0 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20  sful invocation 
30800 6f 66 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62  of [sqlite3_enab
30810 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28  le_shared_cache(
30820 42 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  B)].**          
30830 77 69 6c 6c 20 65 6e 61 62 6c 65 20 6f 72 20 64  will enable or d
30840 69 73 61 62 6c 65 20 73 68 61 72 65 64 20 63 61  isable shared ca
30850 63 68 65 20 6d 6f 64 65 20 66 6f 72 20 61 6e 79  che mode for any
30860 20 73 75 62 73 65 71 75 65 6e 74 6c 79 0a 2a 2a   subsequently.**
30870 20 20 20 20 20 20 20 20 20 20 63 72 65 61 74 65            create
30880 64 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  d [database conn
30890 65 63 74 69 6f 6e 5d 20 69 6e 20 74 68 65 20 73  ection] in the s
308a0 61 6d 65 20 70 72 6f 63 65 73 73 2e 0a 2a 2a 0a  ame process..**.
308b0 2a 2a 20 7b 46 31 30 33 33 36 7d 20 57 68 65 6e  ** {F10336} When
308c0 20 73 68 61 72 65 64 20 63 61 63 68 65 20 69 73   shared cache is
308d0 20 65 6e 61 62 6c 65 64 2c 20 74 68 65 20 5b 73   enabled, the [s
308e0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f  qlite3_create_mo
308f0 64 75 6c 65 28 29 5d 0a 2a 2a 20 20 20 20 20 20  dule()].**      
30900 20 20 20 20 69 6e 74 65 72 66 61 63 65 20 77 69      interface wi
30910 6c 6c 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  ll always return
30920 20 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a   an error..**.**
30930 20 7b 46 31 30 33 33 37 7d 20 54 68 65 20 5b 73   {F10337} The [s
30940 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68  qlite3_enable_sh
30950 61 72 65 64 5f 63 61 63 68 65 28 42 29 5d 20 69  ared_cache(B)] i
30960 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
30970 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51  .**          [SQ
30980 4c 49 54 45 5f 4f 4b 5d 20 69 66 20 73 68 61 72  LITE_OK] if shar
30990 65 64 20 63 61 63 68 65 20 77 61 73 20 65 6e 61  ed cache was ena
309a0 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64  bled or disabled
309b0 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 0a 2a   successfully..*
309c0 2a 0a 2a 2a 20 7b 46 31 30 33 33 39 7d 20 53 68  *.** {F10339} Sh
309d0 61 72 65 64 20 63 61 63 68 65 20 69 73 20 64 69  ared cache is di
309e0 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  sabled by defaul
309f0 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  t..*/.int sqlite
30a00 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f  3_enable_shared_
30a10 63 61 63 68 65 28 69 6e 74 29 3b 0a 0a 2f 2a 0a  cache(int);../*.
30a20 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 41 74  ** CAPI3REF:  At
30a30 74 65 6d 70 74 20 54 6f 20 46 72 65 65 20 48 65  tempt To Free He
30a40 61 70 20 4d 65 6d 6f 72 79 20 7b 46 31 37 33 34  ap Memory {F1734
30a50 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  0}.**.** The sql
30a60 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d  ite3_release_mem
30a70 6f 72 79 28 29 20 69 6e 74 65 72 66 61 63 65 20  ory() interface 
30a80 61 74 74 65 6d 70 74 73 20 74 6f 0a 2a 2a 20 66  attempts to.** f
30a90 72 65 65 20 4e 20 62 79 74 65 73 20 6f 66 20 68  ree N bytes of h
30aa0 65 61 70 20 6d 65 6d 6f 72 79 20 62 79 20 64 65  eap memory by de
30ab0 61 6c 6c 6f 63 61 74 69 6e 67 20 6e 6f 6e 2d 65  allocating non-e
30ac0 73 73 65 6e 74 69 61 6c 20 6d 65 6d 6f 72 79 0a  ssential memory.
30ad0 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 68  ** allocations h
30ae0 65 6c 64 20 62 79 20 74 68 65 20 64 61 74 61 62  eld by the datab
30af0 61 73 65 20 6c 61 62 72 61 72 79 2e 20 7b 45 4e  ase labrary. {EN
30b00 44 7d 20 20 4d 65 6d 6f 72 79 20 75 73 65 64 0a  D}  Memory used.
30b10 2a 2a 20 74 6f 20 63 61 63 68 65 20 64 61 74 61  ** to cache data
30b20 62 61 73 65 20 70 61 67 65 73 20 74 6f 20 69 6d  base pages to im
30b30 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e 63  prove performanc
30b40 65 20 69 73 20 61 6e 20 65 78 61 6d 70 6c 65 20  e is an example 
30b50 6f 66 0a 2a 2a 20 6e 6f 6e 2d 65 73 73 65 6e 74  of.** non-essent
30b60 69 61 6c 20 6d 65 6d 6f 72 79 2e 20 20 53 71 6c  ial memory.  Sql
30b70 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d  ite3_release_mem
30b80 6f 72 79 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a  ory() returns.**
30b90 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
30ba0 79 74 65 73 20 61 63 74 75 61 6c 6c 79 20 66 72  ytes actually fr
30bb0 65 65 64 2c 20 77 68 69 63 68 20 6d 69 67 68 74  eed, which might
30bc0 20 62 65 20 6d 6f 72 65 20 6f 72 20 6c 65 73 73   be more or less
30bd0 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20 61 6d 6f  .** than the amo
30be0 75 6e 74 20 72 65 71 75 65 73 74 65 64 2e 0a 2a  unt requested..*
30bf0 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
30c00 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 34 31 7d 20  .**.** {F17341} 
30c10 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c  The [sqlite3_rel
30c20 65 61 73 65 5f 6d 65 6d 6f 72 79 28 4e 29 5d 20  ease_memory(N)] 
30c30 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70  interface attemp
30c40 74 73 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20  ts to.**        
30c50 20 20 66 72 65 65 20 4e 20 62 79 74 65 73 20 6f    free N bytes o
30c60 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 62 79  f heap memory by
30c70 20 64 65 61 6c 6c 6f 63 61 74 69 6e 67 20 6e 6f   deallocating no
30c80 6e 2d 65 73 73 65 6e 74 69 61 6c 0a 2a 2a 20 20  n-essential.**  
30c90 20 20 20 20 20 20 20 20 6d 65 6d 6f 72 79 20 61          memory a
30ca0 6c 6c 6f 63 61 74 69 6f 6e 73 20 68 65 6c 64 20  llocations held 
30cb0 62 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20  by the database 
30cc0 6c 61 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 7b  labrary..**.** {
30cd0 46 31 36 33 34 32 7d 20 54 68 65 20 5b 73 71 6c  F16342} The [sql
30ce0 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d  ite3_release_mem
30cf0 6f 72 79 28 4e 29 5d 20 72 65 74 75 72 6e 73 20  ory(N)] returns 
30d00 74 68 65 20 6e 75 6d 62 65 72 0a 2a 2a 20 20 20  the number.**   
30d10 20 20 20 20 20 20 20 6f 66 20 62 79 74 65 73 20         of bytes 
30d20 61 63 74 75 61 6c 6c 79 20 66 72 65 65 64 2c 20  actually freed, 
30d30 77 68 69 63 68 20 6d 69 67 68 74 20 62 65 20 6d  which might be m
30d40 6f 72 65 20 6f 72 20 6c 65 73 73 0a 2a 2a 20 20  ore or less.**  
30d50 20 20 20 20 20 20 20 20 74 68 61 6e 20 74 68 65          than the
30d60 20 61 6d 6f 75 6e 74 20 72 65 71 75 65 73 74 65   amount requeste
30d70 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  d..*/.int sqlite
30d80 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79  3_release_memory
30d90 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  (int);../*.** CA
30da0 50 49 33 52 45 46 3a 20 20 49 6d 70 6f 73 65 20  PI3REF:  Impose 
30db0 41 20 4c 69 6d 69 74 20 4f 6e 20 48 65 61 70 20  A Limit On Heap 
30dc0 53 69 7a 65 20 7b 46 31 37 33 35 30 7d 0a 2a 2a  Size {F17350}.**
30dd0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
30de0 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28  soft_heap_limit(
30df0 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 70  ) interface.** p
30e00 6c 61 63 65 73 20 61 20 22 73 6f 66 74 22 20 6c  laces a "soft" l
30e10 69 6d 69 74 20 6f 6e 20 74 68 65 20 61 6d 6f 75  imit on the amou
30e20 6e 74 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72  nt of heap memor
30e30 79 20 74 68 61 74 20 6d 61 79 20 62 65 20 61 6c  y that may be al
30e40 6c 6f 63 61 74 65 64 0a 2a 2a 20 62 79 20 53 51  located.** by SQ
30e50 4c 69 74 65 2e 20 49 66 20 61 6e 20 69 6e 74 65  Lite. If an inte
30e60 72 6e 61 6c 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  rnal allocation 
30e70 69 73 20 72 65 71 75 65 73 74 65 64 20 0a 2a 2a  is requested .**
30e80 20 74 68 61 74 20 77 6f 75 6c 64 20 65 78 63 65   that would exce
30e90 65 64 20 74 68 65 20 73 6f 66 74 20 68 65 61 70  ed the soft heap
30ea0 20 6c 69 6d 69 74 2c 20 5b 73 71 6c 69 74 65 33   limit, [sqlite3
30eb0 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28  _release_memory(
30ec0 29 5d 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64  )] is.** invoked
30ed0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d   one or more tim
30ee0 65 73 20 74 6f 20 66 72 65 65 20 75 70 20 73 6f  es to free up so
30ef0 6d 65 20 73 70 61 63 65 20 62 65 66 6f 72 65 20  me space before 
30f00 74 68 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  the allocation.*
30f10 2a 20 69 73 20 6d 61 64 65 2e 0a 2a 2a 0a 2a 2a  * is made..**.**
30f20 20 54 68 65 20 6c 69 6d 69 74 20 69 73 20 63 61   The limit is ca
30f30 6c 6c 65 64 20 22 73 6f 66 74 22 2c 20 62 65 63  lled "soft", bec
30f40 61 75 73 65 20 69 66 0a 2a 2a 20 5b 73 71 6c 69  ause if.** [sqli
30f50 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f  te3_release_memo
30f60 72 79 28 29 5d 20 63 61 6e 6e 6f 74 0a 2a 2a 20  ry()] cannot.** 
30f70 66 72 65 65 20 73 75 66 66 69 63 69 65 6e 74 20  free sufficient 
30f80 6d 65 6d 6f 72 79 20 74 6f 20 70 72 65 76 65 6e  memory to preven
30f90 74 20 74 68 65 20 6c 69 6d 69 74 20 66 72 6f 6d  t the limit from
30fa0 20 62 65 69 6e 67 20 65 78 63 65 65 64 65 64 2c   being exceeded,
30fb0 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 69  .** the memory i
30fc0 73 20 61 6c 6c 6f 63 61 74 65 64 20 61 6e 79 77  s allocated anyw
30fd0 61 79 20 61 6e 64 20 74 68 65 20 63 75 72 72 65  ay and the curre
30fe0 6e 74 20 6f 70 65 72 61 74 69 6f 6e 20 70 72 6f  nt operation pro
30ff0 63 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 6e  ceeds..**.** A n
31000 65 67 61 74 69 76 65 20 6f 72 20 7a 65 72 6f 20  egative or zero 
31010 76 61 6c 75 65 20 66 6f 72 20 4e 20 6d 65 61 6e  value for N mean
31020 73 20 74 68 61 74 20 74 68 65 72 65 20 69 73 20  s that there is 
31030 6e 6f 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d  no soft heap lim
31040 69 74 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  it and.** [sqlit
31050 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72  e3_release_memor
31060 79 28 29 5d 20 77 69 6c 6c 20 6f 6e 6c 79 20 62  y()] will only b
31070 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 6d 65  e called when me
31080 6d 6f 72 79 20 69 73 20 65 78 68 61 75 73 74 65  mory is exhauste
31090 64 2e 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c  d..** The defaul
310a0 74 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20  t value for the 
310b0 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20  soft heap limit 
310c0 69 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53  is zero..**.** S
310d0 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 62 65  QLite makes a be
310e0 73 74 20 65 66 66 6f 72 74 20 74 6f 20 68 6f 6e  st effort to hon
310f0 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65 61 70  or the soft heap
31100 20 6c 69 6d 69 74 2e 20 20 0a 2a 2a 20 42 75 74   limit.  .** But
31110 20 69 66 20 74 68 65 20 73 6f 66 74 20 68 65 61   if the soft hea
31120 70 20 6c 69 6d 69 74 20 63 61 6e 6e 6f 74 20 68  p limit cannot h
31130 6f 6e 6f 72 65 64 2c 20 65 78 65 63 75 74 69 6f  onored, executio
31140 6e 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 69 6e  n will.** contin
31150 75 65 20 77 69 74 68 6f 75 74 20 65 72 72 6f 72  ue without error
31160 20 6f 72 20 6e 6f 74 69 66 69 63 61 74 69 6f 6e   or notification
31170 2e 20 20 54 68 69 73 20 69 73 20 77 68 79 20 74  .  This is why t
31180 68 65 20 6c 69 6d 69 74 20 69 73 20 0a 2a 2a 20  he limit is .** 
31190 63 61 6c 6c 65 64 20 61 20 22 73 6f 66 74 22 20  called a "soft" 
311a0 6c 69 6d 69 74 2e 20 20 49 74 20 69 73 20 61 64  limit.  It is ad
311b0 76 69 73 6f 72 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a  visory only..**.
311c0 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53 51 4c 69  ** Prior to SQLi
311d0 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30  te version 3.5.0
311e0 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 6f  , this routine o
311f0 6e 6c 79 20 63 6f 6e 73 74 72 61 69 6e 65 64 20  nly constrained 
31200 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c  the memory.** al
31210 6c 6f 63 61 74 65 64 20 62 79 20 61 20 73 69 6e  located by a sin
31220 67 6c 65 20 74 68 72 65 61 64 20 2d 20 74 68 65  gle thread - the
31230 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20   same thread in 
31240 77 68 69 63 68 20 74 68 69 73 20 72 6f 75 74 69  which this routi
31250 6e 65 0a 2a 2a 20 72 75 6e 73 2e 20 20 42 65 67  ne.** runs.  Beg
31260 69 6e 6e 69 6e 67 20 77 69 74 68 20 53 51 4c 69  inning with SQLi
31270 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30  te version 3.5.0
31280 2c 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20  , the soft heap 
31290 6c 69 6d 69 74 20 69 73 0a 2a 2a 20 61 70 70 6c  limit is.** appl
312a0 69 65 64 20 74 6f 20 61 6c 6c 20 74 68 72 65 61  ied to all threa
312b0 64 73 2e 20 54 68 65 20 76 61 6c 75 65 20 73 70  ds. The value sp
312c0 65 63 69 66 69 65 64 20 66 6f 72 20 74 68 65 20  ecified for the 
312d0 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 0a  soft heap limit.
312e0 2a 2a 20 69 73 20 61 6e 20 75 70 70 65 72 20 62  ** is an upper b
312f0 6f 75 6e 64 20 6f 6e 20 74 68 65 20 74 6f 74 61  ound on the tota
31300 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
31310 69 6f 6e 20 66 6f 72 20 61 6c 6c 20 74 68 72 65  ion for all thre
31320 61 64 73 2e 20 49 6e 0a 2a 2a 20 76 65 72 73 69  ads. In.** versi
31330 6f 6e 20 33 2e 35 2e 30 20 74 68 65 72 65 20 69  on 3.5.0 there i
31340 73 20 6e 6f 20 6d 65 63 68 61 6e 69 73 6d 20 66  s no mechanism f
31350 6f 72 20 6c 69 6d 69 74 69 6e 67 20 74 68 65 20  or limiting the 
31360 68 65 61 70 20 75 73 61 67 65 20 66 6f 72 0a 2a  heap usage for.*
31370 2a 20 69 6e 64 69 76 69 64 75 61 6c 20 74 68 72  * individual thr
31380 65 61 64 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  eads..**.** INVA
31390 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  RIANTS:.**.** {F
313a0 31 36 33 35 31 7d 20 54 68 65 20 5b 73 71 6c 69  16351} The [sqli
313b0 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69  te3_soft_heap_li
313c0 6d 69 74 28 4e 29 5d 20 69 6e 74 65 72 66 61 63  mit(N)] interfac
313d0 65 20 70 6c 61 63 65 73 20 61 20 73 6f 66 74 20  e places a soft 
313e0 6c 69 6d 69 74 0a 2a 2a 20 20 20 20 20 20 20 20  limit.**        
313f0 20 20 6f 66 20 4e 20 62 79 74 65 73 20 6f 6e 20    of N bytes on 
31400 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 68 65  the amount of he
31410 61 70 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 6d  ap memory that m
31420 61 79 20 62 65 20 61 6c 6c 6f 63 61 74 65 64 0a  ay be allocated.
31430 2a 2a 20 20 20 20 20 20 20 20 20 20 75 73 69 6e  **          usin
31440 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  g [sqlite3_mallo
31450 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  c()] or [sqlite3
31460 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 61 74 20 61  _realloc()] at a
31470 6e 79 20 70 6f 69 6e 74 0a 2a 2a 20 20 20 20 20  ny point.**     
31480 20 20 20 20 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a       in time..**
31490 0a 2a 2a 20 7b 46 31 36 33 35 32 7d 20 49 66 20  .** {F16352} If 
314a0 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  a call to [sqlit
314b0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20  e3_malloc()] or 
314c0 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
314d0 28 29 5d 20 77 6f 75 6c 64 0a 2a 2a 20 20 20 20  ()] would.**    
314e0 20 20 20 20 20 20 63 61 75 73 65 20 74 68 65 20        cause the 
314f0 74 6f 74 61 6c 20 61 6d 6f 75 6e 74 20 6f 66 20  total amount of 
31500 61 6c 6c 6f 63 61 74 65 64 20 6d 65 6d 6f 72 79  allocated memory
31510 20 74 6f 20 65 78 63 65 65 64 20 74 68 65 0a 2a   to exceed the.*
31520 2a 20 20 20 20 20 20 20 20 20 20 73 6f 66 74 20  *          soft 
31530 68 65 61 70 20 6c 69 6d 69 74 2c 20 74 68 65 6e  heap limit, then
31540 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73   [sqlite3_releas
31550 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 69 73 20 69  e_memory()] is i
31560 6e 76 6f 6b 65 64 0a 2a 2a 20 20 20 20 20 20 20  nvoked.**       
31570 20 20 20 69 6e 20 61 6e 20 61 74 74 65 6d 70 74     in an attempt
31580 20 74 6f 20 72 65 64 75 63 65 20 74 68 65 20 6d   to reduce the m
31590 65 6d 6f 72 79 20 75 73 61 67 65 20 70 72 69 6f  emory usage prio
315a0 72 20 74 6f 20 70 72 6f 63 65 65 64 69 6e 67 0a  r to proceeding.
315b0 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69 74 68  **          with
315c0 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
315d0 63 61 74 69 6f 6e 20 61 74 74 65 6d 70 74 2e 0a  cation attempt..
315e0 2a 2a 0a 2a 2a 20 7b 46 31 36 33 35 33 7d 20 43  **.** {F16353} C
315f0 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
31600 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73  _malloc()] or [s
31610 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
31620 5d 20 74 68 61 74 20 74 72 69 67 67 65 72 0a 2a  ] that trigger.*
31630 2a 20 20 20 20 20 20 20 20 20 20 61 74 74 65 6d  *          attem
31640 70 74 73 20 74 6f 20 72 65 64 75 63 65 20 6d 65  pts to reduce me
31650 6d 6f 72 79 20 75 73 61 67 65 20 74 68 72 6f 75  mory usage throu
31660 67 68 20 74 68 65 20 73 6f 66 74 20 68 65 61 70  gh the soft heap
31670 20 6c 69 6d 69 74 0a 2a 2a 20 20 20 20 20 20 20   limit.**       
31680 20 20 20 6d 65 63 68 61 6e 69 73 6d 20 63 6f 6e     mechanism con
31690 74 69 6e 75 65 20 65 76 65 6e 20 69 66 20 74 68  tinue even if th
316a0 65 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 64  e attempt to red
316b0 75 63 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20  uce memory.**   
316c0 20 20 20 20 20 20 20 75 73 61 67 65 20 69 73 20         usage is 
316d0 75 6e 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2a  unsuccessful..**
316e0 0a 2a 2a 20 7b 46 31 36 33 35 34 7d 20 41 20 6e  .** {F16354} A n
316f0 65 67 61 74 69 76 65 20 6f 72 20 7a 65 72 6f 20  egative or zero 
31700 76 61 6c 75 65 20 66 6f 72 20 4e 20 69 6e 20 61  value for N in a
31710 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 20 20 20 20   call to.**     
31720 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 6f       [sqlite3_so
31730 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 4e 29  ft_heap_limit(N)
31740 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
31750 72 65 20 69 73 20 6e 6f 20 73 6f 66 74 0a 2a 2a  re is no soft.**
31760 20 20 20 20 20 20 20 20 20 20 68 65 61 70 20 6c            heap l
31770 69 6d 69 74 20 61 6e 64 20 5b 73 71 6c 69 74 65  imit and [sqlite
31780 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79  3_release_memory
31790 28 29 5d 20 77 69 6c 6c 20 6f 6e 6c 79 20 62 65  ()] will only be
317a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c  .**          cal
317b0 6c 65 64 20 77 68 65 6e 20 6d 65 6d 6f 72 79 20  led when memory 
317c0 69 73 20 63 6f 6d 70 6c 65 74 65 6c 79 20 65 78  is completely ex
317d0 68 61 75 73 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b  hausted..**.** {
317e0 46 31 36 33 35 35 7d 20 54 68 65 20 64 65 66 61  F16355} The defa
317f0 75 6c 74 20 76 61 6c 75 65 20 66 6f 72 20 74 68  ult value for th
31800 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69  e soft heap limi
31810 74 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a  t is zero..**.**
31820 20 7b 46 31 36 33 35 38 7d 20 45 61 63 68 20 63   {F16358} Each c
31830 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
31840 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28  soft_heap_limit(
31850 4e 29 5d 20 6f 76 65 72 72 69 64 65 73 20 74 68  N)] overrides th
31860 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61  e.**          va
31870 6c 75 65 73 20 73 65 74 20 62 79 20 61 6c 6c 20  lues set by all 
31880 70 72 69 6f 72 20 63 61 6c 6c 73 2e 0a 2a 2f 0a  prior calls..*/.
31890 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 6f 66  void sqlite3_sof
318a0 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 69 6e 74  t_heap_limit(int
318b0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
318c0 45 46 3a 20 20 45 78 74 72 61 63 74 20 4d 65 74  EF:  Extract Met
318d0 61 64 61 74 61 20 41 62 6f 75 74 20 41 20 43 6f  adata About A Co
318e0 6c 75 6d 6e 20 4f 66 20 41 20 54 61 62 6c 65 20  lumn Of A Table 
318f0 7b 46 31 32 38 35 30 7d 0a 2a 2a 0a 2a 2a 20 54  {F12850}.**.** T
31900 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72  his routine.** r
31910 65 74 75 72 6e 73 20 6d 65 74 61 2d 64 61 74 61  eturns meta-data
31920 20 61 62 6f 75 74 20 61 20 73 70 65 63 69 66 69   about a specifi
31930 63 20 63 6f 6c 75 6d 6e 20 6f 66 20 61 20 73 70  c column of a sp
31940 65 63 69 66 69 63 20 64 61 74 61 62 61 73 65 0a  ecific database.
31950 2a 2a 20 74 61 62 6c 65 20 61 63 63 65 73 73 69  ** table accessi
31960 62 6c 65 20 75 73 69 6e 67 20 74 68 65 20 63 6f  ble using the co
31970 6e 6e 65 63 74 69 6f 6e 20 68 61 6e 64 6c 65 20  nnection handle 
31980 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69  passed as the fi
31990 72 73 74 20 66 75 6e 63 74 69 6f 6e 20 0a 2a 2a  rst function .**
319a0 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
319b0 20 54 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 69   The column is i
319c0 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65  dentified by the
319d0 20 73 65 63 6f 6e 64 2c 20 74 68 69 72 64 20 61   second, third a
319e0 6e 64 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  nd fourth parame
319f0 74 65 72 73 20 74 6f 20 0a 2a 2a 20 74 68 69 73  ters to .** this
31a00 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 73   function. The s
31a10 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
31a20 69 73 20 65 69 74 68 65 72 20 74 68 65 20 6e 61  is either the na
31a30 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  me of the databa
31a40 73 65 0a 2a 2a 20 28 69 2e 65 2e 20 22 6d 61 69  se.** (i.e. "mai
31a50 6e 22 2c 20 22 74 65 6d 70 22 20 6f 72 20 61 6e  n", "temp" or an
31a60 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61   attached databa
31a70 73 65 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  se) containing t
31a80 68 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20  he specified.** 
31a90 74 61 62 6c 65 20 6f 72 20 4e 55 4c 4c 2e 20 49  table or NULL. I
31aa0 66 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68  f it is NULL, th
31ab0 65 6e 20 61 6c 6c 20 61 74 74 61 63 68 65 64 20  en all attached 
31ac0 64 61 74 61 62 61 73 65 73 20 61 72 65 20 73 65  databases are se
31ad0 61 72 63 68 65 64 0a 2a 2a 20 66 6f 72 20 74 68  arched.** for th
31ae0 65 20 74 61 62 6c 65 20 75 73 69 6e 67 20 74 68  e table using th
31af0 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d  e same algorithm
31b00 20 61 73 20 74 68 65 20 64 61 74 61 62 61 73 65   as the database
31b10 20 65 6e 67 69 6e 65 20 75 73 65 73 20 74 6f 20   engine uses to 
31b20 0a 2a 2a 20 72 65 73 6f 6c 76 65 20 75 6e 71 75  .** resolve unqu
31b30 61 6c 69 66 69 65 64 20 74 61 62 6c 65 20 72 65  alified table re
31b40 66 65 72 65 6e 63 65 73 2e 0a 2a 2a 0a 2a 2a 20  ferences..**.** 
31b50 54 68 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f  The third and fo
31b60 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 73 20  urth parameters 
31b70 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  to this function
31b80 20 61 72 65 20 74 68 65 20 74 61 62 6c 65 20 61   are the table a
31b90 6e 64 20 63 6f 6c 75 6d 6e 20 0a 2a 2a 20 6e 61  nd column .** na
31ba0 6d 65 20 6f 66 20 74 68 65 20 64 65 73 69 72 65  me of the desire
31bb0 64 20 63 6f 6c 75 6d 6e 2c 20 72 65 73 70 65 63  d column, respec
31bc0 74 69 76 65 6c 79 2e 20 4e 65 69 74 68 65 72 20  tively. Neither 
31bd0 6f 66 20 74 68 65 73 65 20 70 61 72 61 6d 65 74  of these paramet
31be0 65 72 73 20 0a 2a 2a 20 6d 61 79 20 62 65 20 4e  ers .** may be N
31bf0 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 4d 65 74 61 20  ULL..**.** Meta 
31c00 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72  information is r
31c10 65 74 75 72 6e 65 64 20 62 79 20 77 72 69 74 69  eturned by writi
31c20 6e 67 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79  ng to the memory
31c30 20 6c 6f 63 61 74 69 6f 6e 73 20 70 61 73 73 65   locations passe
31c40 64 20 61 73 0a 2a 2a 20 74 68 65 20 35 74 68 20  d as.** the 5th 
31c50 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20 70  and subsequent p
31c60 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 69  arameters to thi
31c70 73 20 66 75 6e 63 74 69 6f 6e 2e 20 41 6e 79 20  s function. Any 
31c80 6f 66 20 74 68 65 73 65 20 0a 2a 2a 20 61 72 67  of these .** arg
31c90 75 6d 65 6e 74 73 20 6d 61 79 20 62 65 20 4e 55  uments may be NU
31ca0 4c 4c 2c 20 69 6e 20 77 68 69 63 68 20 63 61 73  LL, in which cas
31cb0 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  e the correspond
31cc0 69 6e 67 20 65 6c 65 6d 65 6e 74 20 6f 66 20 6d  ing element of m
31cd0 65 74 61 20 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  eta .** informat
31ce0 69 6f 6e 20 69 73 20 6f 6d 6d 69 74 74 65 64 2e  ion is ommitted.
31cf0 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20  .**.** <pre>.** 
31d00 50 61 72 61 6d 65 74 65 72 20 20 20 20 20 4f 75  Parameter     Ou
31d10 74 70 75 74 20 54 79 70 65 20 20 20 20 20 20 44  tput Type      D
31d20 65 73 63 72 69 70 74 69 6f 6e 0a 2a 2a 20 2d 2d  escription.** --
31d30 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
31d40 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
31d50 2d 0a 2a 2a 0a 2a 2a 20 20 20 35 74 68 20 20 20  -.**.**   5th   
31d60 20 20 20 20 20 20 63 6f 6e 73 74 20 63 68 61 72        const char
31d70 2a 20 20 20 20 20 20 44 61 74 61 20 74 79 70 65  *      Data type
31d80 0a 2a 2a 20 20 20 36 74 68 20 20 20 20 20 20 20  .**   6th       
31d90 20 20 63 6f 6e 73 74 20 63 68 61 72 2a 20 20 20    const char*   
31da0 20 20 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 64     Name of the d
31db0 65 66 61 75 6c 74 20 63 6f 6c 6c 61 74 69 6f 6e  efault collation
31dc0 20 73 65 71 75 65 6e 63 65 20 0a 2a 2a 20 20 20   sequence .**   
31dd0 37 74 68 20 20 20 20 20 20 20 20 20 69 6e 74 20  7th         int 
31de0 20 20 20 20 20 20 20 20 20 20 20 20 20 54 72 75               Tru
31df0 65 20 69 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20  e if the column 
31e00 68 61 73 20 61 20 4e 4f 54 20 4e 55 4c 4c 20 63  has a NOT NULL c
31e10 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 20 20 38  onstraint.**   8
31e20 74 68 20 20 20 20 20 20 20 20 20 69 6e 74 20 20  th         int  
31e30 20 20 20 20 20 20 20 20 20 20 20 20 54 72 75 65              True
31e40 20 69 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69   if the column i
31e50 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 50 52  s part of the PR
31e60 49 4d 41 52 59 20 4b 45 59 0a 2a 2a 20 20 20 39  IMARY KEY.**   9
31e70 74 68 20 20 20 20 20 20 20 20 20 69 6e 74 20 20  th         int  
31e80 20 20 20 20 20 20 20 20 20 20 20 20 54 72 75 65              True
31e90 20 69 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69   if the column i
31ea0 73 20 41 55 54 4f 49 4e 43 52 45 4d 45 4e 54 0a  s AUTOINCREMENT.
31eb0 2a 2a 20 3c 2f 70 72 65 3e 0a 2a 2a 0a 2a 2a 0a  ** </pre>.**.**.
31ec0 2a 2a 20 54 68 65 20 6d 65 6d 6f 72 79 20 70 6f  ** The memory po
31ed0 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 20  inted to by the 
31ee0 63 68 61 72 61 63 74 65 72 20 70 6f 69 6e 74 65  character pointe
31ef0 72 73 20 72 65 74 75 72 6e 65 64 20 66 6f 72 20  rs returned for 
31f00 74 68 65 20 0a 2a 2a 20 64 65 63 6c 61 72 61 74  the .** declarat
31f10 69 6f 6e 20 74 79 70 65 20 61 6e 64 20 63 6f 6c  ion type and col
31f20 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20  lation sequence 
31f30 69 73 20 76 61 6c 69 64 20 6f 6e 6c 79 20 75 6e  is valid only un
31f40 74 69 6c 20 74 68 65 20 6e 65 78 74 20 0a 2a 2a  til the next .**
31f50 20 63 61 6c 6c 20 74 6f 20 61 6e 79 20 73 71 6c   call to any sql
31f60 69 74 65 20 41 50 49 20 66 75 6e 63 74 69 6f 6e  ite API function
31f70 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 73  ..**.** If the s
31f80 70 65 63 69 66 69 65 64 20 74 61 62 6c 65 20 69  pecified table i
31f90 73 20 61 63 74 75 61 6c 6c 79 20 61 20 76 69 65  s actually a vie
31fa0 77 2c 20 74 68 65 6e 20 61 6e 20 65 72 72 6f 72  w, then an error
31fb0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
31fc0 0a 2a 2a 20 49 66 20 74 68 65 20 73 70 65 63 69  .** If the speci
31fd0 66 69 65 64 20 63 6f 6c 75 6d 6e 20 69 73 20 22  fied column is "
31fe0 72 6f 77 69 64 22 2c 20 22 6f 69 64 22 20 6f 72  rowid", "oid" or
31ff0 20 22 5f 72 6f 77 69 64 5f 22 20 61 6e 64 20 61   "_rowid_" and a
32000 6e 20 0a 2a 2a 20 49 4e 54 45 47 45 52 20 50 52  n .** INTEGER PR
32010 49 4d 41 52 59 20 4b 45 59 20 63 6f 6c 75 6d 6e  IMARY KEY column
32020 20 68 61 73 20 62 65 65 6e 20 65 78 70 6c 69 63   has been explic
32030 69 74 6c 79 20 64 65 63 6c 61 72 65 64 2c 20 74  itly declared, t
32040 68 65 6e 20 74 68 65 20 6f 75 74 70 75 74 20 0a  hen the output .
32050 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 61 72  ** parameters ar
32060 65 20 73 65 74 20 66 6f 72 20 74 68 65 20 65 78  e set for the ex
32070 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65  plicitly declare
32080 64 20 63 6f 6c 75 6d 6e 2e 20 49 66 20 74 68 65  d column. If the
32090 72 65 20 69 73 20 6e 6f 0a 2a 2a 20 65 78 70 6c  re is no.** expl
320a0 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20  icitly declared 
320b0 49 50 4b 20 63 6f 6c 75 6d 6e 2c 20 74 68 65 6e  IPK column, then
320c0 20 74 68 65 20 6f 75 74 70 75 74 20 70 61 72 61   the output para
320d0 6d 65 74 65 72 73 20 61 72 65 20 73 65 74 20 61  meters are set a
320e0 73 20 0a 2a 2a 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  s .** follows:.*
320f0 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20 20  *.** <pre>.**   
32100 20 20 64 61 74 61 20 74 79 70 65 3a 20 22 49 4e    data type: "IN
32110 54 45 47 45 52 22 0a 2a 2a 20 20 20 20 20 63 6f  TEGER".**     co
32120 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
32130 3a 20 22 42 49 4e 41 52 59 22 0a 2a 2a 20 20 20  : "BINARY".**   
32140 20 20 6e 6f 74 20 6e 75 6c 6c 3a 20 30 0a 2a 2a    not null: 0.**
32150 20 20 20 20 20 70 72 69 6d 61 72 79 20 6b 65 79       primary key
32160 3a 20 31 0a 2a 2a 20 20 20 20 20 61 75 74 6f 20  : 1.**     auto 
32170 69 6e 63 72 65 6d 65 6e 74 3a 20 30 0a 2a 2a 20  increment: 0.** 
32180 3c 2f 70 72 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  </pre>.**.** Thi
32190 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 6c  s function may l
321a0 6f 61 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  oad one or more 
321b0 73 63 68 65 6d 61 73 20 66 72 6f 6d 20 64 61 74  schemas from dat
321c0 61 62 61 73 65 20 66 69 6c 65 73 2e 20 49 66 20  abase files. If 
321d0 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 6f 63 63 75  an.** error occu
321e0 72 73 20 64 75 72 69 6e 67 20 74 68 69 73 20 70  rs during this p
321f0 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 74 68  rocess, or if th
32200 65 20 72 65 71 75 65 73 74 65 64 20 74 61 62 6c  e requested tabl
32210 65 20 6f 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 63  e or column.** c
32220 61 6e 6e 6f 74 20 62 65 20 66 6f 75 6e 64 2c 20  annot be found, 
32230 61 6e 20 53 51 4c 49 54 45 20 65 72 72 6f 72 20  an SQLITE error 
32240 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64  code is returned
32250 20 61 6e 64 20 61 6e 20 65 72 72 6f 72 20 6d 65   and an error me
32260 73 73 61 67 65 0a 2a 2a 20 6c 65 66 74 20 69 6e  ssage.** left in
32270 20 74 68 65 20 64 61 74 61 62 61 73 65 20 68 61   the database ha
32280 6e 64 6c 65 20 28 74 6f 20 62 65 20 72 65 74 72  ndle (to be retr
32290 69 65 76 65 64 20 75 73 69 6e 67 20 73 71 6c 69  ieved using sqli
322a0 74 65 33 5f 65 72 72 6d 73 67 28 29 29 2e 0a 2a  te3_errmsg())..*
322b0 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49 20 69 73  *.** This API is
322c0 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20   only available 
322d0 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 20 77  if the library w
322e0 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  as compiled with
322f0 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 45   the.** SQLITE_E
32300 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54  NABLE_COLUMN_MET
32310 41 44 41 54 41 20 70 72 65 70 72 6f 63 65 73 73  ADATA preprocess
32320 6f 72 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65  or symbol define
32330 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  d..*/.int sqlite
32340 33 5f 74 61 62 6c 65 5f 63 6f 6c 75 6d 6e 5f 6d  3_table_column_m
32350 65 74 61 64 61 74 61 28 0a 20 20 73 71 6c 69 74  etadata(.  sqlit
32360 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
32370 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e 6e 65 63         /* Connec
32380 74 69 6f 6e 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  tion handle */. 
32390 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62   const char *zDb
323a0 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 2f 2a 20  Name,        /* 
323b0 44 61 74 61 62 61 73 65 20 6e 61 6d 65 20 6f 72  Database name or
323c0 20 4e 55 4c 4c 20 2a 2f 0a 20 20 63 6f 6e 73 74   NULL */.  const
323d0 20 63 68 61 72 20 2a 7a 54 61 62 6c 65 4e 61 6d   char *zTableNam
323e0 65 2c 20 20 20 20 20 2f 2a 20 54 61 62 6c 65 20  e,     /* Table 
323f0 6e 61 6d 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  name */.  const 
32400 63 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e 4e 61 6d  char *zColumnNam
32410 65 2c 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20  e,    /* Column 
32420 6e 61 6d 65 20 2a 2f 0a 20 20 63 68 61 72 20 63  name */.  char c
32430 6f 6e 73 74 20 2a 2a 70 7a 44 61 74 61 54 79 70  onst **pzDataTyp
32440 65 2c 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a  e,    /* OUTPUT:
32450 20 44 65 63 6c 61 72 65 64 20 64 61 74 61 20 74   Declared data t
32460 79 70 65 20 2a 2f 0a 20 20 63 68 61 72 20 63 6f  ype */.  char co
32470 6e 73 74 20 2a 2a 70 7a 43 6f 6c 6c 53 65 71 2c  nst **pzCollSeq,
32480 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20       /* OUTPUT: 
32490 43 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  Collation sequen
324a0 63 65 20 6e 61 6d 65 20 2a 2f 0a 20 20 69 6e 74  ce name */.  int
324b0 20 2a 70 4e 6f 74 4e 75 6c 6c 2c 20 20 20 20 20   *pNotNull,     
324c0 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50           /* OUTP
324d0 55 54 3a 20 54 72 75 65 20 69 66 20 4e 4f 54 20  UT: True if NOT 
324e0 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69 6e 74 20  NULL constraint 
324f0 65 78 69 73 74 73 20 2a 2f 0a 20 20 69 6e 74 20  exists */.  int 
32500 2a 70 50 72 69 6d 61 72 79 4b 65 79 2c 20 20 20  *pPrimaryKey,   
32510 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55          /* OUTPU
32520 54 3a 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d  T: True if colum
32530 6e 20 70 61 72 74 20 6f 66 20 50 4b 20 2a 2f 0a  n part of PK */.
32540 20 20 69 6e 74 20 2a 70 41 75 74 6f 69 6e 63 20    int *pAutoinc 
32550 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
32560 20 4f 55 54 50 55 54 3a 20 54 72 75 65 20 69 66   OUTPUT: True if
32570 20 63 6f 6c 75 6d 6e 20 69 73 20 61 75 74 6f 2d   column is auto-
32580 69 6e 63 72 65 6d 65 6e 74 20 2a 2f 0a 29 3b 0a  increment */.);.
32590 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
325a0 20 4c 6f 61 64 20 41 6e 20 45 78 74 65 6e 73 69   Load An Extensi
325b0 6f 6e 20 7b 46 31 32 36 30 30 7d 0a 2a 2a 0a 2a  on {F12600}.**.*
325c0 2a 20 7b 46 31 32 36 30 31 7d 20 54 68 65 20 73  * {F12601} The s
325d0 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65  qlite3_load_exte
325e0 6e 73 69 6f 6e 28 29 20 69 6e 74 65 72 66 61 63  nsion() interfac
325f0 65 0a 2a 2a 20 61 74 74 65 6d 70 74 73 20 74 6f  e.** attempts to
32600 20 6c 6f 61 64 20 61 6e 20 53 51 4c 69 74 65 20   load an SQLite 
32610 65 78 74 65 6e 73 69 6f 6e 20 6c 69 62 72 61 72  extension librar
32620 79 20 63 6f 6e 74 61 69 6e 65 64 20 69 6e 20 74  y contained in t
32630 68 65 20 66 69 6c 65 0a 2a 2a 20 7a 46 69 6c 65  he file.** zFile
32640 2e 20 7b 46 31 32 36 30 32 7d 20 54 68 65 20 65  . {F12602} The e
32650 6e 74 72 79 20 70 6f 69 6e 74 20 69 73 20 7a 50  ntry point is zP
32660 72 6f 63 2e 20 7b 46 31 32 36 30 33 7d 20 7a 50  roc. {F12603} zP
32670 72 6f 63 20 6d 61 79 20 62 65 20 30 0a 2a 2a 20  roc may be 0.** 
32680 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 74 68  in which case th
32690 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 65 6e  e name of the en
326a0 74 72 79 20 70 6f 69 6e 74 20 64 65 66 61 75 6c  try point defaul
326b0 74 73 0a 2a 2a 20 74 6f 20 22 73 71 6c 69 74 65  ts.** to "sqlite
326c0 33 5f 65 78 74 65 6e 73 69 6f 6e 5f 69 6e 69 74  3_extension_init
326d0 22 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36 30 34  "..**.** {F12604
326e0 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f  } The sqlite3_lo
326f0 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 69  ad_extension() i
32700 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c 0a 2a  nterface shall.*
32710 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  * return [SQLITE
32720 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20  _OK] on success 
32730 61 6e 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  and [SQLITE_ERRO
32740 52 5d 20 69 66 20 73 6f 6d 65 74 68 69 6e 67 20  R] if something 
32750 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 0a 2a  goes wrong..**.*
32760 2a 20 7b 46 31 32 36 30 35 7d 0a 2a 2a 20 49 66  * {F12605}.** If
32770 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
32780 20 61 6e 64 20 70 7a 45 72 72 4d 73 67 20 69 73   and pzErrMsg is
32790 20 6e 6f 74 20 30 2c 20 74 68 65 6e 20 74 68 65   not 0, then the
327a0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64  .** sqlite3_load
327b0 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e 74  _extension() int
327c0 65 72 66 61 63 65 20 73 68 61 6c 6c 20 61 74 74  erface shall att
327d0 65 6d 70 74 20 74 6f 20 66 69 6c 6c 20 2a 70 7a  empt to fill *pz
327e0 45 72 72 4d 73 67 20 77 69 74 68 20 0a 2a 2a 20  ErrMsg with .** 
327f0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65  error message te
32800 78 74 20 73 74 6f 72 65 64 20 69 6e 20 6d 65 6d  xt stored in mem
32810 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
32820 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
32830 63 28 29 5d 2e 0a 2a 2a 20 7b 45 4e 44 7d 20 20  c()]..** {END}  
32840 54 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63  The calling func
32850 74 69 6f 6e 20 73 68 6f 75 6c 64 20 66 72 65 65  tion should free
32860 20 74 68 69 73 20 6d 65 6d 6f 72 79 0a 2a 2a 20   this memory.** 
32870 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
32880 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a  te3_free()]..**.
32890 2a 2a 20 7b 46 31 32 36 30 36 7d 0a 2a 2a 20 45  ** {F12606}.** E
328a0 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67  xtension loading
328b0 20 6d 75 73 74 20 62 65 20 65 6e 61 62 6c 65 64   must be enabled
328c0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
328d0 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65  enable_load_exte
328e0 6e 73 69 6f 6e 28 29 5d 0a 2a 2a 20 70 72 69 6f  nsion()].** prio
328f0 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20 74 68 69  r to calling thi
32900 73 20 41 50 49 20 6f 72 20 61 6e 20 65 72 72 6f  s API or an erro
32910 72 20 77 69 6c 6c 20 62 65 20 72 65 74 75 72 6e  r will be return
32920 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ed..*/.int sqlit
32930 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  e3_load_extensio
32940 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  n(.  sqlite3 *db
32950 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4c 6f  ,          /* Lo
32960 61 64 20 74 68 65 20 65 78 74 65 6e 73 69 6f 6e  ad the extension
32970 20 69 6e 74 6f 20 74 68 69 73 20 64 61 74 61 62   into this datab
32980 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 2a  ase connection *
32990 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
329a0 7a 46 69 6c 65 2c 20 20 20 20 2f 2a 20 4e 61 6d  zFile,    /* Nam
329b0 65 20 6f 66 20 74 68 65 20 73 68 61 72 65 64 20  e of the shared 
329c0 6c 69 62 72 61 72 79 20 63 6f 6e 74 61 69 6e 69  library containi
329d0 6e 67 20 65 78 74 65 6e 73 69 6f 6e 20 2a 2f 0a  ng extension */.
329e0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50    const char *zP
329f0 72 6f 63 2c 20 20 20 20 2f 2a 20 45 6e 74 72 79  roc,    /* Entry
32a00 20 70 6f 69 6e 74 2e 20 20 44 65 72 69 76 65 64   point.  Derived
32a10 20 66 72 6f 6d 20 7a 46 69 6c 65 20 69 66 20 30   from zFile if 0
32a20 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45   */.  char **pzE
32a30 72 72 4d 73 67 20 20 20 20 20 20 20 2f 2a 20 50  rrMsg       /* P
32a40 75 74 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  ut error message
32a50 20 68 65 72 65 20 69 66 20 6e 6f 74 20 30 20 2a   here if not 0 *
32a60 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.);../*.** CAPI
32a70 33 52 45 46 3a 20 20 45 6e 61 62 6c 65 20 4f 72  3REF:  Enable Or
32a80 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e 73 69   Disable Extensi
32a90 6f 6e 20 4c 6f 61 64 69 6e 67 20 7b 46 31 32 36  on Loading {F126
32aa0 32 30 7d 0a 2a 2a 0a 2a 2a 20 53 6f 20 61 73 20  20}.**.** So as 
32ab0 6e 6f 74 20 74 6f 20 6f 70 65 6e 20 73 65 63 75  not to open secu
32ac0 72 69 74 79 20 68 6f 6c 65 73 20 69 6e 20 6f 6c  rity holes in ol
32ad0 64 65 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  der applications
32ae0 20 74 68 61 74 20 61 72 65 0a 2a 2a 20 75 6e 70   that are.** unp
32af0 72 65 70 61 72 65 64 20 74 6f 20 64 65 61 6c 20  repared to deal 
32b00 77 69 74 68 20 65 78 74 65 6e 73 69 6f 6e 20 6c  with extension l
32b10 6f 61 64 69 6e 67 2c 20 61 6e 64 20 61 73 20 61  oading, and as a
32b20 20 6d 65 61 6e 73 20 6f 66 20 64 69 73 61 62 6c   means of disabl
32b30 69 6e 67 0a 2a 2a 20 65 78 74 65 6e 73 69 6f 6e  ing.** extension
32b40 20 6c 6f 61 64 69 6e 67 20 77 68 69 6c 65 20 65   loading while e
32b50 76 61 6c 75 61 74 69 6e 67 20 75 73 65 72 2d 65  valuating user-e
32b60 6e 74 65 72 65 64 20 53 51 4c 2c 20 74 68 65 20  ntered SQL, the 
32b70 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 41 50 49  following.** API
32b80 20 69 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20   is provided to 
32b90 74 75 72 6e 20 74 68 65 20 5b 73 71 6c 69 74 65  turn the [sqlite
32ba0 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e  3_load_extension
32bb0 28 29 5d 20 6d 65 63 68 61 6e 69 73 6d 20 6f 6e  ()] mechanism on
32bc0 20 61 6e 64 0a 2a 2a 20 6f 66 66 2e 20 20 7b 46   and.** off.  {F
32bd0 31 32 36 32 32 7d 20 49 74 20 69 73 20 6f 66 66  12622} It is off
32be0 20 62 79 20 64 65 66 61 75 6c 74 2e 20 7b 45 4e   by default. {EN
32bf0 44 7d 20 53 65 65 20 74 69 63 6b 65 74 20 23 31  D} See ticket #1
32c00 38 36 33 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36  863..**.** {F126
32c10 32 31 7d 20 43 61 6c 6c 20 74 68 65 20 73 71 6c  21} Call the sql
32c20 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64  ite3_enable_load
32c30 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 72 6f 75  _extension() rou
32c40 74 69 6e 65 0a 2a 2a 20 77 69 74 68 20 6f 6e 6f  tine.** with ono
32c50 66 66 3d 3d 31 20 74 6f 20 74 75 72 6e 20 65 78  ff==1 to turn ex
32c60 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20  tension loading 
32c70 6f 6e 0a 2a 2a 20 61 6e 64 20 63 61 6c 6c 20 69  on.** and call i
32c80 74 20 77 69 74 68 20 6f 6e 6f 66 66 3d 3d 30 20  t with onoff==0 
32c90 74 6f 20 74 75 72 6e 20 69 74 20 62 61 63 6b 20  to turn it back 
32ca0 6f 66 66 20 61 67 61 69 6e 2e 20 7b 45 4e 44 7d  off again. {END}
32cb0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
32cc0 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65  enable_load_exte
32cd0 6e 73 69 6f 6e 28 73 71 6c 69 74 65 33 20 2a 64  nsion(sqlite3 *d
32ce0 62 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a  b, int onoff);..
32cf0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
32d00 4d 61 6b 65 20 41 72 72 61 6e 67 65 6d 65 6e 74  Make Arrangement
32d10 73 20 54 6f 20 41 75 74 6f 6d 61 74 69 63 61 6c  s To Automatical
32d20 6c 79 20 4c 6f 61 64 20 41 6e 20 45 78 74 65 6e  ly Load An Exten
32d30 73 69 6f 6e 20 7b 46 31 32 36 34 30 7d 0a 2a 2a  sion {F12640}.**
32d40 0a 2a 2a 20 7b 46 31 32 36 34 31 7d 20 54 68 69  .** {F12641} Thi
32d50 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 72 65  s function.** re
32d60 67 69 73 74 65 72 73 20 61 6e 20 65 78 74 65 6e  gisters an exten
32d70 73 69 6f 6e 20 65 6e 74 72 79 20 70 6f 69 6e 74  sion entry point
32d80 20 74 68 61 74 20 69 73 20 61 75 74 6f 6d 61 74   that is automat
32d90 69 63 61 6c 6c 79 20 69 6e 76 6f 6b 65 64 0a 2a  ically invoked.*
32da0 2a 20 77 68 65 6e 65 76 65 72 20 61 20 6e 65 77  * whenever a new
32db0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
32dc0 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 20 75  tion is opened u
32dd0 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
32de0 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
32df0 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72  e3_open16()], or
32e00 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
32e10 32 28 29 5d 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a  2()]. {END}.**.*
32e20 2a 20 54 68 69 73 20 41 50 49 20 63 61 6e 20 62  * This API can b
32e30 65 20 69 6e 76 6f 6b 65 64 20 61 74 20 70 72 6f  e invoked at pro
32e40 67 72 61 6d 20 73 74 61 72 74 75 70 20 69 6e 20  gram startup in 
32e50 6f 72 64 65 72 20 74 6f 20 72 65 67 69 73 74 65  order to registe
32e60 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  r.** one or more
32e70 20 73 74 61 74 69 63 61 6c 6c 79 20 6c 69 6e 6b   statically link
32e80 65 64 20 65 78 74 65 6e 73 69 6f 6e 73 20 74 68  ed extensions th
32e90 61 74 20 77 69 6c 6c 20 62 65 20 61 76 61 69 6c  at will be avail
32ea0 61 62 6c 65 0a 2a 2a 20 74 6f 20 61 6c 6c 20 6e  able.** to all n
32eb0 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ew database conn
32ec0 65 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 7b  ections..**.** {
32ed0 46 31 32 36 34 32 7d 20 44 75 70 6c 69 63 61 74  F12642} Duplicat
32ee0 65 20 65 78 74 65 6e 73 69 6f 6e 73 20 61 72 65  e extensions are
32ef0 20 64 65 74 65 63 74 65 64 20 73 6f 20 63 61 6c   detected so cal
32f00 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e  ling this routin
32f10 65 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 69  e multiple.** ti
32f20 6d 65 73 20 77 69 74 68 20 74 68 65 20 73 61 6d  mes with the sam
32f30 65 20 65 78 74 65 6e 73 69 6f 6e 20 69 73 20 68  e extension is h
32f40 61 72 6d 6c 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 7b  armless..**.** {
32f50 46 31 32 36 34 33 7d 20 54 68 69 73 20 72 6f 75  F12643} This rou
32f60 74 69 6e 65 20 73 74 6f 72 65 73 20 61 20 70 6f  tine stores a po
32f70 69 6e 74 65 72 20 74 6f 20 74 68 65 20 65 78 74  inter to the ext
32f80 65 6e 73 69 6f 6e 20 69 6e 20 61 6e 20 61 72 72  ension in an arr
32f90 61 79 0a 2a 2a 20 74 68 61 74 20 69 73 20 6f 62  ay.** that is ob
32fa0 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69  tained from sqli
32fb0 74 65 5f 6d 61 6c 6c 6f 63 28 29 2e 20 7b 45 4e  te_malloc(). {EN
32fc0 44 7d 20 49 66 20 79 6f 75 20 72 75 6e 20 61 20  D} If you run a 
32fd0 6d 65 6d 6f 72 79 20 6c 65 61 6b 0a 2a 2a 20 63  memory leak.** c
32fe0 68 65 63 6b 65 72 20 6f 6e 20 79 6f 75 72 20 70  hecker on your p
32ff0 72 6f 67 72 61 6d 20 61 6e 64 20 69 74 20 72 65  rogram and it re
33000 70 6f 72 74 73 20 61 20 6c 65 61 6b 20 62 65 63  ports a leak bec
33010 61 75 73 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20  ause of this.** 
33020 61 72 72 61 79 2c 20 74 68 65 6e 20 69 6e 76 6f  array, then invo
33030 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ke [sqlite3_rese
33040 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e  t_auto_extension
33050 28 29 5d 20 70 72 69 6f 72 0a 2a 2a 20 74 6f 20  ()] prior.** to 
33060 73 68 75 74 64 6f 77 6e 20 74 6f 20 66 72 65 65  shutdown to free
33070 20 74 68 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 0a   the memory..**.
33080 2a 2a 20 7b 46 31 32 36 34 34 7d 20 41 75 74 6f  ** {F12644} Auto
33090 6d 61 74 69 63 20 65 78 74 65 6e 73 69 6f 6e 73  matic extensions
330a0 20 61 70 70 6c 79 20 61 63 72 6f 73 73 20 61 6c   apply across al
330b0 6c 20 74 68 72 65 61 64 73 2e 20 7b 45 4e 44 7d  l threads. {END}
330c0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65  .**.** This inte
330d0 72 66 61 63 65 20 69 73 20 65 78 70 65 72 69 6d  rface is experim
330e0 65 6e 74 61 6c 20 61 6e 64 20 69 73 20 73 75 62  ental and is sub
330f0 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 6f  ject to change o
33100 72 0a 2a 2a 20 72 65 6d 6f 76 61 6c 20 69 6e 20  r.** removal in 
33110 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
33120 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e  of SQLite..*/.in
33130 74 20 73 71 6c 69 74 65 33 5f 61 75 74 6f 5f 65  t sqlite3_auto_e
33140 78 74 65 6e 73 69 6f 6e 28 76 6f 69 64 20 2a 78  xtension(void *x
33150 45 6e 74 72 79 50 6f 69 6e 74 29 3b 0a 0a 0a 2f  EntryPoint);.../
33160 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
33170 65 73 65 74 20 41 75 74 6f 6d 61 74 69 63 20 45  eset Automatic E
33180 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e 67  xtension Loading
33190 20 7b 46 31 32 36 36 30 7d 0a 2a 2a 0a 2a 2a 20   {F12660}.**.** 
331a0 7b 46 31 32 36 36 31 7d 20 54 68 69 73 20 66 75  {F12661} This fu
331b0 6e 63 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 20  nction disables 
331c0 61 6c 6c 20 70 72 65 76 69 6f 75 73 6c 79 20 72  all previously r
331d0 65 67 69 73 74 65 72 65 64 0a 2a 2a 20 61 75 74  egistered.** aut
331e0 6f 6d 61 74 69 63 20 65 78 74 65 6e 73 69 6f 6e  omatic extension
331f0 73 2e 20 7b 45 4e 44 7d 20 20 54 68 69 73 0a 2a  s. {END}  This.*
33200 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73  * routine undoes
33210 20 74 68 65 20 65 66 66 65 63 74 20 6f 66 20 61   the effect of a
33220 6c 6c 20 70 72 69 6f 72 20 5b 73 71 6c 69 74 65  ll prior [sqlite
33230 33 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e  3_auto_extension
33240 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 2e 0a 2a 2a  ()].** calls..**
33250 0a 2a 2a 20 7b 46 31 32 36 36 32 7d 20 54 68 69  .** {F12662} Thi
33260 73 20 63 61 6c 6c 20 64 69 73 61 62 6c 65 64 20  s call disabled 
33270 61 75 74 6f 6d 61 74 69 63 20 65 78 74 65 6e 73  automatic extens
33280 69 6f 6e 73 20 69 6e 20 61 6c 6c 20 74 68 72 65  ions in all thre
33290 61 64 73 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a  ads. {END}.**.**
332a0 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   This interface 
332b0 69 73 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20  is experimental 
332c0 61 6e 64 20 69 73 20 73 75 62 6a 65 63 74 20 74  and is subject t
332d0 6f 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 72  o change or.** r
332e0 65 6d 6f 76 61 6c 20 69 6e 20 66 75 74 75 72 65  emoval in future
332f0 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
33300 69 74 65 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  ite..*/.void sql
33310 69 74 65 33 5f 72 65 73 65 74 5f 61 75 74 6f 5f  ite3_reset_auto_
33320 65 78 74 65 6e 73 69 6f 6e 28 76 6f 69 64 29 3b  extension(void);
33330 0a 0a 0a 2f 2a 0a 2a 2a 2a 2a 2a 2a 20 45 58 50  .../*.****** EXP
33340 45 52 49 4d 45 4e 54 41 4c 20 2d 20 73 75 62 6a  ERIMENTAL - subj
33350 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 77 69  ect to change wi
33360 74 68 6f 75 74 20 6e 6f 74 69 63 65 20 2a 2a 2a  thout notice ***
33370 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2a 0a 2a  ***********.**.*
33380 2a 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20  * The interface 
33390 74 6f 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74  to the virtual-t
333a0 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 69  able mechanism i
333b0 73 20 63 75 72 72 65 6e 74 6c 79 20 63 6f 6e 73  s currently cons
333c0 69 64 65 72 65 64 0a 2a 2a 20 74 6f 20 62 65 20  idered.** to be 
333d0 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 54  experimental.  T
333e0 68 65 20 69 6e 74 65 72 66 61 63 65 20 6d 69 67  he interface mig
333f0 68 74 20 63 68 61 6e 67 65 20 69 6e 20 69 6e 63  ht change in inc
33400 6f 6d 70 61 74 69 62 6c 65 20 77 61 79 73 2e 0a  ompatible ways..
33410 2a 2a 20 49 66 20 74 68 69 73 20 69 73 20 61 20  ** If this is a 
33420 70 72 6f 62 6c 65 6d 20 66 6f 72 20 79 6f 75 2c  problem for you,
33430 20 64 6f 20 6e 6f 74 20 75 73 65 20 74 68 65 20   do not use the 
33440 69 6e 74 65 72 66 61 63 65 20 61 74 20 74 68 69  interface at thi
33450 73 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57 68  s time..**.** Wh
33460 65 6e 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74  en the virtual-t
33470 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 73  able mechanism s
33480 74 61 62 6c 69 7a 65 73 2c 20 77 65 20 77 69 6c  tablizes, we wil
33490 6c 20 64 65 63 6c 61 72 65 20 74 68 65 0a 2a 2a  l declare the.**
334a0 20 69 6e 74 65 72 66 61 63 65 20 66 69 78 65 64   interface fixed
334b0 2c 20 73 75 70 70 6f 72 74 20 69 74 20 69 6e 64  , support it ind
334c0 65 66 69 6e 69 74 65 6c 79 2c 20 61 6e 64 20 72  efinitely, and r
334d0 65 6d 6f 76 65 20 74 68 69 73 20 63 6f 6d 6d 65  emove this comme
334e0 6e 74 2e 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 53 74  nt..*/../*.** St
334f0 72 75 63 74 75 72 65 73 20 75 73 65 64 20 62 79  ructures used by
33500 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62   the virtual tab
33510 6c 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2f 0a  le interface.*/.
33520 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
33530 71 6c 69 74 65 33 5f 76 74 61 62 20 73 71 6c 69  qlite3_vtab sqli
33540 74 65 33 5f 76 74 61 62 3b 0a 74 79 70 65 64 65  te3_vtab;.typede
33550 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
33560 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73 71 6c 69  _index_info sqli
33570 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 3b 0a  te3_index_info;.
33580 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
33590 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
335a0 6f 72 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  or sqlite3_vtab_
335b0 63 75 72 73 6f 72 3b 0a 74 79 70 65 64 65 66 20  cursor;.typedef 
335c0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d  struct sqlite3_m
335d0 6f 64 75 6c 65 20 73 71 6c 69 74 65 33 5f 6d 6f  odule sqlite3_mo
335e0 64 75 6c 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  dule;../*.** CAP
335f0 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54  I3REF: Virtual T
33600 61 62 6c 65 20 4f 62 6a 65 63 74 20 7b 46 31 38  able Object {F18
33610 30 30 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  000}.** KEYWORDS
33620 3a 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65  : sqlite3_module
33630 0a 2a 2a 0a 2a 2a 20 41 20 6d 6f 64 75 6c 65 20  .**.** A module 
33640 69 73 20 61 20 63 6c 61 73 73 20 6f 66 20 76 69  is a class of vi
33650 72 74 75 61 6c 20 74 61 62 6c 65 73 2e 20 20 45  rtual tables.  E
33660 61 63 68 20 6d 6f 64 75 6c 65 20 69 73 20 64 65  ach module is de
33670 66 69 6e 65 64 0a 2a 2a 20 62 79 20 61 6e 20 69  fined.** by an i
33680 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 66  nstance of the f
33690 6f 6c 6c 6f 77 69 6e 67 20 73 74 72 75 63 74 75  ollowing structu
336a0 72 65 2e 20 20 54 68 69 73 20 73 74 72 75 63 74  re.  This struct
336b0 75 72 65 20 63 6f 6e 73 69 73 74 73 0a 2a 2a 20  ure consists.** 
336c0 6d 6f 73 74 6c 79 20 6f 66 20 6d 65 74 68 6f 64  mostly of method
336d0 73 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65  s for the module
336e0 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69  ..*/.struct sqli
336f0 74 65 33 5f 6d 6f 64 75 6c 65 20 7b 0a 20 20 69  te3_module {.  i
33700 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69  nt iVersion;.  i
33710 6e 74 20 28 2a 78 43 72 65 61 74 65 29 28 73 71  nt (*xCreate)(sq
33720 6c 69 74 65 33 2a 2c 20 76 6f 69 64 20 2a 70 41  lite3*, void *pA
33730 75 78 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  ux,.            
33740 20 20 20 69 6e 74 20 61 72 67 63 2c 20 63 6f 6e     int argc, con
33750 73 74 20 63 68 61 72 20 2a 63 6f 6e 73 74 2a 61  st char *const*a
33760 72 67 76 2c 0a 20 20 20 20 20 20 20 20 20 20 20  rgv,.           
33770 20 20 20 20 73 71 6c 69 74 65 33 5f 76 74 61 62      sqlite3_vtab
33780 20 2a 2a 70 70 56 54 61 62 2c 20 63 68 61 72 2a   **ppVTab, char*
33790 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6e  *);.  int (*xCon
337a0 6e 65 63 74 29 28 73 71 6c 69 74 65 33 2a 2c 20  nect)(sqlite3*, 
337b0 76 6f 69 64 20 2a 70 41 75 78 2c 0a 20 20 20 20  void *pAux,.    
337c0 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 61             int a
337d0 72 67 63 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  rgc, const char 
337e0 2a 63 6f 6e 73 74 2a 61 72 67 76 2c 0a 20 20 20  *const*argv,.   
337f0 20 20 20 20 20 20 20 20 20 20 20 20 73 71 6c 69              sqli
33800 74 65 33 5f 76 74 61 62 20 2a 2a 70 70 56 54 61  te3_vtab **ppVTa
33810 62 2c 20 63 68 61 72 2a 2a 29 3b 0a 20 20 69 6e  b, char**);.  in
33820 74 20 28 2a 78 42 65 73 74 49 6e 64 65 78 29 28  t (*xBestIndex)(
33830 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56  sqlite3_vtab *pV
33840 54 61 62 2c 20 73 71 6c 69 74 65 33 5f 69 6e 64  Tab, sqlite3_ind
33850 65 78 5f 69 6e 66 6f 2a 29 3b 0a 20 20 69 6e 74  ex_info*);.  int
33860 20 28 2a 78 44 69 73 63 6f 6e 6e 65 63 74 29 28   (*xDisconnect)(
33870 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56  sqlite3_vtab *pV
33880 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44  Tab);.  int (*xD
33890 65 73 74 72 6f 79 29 28 73 71 6c 69 74 65 33 5f  estroy)(sqlite3_
338a0 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20  vtab *pVTab);.  
338b0 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c  int (*xOpen)(sql
338c0 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62  ite3_vtab *pVTab
338d0 2c 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63  , sqlite3_vtab_c
338e0 75 72 73 6f 72 20 2a 2a 70 70 43 75 72 73 6f 72  ursor **ppCursor
338f0 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73  );.  int (*xClos
33900 65 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  e)(sqlite3_vtab_
33910 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20  cursor*);.  int 
33920 28 2a 78 46 69 6c 74 65 72 29 28 73 71 6c 69 74  (*xFilter)(sqlit
33930 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c  e3_vtab_cursor*,
33940 20 69 6e 74 20 69 64 78 4e 75 6d 2c 20 63 6f 6e   int idxNum, con
33950 73 74 20 63 68 61 72 20 2a 69 64 78 53 74 72 2c  st char *idxStr,
33960 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
33970 20 69 6e 74 20 61 72 67 63 2c 20 73 71 6c 69 74   int argc, sqlit
33980 65 33 5f 76 61 6c 75 65 20 2a 2a 61 72 67 76 29  e3_value **argv)
33990 3b 0a 20 20 69 6e 74 20 28 2a 78 4e 65 78 74 29  ;.  int (*xNext)
339a0 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75  (sqlite3_vtab_cu
339b0 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  rsor*);.  int (*
339c0 78 45 6f 66 29 28 73 71 6c 69 74 65 33 5f 76 74  xEof)(sqlite3_vt
339d0 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69  ab_cursor*);.  i
339e0 6e 74 20 28 2a 78 43 6f 6c 75 6d 6e 29 28 73 71  nt (*xColumn)(sq
339f0 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f  lite3_vtab_curso
33a00 72 2a 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  r*, sqlite3_cont
33a10 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e  ext*, int);.  in
33a20 74 20 28 2a 78 52 6f 77 69 64 29 28 73 71 6c 69  t (*xRowid)(sqli
33a30 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a  te3_vtab_cursor*
33a40 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
33a50 2a 70 52 6f 77 69 64 29 3b 0a 20 20 69 6e 74 20  *pRowid);.  int 
33a60 28 2a 78 55 70 64 61 74 65 29 28 73 71 6c 69 74  (*xUpdate)(sqlit
33a70 65 33 5f 76 74 61 62 20 2a 2c 20 69 6e 74 2c 20  e3_vtab *, int, 
33a80 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 2a  sqlite3_value **
33a90 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
33aa0 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 42 65 67  *);.  int (*xBeg
33ab0 69 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  in)(sqlite3_vtab
33ac0 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20   *pVTab);.  int 
33ad0 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33  (*xSync)(sqlite3
33ae0 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20  _vtab *pVTab);. 
33af0 20 69 6e 74 20 28 2a 78 43 6f 6d 6d 69 74 29 28   int (*xCommit)(
33b00 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56  sqlite3_vtab *pV
33b10 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52  Tab);.  int (*xR
33b20 6f 6c 6c 62 61 63 6b 29 28 73 71 6c 69 74 65 33  ollback)(sqlite3
33b30 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20  _vtab *pVTab);. 
33b40 20 69 6e 74 20 28 2a 78 46 69 6e 64 46 75 6e 63   int (*xFindFunc
33b50 74 69 6f 6e 29 28 73 71 6c 69 74 65 33 5f 76 74  tion)(sqlite3_vt
33b60 61 62 20 2a 70 56 74 61 62 2c 20 69 6e 74 20 6e  ab *pVtab, int n
33b70 41 72 67 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  Arg, const char 
33b80 2a 7a 4e 61 6d 65 2c 0a 20 20 20 20 20 20 20 20  *zName,.        
33b90 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76                 v
33ba0 6f 69 64 20 28 2a 2a 70 78 46 75 6e 63 29 28 73  oid (**pxFunc)(s
33bb0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
33bc0 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
33bd0 65 2a 2a 29 2c 0a 20 20 20 20 20 20 20 20 20 20  e**),.          
33be0 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69               voi
33bf0 64 20 2a 2a 70 70 41 72 67 29 3b 0a 0a 20 20 69  d **ppArg);..  i
33c00 6e 74 20 28 2a 78 52 65 6e 61 6d 65 29 28 73 71  nt (*xRename)(sq
33c10 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74 61  lite3_vtab *pVta
33c20 62 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  b, const char *z
33c30 4e 65 77 29 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  New);.};../*.** 
33c40 43 41 50 49 33 52 45 46 3a 20 56 69 72 74 75 61  CAPI3REF: Virtua
33c50 6c 20 54 61 62 6c 65 20 49 6e 64 65 78 69 6e 67  l Table Indexing
33c60 20 49 6e 66 6f 72 6d 61 74 69 6f 6e 20 7b 46 31   Information {F1
33c70 38 31 30 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  8100}.** KEYWORD
33c80 53 3a 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78  S: sqlite3_index
33c90 5f 69 6e 66 6f 0a 2a 2a 0a 2a 2a 20 54 68 65 20  _info.**.** The 
33ca0 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e  sqlite3_index_in
33cb0 66 6f 20 73 74 72 75 63 74 75 72 65 20 61 6e 64  fo structure and
33cc0 20 69 74 73 20 73 75 62 73 74 72 75 63 74 75 72   its substructur
33cd0 65 73 20 69 73 20 75 73 65 64 20 74 6f 0a 2a 2a  es is used to.**
33ce0 20 70 61 73 73 20 69 6e 66 6f 72 6d 61 74 69 6f   pass informatio
33cf0 6e 20 69 6e 74 6f 20 61 6e 64 20 72 65 63 65 69  n into and recei
33d00 76 65 20 74 68 65 20 72 65 70 6c 79 20 66 72 6f  ve the reply fro
33d10 6d 20 74 68 65 20 78 42 65 73 74 49 6e 64 65 78  m the xBestIndex
33d20 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e  .** method of an
33d30 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 2e   sqlite3_module.
33d40 20 20 54 68 65 20 66 69 65 6c 64 73 20 75 6e 64    The fields und
33d50 65 72 20 2a 2a 49 6e 70 75 74 73 2a 2a 20 61 72  er **Inputs** ar
33d60 65 20 74 68 65 0a 2a 2a 20 69 6e 70 75 74 73 20  e the.** inputs 
33d70 74 6f 20 78 42 65 73 74 49 6e 64 65 78 20 61 6e  to xBestIndex an
33d80 64 20 61 72 65 20 72 65 61 64 2d 6f 6e 6c 79 2e  d are read-only.
33d90 20 20 78 42 65 73 74 49 6e 64 65 78 20 69 6e 73    xBestIndex ins
33da0 65 72 74 73 20 69 74 73 0a 2a 2a 20 72 65 73 75  erts its.** resu
33db0 6c 74 73 20 69 6e 74 6f 20 74 68 65 20 2a 2a 4f  lts into the **O
33dc0 75 74 70 75 74 73 2a 2a 20 66 69 65 6c 64 73 2e  utputs** fields.
33dd0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 43 6f 6e 73  .**.** The aCons
33de0 74 72 61 69 6e 74 5b 5d 20 61 72 72 61 79 20 72  traint[] array r
33df0 65 63 6f 72 64 73 20 57 48 45 52 45 20 63 6c 61  ecords WHERE cla
33e00 75 73 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20  use constraints 
33e10 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 3a 0a  of the.** form:.
33e20 2a 2a 0a 2a 2a 20 20 20 20 20 20 20 20 20 63 6f  **.**         co
33e30 6c 75 6d 6e 20 4f 50 20 65 78 70 72 0a 2a 2a 0a  lumn OP expr.**.
33e40 2a 2a 20 57 68 65 72 65 20 4f 50 20 69 73 20 3d  ** Where OP is =
33e50 2c 20 26 6c 74 3b 2c 20 26 6c 74 3b 3d 2c 20 26  , &lt;, &lt;=, &
33e60 67 74 3b 2c 20 6f 72 20 26 67 74 3b 3d 2e 20 20  gt;, or &gt;=.  
33e70 0a 2a 2a 20 54 68 65 20 70 61 72 74 69 63 75 6c  .** The particul
33e80 61 72 20 6f 70 65 72 61 74 6f 72 20 69 73 20 73  ar operator is s
33e90 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 43 6f 6e  tored.** in aCon
33ea0 73 74 72 61 69 6e 74 5b 5d 2e 6f 70 2e 20 20 54  straint[].op.  T
33eb0 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20  he index of the 
33ec0 63 6f 6c 75 6d 6e 20 69 73 20 73 74 6f 72 65 64  column is stored
33ed0 20 69 6e 20 0a 2a 2a 20 61 43 6f 6e 73 74 72 61   in .** aConstra
33ee0 69 6e 74 5b 5d 2e 69 43 6f 6c 75 6d 6e 2e 20 20  int[].iColumn.  
33ef0 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 75 73  aConstraint[].us
33f00 61 62 6c 65 20 69 73 20 54 52 55 45 20 69 66 20  able is TRUE if 
33f10 74 68 65 0a 2a 2a 20 65 78 70 72 20 6f 6e 20 74  the.** expr on t
33f20 68 65 20 72 69 67 68 74 2d 68 61 6e 64 20 73 69  he right-hand si
33f30 64 65 20 63 61 6e 20 62 65 20 65 76 61 6c 75 61  de can be evalua
33f40 74 65 64 20 28 61 6e 64 20 74 68 75 73 20 74 68  ted (and thus th
33f50 65 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20  e constraint.** 
33f60 69 73 20 75 73 61 62 6c 65 29 20 61 6e 64 20 66  is usable) and f
33f70 61 6c 73 65 20 69 66 20 69 74 20 63 61 6e 6e 6f  alse if it canno
33f80 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 70 74  t..**.** The opt
33f90 69 6d 69 7a 65 72 20 61 75 74 6f 6d 61 74 69 63  imizer automatic
33fa0 61 6c 6c 79 20 69 6e 76 65 72 74 73 20 74 65 72  ally inverts ter
33fb0 6d 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22  ms of the form "
33fc0 65 78 70 72 20 4f 50 20 63 6f 6c 75 6d 6e 22 0a  expr OP column".
33fd0 2a 2a 20 61 6e 64 20 6d 61 6b 65 73 20 6f 74 68  ** and makes oth
33fe0 65 72 20 73 69 6d 70 6c 69 66 69 63 61 74 69 6f  er simplificatio
33ff0 6e 73 20 74 6f 20 74 68 65 20 57 48 45 52 45 20  ns to the WHERE 
34000 63 6c 61 75 73 65 20 69 6e 20 61 6e 20 61 74 74  clause in an att
34010 65 6d 70 74 20 74 6f 0a 2a 2a 20 67 65 74 20 61  empt to.** get a
34020 73 20 6d 61 6e 79 20 57 48 45 52 45 20 63 6c 61  s many WHERE cla
34030 75 73 65 20 74 65 72 6d 73 20 69 6e 74 6f 20 74  use terms into t
34040 68 65 20 66 6f 72 6d 20 73 68 6f 77 6e 20 61 62  he form shown ab
34050 6f 76 65 20 61 73 20 70 6f 73 73 69 62 6c 65 2e  ove as possible.
34060 0a 2a 2a 20 54 68 65 20 61 43 6f 6e 73 74 72 61  .** The aConstra
34070 69 6e 74 5b 5d 20 61 72 72 61 79 20 6f 6e 6c 79  int[] array only
34080 20 72 65 70 6f 72 74 73 20 57 48 45 52 45 20 63   reports WHERE c
34090 6c 61 75 73 65 20 74 65 72 6d 73 20 69 6e 20 74  lause terms in t
340a0 68 65 20 63 6f 72 72 65 63 74 0a 2a 2a 20 66 6f  he correct.** fo
340b0 72 6d 20 74 68 61 74 20 72 65 66 65 72 20 74 6f  rm that refer to
340c0 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20   the particular 
340d0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 62 65  virtual table be
340e0 69 6e 67 20 71 75 65 72 69 65 64 2e 0a 2a 2a 0a  ing queried..**.
340f0 2a 2a 20 49 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  ** Information a
34100 62 6f 75 74 20 74 68 65 20 4f 52 44 45 52 20 42  bout the ORDER B
34110 59 20 63 6c 61 75 73 65 20 69 73 20 73 74 6f 72  Y clause is stor
34120 65 64 20 69 6e 20 61 4f 72 64 65 72 42 79 5b 5d  ed in aOrderBy[]
34130 2e 0a 2a 2a 20 45 61 63 68 20 74 65 72 6d 20 6f  ..** Each term o
34140 66 20 61 4f 72 64 65 72 42 79 20 72 65 63 6f 72  f aOrderBy recor
34150 64 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  ds a column of t
34160 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75  he ORDER BY clau
34170 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 42  se..**.** The xB
34180 65 73 74 49 6e 64 65 78 20 6d 65 74 68 6f 64 20  estIndex method 
34190 6d 75 73 74 20 66 69 6c 6c 20 61 43 6f 6e 73 74  must fill aConst
341a0 72 61 69 6e 74 55 73 61 67 65 5b 5d 20 77 69 74  raintUsage[] wit
341b0 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a  h information.**
341c0 20 61 62 6f 75 74 20 77 68 61 74 20 70 61 72 61   about what para
341d0 6d 65 74 65 72 73 20 74 6f 20 70 61 73 73 20 74  meters to pass t
341e0 6f 20 78 46 69 6c 74 65 72 2e 20 20 49 66 20 61  o xFilter.  If a
341f0 72 67 76 49 6e 64 65 78 3e 30 20 74 68 65 6e 0a  rgvIndex>0 then.
34200 2a 2a 20 74 68 65 20 72 69 67 68 74 2d 68 61 6e  ** the right-han
34210 64 20 73 69 64 65 20 6f 66 20 74 68 65 20 63 6f  d side of the co
34220 72 72 65 73 70 6f 6e 64 69 6e 67 20 61 43 6f 6e  rresponding aCon
34230 73 74 72 61 69 6e 74 5b 5d 20 69 73 20 65 76 61  straint[] is eva
34240 6c 75 61 74 65 64 0a 2a 2a 20 61 6e 64 20 62 65  luated.** and be
34250 63 6f 6d 65 73 20 74 68 65 20 61 72 67 76 49 6e  comes the argvIn
34260 64 65 78 2d 74 68 20 65 6e 74 72 79 20 69 6e 20  dex-th entry in 
34270 61 72 67 76 2e 20 20 49 66 20 61 43 6f 6e 73 74  argv.  If aConst
34280 72 61 69 6e 74 55 73 61 67 65 5b 5d 2e 6f 6d 69  raintUsage[].omi
34290 74 0a 2a 2a 20 69 73 20 74 72 75 65 2c 20 74 68  t.** is true, th
342a0 65 6e 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e  en the constrain
342b0 74 20 69 73 20 61 73 73 75 6d 65 64 20 74 6f 20  t is assumed to 
342c0 62 65 20 66 75 6c 6c 79 20 68 61 6e 64 6c 65 64  be fully handled
342d0 20 62 79 20 74 68 65 0a 2a 2a 20 76 69 72 74 75   by the.** virtu
342e0 61 6c 20 74 61 62 6c 65 20 61 6e 64 20 69 73 20  al table and is 
342f0 6e 6f 74 20 63 68 65 63 6b 65 64 20 61 67 61 69  not checked agai
34300 6e 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a  n by SQLite..**.
34310 2a 2a 20 54 68 65 20 69 64 78 4e 75 6d 20 61 6e  ** The idxNum an
34320 64 20 69 64 78 50 74 72 20 76 61 6c 75 65 73 20  d idxPtr values 
34330 61 72 65 20 72 65 63 6f 72 64 65 64 20 61 6e 64  are recorded and
34340 20 70 61 73 73 65 64 20 69 6e 74 6f 20 78 46 69   passed into xFi
34350 6c 74 65 72 2e 0a 2a 2a 20 73 71 6c 69 74 65 33  lter..** sqlite3
34360 5f 66 72 65 65 28 29 20 69 73 20 75 73 65 64 20  _free() is used 
34370 74 6f 20 66 72 65 65 20 69 64 78 50 74 72 20 69  to free idxPtr i
34380 66 20 6e 65 65 64 54 6f 46 72 65 65 49 64 78 50  f needToFreeIdxP
34390 74 72 20 69 73 20 74 72 75 65 2e 0a 2a 2a 0a 2a  tr is true..**.*
343a0 2a 20 54 68 65 20 6f 72 64 65 72 42 79 43 6f 6e  * The orderByCon
343b0 73 75 6d 65 64 20 6d 65 61 6e 73 20 74 68 61 74  sumed means that
343c0 20 6f 75 74 70 75 74 20 66 72 6f 6d 20 78 46 69   output from xFi
343d0 6c 74 65 72 20 77 69 6c 6c 20 6f 63 63 75 72 20  lter will occur 
343e0 69 6e 0a 2a 2a 20 74 68 65 20 63 6f 72 72 65 63  in.** the correc
343f0 74 20 6f 72 64 65 72 20 74 6f 20 73 61 74 69 73  t order to satis
34400 66 79 20 74 68 65 20 4f 52 44 45 52 20 42 59 20  fy the ORDER BY 
34410 63 6c 61 75 73 65 20 73 6f 20 74 68 61 74 20 6e  clause so that n
34420 6f 20 73 65 70 61 72 61 74 65 0a 2a 2a 20 73 6f  o separate.** so
34430 72 74 69 6e 67 20 73 74 65 70 20 69 73 20 72 65  rting step is re
34440 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  quired..**.** Th
34450 65 20 65 73 74 69 6d 61 74 65 64 43 6f 73 74 20  e estimatedCost 
34460 76 61 6c 75 65 20 69 73 20 61 6e 20 65 73 74 69  value is an esti
34470 6d 61 74 65 20 6f 66 20 74 68 65 20 63 6f 73 74  mate of the cost
34480 20 6f 66 20 64 6f 69 6e 67 20 74 68 65 0a 2a 2a   of doing the.**
34490 20 70 61 72 74 69 63 75 6c 61 72 20 6c 6f 6f 6b   particular look
344a0 75 70 2e 20 20 41 20 66 75 6c 6c 20 73 63 61 6e  up.  A full scan
344b0 20 6f 66 20 61 20 74 61 62 6c 65 20 77 69 74 68   of a table with
344c0 20 4e 20 65 6e 74 72 69 65 73 20 73 68 6f 75 6c   N entries shoul
344d0 64 20 68 61 76 65 0a 2a 2a 20 61 20 63 6f 73 74  d have.** a cost
344e0 20 6f 66 20 4e 2e 20 20 41 20 62 69 6e 61 72 79   of N.  A binary
344f0 20 73 65 61 72 63 68 20 6f 66 20 61 20 74 61 62   search of a tab
34500 6c 65 20 6f 66 20 4e 20 65 6e 74 72 69 65 73 20  le of N entries 
34510 73 68 6f 75 6c 64 20 68 61 76 65 20 61 0a 2a 2a  should have a.**
34520 20 63 6f 73 74 20 6f 66 20 61 70 70 72 6f 78 69   cost of approxi
34530 6d 61 74 65 6c 79 20 6c 6f 67 28 4e 29 2e 0a 2a  mately log(N)..*
34540 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  /.struct sqlite3
34550 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 7b 0a 20 20  _index_info {.  
34560 2f 2a 20 49 6e 70 75 74 73 20 2a 2f 0a 20 20 69  /* Inputs */.  i
34570 6e 74 20 6e 43 6f 6e 73 74 72 61 69 6e 74 3b 20  nt nConstraint; 
34580 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d            /* Num
34590 62 65 72 20 6f 66 20 65 6e 74 72 69 65 73 20 69  ber of entries i
345a0 6e 20 61 43 6f 6e 73 74 72 61 69 6e 74 20 2a 2f  n aConstraint */
345b0 0a 20 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  .  struct sqlite
345c0 33 5f 69 6e 64 65 78 5f 63 6f 6e 73 74 72 61 69  3_index_constrai
345d0 6e 74 20 7b 0a 20 20 20 20 20 69 6e 74 20 69 43  nt {.     int iC
345e0 6f 6c 75 6d 6e 3b 20 20 20 20 20 20 20 20 20 20  olumn;          
345f0 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6f 6e      /* Column on
34600 20 6c 65 66 74 2d 68 61 6e 64 20 73 69 64 65 20   left-hand side 
34610 6f 66 20 63 6f 6e 73 74 72 61 69 6e 74 20 2a 2f  of constraint */
34620 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63  .     unsigned c
34630 68 61 72 20 6f 70 3b 20 20 20 20 20 20 20 20 20  har op;         
34640 2f 2a 20 43 6f 6e 73 74 72 61 69 6e 74 20 6f 70  /* Constraint op
34650 65 72 61 74 6f 72 20 2a 2f 0a 20 20 20 20 20 75  erator */.     u
34660 6e 73 69 67 6e 65 64 20 63 68 61 72 20 75 73 61  nsigned char usa
34670 62 6c 65 3b 20 20 20 20 20 2f 2a 20 54 72 75 65  ble;     /* True
34680 20 69 66 20 74 68 69 73 20 63 6f 6e 73 74 72 61   if this constra
34690 69 6e 74 20 69 73 20 75 73 61 62 6c 65 20 2a 2f  int is usable */
346a0 0a 20 20 20 20 20 69 6e 74 20 69 54 65 72 6d 4f  .     int iTermO
346b0 66 66 73 65 74 3b 20 20 20 20 20 20 20 20 20 20  ffset;          
346c0 2f 2a 20 55 73 65 64 20 69 6e 74 65 72 6e 61 6c  /* Used internal
346d0 6c 79 20 2d 20 78 42 65 73 74 49 6e 64 65 78 20  ly - xBestIndex 
346e0 73 68 6f 75 6c 64 20 69 67 6e 6f 72 65 20 2a 2f  should ignore */
346f0 0a 20 20 7d 20 2a 61 43 6f 6e 73 74 72 61 69 6e  .  } *aConstrain
34700 74 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  t;            /*
34710 20 54 61 62 6c 65 20 6f 66 20 57 48 45 52 45 20   Table of WHERE 
34720 63 6c 61 75 73 65 20 63 6f 6e 73 74 72 61 69 6e  clause constrain
34730 74 73 20 2a 2f 0a 20 20 69 6e 74 20 6e 4f 72 64  ts */.  int nOrd
34740 65 72 42 79 3b 20 20 20 20 20 20 20 20 20 20 20  erBy;           
34750 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20     /* Number of 
34760 74 65 72 6d 73 20 69 6e 20 74 68 65 20 4f 52 44  terms in the ORD
34770 45 52 20 42 59 20 63 6c 61 75 73 65 20 2a 2f 0a  ER BY clause */.
34780 20 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33    struct sqlite3
34790 5f 69 6e 64 65 78 5f 6f 72 64 65 72 62 79 20 7b  _index_orderby {
347a0 0a 20 20 20 20 20 69 6e 74 20 69 43 6f 6c 75 6d  .     int iColum
347b0 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  n;              
347c0 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72  /* Column number
347d0 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e 65   */.     unsigne
347e0 64 20 63 68 61 72 20 64 65 73 63 3b 20 20 20 20  d char desc;    
347f0 20 20 20 2f 2a 20 54 72 75 65 20 66 6f 72 20 44     /* True for D
34800 45 53 43 2e 20 20 46 61 6c 73 65 20 66 6f 72 20  ESC.  False for 
34810 41 53 43 2e 20 2a 2f 0a 20 20 7d 20 2a 61 4f 72  ASC. */.  } *aOr
34820 64 65 72 42 79 3b 20 20 20 20 20 20 20 20 20 20  derBy;          
34830 20 20 20 20 20 2f 2a 20 54 68 65 20 4f 52 44 45       /* The ORDE
34840 52 20 42 59 20 63 6c 61 75 73 65 20 2a 2f 0a 0a  R BY clause */..
34850 20 20 2f 2a 20 4f 75 74 70 75 74 73 20 2a 2f 0a    /* Outputs */.
34860 20 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33    struct sqlite3
34870 5f 69 6e 64 65 78 5f 63 6f 6e 73 74 72 61 69 6e  _index_constrain
34880 74 5f 75 73 61 67 65 20 7b 0a 20 20 20 20 69 6e  t_usage {.    in
34890 74 20 61 72 67 76 49 6e 64 65 78 3b 20 20 20 20  t argvIndex;    
348a0 20 20 20 20 20 20 20 2f 2a 20 69 66 20 3e 30 2c         /* if >0,
348b0 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 70   constraint is p
348c0 61 72 74 20 6f 66 20 61 72 67 76 20 74 6f 20 78  art of argv to x
348d0 46 69 6c 74 65 72 20 2a 2f 0a 20 20 20 20 75 6e  Filter */.    un
348e0 73 69 67 6e 65 64 20 63 68 61 72 20 6f 6d 69 74  signed char omit
348f0 3b 20 20 20 20 20 20 2f 2a 20 44 6f 20 6e 6f 74  ;      /* Do not
34900 20 63 6f 64 65 20 61 20 74 65 73 74 20 66 6f 72   code a test for
34910 20 74 68 69 73 20 63 6f 6e 73 74 72 61 69 6e 74   this constraint
34920 20 2a 2f 0a 20 20 7d 20 2a 61 43 6f 6e 73 74 72   */.  } *aConstr
34930 61 69 6e 74 55 73 61 67 65 3b 0a 20 20 69 6e 74  aintUsage;.  int
34940 20 69 64 78 4e 75 6d 3b 20 20 20 20 20 20 20 20   idxNum;        
34950 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65          /* Numbe
34960 72 20 75 73 65 64 20 74 6f 20 69 64 65 6e 74 69  r used to identi
34970 66 79 20 74 68 65 20 69 6e 64 65 78 20 2a 2f 0a  fy the index */.
34980 20 20 63 68 61 72 20 2a 69 64 78 53 74 72 3b 20    char *idxStr; 
34990 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
349a0 53 74 72 69 6e 67 2c 20 70 6f 73 73 69 62 6c 79  String, possibly
349b0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73   obtained from s
349c0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 20 2a 2f  qlite3_malloc */
349d0 0a 20 20 69 6e 74 20 6e 65 65 64 54 6f 46 72 65  .  int needToFre
349e0 65 49 64 78 53 74 72 3b 20 20 20 20 20 20 2f 2a  eIdxStr;      /*
349f0 20 46 72 65 65 20 69 64 78 53 74 72 20 75 73 69   Free idxStr usi
34a00 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  ng sqlite3_free(
34a10 29 20 69 66 20 74 72 75 65 20 2a 2f 0a 20 20 69  ) if true */.  i
34a20 6e 74 20 6f 72 64 65 72 42 79 43 6f 6e 73 75 6d  nt orderByConsum
34a30 65 64 3b 20 20 20 20 20 20 20 2f 2a 20 54 72 75  ed;       /* Tru
34a40 65 20 69 66 20 6f 75 74 70 75 74 20 69 73 20 61  e if output is a
34a50 6c 72 65 61 64 79 20 6f 72 64 65 72 65 64 20 2a  lready ordered *
34a60 2f 0a 20 20 64 6f 75 62 6c 65 20 65 73 74 69 6d  /.  double estim
34a70 61 74 65 64 43 6f 73 74 3b 20 20 20 20 20 20 2f  atedCost;      /
34a80 2a 20 45 73 74 69 6d 61 74 65 64 20 63 6f 73 74  * Estimated cost
34a90 20 6f 66 20 75 73 69 6e 67 20 74 68 69 73 20 69   of using this i
34aa0 6e 64 65 78 20 2a 2f 0a 7d 3b 0a 23 64 65 66 69  ndex */.};.#defi
34ab0 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f  ne SQLITE_INDEX_
34ac0 43 4f 4e 53 54 52 41 49 4e 54 5f 45 51 20 20 20  CONSTRAINT_EQ   
34ad0 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
34ae0 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49  E_INDEX_CONSTRAI
34af0 4e 54 5f 47 54 20 20 20 20 34 0a 23 64 65 66 69  NT_GT    4.#defi
34b00 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f  ne SQLITE_INDEX_
34b10 43 4f 4e 53 54 52 41 49 4e 54 5f 4c 45 20 20 20  CONSTRAINT_LE   
34b20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   8.#define SQLIT
34b30 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49  E_INDEX_CONSTRAI
34b40 4e 54 5f 4c 54 20 20 20 20 31 36 0a 23 64 65 66  NT_LT    16.#def
34b50 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58  ine SQLITE_INDEX
34b60 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 47 45 20 20  _CONSTRAINT_GE  
34b70 20 20 33 32 0a 23 64 65 66 69 6e 65 20 53 51 4c    32.#define SQL
34b80 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52  ITE_INDEX_CONSTR
34b90 41 49 4e 54 5f 4d 41 54 43 48 20 36 34 0a 0a 2f  AINT_MATCH 64../
34ba0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
34bb0 65 67 69 73 74 65 72 20 41 20 56 69 72 74 75 61  egister A Virtua
34bc0 6c 20 54 61 62 6c 65 20 49 6d 70 6c 65 6d 65 6e  l Table Implemen
34bd0 74 61 74 69 6f 6e 20 7b 46 31 38 32 30 30 7d 0a  tation {F18200}.
34be0 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
34bf0 6e 65 20 69 73 20 75 73 65 64 20 74 6f 20 72 65  ne is used to re
34c00 67 69 73 74 65 72 20 61 20 6e 65 77 20 6d 6f 64  gister a new mod
34c10 75 6c 65 20 6e 61 6d 65 20 77 69 74 68 20 61 6e  ule name with an
34c20 20 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 6e 6e 65   SQLite.** conne
34c30 63 74 69 6f 6e 2e 20 20 4d 6f 64 75 6c 65 20 6e  ction.  Module n
34c40 61 6d 65 73 20 6d 75 73 74 20 62 65 20 72 65 67  ames must be reg
34c50 69 73 74 65 72 65 64 20 62 65 66 6f 72 65 20 63  istered before c
34c60 72 65 61 74 69 6e 67 20 6e 65 77 0a 2a 2a 20 76  reating new.** v
34c70 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 6f 6e  irtual tables on
34c80 20 74 68 65 20 6d 6f 64 75 6c 65 2c 20 6f 72 20   the module, or 
34c90 62 65 66 6f 72 65 20 75 73 69 6e 67 20 70 72 65  before using pre
34ca0 65 78 69 73 74 69 6e 67 20 76 69 72 74 75 61 6c  existing virtual
34cb0 0a 2a 2a 20 74 61 62 6c 65 73 20 6f 66 20 74 68  .** tables of th
34cc0 65 20 6d 6f 64 75 6c 65 2e 0a 2a 2f 0a 69 6e 74  e module..*/.int
34cd0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
34ce0 6d 6f 64 75 6c 65 28 0a 20 20 73 71 6c 69 74 65  module(.  sqlite
34cf0 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
34d00 20 20 20 20 20 2f 2a 20 53 51 4c 69 74 65 20 63       /* SQLite c
34d10 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 72 65 67  onnection to reg
34d20 69 73 74 65 72 20 6d 6f 64 75 6c 65 20 77 69 74  ister module wit
34d30 68 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  h */.  const cha
34d40 72 20 2a 7a 4e 61 6d 65 2c 20 20 20 20 20 20 20  r *zName,       
34d50 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65    /* Name of the
34d60 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 63 6f 6e   module */.  con
34d70 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c  st sqlite3_modul
34d80 65 20 2a 2c 20 20 20 20 2f 2a 20 4d 65 74 68 6f  e *,    /* Metho
34d90 64 73 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c  ds for the modul
34da0 65 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 20 20 20  e */.  void *   
34db0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
34dc0 20 20 2f 2a 20 43 6c 69 65 6e 74 20 64 61 74 61    /* Client data
34dd0 20 66 6f 72 20 78 43 72 65 61 74 65 2f 78 43 6f   for xCreate/xCo
34de0 6e 6e 65 63 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a  nnect */.);../*.
34df0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 67  ** CAPI3REF: Reg
34e00 69 73 74 65 72 20 41 20 56 69 72 74 75 61 6c 20  ister A Virtual 
34e10 54 61 62 6c 65 20 49 6d 70 6c 65 6d 65 6e 74 61  Table Implementa
34e20 74 69 6f 6e 20 7b 46 31 38 32 31 30 7d 0a 2a 2a  tion {F18210}.**
34e30 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
34e40 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f   is identical to
34e50 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65   the sqlite3_cre
34e60 61 74 65 5f 6d 6f 64 75 6c 65 28 29 20 6d 65 74  ate_module() met
34e70 68 6f 64 20 61 62 6f 76 65 2c 0a 2a 2a 20 65 78  hod above,.** ex
34e80 63 65 70 74 20 74 68 61 74 20 69 74 20 61 6c 6c  cept that it all
34e90 6f 77 73 20 61 20 64 65 73 74 72 75 63 74 6f 72  ows a destructor
34ea0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
34eb0 73 70 65 63 69 66 69 65 64 2e 20 49 74 20 69 73  specified. It is
34ec0 0a 2a 2a 20 65 76 65 6e 20 6d 6f 72 65 20 65 78  .** even more ex
34ed0 70 65 72 69 6d 65 6e 74 61 6c 20 74 68 61 6e 20  perimental than 
34ee0 74 68 65 20 72 65 73 74 20 6f 66 20 74 68 65 20  the rest of the 
34ef0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 41  virtual tables A
34f00 50 49 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  PI..*/.int sqlit
34f10 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65  e3_create_module
34f20 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v2(.  sqlite3 *
34f30 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  db,             
34f40 20 20 2f 2a 20 53 51 4c 69 74 65 20 63 6f 6e 6e    /* SQLite conn
34f50 65 63 74 69 6f 6e 20 74 6f 20 72 65 67 69 73 74  ection to regist
34f60 65 72 20 6d 6f 64 75 6c 65 20 77 69 74 68 20 2a  er module with *
34f70 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
34f80 7a 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 20 2f  zName,         /
34f90 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 6d 6f  * Name of the mo
34fa0 64 75 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  dule */.  const 
34fb0 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 2a  sqlite3_module *
34fc0 2c 20 20 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20  ,    /* Methods 
34fd0 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a  for the module *
34fe0 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20  /.  void *,     
34ff0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
35000 2a 20 43 6c 69 65 6e 74 20 64 61 74 61 20 66 6f  * Client data fo
35010 72 20 78 43 72 65 61 74 65 2f 78 43 6f 6e 6e 65  r xCreate/xConne
35020 63 74 20 2a 2f 0a 20 20 76 6f 69 64 28 2a 78 44  ct */.  void(*xD
35030 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 20 20  estroy)(void*)  
35040 20 20 20 2f 2a 20 4d 6f 64 75 6c 65 20 64 65 73     /* Module des
35050 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e  tructor function
35060 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.);../*.** CA
35070 50 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20  PI3REF: Virtual 
35080 54 61 62 6c 65 20 49 6e 73 74 61 6e 63 65 20 4f  Table Instance O
35090 62 6a 65 63 74 20 7b 46 31 38 30 31 30 7d 0a 2a  bject {F18010}.*
350a0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69  * KEYWORDS: sqli
350b0 74 65 33 5f 76 74 61 62 0a 2a 2a 0a 2a 2a 20 45  te3_vtab.**.** E
350c0 76 65 72 79 20 6d 6f 64 75 6c 65 20 69 6d 70 6c  very module impl
350d0 65 6d 65 6e 74 61 74 69 6f 6e 20 75 73 65 73 20  ementation uses 
350e0 61 20 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68  a subclass of th
350f0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 72 75  e following stru
35100 63 74 75 72 65 0a 2a 2a 20 74 6f 20 64 65 73 63  cture.** to desc
35110 72 69 62 65 20 61 20 70 61 72 74 69 63 75 6c 61  ribe a particula
35120 72 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  r instance of th
35130 65 20 6d 6f 64 75 6c 65 2e 20 20 45 61 63 68 20  e module.  Each 
35140 73 75 62 63 6c 61 73 73 20 77 69 6c 6c 0a 2a 2a  subclass will.**
35150 20 62 65 20 74 61 69 6c 6f 72 65 64 20 74 6f 20   be tailored to 
35160 74 68 65 20 73 70 65 63 69 66 69 63 20 6e 65 65  the specific nee
35170 64 73 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65  ds of the module
35180 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e   implementation.
35190 20 20 20 54 68 65 0a 2a 2a 20 70 75 72 70 6f 73     The.** purpos
351a0 65 20 6f 66 20 74 68 69 73 20 73 75 70 65 72 63  e of this superc
351b0 6c 61 73 73 20 69 73 20 74 6f 20 64 65 66 69 6e  lass is to defin
351c0 65 20 63 65 72 74 61 69 6e 20 66 69 65 6c 64 73  e certain fields
351d0 20 74 68 61 74 20 61 72 65 20 63 6f 6d 6d 6f 6e   that are common
351e0 0a 2a 2a 20 74 6f 20 61 6c 6c 20 6d 6f 64 75 6c  .** to all modul
351f0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
35200 73 2e 0a 2a 2a 0a 2a 2a 20 56 69 72 74 75 61 6c  s..**.** Virtual
35210 20 74 61 62 6c 65 73 20 6d 65 74 68 6f 64 73 20   tables methods 
35220 63 61 6e 20 73 65 74 20 61 6e 20 65 72 72 6f 72  can set an error
35230 20 6d 65 73 73 61 67 65 20 62 79 20 61 73 73 69   message by assi
35240 67 6e 69 6e 67 20 61 0a 2a 2a 20 73 74 72 69 6e  gning a.** strin
35250 67 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  g obtained from 
35260 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
35270 29 20 74 6f 20 7a 45 72 72 4d 73 67 2e 20 20 54  ) to zErrMsg.  T
35280 68 65 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64  he method should
35290 0a 2a 2a 20 74 61 6b 65 20 63 61 72 65 20 74 68  .** take care th
352a0 61 74 20 61 6e 79 20 70 72 69 6f 72 20 73 74 72  at any prior str
352b0 69 6e 67 20 69 73 20 66 72 65 65 64 20 62 79 20  ing is freed by 
352c0 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  a call to sqlite
352d0 33 5f 66 72 65 65 28 29 0a 2a 2a 20 70 72 69 6f  3_free().** prio
352e0 72 20 74 6f 20 61 73 73 69 67 6e 69 6e 67 20 61  r to assigning a
352f0 20 6e 65 77 20 73 74 72 69 6e 67 20 74 6f 20 7a   new string to z
35300 45 72 72 4d 73 67 2e 20 20 41 66 74 65 72 20 74  ErrMsg.  After t
35310 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
35320 0a 2a 2a 20 69 73 20 64 65 6c 69 76 65 72 65 64  .** is delivered
35330 20 75 70 20 74 6f 20 74 68 65 20 63 6c 69 65 6e   up to the clien
35340 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74  t application, t
35350 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62  he string will b
35360 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a  e automatically.
35370 2a 2a 20 66 72 65 65 64 20 62 79 20 73 71 6c 69  ** freed by sqli
35380 74 65 33 5f 66 72 65 65 28 29 20 61 6e 64 20 74  te3_free() and t
35390 68 65 20 7a 45 72 72 4d 73 67 20 66 69 65 6c 64  he zErrMsg field
353a0 20 77 69 6c 6c 20 62 65 20 7a 65 72 6f 65 64 2e   will be zeroed.
353b0 20 20 4e 6f 74 65 0a 2a 2a 20 74 68 61 74 20 73    Note.** that s
353c0 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29  qlite3_mprintf()
353d0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 66 72 65   and sqlite3_fre
353e0 65 28 29 20 61 72 65 20 75 73 65 64 20 6f 6e 20  e() are used on 
353f0 74 68 65 20 7a 45 72 72 4d 73 67 20 66 69 65 6c  the zErrMsg fiel
35400 64 0a 2a 2a 20 73 69 6e 63 65 20 76 69 72 74 75  d.** since virtu
35410 61 6c 20 74 61 62 6c 65 73 20 61 72 65 20 63 6f  al tables are co
35420 6d 6d 6f 6e 6c 79 20 69 6d 70 6c 65 6d 65 6e 74  mmonly implement
35430 65 64 20 69 6e 20 6c 6f 61 64 61 62 6c 65 20 65  ed in loadable e
35440 78 74 65 6e 73 69 6f 6e 73 20 77 68 69 63 68 0a  xtensions which.
35450 2a 2a 20 64 6f 20 6e 6f 74 20 68 61 76 65 20 61  ** do not have a
35460 63 63 65 73 73 20 74 6f 20 73 71 6c 69 74 65 33  ccess to sqlite3
35470 4d 50 72 69 6e 74 66 28 29 20 6f 72 20 73 71 6c  MPrintf() or sql
35480 69 74 65 33 46 72 65 65 28 29 2e 0a 2a 2f 0a 73  ite3Free()..*/.s
35490 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 74  truct sqlite3_vt
354a0 61 62 20 7b 0a 20 20 63 6f 6e 73 74 20 73 71 6c  ab {.  const sql
354b0 69 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 70 4d 6f  ite3_module *pMo
354c0 64 75 6c 65 3b 20 20 2f 2a 20 54 68 65 20 6d 6f  dule;  /* The mo
354d0 64 75 6c 65 20 66 6f 72 20 74 68 69 73 20 76 69  dule for this vi
354e0 72 74 75 61 6c 20 74 61 62 6c 65 20 2a 2f 0a 20  rtual table */. 
354f0 20 69 6e 74 20 6e 52 65 66 3b 20 20 20 20 20 20   int nRef;      
35500 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
35510 20 2f 2a 20 55 73 65 64 20 69 6e 74 65 72 6e 61   /* Used interna
35520 6c 6c 79 20 2a 2f 0a 20 20 63 68 61 72 20 2a 7a  lly */.  char *z
35530 45 72 72 4d 73 67 3b 20 20 20 20 20 20 20 20 20  ErrMsg;         
35540 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f           /* Erro
35550 72 20 6d 65 73 73 61 67 65 20 66 72 6f 6d 20 73  r message from s
35560 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29  qlite3_mprintf()
35570 20 2a 2f 0a 20 20 2f 2a 20 56 69 72 74 75 61 6c   */.  /* Virtual
35580 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74   table implement
35590 61 74 69 6f 6e 73 20 77 69 6c 6c 20 74 79 70 69  ations will typi
355a0 63 61 6c 6c 79 20 61 64 64 20 61 64 64 69 74 69  cally add additi
355b0 6f 6e 61 6c 20 66 69 65 6c 64 73 20 2a 2f 0a 7d  onal fields */.}
355c0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
355d0 46 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65  F: Virtual Table
355e0 20 43 75 72 73 6f 72 20 4f 62 6a 65 63 74 20 20   Cursor Object  
355f0 7b 46 31 38 30 32 30 7d 0a 2a 2a 20 4b 45 59 57  {F18020}.** KEYW
35600 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76 74  ORDS: sqlite3_vt
35610 61 62 5f 63 75 72 73 6f 72 0a 2a 2a 0a 2a 2a 20  ab_cursor.**.** 
35620 45 76 65 72 79 20 6d 6f 64 75 6c 65 20 69 6d 70  Every module imp
35630 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 75 73 65 73  lementation uses
35640 20 61 20 73 75 62 63 6c 61 73 73 20 6f 66 20 74   a subclass of t
35650 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 72  he following str
35660 75 63 74 75 72 65 0a 2a 2a 20 74 6f 20 64 65 73  ucture.** to des
35670 63 72 69 62 65 20 63 75 72 73 6f 72 73 20 74 68  cribe cursors th
35680 61 74 20 70 6f 69 6e 74 20 69 6e 74 6f 20 74 68  at point into th
35690 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  e virtual table 
356a0 61 6e 64 20 61 72 65 20 75 73 65 64 0a 2a 2a 20  and are used.** 
356b0 74 6f 20 6c 6f 6f 70 20 74 68 72 6f 75 67 68 20  to loop through 
356c0 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c  the virtual tabl
356d0 65 2e 20 20 43 75 72 73 6f 72 73 20 61 72 65 20  e.  Cursors are 
356e0 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 74 68  created using th
356f0 65 0a 2a 2a 20 78 4f 70 65 6e 20 6d 65 74 68 6f  e.** xOpen metho
35700 64 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 2e  d of the module.
35710 20 20 45 61 63 68 20 6d 6f 64 75 6c 65 20 69 6d    Each module im
35720 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c  plementation wil
35730 6c 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20  l define.** the 
35740 63 6f 6e 74 65 6e 74 20 6f 66 20 61 20 63 75 72  content of a cur
35750 73 6f 72 20 73 74 72 75 63 74 75 72 65 20 74 6f  sor structure to
35760 20 73 75 69 74 20 69 74 73 20 6f 77 6e 20 6e 65   suit its own ne
35770 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  eds..**.** This 
35780 73 75 70 65 72 63 6c 61 73 73 20 65 78 69 73 74  superclass exist
35790 73 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 64 65  s in order to de
357a0 66 69 6e 65 20 66 69 65 6c 64 73 20 6f 66 20 74  fine fields of t
357b0 68 65 20 63 75 72 73 6f 72 20 74 68 61 74 0a 2a  he cursor that.*
357c0 2a 20 61 72 65 20 63 6f 6d 6d 6f 6e 20 74 6f 20  * are common to 
357d0 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  all implementati
357e0 6f 6e 73 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73  ons..*/.struct s
357f0 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
35800 6f 72 20 7b 0a 20 20 73 71 6c 69 74 65 33 5f 76  or {.  sqlite3_v
35810 74 61 62 20 2a 70 56 74 61 62 3b 20 20 20 20 20  tab *pVtab;     
35820 20 2f 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c   /* Virtual tabl
35830 65 20 6f 66 20 74 68 69 73 20 63 75 72 73 6f 72  e of this cursor
35840 20 2a 2f 0a 20 20 2f 2a 20 56 69 72 74 75 61 6c   */.  /* Virtual
35850 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74   table implement
35860 61 74 69 6f 6e 73 20 77 69 6c 6c 20 74 79 70 69  ations will typi
35870 63 61 6c 6c 79 20 61 64 64 20 61 64 64 69 74 69  cally add additi
35880 6f 6e 61 6c 20 66 69 65 6c 64 73 20 2a 2f 0a 7d  onal fields */.}
35890 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
358a0 46 3a 20 44 65 63 6c 61 72 65 20 54 68 65 20 53  F: Declare The S
358b0 63 68 65 6d 61 20 4f 66 20 41 20 56 69 72 74 75  chema Of A Virtu
358c0 61 6c 20 54 61 62 6c 65 20 7b 46 31 38 32 38 30  al Table {F18280
358d0 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 43 72 65  }.**.** The xCre
358e0 61 74 65 20 61 6e 64 20 78 43 6f 6e 6e 65 63 74  ate and xConnect
358f0 20 6d 65 74 68 6f 64 73 20 6f 66 20 61 20 6d 6f   methods of a mo
35900 64 75 6c 65 20 75 73 65 20 74 68 65 20 66 6f 6c  dule use the fol
35910 6c 6f 77 69 6e 67 20 41 50 49 0a 2a 2a 20 74 6f  lowing API.** to
35920 20 64 65 63 6c 61 72 65 20 74 68 65 20 66 6f 72   declare the for
35930 6d 61 74 20 28 74 68 65 20 6e 61 6d 65 73 20 61  mat (the names a
35940 6e 64 20 64 61 74 61 74 79 70 65 73 20 6f 66 20  nd datatypes of 
35950 74 68 65 20 63 6f 6c 75 6d 6e 73 29 20 6f 66 0a  the columns) of.
35960 2a 2a 20 74 68 65 20 76 69 72 74 75 61 6c 20 74  ** the virtual t
35970 61 62 6c 65 73 20 74 68 65 79 20 69 6d 70 6c 65  ables they imple
35980 6d 65 6e 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ment..*/.int sql
35990 69 74 65 33 5f 64 65 63 6c 61 72 65 5f 76 74 61  ite3_declare_vta
359a0 62 28 73 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73  b(sqlite3*, cons
359b0 74 20 63 68 61 72 20 2a 7a 43 72 65 61 74 65 54  t char *zCreateT
359c0 61 62 6c 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  able);../*.** CA
359d0 50 49 33 52 45 46 3a 20 4f 76 65 72 6c 6f 61 64  PI3REF: Overload
359e0 20 41 20 46 75 6e 63 74 69 6f 6e 20 46 6f 72 20   A Function For 
359f0 41 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20  A Virtual Table 
35a00 7b 46 31 38 33 30 30 7d 0a 2a 2a 0a 2a 2a 20 56  {F18300}.**.** V
35a10 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 63 61  irtual tables ca
35a20 6e 20 70 72 6f 76 69 64 65 20 61 6c 74 65 72 6e  n provide altern
35a30 61 74 69 76 65 20 69 6d 70 6c 65 6d 65 6e 74 61  ative implementa
35a40 74 69 6f 6e 73 20 6f 66 20 66 75 6e 63 74 69 6f  tions of functio
35a50 6e 73 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 20  ns.** using the 
35a60 78 46 69 6e 64 46 75 6e 63 74 69 6f 6e 20 6d 65  xFindFunction me
35a70 74 68 6f 64 2e 20 20 42 75 74 20 67 6c 6f 62 61  thod.  But globa
35a80 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 74 68  l versions of th
35a90 6f 73 65 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a  ose functions.**
35aa0 20 6d 75 73 74 20 65 78 69 73 74 20 69 6e 20 6f   must exist in o
35ab0 72 64 65 72 20 74 6f 20 62 65 20 6f 76 65 72 6c  rder to be overl
35ac0 6f 61 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  oaded..**.** Thi
35ad0 73 20 41 50 49 20 6d 61 6b 65 73 20 73 75 72 65  s API makes sure
35ae0 20 61 20 67 6c 6f 62 61 6c 20 76 65 72 73 69 6f   a global versio
35af0 6e 20 6f 66 20 61 20 66 75 6e 63 74 69 6f 6e 20  n of a function 
35b00 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61  with a particula
35b10 72 0a 2a 2a 20 6e 61 6d 65 20 61 6e 64 20 6e 75  r.** name and nu
35b20 6d 62 65 72 20 6f 66 20 70 61 72 61 6d 65 74 65  mber of paramete
35b30 72 73 20 65 78 69 73 74 73 2e 20 20 49 66 20 6e  rs exists.  If n
35b40 6f 20 73 75 63 68 20 66 75 6e 63 74 69 6f 6e 20  o such function 
35b50 65 78 69 73 74 73 0a 2a 2a 20 62 65 66 6f 72 65  exists.** before
35b60 20 74 68 69 73 20 41 50 49 20 69 73 20 63 61 6c   this API is cal
35b70 6c 65 64 2c 20 61 20 6e 65 77 20 66 75 6e 63 74  led, a new funct
35b80 69 6f 6e 20 69 73 20 63 72 65 61 74 65 64 2e 20  ion is created. 
35b90 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   The implementat
35ba0 69 6f 6e 0a 2a 2a 20 6f 66 20 74 68 65 20 6e 65  ion.** of the ne
35bb0 77 20 66 75 6e 63 74 69 6f 6e 20 61 6c 77 61 79  w function alway
35bc0 73 20 63 61 75 73 65 73 20 61 6e 20 65 78 63 65  s causes an exce
35bd0 70 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 72 6f  ption to be thro
35be0 77 6e 2e 20 20 53 6f 0a 2a 2a 20 74 68 65 20 6e  wn.  So.** the n
35bf0 65 77 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 6e  ew function is n
35c00 6f 74 20 67 6f 6f 64 20 66 6f 72 20 61 6e 79 74  ot good for anyt
35c10 68 69 6e 67 20 62 79 20 69 74 73 65 6c 66 2e 20  hing by itself. 
35c20 20 49 74 73 20 6f 6e 6c 79 0a 2a 2a 20 70 75 72   Its only.** pur
35c30 70 6f 73 65 20 69 73 20 74 6f 20 62 65 20 61 20  pose is to be a 
35c40 70 6c 61 63 65 2d 68 6f 6c 64 65 72 20 66 75 6e  place-holder fun
35c50 63 74 69 6f 6e 20 74 68 61 74 20 63 61 6e 20 62  ction that can b
35c60 65 20 6f 76 65 72 6c 6f 61 64 65 64 0a 2a 2a 20  e overloaded.** 
35c70 62 79 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  by virtual table
35c80 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50  s..**.** This AP
35c90 49 20 73 68 6f 75 6c 64 20 62 65 20 63 6f 6e 73  I should be cons
35ca0 69 64 65 72 65 64 20 70 61 72 74 20 6f 66 20 74  idered part of t
35cb0 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  he virtual table
35cc0 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 77   interface,.** w
35cd0 68 69 63 68 20 69 73 20 65 78 70 65 72 69 6d 65  hich is experime
35ce0 6e 74 61 6c 20 61 6e 64 20 73 75 62 6a 65 63 74  ntal and subject
35cf0 20 74 6f 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 69   to change..*/.i
35d00 6e 74 20 73 71 6c 69 74 65 33 5f 6f 76 65 72 6c  nt sqlite3_overl
35d10 6f 61 64 5f 66 75 6e 63 74 69 6f 6e 28 73 71 6c  oad_function(sql
35d20 69 74 65 33 2a 2c 20 63 6f 6e 73 74 20 63 68 61  ite3*, const cha
35d30 72 20 2a 7a 46 75 6e 63 4e 61 6d 65 2c 20 69 6e  r *zFuncName, in
35d40 74 20 6e 41 72 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t nArg);../*.** 
35d50 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f  The interface to
35d60 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62   the virtual-tab
35d70 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 64 65 66  le mechanism def
35d80 69 6e 65 64 20 61 62 6f 76 65 20 28 62 61 63 6b  ined above (back
35d90 20 75 70 0a 2a 2a 20 74 6f 20 61 20 63 6f 6d 6d   up.** to a comm
35da0 65 6e 74 20 72 65 6d 61 72 6b 61 62 6c 79 20 73  ent remarkably s
35db0 69 6d 69 6c 61 72 20 74 6f 20 74 68 69 73 20 6f  imilar to this o
35dc0 6e 65 29 20 69 73 20 63 75 72 72 65 6e 74 6c 79  ne) is currently
35dd0 20 63 6f 6e 73 69 64 65 72 65 64 0a 2a 2a 20 74   considered.** t
35de0 6f 20 62 65 20 65 78 70 65 72 69 6d 65 6e 74 61  o be experimenta
35df0 6c 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61 63  l.  The interfac
35e00 65 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69  e might change i
35e10 6e 20 69 6e 63 6f 6d 70 61 74 69 62 6c 65 20 77  n incompatible w
35e20 61 79 73 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20  ays..** If this 
35e30 69 73 20 61 20 70 72 6f 62 6c 65 6d 20 66 6f 72  is a problem for
35e40 20 79 6f 75 2c 20 64 6f 20 6e 6f 74 20 75 73 65   you, do not use
35e50 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 61   the interface a
35e60 74 20 74 68 69 73 20 74 69 6d 65 2e 0a 2a 2a 0a  t this time..**.
35e70 2a 2a 20 57 68 65 6e 20 74 68 65 20 76 69 72 74  ** When the virt
35e80 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e  ual-table mechan
35e90 69 73 6d 20 73 74 61 62 69 6c 69 7a 65 73 2c 20  ism stabilizes, 
35ea0 77 65 20 77 69 6c 6c 20 64 65 63 6c 61 72 65 20  we will declare 
35eb0 74 68 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  the.** interface
35ec0 20 66 69 78 65 64 2c 20 73 75 70 70 6f 72 74 20   fixed, support 
35ed0 69 74 20 69 6e 64 65 66 69 6e 69 74 65 6c 79 2c  it indefinitely,
35ee0 20 61 6e 64 20 72 65 6d 6f 76 65 20 74 68 69 73   and remove this
35ef0 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 2a   comment..**.***
35f00 2a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c  *** EXPERIMENTAL
35f10 20 2d 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68   - subject to ch
35f20 61 6e 67 65 20 77 69 74 68 6f 75 74 20 6e 6f 74  ange without not
35f30 69 63 65 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ice ************
35f40 2a 2a 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  **.*/../*.** CAP
35f50 49 33 52 45 46 3a 20 41 20 48 61 6e 64 6c 65 20  I3REF: A Handle 
35f60 54 6f 20 41 6e 20 4f 70 65 6e 20 42 4c 4f 42 20  To An Open BLOB 
35f70 7b 46 31 37 38 30 30 7d 0a 2a 2a 0a 2a 2a 20 41  {F17800}.**.** A
35f80 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
35f90 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73  is object repres
35fa0 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 42 4c 4f  ents an open BLO
35fb0 42 20 6f 6e 20 77 68 69 63 68 0a 2a 2a 20 69 6e  B on which.** in
35fc0 63 72 65 6d 65 6e 74 61 6c 20 49 2f 4f 20 63 61  cremental I/O ca
35fd0 6e 20 62 65 20 70 72 65 66 6f 72 6d 65 64 2e 0a  n be preformed..
35fe0 2a 2a 20 4f 62 6a 65 63 74 73 20 6f 66 20 74 68  ** Objects of th
35ff0 69 73 20 74 79 70 65 20 61 72 65 20 63 72 65 61  is type are crea
36000 74 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ted by.** [sqlit
36010 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20  e3_blob_open()] 
36020 61 6e 64 20 64 65 73 74 72 6f 79 65 64 20 62 79  and destroyed by
36030 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63   [sqlite3_blob_c
36040 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  lose()]..** The 
36050 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65  [sqlite3_blob_re
36060 61 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ad()] and [sqlit
36070 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29 5d  e3_blob_write()]
36080 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 63   interfaces.** c
36090 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65  an be used to re
360a0 61 64 20 6f 72 20 77 72 69 74 65 20 73 6d 61 6c  ad or write smal
360b0 6c 20 73 75 62 73 65 63 74 69 6f 6e 73 20 6f 66  l subsections of
360c0 20 74 68 65 20 62 6c 6f 62 2e 0a 2a 2a 20 54 68   the blob..** Th
360d0 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  e [sqlite3_blob_
360e0 62 79 74 65 73 28 29 5d 20 69 6e 74 65 72 66 61  bytes()] interfa
360f0 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 73  ce returns the s
36100 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 62 6c  ize of the.** bl
36110 6f 62 20 69 6e 20 62 79 74 65 73 2e 0a 2a 2f 0a  ob in bytes..*/.
36120 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
36130 71 6c 69 74 65 33 5f 62 6c 6f 62 20 73 71 6c 69  qlite3_blob sqli
36140 74 65 33 5f 62 6c 6f 62 3b 0a 0a 2f 2a 0a 2a 2a  te3_blob;../*.**
36150 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 20   CAPI3REF: Open 
36160 41 20 42 4c 4f 42 20 46 6f 72 20 49 6e 63 72 65  A BLOB For Incre
36170 6d 65 6e 74 61 6c 20 49 2f 4f 20 7b 46 31 37 38  mental I/O {F178
36180 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  10}.**.** This i
36190 6e 74 65 72 66 61 63 65 73 20 6f 70 65 6e 73 20  nterfaces opens 
361a0 61 20 68 61 6e 64 6c 65 20 74 6f 20 74 68 65 20  a handle to the 
361b0 62 6c 6f 62 20 6c 6f 63 61 74 65 64 0a 2a 2a 20  blob located.** 
361c0 69 6e 20 72 6f 77 20 69 52 6f 77 2c 2c 20 63 6f  in row iRow,, co
361d0 6c 75 6d 6e 20 7a 43 6f 6c 75 6d 6e 2c 20 74 61  lumn zColumn, ta
361e0 62 6c 65 20 7a 54 61 62 6c 65 20 69 6e 20 64 61  ble zTable in da
361f0 74 61 62 61 73 65 20 7a 44 62 3b 0a 2a 2a 20 69  tabase zDb;.** i
36200 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 20  n other words,  
36210 74 68 65 20 73 61 6d 65 20 62 6c 6f 62 20 74 68  the same blob th
36220 61 74 20 77 6f 75 6c 64 20 62 65 20 73 65 6c 65  at would be sele
36230 63 74 65 64 20 62 79 3a 0a 2a 2a 0a 2a 2a 20 3c  cted by:.**.** <
36240 70 72 65 3e 0a 2a 2a 20 20 20 20 20 53 45 4c 45  pre>.**     SELE
36250 43 54 20 7a 43 6f 6c 75 6d 6e 20 46 52 4f 4d 20  CT zColumn FROM 
36260 7a 44 62 2e 7a 54 61 62 6c 65 20 57 48 45 52 45  zDb.zTable WHERE
36270 20 72 6f 77 69 64 20 3d 20 69 52 6f 77 3b 0a 2a   rowid = iRow;.*
36280 2a 20 3c 2f 70 72 65 3e 20 7b 45 4e 44 7d 0a 2a  * </pre> {END}.*
36290 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66 6c 61 67  *.** If the flag
362a0 73 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e  s parameter is n
362b0 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 62 6c 6f  on-zero, the blo
362c0 62 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  b is opened for 
362d0 0a 2a 2a 20 72 65 61 64 20 61 6e 64 20 77 72 69  .** read and wri
362e0 74 65 20 61 63 63 65 73 73 2e 20 49 66 20 69 74  te access. If it
362f0 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 20 62 6c   is zero, the bl
36300 6f 62 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72  ob is opened for
36310 20 72 65 61 64 20 0a 2a 2a 20 61 63 63 65 73 73   read .** access
36320 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63 65  ..**.** On succe
36330 73 73 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  ss, [SQLITE_OK] 
36340 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20  is returned and 
36350 74 68 65 20 6e 65 77 20 0a 2a 2a 20 5b 73 71 6c  the new .** [sql
36360 69 74 65 33 5f 62 6c 6f 62 20 7c 20 62 6c 6f 62  ite3_blob | blob
36370 20 68 61 6e 64 6c 65 5d 20 69 73 20 77 72 69 74   handle] is writ
36380 74 65 6e 20 74 6f 20 2a 70 70 42 6c 6f 62 2e 20  ten to *ppBlob. 
36390 0a 2a 2a 20 4f 74 68 65 72 77 69 73 65 20 61 6e  .** Otherwise an
363a0 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72   error code is r
363b0 65 74 75 72 6e 65 64 20 61 6e 64 20 0a 2a 2a 20  eturned and .** 
363c0 61 6e 79 20 76 61 6c 75 65 20 77 72 69 74 74 65  any value writte
363d0 6e 20 74 6f 20 2a 70 70 42 6c 6f 62 20 73 68 6f  n to *ppBlob sho
363e0 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20  uld not be used 
363f0 62 79 20 74 68 65 20 63 61 6c 6c 65 72 2e 0a 2a  by the caller..*
36400 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  * This function 
36410 73 65 74 73 20 74 68 65 20 64 61 74 61 62 61 73  sets the databas
36420 65 2d 68 61 6e 64 6c 65 20 65 72 72 6f 72 20 63  e-handle error c
36430 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65 0a  ode and message.
36440 2a 2a 20 61 63 63 65 73 73 69 62 6c 65 20 76 69  ** accessible vi
36450 61 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  a [sqlite3_errco
36460 64 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  de()] and [sqlit
36470 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a  e3_errmsg()]..**
36480 20 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a   .** INVARIANTS:
36490 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 38 31 33 7d 20  .**.** {F17813} 
364a0 41 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e 76  A successful inv
364b0 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b  ocation of the [
364c0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65  sqlite3_blob_ope
364d0 6e 28 44 2c 42 2c 54 2c 43 2c 52 2c 46 2c 50 29  n(D,B,T,C,R,F,P)
364e0 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  ].**          in
364f0 74 65 72 66 61 63 65 20 6f 70 65 6e 73 20 61 6e  terface opens an
36500 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5d 20   [sqlite3_blob] 
36510 6f 62 6a 65 63 74 20 50 20 6f 6e 20 74 68 65 20  object P on the 
36520 62 6c 6f 62 0a 2a 2a 20 20 20 20 20 20 20 20 20  blob.**         
36530 20 69 6e 20 63 6f 6c 75 6d 6e 20 43 20 6f 66 20   in column C of 
36540 74 61 62 6c 65 20 54 20 69 6e 20 64 61 74 61 62  table T in datab
36550 61 73 65 20 42 20 6f 6e 20 5b 64 61 74 61 62 61  ase B on [databa
36560 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
36570 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 38 31 34 7d  ..**.** {F17814}
36580 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e   A successful in
36590 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c  vocation of [sql
365a0 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 44  ite3_blob_open(D
365b0 2c 2e 2e 2e 29 5d 20 73 74 61 72 74 73 0a 2a 2a  ,...)] starts.**
365c0 20 20 20 20 20 20 20 20 20 20 61 20 6e 65 77 20            a new 
365d0 74 72 61 6e 73 61 63 74 69 6f 6e 20 6f 6e 20 5b  transaction on [
365e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
365f0 69 6f 6e 5d 20 44 20 69 66 20 74 68 61 74 20 63  ion] D if that c
36600 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20  onnection.**    
36610 20 20 20 20 20 20 69 73 20 6e 6f 74 20 61 6c 72        is not alr
36620 65 61 64 79 20 69 6e 20 61 20 74 72 61 6e 73 61  eady in a transa
36630 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  ction..**.** {F1
36640 37 38 31 36 7d 20 54 68 65 20 5b 73 71 6c 69 74  7816} The [sqlit
36650 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 44 2c 42  e3_blob_open(D,B
36660 2c 54 2c 43 2c 52 2c 46 2c 50 29 5d 20 69 6e 74  ,T,C,R,F,P)] int
36670 65 72 66 61 63 65 20 6f 70 65 6e 73 20 74 68 65  erface opens the
36680 20 62 6c 6f 62 0a 2a 2a 20 20 20 20 20 20 20 20   blob.**        
36690 20 20 66 6f 72 20 72 65 61 64 20 61 6e 64 20 77    for read and w
366a0 72 69 74 65 20 61 63 63 65 73 73 20 69 66 20 61  rite access if a
366b0 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 46  nd only if the F
366c0 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20   parameter.**   
366d0 20 20 20 20 20 20 20 69 73 20 6e 6f 6e 2d 7a 65         is non-ze
366e0 72 6f 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 38 31  ro..**.** {F1781
366f0 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  9} The [sqlite3_
36700 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20 69 6e 74  blob_open()] int
36710 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 5b  erface returns [
36720 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 0a 2a  SQLITE_OK] on .*
36730 2a 20 20 20 20 20 20 20 20 20 20 73 75 63 63 65  *          succe
36740 73 73 20 61 6e 64 20 61 6e 20 61 70 70 72 6f 70  ss and an approp
36750 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64  riate [error cod
36760 65 5d 20 6f 6e 20 66 61 69 6c 75 72 65 2e 0a 2a  e] on failure..*
36770 2a 0a 2a 2a 20 7b 46 31 37 38 32 31 7d 20 49 66  *.** {F17821} If
36780 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
36790 20 64 75 72 69 6e 67 20 65 76 61 6c 75 61 74 69   during evaluati
367a0 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 62  on of [sqlite3_b
367b0 6c 6f 62 5f 6f 70 65 6e 28 44 2c 2e 2e 2e 29 5d  lob_open(D,...)]
367c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
367d0 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  n subsequent cal
367e0 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65  ls to [sqlite3_e
367f0 72 72 63 6f 64 65 28 44 29 5d 2c 0a 2a 2a 20 20  rrcode(D)],.**  
36800 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
36810 5f 65 72 72 6d 73 67 28 44 29 5d 2c 20 61 6e 64  _errmsg(D)], and
36820 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
36830 31 36 28 44 29 5d 20 77 69 6c 6c 20 72 65 74 75  16(D)] will retu
36840 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  rn.**          i
36850 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 70 70 72 6f  nformation appro
36860 70 72 61 74 65 20 66 6f 72 20 74 68 61 74 20 65  prate for that e
36870 72 72 6f 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  rror..*/.int sql
36880 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 0a  ite3_blob_open(.
36890 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 63 6f    sqlite3*,.  co
368a0 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 2c 0a 20  nst char *zDb,. 
368b0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 54 61   const char *zTa
368c0 62 6c 65 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61  ble,.  const cha
368d0 72 20 2a 7a 43 6f 6c 75 6d 6e 2c 0a 20 20 73 71  r *zColumn,.  sq
368e0 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 52 6f 77  lite3_int64 iRow
368f0 2c 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 0a 20  ,.  int flags,. 
36900 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 2a   sqlite3_blob **
36910 70 70 42 6c 6f 62 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  ppBlob.);../*.**
36920 20 43 41 50 49 33 52 45 46 3a 20 20 43 6c 6f 73   CAPI3REF:  Clos
36930 65 20 41 20 42 4c 4f 42 20 48 61 6e 64 6c 65 20  e A BLOB Handle 
36940 7b 46 31 37 38 33 30 7d 0a 2a 2a 0a 2a 2a 20 43  {F17830}.**.** C
36950 6c 6f 73 65 20 61 6e 20 6f 70 65 6e 20 5b 73 71  lose an open [sq
36960 6c 69 74 65 33 5f 62 6c 6f 62 20 7c 20 62 6c 6f  lite3_blob | blo
36970 62 20 68 61 6e 64 6c 65 5d 2e 0a 2a 2a 0a 2a 2a  b handle]..**.**
36980 20 43 6c 6f 73 69 6e 67 20 61 20 42 4c 4f 42 20   Closing a BLOB 
36990 73 68 61 6c 6c 20 63 61 75 73 65 20 74 68 65 20  shall cause the 
369a0 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74  current transact
369b0 69 6f 6e 20 74 6f 20 63 6f 6d 6d 69 74 0a 2a 2a  ion to commit.**
369c0 20 69 66 20 74 68 65 72 65 20 61 72 65 20 6e 6f   if there are no
369d0 20 6f 74 68 65 72 20 42 4c 4f 42 73 2c 20 6e 6f   other BLOBs, no
369e0 20 70 65 6e 64 69 6e 67 20 70 72 65 70 61 72 65   pending prepare
369f0 64 20 73 74 61 74 65 6d 65 6e 74 73 2c 20 61 6e  d statements, an
36a00 64 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  d the.** databas
36a10 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
36a20 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f  in autocommit mo
36a30 64 65 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 77 72  de..** If any wr
36a40 69 74 65 73 20 77 65 72 65 20 6d 61 64 65 20 74  ites were made t
36a50 6f 20 74 68 65 20 42 4c 4f 42 2c 20 74 68 65 79  o the BLOB, they
36a60 20 6d 69 67 68 74 20 62 65 20 68 65 6c 64 20 69   might be held i
36a70 6e 20 63 61 63 68 65 0a 2a 2a 20 75 6e 74 69 6c  n cache.** until
36a80 20 74 68 65 20 63 6c 6f 73 65 20 6f 70 65 72 61   the close opera
36a90 74 69 6f 6e 20 69 66 20 74 68 65 79 20 77 69 6c  tion if they wil
36aa0 6c 20 66 69 74 2e 20 7b 45 4e 44 7d 0a 2a 2a 20  l fit. {END}.** 
36ab0 43 6c 6f 73 69 6e 67 20 74 68 65 20 42 4c 4f 42  Closing the BLOB
36ac0 20 6f 66 74 65 6e 20 66 6f 72 63 65 73 20 74 68   often forces th
36ad0 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f 75 74  e changes.** out
36ae0 20 74 6f 20 64 69 73 6b 20 61 6e 64 20 73 6f 20   to disk and so 
36af0 69 66 20 61 6e 79 20 49 2f 4f 20 65 72 72 6f 72  if any I/O error
36b00 73 20 6f 63 63 75 72 2c 20 74 68 65 79 20 77 69  s occur, they wi
36b10 6c 6c 20 6c 69 6b 65 6c 79 20 6f 63 63 75 72 0a  ll likely occur.
36b20 2a 2a 20 61 74 20 74 68 65 20 74 69 6d 65 20 77  ** at the time w
36b30 68 65 6e 20 74 68 65 20 42 4c 4f 42 20 69 73 20  hen the BLOB is 
36b40 63 6c 6f 73 65 64 2e 20 20 7b 46 31 37 38 33 33  closed.  {F17833
36b50 7d 20 41 6e 79 20 65 72 72 6f 72 73 20 74 68 61  } Any errors tha
36b60 74 20 6f 63 63 75 72 20 64 75 72 69 6e 67 0a 2a  t occur during.*
36b70 2a 20 63 6c 6f 73 69 6e 67 20 61 72 65 20 72 65  * closing are re
36b80 70 6f 72 74 65 64 20 61 73 20 61 20 6e 6f 6e 2d  ported as a non-
36b90 7a 65 72 6f 20 72 65 74 75 72 6e 20 76 61 6c 75  zero return valu
36ba0 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 42 4c 4f  e..**.** The BLO
36bb0 42 20 69 73 20 63 6c 6f 73 65 64 20 75 6e 63 6f  B is closed unco
36bc0 6e 64 69 74 69 6f 6e 61 6c 6c 79 2e 20 20 45 76  nditionally.  Ev
36bd0 65 6e 20 69 66 20 74 68 69 73 20 72 6f 75 74 69  en if this routi
36be0 6e 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e  ne returns.** an
36bf0 20 65 72 72 6f 72 20 63 6f 64 65 2c 20 74 68 65   error code, the
36c00 20 42 4c 4f 42 20 69 73 20 73 74 69 6c 6c 20 63   BLOB is still c
36c10 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  losed..**.** INV
36c20 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
36c30 46 31 37 38 33 33 7d 20 54 68 65 20 5b 73 71 6c  F17833} The [sql
36c40 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28  ite3_blob_close(
36c50 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6c  P)] interface cl
36c60 6f 73 65 73 20 61 6e 0a 2a 2a 20 20 20 20 20 20  oses an.**      
36c70 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f      [sqlite3_blo
36c80 62 5d 20 6f 62 6a 65 63 74 20 50 20 70 72 65 76  b] object P prev
36c90 69 6f 75 73 6c 79 20 6f 70 65 6e 65 64 20 75 73  iously opened us
36ca0 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ing.**          
36cb0 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70  [sqlite3_blob_op
36cc0 65 6e 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  en()]..**.** {F1
36cd0 37 38 33 36 7d 20 43 6c 6f 73 69 6e 67 20 61 6e  7836} Closing an
36ce0 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5d 20   [sqlite3_blob] 
36cf0 6f 62 6a 65 63 74 20 75 73 69 6e 67 0a 2a 2a 20  object using.** 
36d00 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
36d10 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 20  3_blob_close()] 
36d20 73 68 61 6c 6c 20 63 61 75 73 65 20 74 68 65 20  shall cause the 
36d30 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74  current transact
36d40 69 6f 6e 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20  ion to.**       
36d50 20 20 20 63 6f 6d 6d 69 74 20 69 66 20 74 68 65     commit if the
36d60 72 65 20 61 72 65 20 6e 6f 20 6f 74 68 65 72 20  re are no other 
36d70 6f 70 65 6e 20 5b 73 71 6c 69 74 65 33 5f 62 6c  open [sqlite3_bl
36d80 6f 62 5d 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 20  ob] objects.**  
36d90 20 20 20 20 20 20 20 20 6f 72 20 5b 70 72 65 70          or [prep
36da0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
36db0 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61   on the same [da
36dc0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
36dd0 6e 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20  n] and.**       
36de0 20 20 20 74 68 65 20 5b 64 61 74 61 62 61 73 65     the [database
36df0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20   connection] is 
36e00 69 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  in.**          [
36e10 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f  sqlite3_get_auto
36e20 63 6f 6d 6d 69 74 20 7c 20 61 75 74 6f 63 6f 6d  commit | autocom
36e30 6d 69 74 20 6d 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a  mit mode]..**.**
36e40 20 7b 46 31 37 38 33 39 7d 20 54 68 65 20 5b 73   {F17839} The [s
36e50 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73  qlite3_blob_clos
36e60 65 28 50 29 5d 20 69 6e 74 65 72 66 61 63 65 73  e(P)] interfaces
36e70 20 63 6c 6f 73 65 73 20 74 68 65 20 0a 2a 2a 20   closes the .** 
36e80 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
36e90 33 5f 62 6c 6f 62 5d 20 6f 62 6a 65 63 74 20 50  3_blob] object P
36ea0 20 75 6e 63 6f 6e 64 69 74 69 6f 6e 61 6c 6c 79   unconditionally
36eb0 2c 20 65 76 65 6e 20 69 66 0a 2a 2a 20 20 20 20  , even if.**    
36ec0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62        [sqlite3_b
36ed0 6c 6f 62 5f 63 6c 6f 73 65 28 50 29 5d 20 72 65  lob_close(P)] re
36ee0 74 75 72 6e 73 20 73 6f 6d 65 74 68 69 6e 67 20  turns something 
36ef0 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
36f00 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 20 20 20 20 20  TE_OK]..**      
36f10 20 20 20 20 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69      .*/.int sqli
36f20 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 73  te3_blob_close(s
36f30 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 29 3b 0a  qlite3_blob *);.
36f40 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
36f50 20 20 52 65 74 75 72 6e 20 54 68 65 20 53 69 7a    Return The Siz
36f60 65 20 4f 66 20 41 6e 20 4f 70 65 6e 20 42 4c 4f  e Of An Open BLO
36f70 42 20 7b 46 31 37 38 34 30 7d 0a 2a 2a 0a 2a 2a  B {F17840}.**.**
36f80 20 52 65 74 75 72 6e 20 74 68 65 20 73 69 7a 65   Return the size
36f90 20 69 6e 20 62 79 74 65 73 20 6f 66 20 74 68 65   in bytes of the
36fa0 20 62 6c 6f 62 20 61 63 63 65 73 73 69 62 6c 65   blob accessible
36fb0 20 76 69 61 20 74 68 65 20 6f 70 65 6e 20 0a 2a   via the open .*
36fc0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5d  * [sqlite3_blob]
36fd0 20 6f 62 6a 65 63 74 20 69 6e 20 69 74 73 20 6f   object in its o
36fe0 6e 6c 79 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  nly argument..**
36ff0 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
37000 2a 2a 0a 2a 2a 20 7b 46 31 37 38 34 33 7d 20 54  **.** {F17843} T
37010 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  he [sqlite3_blob
37020 5f 62 79 74 65 73 28 50 29 5d 20 69 6e 74 65 72  _bytes(P)] inter
37030 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
37040 20 73 69 7a 65 0a 2a 2a 20 20 20 20 20 20 20 20   size.**        
37050 20 20 69 6e 20 62 79 74 65 73 20 6f 66 20 74 68    in bytes of th
37060 65 20 42 4c 4f 42 20 74 68 61 74 20 74 68 65 20  e BLOB that the 
37070 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5d 20 6f  [sqlite3_blob] o
37080 62 6a 65 63 74 20 50 0a 2a 2a 20 20 20 20 20 20  bject P.**      
37090 20 20 20 20 72 65 66 65 72 73 20 74 6f 2e 0a 2a      refers to..*
370a0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c  /.int sqlite3_bl
370b0 6f 62 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33  ob_bytes(sqlite3
370c0 5f 62 6c 6f 62 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  _blob *);../*.**
370d0 20 43 41 50 49 33 52 45 46 3a 20 20 52 65 61 64   CAPI3REF:  Read
370e0 20 44 61 74 61 20 46 72 6f 6d 20 41 20 42 4c 4f   Data From A BLO
370f0 42 20 49 6e 63 72 65 6d 65 6e 74 61 6c 6c 79 20  B Incrementally 
37100 7b 46 31 37 38 35 30 7d 0a 2a 2a 0a 2a 2a 20 54  {F17850}.**.** T
37110 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  his function is 
37120 75 73 65 64 20 74 6f 20 72 65 61 64 20 64 61 74  used to read dat
37130 61 20 66 72 6f 6d 20 61 6e 20 6f 70 65 6e 20 0a  a from an open .
37140 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  ** [sqlite3_blob
37150 20 7c 20 62 6c 6f 62 2d 68 61 6e 64 6c 65 5d 20   | blob-handle] 
37160 69 6e 74 6f 20 61 20 63 61 6c 6c 65 72 20 73 75  into a caller su
37170 70 70 6c 69 65 64 20 62 75 66 66 65 72 2e 0a 2a  pplied buffer..*
37180 2a 20 4e 20 62 79 74 65 73 20 6f 66 20 64 61 74  * N bytes of dat
37190 61 20 61 72 65 20 63 6f 70 69 65 64 20 69 6e 74  a are copied int
371a0 6f 20 62 75 66 66 65 72 0a 2a 2a 20 5a 20 66 72  o buffer.** Z fr
371b0 6f 6d 20 74 68 65 20 6f 70 65 6e 20 62 6c 6f 62  om the open blob
371c0 2c 20 73 74 61 72 74 69 6e 67 20 61 74 20 6f 66  , starting at of
371d0 66 73 65 74 20 69 4f 66 66 73 65 74 2e 0a 2a 2a  fset iOffset..**
371e0 0a 2a 2a 20 49 66 20 6f 66 66 73 65 74 20 69 4f  .** If offset iO
371f0 66 66 73 65 74 20 69 73 20 6c 65 73 73 20 74 68  ffset is less th
37200 61 6e 20 4e 20 62 79 74 65 73 20 66 72 6f 6d 20  an N bytes from 
37210 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 62  the end of the b
37220 6c 6f 62 2c 20 0a 2a 2a 20 5b 53 51 4c 49 54 45  lob, .** [SQLITE
37230 5f 45 52 52 4f 52 5d 20 69 73 20 72 65 74 75 72  _ERROR] is retur
37240 6e 65 64 20 61 6e 64 20 6e 6f 20 64 61 74 61 20  ned and no data 
37250 69 73 20 72 65 61 64 2e 20 20 49 66 20 4e 20 6f  is read.  If N o
37260 72 20 69 4f 66 66 73 65 74 20 69 73 0a 2a 2a 20  r iOffset is.** 
37270 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 20 5b  less than zero [
37280 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 73  SQLITE_ERROR] is
37290 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f   returned and no
372a0 20 64 61 74 61 20 69 73 20 72 65 61 64 2e 0a 2a   data is read..*
372b0 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73 2c  *.** On success,
372c0 20 53 51 4c 49 54 45 5f 4f 4b 20 69 73 20 72 65   SQLITE_OK is re
372d0 74 75 72 6e 65 64 2e 20 4f 74 68 65 72 77 69 73  turned. Otherwis
372e0 65 2c 20 61 6e 20 0a 2a 2a 20 5b 65 72 72 6f 72  e, an .** [error
372f0 20 63 6f 64 65 5d 20 6f 72 20 61 6e 20 5b 65 78   code] or an [ex
37300 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64  tended error cod
37310 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  e] is returned..
37320 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
37330 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 38 35 33 7d  :.**.** {F17853}
37340 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c   The [sqlite3_bl
37350 6f 62 5f 72 65 61 64 28 50 2c 5a 2c 4e 2c 58 29  ob_read(P,Z,N,X)
37360 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 61 64  ] interface read
37370 73 20 4e 20 62 79 74 65 73 0a 2a 2a 20 20 20 20  s N bytes.**    
37380 20 20 20 20 20 20 62 65 67 69 6e 6e 69 6e 67 20        beginning 
37390 61 74 20 6f 66 66 73 65 74 20 58 20 66 72 6f 6d  at offset X from
373a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
373b0 20 62 6c 6f 62 20 74 68 61 74 20 5b 73 71 6c 69   blob that [sqli
373c0 74 65 33 5f 62 6c 6f 62 5d 20 6f 62 6a 65 63 74  te3_blob] object
373d0 20 50 20 72 65 66 65 72 73 20 74 6f 0a 2a 2a 20   P refers to.** 
373e0 20 20 20 20 20 20 20 20 20 61 6e 64 20 77 72 69           and wri
373f0 74 65 73 20 74 68 6f 73 65 20 4e 20 62 79 74 65  tes those N byte
37400 73 20 69 6e 74 6f 20 62 75 66 66 65 72 20 5a 2e  s into buffer Z.
37410 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 38 35 36 7d 20  .**.** {F17856} 
37420 49 6e 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  In [sqlite3_blob
37430 5f 72 65 61 64 28 50 2c 5a 2c 4e 2c 58 29 5d 20  _read(P,Z,N,X)] 
37440 69 66 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  if the size of t
37450 68 65 20 62 6c 6f 62 0a 2a 2a 20 20 20 20 20 20  he blob.**      
37460 20 20 20 20 69 73 20 6c 65 73 73 20 74 68 61 6e      is less than
37470 20 4e 2b 58 20 62 79 74 65 73 2c 20 74 68 65 6e   N+X bytes, then
37480 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 72 65   the function re
37490 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 45 52  turns [SQLITE_ER
374a0 52 4f 52 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ROR].**         
374b0 20 61 6e 64 20 6e 6f 74 68 69 6e 67 20 69 73 20   and nothing is 
374c0 72 65 61 64 20 66 72 6f 6d 20 74 68 65 20 62 6c  read from the bl
374d0 6f 62 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 38 35  ob..**.** {F1785
374e0 39 7d 20 49 6e 20 5b 73 71 6c 69 74 65 33 5f 62  9} In [sqlite3_b
374f0 6c 6f 62 5f 72 65 61 64 28 50 2c 5a 2c 4e 2c 58  lob_read(P,Z,N,X
37500 29 5d 20 69 66 20 58 20 6f 72 20 4e 20 69 73 20  )] if X or N is 
37510 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 0a 2a  less than zero.*
37520 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20  *          then 
37530 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  the function ret
37540 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 45 52 52  urns [SQLITE_ERR
37550 4f 52 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  OR].**          
37560 61 6e 64 20 6e 6f 74 68 69 6e 67 20 69 73 20 72  and nothing is r
37570 65 61 64 20 66 72 6f 6d 20 74 68 65 20 62 6c 6f  ead from the blo
37580 62 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 38 36 32  b..**.** {F17862
37590 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  } The [sqlite3_b
375a0 6c 6f 62 5f 72 65 61 64 28 50 2c 5a 2c 4e 2c 58  lob_read(P,Z,N,X
375b0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
375c0 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
375d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 66 20  .**          if 
375e0 4e 20 62 79 74 65 73 20 77 68 65 72 65 20 73 75  N bytes where su
375f0 63 63 65 73 73 66 75 6c 6c 79 20 72 65 61 64 20  ccessfully read 
37600 69 6e 74 6f 20 62 75 66 66 65 72 20 5a 2e 0a 2a  into buffer Z..*
37610 2a 0a 2a 2a 20 7b 46 31 37 38 36 35 7d 20 49 66  *.** {F17865} If
37620 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20 72   the requested r
37630 65 61 64 20 63 6f 75 6c 64 20 6e 6f 74 20 62 65  ead could not be
37640 20 63 6f 6d 70 6c 65 74 65 64 2c 0a 2a 2a 20 20   completed,.**  
37650 20 20 20 20 20 20 20 20 74 68 65 20 5b 73 71 6c          the [sql
37660 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 50  ite3_blob_read(P
37670 2c 5a 2c 4e 2c 58 29 5d 20 69 6e 74 65 72 66 61  ,Z,N,X)] interfa
37680 63 65 20 72 65 74 75 72 6e 73 20 61 6e 0a 2a 2a  ce returns an.**
37690 20 20 20 20 20 20 20 20 20 20 61 70 70 72 6f 70            approp
376a0 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64  riate [error cod
376b0 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20  e] or [extended 
376c0 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a  error code]..**.
376d0 2a 2a 20 7b 46 31 37 38 36 38 7d 20 49 66 20 61  ** {F17868} If a
376e0 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64  n error occurs d
376f0 75 72 69 6e 67 20 65 76 61 6c 75 61 74 69 6f 6e  uring evaluation
37700 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f   of [sqlite3_blo
37710 62 5f 72 65 61 64 28 44 2c 2e 2e 2e 29 5d 0a 2a  b_read(D,...)].*
37720 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20  *          then 
37730 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
37740 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72   to [sqlite3_err
37750 63 6f 64 65 28 44 29 5d 2c 0a 2a 2a 20 20 20 20  code(D)],.**    
37760 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 65        [sqlite3_e
37770 72 72 6d 73 67 28 44 29 5d 2c 20 61 6e 64 20 5b  rrmsg(D)], and [
37780 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
37790 28 44 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  (D)] will return
377a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 66  .**          inf
377b0 6f 72 6d 61 74 69 6f 6e 20 61 70 70 72 6f 70 72  ormation appropr
377c0 61 74 65 20 66 6f 72 20 74 68 61 74 20 65 72 72  ate for that err
377d0 6f 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  or..*/.int sqlit
377e0 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 73 71 6c  e3_blob_read(sql
377f0 69 74 65 33 5f 62 6c 6f 62 20 2a 2c 20 76 6f 69  ite3_blob *, voi
37800 64 20 2a 5a 2c 20 69 6e 74 20 4e 2c 20 69 6e 74  d *Z, int N, int
37810 20 69 4f 66 66 73 65 74 29 3b 0a 0a 2f 2a 0a 2a   iOffset);../*.*
37820 2a 20 43 41 50 49 33 52 45 46 3a 20 20 57 72 69  * CAPI3REF:  Wri
37830 74 65 20 44 61 74 61 20 49 6e 74 6f 20 41 20 42  te Data Into A B
37840 4c 4f 42 20 49 6e 63 72 65 6d 65 6e 74 61 6c 6c  LOB Incrementall
37850 79 20 7b 46 31 37 38 37 30 7d 0a 2a 2a 0a 2a 2a  y {F17870}.**.**
37860 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69   This function i
37870 73 20 75 73 65 64 20 74 6f 20 77 72 69 74 65 20  s used to write 
37880 64 61 74 61 20 69 6e 74 6f 20 61 6e 20 6f 70 65  data into an ope
37890 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  n .** [sqlite3_b
378a0 6c 6f 62 20 7c 20 62 6c 6f 62 2d 68 61 6e 64 6c  lob | blob-handl
378b0 65 5d 20 66 72 6f 6d 20 61 20 75 73 65 72 20 73  e] from a user s
378c0 75 70 70 6c 69 65 64 20 62 75 66 66 65 72 2e 0a  upplied buffer..
378d0 2a 2a 20 6e 20 62 79 74 65 73 20 6f 66 20 64 61  ** n bytes of da
378e0 74 61 20 61 72 65 20 63 6f 70 69 65 64 20 66 72  ta are copied fr
378f0 6f 6d 20 74 68 65 20 62 75 66 66 65 72 0a 2a 2a  om the buffer.**
37900 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 7a   pointed to by z
37910 20 69 6e 74 6f 20 74 68 65 20 6f 70 65 6e 20 62   into the open b
37920 6c 6f 62 2c 20 73 74 61 72 74 69 6e 67 20 61 74  lob, starting at
37930 20 6f 66 66 73 65 74 20 69 4f 66 66 73 65 74 2e   offset iOffset.
37940 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 73  .**.** If the [s
37950 71 6c 69 74 65 33 5f 62 6c 6f 62 20 7c 20 62 6c  qlite3_blob | bl
37960 6f 62 2d 68 61 6e 64 6c 65 5d 20 70 61 73 73 65  ob-handle] passe
37970 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61  d as the first a
37980 72 67 75 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 6e  rgument.** was n
37990 6f 74 20 6f 70 65 6e 65 64 20 66 6f 72 20 77 72  ot opened for wr
379a0 69 74 69 6e 67 20 28 74 68 65 20 66 6c 61 67 73  iting (the flags
379b0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
379c0 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e  qlite3_blob_open
379d0 28 29 5d 0a 2a 2a 2a 20 77 61 73 20 7a 65 72 6f  ()].*** was zero
379e0 29 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  ), this function
379f0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
37a00 5f 52 45 41 44 4f 4e 4c 59 5d 2e 0a 2a 2a 0a 2a  _READONLY]..**.*
37a10 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  * This function 
37a20 6d 61 79 20 6f 6e 6c 79 20 6d 6f 64 69 66 79 20  may only modify 
37a30 74 68 65 20 63 6f 6e 74 65 6e 74 73 20 6f 66 20  the contents of 
37a40 74 68 65 20 62 6c 6f 62 3b 20 69 74 20 69 73 0a  the blob; it is.
37a50 2a 2a 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  ** not possible 
37a60 74 6f 20 69 6e 63 72 65 61 73 65 20 74 68 65 20  to increase the 
37a70 73 69 7a 65 20 6f 66 20 61 20 62 6c 6f 62 20 75  size of a blob u
37a80 73 69 6e 67 20 74 68 69 73 20 41 50 49 2e 0a 2a  sing this API..*
37a90 2a 20 49 66 20 6f 66 66 73 65 74 20 69 4f 66 66  * If offset iOff
37aa0 73 65 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e  set is less than
37ab0 20 6e 20 62 79 74 65 73 20 66 72 6f 6d 20 74 68   n bytes from th
37ac0 65 20 65 6e 64 20 6f 66 20 74 68 65 20 62 6c 6f  e end of the blo
37ad0 62 2c 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45  b, .** [SQLITE_E
37ae0 52 52 4f 52 5d 20 69 73 20 72 65 74 75 72 6e 65  RROR] is returne
37af0 64 20 61 6e 64 20 6e 6f 20 64 61 74 61 20 69 73  d and no data is
37b00 20 77 72 69 74 74 65 6e 2e 20 20 49 66 20 6e 20   written.  If n 
37b10 69 73 0a 2a 2a 20 6c 65 73 73 20 74 68 61 6e 20  is.** less than 
37b20 7a 65 72 6f 20 5b 53 51 4c 49 54 45 5f 45 52 52  zero [SQLITE_ERR
37b30 4f 52 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  OR] is returned 
37b40 61 6e 64 20 6e 6f 20 64 61 74 61 20 69 73 20 77  and no data is w
37b50 72 69 74 74 65 6e 2e 0a 2a 2a 0a 2a 2a 20 4f 6e  ritten..**.** On
37b60 20 73 75 63 63 65 73 73 2c 20 53 51 4c 49 54 45   success, SQLITE
37b70 5f 4f 4b 20 69 73 20 72 65 74 75 72 6e 65 64 2e  _OK is returned.
37b80 20 4f 74 68 65 72 77 69 73 65 2c 20 61 6e 20 0a   Otherwise, an .
37b90 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  ** [error code] 
37ba0 6f 72 20 61 6e 20 5b 65 78 74 65 6e 64 65 64 20  or an [extended 
37bb0 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
37bc0 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  eturned..**.** I
37bd0 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
37be0 20 7b 46 31 37 38 37 33 7d 20 54 68 65 20 5b 73   {F17873} The [s
37bf0 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74  qlite3_blob_writ
37c00 65 28 50 2c 5a 2c 4e 2c 58 29 5d 20 69 6e 74 65  e(P,Z,N,X)] inte
37c10 72 66 61 63 65 20 77 72 69 74 65 73 20 4e 20 62  rface writes N b
37c20 79 74 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  ytes.**         
37c30 20 66 72 6f 6d 20 62 75 66 66 65 72 20 5a 20 69   from buffer Z i
37c40 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  nto.**          
37c50 74 68 65 20 62 6c 6f 62 20 74 68 61 74 20 5b 73  the blob that [s
37c60 71 6c 69 74 65 33 5f 62 6c 6f 62 5d 20 6f 62 6a  qlite3_blob] obj
37c70 65 63 74 20 50 20 72 65 66 65 72 73 20 74 6f 0a  ect P refers to.
37c80 2a 2a 20 20 20 20 20 20 20 20 20 20 62 65 67 69  **          begi
37c90 6e 6e 69 6e 67 20 61 74 20 61 6e 20 6f 66 66 73  nning at an offs
37ca0 65 74 20 6f 66 20 58 20 69 6e 74 6f 20 74 68 65  et of X into the
37cb0 20 62 6c 6f 62 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31   blob..**.** {F1
37cc0 37 38 37 35 7d 20 54 68 65 20 5b 73 71 6c 69 74  7875} The [sqlit
37cd0 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 50 2c  e3_blob_write(P,
37ce0 5a 2c 4e 2c 58 29 5d 20 69 6e 74 65 72 66 61 63  Z,N,X)] interfac
37cf0 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20  e returns.**    
37d00 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 52 45        [SQLITE_RE
37d10 41 44 4f 4e 4c 59 5d 20 69 66 20 74 68 65 20 5b  ADONLY] if the [
37d20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5d 20 6f 62  sqlite3_blob] ob
37d30 6a 65 63 74 20 50 20 77 61 73 0a 2a 2a 20 20 20  ject P was.**   
37d40 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
37d50 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 6f 70 65 6e  blob_open | open
37d60 65 64 5d 20 66 6f 72 20 72 65 61 64 69 6e 67 20  ed] for reading 
37d70 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37  only..**.** {F17
37d80 38 37 36 7d 20 49 6e 20 5b 73 71 6c 69 74 65 33  876} In [sqlite3
37d90 5f 62 6c 6f 62 5f 77 72 69 74 65 28 50 2c 5a 2c  _blob_write(P,Z,
37da0 4e 2c 58 29 5d 20 69 66 20 74 68 65 20 73 69 7a  N,X)] if the siz
37db0 65 20 6f 66 20 74 68 65 20 62 6c 6f 62 0a 2a 2a  e of the blob.**
37dc0 20 20 20 20 20 20 20 20 20 20 69 73 20 6c 65 73            is les
37dd0 73 20 74 68 61 6e 20 4e 2b 58 20 62 79 74 65 73  s than N+X bytes
37de0 2c 20 74 68 65 6e 20 74 68 65 20 66 75 6e 63 74  , then the funct
37df0 69 6f 6e 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ion returns [SQL
37e00 49 54 45 5f 45 52 52 4f 52 5d 0a 2a 2a 20 20 20  ITE_ERROR].**   
37e10 20 20 20 20 20 20 20 61 6e 64 20 6e 6f 74 68 69         and nothi
37e20 6e 67 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e  ng is written in
37e30 74 6f 20 74 68 65 20 62 6c 6f 62 2e 0a 2a 2a 0a  to the blob..**.
37e40 2a 2a 20 7b 46 31 37 38 37 39 7d 20 49 6e 20 5b  ** {F17879} In [
37e50 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69  sqlite3_blob_wri
37e60 74 65 28 50 2c 5a 2c 4e 2c 58 29 5d 20 69 66 20  te(P,Z,N,X)] if 
37e70 58 20 6f 72 20 4e 20 69 73 20 6c 65 73 73 20 74  X or N is less t
37e80 68 61 6e 20 7a 65 72 6f 0a 2a 2a 20 20 20 20 20  han zero.**     
37e90 20 20 20 20 20 74 68 65 6e 20 74 68 65 20 66 75       then the fu
37ea0 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 5b  nction returns [
37eb0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 0a 2a 2a  SQLITE_ERROR].**
37ec0 20 20 20 20 20 20 20 20 20 20 61 6e 64 20 6e 6f            and no
37ed0 74 68 69 6e 67 20 69 73 20 77 72 69 74 74 65 6e  thing is written
37ee0 20 69 6e 74 6f 20 74 68 65 20 62 6c 6f 62 2e 0a   into the blob..
37ef0 2a 2a 0a 2a 2a 20 7b 46 31 37 38 38 32 7d 20 54  **.** {F17882} T
37f00 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  he [sqlite3_blob
37f10 5f 77 72 69 74 65 28 50 2c 5a 2c 4e 2c 58 29 5d  _write(P,Z,N,X)]
37f20 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
37f30 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 0a 2a  ns [SQLITE_OK].*
37f40 2a 20 20 20 20 20 20 20 20 20 20 69 66 20 4e 20  *          if N 
37f50 62 79 74 65 73 20 77 68 65 72 65 20 73 75 63 63  bytes where succ
37f60 65 73 73 66 75 6c 6c 79 20 77 72 69 74 74 65 6e  essfully written
37f70 20 69 6e 74 6f 20 62 6c 6f 62 2e 0a 2a 2a 0a 2a   into blob..**.*
37f80 2a 20 7b 46 31 37 38 38 35 7d 20 49 66 20 74 68  * {F17885} If th
37f90 65 20 72 65 71 75 65 73 74 65 64 20 77 72 69 74  e requested writ
37fa0 65 20 63 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63  e could not be c
37fb0 6f 6d 70 6c 65 74 65 64 2c 0a 2a 2a 20 20 20 20  ompleted,.**    
37fc0 20 20 20 20 20 20 74 68 65 20 5b 73 71 6c 69 74        the [sqlit
37fd0 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 50 2c  e3_blob_write(P,
37fe0 5a 2c 4e 2c 58 29 5d 20 69 6e 74 65 72 66 61 63  Z,N,X)] interfac
37ff0 65 20 72 65 74 75 72 6e 73 20 61 6e 0a 2a 2a 20  e returns an.** 
38000 20 20 20 20 20 20 20 20 20 61 70 70 72 6f 70 72           appropr
38010 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65  iate [error code
38020 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65  ] or [extended e
38030 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a  rror code]..**.*
38040 2a 20 7b 46 31 37 38 38 38 7d 20 49 66 20 61 6e  * {F17888} If an
38050 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75   error occurs du
38060 72 69 6e 67 20 65 76 61 6c 75 61 74 69 6f 6e 20  ring evaluation 
38070 6f 66 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  of [sqlite3_blob
38080 5f 77 72 69 74 65 28 44 2c 2e 2e 2e 29 5d 0a 2a  _write(D,...)].*
38090 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20  *          then 
380a0 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
380b0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72   to [sqlite3_err
380c0 63 6f 64 65 28 44 29 5d 2c 0a 2a 2a 20 20 20 20  code(D)],.**    
380d0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 65        [sqlite3_e
380e0 72 72 6d 73 67 28 44 29 5d 2c 20 61 6e 64 20 5b  rrmsg(D)], and [
380f0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
38100 28 44 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  (D)] will return
38110 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 66  .**          inf
38120 6f 72 6d 61 74 69 6f 6e 20 61 70 70 72 6f 70 72  ormation appropr
38130 61 74 65 20 66 6f 72 20 74 68 61 74 20 65 72 72  ate for that err
38140 6f 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  or..*/.int sqlit
38150 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 73 71  e3_blob_write(sq
38160 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 2c 20 63 6f  lite3_blob *, co
38170 6e 73 74 20 76 6f 69 64 20 2a 7a 2c 20 69 6e 74  nst void *z, int
38180 20 6e 2c 20 69 6e 74 20 69 4f 66 66 73 65 74 29   n, int iOffset)
38190 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
381a0 46 3a 20 20 56 69 72 74 75 61 6c 20 46 69 6c 65  F:  Virtual File
381b0 20 53 79 73 74 65 6d 20 4f 62 6a 65 63 74 73 20   System Objects 
381c0 7b 46 31 31 32 30 30 7d 0a 2a 2a 0a 2a 2a 20 41  {F11200}.**.** A
381d0 20 76 69 72 74 75 61 6c 20 66 69 6c 65 73 79 73   virtual filesys
381e0 74 65 6d 20 28 56 46 53 29 20 69 73 20 61 6e 20  tem (VFS) is an 
381f0 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
38200 6a 65 63 74 0a 2a 2a 20 74 68 61 74 20 53 51 4c  ject.** that SQL
38210 69 74 65 20 75 73 65 73 20 74 6f 20 69 6e 74 65  ite uses to inte
38220 72 61 63 74 0a 2a 2a 20 77 69 74 68 20 74 68 65  ract.** with the
38230 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72   underlying oper
38240 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 4d  ating system.  M
38250 6f 73 74 20 53 51 4c 69 74 65 20 62 75 69 6c 64  ost SQLite build
38260 73 20 63 6f 6d 65 20 77 69 74 68 20 61 0a 2a 2a  s come with a.**
38270 20 73 69 6e 67 6c 65 20 64 65 66 61 75 6c 74 20   single default 
38280 56 46 53 20 74 68 61 74 20 69 73 20 61 70 70 72  VFS that is appr
38290 6f 70 72 69 61 74 65 20 66 6f 72 20 74 68 65 20  opriate for the 
382a0 68 6f 73 74 20 63 6f 6d 70 75 74 65 72 2e 0a 2a  host computer..*
382b0 2a 20 4e 65 77 20 56 46 53 65 73 20 63 61 6e 20  * New VFSes can 
382c0 62 65 20 72 65 67 69 73 74 65 72 65 64 20 61 6e  be registered an
382d0 64 20 65 78 69 73 74 69 6e 67 20 56 46 53 65 73  d existing VFSes
382e0 20 63 61 6e 20 62 65 20 75 6e 72 65 67 69 73 74   can be unregist
382f0 65 72 65 64 2e 0a 2a 2a 20 54 68 65 20 66 6f 6c  ered..** The fol
38300 6c 6f 77 69 6e 67 20 69 6e 74 65 72 66 61 63 65  lowing interface
38310 73 20 61 72 65 20 70 72 6f 76 69 64 65 64 2e 0a  s are provided..
38320 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
38330 33 5f 76 66 73 5f 66 69 6e 64 28 29 20 69 6e 74  3_vfs_find() int
38340 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
38350 20 70 6f 69 6e 74 65 72 20 74 6f 20 0a 2a 2a 20   pointer to .** 
38360 61 20 56 46 53 20 67 69 76 65 6e 20 69 74 73 20  a VFS given its 
38370 6e 61 6d 65 2e 20 20 4e 61 6d 65 73 20 61 72 65  name.  Names are
38380 20 63 61 73 65 20 73 65 6e 73 69 74 69 76 65 2e   case sensitive.
38390 0a 2a 2a 20 4e 61 6d 65 73 20 61 72 65 20 7a 65  .** Names are ze
383a0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
383b0 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20  F-8 strings..** 
383c0 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 6d  If there is no m
383d0 61 74 63 68 2c 20 61 20 4e 55 4c 4c 0a 2a 2a 20  atch, a NULL.** 
383e0 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72  pointer is retur
383f0 6e 65 64 2e 20 20 49 66 20 7a 56 66 73 4e 61 6d  ned.  If zVfsNam
38400 65 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74  e is NULL then t
38410 68 65 20 64 65 66 61 75 6c 74 20 0a 2a 2a 20 56  he default .** V
38420 46 53 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  FS is returned. 
38430 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 56 46 53 65 73  .**.** New VFSes
38440 20 61 72 65 20 72 65 67 69 73 74 65 72 65 64 20   are registered 
38450 77 69 74 68 20 73 71 6c 69 74 65 33 5f 76 66 73  with sqlite3_vfs
38460 5f 72 65 67 69 73 74 65 72 28 29 2e 0a 2a 2a 20  _register()..** 
38470 45 61 63 68 20 6e 65 77 20 56 46 53 20 62 65 63  Each new VFS bec
38480 6f 6d 65 73 20 74 68 65 20 64 65 66 61 75 6c 74  omes the default
38490 20 56 46 53 20 69 66 20 74 68 65 20 6d 61 6b 65   VFS if the make
384a0 44 66 6c 74 20 66 6c 61 67 20 69 73 20 73 65 74  Dflt flag is set
384b0 2e 0a 2a 2a 20 54 68 65 20 73 61 6d 65 20 56 46  ..** The same VF
384c0 53 20 63 61 6e 20 62 65 20 72 65 67 69 73 74 65  S can be registe
384d0 72 65 64 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d  red multiple tim
384e0 65 73 20 77 69 74 68 6f 75 74 20 69 6e 6a 75 72  es without injur
384f0 79 2e 0a 2a 2a 20 54 6f 20 6d 61 6b 65 20 61 6e  y..** To make an
38500 20 65 78 69 73 74 69 6e 67 20 56 46 53 20 69 6e   existing VFS in
38510 74 6f 20 74 68 65 20 64 65 66 61 75 6c 74 20 56  to the default V
38520 46 53 2c 20 72 65 67 69 73 74 65 72 20 69 74 20  FS, register it 
38530 61 67 61 69 6e 0a 2a 2a 20 77 69 74 68 20 74 68  again.** with th
38540 65 20 6d 61 6b 65 44 66 6c 74 20 66 6c 61 67 20  e makeDflt flag 
38550 73 65 74 2e 20 20 49 66 20 74 77 6f 20 64 69 66  set.  If two dif
38560 66 65 72 65 6e 74 20 56 46 53 65 73 20 77 69 74  ferent VFSes wit
38570 68 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20 6e 61  h the.** same na
38580 6d 65 20 61 72 65 20 72 65 67 69 73 74 65 72 65  me are registere
38590 64 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  d, the behavior 
385a0 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 49  is undefined.  I
385b0 66 20 61 0a 2a 2a 20 56 46 53 20 69 73 20 72 65  f a.** VFS is re
385c0 67 69 73 74 65 72 65 64 20 77 69 74 68 20 61 20  gistered with a 
385d0 6e 61 6d 65 20 74 68 61 74 20 69 73 20 4e 55 4c  name that is NUL
385e0 4c 20 6f 72 20 61 6e 20 65 6d 70 74 79 20 73 74  L or an empty st
385f0 72 69 6e 67 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  ring,.** then th
38600 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e  e behavior is un
38610 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a 20  defined..** .** 
38620 55 6e 72 65 67 69 73 74 65 72 20 61 20 56 46 53  Unregister a VFS
38630 20 77 69 74 68 20 74 68 65 20 73 71 6c 69 74 65   with the sqlite
38640 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72  3_vfs_unregister
38650 28 29 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  () interface..**
38660 20 49 66 20 74 68 65 20 64 65 66 61 75 6c 74 20   If the default 
38670 56 46 53 20 69 73 20 75 6e 72 65 67 69 73 74 65  VFS is unregiste
38680 72 65 64 2c 20 61 6e 6f 74 68 65 72 20 56 46 53  red, another VFS
38690 20 69 73 20 63 68 6f 73 65 6e 20 61 73 0a 2a 2a   is chosen as.**
386a0 20 74 68 65 20 64 65 66 61 75 6c 74 2e 20 20 54   the default.  T
386b0 68 65 20 63 68 6f 69 63 65 20 66 6f 72 20 74 68  he choice for th
386c0 65 20 6e 65 77 20 56 46 53 20 69 73 20 61 72 62  e new VFS is arb
386d0 69 74 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 4e  itrary..**.** IN
386e0 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
386f0 7b 46 31 31 32 30 33 7d 20 54 68 65 20 5b 73 71  {F11203} The [sq
38700 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 4e  lite3_vfs_find(N
38710 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
38720 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
38730 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  o the.**        
38740 20 20 72 65 67 69 73 74 65 72 65 64 20 5b 73 71    registered [sq
38750 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
38760 74 20 77 68 6f 73 65 20 6e 61 6d 65 20 65 78 61  t whose name exa
38770 63 74 6c 79 20 6d 61 74 63 68 65 73 0a 2a 2a 20  ctly matches.** 
38780 20 20 20 20 20 20 20 20 20 74 68 65 20 7a 65 72           the zer
38790 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
387a0 2d 38 20 73 74 72 69 6e 67 20 4e 2c 20 6f 72 20  -8 string N, or 
387b0 69 74 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20  it returns NULL 
387c0 69 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  if.**          t
387d0 68 65 72 65 20 69 73 20 6e 6f 20 6d 61 74 63 68  here is no match
387e0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 32 30 36 7d  ..**.** {F11206}
387f0 20 49 66 20 74 68 65 20 4e 20 70 61 72 61 6d 65   If the N parame
38800 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
38810 76 66 73 5f 66 69 6e 64 28 4e 29 5d 20 69 73 20  vfs_find(N)] is 
38820 4e 55 4c 4c 20 74 68 65 6e 0a 2a 2a 20 20 20 20  NULL then.**    
38830 20 20 20 20 20 20 74 68 65 20 66 75 6e 63 74 69        the functi
38840 6f 6e 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  on returns a poi
38850 6e 74 65 72 20 74 6f 20 74 68 65 20 64 65 66 61  nter to the defa
38860 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  ult [sqlite3_vfs
38870 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 62  ].**          ob
38880 6a 65 63 74 20 69 66 20 74 68 65 72 65 20 69 73  ject if there is
38890 20 6f 6e 65 2c 20 6f 72 20 4e 55 4c 4c 20 69 66   one, or NULL if
388a0 20 74 68 65 72 65 20 69 73 20 6e 6f 20 64 65 66   there is no def
388b0 61 75 6c 74 20 0a 2a 2a 20 20 20 20 20 20 20 20  ault .**        
388c0 20 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20    [sqlite3_vfs] 
388d0 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46  object..**.** {F
388e0 31 31 32 30 39 7d 20 54 68 65 20 5b 73 71 6c 69  11209} The [sqli
388f0 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72  te3_vfs_register
38900 28 50 2c 46 29 5d 20 69 6e 74 65 72 66 61 63 65  (P,F)] interface
38910 20 72 65 67 69 73 74 65 72 73 20 74 68 65 0a 2a   registers the.*
38920 2a 20 20 20 20 20 20 20 20 20 20 77 65 6c 6c 2d  *          well-
38930 66 6f 72 6d 65 64 20 5b 73 71 6c 69 74 65 33 5f  formed [sqlite3_
38940 76 66 73 5d 20 6f 62 6a 65 63 74 20 50 20 75 73  vfs] object P us
38950 69 6e 67 20 74 68 65 20 6e 61 6d 65 20 67 69 76  ing the name giv
38960 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62  en.**          b
38970 79 20 74 68 65 20 7a 4e 61 6d 65 20 66 69 65 6c  y the zName fiel
38980 64 20 6f 66 20 74 68 65 20 6f 62 6a 65 63 74 2e  d of the object.
38990 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 32 31 32 7d 20  .**.** {F11212} 
389a0 55 73 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74  Using the [sqlit
389b0 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28  e3_vfs_register(
389c0 50 2c 46 29 5d 20 69 6e 74 65 72 66 61 63 65 20  P,F)] interface 
389d0 74 6f 20 72 65 67 69 73 74 65 72 0a 2a 2a 20 20  to regi