/ Hex Artifact Content
Login

Artifact 1cf531c45f20cedf0786f4dc5dedc8dcc33b5df3:


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 31 20 32 30 30 38 2f  in,v 1.291 2008/
05f0: 30 33 2f 30 38 20 31 32 3a 33 37 3a 33 31 20 64  03/08 12:37:31 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 0a 2a 2a 20 53 51 4c  15000}.**.** SQL
18e60 69 74 65 20 75 73 65 73 20 74 68 65 20 73 71 6c  ite uses the sql
18e70 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
18e80 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61  t to represent a
18e90 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61  ll values.** tha
18ea0 74 20 61 72 65 20 6f 72 20 63 61 6e 20 62 65 20  t are or can be 
18eb0 73 74 6f 72 65 64 20 69 6e 20 61 20 64 61 74 61  stored in a data
18ec0 62 61 73 65 20 74 61 62 6c 65 2e 0a 2a 2a 20 53  base table..** S
18ed0 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d  QLite uses dynam
18ee0 69 63 20 74 79 70 69 6e 67 20 66 6f 72 20 74 68  ic typing for th
18ef0 65 20 76 61 6c 75 65 73 20 69 74 20 73 74 6f 72  e values it stor
18f00 65 73 2e 20 20 0a 2a 2a 20 56 61 6c 75 65 73 20  es.  .** Values 
18f10 73 74 6f 72 65 64 20 69 6e 20 73 71 6c 69 74 65  stored in sqlite
18f20 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20  3_value objects 
18f30 63 61 6e 20 62 65 0a 2a 2a 20 62 65 20 69 6e 74  can be.** be int
18f40 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20  egers, floating 
18f50 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74  point values, st
18f60 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72  rings, BLOBs, or
18f70 20 4e 55 4c 4c 2e 0a 2a 2f 0a 74 79 70 65 64 65   NULL..*/.typede
18f80 66 20 73 74 72 75 63 74 20 4d 65 6d 20 73 71 6c  f struct Mem sql
18f90 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a  ite3_value;../*.
18fa0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 53 51  ** CAPI3REF:  SQ
18fb0 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65  L Function Conte
18fc0 78 74 20 4f 62 6a 65 63 74 20 7b 46 31 36 30 30  xt Object {F1600
18fd0 31 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e  1}.**.** The con
18fe0 74 65 78 74 20 69 6e 20 77 68 69 63 68 20 61 6e  text in which an
18ff0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78   SQL function ex
19000 65 63 75 74 65 73 20 69 73 20 73 74 6f 72 65 64  ecutes is stored
19010 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65   in an.** sqlite
19020 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74  3_context object
19030 2e 20 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20  .  A pointer to 
19040 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  an sqlite3_conte
19050 78 74 0a 2a 2a 20 6f 62 6a 65 63 74 20 69 73 20  xt.** object is 
19060 61 6c 77 61 79 73 20 66 69 72 73 74 20 70 61 72  always first par
19070 61 6d 65 74 65 72 20 74 6f 20 61 70 70 6c 69 63  ameter to applic
19080 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
19090 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2f 0a  L functions..*/.
190a0 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
190b0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 73  qlite3_context s
190c0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a  qlite3_context;.
190d0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
190e0 20 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73    Binding Values
190f0 20 54 6f 20 50 72 65 70 61 72 65 64 20 53 74 61   To Prepared Sta
19100 74 65 6d 65 6e 74 73 20 7b 46 31 33 35 30 30 7d  tements {F13500}
19110 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 53 51  .**.** In the SQ
19120 4c 20 73 74 72 69 6e 67 73 20 69 6e 70 75 74 20  L strings input 
19130 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  to [sqlite3_prep
19140 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 74  are_v2()] and it
19150 73 0a 2a 2a 20 76 61 72 69 61 6e 74 73 2c 20 6c  s.** variants, l
19160 69 74 65 72 61 6c 73 20 6d 61 79 20 62 65 20 72  iterals may be r
19170 65 70 6c 61 63 65 20 62 79 20 61 20 70 61 72 61  eplace by a para
19180 6d 65 74 65 72 20 69 6e 20 6f 6e 65 0a 2a 2a 20  meter in one.** 
19190 6f 66 20 74 68 65 73 65 20 66 6f 72 6d 73 3a 0a  of these forms:.
191a0 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
191b0 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f  i>  ?.** <li>  ?
191c0 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56  NNN.** <li>  :VV
191d0 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a  V.** <li>  @VVV.
191e0 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a  ** <li>  $VVV.**
191f0 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20   </ul>.**.** In 
19200 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 66 6f  the parameter fo
19210 72 6d 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20  rms shown above 
19220 4e 4e 4e 20 69 73 20 61 6e 20 69 6e 74 65 67 65  NNN is an intege
19230 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 56 56  r literal,.** VV
19240 56 20 61 6c 70 68 61 2d 6e 75 6d 65 72 69 63 20  V alpha-numeric 
19250 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 2e 0a  parameter name..
19260 2a 2a 20 54 68 65 20 76 61 6c 75 65 73 20 6f 66  ** The values of
19270 20 74 68 65 73 65 20 70 61 72 61 6d 65 74 65 72   these parameter
19280 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22  s (also called "
19290 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e  host parameter n
192a0 61 6d 65 73 22 0a 2a 2a 20 6f 72 20 22 53 51 4c  ames".** or "SQL
192b0 20 70 61 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a   parameters").**
192c0 20 63 61 6e 20 62 65 20 73 65 74 20 75 73 69 6e   can be set usin
192d0 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  g the sqlite3_bi
192e0 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
192f0 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a  defined here..**
19300 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
19310 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71  gument to the sq
19320 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
19330 6f 75 74 69 6e 65 73 20 61 6c 77 61 79 73 0a 2a  outines always.*
19340 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  * is a pointer t
19350 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  o the [sqlite3_s
19360 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 74 75  tmt] object retu
19370 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71  rned from.** [sq
19380 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
19390 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61  ()] or its varia
193a0 6e 74 73 2e 20 54 68 65 20 73 65 63 6f 6e 64 0a  nts. The second.
193b0 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  ** argument is t
193c0 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20  he index of the 
193d0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20  parameter to be 
193e0 73 65 74 2e 20 54 68 65 0a 2a 2a 20 66 69 72 73  set. The.** firs
193f0 74 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20  t parameter has 
19400 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e 20 20  an index of 1.  
19410 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20 6e 61  When the same na
19420 6d 65 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  med.** parameter
19430 20 69 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68   is used more th
19440 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20  an once, second 
19450 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a  and subsequent.*
19460 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61  * occurrences ha
19470 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65  ve the same inde
19480 78 20 61 73 20 74 68 65 20 66 69 72 73 74 20 6f  x as the first o
19490 63 63 75 72 72 65 6e 63 65 2e 20 0a 2a 2a 20 54  ccurrence. .** T
194a0 68 65 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d  he index for nam
194b0 65 64 20 70 61 72 61 6d 65 74 65 72 73 20 63 61  ed parameters ca
194c0 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75  n be looked up u
194d0 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  sing the.** [sql
194e0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
194f0 74 65 72 5f 6e 61 6d 65 28 29 5d 20 41 50 49 20  ter_name()] API 
19500 69 66 20 64 65 73 69 72 65 64 2e 20 20 54 68 65  if desired.  The
19510 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f   index.** for "?
19520 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20  NNN" parameters 
19530 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  is the value of 
19540 4e 4e 4e 2e 0a 2a 2a 20 54 68 65 20 4e 4e 4e 20  NNN..** The NNN 
19550 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65  value must be be
19560 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20  tween 1 and the 
19570 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20  compile-time.** 
19580 70 61 72 61 6d 65 74 65 72 20 53 51 4c 49 54 45  parameter SQLITE
19590 5f 4d 41 58 5f 56 41 52 49 41 42 4c 45 5f 4e 55  _MAX_VARIABLE_NU
195a0 4d 42 45 52 20 28 64 65 66 61 75 6c 74 20 76 61  MBER (default va
195b0 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a  lue: 999)..**.**
195c0 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   The third argum
195d0 65 6e 74 20 69 73 20 74 68 65 20 76 61 6c 75 65  ent is the value
195e0 20 74 6f 20 62 69 6e 64 20 74 6f 20 74 68 65 20   to bind to the 
195f0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
19600 20 49 6e 20 74 68 6f 73 65 0a 2a 2a 20 72 6f 75   In those.** rou
19610 74 69 6e 65 73 20 74 68 61 74 20 68 61 76 65 20  tines that have 
19620 61 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  a fourth argumen
19630 74 2c 20 69 74 73 20 76 61 6c 75 65 20 69 73 20  t, its value is 
19640 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
19650 74 65 73 0a 2a 2a 20 69 6e 20 74 68 65 20 70 61  tes.** in the pa
19660 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 20  rameter.  To be 
19670 63 6c 65 61 72 3a 20 74 68 65 20 76 61 6c 75 65  clear: the value
19680 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
19690 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 0a 2a  f <u>bytes</u>.*
196a0 2a 20 69 6e 20 74 68 65 20 76 61 6c 75 65 2c 20  * in the value, 
196b0 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  not the number o
196c0 66 20 63 68 61 72 61 63 74 65 72 73 2e 20 20 20  f characters.   
196d0 54 68 65 20 6e 75 6d 62 65 72 0a 2a 2a 20 6f 66  The number.** of
196e0 20 62 79 74 65 73 20 64 6f 65 73 20 6e 6f 74 20   bytes does not 
196f0 69 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f  include the zero
19700 2d 74 65 72 6d 69 6e 61 74 6f 72 20 61 74 20 74  -terminator at t
19710 68 65 20 65 6e 64 20 6f 66 20 73 74 72 69 6e 67  he end of string
19720 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f 75  s..** If the fou
19730 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
19740 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 20 6c   negative, the l
19750 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73 74 72  ength of the str
19760 69 6e 67 20 69 73 0a 2a 2a 20 6e 75 6d 62 65 72  ing is.** number
19770 20 6f 66 20 62 79 74 65 73 20 75 70 20 74 6f 20   of bytes up to 
19780 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74  the first zero t
19790 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a  erminator..**.**
197a0 20 54 68 65 20 66 69 66 74 68 20 61 72 67 75 6d   The fifth argum
197b0 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ent to sqlite3_b
197c0 69 6e 64 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69  ind_blob(), sqli
197d0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c  te3_bind_text(),
197e0 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   and.** sqlite3_
197f0 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 69 73  bind_text16() is
19800 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 75 73   a destructor us
19810 65 64 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66  ed to dispose of
19820 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20   the BLOB or.** 
19830 73 74 72 69 6e 67 20 61 66 74 65 72 20 53 51 4c  string after SQL
19840 69 74 65 20 68 61 73 20 66 69 6e 69 73 68 65 64  ite has finished
19850 20 77 69 74 68 20 69 74 2e 20 49 66 20 74 68 65   with it. If the
19860 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20   fifth argument 
19870 69 73 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 61  is.** the specia
19880 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f  l value [SQLITE_
19890 53 54 41 54 49 43 5d 2c 20 74 68 65 6e 20 53 51  STATIC], then SQ
198a0 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 61  Lite assumes tha
198b0 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61  t the.** informa
198c0 74 69 6f 6e 20 69 73 20 69 6e 20 73 74 61 74 69  tion is in stati
198d0 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 61  c, unmanaged spa
198e0 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20  ce and does not 
198f0 6e 65 65 64 20 74 6f 20 62 65 20 66 72 65 65 64  need to be freed
19900 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 66 74  ..** If the fift
19910 68 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20 74  h argument has t
19920 68 65 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45  he value [SQLITE
19930 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65  _TRANSIENT], the
19940 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65  n.** SQLite make
19950 73 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74  s its own privat
19960 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61  e copy of the da
19970 74 61 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20  ta immediately, 
19980 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71  before.** the sq
19990 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
199a0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a  outine returns..
199b0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
199c0 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28  3_bind_zeroblob(
199d0 29 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 73 20  ) routine binds 
199e0 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68  a BLOB of length
199f0 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20 66 69   N that.** is fi
19a00 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 6f 73 2e  lled with zeros.
19a10 20 20 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65    A zeroblob use
19a20 73 20 61 20 66 69 78 65 64 20 61 6d 6f 75 6e 74  s a fixed amount
19a30 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a   of memory.** (j
19a40 75 73 74 20 61 6e 20 69 6e 74 65 67 65 72 20 74  ust an integer t
19a50 6f 20 68 6f 6c 64 20 69 74 20 73 69 7a 65 29 20  o hold it size) 
19a60 77 68 69 6c 65 20 69 74 20 69 73 20 62 65 69 6e  while it is bein
19a70 67 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20  g processed..** 
19a80 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e  Zeroblobs are in
19a90 74 65 6e 64 65 64 20 74 6f 20 73 65 72 76 65 20  tended to serve 
19aa0 61 73 20 70 6c 61 63 65 2d 68 6f 6c 64 65 72 73  as place-holders
19ab0 20 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73 65   for BLOBs whose
19ac0 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c  .** content is l
19ad0 61 74 65 72 20 77 72 69 74 74 65 6e 20 75 73 69  ater written usi
19ae0 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ng .** [sqlite3_
19af0 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72  blob_open | incr
19b00 65 6d 65 6e 74 20 42 4c 4f 42 20 49 2f 4f 5d 20  ement BLOB I/O] 
19b10 72 6f 75 74 69 6e 65 73 2e 20 41 20 6e 65 67 61  routines. A nega
19b20 74 69 76 65 0a 2a 2a 20 76 61 6c 75 65 20 66 6f  tive.** value fo
19b30 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72  r the zeroblob r
19b40 65 73 75 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f  esults in a zero
19b50 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a  -length BLOB..**
19b60 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
19b70 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
19b80 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  s must be called
19b90 20 61 66 74 65 72 0a 2a 2a 20 5b 73 71 6c 69 74   after.** [sqlit
19ba0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
19bb0 20 28 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e   (and its varian
19bc0 74 73 29 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ts) or [sqlite3_
19bd0 72 65 73 65 74 28 29 5d 20 61 6e 64 0a 2a 2a 20  reset()] and.** 
19be0 62 65 66 6f 72 65 20 5b 73 71 6c 69 74 65 33 5f  before [sqlite3_
19bf0 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 42 69 6e 64  step()]..** Bind
19c00 69 6e 67 73 20 61 72 65 20 6e 6f 74 20 63 6c 65  ings are not cle
19c10 61 72 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c  ared by the [sql
19c20 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 72 6f  ite3_reset()] ro
19c30 75 74 69 6e 65 2e 0a 2a 2a 20 55 6e 62 6f 75 6e  utine..** Unboun
19c40 64 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65  d parameters are
19c50 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
19c60 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  NULL..**.** Thes
19c70 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
19c80 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e  n [SQLITE_OK] on
19c90 20 73 75 63 63 65 73 73 20 6f 72 20 61 6e 20 65   success or an e
19ca0 72 72 6f 72 20 63 6f 64 65 20 69 66 0a 2a 2a 20  rror code if.** 
19cb0 61 6e 79 74 68 69 6e 67 20 67 6f 65 73 20 77 72  anything goes wr
19cc0 6f 6e 67 2e 20 20 5b 53 51 4c 49 54 45 5f 52 41  ong.  [SQLITE_RA
19cd0 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64  NGE] is returned
19ce0 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
19cf0 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f 75  r.** index is ou
19d00 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5b 53 51  t of range.  [SQ
19d10 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72  LITE_NOMEM] is r
19d20 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f  eturned if mallo
19d30 63 20 66 61 69 6c 73 2e 0a 2a 2a 20 5b 53 51 4c  c fails..** [SQL
19d40 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d 69 67 68  ITE_MISUSE] migh
19d50 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 69 66  t be returned if
19d60 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
19d70 61 72 65 20 63 61 6c 6c 65 64 20 6f 6e 20 61 0a  are called on a.
19d80 2a 2a 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69  ** virtual machi
19d90 6e 65 20 74 68 61 74 20 69 73 20 74 68 65 20 77  ne that is the w
19da0 72 6f 6e 67 20 73 74 61 74 65 20 6f 72 20 77 68  rong state or wh
19db0 69 63 68 20 68 61 73 20 61 6c 72 65 61 64 79 20  ich has already 
19dc0 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 0a  been finalized..
19dd0 2a 2a 20 44 65 74 65 63 74 69 6f 6e 20 6f 66 20  ** Detection of 
19de0 6d 69 73 75 73 65 20 69 73 20 75 6e 72 65 6c 69  misuse is unreli
19df0 61 62 6c 65 2e 20 20 41 70 70 6c 69 63 61 74 69  able.  Applicati
19e00 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20 64  ons should not d
19e10 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 53 51 4c 49  epend.** on SQLI
19e20 54 45 5f 4d 49 53 55 53 45 20 72 65 74 75 72 6e  TE_MISUSE return
19e30 73 2e 20 20 53 51 4c 49 54 45 5f 4d 49 53 55 53  s.  SQLITE_MISUS
19e40 45 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f  E is intended to
19e50 20 69 6e 64 69 63 61 74 65 20 61 0a 2a 2a 20 61   indicate a.** a
19e60 20 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20   logic error in 
19e70 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e  the application.
19e80 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e    Future version
19e90 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68  s of SQLite migh
19ea0 74 0a 2a 2a 20 70 61 6e 69 63 20 72 61 74 68 65  t.** panic rathe
19eb0 72 20 74 68 61 6e 20 72 65 74 75 72 6e 20 53 51  r than return SQ
19ec0 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 0a  LITE_MISUSE..**.
19ed0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
19ee0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
19ef0 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a  eter_count()],.*
19f00 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
19f10 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29  parameter_name()
19f20 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
19f30 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
19f40 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a  r_index()]..**.*
19f50 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
19f60 0a 2a 2a 20 7b 46 31 33 35 30 36 7d 20 54 68 65  .** {F13506} The
19f70 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
19f80 65 20 7c 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  e | SQL statemen
19f90 74 20 63 6f 6d 70 69 6c 65 72 5d 20 72 65 63 6f  t compiler] reco
19fa0 67 6e 69 7a 65 73 0a 2a 2a 20 20 20 20 20 20 20  gnizes.**       
19fb0 20 20 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65     tokens of the
19fc0 20 66 6f 72 6d 73 20 22 3f 22 2c 20 22 3f 4e 4e   forms "?", "?NN
19fd0 4e 22 2c 20 22 24 56 56 56 22 2c 20 22 3a 56 56  N", "$VVV", ":VV
19fe0 56 22 2c 20 61 6e 64 20 22 40 56 56 56 22 0a 2a  V", and "@VVV".*
19ff0 2a 20 20 20 20 20 20 20 20 20 20 61 73 20 53 51  *          as SQ
1a000 4c 20 70 61 72 61 6d 65 74 65 72 73 2c 20 77 68  L parameters, wh
1a010 65 72 65 20 4e 4e 4e 20 69 73 20 61 6e 79 20 73  ere NNN is any s
1a020 65 71 75 65 6e 63 65 20 6f 66 20 6f 6e 65 20 6f  equence of one o
1a030 72 20 6d 6f 72 65 0a 2a 2a 20 20 20 20 20 20 20  r more.**       
1a040 20 20 20 64 69 67 69 74 73 20 61 6e 64 20 77 68     digits and wh
1a050 65 72 65 20 56 56 56 20 69 73 20 61 6e 79 20 73  ere VVV is any s
1a060 65 71 75 65 6e 63 65 20 6f 66 20 6f 6e 65 20 6f  equence of one o
1a070 72 20 6d 6f 72 65 20 0a 2a 2a 20 20 20 20 20 20  r more .**      
1a080 20 20 20 20 61 6c 70 68 61 6e 75 6d 65 72 69 63      alphanumeric
1a090 20 63 68 61 72 61 63 74 65 72 73 20 6f 72 20 22   characters or "
1a0a0 3a 3a 22 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 66  ::" optionally f
1a0b0 6f 6c 6c 6f 77 65 64 20 62 79 0a 2a 2a 20 20 20  ollowed by.**   
1a0c0 20 20 20 20 20 20 20 61 20 73 74 72 69 6e 67 20         a string 
1a0d0 63 6f 6e 74 61 69 6e 69 6e 67 20 6e 6f 20 73 70  containing no sp
1a0e0 61 63 65 73 20 61 6e 64 20 63 6f 6e 74 61 69 6e  aces and contain
1a0f0 65 64 20 77 69 74 68 69 6e 20 70 61 72 65 6e 74  ed within parent
1a100 68 65 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  heses..**.** {F1
1a110 33 35 30 39 7d 20 54 68 65 20 69 6e 69 74 69 61  3509} The initia
1a120 6c 20 76 61 6c 75 65 20 6f 66 20 61 6e 20 53 51  l value of an SQ
1a130 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e  L parameter is N
1a140 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35  ULL..**.** {F135
1a150 31 32 7d 20 54 68 65 20 69 6e 64 65 78 20 6f 66  12} The index of
1a160 20 61 6e 20 22 3f 22 20 53 51 4c 20 70 61 72 61   an "?" SQL para
1a170 6d 65 74 65 72 20 69 73 20 6f 6e 65 20 6c 61 72  meter is one lar
1a180 67 65 72 20 74 68 61 6e 20 74 68 65 0a 2a 2a 20  ger than the.** 
1a190 20 20 20 20 20 20 20 20 20 6c 61 72 67 65 73 74           largest
1a1a0 20 69 6e 64 65 78 20 6f 66 20 53 51 4c 20 70 61   index of SQL pa
1a1b0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 6c  rameter to the l
1a1c0 65 66 74 2c 20 6f 72 20 31 20 69 66 0a 2a 2a 20  eft, or 1 if.** 
1a1d0 20 20 20 20 20 20 20 20 20 74 68 65 20 22 3f 22           the "?"
1a1e0 20 69 73 20 74 68 65 20 6c 65 66 74 6d 6f 73 74   is the leftmost
1a1f0 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 2e 0a   SQL parameter..
1a200 2a 2a 0a 2a 2a 20 7b 46 31 33 35 31 35 7d 20 54  **.** {F13515} T
1a210 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 22  he index of an "
1a220 3f 4e 4e 4e 22 20 53 51 4c 20 70 61 72 61 6d 65  ?NNN" SQL parame
1a230 74 65 72 20 69 73 20 74 68 65 20 69 6e 74 65 67  ter is the integ
1a240 65 72 20 4e 4e 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 46  er NNN..**.** {F
1a250 31 33 35 31 38 7d 20 54 68 65 20 69 6e 64 65 78  13518} The index
1a260 20 6f 66 20 61 6e 20 22 3a 56 56 56 22 2c 20 22   of an ":VVV", "
1a270 24 56 56 56 22 2c 20 6f 72 20 22 40 56 56 56 22  $VVV", or "@VVV"
1a280 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69   SQL parameter i
1a290 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  s.**          th
1a2a0 65 20 73 61 6d 65 20 61 73 20 74 68 65 20 69 6e  e same as the in
1a2b0 64 65 78 20 6f 66 20 6c 65 66 74 6d 6f 73 74 20  dex of leftmost 
1a2c0 6f 63 63 75 72 61 6e 63 65 73 20 6f 66 20 74 68  occurances of th
1a2d0 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20  e same.**       
1a2e0 20 20 20 70 61 72 61 6d 65 74 65 72 2c 20 6f 72     parameter, or
1a2f0 20 6f 6e 65 20 6d 6f 72 65 20 74 68 61 6e 20 74   one more than t
1a300 68 65 20 6c 61 72 67 65 73 74 20 69 6e 64 65 78  he largest index
1a310 20 6f 76 65 72 20 61 6c 6c 0a 2a 2a 20 20 20 20   over all.**    
1a320 20 20 20 20 20 20 70 61 72 61 6d 65 74 65 72 73        parameters
1a330 20 74 6f 20 74 68 65 20 6c 65 66 74 20 69 66 20   to the left if 
1a340 74 68 69 73 20 69 73 20 74 68 65 20 66 69 72 73  this is the firs
1a350 74 20 6f 63 63 75 72 72 61 6e 63 65 0a 2a 2a 20  t occurrance.** 
1a360 20 20 20 20 20 20 20 20 20 6f 66 20 74 68 69 73           of this
1a370 20 70 61 72 61 6d 65 74 65 72 2c 20 6f 72 20 31   parameter, or 1
1a380 20 69 66 20 74 68 69 73 20 69 73 20 74 68 65 20   if this is the 
1a390 6c 65 66 74 6d 6f 73 74 20 70 61 72 61 6d 65 74  leftmost paramet
1a3a0 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 32  er..**.** {F1352
1a3b0 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
1a3c0 70 72 65 70 61 72 65 20 7c 20 53 51 4c 20 73 74  prepare | SQL st
1a3d0 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72  atement compiler
1a3e0 5d 20 66 61 69 6c 20 77 69 74 68 0a 2a 2a 20 20  ] fail with.**  
1a3f0 20 20 20 20 20 20 20 20 61 6e 20 5b 53 51 4c 49          an [SQLI
1a400 54 45 5f 52 41 4e 47 45 5d 20 65 72 72 6f 72 20  TE_RANGE] error 
1a410 69 66 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20  if the index of 
1a420 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  an SQL parameter
1a430 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20  .**          is 
1a440 6c 65 73 73 20 74 68 61 6e 20 31 20 6f 72 20 67  less than 1 or g
1a450 72 65 61 74 65 72 20 74 68 61 6e 20 53 51 4c 49  reater than SQLI
1a460 54 45 5f 4d 41 58 5f 56 41 52 49 41 42 4c 45 5f  TE_MAX_VARIABLE_
1a470 4e 55 4d 42 45 52 2e 0a 2a 2a 0a 2a 2a 20 7b 46  NUMBER..**.** {F
1a480 31 33 35 32 34 7d 20 43 61 6c 6c 73 20 74 6f 20  13524} Calls to 
1a490 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65  [sqlite3_bind_te
1a4a0 78 74 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e  xt | sqlite3_bin
1a4b0 64 28 53 2c 4e 2c 56 2c 2e 2e 2e 29 5d 0a 2a 2a  d(S,N,V,...)].**
1a4c0 20 20 20 20 20 20 20 20 20 20 61 73 73 6f 63 69            associ
1a4d0 61 74 65 20 74 68 65 20 76 61 6c 75 65 20 56 20  ate the value V 
1a4e0 77 69 74 68 20 61 6c 6c 20 53 51 4c 20 70 61 72  with all SQL par
1a4f0 61 6d 65 74 65 72 73 20 68 61 76 69 6e 67 20 61  ameters having a
1a500 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  n.**          in
1a510 64 65 78 20 6f 66 20 4e 20 69 6e 20 74 68 65 20  dex of N in the 
1a520 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
1a530 65 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 46  ent] S..**.** {F
1a540 31 33 35 32 37 7d 20 43 61 6c 6c 73 20 74 6f 20  13527} Calls to 
1a550 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65  [sqlite3_bind_te
1a560 78 74 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e  xt | sqlite3_bin
1a570 64 28 53 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20  d(S,N,...)].**  
1a580 20 20 20 20 20 20 20 20 6f 76 65 72 72 69 64 65          override
1a590 20 70 72 69 6f 72 20 63 61 6c 6c 73 20 77 69 74   prior calls wit
1a5a0 68 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65  h the same value
1a5b0 73 20 6f 66 20 53 20 61 6e 64 20 4e 2e 0a 2a 2a  s of S and N..**
1a5c0 0a 2a 2a 20 7b 46 31 33 35 33 30 7d 20 42 69 6e  .** {F13530} Bin
1a5d0 64 69 6e 67 73 20 65 73 74 61 62 6c 69 73 68 65  dings establishe
1a5e0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 62 69  d by [sqlite3_bi
1a5f0 6e 64 5f 74 65 78 74 20 7c 20 73 71 6c 69 74 65  nd_text | sqlite
1a600 33 5f 62 69 6e 64 28 53 2c 2e 2e 2e 29 5d 0a 2a  3_bind(S,...)].*
1a610 2a 20 20 20 20 20 20 20 20 20 20 70 65 72 73 69  *          persi
1a620 73 74 20 61 63 72 6f 73 73 20 63 61 6c 6c 73 20  st across calls 
1a630 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  to [sqlite3_rese
1a640 74 28 53 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  t(S)]..**.** {F1
1a650 33 35 33 33 7d 20 49 6e 20 63 61 6c 6c 73 20 74  3533} In calls t
1a660 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  o [sqlite3_bind_
1a670 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d  blob(S,N,V,L,D)]
1a680 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  ,.**          [s
1a690 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
1a6a0 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 20 6f 72  (S,N,V,L,D)], or
1a6b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
1a6c0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
1a6d0 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 53 51  6(S,N,V,L,D)] SQ
1a6e0 4c 69 74 65 20 62 69 6e 64 73 20 74 68 65 20 66  Lite binds the f
1a6f0 69 72 73 74 20 4c 0a 2a 2a 20 20 20 20 20 20 20  irst L.**       
1a700 20 20 20 62 79 74 65 73 20 6f 66 20 74 68 65 20     bytes of the 
1a710 62 6c 6f 62 20 6f 72 20 73 74 72 69 6e 67 20 70  blob or string p
1a720 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 56 2c 20  ointed to by V, 
1a730 77 68 65 6e 20 4c 0a 2a 2a 20 20 20 20 20 20 20  when L.**       
1a740 20 20 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69     is non-negati
1a750 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 33  ve..**.** {F1353
1a760 36 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b  6} In calls to [
1a770 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
1a780 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 6f 72  t(S,N,V,L,D)] or
1a790 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
1a7a0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
1a7b0 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 53 51  6(S,N,V,L,D)] SQ
1a7c0 4c 69 74 65 20 62 69 6e 64 73 20 63 68 61 72 61  Lite binds chara
1a7d0 63 74 65 72 73 0a 2a 2a 20 20 20 20 20 20 20 20  cters.**        
1a7e0 20 20 66 72 6f 6d 20 56 20 74 68 72 6f 75 67 68    from V through
1a7f0 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
1a800 63 68 61 72 61 63 74 65 72 20 77 68 65 6e 20 4c  character when L
1a810 20 69 73 20 6e 65 67 61 74 69 76 65 2e 0a 2a 2a   is negative..**
1a820 0a 2a 2a 20 7b 46 31 33 35 33 39 7d 20 49 6e 20  .** {F13539} In 
1a830 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
1a840 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c  3_bind_blob(S,N,
1a850 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20  V,L,D)],.**     
1a860 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69       [sqlite3_bi
1a870 6e 64 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c  nd_text(S,N,V,L,
1a880 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20  D)], or.**      
1a890 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e      [sqlite3_bin
1a8a0 64 5f 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c  d_text16(S,N,V,L
1a8b0 2c 44 29 5d 20 77 68 65 6e 20 44 20 69 73 20 74  ,D)] when D is t
1a8c0 68 65 20 73 70 65 63 69 61 6c 0a 2a 2a 20 20 20  he special.**   
1a8d0 20 20 20 20 20 20 20 63 6f 6e 73 74 61 6e 74 20         constant 
1a8e0 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c  [SQLITE_STATIC],
1a8f0 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20   SQLite assumes 
1a900 74 68 61 74 20 74 68 65 20 76 61 6c 75 65 20 56  that the value V
1a910 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20  .**          is 
1a920 68 65 6c 64 20 69 6e 20 73 74 61 74 69 63 20 75  held in static u
1a930 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20 74  nmanaged space t
1a940 68 61 74 20 77 69 6c 6c 20 6e 6f 74 20 63 68 61  hat will not cha
1a950 6e 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  nge.**          
1a960 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74  during the lifet
1a970 69 6d 65 20 6f 66 20 74 68 65 20 62 69 6e 64 69  ime of the bindi
1a980 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 34  ng..**.** {F1354
1a990 32 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b  2} In calls to [
1a9a0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
1a9b0 62 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a  b(S,N,V,L,D)],.*
1a9c0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
1a9d0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 53 2c  te3_bind_text(S,
1a9e0 4e 2c 56 2c 4c 2c 44 29 5d 2c 20 6f 72 0a 2a 2a  N,V,L,D)], or.**
1a9f0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
1aa00 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 53  e3_bind_text16(S
1aa10 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 77 68 65 6e 20  ,N,V,L,D)] when 
1aa20 44 20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c  D is the special
1aa30 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e  .**          con
1aa40 73 74 61 6e 74 20 5b 53 51 4c 49 54 45 5f 54 52  stant [SQLITE_TR
1aa50 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 20 72 6f  ANSIENT], the ro
1aa60 75 74 69 6e 65 20 6d 61 6b 65 73 20 61 20 0a 2a  utine makes a .*
1aa70 2a 20 20 20 20 20 20 20 20 20 20 70 72 69 76 61  *          priva
1aa80 74 65 20 63 6f 70 79 20 6f 66 20 56 20 76 61 6c  te copy of V val
1aa90 75 65 20 62 65 66 6f 72 65 20 69 74 20 72 65 74  ue before it ret
1aaa0 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  urns..**.** {F13
1aab0 35 34 35 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f  545} In calls to
1aac0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
1aad0 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c  lob(S,N,V,L,D)],
1aae0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
1aaf0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
1ab00 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 20 6f 72 0a  S,N,V,L,D)], or.
1ab10 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
1ab20 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
1ab30 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 77 68 65  (S,N,V,L,D)] whe
1ab40 6e 20 44 20 69 73 20 61 20 70 6f 69 6e 74 65 72  n D is a pointer
1ab50 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   to.**          
1ab60 61 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51 4c 69  a function, SQLi
1ab70 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 61 74 20  te invokes that 
1ab80 66 75 6e 63 74 69 6f 6e 20 74 6f 20 64 65 73 74  function to dest
1ab90 72 6f 79 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  roy the.**      
1aba0 20 20 20 20 56 20 76 61 6c 75 65 20 61 66 74 65      V value afte
1abb0 72 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65  r it has finishe
1abc0 64 20 75 73 69 6e 67 20 74 68 65 20 56 20 76 61  d using the V va
1abd0 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35  lue..**.** {F135
1abe0 34 38 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20  48} In calls to 
1abf0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65  [sqlite3_bind_ze
1ac00 72 6f 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 29 5d  roblob(S,N,V,L)]
1ac10 20 74 68 65 20 76 61 6c 75 65 20 62 6f 75 6e 64   the value bound
1ac20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20  .**          is 
1ac30 61 20 62 6c 6f 62 20 6f 66 20 4c 20 62 79 74 65  a blob of L byte
1ac40 73 2c 20 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e  s, or a zero-len
1ac50 67 74 68 20 62 6c 6f 62 20 69 66 20 4c 20 69 73  gth blob if L is
1ac60 20 6e 65 67 61 74 69 76 65 2e 0a 2a 2f 0a 69 6e   negative..*/.in
1ac70 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62  t sqlite3_bind_b
1ac80 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lob(sqlite3_stmt
1ac90 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f  *, int, const vo
1aca0 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64  id*, int n, void
1acb0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74  (*)(void*));.int
1acc0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f   sqlite3_bind_do
1acd0 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  uble(sqlite3_stm
1ace0 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29  t*, int, double)
1acf0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
1ad00 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73  nd_int(sqlite3_s
1ad10 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b  tmt*, int, int);
1ad20 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
1ad30 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  d_int64(sqlite3_
1ad40 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69  stmt*, int, sqli
1ad50 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20  te3_int64);.int 
1ad60 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c  sqlite3_bind_nul
1ad70 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  l(sqlite3_stmt*,
1ad80 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74   int);.int sqlit
1ad90 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c  e3_bind_text(sql
1ada0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
1adb0 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e   const char*, in
1adc0 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  t n, void(*)(voi
1add0 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  d*));.int sqlite
1ade0 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71  3_bind_text16(sq
1adf0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
1ae00 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
1ae10 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  nt, void(*)(void
1ae20 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  *));.int sqlite3
1ae30 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69  _bind_value(sqli
1ae40 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
1ae50 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61  const sqlite3_va
1ae60 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
1ae70 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62  e3_bind_zeroblob
1ae80 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
1ae90 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a  int, int n);../*
1aea0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75  .** CAPI3REF: Nu
1aeb0 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61  mber Of SQL Para
1aec0 6d 65 74 65 72 73 20 7b 46 31 33 36 30 30 7d 0a  meters {F13600}.
1aed0 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
1aee0 6e 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  ne can be used t
1aef0 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65  o find the numbe
1af00 72 20 6f 66 20 53 51 4c 20 70 61 72 61 6d 65 74  r of SQL paramet
1af10 65 72 73 0a 2a 2a 20 69 6e 20 61 20 70 72 65 70  ers.** in a prep
1af20 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 2e 20  ared statement. 
1af30 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20   SQL parameters 
1af40 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68  are tokens of th
1af50 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22  e.** form "?", "
1af60 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22  ?NNN", ":AAA", "
1af70 24 41 41 41 22 2c 20 6f 72 20 22 40 41 41 41 22  $AAA", or "@AAA"
1af80 20 74 68 61 74 20 73 65 72 76 65 20 61 73 0a 2a   that serve as.*
1af90 2a 20 70 6c 61 63 65 2d 68 6f 6c 64 65 72 73 20  * place-holders 
1afa0 66 6f 72 20 76 61 6c 75 65 73 20 74 68 61 74 20  for values that 
1afb0 61 72 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  are [sqlite3_bin
1afc0 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a  d_blob | bound].
1afd0 2a 2a 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65  ** to the parame
1afe0 74 65 72 73 20 61 74 20 61 20 6c 61 74 65 72 20  ters at a later 
1aff0 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  time..**.** This
1b000 20 72 6f 75 74 69 6e 65 20 61 63 74 75 61 6c 6c   routine actuall
1b010 79 20 72 65 74 75 72 6e 73 20 74 68 65 20 69 6e  y returns the in
1b020 64 65 78 20 6f 66 20 74 68 65 20 6c 61 72 67 65  dex of the large
1b030 73 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  st parameter..**
1b040 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65   For all forms e
1b050 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73  xcept ?NNN, this
1b060 20 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64   will correspond
1b070 20 74 6f 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   to the number o
1b080 66 0a 2a 2a 20 75 6e 69 71 75 65 20 70 61 72 61  f.** unique para
1b090 6d 65 74 65 72 73 2e 20 20 49 66 20 70 61 72 61  meters.  If para
1b0a0 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 3f 4e  meters of the ?N
1b0b0 4e 4e 20 61 72 65 20 75 73 65 64 2c 20 74 68 65  NN are used, the
1b0c0 72 65 20 6d 61 79 0a 2a 2a 20 62 65 20 67 61 70  re may.** be gap
1b0d0 73 20 69 6e 20 74 68 65 20 6c 69 73 74 2e 0a 2a  s in the list..*
1b0e0 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
1b0f0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
1b100 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
1b110 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
1b120 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
1b130 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  me()], and.** [s
1b140 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
1b150 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
1b160 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
1b170 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 36 30 31 7d  :.**.** {F13601}
1b180 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   The [sqlite3_bi
1b190 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
1b1a0 6e 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65  nt(S)] interface
1b1b0 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20   returns.**     
1b1c0 20 20 20 20 20 74 68 65 20 6c 61 72 67 65 73 74       the largest
1b1d0 20 69 6e 64 65 78 20 6f 66 20 61 6c 6c 20 53 51   index of all SQ
1b1e0 4c 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20  L parameters in 
1b1f0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
1b200 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
1b210 65 6e 74 5d 20 53 2c 20 6f 72 20 30 20 69 66 20  ent] S, or 0 if 
1b220 53 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f  S.**          co
1b230 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 70 61  ntains no SQL pa
1b240 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 69 6e 74  rameters..*/.int
1b250 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61   sqlite3_bind_pa
1b260 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73 71  rameter_count(sq
1b270 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
1b280 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
1b290 61 6d 65 20 4f 66 20 41 20 48 6f 73 74 20 50 61  ame Of A Host Pa
1b2a0 72 61 6d 65 74 65 72 20 7b 46 31 33 36 32 30 7d  rameter {F13620}
1b2b0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
1b2c0 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ine returns a po
1b2d0 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6e 61 6d  inter to the nam
1b2e0 65 20 6f 66 20 74 68 65 20 6e 2d 74 68 0a 2a 2a  e of the n-th.**
1b2f0 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69   SQL parameter i
1b300 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  n a [prepared st
1b310 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 53 51 4c  atement]..** SQL
1b320 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74   parameters of t
1b330 68 65 20 66 6f 72 6d 20 22 3a 41 41 41 22 20 6f  he form ":AAA" o
1b340 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41  r "@AAA" or "$AA
1b350 41 22 20 68 61 76 65 20 61 20 6e 61 6d 65 0a 2a  A" have a name.*
1b360 2a 20 77 68 69 63 68 20 69 73 20 74 68 65 20 73  * which is the s
1b370 74 72 69 6e 67 20 22 3a 41 41 41 22 20 6f 72 20  tring ":AAA" or 
1b380 22 40 41 41 41 22 20 6f 72 20 22 24 56 56 56 22  "@AAA" or "$VVV"
1b390 2e 20 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77  . .** In other w
1b3a0 6f 72 64 73 2c 20 74 68 65 20 69 6e 69 74 69 61  ords, the initia
1b3b0 6c 20 22 3a 22 20 6f 72 20 22 24 22 20 6f 72 20  l ":" or "$" or 
1b3c0 22 40 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64  "@".** is includ
1b3d0 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68  ed as part of th
1b3e0 65 20 6e 61 6d 65 2e 0a 2a 2a 20 50 61 72 61 6d  e name..** Param
1b3f0 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72  eters of the for
1b400 6d 20 22 3f 22 20 6f 72 20 22 3f 4e 4e 4e 22 20  m "?" or "?NNN" 
1b410 68 61 76 65 20 6e 6f 20 6e 61 6d 65 2e 0a 2a 2a  have no name..**
1b420 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 68 6f  .** The first ho
1b430 73 74 20 70 61 72 61 6d 65 74 65 72 20 68 61 73  st parameter has
1b440 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20   an index of 1, 
1b450 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  not 0..**.** If 
1b460 74 68 65 20 76 61 6c 75 65 20 6e 20 69 73 20 6f  the value n is o
1b470 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 69  ut of range or i
1b480 66 20 74 68 65 20 6e 2d 74 68 20 70 61 72 61 6d  f the n-th param
1b490 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c  eter is.** namel
1b4a0 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69  ess, then NULL i
1b4b0 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65  s returned.  The
1b4c0 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
1b4d0 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e   is.** always in
1b4e0 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64   the UTF-8 encod
1b4f0 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20  ing even if the 
1b500 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20  named parameter 
1b510 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c  was.** originall
1b520 79 20 73 70 65 63 69 66 69 65 64 20 61 73 20 55  y specified as U
1b530 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65  TF-16 in [sqlite
1b540 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 6f  3_prepare16()] o
1b550 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  r.** [sqlite3_pr
1b560 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a  epare16_v2()]..*
1b570 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
1b580 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
1b590 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
1b5a0 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
1b5b0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
1b5c0 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  unt()], and.** [
1b5d0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
1b5e0 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e  ameter_index()].
1b5f0 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
1b600 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 36 32 31  S:.**.** {F13621
1b610 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  } The [sqlite3_b
1b620 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
1b630 6d 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61  me(S,N)] interfa
1b640 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20  ce returns.**   
1b650 20 20 20 20 20 20 20 61 20 55 54 46 2d 38 20 72         a UTF-8 r
1b660 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20  endering of the 
1b670 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20  name of the SQL 
1b680 70 61 72 61 6d 65 74 65 72 20 69 6e 0a 2a 2a 20  parameter in.** 
1b690 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72           [prepar
1b6a0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
1b6b0 68 61 76 69 6e 67 20 69 6e 64 65 78 20 4e 2c 20  having index N, 
1b6c0 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e  or.**          N
1b6d0 55 4c 4c 20 69 66 20 74 68 65 72 65 20 69 73 20  ULL if there is 
1b6e0 6e 6f 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  no SQL parameter
1b6f0 20 77 69 74 68 20 69 6e 64 65 78 20 4e 20 6f 72   with index N or
1b700 20 69 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   if the.**      
1b710 20 20 20 20 70 61 72 61 6d 65 74 65 72 20 77 69      parameter wi
1b720 74 68 20 69 6e 64 65 78 20 4e 20 69 73 20 61 6e  th index N is an
1b730 20 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d   anonymous param
1b740 65 74 65 72 20 22 3f 22 20 6f 72 0a 2a 2a 20 20  eter "?" or.**  
1b750 20 20 20 20 20 20 20 20 61 20 6e 75 6d 62 65 72          a number
1b760 65 64 20 70 61 72 61 6d 65 74 65 72 20 22 3f 4e  ed parameter "?N
1b770 4e 4e 22 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  NN"..*/.const ch
1b780 61 72 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64  ar *sqlite3_bind
1b790 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
1b7a0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
1b7b0 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
1b7c0 33 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 20 41  3REF: Index Of A
1b7d0 20 50 61 72 61 6d 65 74 65 72 20 57 69 74 68 20   Parameter With 
1b7e0 41 20 47 69 76 65 6e 20 4e 61 6d 65 20 7b 46 31  A Given Name {F1
1b7f0 33 36 34 30 7d 0a 2a 2a 0a 2a 2a 20 52 65 74 75  3640}.**.** Retu
1b800 72 6e 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20  rn the index of 
1b810 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  an SQL parameter
1b820 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e   given its name.
1b830 20 20 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76    The.** index v
1b840 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 73  alue returned is
1b850 20 73 75 69 74 61 62 6c 65 20 66 6f 72 20 75 73   suitable for us
1b860 65 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a  e as the second.
1b870 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  ** parameter to 
1b880 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
1b890 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28  ob|sqlite3_bind(
1b8a0 29 5d 2e 20 20 41 20 7a 65 72 6f 0a 2a 2a 20 69  )].  A zero.** i
1b8b0 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f  s returned if no
1b8c0 20 6d 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65   matching parame
1b8d0 74 65 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 54  ter is found.  T
1b8e0 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  he parameter.** 
1b8f0 6e 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76  name must be giv
1b900 65 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e  en in UTF-8 even
1b910 20 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c   if the original
1b920 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61   statement.** wa
1b930 73 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20  s prepared from 
1b940 55 54 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e  UTF-16 text usin
1b950 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  g [sqlite3_prepa
1b960 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a  re16_v2()]..**.*
1b970 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
1b980 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
1b990 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a  qlite3_bind()],.
1b9a0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
1b9b0 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
1b9c0 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
1b9d0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
1b9e0 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a  ter_index()]..**
1b9f0 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
1ba00 2a 2a 0a 2a 2a 20 7b 46 31 33 36 34 31 7d 20 54  **.** {F13641} T
1ba10 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  he [sqlite3_bind
1ba20 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
1ba30 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  (S,N)] interface
1ba40 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20   returns.**     
1ba50 20 20 20 20 20 74 68 65 20 69 6e 64 65 78 20 6f       the index o
1ba60 66 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  f SQL parameter 
1ba70 69 6e 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  in [prepared sta
1ba80 74 65 6d 65 6e 74 5d 0a 2a 2a 20 20 20 20 20 20  tement].**      
1ba90 20 20 20 20 53 20 77 68 6f 73 65 20 6e 61 6d 65      S whose name
1baa0 20 6d 61 74 63 68 65 73 20 74 68 65 20 55 54 46   matches the UTF
1bab0 2d 38 20 73 74 72 69 6e 67 20 4e 2c 20 6f 72 20  -8 string N, or 
1bac0 30 20 69 66 20 74 68 65 72 65 20 69 73 0a 2a 2a  0 if there is.**
1bad0 20 20 20 20 20 20 20 20 20 20 6e 6f 20 6d 61 74            no mat
1bae0 63 68 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ch..*/.int sqlit
1baf0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
1bb00 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f  r_index(sqlite3_
1bb10 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61  stmt*, const cha
1bb20 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a  r *zName);../*.*
1bb30 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65  * CAPI3REF: Rese
1bb40 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f  t All Bindings O
1bb50 6e 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  n A Prepared Sta
1bb60 74 65 6d 65 6e 74 20 7b 46 31 33 36 36 30 7d 0a  tement {F13660}.
1bb70 2a 2a 0a 2a 2a 20 43 6f 6e 74 72 61 72 79 20 74  **.** Contrary t
1bb80 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20  o the intuition 
1bb90 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65  of many, [sqlite
1bba0 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20  3_reset()] does 
1bbb0 6e 6f 74 0a 2a 2a 20 72 65 73 65 74 20 74 68 65  not.** reset the
1bbc0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
1bbd0 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20  lob | bindings] 
1bbe0 6f 6e 20 61 20 0a 2a 2a 20 5b 70 72 65 70 61 72  on a .** [prepar
1bbf0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20  ed statement].  
1bc00 55 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  Use this routine
1bc10 20 74 6f 0a 2a 2a 20 72 65 73 65 74 20 61 6c 6c   to.** reset all
1bc20 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73   host parameters
1bc30 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   to NULL..**.** 
1bc40 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
1bc50 2a 20 7b 46 31 33 36 36 31 7d 20 54 68 65 20 5b  * {F13661} The [
1bc60 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69  sqlite3_clear_bi
1bc70 6e 64 69 6e 67 73 28 53 29 5d 20 69 6e 74 65 72  ndings(S)] inter
1bc80 66 61 63 65 20 72 65 73 65 74 73 20 61 6c 6c 0a  face resets all.
1bc90 2a 2a 20 20 20 20 20 20 20 20 20 20 53 51 4c 20  **          SQL 
1bca0 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e  parameter bindin
1bcb0 67 73 20 69 6e 20 5b 70 72 65 70 61 72 65 64 20  gs in [prepared 
1bcc0 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20  statement] S.** 
1bcd0 20 20 20 20 20 20 20 20 20 62 61 63 6b 20 74 6f           back to
1bce0 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71   NULL..*/.int sq
1bcf0 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64  lite3_clear_bind
1bd00 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d  ings(sqlite3_stm
1bd10 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
1bd20 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20  3REF: Number Of 
1bd30 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73  Columns In A Res
1bd40 75 6c 74 20 53 65 74 20 7b 46 31 33 37 31 30 7d  ult Set {F13710}
1bd50 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 74 68  .**.** Return th
1bd60 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
1bd70 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c  mns in the resul
1bd80 74 20 73 65 74 20 72 65 74 75 72 6e 65 64 20 62  t set returned b
1bd90 79 20 74 68 65 20 0a 2a 2a 20 5b 70 72 65 70 61  y the .** [prepa
1bda0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20  red statement]. 
1bdb0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  This routine ret
1bdc0 75 72 6e 73 20 30 0a 2a 2a 20 69 66 20 70 53 74  urns 0.** if pSt
1bdd0 6d 74 20 69 73 20 61 6e 20 53 51 4c 20 73 74 61  mt is an SQL sta
1bde0 74 65 6d 65 6e 74 20 74 68 61 74 20 64 6f 65 73  tement that does
1bdf0 20 6e 6f 74 20 72 65 74 75 72 6e 20 64 61 74 61   not return data
1be00 20 28 66 6f 72 20 0a 2a 2a 20 65 78 61 6d 70 6c   (for .** exampl
1be10 65 20 61 6e 20 55 50 44 41 54 45 29 2e 0a 2a 2a  e an UPDATE)..**
1be20 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
1be30 2a 2a 0a 2a 2a 20 7b 46 31 33 37 31 31 7d 20 54  **.** {F13711} T
1be40 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
1be50 6d 6e 5f 63 6f 75 6e 74 28 53 29 5d 20 69 6e 74  mn_count(S)] int
1be60 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
1be70 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
1be80 20 20 20 20 20 20 20 20 20 63 6f 6c 75 6d 6e 73           columns
1be90 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73   in the result s
1bea0 65 74 20 67 65 6e 65 72 61 74 65 64 20 62 79 20  et generated by 
1beb0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
1bec0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
1bed0 65 6e 74 5d 20 53 2c 20 6f 72 20 30 20 69 66 20  ent] S, or 0 if 
1bee0 53 20 64 6f 65 73 20 6e 6f 74 20 67 65 6e 65 72  S does not gener
1bef0 61 74 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ate.**          
1bf00 61 20 72 65 73 75 6c 74 20 73 65 74 2e 0a 2a 2f  a result set..*/
1bf10 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
1bf20 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  umn_count(sqlite
1bf30 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
1bf40 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1bf50 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e   Column Names In
1bf60 20 41 20 52 65 73 75 6c 74 20 53 65 74 20 7b 46   A Result Set {F
1bf70 31 33 37 32 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  13720}.**.** The
1bf80 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
1bf90 72 6e 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69  rn the name assi
1bfa0 67 6e 65 64 20 74 6f 20 61 20 70 61 72 74 69 63  gned to a partic
1bfb0 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69  ular column.** i
1bfc0 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  n the result set
1bfd0 20 6f 66 20 61 20 53 45 4c 45 43 54 20 73 74 61   of a SELECT sta
1bfe0 74 65 6d 65 6e 74 2e 20 20 54 68 65 20 73 71 6c  tement.  The sql
1bff0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
1c000 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ().** interface 
1c010 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
1c020 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d  r to a zero-term
1c030 69 6e 61 74 65 64 20 55 54 46 38 20 73 74 72 69  inated UTF8 stri
1c040 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65  ng.** and sqlite
1c050 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
1c060 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  ) returns a poin
1c070 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65  ter to a zero-te
1c080 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 31  rminated.** UTF1
1c090 36 20 73 74 72 69 6e 67 2e 20 20 54 68 65 20 66  6 string.  The f
1c0a0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
1c0b0 73 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  s the.** [prepar
1c0c0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
1c0d0 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68  at implements th
1c0e0 65 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65  e SELECT stateme
1c0f0 6e 74 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  nt..** The secon
1c100 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  d parameter is t
1c110 68 65 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72  he column number
1c120 2e 20 20 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74  .  The left-most
1c130 20 63 6f 6c 75 6d 6e 20 69 73 0a 2a 2a 20 6e 75   column is.** nu
1c140 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 54 68  mber 0..**.** Th
1c150 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
1c160 67 20 70 6f 69 6e 74 65 72 20 69 73 20 76 61 6c  g pointer is val
1c170 69 64 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20  id until either 
1c180 74 68 65 20 0a 2a 2a 20 5b 70 72 65 70 61 72 65  the .** [prepare
1c190 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20  d statement] is 
1c1a0 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71  destroyed by [sq
1c1b0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
1c1c0 5d 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68  ].** or until th
1c1d0 65 20 6e 65 78 74 20 63 61 6c 6c 20 73 71 6c 69  e next call sqli
1c1e0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
1c1f0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ) or sqlite3_col
1c200 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 0a 2a 2a 20  umn_name16().** 
1c210 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75  on the same colu
1c220 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 73 71 6c  mn..**.** If sql
1c230 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61  ite3_malloc() fa
1c240 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20 70  ils during the p
1c250 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74  rocessing of eit
1c260 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28  her routine.** (
1c270 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69  for example duri
1c280 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20  ng a conversion 
1c290 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54  from UTF-8 to UT
1c2a0 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20  F-16) then a.** 
1c2b0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20  NULL pointer is 
1c2c0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
1c2d0 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65  The name of a re
1c2e0 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74  sult column is t
1c2f0 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
1c300 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a  "AS" clause for.
1c310 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20  ** that column, 
1c320 69 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 41  if there is an A
1c330 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68  S clause.  If th
1c340 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61  ere is no AS cla
1c350 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  use.** then the 
1c360 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75  name of the colu
1c370 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69 65  mn is unspecifie
1c380 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65  d and may change
1c390 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c   from.** one rel
1c3a0 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74  ease of SQLite t
1c3b0 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2a 0a 2a  o the next..**.*
1c3c0 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
1c3d0 0a 2a 2a 20 7b 46 31 33 37 32 31 7d 20 41 20 73  .** {F13721} A s
1c3e0 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61  uccessful invoca
1c3f0 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c  tion of the [sql
1c400 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
1c410 28 53 2c 4e 29 5d 0a 2a 2a 20 20 20 20 20 20 20  (S,N)].**       
1c420 20 20 20 69 6e 74 65 72 66 61 63 65 20 72 65 74     interface ret
1c430 75 72 6e 73 20 74 68 65 20 6e 61 6d 65 0a 2a 2a  urns the name.**
1c440 20 20 20 20 20 20 20 20 20 20 6f 66 20 74 68 65            of the
1c450 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 28 77 68 65   Nth column (whe
1c460 72 65 20 30 20 69 73 20 74 68 65 20 6c 65 66 74  re 0 is the left
1c470 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 29 20 66 6f  -most column) fo
1c480 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  r the.**        
1c490 20 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20    result set of 
1c4a0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
1c4b0 65 6e 74 5d 20 53 20 61 73 20 61 0a 2a 2a 20 20  ent] S as a.**  
1c4c0 20 20 20 20 20 20 20 20 7a 65 72 6f 2d 74 65 72          zero-ter
1c4d0 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74  minated UTF-8 st
1c4e0 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  ring..**.** {F13
1c4f0 37 32 33 7d 20 41 20 73 75 63 63 65 73 73 66 75  723} A successfu
1c500 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20  l invocation of 
1c510 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  the [sqlite3_col
1c520 75 6d 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d  umn_name16(S,N)]
1c530 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74  .**          int
1c540 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
1c550 68 65 20 6e 61 6d 65 0a 2a 2a 20 20 20 20 20 20  he name.**      
1c560 20 20 20 20 6f 66 20 74 68 65 20 4e 74 68 20 63      of the Nth c
1c570 6f 6c 75 6d 6e 20 28 77 68 65 72 65 20 30 20 69  olumn (where 0 i
1c580 73 20 74 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20  s the left-most 
1c590 63 6f 6c 75 6d 6e 29 20 66 6f 72 20 74 68 65 0a  column) for the.
1c5a0 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 73 75  **          resu
1c5b0 6c 74 20 73 65 74 20 6f 66 20 5b 70 72 65 70 61  lt set of [prepa
1c5c0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
1c5d0 20 61 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20   as a.**        
1c5e0 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65    zero-terminate
1c5f0 64 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20  d UTF-16 string 
1c600 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79  in the native by
1c610 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20  te order..**.** 
1c620 7b 46 31 33 37 32 34 7d 20 54 68 65 20 5b 73 71  {F13724} The [sq
1c630 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
1c640 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
1c650 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
1c660 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  )].**          i
1c670 6e 74 65 72 66 61 63 65 73 20 72 65 74 75 72 6e  nterfaces return
1c680 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
1c690 69 66 20 74 68 65 79 20 61 72 65 20 75 6e 61 62  if they are unab
1c6a0 6c 65 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20  le to.**        
1c6b0 20 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72    allocate memor
1c6c0 79 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64  y memory to hold
1c6d0 20 74 68 65 72 65 20 6e 6f 72 6d 61 6c 20 72 65   there normal re
1c6e0 74 75 72 6e 20 73 74 72 69 6e 67 73 2e 0a 2a 2a  turn strings..**
1c6f0 0a 2a 2a 20 7b 46 31 33 37 32 35 7d 20 49 66 20  .** {F13725} If 
1c700 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20  the N parameter 
1c710 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  to [sqlite3_colu
1c720 6d 6e 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 6f 72  mn_name(S,N)] or
1c730 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
1c740 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
1c750 65 31 36 28 53 2c 4e 29 5d 20 69 73 20 6f 75 74  e16(S,N)] is out
1c760 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 6e 20   of range, then 
1c770 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
1c780 69 6e 74 65 72 66 61 63 65 73 20 72 65 74 75 72  interfaces retur
1c790 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ns a NULL pointe
1c7a0 72 2e 0a 2a 2a 20 0a 2a 2a 20 7b 46 31 33 37 32  r..** .** {F1372
1c7b0 36 7d 20 54 68 65 20 73 74 72 69 6e 67 73 20 72  6} The strings r
1c7c0 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
1c7d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
1c7e0 53 2c 4e 29 5d 20 61 6e 64 0a 2a 2a 20 20 20 20  S,N)] and.**    
1c7f0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63        [sqlite3_c
1c800 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e  olumn_name16(S,N
1c810 29 5d 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74  )] are valid unt
1c820 69 6c 20 74 68 65 20 6e 65 78 74 0a 2a 2a 20 20  il the next.**  
1c830 20 20 20 20 20 20 20 20 63 61 6c 6c 20 74 6f 20          call to 
1c840 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65 20 77  either routine w
1c850 69 74 68 20 74 68 65 20 73 61 6d 65 20 53 20 61  ith the same S a
1c860 6e 64 20 4e 20 70 61 72 61 6d 65 74 65 72 73 0a  nd N parameters.
1c870 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 75  **          or u
1c880 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69  ntil [sqlite3_fi
1c890 6e 61 6c 69 7a 65 28 53 29 5d 20 69 73 20 63 61  nalize(S)] is ca
1c8a0 6c 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  lled..**.** {F13
1c8b0 37 32 37 7d 20 57 68 65 6e 20 61 20 72 65 73 75  727} When a resu
1c8c0 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 61 20 5b  lt column of a [
1c8d0 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
1c8e0 74 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 20 20  t contains.**   
1c8f0 20 20 20 20 20 20 20 61 6e 20 41 53 20 63 6c 61         an AS cla
1c900 75 73 65 2c 20 74 68 65 20 6e 61 6d 65 20 6f 66  use, the name of
1c910 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20   that column is 
1c920 74 68 65 20 69 6e 64 65 6e 74 69 66 69 65 72 0a  the indentifier.
1c930 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 74  **          to t
1c940 68 65 20 72 69 67 68 74 20 6f 66 20 74 68 65 20  he right of the 
1c950 41 53 20 6b 65 79 77 6f 72 64 2e 0a 2a 2f 0a 63  AS keyword..*/.c
1c960 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
1c970 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73  e3_column_name(s
1c980 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
1c990 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  t N);.const void
1c9a0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
1c9b0 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
1c9c0 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a  stmt*, int N);..
1c9d0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1c9e0 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20 49  Source Of Data I
1c9f0 6e 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74  n A Query Result
1ca00 20 7b 46 31 33 37 34 30 7d 0a 2a 2a 0a 2a 2a 20   {F13740}.**.** 
1ca10 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 70  These routines p
1ca20 72 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20 74  rovide a means t
1ca30 6f 20 64 65 74 65 72 6d 69 6e 65 20 77 68 61 74  o determine what
1ca40 20 63 6f 6c 75 6d 6e 20 6f 66 20 77 68 61 74 0a   column of what.
1ca50 2a 2a 20 74 61 62 6c 65 20 69 6e 20 77 68 69 63  ** table in whic
1ca60 68 20 64 61 74 61 62 61 73 65 20 61 20 72 65 73  h database a res
1ca70 75 6c 74 20 6f 66 20 61 20 53 45 4c 45 43 54 20  ult of a SELECT 
1ca80 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 65 73 20  statement comes 
1ca90 66 72 6f 6d 2e 0a 2a 2a 20 54 68 65 20 6e 61 6d  from..** The nam
1caa0 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  e of the databas
1cab0 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 6f  e or table or co
1cac0 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 75  lumn can be retu
1cad0 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 65  rned as.** eithe
1cae0 72 20 61 20 55 54 46 38 20 6f 72 20 55 54 46 31  r a UTF8 or UTF1
1caf0 36 20 73 74 72 69 6e 67 2e 20 20 54 68 65 20 5f  6 string.  The _
1cb00 64 61 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e  database_ routin
1cb10 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65  es return.** the
1cb20 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20   database name, 
1cb30 74 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74  the _table_ rout
1cb40 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20  ines return the 
1cb50 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a  table name, and.
1cb60 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72  ** the origin_ r
1cb70 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74  outines return t
1cb80 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a  he column name..
1cb90 2a 2a 20 54 68 65 20 72 65 74 75 72 6e 65 64 20  ** The returned 
1cba0 73 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20  string is valid 
1cbb0 75 6e 74 69 6c 0a 2a 2a 20 74 68 65 20 5b 70 72  until.** the [pr
1cbc0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1cbd0 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64 20 75  ] is destroyed u
1cbe0 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
1cbf0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20  _finalize()] or 
1cc00 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69  until the same i
1cc10 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65  nformation is re
1cc20 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e  quested.** again
1cc30 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20   in a different 
1cc40 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  encoding..**.** 
1cc50 54 68 65 20 6e 61 6d 65 73 20 72 65 74 75 72 6e  The names return
1cc60 65 64 20 61 72 65 20 74 68 65 20 6f 72 69 67 69  ed are the origi
1cc70 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e  nal un-aliased n
1cc80 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64  ames of the.** d
1cc90 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20  atabase, table, 
1cca0 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a  and column..**.*
1ccb0 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
1ccc0 6d 65 6e 74 20 74 6f 20 74 68 65 20 66 6f 6c 6c  ment to the foll
1ccd0 6f 77 69 6e 67 20 63 61 6c 6c 73 20 69 73 20 61  owing calls is a
1cce0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1ccf0 6d 65 6e 74 5d 2e 0a 2a 2a 20 54 68 65 73 65 20  ment]..** These 
1cd00 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
1cd10 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   information abo
1cd20 75 74 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  ut the Nth colum
1cd30 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20 0a 2a  n returned by .*
1cd40 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c  * the statement,
1cd50 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20   where N is the 
1cd60 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20  second function 
1cd70 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
1cd80 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  If the Nth colum
1cd90 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  n returned by th
1cda0 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
1cdb0 6e 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20  n expression.** 
1cdc0 6f 72 20 73 75 62 71 75 65 72 79 20 61 6e 64 20  or subquery and 
1cdd0 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20  is not a column 
1cde0 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20  value, then all 
1cdf0 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  of these functio
1ce00 6e 73 0a 2a 2a 20 72 65 74 75 72 6e 20 4e 55 4c  ns.** return NUL
1ce10 4c 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e  L.  These routin
1ce20 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 72 65 74  e might also ret
1ce30 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65  urn NULL if a me
1ce40 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69  mory.** allocati
1ce50 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e  on error occurs.
1ce60 20 20 4f 74 68 65 72 77 69 73 65 2c 20 74 68 65    Otherwise, the
1ce70 79 20 72 65 74 75 72 6e 20 74 68 65 20 0a 2a 2a  y return the .**
1ce80 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74   name of the att
1ce90 61 63 68 65 64 20 64 61 74 61 62 61 73 65 2c 20  ached database, 
1cea0 74 61 62 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e  table and column
1ceb0 20 74 68 61 74 20 71 75 65 72 79 20 72 65 73 75   that query resu
1cec0 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 77 61 73  lt.** column was
1ced0 20 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e   extracted from.
1cee0 0a 2a 2a 0a 2a 2a 20 41 73 20 77 69 74 68 20 61  .**.** As with a
1cef0 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ll other SQLite 
1cf00 41 50 49 73 2c 20 74 68 6f 73 65 20 70 6f 73 74  APIs, those post
1cf10 66 69 78 65 64 20 77 69 74 68 20 22 31 36 22 20  fixed with "16" 
1cf20 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36  return.** UTF-16
1cf30 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 73   encoded strings
1cf40 2c 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e 63  , the other func
1cf50 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 46  tions return UTF
1cf60 2d 38 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20  -8. {END}.**.** 
1cf70 54 68 65 73 65 20 41 50 49 73 20 61 72 65 20 6f  These APIs are o
1cf80 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66  nly available if
1cf90 20 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 73   the library was
1cfa0 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74   compiled with t
1cfb0 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 45 4e  he .** SQLITE_EN
1cfc0 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41  ABLE_COLUMN_META
1cfd0 44 41 54 41 20 70 72 65 70 72 6f 63 65 73 73 6f  DATA preprocesso
1cfe0 72 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64  r symbol defined
1cff0 2e 0a 2a 2a 0a 2a 2a 20 7b 55 31 33 37 35 31 7d  ..**.** {U13751}
1d000 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f  .** If two or mo
1d010 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20  re threads call 
1d020 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74  one or more of t
1d030 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 67  hese routines ag
1d040 61 69 6e 73 74 20 74 68 65 20 73 61 6d 65 0a 2a  ainst the same.*
1d050 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  * prepared state
1d060 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20  ment and column 
1d070 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
1d080 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
1d090 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e  s are.** undefin
1d0a0 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  ed..**.** INVARI
1d0b0 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  ANTS:.**.** {F13
1d0c0 37 34 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  741} The [sqlite
1d0d0 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73  3_column_databas
1d0e0 65 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 69 6e 74  e_name(S,N)] int
1d0f0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 65  erface returns e
1d100 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  ither.**        
1d110 20 20 74 68 65 20 55 54 46 2d 38 20 7a 65 72 6f    the UTF-8 zero
1d120 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65  -terminated name
1d130 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
1d140 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20   from which the 
1d150 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68  .**          Nth
1d160 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f   result column o
1d170 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  f [prepared stat
1d180 65 6d 65 6e 74 5d 20 53 20 0a 2a 2a 20 20 20 20  ement] S .**    
1d190 20 20 20 20 20 20 69 73 20 65 78 74 72 61 63 74        is extract
1d1a0 65 64 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74  ed, or NULL if t
1d1b0 68 65 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  he the Nth colum
1d1c0 6e 20 6f 66 20 53 20 69 73 20 61 0a 2a 2a 20 20  n of S is a.**  
1d1d0 20 20 20 20 20 20 20 20 67 65 6e 65 72 61 6c 20          general 
1d1e0 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 69 66  expression or if
1d1f0 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
1d200 61 74 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20  ate memory.**   
1d210 20 20 20 20 20 20 20 74 6f 20 73 74 6f 72 65 20         to store 
1d220 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 20 20 20 20  the name..**    
1d230 20 20 20 20 20 20 0a 2a 2a 20 7b 46 31 33 37 34        .** {F1374
1d240 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  2} The [sqlite3_
1d250 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
1d260 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20 69 6e 74  name16(S,N)] int
1d270 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 65  erface returns e
1d280 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  ither.**        
1d290 20 20 74 68 65 20 55 54 46 2d 31 36 20 6e 61 74    the UTF-16 nat
1d2a0 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 0a 2a  ive byte order.*
1d2b0 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 2d  *          zero-
1d2c0 74 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20  terminated name 
1d2d0 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
1d2e0 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20 0a  from which the .
1d2f0 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20  **          Nth 
1d300 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66  result column of
1d310 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1d320 6d 65 6e 74 5d 20 53 20 0a 2a 2a 20 20 20 20 20  ment] S .**     
1d330 20 20 20 20 20 69 73 20 65 78 74 72 61 63 74 65       is extracte
1d340 64 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68  d, or NULL if th
1d350 65 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  e the Nth column
1d360 20 6f 66 20 53 20 69 73 20 61 0a 2a 2a 20 20 20   of S is a.**   
1d370 20 20 20 20 20 20 20 67 65 6e 65 72 61 6c 20 65         general e
1d380 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 69 66 20  xpression or if 
1d390 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61  unable to alloca
1d3a0 74 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20 20  te memory.**    
1d3b0 20 20 20 20 20 20 74 6f 20 73 74 6f 72 65 20 74        to store t
1d3c0 68 65 20 6e 61 6d 65 2e 0a 2a 2a 20 20 20 20 20  he name..**     
1d3d0 20 20 20 20 20 0a 2a 2a 20 7b 46 31 33 37 34 33       .** {F13743
1d3e0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
1d3f0 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65  olumn_table_name
1d400 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  (S,N)] interface
1d410 20 72 65 74 75 72 6e 73 20 65 69 74 68 65 72 0a   returns either.
1d420 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
1d430 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69  UTF-8 zero-termi
1d440 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66 20 74 68  nated name of th
1d450 65 20 74 61 62 6c 65 20 66 72 6f 6d 20 77 68 69  e table from whi
1d460 63 68 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 20  ch the .**      
1d470 20 20 20 20 4e 74 68 20 72 65 73 75 6c 74 20 63      Nth result c
1d480 6f 6c 75 6d 6e 20 6f 66 20 5b 70 72 65 70 61 72  olumn of [prepar
1d490 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
1d4a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20  .**          is 
1d4b0 65 78 74 72 61 63 74 65 64 2c 20 6f 72 20 4e 55  extracted, or NU
1d4c0 4c 4c 20 69 66 20 74 68 65 20 74 68 65 20 4e 74  LL if the the Nt
1d4d0 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73  h column of S is
1d4e0 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 67   a.**          g
1d4f0 65 6e 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f  eneral expressio
1d500 6e 20 6f 72 20 69 66 20 75 6e 61 62 6c 65 20 74  n or if unable t
1d510 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72  o allocate memor
1d520 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f  y.**          to
1d530 20 73 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e   store the name.
1d540 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 0a 2a 2a  .**          .**
1d550 20 7b 46 31 33 37 34 34 7d 20 54 68 65 20 5b 73   {F13744} The [s
1d560 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61  qlite3_column_ta
1d570 62 6c 65 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d  ble_name16(S,N)]
1d580 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
1d590 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20  ns either.**    
1d5a0 20 20 20 20 20 20 74 68 65 20 55 54 46 2d 31 36        the UTF-16
1d5b0 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
1d5c0 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a  er.**          z
1d5d0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e  ero-terminated n
1d5e0 61 6d 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65  ame of the table
1d5f0 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20   from which the 
1d600 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68  .**          Nth
1d610 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f   result column o
1d620 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  f [prepared stat
1d630 65 6d 65 6e 74 5d 20 53 20 0a 2a 2a 20 20 20 20  ement] S .**    
1d640 20 20 20 20 20 20 69 73 20 65 78 74 72 61 63 74        is extract
1d650 65 64 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74  ed, or NULL if t
1d660 68 65 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  he the Nth colum
1d670 6e 20 6f 66 20 53 20 69 73 20 61 0a 2a 2a 20 20  n of S is a.**  
1d680 20 20 20 20 20 20 20 20 67 65 6e 65 72 61 6c 20          general 
1d690 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 69 66  expression or if
1d6a0 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
1d6b0 61 74 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20  ate memory.**   
1d6c0 20 20 20 20 20 20 20 74 6f 20 73 74 6f 72 65 20         to store 
1d6d0 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 20 20 20 20  the name..**    
1d6e0 20 20 20 20 20 20 0a 2a 2a 20 7b 46 31 33 37 34        .** {F1374
1d6f0 35 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  5} The [sqlite3_
1d700 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61  column_origin_na
1d710 6d 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61  me(S,N)] interfa
1d720 63 65 20 72 65 74 75 72 6e 73 20 65 69 74 68 65  ce returns eithe
1d730 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  r.**          th
1d740 65 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72  e UTF-8 zero-ter
1d750 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66 20  minated name of 
1d760 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  the table column
1d770 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20   from which the 
1d780 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68  .**          Nth
1d790 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f   result column o
1d7a0 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  f [prepared stat
1d7b0 65 6d 65 6e 74 5d 20 53 20 0a 2a 2a 20 20 20 20  ement] S .**    
1d7c0 20 20 20 20 20 20 69 73 20 65 78 74 72 61 63 74        is extract
1d7d0 65 64 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74  ed, or NULL if t
1d7e0 68 65 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  he the Nth colum
1d7f0 6e 20 6f 66 20 53 20 69 73 20 61 0a 2a 2a 20 20  n of S is a.**  
1d800 20 20 20 20 20 20 20 20 67 65 6e 65 72 61 6c 20          general 
1d810 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 69 66  expression or if
1d820 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
1d830 61 74 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20  ate memory.**   
1d840 20 20 20 20 20 20 20 74 6f 20 73 74 6f 72 65 20         to store 
1d850 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 20 20 20 20  the name..**    
1d860 20 20 20 20 20 20 0a 2a 2a 20 7b 46 31 33 37 34        .** {F1374
1d870 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  6} The [sqlite3_
1d880 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61  column_origin_na
1d890 6d 65 31 36 28 53 2c 4e 29 5d 20 69 6e 74 65 72  me16(S,N)] inter
1d8a0 66 61 63 65 20 72 65 74 75 72 6e 73 20 65 69 74  face returns eit
1d8b0 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  her.**          
1d8c0 74 68 65 20 55 54 46 2d 31 36 20 6e 61 74 69 76  the UTF-16 nativ
1d8d0 65 20 62 79 74 65 20 6f 72 64 65 72 0a 2a 2a 20  e byte order.** 
1d8e0 20 20 20 20 20 20 20 20 20 7a 65 72 6f 2d 74 65           zero-te
1d8f0 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66  rminated name of
1d900 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d   the table colum
1d910 6e 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65  n from which the
1d920 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74   .**          Nt
1d930 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  h result column 
1d940 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  of [prepared sta
1d950 74 65 6d 65 6e 74 5d 20 53 20 0a 2a 2a 20 20 20  tement] S .**   
1d960 20 20 20 20 20 20 20 69 73 20 65 78 74 72 61 63         is extrac
1d970 74 65 64 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20  ted, or NULL if 
1d980 74 68 65 20 74 68 65 20 4e 74 68 20 63 6f 6c 75  the the Nth colu
1d990 6d 6e 20 6f 66 20 53 20 69 73 20 61 0a 2a 2a 20  mn of S is a.** 
1d9a0 20 20 20 20 20 20 20 20 20 67 65 6e 65 72 61 6c           general
1d9b0 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 69   expression or i
1d9c0 66 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f  f unable to allo
1d9d0 63 61 74 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20  cate memory.**  
1d9e0 20 20 20 20 20 20 20 20 74 6f 20 73 74 6f 72 65          to store
1d9f0 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 20 20 20   the name..**   
1da00 20 20 20 20 20 20 20 0a 2a 2a 20 7b 46 31 33 37         .** {F137
1da10 34 38 7d 20 54 68 65 20 72 65 74 75 72 6e 20 76  48} The return v
1da20 61 6c 75 65 73 20 66 72 6f 6d 0a 2a 2a 20 20 20  alues from.**   
1da30 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
1da40 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
1da50 6e 61 6d 65 7c 63 6f 6c 75 6d 6e 20 6d 65 74 61  name|column meta
1da60 64 61 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d  data interfaces]
1da70 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 72 65  .**          are
1da80 20 76 61 6c 69 64 0a 2a 2a 20 20 20 20 20 20 20   valid.**       
1da90 20 20 20 66 6f 72 20 74 68 65 20 6c 69 66 65 74     for the lifet
1daa0 69 6d 65 20 6f 66 20 74 68 65 20 5b 70 72 65 70  ime of the [prep
1dab0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a  ared statement].
1dac0 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 75  **          or u
1dad0 6e 74 69 6c 20 74 68 65 20 65 6e 63 6f 64 69 6e  ntil the encodin
1dae0 67 20 69 73 20 63 68 61 6e 67 65 64 20 62 79 20  g is changed by 
1daf0 61 6e 6f 74 68 65 72 20 6d 65 74 61 64 61 74 61  another metadata
1db00 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74  .**          int
1db10 65 72 66 61 63 65 20 63 61 6c 6c 20 66 6f 72 20  erface call for 
1db20 74 68 65 20 73 61 6d 65 20 70 72 65 70 61 72 65  the same prepare
1db30 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20  d statement and 
1db40 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 4c 49  column..**.** LI
1db50 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a  MITATIONS:.**.**
1db60 20 7b 55 31 33 37 35 31 7d 20 49 66 20 74 77 6f   {U13751} If two
1db70 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73   or more threads
1db80 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72   call one or mor
1db90 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  e.**          [s
1dba0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61  qlite3_column_da
1dbb0 74 61 62 61 73 65 5f 6e 61 6d 65 7c 63 6f 6c 75  tabase_name|colu
1dbc0 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65  mn metadata inte
1dbd0 72 66 61 63 65 73 5d 0a 2a 2a 20 20 20 20 20 20  rfaces].**      
1dbe0 20 20 20 20 74 68 65 20 73 61 6d 65 20 5b 70 72      the same [pr
1dbf0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1dc00 5d 20 61 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c  ] and result col
1dc10 75 6d 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  umn.**          
1dc20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
1dc30 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
1dc40 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
1dc50 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
1dc60 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
1dc70 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c  atabase_name(sql
1dc80 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
1dc90 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
1dca0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61  ite3_column_data
1dcb0 62 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69  base_name16(sqli
1dcc0 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
1dcd0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
1dce0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65  te3_column_table
1dcf0 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
1dd00 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
1dd10 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
1dd20 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31  lumn_table_name1
1dd30 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
1dd40 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72  int);.const char
1dd50 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
1dd60 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c  _origin_name(sql
1dd70 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
1dd80 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *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 31 36 28 73 71 6c 69 74 65  in_name16(sqlite
1ddb0 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f  3_stmt*,int);../
1ddc0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
1ddd0 65 63 6c 61 72 65 64 20 44 61 74 61 74 79 70 65  eclared Datatype
1dde0 20 4f 66 20 41 20 51 75 65 72 79 20 52 65 73 75   Of A Query Resu
1ddf0 6c 74 20 7b 46 31 33 37 36 30 7d 0a 2a 2a 0a 2a  lt {F13760}.**.*
1de00 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61  * The first para
1de10 6d 65 74 65 72 20 69 73 20 61 20 5b 70 72 65 70  meter is a [prep
1de20 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
1de30 20 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61   .** If this sta
1de40 74 65 6d 65 6e 74 20 69 73 20 61 20 53 45 4c 45  tement is a SELE
1de50 43 54 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64  CT statement and
1de60 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
1de70 6f 66 20 74 68 65 20 0a 2a 2a 20 72 65 74 75 72  of the .** retur
1de80 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f  ned result set o
1de90 66 20 74 68 61 74 20 53 45 4c 45 43 54 20 69 73  f that SELECT is
1dea0 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20   a table column 
1deb0 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65  (not an.** expre
1dec0 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72  ssion or subquer
1ded0 79 29 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c  y) then the decl
1dee0 61 72 65 64 20 74 79 70 65 20 6f 66 20 74 68 65  ared type of the
1def0 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e   table.** column
1df00 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 49   is returned.  I
1df10 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  f the Nth column
1df20 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
1df30 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72  et is an.** expr
1df40 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65  ession or subque
1df50 72 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20  ry, then a NULL 
1df60 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72  pointer is retur
1df70 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 72 65 74 75  ned..** The retu
1df80 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 61  rned string is a
1df90 6c 77 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f  lways UTF-8 enco
1dfa0 64 65 64 2e 20 20 7b 45 4e 44 7d 20 0a 2a 2a 20  ded.  {END} .** 
1dfb0 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 6e 20  For example, in 
1dfc0 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68  the database sch
1dfd0 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54  ema:.**.** CREAT
1dfe0 45 20 54 41 42 4c 45 20 74 31 28 63 31 20 56 41  E TABLE t1(c1 VA
1dff0 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 41 6e  RIANT);.**.** An
1e000 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  d the following 
1e010 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c  statement compil
1e020 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54  ed:.**.** SELECT
1e030 20 63 31 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d   c1 + 1, c1 FROM
1e040 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 54 68 65 6e 20   t1;.**.** Then 
1e050 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 6f 75  this routine wou
1e060 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 73 74  ld return the st
1e070 72 69 6e 67 20 22 56 41 52 49 41 4e 54 22 20 66  ring "VARIANT" f
1e080 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a  or the second.**
1e090 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28   result column (
1e0a0 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c  i==1), and a NUL
1e0b0 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68  L pointer for th
1e0c0 65 20 66 69 72 73 74 20 72 65 73 75 6c 74 20 63  e first result c
1e0d0 6f 6c 75 6d 6e 0a 2a 2a 20 28 69 3d 3d 30 29 2e  olumn.** (i==0).
1e0e0 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73  .**.** SQLite us
1e0f0 65 73 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74  es dynamic run-t
1e100 69 6d 65 20 74 79 70 69 6e 67 2e 20 20 53 6f 20  ime typing.  So 
1e110 6a 75 73 74 20 62 65 63 61 75 73 65 20 61 20 63  just because a c
1e120 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c  olumn.** is decl
1e130 61 72 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20  ared to contain 
1e140 61 20 70 61 72 74 69 63 75 6c 61 72 20 74 79 70  a particular typ
1e150 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20  e does not mean 
1e160 74 68 61 74 20 74 68 65 0a 2a 2a 20 64 61 74 61  that the.** data
1e170 20 73 74 6f 72 65 64 20 69 6e 20 74 68 61 74 20   stored in that 
1e180 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68 65  column is of the
1e190 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 2e 20   declared type. 
1e1a0 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74   SQLite is.** st
1e1b0 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20 62 75  rongly typed, bu
1e1c0 74 20 74 68 65 20 74 79 70 69 6e 67 20 69 73 20  t the typing is 
1e1d0 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61 74  dynamic not stat
1e1e0 69 63 2e 20 20 54 79 70 65 0a 2a 2a 20 69 73 20  ic.  Type.** is 
1e1f0 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
1e200 69 6e 64 69 76 69 64 75 61 6c 20 76 61 6c 75 65  individual value
1e210 73 2c 20 6e 6f 74 20 77 69 74 68 20 74 68 65 20  s, not with the 
1e220 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73  containers.** us
1e230 65 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65  ed to hold those
1e240 20 76 61 6c 75 65 73 2e 0a 2a 2a 0a 2a 2a 20 49   values..**.** I
1e250 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
1e260 20 7b 46 31 33 37 36 31 7d 20 20 41 20 73 75 63   {F13761}  A suc
1e270 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
1e280 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
1e290 64 65 63 6c 74 79 70 65 28 53 2c 4e 29 5d 0a 2a  decltype(S,N)].*
1e2a0 2a 20 20 20 20 20 20 20 20 20 20 20 72 65 74 75  *           retu
1e2b0 72 6e 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69  rns a zero-termi
1e2c0 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69  nated UTF-8 stri
1e2d0 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  ng containing th
1e2e0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74  e.**           t
1e2f0 68 65 20 64 65 63 6c 61 72 65 64 20 64 61 74 61  he declared data
1e300 74 79 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c  type of the tabl
1e310 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 61 70  e column that ap
1e320 70 65 61 72 73 0a 2a 2a 20 20 20 20 20 20 20 20  pears.**        
1e330 20 20 20 61 73 20 74 68 65 20 4e 74 68 20 63 6f     as the Nth co
1e340 6c 75 6d 6e 20 28 6e 75 6d 62 65 72 65 64 20 66  lumn (numbered f
1e350 72 6f 6d 20 30 29 20 6f 66 20 74 68 65 20 72 65  rom 0) of the re
1e360 73 75 6c 74 20 73 65 74 20 74 6f 20 74 68 65 0a  sult set to the.
1e370 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 70 72  **           [pr
1e380 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1e390 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37  ] S..**.** {F137
1e3a0 36 32 7d 20 20 41 20 73 75 63 63 65 73 73 66 75  62}  A successfu
1e3b0 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  l call to [sqlit
1e3c0 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79  e3_column_declty
1e3d0 70 65 31 36 28 53 2c 4e 29 5d 0a 2a 2a 20 20 20  pe16(S,N)].**   
1e3e0 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 73 20          returns 
1e3f0 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
1e400 64 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20  d UTF-16 native 
1e410 62 79 74 65 20 6f 72 64 65 72 20 73 74 72 69 6e  byte order strin
1e420 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 63  g.**           c
1e430 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 64 65  ontaining the de
1e440 63 6c 61 72 65 64 20 64 61 74 61 74 79 70 65 20  clared datatype 
1e450 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c  of the table col
1e460 75 6d 6e 20 74 68 61 74 20 61 70 70 65 61 72 73  umn that appears
1e470 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 61 73  .**           as
1e480 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
1e490 28 6e 75 6d 62 65 72 65 64 20 66 72 6f 6d 20 30  (numbered from 0
1e4a0 29 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  ) of the result 
1e4b0 73 65 74 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20  set to the.**   
1e4c0 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65          [prepare
1e4d0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a  d statement] S..
1e4e0 2a 2a 0a 2a 2a 20 7b 46 31 33 37 36 33 7d 20 20  **.** {F13763}  
1e4f0 49 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61  If N is less tha
1e500 6e 20 30 20 6f 72 20 4e 20 69 73 20 67 72 65 61  n 0 or N is grea
1e510 74 65 72 20 74 68 61 6e 20 6f 72 20 65 71 75 61  ter than or equa
1e520 6c 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20  l to.**         
1e530 20 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20    the number of 
1e540 63 6f 6c 75 6d 6e 73 20 69 6e 20 5b 70 72 65 70  columns in [prep
1e550 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
1e560 53 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6f  S.**           o
1e570 72 20 69 66 20 74 68 65 20 4e 74 68 20 63 6f 6c  r if the Nth col
1e580 75 6d 6e 20 6f 66 20 53 20 69 73 20 61 6e 20 65  umn of S is an e
1e590 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62  xpression or sub
1e5a0 71 75 65 72 79 20 72 61 74 68 65 72 0a 2a 2a 20  query rather.** 
1e5b0 20 20 20 20 20 20 20 20 20 20 74 68 61 6e 20 61            than a
1e5c0 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 6f 72   table column or
1e5d0 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   if a memory all
1e5e0 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 0a  ocation failure.
1e5f0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6f 63 63  **           occ
1e600 75 72 73 20 64 75 72 69 6e 67 20 65 6e 63 6f 64  urs during encod
1e610 69 6e 67 20 63 6f 6e 76 65 72 73 69 6f 6e 73 2c  ing conversions,
1e620 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20   then.**        
1e630 20 20 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c     calls to [sql
1e640 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c  ite3_column_decl
1e650 74 79 70 65 28 53 2c 4e 29 5d 20 6f 72 0a 2a 2a  type(S,N)] or.**
1e660 20 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69             [sqli
1e670 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74  te3_column_declt
1e680 79 70 65 31 36 28 53 2c 4e 29 5d 20 72 65 74 75  ype16(S,N)] retu
1e690 72 6e 20 4e 55 4c 4c 2e 0a 2a 2f 0a 63 6f 6e 73  rn NULL..*/.cons
1e6a0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
1e6b0 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28  column_decltype(
1e6c0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
1e6d0 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  t);.const void *
1e6e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
1e6f0 65 63 6c 74 79 70 65 31 36 28 73 71 6c 69 74 65  ecltype16(sqlite
1e700 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f  3_stmt*,int);../
1e710 2a 20 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  * .** CAPI3REF: 
1e720 20 45 76 61 6c 75 61 74 65 20 41 6e 20 53 51 4c   Evaluate An SQL
1e730 20 53 74 61 74 65 6d 65 6e 74 20 7b 46 31 33 32   Statement {F132
1e740 30 30 7d 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20  00}.**.** After 
1e750 61 6e 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  an [prepared sta
1e760 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e  tement] has been
1e770 20 70 72 65 70 61 72 65 64 20 77 69 74 68 20 61   prepared with a
1e780 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 65 69 74 68   call.** to eith
1e790 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  er [sqlite3_prep
1e7a0 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71  are_v2()] or [sq
1e7b0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
1e7c0 76 32 28 29 5d 20 6f 72 20 74 6f 20 6f 6e 65 20  v2()] or to one 
1e7d0 6f 66 0a 2a 2a 20 74 68 65 20 6c 65 67 61 63 79  of.** the legacy
1e7e0 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c   interfaces [sql
1e7f0 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
1e800 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
1e810 61 72 65 31 36 28 29 5d 2c 0a 2a 2a 20 74 68 65  are16()],.** the
1e820 6e 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  n this function 
1e830 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 6f  must be called o
1e840 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73  ne or more times
1e850 20 74 6f 20 65 76 61 6c 75 61 74 65 20 74 68 65   to evaluate the
1e860 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 0a   .** statement..
1e870 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c  **.** The detail
1e880 73 20 6f 66 20 74 68 65 20 62 65 68 61 76 69 6f  s of the behavio
1e890 72 20 6f 66 20 74 68 69 73 20 73 71 6c 69 74 65  r of this sqlite
1e8a0 33 5f 73 74 65 70 28 29 20 69 6e 74 65 72 66 61  3_step() interfa
1e8b0 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20  ce depend.** on 
1e8c0 77 68 65 74 68 65 72 20 74 68 65 20 73 74 61 74  whether the stat
1e8d0 65 6d 65 6e 74 20 77 61 73 20 70 72 65 70 61 72  ement was prepar
1e8e0 65 64 20 75 73 69 6e 67 20 74 68 65 20 6e 65 77  ed using the new
1e8f0 65 72 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  er "v2" interfac
1e900 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  e.** [sqlite3_pr
1e910 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
1e920 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1e930 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 68 65 20  16_v2()] or the 
1e940 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20  older legacy.** 
1e950 69 6e 74 65 72 66 61 63 65 20 5b 73 71 6c 69 74  interface [sqlit
1e960 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e  e3_prepare()] an
1e970 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
1e980 72 65 31 36 28 29 5d 2e 20 20 54 68 65 20 75 73  re16()].  The us
1e990 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20  e of the.** new 
1e9a0 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69  "v2" interface i
1e9b0 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f  s recommended fo
1e9c0 72 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f  r new applicatio
1e9d0 6e 73 20 62 75 74 20 74 68 65 20 6c 65 67 61 63  ns but the legac
1e9e0 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 77  y.** interface w
1e9f0 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20  ill continue to 
1ea00 62 65 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a  be supported..**
1ea10 0a 2a 2a 20 49 6e 20 74 68 65 20 6c 61 67 61 63  .** In the lagac
1ea20 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65  y interface, the
1ea30 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 77 69   return value wi
1ea40 6c 6c 20 62 65 20 65 69 74 68 65 72 20 5b 53 51  ll be either [SQ
1ea50 4c 49 54 45 5f 42 55 53 59 5d 2c 20 0a 2a 2a 20  LITE_BUSY], .** 
1ea60 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b  [SQLITE_DONE], [
1ea70 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51  SQLITE_ROW], [SQ
1ea80 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20  LITE_ERROR], or 
1ea90 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e  [SQLITE_MISUSE].
1eaa0 0a 2a 2a 20 57 69 74 68 20 74 68 65 20 22 76 32  .** With the "v2
1eab0 22 20 69 6e 74 65 72 66 61 63 65 2c 20 61 6e 79  " interface, any
1eac0 20 6f 66 20 74 68 65 20 6f 74 68 65 72 20 5b 53   of the other [S
1ead0 51 4c 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c  QLITE_OK | resul
1eae0 74 20 63 6f 64 65 5d 0a 2a 2a 20 6f 72 20 5b 53  t code].** or [S
1eaf0 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44  QLITE_IOERR_READ
1eb00 20 7c 20 65 78 74 65 6e 64 65 64 20 72 65 73 75   | extended resu
1eb10 6c 74 20 63 6f 64 65 5d 20 6d 69 67 68 74 20 62  lt code] might b
1eb20 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a  e returned as.**
1eb30 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51   well..**.** [SQ
1eb40 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73  LITE_BUSY] means
1eb50 20 74 68 61 74 20 74 68 65 20 64 61 74 61 62 61   that the databa
1eb60 73 65 20 65 6e 67 69 6e 65 20 77 61 73 20 75 6e  se engine was un
1eb70 61 62 6c 65 20 74 6f 20 61 63 71 75 69 72 65 20  able to acquire 
1eb80 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
1eb90 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64 73 20 74  locks it needs t
1eba0 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20 49  o do its job.  I
1ebb0 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
1ebc0 69 73 20 61 20 43 4f 4d 4d 49 54 0a 2a 2a 20 6f  is a COMMIT.** o
1ebd0 72 20 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65  r occurs outside
1ebe0 20 6f 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20   of an explicit 
1ebf0 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65  transaction, the
1ec00 6e 20 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20  n you can retry 
1ec10 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  the.** statement
1ec20 2e 20 20 49 66 20 74 68 65 20 73 74 61 74 65 6d  .  If the statem
1ec30 65 6e 74 20 69 73 20 6e 6f 74 20 61 20 43 4f 4d  ent is not a COM
1ec40 4d 49 54 20 61 6e 64 20 6f 63 63 75 72 73 20 77  MIT and occurs w
1ec50 69 74 68 69 6e 20 61 0a 2a 2a 20 65 78 70 6c 69  ithin a.** expli
1ec60 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  cit transaction 
1ec70 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20  then you should 
1ec80 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61  rollback the tra
1ec90 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a  nsaction before.
1eca0 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a  ** continuing..*
1ecb0 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  *.** [SQLITE_DON
1ecc0 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  E] means that th
1ecd0 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20  e statement has 
1ece0 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69  finished executi
1ecf0 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c  ng.** successful
1ed00 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65  ly.  sqlite3_ste
1ed10 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62  p() should not b
1ed20 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f  e called again o
1ed30 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a  n this virtual.*
1ed40 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75  * machine withou
1ed50 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20  t first calling 
1ed60 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
1ed70 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 76  ] to reset the v
1ed80 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e  irtual.** machin
1ed90 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e  e back to its in
1eda0 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a  itial state..**.
1edb0 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 74  ** If the SQL st
1edc0 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78  atement being ex
1edd0 65 63 75 74 65 64 20 72 65 74 75 72 6e 73 20 61  ecuted returns a
1ede0 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20 0a 2a  ny data, then .*
1edf0 2a 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 69  * [SQLITE_ROW] i
1ee00 73 20 72 65 74 75 72 6e 65 64 20 65 61 63 68 20  s returned each 
1ee10 74 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f  time a new row o
1ee20 66 20 64 61 74 61 20 69 73 20 72 65 61 64 79 0a  f data is ready.
1ee30 2a 2a 20 66 6f 72 20 70 72 6f 63 65 73 73 69 6e  ** for processin
1ee40 67 20 62 79 20 74 68 65 20 63 61 6c 6c 65 72 2e  g by the caller.
1ee50 20 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20   The values may 
1ee60 62 65 20 61 63 63 65 73 73 65 64 20 75 73 69 6e  be accessed usin
1ee70 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  g.** the [sqlite
1ee80 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 63  3_column_int | c
1ee90 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e  olumn access fun
1eea0 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69  ctions]..** sqli
1eeb0 74 65 33 5f 73 74 65 70 28 29 20 69 73 20 63 61  te3_step() is ca
1eec0 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f 20 72 65  lled again to re
1eed0 74 72 69 65 76 65 20 74 68 65 20 6e 65 78 74 20  trieve the next 
1eee0 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 20  row of data..** 
1eef0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  .** [SQLITE_ERRO
1ef00 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20  R] means that a 
1ef10 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 28  run-time error (
1ef20 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73 74 72  such as a constr
1ef30 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f  aint.** violatio
1ef40 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65 64 2e  n) has occurred.
1ef50 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29    sqlite3_step()
1ef60 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63   should not be c
1ef70 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a  alled again on.*
1ef80 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69  * the VM. More i
1ef90 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62  nformation may b
1efa0 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69  e found by calli
1efb0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ng [sqlite3_errm
1efc0 73 67 28 29 5d 2e 0a 2a 2a 20 57 69 74 68 20 74  sg()]..** With t
1efd0 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66  he legacy interf
1efe0 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 70 65 63  ace, a more spec
1eff0 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20  ific error code 
1f000 28 65 78 61 6d 70 6c 65 3a 0a 2a 2a 20 5b 53 51  (example:.** [SQ
1f010 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c  LITE_INTERRUPT],
1f020 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d   [SQLITE_SCHEMA]
1f030 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50  , [SQLITE_CORRUP
1f040 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 68  T], and so forth
1f050 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 61  ).** can be obta
1f060 69 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20  ined by calling 
1f070 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
1f080 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65  ] on the.** [pre
1f090 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
1f0a0 2e 20 20 49 6e 20 74 68 65 20 22 76 32 22 20 69  .  In the "v2" i
1f0b0 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65  nterface,.** the
1f0c0 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65   more specific e
1f0d0 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74  rror code is ret
1f0e0 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 20 62  urned directly b
1f0f0 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  y sqlite3_step()
1f100 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ..**.** [SQLITE_
1f110 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 68  MISUSE] means th
1f120 61 74 20 74 68 65 20 74 68 69 73 20 72 6f 75 74  at the this rout
1f130 69 6e 65 20 77 61 73 20 63 61 6c 6c 65 64 20 69  ine was called i
1f140 6e 61 70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a  nappropriately..
1f150 2a 2a 20 50 65 72 68 61 70 73 20 69 74 20 77 61  ** Perhaps it wa
1f160 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70  s called on a [p
1f170 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1f180 74 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 61  t] that has.** a
1f190 6c 72 65 61 64 79 20 62 65 65 6e 20 5b 73 71 6c  lready been [sql
1f1a0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20  ite3_finalize | 
1f1b0 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e  finalized] or on
1f1c0 20 6f 6e 65 20 74 68 61 74 20 68 61 64 20 0a 2a   one that had .*
1f1d0 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74  * previously ret
1f1e0 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 52  urned [SQLITE_ER
1f1f0 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ROR] or [SQLITE_
1f200 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f  DONE].  Or it co
1f210 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 61  uld.** be the ca
1f220 73 65 20 74 68 61 74 20 74 68 65 20 73 61 6d 65  se that the same
1f230 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1f240 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 73  tion is being us
1f250 65 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20  ed by two or.** 
1f260 6d 6f 72 65 20 74 68 72 65 61 64 73 20 61 74 20  more threads at 
1f270 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20  the same moment 
1f280 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 3c  in time..**.** <
1f290 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63  b>Goofy Interfac
1f2a0 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 0a 2a 2a 20  e Alert:</b>.** 
1f2b0 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e  In the legacy in
1f2c0 74 65 72 66 61 63 65 2c 20 0a 2a 2a 20 74 68 65  terface, .** the
1f2d0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
1f2e0 41 50 49 20 61 6c 77 61 79 73 20 72 65 74 75 72  API always retur
1f2f0 6e 73 20 61 20 67 65 6e 65 72 69 63 20 65 72 72  ns a generic err
1f300 6f 72 20 63 6f 64 65 2c 0a 2a 2a 20 5b 53 51 4c  or code,.** [SQL
1f310 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c  ITE_ERROR], foll
1f320 6f 77 69 6e 67 20 61 6e 79 20 65 72 72 6f 72 20  owing any error 
1f330 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
1f340 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 61 6e 64 20  TE_BUSY].** and 
1f350 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e  [SQLITE_MISUSE].
1f360 20 20 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 20    You must call 
1f370 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
1f380 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
1f390 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20  _finalize()] in 
1f3a0 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e  order to find on
1f3b0 65 20 6f 66 20 74 68 65 20 73 70 65 63 69 66 69  e of the specifi
1f3c0 63 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65  c.** [error code
1f3d0 73 5d 20 74 68 61 74 20 62 65 74 74 65 72 20 64  s] that better d
1f3e0 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72  escribes the err
1f3f0 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20  or..** We admit 
1f400 74 68 61 74 20 74 68 69 73 20 69 73 20 61 20 67  that this is a g
1f410 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68  oofy design.  Th
1f420 65 20 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65  e problem has be
1f430 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68  en fixed.** with
1f440 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
1f450 61 63 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65  ace.  If you pre
1f460 70 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72  pare all of your
1f470 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
1f480 2a 2a 20 75 73 69 6e 67 20 65 69 74 68 65 72 20  ** using either 
1f490 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1f4a0 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  _v2()] or [sqlit
1f4b0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
1f4c0 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66  )] instead.** of
1f4d0 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c   the legacy [sql
1f4e0 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
1f4f0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  and [sqlite3_pre
1f500 70 61 72 65 31 36 28 29 5d 2c 20 74 68 65 6e 20  pare16()], then 
1f510 74 68 65 20 0a 2a 2a 20 6d 6f 72 65 20 73 70 65  the .** more spe
1f520 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64  cific [error cod
1f530 65 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64  es] are returned
1f540 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20   directly.** by 
1f550 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20  sqlite3_step(). 
1f560 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 20   The use of the 
1f570 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69  "v2" interface i
1f580 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a  s recommended..*
1f590 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
1f5a0 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 32 30 32 7d 20  .**.** {F13202} 
1f5b0 20 49 66 20 5b 70 72 65 70 61 72 65 64 20 73 74   If [prepared st
1f5c0 61 74 65 6d 65 6e 74 5d 20 53 20 69 73 20 72 65  atement] S is re
1f5d0 61 64 79 20 74 6f 20 62 65 0a 2a 2a 20 20 20 20  ady to be.**    
1f5e0 20 20 20 20 20 20 20 72 75 6e 2c 20 74 68 65 6e         run, then
1f5f0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
1f600 29 5d 20 61 64 76 61 6e 63 65 73 20 74 68 61 74  )] advances that
1f610 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
1f620 65 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ent.**          
1f630 20 75 6e 74 69 6c 20 74 6f 20 63 6f 6d 70 6c 65   until to comple
1f640 74 69 6f 6e 20 6f 72 20 75 6e 74 69 6c 20 69 74  tion or until it
1f650 20 69 73 20 72 65 61 64 79 20 74 6f 20 72 65 74   is ready to ret
1f660 75 72 6e 20 61 6e 6f 74 68 65 72 0a 2a 2a 20 20  urn another.**  
1f670 20 20 20 20 20 20 20 20 20 72 6f 77 20 6f 66 20           row of 
1f680 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f  the result set o
1f690 72 20 61 6e 20 69 6e 74 65 72 72 75 70 74 20 6f  r an interrupt o
1f6a0 72 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72  r run-time error
1f6b0 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b   occurs..**.** {
1f6c0 46 31 35 33 30 34 7d 20 20 57 68 65 6e 20 61 20  F15304}  When a 
1f6d0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
1f6e0 5f 73 74 65 70 28 53 29 5d 20 63 61 75 73 65 73  _step(S)] causes
1f6f0 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 20 20 20   the .**        
1f700 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61     [prepared sta
1f710 74 65 6d 65 6e 74 5d 20 53 20 74 6f 20 72 75 6e  tement] S to run
1f720 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2c 0a   to completion,.
1f730 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 68 65  **           the
1f740 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
1f750 73 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e  s [SQLITE_DONE].
1f760 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 33 30 36 7d 20  .**.** {F15306} 
1f770 20 57 68 65 6e 20 61 20 63 61 6c 6c 20 74 6f 20   When a call to 
1f780 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
1f790 5d 20 73 74 6f 70 73 20 62 65 63 61 75 73 65 20  ] stops because 
1f7a0 69 74 20 69 73 20 72 65 61 64 79 0a 2a 2a 20 20  it is ready.**  
1f7b0 20 20 20 20 20 20 20 20 20 74 6f 20 72 65 74 75           to retu
1f7c0 72 6e 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 6f  rn another row o
1f7d0 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
1f7e0 2c 20 69 74 20 72 65 74 75 72 6e 73 0a 2a 2a 20  , it returns.** 
1f7f0 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54            [SQLIT
1f800 45 5f 52 4f 57 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46  E_ROW]..**.** {F
1f810 31 35 33 30 38 7d 20 20 49 66 20 61 20 63 61 6c  15308}  If a cal
1f820 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
1f830 65 70 28 53 29 5d 20 65 6e 63 6f 75 6e 74 65 72  ep(S)] encounter
1f840 73 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  s an.**         
1f850 20 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72    [sqlite3_inter
1f860 72 75 70 74 7c 69 6e 74 65 72 72 75 70 74 5d 20  rupt|interrupt] 
1f870 6f 72 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72  or a run-time er
1f880 72 6f 72 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ror,.**         
1f890 20 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20    it returns an 
1f8a0 61 70 70 72 6f 70 72 61 69 74 65 20 65 72 72 6f  appropraite erro
1f8b0 72 20 63 6f 64 65 20 74 68 61 74 20 69 73 20 6e  r code that is n
1f8c0 6f 74 20 6f 6e 65 20 6f 66 0a 2a 2a 20 20 20 20  ot one of.**    
1f8d0 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 4f         [SQLITE_O
1f8e0 4b 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  K], [SQLITE_ROW]
1f8f0 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  , or [SQLITE_DON
1f900 45 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 33 31  E]..**.** {F1531
1f910 30 7d 20 20 49 66 20 61 6e 20 5b 73 71 6c 69 74  0}  If an [sqlit
1f920 65 33 5f 69 6e 74 65 72 72 75 70 74 7c 69 6e 74  e3_interrupt|int
1f930 65 72 72 75 70 74 5d 20 6f 72 20 72 75 6e 2d 74  errupt] or run-t
1f940 69 6d 65 20 65 72 72 6f 72 0a 2a 2a 20 20 20 20  ime error.**    
1f950 20 20 20 20 20 20 20 6f 63 63 75 72 73 20 64 75         occurs du
1f960 72 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 5b  ring a call to [
1f970 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
1f980 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 66 6f  .**           fo
1f990 72 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  r a [prepared st
1f9a0 61 74 65 6d 65 6e 74 5d 20 53 20 63 72 65 61 74  atement] S creat
1f9b0 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20  ed using.**     
1f9c0 20 20 20 20 20 20 6c 65 67 61 63 79 20 69 6e 74        legacy int
1f9d0 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33  erfaces [sqlite3
1f9e0 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 0a 2a  _prepare()] or.*
1f9f0 2a 20 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  *           [sql
1fa00 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
1fa10 5d 20 74 68 65 6e 20 74 68 65 20 66 75 6e 63 74  ] then the funct
1fa20 69 6f 6e 20 72 65 74 75 72 6e 73 20 65 69 74 68  ion returns eith
1fa30 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  er.**           
1fa40 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20  [SQLITE_ERROR], 
1fa50 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 20 6f  [SQLITE_BUSY], o
1fa60 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  r [SQLITE_MISUSE
1fa70 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
1fa80 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73  3_step(sqlite3_s
1fa90 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
1faa0 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f  PI3REF: Number o
1fab0 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72  f columns in a r
1fac0 65 73 75 6c 74 20 73 65 74 20 7b 46 31 33 37 37  esult set {F1377
1fad0 30 7d 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20  0}.**.** Return 
1fae0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 76 61  the number of va
1faf0 6c 75 65 73 20 69 6e 20 74 68 65 20 63 75 72 72  lues in the curr
1fb00 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72  ent row of the r
1fb10 65 73 75 6c 74 20 73 65 74 2e 0a 2a 2a 0a 2a 2a  esult set..**.**
1fb20 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
1fb30 2a 2a 20 7b 46 31 33 37 37 31 7d 20 20 41 66 74  ** {F13771}  Aft
1fb40 65 72 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71  er a call to [sq
1fb50 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 74  lite3_step(S)] t
1fb60 68 61 74 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20  hat returns.**  
1fb70 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45           [SQLITE
1fb80 5f 52 4f 57 5d 2c 20 74 68 65 20 5b 73 71 6c 69  _ROW], the [sqli
1fb90 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 53  te3_data_count(S
1fba0 29 5d 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 20 20  )] routine.**   
1fbb0 20 20 20 20 20 20 20 20 77 69 6c 6c 20 72 65 74          will ret
1fbc0 75 72 6e 20 74 68 65 20 73 61 6d 65 20 76 61 6c  urn the same val
1fbd0 75 65 20 61 73 20 74 68 65 0a 2a 2a 20 20 20 20  ue as the.**    
1fbe0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
1fbf0 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 53 29 5d  column_count(S)]
1fc00 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   function..**.**
1fc10 20 7b 46 31 33 37 37 32 7d 20 20 41 66 74 65 72   {F13772}  After
1fc20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
1fc30 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 20  )] has returned 
1fc40 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20  any value other 
1fc50 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  than.**         
1fc60 20 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f    [SQLITE_ROW] o
1fc70 72 20 62 65 66 6f 72 65 20 5b 73 71 6c 69 74 65  r before [sqlite
1fc80 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20 62  3_step(S)] has b
1fc90 65 65 6e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  een .**         
1fca0 20 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20    called on the 
1fcb0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
1fcc0 65 6e 74 5d 20 66 6f 72 0a 2a 2a 20 20 20 20 20  ent] for.**     
1fcd0 20 20 20 20 20 20 74 68 65 20 66 69 72 73 74 20        the first 
1fce0 74 69 6d 65 20 73 69 6e 63 65 20 69 74 20 77 61  time since it wa
1fcf0 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  s [sqlite3_prepa
1fd00 72 65 7c 70 72 65 70 61 72 65 64 5d 0a 2a 2a 20  re|prepared].** 
1fd10 20 20 20 20 20 20 20 20 20 20 6f 72 20 5b 73 71            or [sq
1fd20 6c 69 74 65 33 5f 72 65 73 65 74 7c 72 65 73 65  lite3_reset|rese
1fd30 74 5d 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33  t], the [sqlite3
1fd40 5f 64 61 74 61 5f 63 6f 75 6e 74 28 53 29 5d 0a  _data_count(S)].
1fd50 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72 6f 75  **           rou
1fd60 74 69 6e 65 20 72 65 74 75 72 6e 73 20 7a 65 72  tine returns zer
1fd70 6f 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  o..*/.int sqlite
1fd80 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c  3_data_count(sql
1fd90 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
1fda0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1fdb0 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20  EF: Fundamental 
1fdc0 44 61 74 61 74 79 70 65 73 20 7b 46 31 30 32 36  Datatypes {F1026
1fdd0 35 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  5}.** KEYWORDS: 
1fde0 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a  SQLITE_TEXT.**.*
1fdf0 2a 20 7b 46 31 30 32 36 36 7d 45 76 65 72 79 20  * {F10266}Every 
1fe00 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20  value in SQLite 
1fe10 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20  has one of five 
1fe20 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61  fundamental data
1fe30 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  types:.**.** <ul
1fe40 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74  >.** <li> 64-bit
1fe50 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a   signed integer.
1fe60 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49  ** <li> 64-bit I
1fe70 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  EEE floating poi
1fe80 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69  nt number.** <li
1fe90 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e  > string.** <li>
1fea0 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55   BLOB.** <li> NU
1feb0 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 20 7b 45 4e 44  LL.** </ul> {END
1fec0 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  }.**.** These co
1fed0 6e 73 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65  nstants are code
1fee0 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68  s for each of th
1fef0 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a  ose types..**.**
1ff00 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 53   Note that the S
1ff10 51 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74  QLITE_TEXT const
1ff20 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65  ant was also use
1ff30 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73  d in SQLite vers
1ff40 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63  ion 2.** for a c
1ff50 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72  ompletely differ
1ff60 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f  ent meaning.  So
1ff70 66 74 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b  ftware that link
1ff80 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a  s against both.*
1ff90 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  * SQLite version
1ffa0 20 32 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65   2 and SQLite ve
1ffb0 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75  rsion 3 should u
1ffc0 73 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20  se SQLITE3_TEXT 
1ffd0 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45  not.** SQLITE_TE
1ffe0 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  XT..*/.#define S
1fff0 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20 31  QLITE_INTEGER  1
20000 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
20010 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66 69  FLOAT    2.#defi
20020 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20  ne SQLITE_BLOB  
20030 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c     4.#define SQL
20040 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23  ITE_NULL     5.#
20050 69 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58  ifdef SQLITE_TEX
20060 54 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45  T.# undef SQLITE
20070 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64 65  _TEXT.#else.# de
20080 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 54  fine SQLITE_TEXT
20090 20 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23 64       3.#endif.#d
200a0 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 45  efine SQLITE3_TE
200b0 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20  XT     3../*.** 
200c0 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74  CAPI3REF: Result
200d0 73 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20  s Values From A 
200e0 51 75 65 72 79 20 7b 46 31 33 38 30 30 7d 0a 2a  Query {F13800}.*
200f0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
20100 6e 65 73 20 66 6f 72 6d 20 74 68 65 20 22 72 65  nes form the "re
20110 73 75 6c 74 20 73 65 74 20 71 75 65 72 79 22 20  sult set query" 
20120 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
20130 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
20140 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69  return informati
20150 6f 6e 20 61 62 6f 75 74 0a 2a 2a 20 61 20 73 69  on about.** a si
20160 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  ngle column of t
20170 68 65 20 63 75 72 72 65 6e 74 20 72 65 73 75 6c  he current resul
20180 74 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79  t row of a query
20190 2e 20 20 49 6e 20 65 76 65 72 79 0a 2a 2a 20 63  .  In every.** c
201a0 61 73 65 20 74 68 65 20 66 69 72 73 74 20 61 72  ase the first ar
201b0 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e  gument is a poin
201c0 74 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20 5b  ter to the .** [
201d0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
201e0 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65 69 6e  nt] that is bein
201f0 67 0a 2a 2a 20 65 76 61 6c 75 61 74 65 64 20 28  g.** evaluated (
20200 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  the [sqlite3_stm
20210 74 2a 5d 20 74 68 61 74 20 77 61 73 20 72 65 74  t*] that was ret
20220 75 72 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b  urned from .** [
20230 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
20240 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20  v2()] or one of 
20250 69 74 73 20 76 61 72 69 61 6e 74 73 29 20 61 6e  its variants) an
20260 64 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20  d.** the second 
20270 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
20280 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c  index of the col
20290 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e  umn for which in
202a0 66 6f 72 6d 61 74 69 6f 6e 20 0a 2a 2a 20 73 68  formation .** sh
202b0 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64  ould be returned
202c0 2e 20 20 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74  .  The left-most
202d0 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72   column of the r
202e0 65 73 75 6c 74 20 73 65 74 0a 2a 2a 20 68 61 73  esult set.** has
202f0 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 30 2e 0a   an index of 0..
20300 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c  **.** If the SQL
20310 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f   statement is no
20320 74 20 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e  t currently poin
20330 74 20 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77  t to a valid row
20340 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 74  , or if the.** t
20350 68 65 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20  he column index 
20360 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c  is out of range,
20370 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 75   the result is u
20380 6e 64 65 66 69 6e 65 64 2e 20 0a 2a 2a 20 54 68  ndefined. .** Th
20390 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79  ese routines may
203a0 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20   only be called 
203b0 77 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65  when the most re
203c0 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  cent call to.** 
203d0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
203e0 20 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53   has returned [S
203f0 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e  QLITE_ROW] and n
20400 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74  either.** [sqlit
20410 65 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20  e3_reset()] nor 
20420 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
20430 65 28 29 5d 20 68 61 73 20 62 65 65 6e 20 63 61  e()] has been ca
20440 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e  ll subsequently.
20450 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 68  .** If any of th
20460 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
20470 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73   called after [s
20480 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
20490 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  or.** [sqlite3_f
204a0 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66  inalize()] or af
204b0 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ter [sqlite3_ste
204c0 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65  p()] has returne
204d0 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f  d.** something o
204e0 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
204f0 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 75  E_ROW], the resu
20500 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
20510 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65  d..** If [sqlite
20520 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71  3_step()] or [sq
20530 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
20540 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  r [sqlite3_final
20550 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61  ize()].** are ca
20560 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64 69 66 66  lled from a diff
20570 65 72 65 6e 74 20 74 68 72 65 61 64 20 77 68 69  erent thread whi
20580 6c 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20  le any of these 
20590 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20  routines.** are 
205a0 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 68  pending, then th
205b0 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
205c0 64 65 66 69 6e 65 64 2e 20 20 0a 2a 2a 0a 2a 2a  defined.  .**.**
205d0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c   The sqlite3_col
205e0 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 74 69  umn_type() routi
205f0 6e 65 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 5b  ne returns .** [
20600 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c  SQLITE_INTEGER |
20610 20 64 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20   datatype code] 
20620 66 6f 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20  for the initial 
20630 64 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20  data type.** of 
20640 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  the result colum
20650 6e 2e 20 20 54 68 65 20 72 65 74 75 72 6e 65 64  n.  The returned
20660 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66   value is one of
20670 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52   [SQLITE_INTEGER
20680 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c  ],.** [SQLITE_FL
20690 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45  OAT], [SQLITE_TE
206a0 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f  XT], [SQLITE_BLO
206b0 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e  B], or [SQLITE_N
206c0 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75 65  ULL].  The value
206d0 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20  .** returned by 
206e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
206f0 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65  ype() is only me
20700 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74  aningful if no t
20710 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f  ype.** conversio
20720 6e 73 20 68 61 76 65 20 6f 63 63 75 72 72 65 64  ns have occurred
20730 20 61 73 20 64 65 73 63 72 69 62 65 64 20 62 65   as described be
20740 6c 6f 77 2e 20 20 41 66 74 65 72 20 61 20 74 79  low.  After a ty
20750 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a  pe conversion,.*
20760 2a 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  * the value retu
20770 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
20780 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73  column_type() is
20790 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 46 75 74   undefined.  Fut
207a0 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20  ure.** versions 
207b0 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63 68  of SQLite may ch
207c0 61 6e 67 65 20 74 68 65 20 62 65 68 61 76 69 6f  ange the behavio
207d0 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r of sqlite3_col
207e0 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f  umn_type().** fo
207f0 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20 63  llowing a type c
20800 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  onversion..**.**
20810 20 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69   If the result i
20820 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d  s a BLOB or UTF-
20830 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68  8 string then th
20840 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
20850 5f 62 79 74 65 73 28 29 20 0a 2a 2a 20 72 6f 75  _bytes() .** rou
20860 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
20870 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
20880 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72   in that BLOB or
20890 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 49 66 20 74   string..** If t
208a0 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55  he result is a U
208b0 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68  TF-16 string, th
208c0 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
208d0 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72  n_bytes() conver
208e0 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67  ts.** the string
208f0 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68   to UTF-8 and th
20900 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  en returns the n
20910 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a  umber of bytes..
20920 2a 2a 20 49 66 20 74 68 65 20 72 65 73 75 6c 74  ** If the result
20930 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61   is a numeric va
20940 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33  lue then sqlite3
20950 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
20960 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  uses.** [sqlite3
20970 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20  _snprintf()] to 
20980 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c  convert that val
20990 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73 74  ue to a UTF-8 st
209a0 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73  ring and returns
209b0 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
209c0 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20  f bytes in that 
209d0 73 74 72 69 6e 67 2e 0a 2a 2a 20 54 68 65 20 76  string..** The v
209e0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 64 6f  alue returned do
209f0 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74  es not include t
20a00 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  he zero terminat
20a10 6f 72 20 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a  or at the end.**
20a20 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 2e 20   of the string. 
20a30 20 46 6f 72 20 63 6c 61 72 69 74 79 3a 20 74 68   For clarity: th
20a40 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
20a50 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
20a60 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68  f.** bytes in th
20a70 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68  e string, not th
20a80 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72  e number of char
20a90 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 53 74  acters..**.** St
20aa0 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62  rings returned b
20ab0 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
20ac0 5f 74 65 78 74 28 29 20 61 6e 64 20 73 71 6c 69  _text() and sqli
20ad0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
20ae0 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70  6(),.** even emp
20af0 74 79 20 73 74 72 69 6e 67 73 2c 20 61 72 65 20  ty strings, are 
20b00 61 6c 77 61 79 73 20 7a 65 72 6f 20 74 65 72 6d  always zero term
20b10 69 6e 61 74 65 64 2e 20 20 54 68 65 20 72 65 74  inated.  The ret
20b20 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f  urn.** value fro
20b30 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  m sqlite3_column
20b40 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a 65  _blob() for a ze
20b50 72 6f 2d 6c 65 6e 67 74 68 20 62 6c 6f 62 20 69  ro-length blob i
20b60 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 0a 2a  s an arbitrary.*
20b70 2a 20 70 6f 69 6e 74 65 72 2c 20 70 6f 73 73 69  * pointer, possi
20b80 62 6c 79 20 65 76 65 6e 20 61 20 4e 55 4c 4c 20  bly even a NULL 
20b90 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54  pointer..**.** T
20ba0 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
20bb0 6e 5f 62 79 74 65 73 31 36 28 29 20 72 6f 75 74  n_bytes16() rout
20bc0 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74  ine is similar t
20bd0 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
20be0 5f 62 79 74 65 73 28 29 0a 2a 2a 20 62 75 74 20  _bytes().** but 
20bf0 6c 65 61 76 65 73 20 74 68 65 20 72 65 73 75 6c  leaves the resul
20c00 74 20 69 6e 20 55 54 46 2d 31 36 20 69 6e 20 6e  t in UTF-16 in n
20c10 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
20c20 20 69 6e 73 74 65 61 64 20 6f 66 20 55 54 46 2d   instead of UTF-
20c30 38 2e 20 20 0a 2a 2a 20 54 68 65 20 7a 65 72 6f  8.  .** The zero
20c40 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 73 20 6e   terminator is n
20c50 6f 74 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74  ot included in t
20c60 68 69 73 20 63 6f 75 6e 74 2e 0a 2a 2a 0a 2a 2a  his count..**.**
20c70 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
20c80 61 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65  attempt to conve
20c90 72 74 20 74 68 65 20 76 61 6c 75 65 20 77 68 65  rt the value whe
20ca0 72 65 20 61 70 70 72 6f 70 72 69 61 74 65 2e 20  re appropriate. 
20cb0 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c   For.** example,
20cc0 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c   if the internal
20cd0 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20   representation 
20ce0 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74  is FLOAT and a t
20cf0 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73  ext result.** is
20d00 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c   requested, [sql
20d10 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
20d20 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61   is used interna
20d30 6c 6c 79 20 74 6f 20 64 6f 20 74 68 65 20 63 6f  lly to do the co
20d40 6e 76 65 72 73 69 6f 6e 0a 2a 2a 20 61 75 74 6f  nversion.** auto
20d50 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54 68 65 20  matically.  The 
20d60 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20  following table 
20d70 64 65 74 61 69 6c 73 20 74 68 65 20 63 6f 6e 76  details the conv
20d80 65 72 73 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20  ersions that.** 
20d90 61 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a  are applied:.**.
20da0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  ** <blockquote>.
20db0 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72  ** <table border
20dc0 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68  ="1">.** <tr><th
20dd0 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79  > Internal<br>Ty
20de0 70 65 20 3c 74 68 3e 20 52 65 71 75 65 73 74 65  pe <th> Requeste
20df0 64 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20  d<br>Type <th>  
20e00 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a  Conversion.**.**
20e10 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
20e20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
20e30 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
20e40 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20   0.** <tr><td>  
20e50 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c  NULL    <td>  FL
20e60 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75  OAT    <td> Resu
20e70 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72  lt is 0.0.** <tr
20e80 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
20e90 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
20ea0 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c  d> Result is NUL
20eb0 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72  L pointer.** <tr
20ec0 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
20ed0 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
20ee0 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c  d> Result is NUL
20ef0 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72  L pointer.** <tr
20f00 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c  ><td> INTEGER  <
20f10 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
20f20 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20  d> Convert from 
20f30 69 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 74  integer to float
20f40 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54  .** <tr><td> INT
20f50 45 47 45 52 20 20 3c 74 64 3e 20 20 20 54 45 58  EGER  <td>   TEX
20f60 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20  T    <td> ASCII 
20f70 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65  rendering of the
20f80 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e   integer.** <tr>
20f90 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74  <td> INTEGER  <t
20fa0 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
20fb0 3e 20 53 61 6d 65 20 61 73 20 66 6f 72 20 49 4e  > Same as for IN
20fc0 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c  TEGER->TEXT.** <
20fd0 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  tr><td>  FLOAT  
20fe0 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
20ff0 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f  <td> Convert fro
21000 6d 20 66 6c 6f 61 74 20 74 6f 20 69 6e 74 65 67  m float to integ
21010 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  er.** <tr><td>  
21020 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 54  FLOAT   <td>   T
21030 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49  EXT    <td> ASCI
21040 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74  I rendering of t
21050 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e  he float.** <tr>
21060 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74  <td>  FLOAT   <t
21070 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
21080 3e 20 53 61 6d 65 20 61 73 20 46 4c 4f 41 54 2d  > Same as FLOAT-
21090 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64  >TEXT.** <tr><td
210a0 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20  >  TEXT    <td> 
210b0 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 55  INTEGER   <td> U
210c0 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72  se atoi().** <tr
210d0 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c  ><td>  TEXT    <
210e0 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
210f0 64 3e 20 55 73 65 20 61 74 6f 66 28 29 0a 2a 2a  d> Use atof().**
21100 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20   <tr><td>  TEXT 
21110 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20     <td>   BLOB  
21120 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65    <td> No change
21130 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c  .** <tr><td>  BL
21140 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  OB    <td> INTEG
21150 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72  ER   <td> Conver
21160 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75  t to TEXT then u
21170 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72  se atoi().** <tr
21180 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c  ><td>  BLOB    <
21190 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
211a0 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45  d> Convert to TE
211b0 58 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f 66  XT then use atof
211c0 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ().** <tr><td>  
211d0 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 54  BLOB    <td>   T
211e0 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64 20  EXT    <td> Add 
211f0 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  a zero terminato
21200 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c  r if needed.** <
21210 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f  /table>.** </blo
21220 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
21230 68 65 20 74 61 62 6c 65 20 61 62 6f 76 65 20 6d  he table above m
21240 61 6b 65 73 20 72 65 66 65 72 65 6e 63 65 20 74  akes reference t
21250 6f 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  o standard C lib
21260 72 61 72 79 20 66 75 6e 63 74 69 6f 6e 73 20 61  rary functions a
21270 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74 6f  toi().** and ato
21280 66 28 29 2e 20 20 53 51 4c 69 74 65 20 64 6f 65  f().  SQLite doe
21290 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73 65  s not really use
212a0 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
212b0 2e 20 20 49 74 20 68 61 73 20 69 74 73 0a 2a 2a  .  It has its.**
212c0 20 6f 6e 20 65 71 75 61 76 61 6c 65 6e 74 20 69   on equavalent i
212d0 6e 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e 65 73  nternal routines
212e0 2e 20 20 54 68 65 20 61 74 6f 69 28 29 20 61 6e  .  The atoi() an
212f0 64 20 61 74 6f 66 28 29 20 6e 61 6d 65 73 20 61  d atof() names a
21300 72 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20 74 68  re.** used in th
21310 65 20 74 61 62 6c 65 20 66 6f 72 20 62 72 65 76  e table for brev
21320 69 74 79 20 61 6e 64 20 62 65 63 61 75 73 65 20  ity and because 
21330 74 68 65 79 20 61 72 65 20 66 61 6d 69 6c 69 61  they are familia
21340 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20 70  r to most.** C p
21350 72 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a  rogrammers..**.*
21360 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e  * Note that when
21370 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
21380 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72  s occur, pointer
21390 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 70 72  s returned by pr
213a0 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20  ior.** calls to 
213b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
213c0 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63  lob(), sqlite3_c
213d0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e  olumn_text(), an
213e0 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  d/or.** sqlite3_
213f0 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
21400 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74  may be invalidat
21410 65 64 2e 20 0a 2a 2a 20 54 79 70 65 20 63 6f 6e  ed. .** Type con
21420 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69  versions and poi
21430 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f  nter invalidatio
21440 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a  ns might occur.*
21450 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69  * in the followi
21460 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20  ng cases:.**.** 
21470 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 3c 70 3e 20  <ul>.** <li><p> 
21480 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e   The initial con
21490 74 65 6e 74 20 69 73 20 61 20 42 4c 4f 42 20 61  tent is a BLOB a
214a0 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
214b0 6e 5f 74 65 78 74 28 29 20 0a 2a 2a 20 20 20 20  n_text() .**    
214c0 20 20 20 20 20 20 6f 72 20 73 71 6c 69 74 65 33        or sqlite3
214d0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
214e0 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a   is called.  A z
214f0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d  ero-terminator m
21500 69 67 68 74 0a 2a 2a 20 20 20 20 20 20 20 20 20  ight.**         
21510 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64 65   need to be adde
21520 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67 2e  d to the string.
21530 3c 2f 70 3e 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20  </p></li>.**.** 
21540 3c 6c 69 3e 3c 70 3e 20 20 54 68 65 20 69 6e 69  <li><p>  The ini
21550 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20  tial content is 
21560 55 54 46 2d 38 20 74 65 78 74 20 61 6e 64 20 73  UTF-8 text and s
21570 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
21580 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20  tes16() or.**   
21590 20 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63         sqlite3_c
215a0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69  olumn_text16() i
215b0 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63  s called.  The c
215c0 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63  ontent must be c
215d0 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20  onverted.**     
215e0 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c       to UTF-16.<
215f0 2f 70 3e 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c  /p></li>.**.** <
21600 6c 69 3e 3c 70 3e 20 20 54 68 65 20 69 6e 69 74  li><p>  The init
21610 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55  ial content is U
21620 54 46 2d 31 36 20 74 65 78 74 20 61 6e 64 20 73  TF-16 text and s
21630 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
21640 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20  tes() or.**     
21650 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c       sqlite3_col
21660 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61  umn_text() is ca
21670 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65  lled.  The conte
21680 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65  nt must be conve
21690 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  rted.**         
216a0 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 70 3e 3c 2f   to UTF-8.</p></
216b0 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  li>.** </ul>.**.
216c0 2a 2a 20 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62  ** Conversions b
216d0 65 74 77 65 65 6e 20 55 54 46 2d 31 36 62 65 20  etween UTF-16be 
216e0 61 6e 64 20 55 54 46 2d 31 36 6c 65 20 61 72 65  and UTF-16le are
216f0 20 61 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e 20   always done in 
21700 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20  place and do.** 
21710 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74 65 20 61  not invalidate a
21720 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20   prior pointer, 
21730 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 65  though of course
21740 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
21750 74 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 74 68  the buffer.** th
21760 61 74 20 74 68 65 20 70 72 69 6f 72 20 70 6f 69  at the prior poi
21770 6e 74 65 72 20 70 6f 69 6e 74 73 20 74 6f 20 77  nter points to w
21780 69 6c 6c 20 68 61 76 65 20 62 65 65 6e 20 6d 6f  ill have been mo
21790 64 69 66 69 65 64 2e 20 20 4f 74 68 65 72 20 6b  dified.  Other k
217a0 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65  inds.** of conve
217b0 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69  rsion are done i
217c0 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 69 74 20  n place when it 
217d0 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 62 75 74  is possible, but
217e0 20 73 6f 6d 65 74 69 6d 65 20 69 74 20 69 73 0a   sometime it is.
217f0 2a 2a 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  ** not possible 
21800 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73  and in those cas
21810 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72  es prior pointer
21820 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65  s are invalidate
21830 64 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  d.  .**.** The s
21840 61 66 65 73 74 20 61 6e 64 20 65 61 73 69 65 73  afest and easies
21850 74 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 70 6f  t to remember po
21860 6c 69 63 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b  licy is to invok
21870 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  e these routines
21880 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68  .** in one of th
21890 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73  e following ways
218a0 3a 0a 2a 2a 0a 2a 2a 20 20 3c 75 6c 3e 0a 2a 2a  :.**.**  <ul>.**
218b0 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f    <li>sqlite3_co
218c0 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c  lumn_text() foll
218d0 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  owed by sqlite3_
218e0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f  column_bytes()</
218f0 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69  li>.**  <li>sqli
21900 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
21910 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71  ) followed by sq
21920 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
21930 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c  es()</li>.**  <l
21940 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  i>sqlite3_column
21950 5f 74 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77  _text16() follow
21960 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
21970 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f  lumn_bytes16()</
21980 6c 69 3e 0a 2a 2a 20 20 3c 2f 75 6c 3e 0a 2a 2a  li>.**  </ul>.**
21990 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  .** In other wor
219a0 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20 63  ds, you should c
219b0 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  all sqlite3_colu
219c0 6d 6e 5f 74 65 78 74 28 29 2c 20 73 71 6c 69 74  mn_text(), sqlit
219d0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
219e0 2c 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  ,.** or sqlite3_
219f0 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
21a00 66 69 72 73 74 20 74 6f 20 66 6f 72 63 65 20 74  first to force t
21a10 68 65 20 72 65 73 75 6c 74 20 69 6e 74 6f 20 74  he result into t
21a20 68 65 20 64 65 73 69 72 65 64 0a 2a 2a 20 66 6f  he desired.** fo
21a30 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b  rmat, then invok
21a40 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
21a50 5f 62 79 74 65 73 28 29 20 6f 72 20 73 71 6c 69  _bytes() or sqli
21a60 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
21a70 31 36 28 29 20 74 6f 0a 2a 2a 20 66 69 6e 64 20  16() to.** find 
21a80 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
21a90 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20  result.  Do not 
21aa0 6d 69 78 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  mix call to sqli
21ab0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
21ac0 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ) or.** sqlite3_
21ad0 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69  column_blob() wi
21ae0 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  th calls to sqli
21af0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
21b00 31 36 28 29 2e 20 20 41 6e 64 20 64 6f 20 6e 6f  16().  And do no
21b10 74 0a 2a 2a 20 6d 69 78 20 63 61 6c 6c 73 20 74  t.** mix calls t
21b20 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
21b30 5f 74 65 78 74 31 36 28 29 20 77 69 74 68 20 63  _text16() with c
21b40 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
21b50 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a  column_bytes()..
21b60 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65  **.** The pointe
21b70 72 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20  rs returned are 
21b80 76 61 6c 69 64 20 75 6e 74 69 6c 20 61 20 74 79  valid until a ty
21b90 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63  pe conversion oc
21ba0 63 75 72 73 20 61 73 0a 2a 2a 20 64 65 73 63 72  curs as.** descr
21bb0 69 62 65 64 20 61 62 6f 76 65 2c 20 6f 72 20 75  ibed above, or u
21bc0 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74  ntil [sqlite3_st
21bd0 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ep()] or [sqlite
21be0 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a  3_reset()] or.**
21bf0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
21c00 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e  ze()] is called.
21c10 20 20 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 61    The memory spa
21c20 63 65 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20  ce used to hold 
21c30 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 62  strings.** and b
21c40 6c 6f 62 73 20 69 73 20 66 72 65 65 64 20 61 75  lobs is freed au
21c50 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f  tomatically.  Do
21c60 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 73   <b>not</b> pass
21c70 20 74 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65   the pointers re
21c80 74 75 72 6e 65 64 0a 2a 2a 20 5b 73 71 6c 69 74  turned.** [sqlit
21c90 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
21ca0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ], [sqlite3_colu
21cb0 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 2e  mn_text()], etc.
21cc0 20 69 6e 74 6f 20 0a 2a 2a 20 5b 73 71 6c 69 74   into .** [sqlit
21cd0 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a  e3_free()]..**.*
21ce0 2a 20 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c  * If a memory al
21cf0 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f  location error o
21d00 63 63 75 72 73 20 64 75 72 69 6e 67 20 74 68 65  ccurs during the
21d10 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61   evaluation of a
21d20 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 72  ny.** of these r
21d30 6f 75 74 69 6e 65 73 2c 20 61 20 64 65 66 61 75  outines, a defau
21d40 6c 74 20 76 61 6c 75 65 20 69 73 20 72 65 74 75  lt value is retu
21d50 72 6e 65 64 2e 20 20 54 68 65 20 64 65 66 61 75  rned.  The defau
21d60 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65  lt value.** is e
21d70 69 74 68 65 72 20 74 68 65 20 69 6e 74 65 67 65  ither the intege
21d80 72 20 30 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e  r 0, the floatin
21d90 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30  g point number 0
21da0 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a  .0, or a NULL.**
21db0 20 70 6f 69 6e 74 65 72 2e 20 20 53 75 62 73 65   pointer.  Subse
21dc0 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b  quent calls to [
21dd0 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
21de0 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a  )] will return.*
21df0 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d  * [SQLITE_NOMEM]
21e00 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
21e10 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 30  TS:.**.** {F1380
21e20 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  3} The [sqlite3_
21e30 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 53 2c 4e 29  column_blob(S,N)
21e40 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76  ] interface conv
21e50 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  erts the.**     
21e60 20 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20       Nth column 
21e70 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72  in the current r
21e80 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ow of the result
21e90 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20   set for.**     
21ea0 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73       [prepared s
21eb0 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f  tatement] S into
21ec0 20 61 20 62 6c 6f 62 20 61 6e 64 20 74 68 65 6e   a blob and then
21ed0 20 72 65 74 75 72 6e 73 20 61 0a 2a 2a 20 20 20   returns a.**   
21ee0 20 20 20 20 20 20 20 70 6f 69 6e 74 65 72 20 74         pointer t
21ef0 6f 20 74 68 65 20 63 6f 6e 76 65 72 74 65 64 20  o the converted 
21f00 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  value..**.** {F1
21f10 33 38 30 36 7d 20 54 68 65 20 5b 73 71 6c 69 74  3806} The [sqlit
21f20 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
21f30 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  S,N)] interface 
21f40 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20  returns the.**  
21f50 20 20 20 20 20 20 20 20 6e 75 6d 62 65 72 20 6f          number o
21f60 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 62  f bytes in the b
21f70 6c 6f 62 20 6f 72 20 73 74 72 69 6e 67 20 28 65  lob or string (e
21f80 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65 0a  xclusive of the.
21f90 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f  **          zero
21fa0 20 74 65 72 6d 69 6e 61 74 6f 72 20 6f 6e 20 74   terminator on t
21fb0 68 65 20 73 74 72 69 6e 67 29 20 74 68 61 74 20  he string) that 
21fc0 77 61 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  was returned by 
21fd0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
21fe0 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c  most recent call
21ff0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   to [sqlite3_col
22000 75 6d 6e 5f 62 6c 6f 62 28 53 2c 4e 29 5d 20 6f  umn_blob(S,N)] o
22010 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  r.**          [s
22020 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
22030 78 74 28 53 2c 4e 29 5d 2e 0a 2a 2a 0a 2a 2a 20  xt(S,N)]..**.** 
22040 7b 46 31 33 38 30 39 7d 20 54 68 65 20 5b 73 71  {F13809} The [sq
22050 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
22060 65 73 31 36 28 53 2c 4e 29 5d 20 69 6e 74 65 72  es16(S,N)] inter
22070 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
22080 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 75 6d  .**          num
22090 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
220a0 74 68 65 20 73 74 72 69 6e 67 20 28 65 78 63 6c  the string (excl
220b0 75 73 69 76 65 20 6f 66 20 74 68 65 0a 2a 2a 20  usive of the.** 
220c0 20 20 20 20 20 20 20 20 20 7a 65 72 6f 20 74 65           zero te
220d0 72 6d 69 6e 61 74 6f 72 20 6f 6e 20 74 68 65 20  rminator on the 
220e0 73 74 72 69 6e 67 29 20 74 68 61 74 20 77 61 73  string) that was
220f0 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
22100 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 6f 73  .**          mos
22110 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f  t recent call to
22120 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
22130 5f 74 65 78 74 31 36 28 53 2c 4e 29 5d 2e 0a 2a  _text16(S,N)]..*
22140 2a 0a 2a 2a 20 7b 46 31 33 38 31 32 7d 20 54 68  *.** {F13812} Th
22150 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
22160 6e 5f 64 6f 75 62 6c 65 28 53 2c 4e 29 5d 20 69  n_double(S,N)] i
22170 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74  nterface convert
22180 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
22190 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20    Nth column in 
221a0 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20  the current row 
221b0 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
221c0 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  t for.**        
221d0 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74    [prepared stat
221e0 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20  ement] S into a 
221f0 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76  floating point v
22200 61 6c 75 65 20 61 6e 64 0a 2a 2a 20 20 20 20 20  alue and.**     
22210 20 20 20 20 20 72 65 74 75 72 6e 73 20 61 20 63       returns a c
22220 6f 70 79 20 6f 66 20 74 68 61 74 20 76 61 6c 75  opy of that valu
22230 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 31 35  e..**.** {F13815
22240 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
22250 6f 6c 75 6d 6e 5f 69 6e 74 28 53 2c 4e 29 5d 20  olumn_int(S,N)] 
22260 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72  interface conver
22270 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ts the.**       
22280 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e     Nth column in
22290 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77   the current row
222a0 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
222b0 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20  et for.**       
222c0 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61     [prepared sta
222d0 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61  tement] S into a
222e0 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69   64-bit signed i
222f0 6e 74 65 67 65 72 20 61 6e 64 0a 2a 2a 20 20 20  nteger and.**   
22300 20 20 20 20 20 20 20 72 65 74 75 72 6e 73 20 74         returns t
22310 68 65 20 6c 6f 77 65 72 20 33 32 20 62 69 74 73  he lower 32 bits
22320 20 6f 66 20 74 68 61 74 20 69 6e 74 65 67 65 72   of that integer
22330 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 31 38 7d  ..**.** {F13818}
22340 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
22350 6c 75 6d 6e 5f 69 6e 74 36 34 28 53 2c 4e 29 5d  lumn_int64(S,N)]
22360 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65   interface conve
22370 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  rts the.**      
22380 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69      Nth column i
22390 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f  n the current ro
223a0 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  w of the result 
223b0 73 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20  set for.**      
223c0 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74      [prepared st
223d0 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20  atement] S into 
223e0 61 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  a 64-bit signed 
223f0 69 6e 74 65 67 65 72 20 61 6e 64 0a 2a 2a 20 20  integer and.**  
22400 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 73 20          returns 
22410 61 20 63 6f 70 79 20 6f 66 20 74 68 61 74 20 69  a copy of that i
22420 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46  nteger..**.** {F
22430 31 33 38 32 31 7d 20 54 68 65 20 5b 73 71 6c 69  13821} The [sqli
22440 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
22450 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  S,N)] interface 
22460 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20  converts the.** 
22470 20 20 20 20 20 20 20 20 20 4e 74 68 20 63 6f 6c           Nth col
22480 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65  umn in the curre
22490 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65  nt row of the re
224a0 73 75 6c 74 20 73 65 74 20 66 6f 72 0a 2a 2a 20  sult set for.** 
224b0 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72           [prepar
224c0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
224d0 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d  into a zero-term
224e0 69 6e 61 74 65 64 20 55 54 46 2d 38 20 0a 2a 2a  inated UTF-8 .**
224f0 20 20 20 20 20 20 20 20 20 20 73 74 72 69 6e 67            string
22500 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70   and returns a p
22510 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20 73  ointer to that s
22520 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  tring..**.** {F1
22530 33 38 32 34 7d 20 54 68 65 20 5b 73 71 6c 69 74  3824} The [sqlit
22540 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
22550 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  (S,N)] interface
22560 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a   converts the.**
22570 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 63 6f            Nth co
22580 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72  lumn in the curr
22590 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72  ent row of the r
225a0 65 73 75 6c 74 20 73 65 74 20 66 6f 72 0a 2a 2a  esult set for.**
225b0 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61            [prepa
225c0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
225d0 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72   into a zero-ter
225e0 6d 69 6e 61 74 65 64 20 32 2d 62 79 74 65 0a 2a  minated 2-byte.*
225f0 2a 20 20 20 20 20 20 20 20 20 20 61 6c 69 67 6e  *          align
22600 65 64 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65  ed UTF-16 native
22610 20 62 79 74 65 20 6f 72 64 65 72 0a 2a 2a 20 20   byte order.**  
22620 20 20 20 20 20 20 20 20 73 74 72 69 6e 67 20 61          string a
22630 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  nd returns a poi
22640 6e 74 65 72 20 74 6f 20 74 68 61 74 20 73 74 72  nter to that str
22650 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38  ing..**.** {F138
22660 32 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  27} The [sqlite3
22670 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 53 2c 4e  _column_type(S,N
22680 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
22690 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  urns.**         
226a0 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f   one of [SQLITE_
226b0 4e 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49  NULL], [SQLITE_I
226c0 4e 54 45 47 45 52 5d 2c 20 5b 53 51 4c 49 54 45  NTEGER], [SQLITE
226d0 5f 46 4c 4f 41 54 5d 2c 0a 2a 2a 20 20 20 20 20  _FLOAT],.**     
226e0 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 54 45 58       [SQLITE_TEX
226f0 54 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 42  T], or [SQLITE_B
22700 4c 4f 42 5d 20 61 73 20 61 70 70 72 6f 70 72 69  LOB] as appropri
22710 61 74 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20  ate for.**      
22720 20 20 20 20 74 68 65 20 4e 74 68 20 63 6f 6c 75      the Nth colu
22730 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e  mn in the curren
22740 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73  t row of the res
22750 75 6c 74 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20  ult set for.**  
22760 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65          [prepare
22770 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a  d statement] S..
22780 2a 2a 0a 2a 2a 20 7b 46 31 33 38 33 30 7d 20 54  **.** {F13830} T
22790 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
227a0 6d 6e 5f 76 61 6c 75 65 28 53 2c 4e 29 5d 20 69  mn_value(S,N)] i
227b0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
227c0 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70   a.**          p
227d0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ointer to the [s
227e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
227f0 6a 65 63 74 20 74 68 61 74 20 66 6f 72 20 74 68  ject that for th
22800 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74  e.**          Nt
22810 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20  h column in the 
22820 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74  current row of t
22830 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f  he result set fo
22840 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  r.**          [p
22850 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
22860 74 5d 20 53 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76  t] S..*/.const v
22870 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
22880 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  umn_blob(sqlite3
22890 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
228a0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
228b0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69  olumn_bytes(sqli
228c0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
228d0 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  Col);.int sqlite
228e0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
228f0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
22900 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c  int iCol);.doubl
22910 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
22920 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
22930 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
22940 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
22950 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33  lumn_int(sqlite3
22960 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
22970 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  );.sqlite3_int64
22980 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
22990 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74  int64(sqlite3_st
229a0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
229b0 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63  const unsigned c
229c0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
229d0 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33  umn_text(sqlite3
229e0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
229f0 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
22a00 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
22a10 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  xt16(sqlite3_stm
22a20 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69  t*, int iCol);.i
22a30 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
22a40 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73  n_type(sqlite3_s
22a50 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
22a60 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a  .sqlite3_value *
22a70 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
22a80 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  alue(sqlite3_stm
22a90 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a  t*, int iCol);..
22aa0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
22ab0 44 65 73 74 72 6f 79 20 41 20 50 72 65 70 61 72  Destroy A Prepar
22ac0 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a  ed Statement Obj
22ad0 65 63 74 20 7b 46 31 33 33 30 30 7d 0a 2a 2a 0a  ect {F13300}.**.
22ae0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 66  ** The sqlite3_f
22af0 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69  inalize() functi
22b00 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20  on is called to 
22b10 64 65 6c 65 74 65 20 61 20 0a 2a 2a 20 5b 70 72  delete a .** [pr
22b20 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
22b30 5d 2e 20 49 66 20 74 68 65 20 73 74 61 74 65 6d  ]. If the statem
22b40 65 6e 74 20 77 61 73 0a 2a 2a 20 65 78 65 63 75  ent was.** execu
22b50 74 65 64 20 73 75 63 63 65 73 73 66 75 6c 6c 79  ted successfully
22b60 2c 20 6f 72 20 6e 6f 74 20 65 78 65 63 75 74 65  , or not execute
22b70 64 20 61 74 20 61 6c 6c 2c 20 74 68 65 6e 20 53  d at all, then S
22b80 51 4c 49 54 45 5f 4f 4b 20 69 73 20 72 65 74 75  QLITE_OK is retu
22b90 72 6e 65 64 2e 0a 2a 2a 20 49 66 20 65 78 65 63  rned..** If exec
22ba0 75 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 61  ution of the sta
22bb0 74 65 6d 65 6e 74 20 66 61 69 6c 65 64 20 74 68  tement failed th
22bc0 65 6e 20 61 6e 20 0a 2a 2a 20 5b 65 72 72 6f 72  en an .** [error
22bd0 20 63 6f 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e   code] or [exten
22be0 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 0a  ded error code].
22bf0 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  ** is returned. 
22c00 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
22c10 69 6e 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65  ine can be calle
22c20 64 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 64  d at any point d
22c30 75 72 69 6e 67 20 74 68 65 20 65 78 65 63 75 74  uring the execut
22c40 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 70  ion of the.** [p
22c50 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
22c60 74 5d 2e 20 20 49 66 20 74 68 65 20 76 69 72 74  t].  If the virt
22c70 75 61 6c 20 6d 61 63 68 69 6e 65 20 68 61 73 20  ual machine has 
22c80 6e 6f 74 20 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65  not .** complete
22c90 64 20 65 78 65 63 75 74 69 6f 6e 20 77 68 65 6e  d execution when
22ca0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   this routine is
22cb0 20 63 61 6c 6c 65 64 2c 20 74 68 61 74 20 69 73   called, that is
22cc0 20 6c 69 6b 65 0a 2a 2a 20 65 6e 63 6f 75 6e 74   like.** encount
22cd0 65 72 69 6e 67 20 61 6e 20 65 72 72 6f 72 20 6f  ering an error o
22ce0 72 20 61 6e 20 69 6e 74 65 72 72 75 70 74 2e 20  r an interrupt. 
22cf0 20 28 53 65 65 20 5b 73 71 6c 69 74 65 33 5f 69   (See [sqlite3_i
22d00 6e 74 65 72 72 75 70 74 28 29 5d 2e 29 20 0a 2a  nterrupt()].) .*
22d10 2a 20 49 6e 63 6f 6d 70 6c 65 74 65 20 75 70 64  * Incomplete upd
22d20 61 74 65 73 20 6d 61 79 20 62 65 20 72 6f 6c 6c  ates may be roll
22d30 65 64 20 62 61 63 6b 20 61 6e 64 20 74 72 61 6e  ed back and tran
22d40 73 61 63 74 69 6f 6e 73 20 63 61 6e 63 65 6c 6c  sactions cancell
22d50 65 64 2c 20 20 0a 2a 2a 20 64 65 70 65 6e 64 69  ed,  .** dependi
22d60 6e 67 20 6f 6e 20 74 68 65 20 63 69 72 63 75 6d  ng on the circum
22d70 73 74 61 6e 63 65 73 2c 20 61 6e 64 20 74 68 65  stances, and the
22d80 20 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65   .** [error code
22d90 5d 20 72 65 74 75 72 6e 65 64 20 77 69 6c 6c 20  ] returned will 
22da0 62 65 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54  be [SQLITE_ABORT
22db0 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  ]..**.** INVARIA
22dc0 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 33  NTS:.**.** {F113
22dd0 30 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  02} The [sqlite3
22de0 5f 66 69 6e 61 6c 69 7a 65 28 53 29 5d 20 69 6e  _finalize(S)] in
22df0 74 65 72 66 61 63 65 20 64 65 73 74 72 6f 79 73  terface destroys
22e00 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
22e10 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
22e20 6d 65 6e 74 5d 20 53 20 61 6e 64 20 72 65 6c 65  ment] S and rele
22e30 61 73 65 73 20 61 6c 6c 0a 2a 2a 20 20 20 20 20  ases all.**     
22e40 20 20 20 20 20 6d 65 6d 6f 72 79 20 61 6e 64 20       memory and 
22e50 66 69 6c 65 20 72 65 73 6f 75 72 63 65 73 20 68  file resources h
22e60 65 6c 64 20 62 79 20 74 68 61 74 20 6f 62 6a 65  eld by that obje
22e70 63 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 33 30  ct..**.** {F1130
22e80 34 7d 20 49 66 20 74 68 65 20 6d 6f 73 74 20 72  4} If the most r
22e90 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73  ecent call to [s
22ea0 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
22eb0 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  for the.**      
22ec0 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74      [prepared st
22ed0 61 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 75 72  atement] S retur
22ee0 6e 65 64 20 61 6e 20 65 72 72 6f 72 2c 0a 2a 2a  ned an error,.**
22ef0 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 5b            then [
22f00 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
22f10 28 53 29 5d 20 72 65 74 75 72 6e 73 20 74 68 61  (S)] returns tha
22f20 74 20 73 61 6d 65 20 65 72 72 6f 72 2e 0a 2a 2f  t same error..*/
22f30 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6e  .int sqlite3_fin
22f40 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 74  alize(sqlite3_st
22f50 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
22f60 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73  ** CAPI3REF: Res
22f70 65 74 20 41 20 50 72 65 70 61 72 65 64 20 53 74  et A Prepared St
22f80 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 20 7b  atement Object {
22f90 46 31 33 33 33 30 7d 0a 2a 2a 0a 2a 2a 20 54 68  F13330}.**.** Th
22fa0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28  e sqlite3_reset(
22fb0 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61  ) function is ca
22fc0 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61 20  lled to reset a 
22fd0 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
22fe0 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 2e  atement] object.
22ff0 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 69 74 73 20  .** back to its 
23000 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72  initial state, r
23010 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78  eady to be re-ex
23020 65 63 75 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 53  ecuted..** Any S
23030 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72  QL statement var
23040 69 61 62 6c 65 73 20 74 68 61 74 20 68 61 64 20  iables that had 
23050 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20  values bound to 
23060 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68  them using.** th
23070 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
23080 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62  blob | sqlite3_b
23090 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74  ind_*() API] ret
230a0 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73  ain their values
230b0 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65  ..** Use [sqlite
230c0 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73  3_clear_bindings
230d0 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65  ()] to reset the
230e0 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a   bindings..**.**
230f0 20 7b 46 31 31 33 33 32 7d 20 54 68 65 20 5b 73   {F11332} The [s
23100 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
23110 20 69 6e 74 65 72 66 61 63 65 20 72 65 73 65 74   interface reset
23120 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  s the [prepared 
23130 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20  statement] S.** 
23140 20 20 20 20 20 20 20 20 20 62 61 63 6b 20 74 6f           back to
23150 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f   the beginning o
23160 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a  f its program..*
23170 2a 0a 2a 2a 20 7b 46 31 31 33 33 34 7d 20 49 66  *.** {F11334} If
23180 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
23190 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
231a0 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 0a  3_step(S)] for .
231b0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65  **          [pre
231c0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
231d0 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c   S returned [SQL
231e0 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c  ITE_ROW] or [SQL
231f0 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 20 20  ITE_DONE],.**   
23200 20 20 20 20 20 20 20 6f 72 20 69 66 20 5b 73 71         or if [sq
23210 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68  lite3_step(S)] h
23220 61 73 20 6e 65 76 65 72 20 62 65 66 6f 72 65 20  as never before 
23230 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53  been called on S
23240 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  ,.**          th
23250 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  en [sqlite3_rese
23260 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53  t(S)] returns [S
23270 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a  QLITE_OK]..**.**
23280 20 7b 46 31 31 33 33 36 7d 20 49 66 20 74 68 65   {F11336} If the
23290 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c   most recent cal
232a0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
232b0 65 70 28 53 29 5d 20 66 6f 72 0a 2a 2a 20 20 20  ep(S)] for.**   
232c0 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64         [prepared
232d0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e   statement] S in
232e0 64 69 63 61 74 65 64 20 61 6e 20 65 72 72 6f 72  dicated an error
232f0 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20  , then.**       
23300 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65     [sqlite3_rese
23310 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 61 6e  t(S)] returns an
23320 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72   appropriate [er
23330 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a  ror code]..**.**
23340 20 7b 46 31 31 33 33 38 7d 20 54 68 65 20 5b 73   {F11338} The [s
23350 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
23360 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20   interface does 
23370 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76  not change the v
23380 61 6c 75 65 73 0a 2a 2a 20 20 20 20 20 20 20 20  alues.**        
23390 20 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69 74 65    of any [sqlite
233a0 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64  3_bind_blob|bind
233b0 69 6e 67 73 5d 20 6f 6e 20 5b 70 72 65 70 61 72  ings] on [prepar
233c0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e  ed statement] S.
233d0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
233e0 72 65 73 65 74 28 73 71 6c 69 74 65 33 5f 73 74  reset(sqlite3_st
233f0 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
23400 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 72 65  ** CAPI3REF: Cre
23410 61 74 65 20 4f 72 20 52 65 64 65 66 69 6e 65 20  ate Or Redefine 
23420 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73 20 7b 46  SQL Functions {F
23430 31 36 31 30 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52  16100}.** KEYWOR
23440 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72  DS: {function cr
23450 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d  eation routines}
23460 20 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 74 77   .**.** These tw
23470 6f 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c  o functions (col
23480 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20  lectively known 
23490 61 73 0a 2a 2a 20 22 66 75 6e 63 74 69 6f 6e 20  as.** "function 
234a0 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  creation routine
234b0 73 22 29 20 61 72 65 20 75 73 65 64 20 74 6f 20  s") are used to 
234c0 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  add SQL function
234d0 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 0a  s or aggregates.
234e0 2a 2a 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e  ** or to redefin
234f0 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f  e the behavior o
23500 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66  f existing SQL f
23510 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72  unctions or aggr
23520 65 67 61 74 65 73 2e 20 20 54 68 65 0a 2a 2a 20  egates.  The.** 
23530 64 69 66 66 65 72 65 6e 63 65 20 6f 6e 6c 79 20  difference only 
23540 62 65 74 77 65 65 6e 20 74 68 65 20 74 77 6f 20  between the two 
23550 69 73 20 74 68 61 74 20 74 68 65 20 73 65 63 6f  is that the seco
23560 6e 64 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68  nd parameter, th
23570 65 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20 74 68 65  e.** name of the
23580 20 28 73 63 61 6c 61 72 29 20 66 75 6e 63 74 69   (scalar) functi
23590 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c  on or aggregate,
235a0 20 69 73 20 65 6e 63 6f 64 65 64 20 69 6e 20 55   is encoded in U
235b0 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69  TF-8 for.** sqli
235c0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
235d0 69 6f 6e 28 29 20 61 6e 64 20 55 54 46 2d 31 36  ion() and UTF-16
235e0 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65   for sqlite3_cre
235f0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
23600 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
23610 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  t parameter is t
23620 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
23630 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63  nection] to whic
23640 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e  h the SQL.** fun
23650 63 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 20 61  ction is to be a
23660 64 64 65 64 2e 20 20 49 66 20 61 20 73 69 6e 67  dded.  If a sing
23670 6c 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73  le.** program us
23680 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65  es more than one
23690 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
236a0 63 74 69 6f 6e 5d 20 69 6e 74 65 72 6e 61 6c 6c  ction] internall
236b0 79 2c 20 74 68 65 6e 20 53 51 4c 0a 2a 2a 20 66  y, then SQL.** f
236c0 75 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 65  unctions must be
236d0 20 61 64 64 65 64 20 69 6e 64 69 76 69 64 75 61   added individua
236e0 6c 6c 79 20 74 6f 20 65 61 63 68 20 5b 64 61 74  lly to each [dat
236f0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
23700 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63  ]..**.** The sec
23710 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
23720 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
23730 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f   SQL function to
23740 20 62 65 20 63 72 65 61 74 65 64 0a 2a 2a 20 6f   be created.** o
23750 72 20 72 65 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  r redefined..** 
23760 54 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68  The length of th
23770 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74 65  e name is limite
23780 64 20 74 6f 20 32 35 35 20 62 79 74 65 73 2c 20  d to 255 bytes, 
23790 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65  exclusive of the
237a0 20 0a 2a 2a 20 7a 65 72 6f 2d 74 65 72 6d 69 6e   .** zero-termin
237b0 61 74 6f 72 2e 20 20 4e 6f 74 65 20 74 68 61 74  ator.  Note that
237c0 20 74 68 65 20 6e 61 6d 65 20 6c 65 6e 67 74 68   the name length
237d0 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 62 79 74   limit is in byt
237e0 65 73 2c 20 6e 6f 74 0a 2a 2a 20 63 68 61 72 61  es, not.** chara
237f0 63 74 65 72 73 2e 20 20 41 6e 79 20 61 74 74 65  cters.  Any atte
23800 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20 61 20  mpt to create a 
23810 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20  function with a 
23820 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77  longer name.** w
23830 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 61 6e  ill result in an
23840 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 65 72   SQLITE_ERROR er
23850 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  ror..**.** The t
23860 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69  hird parameter i
23870 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
23880 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 74  arguments that t
23890 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
238a0 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20  or.** aggregate 
238b0 74 61 6b 65 73 2e 20 49 66 20 74 68 69 73 20 70  takes. If this p
238c0 61 72 61 6d 65 74 65 72 20 69 73 20 6e 65 67 61  arameter is nega
238d0 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20 53  tive, then the S
238e0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a  QL function or.*
238f0 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61 79 20  * aggregate may 
23900 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20  take any number 
23910 6f 66 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a  of arguments..**
23920 0a 2a 2a 20 54 68 65 20 66 6f 75 72 74 68 20 70  .** The fourth p
23930 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52  arameter, eTextR
23940 65 70 2c 20 73 70 65 63 69 66 69 65 73 20 77 68  ep, specifies wh
23950 61 74 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55  at .** [SQLITE_U
23960 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64  TF8 | text encod
23970 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75  ing] this SQL fu
23980 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66  nction prefers f
23990 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65  or.** its parame
239a0 74 65 72 73 2e 20 20 41 6e 79 20 53 51 4c 20 66  ters.  Any SQL f
239b0 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
239c0 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65  tation should be
239d0 20 61 62 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a   able to work.**
239e0 20 77 6f 72 6b 20 77 69 74 68 20 55 54 46 2d 38   work with UTF-8
239f0 2c 20 55 54 46 2d 31 36 6c 65 2c 20 6f 72 20 55  , UTF-16le, or U
23a00 54 46 2d 31 36 62 65 2e 20 20 42 75 74 20 73 6f  TF-16be.  But so
23a10 6d 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  me implementatio
23a20 6e 73 20 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f 72  ns may be.** mor
23a30 65 20 65 66 66 69 63 69 65 6e 74 20 77 69 74 68  e efficient with
23a40 20 6f 6e 65 20 65 6e 63 6f 64 69 6e 67 20 74 68   one encoding th
23a50 61 6e 20 61 6e 6f 74 68 65 72 2e 20 20 49 74 20  an another.  It 
23a60 69 73 20 61 6c 6c 6f 77 65 64 20 74 6f 0a 2a 2a  is allowed to.**
23a70 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
23a80 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
23a90 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65  ) or sqlite3_cre
23aa0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
23ab0 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d   multiple.** tim
23ac0 65 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65  es with the same
23ad0 20 66 75 6e 63 74 69 6f 6e 20 62 75 74 20 77 69   function but wi
23ae0 74 68 20 64 69 66 66 65 72 65 6e 74 20 76 61 6c  th different val
23af0 75 65 73 20 6f 66 20 65 54 65 78 74 52 65 70 2e  ues of eTextRep.
23b00 0a 2a 2a 20 57 68 65 6e 20 6d 75 6c 74 69 70 6c  .** When multipl
23b10 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
23b20 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75  s of the same fu
23b30 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c  nction are avail
23b40 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20  able, SQLite.** 
23b50 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e  will pick the on
23b60 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20  e that involves 
23b70 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74  the least amount
23b80 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73   of data convers
23b90 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 72 65  ion..** If there
23ba0 20 69 73 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c   is only a singl
23bb0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
23bc0 20 77 68 69 63 68 20 64 6f 65 73 20 6e 6f 74 20   which does not 
23bd0 63 61 72 65 20 77 68 61 74 0a 2a 2a 20 74 65 78  care what.** tex
23be0 74 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73  t encoding is us
23bf0 65 64 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 75  ed, then the fou
23c00 72 74 68 20 61 72 67 75 6d 65 6e 74 20 73 68 6f  rth argument sho
23c10 75 6c 64 20 62 65 0a 2a 2a 20 5b 53 51 4c 49 54  uld be.** [SQLIT
23c20 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  E_ANY]..**.** Th
23c30 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65  e fifth paramete
23c40 72 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 72  r is an arbitrar
23c50 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20  y pointer.  The 
23c60 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a  implementation.*
23c70 2a 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f  * of the functio
23c80 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63 65 73  n can gain acces
23c90 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 65  s to this pointe
23ca0 72 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  r using.** [sqli
23cb0 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d  te3_user_data()]
23cc0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 76 65  ..**.** The seve
23cd0 6e 74 68 2c 20 65 69 67 68 74 68 20 61 6e 64 20  nth, eighth and 
23ce0 6e 69 6e 74 68 20 70 61 72 61 6d 65 74 65 72 73  ninth parameters
23cf0 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20 61  , xFunc, xStep a
23d00 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a  nd xFinal, are.*
23d10 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d  * pointers to C-
23d20 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69 6f  language functio
23d30 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ns that implemen
23d40 74 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e  t the SQL.** fun
23d50 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61  ction or aggrega
23d60 74 65 2e 20 41 20 73 63 61 6c 61 72 20 53 51 4c  te. A scalar SQL
23d70 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72   function requir
23d80 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  es an implementa
23d90 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 20 78  tion of.** the x
23da0 46 75 6e 63 20 63 61 6c 6c 62 61 63 6b 20 6f 6e  Func callback on
23db0 6c 79 2c 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  ly, NULL pointer
23dc0 73 20 73 68 6f 75 6c 64 20 62 65 20 70 61 73 73  s should be pass
23dd0 65 64 20 61 73 20 74 68 65 20 78 53 74 65 70 0a  ed as the xStep.
23de0 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 70 61  ** and xFinal pa
23df0 72 61 6d 65 74 65 72 73 2e 20 41 6e 20 61 67 67  rameters. An agg
23e00 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74  regate SQL funct
23e10 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20  ion requires an 
23e20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a  implementation.*
23e30 2a 20 6f 66 20 78 53 74 65 70 20 61 6e 64 20 78  * of xStep and x
23e40 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 73  Final and NULL s
23e50 68 6f 75 6c 64 20 62 65 20 70 61 73 73 65 64 20  hould be passed 
23e60 66 6f 72 20 78 46 75 6e 63 2e 20 54 6f 20 64 65  for xFunc. To de
23e70 6c 65 74 65 20 61 6e 0a 2a 2a 20 65 78 69 73 74  lete an.** exist
23e80 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ing SQL function
23e90 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20 70   or aggregate, p
23ea0 61 73 73 20 4e 55 4c 4c 20 66 6f 72 20 61 6c 6c  ass NULL for all
23eb0 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a   three function.
23ec0 2a 2a 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a  ** callback..**.
23ed0 2a 2a 20 49 74 20 69 73 20 70 65 72 6d 69 74 74  ** It is permitt
23ee0 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d  ed to register m
23ef0 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e  ultiple implemen
23f00 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  tations of the s
23f10 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73  ame.** functions
23f20 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e   with the same n
23f30 61 6d 65 20 62 75 74 20 77 69 74 68 20 65 69 74  ame but with eit
23f40 68 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75  her differing nu
23f50 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75  mbers of.** argu
23f60 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69  ments or differi
23f70 6e 67 20 70 65 72 66 65 72 72 65 64 20 74 65 78  ng perferred tex
23f80 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 53 51  t encodings.  SQ
23f90 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a  Lite will use.**
23fa0 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
23fb0 69 6f 6e 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79  ion most closely
23fc0 20 6d 61 74 63 68 65 73 20 74 68 65 20 77 61 79   matches the way
23fd0 20 69 6e 20 77 68 69 63 68 20 74 68 65 0a 2a 2a   in which the.**
23fe0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73   SQL function is
23ff0 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56   used..**.** INV
24000 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
24010 46 31 36 31 30 33 7d 20 54 68 65 20 5b 73 71 6c  F16103} The [sql
24020 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
24030 74 69 6f 6e 31 36 28 29 5d 20 69 6e 74 65 72 66  tion16()] interf
24040 61 63 65 20 62 65 68 61 76 65 73 20 65 78 61 63  ace behaves exac
24050 74 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  tly.**          
24060 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 63 72  like [sqlite3_cr
24070 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
24080 20 69 6e 20 65 76 65 72 79 20 77 61 79 20 65 78   in every way ex
24090 63 65 70 74 20 74 68 61 74 20 69 74 0a 2a 2a 20  cept that it.** 
240a0 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 70 72           interpr
240b0 65 74 73 20 74 68 65 20 7a 46 75 6e 63 74 69 6f  ets the zFunctio
240c0 6e 4e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 61  nName argument a
240d0 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65  s.**          ze
240e0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
240f0 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65  F-16 native byte
24100 20 6f 72 64 65 72 20 69 6e 73 74 65 61 64 20 6f   order instead o
24110 66 20 61 73 20 61 0a 2a 2a 20 20 20 20 20 20 20  f as a.**       
24120 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74     zero-terminat
24130 65 64 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20  ed UTF-8..**.** 
24140 7b 46 31 36 31 30 36 7d 20 41 20 73 75 63 63 65  {F16106} A succe
24150 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e  ssful invocation
24160 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   of.**          
24170 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  the [sqlite3_cre
24180 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58  ate_function(D,X
24190 2c 4e 2c 45 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72  ,N,E,...)] inter
241a0 66 61 63 65 20 72 65 67 69 73 74 65 72 73 0a 2a  face registers.*
241b0 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 72 65  *          or re
241c0 70 6c 61 63 65 73 20 63 61 6c 6c 62 61 63 6b 20  places callback 
241d0 66 75 6e 63 74 69 6f 6e 73 20 69 6e 20 5b 64 61  functions in [da
241e0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
241f0 6e 5d 20 44 0a 2a 2a 20 20 20 20 20 20 20 20 20  n] D.**         
24200 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65   used to impleme
24210 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  nt the SQL funct
24220 69 6f 6e 20 6e 61 6d 65 64 20 58 20 77 69 74 68  ion named X with
24230 20 4e 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a   N parameters.**
24240 20 20 20 20 20 20 20 20 20 20 61 6e 64 20 68 61            and ha
24250 76 69 6e 67 20 61 20 70 65 72 66 65 72 72 65 64  ving a perferred
24260 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 6f   text encoding o
24270 66 20 45 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31  f E..**.** {F161
24280 30 39 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c  09} A successful
24290 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
242a0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
242b0 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c  n(D,X,N,E,P,F,S,
242c0 4c 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  L)].**          
242d0 72 65 70 6c 61 63 65 73 20 74 68 65 20 50 2c 20  replaces the P, 
242e0 46 2c 20 53 2c 20 61 6e 64 20 4c 20 76 61 6c 75  F, S, and L valu
242f0 65 73 20 66 72 6f 6d 20 61 6e 79 20 70 72 69 6f  es from any prio
24300 72 20 63 61 6c 6c 73 20 77 69 74 68 0a 2a 2a 20  r calls with.** 
24310 20 20 20 20 20 20 20 20 20 74 68 65 20 73 61 6d           the sam
24320 65 20 44 2c 20 58 2c 20 4e 2c 20 61 6e 64 20 45  e D, X, N, and E
24330 20 76 61 6c 75 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b   values..**.** {
24340 46 31 36 31 31 32 7d 20 54 68 65 20 5b 73 71 6c  F16112} The [sql
24350 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
24360 74 69 6f 6e 28 44 2c 58 2c 2e 2e 2e 29 5d 20 69  tion(D,X,...)] i
24370 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73 20 77  nterface fails w
24380 69 74 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ith.**          
24390 61 20 72 65 74 75 72 6e 20 63 6f 64 65 20 6f 66  a return code of
243a0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
243b0 69 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  if the SQL funct
243c0 69 6f 6e 20 6e 61 6d 65 20 58 20 69 73 0a 2a 2a  ion name X is.**
243d0 20 20 20 20 20 20 20 20 20 20 6c 6f 6e 67 65 72            longer
243e0 20 74 68 61 6e 20 32 35 35 20 62 79 74 65 73 20   than 255 bytes 
243f0 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65  exclusive of the
24400 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
24410 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 31 38 7d  ..**.** {F16118}
24420 20 45 69 74 68 65 72 20 46 20 6d 75 73 74 20 62   Either F must b
24430 65 20 4e 55 4c 4c 20 61 6e 64 20 53 20 61 6e 64  e NULL and S and
24440 20 4c 20 61 72 65 20 6e 6f 6e 2d 4e 55 4c 4c 20   L are non-NULL 
24450 6f 72 20 65 6c 73 65 20 46 0a 2a 2a 20 20 20 20  or else F.**    
24460 20 20 20 20 20 20 69 73 20 6e 6f 6e 2d 4e 55 4c        is non-NUL
24470 4c 20 61 6e 64 20 53 20 61 6e 64 20 4c 20 61 72  L and S and L ar
24480 65 20 4e 55 4c 4c 2c 20 6f 74 68 65 72 77 69 73  e NULL, otherwis
24490 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  e.**          [s
244a0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
244b0 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50  nction(D,X,N,E,P
244c0 2c 46 2c 53 2c 4c 29 5d 20 72 65 74 75 72 6e 73  ,F,S,L)] returns
244d0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e   [SQLITE_ERROR].
244e0 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 32 31 7d 20  .**.** {F16121} 
244f0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  The [sqlite3_cre
24500 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 2e  ate_function(D,.
24510 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 66  ..)] interface f
24520 61 69 6c 73 20 77 69 74 68 20 61 6e 0a 2a 2a 20  ails with an.** 
24530 20 20 20 20 20 20 20 20 20 65 72 72 6f 72 20 63           error c
24540 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 42  ode of [SQLITE_B
24550 55 53 59 5d 20 69 66 20 74 68 65 72 65 20 65 78  USY] if there ex
24560 69 73 74 20 5b 70 72 65 70 61 72 65 64 20 73 74  ist [prepared st
24570 61 74 65 6d 65 6e 74 73 5d 0a 2a 2a 20 20 20 20  atements].**    
24580 20 20 20 20 20 20 61 73 73 6f 63 69 61 74 65 64        associated
24590 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62   with the [datab
245a0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
245b0 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 32 34  D..**.** {F16124
245c0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
245d0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44  reate_function(D
245e0 2c 58 2c 4e 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72  ,X,N,...)] inter
245f0 66 61 63 65 20 66 61 69 6c 73 20 77 69 74 68 20  face fails with 
24600 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65  an.**          e
24610 72 72 6f 72 20 63 6f 64 65 20 6f 66 20 5b 53 51  rror code of [SQ
24620 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 70  LITE_ERROR] if p
24630 61 72 61 6d 65 74 65 72 20 4e 20 28 73 70 65 63  arameter N (spec
24640 69 66 79 69 6e 67 20 74 68 65 20 6e 75 6d 62 65  ifying the numbe
24650 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66  r.**          of
24660 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
24670 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 62  e SQL function b
24680 65 69 6e 67 20 72 65 67 69 73 74 65 72 65 64 29  eing registered)
24690 20 69 73 20 6c 65 73 73 0a 2a 2a 20 20 20 20 20   is less.**     
246a0 20 20 20 20 20 74 68 61 6e 20 2d 31 20 6f 72 20       than -1 or 
246b0 67 72 65 61 74 65 72 20 74 68 61 6e 20 31 32 37  greater than 127
246c0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 32 37 7d  ..**.** {F16127}
246d0 20 57 68 65 6e 20 4e 20 69 73 20 6e 6f 6e 2d 6e   When N is non-n
246e0 65 67 61 74 69 76 65 2c 20 74 68 65 20 5b 73 71  egative, the [sq
246f0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
24700 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e 29  ction(D,X,N,...)
24710 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  ].**          in
24720 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 63  terface causes c
24730 61 6c 6c 62 61 63 6b 73 20 74 6f 20 62 65 20 69  allbacks to be i
24740 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68 65 20 53  nvoked for the S
24750 51 4c 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20  QL function.**  
24760 20 20 20 20 20 20 20 20 6e 61 6d 65 64 20 58 20          named X 
24770 77 68 65 6e 20 74 68 65 20 6e 75 6d 62 65 72 20  when the number 
24780 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  of arguments to 
24790 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
247a0 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   is.**          
247b0 65 78 61 63 74 6c 79 20 4e 2e 0a 2a 2a 0a 2a 2a  exactly N..**.**
247c0 20 7b 46 31 36 31 33 30 7d 20 57 68 65 6e 20 4e   {F16130} When N
247d0 20 69 73 20 2d 31 2c 20 74 68 65 20 5b 73 71 6c   is -1, the [sql
247e0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
247f0 74 69 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d  tion(D,X,N,...)]
24800 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74  .**          int
24810 65 72 66 61 63 65 20 63 61 75 73 65 73 20 63 61  erface causes ca
24820 6c 6c 62 61 63 6b 73 20 74 6f 20 62 65 20 69 6e  llbacks to be in
24830 76 6f 6b 65 64 20 66 6f 72 20 74 68 65 20 53 51  voked for the SQ
24840 4c 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20  L function.**   
24850 20 20 20 20 20 20 20 6e 61 6d 65 64 20 58 20 77         named X w
24860 69 74 68 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f  ith any number o
24870 66 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a  f arguments..**.
24880 2a 2a 20 7b 46 31 36 31 33 33 7d 20 57 68 65 6e  ** {F16133} When
24890 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
248a0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
248b0 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d 0a 2a  on(D,X,N,...)].*
248c0 2a 20 20 20 20 20 20 20 20 20 20 73 70 65 63 69  *          speci
248d0 66 79 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c  fy multiple impl
248e0 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74  ementations of t
248f0 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e  he same function
24900 20 58 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61   X.**          a
24910 6e 64 20 77 68 65 6e 20 6f 6e 65 20 69 6d 70 6c  nd when one impl
24920 65 6d 65 6e 74 61 74 69 6f 6e 20 68 61 73 20 4e  ementation has N
24930 3e 3d 30 20 61 6e 64 20 74 68 65 20 6f 74 68 65  >=0 and the othe
24940 72 20 68 61 73 20 4e 3d 28 2d 31 29 0a 2a 2a 20  r has N=(-1).** 
24950 20 20 20 20 20 20 20 20 20 74 68 65 20 69 6d 70           the imp
24960 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68  lementation with
24970 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 4e 20 69 73   a non-zero N is
24980 20 70 72 65 66 65 72 72 65 64 2e 0a 2a 2a 0a 2a   preferred..**.*
24990 2a 20 7b 46 31 36 31 33 36 7d 20 57 68 65 6e 20  * {F16136} When 
249a0 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
249b0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
249c0 6e 28 44 2c 58 2c 4e 2c 45 2c 2e 2e 2e 29 5d 0a  n(D,X,N,E,...)].
249d0 2a 2a 20 20 20 20 20 20 20 20 20 20 73 70 65 63  **          spec
249e0 69 66 79 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70  ify multiple imp
249f0 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20  lementations of 
24a00 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f  the same functio
24a10 6e 20 58 20 77 69 74 68 0a 2a 2a 20 20 20 20 20  n X with.**     
24a20 20 20 20 20 20 74 68 65 20 73 61 6d 65 20 6e 75       the same nu
24a30 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
24a40 73 20 4e 20 62 75 74 20 77 69 74 68 20 64 69 66  s N but with dif
24a50 66 65 72 65 6e 74 0a 2a 2a 20 20 20 20 20 20 20  ferent.**       
24a60 20 20 20 65 6e 63 6f 64 69 6e 67 73 20 45 2c 20     encodings E, 
24a70 74 68 65 6e 20 74 68 65 20 69 6d 70 6c 65 6d 65  then the impleme
24a80 6e 74 61 74 69 6f 6e 20 77 68 65 72 65 20 45 20  ntation where E 
24a90 6d 61 74 63 68 65 73 20 74 68 65 0a 2a 2a 20 20  matches the.**  
24aa0 20 20 20 20 20 20 20 20 64 61 74 61 62 61 73 65          database
24ab0 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 70 72 65   encoding is pre
24ac0 66 65 72 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46  ferred..**.** {F
24ad0 31 36 31 33 39 7d 20 46 6f 72 20 61 6e 20 61 67  16139} For an ag
24ae0 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63  gregate SQL func
24af0 74 69 6f 6e 20 63 72 65 61 74 65 64 20 75 73 69  tion created usi
24b00 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ng.**          [
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 30 2c 53 2c 4c 29 5d 20 74 68 65 20 66 69  P,0,S,L)] the fi
24b40 6e 69 61 6c 69 7a 65 72 0a 2a 2a 20 20 20 20 20  nializer.**     
24b50 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 20 4c 20       function L 
24b60 77 69 6c 6c 20 61 6c 77 61 79 73 20 62 65 20 69  will always be i
24b70 6e 76 6f 6b 65 64 20 65 78 61 63 74 6c 79 20 6f  nvoked exactly o
24b80 6e 63 65 20 69 66 20 74 68 65 0a 2a 2a 20 20 20  nce if the.**   
24b90 20 20 20 20 20 20 20 73 74 65 70 20 66 75 6e 63         step func
24ba0 74 69 6f 6e 20 53 20 69 73 20 63 61 6c 6c 65 64  tion S is called
24bb0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d   one or more tim
24bc0 65 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  es..*/.int sqlit
24bd0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
24be0 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  on(.  sqlite3 *d
24bf0 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  b,.  const char 
24c00 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a  *zFunctionName,.
24c10 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e    int nArg,.  in
24c20 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f  t eTextRep,.  vo
24c30 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64  id *pApp,.  void
24c40 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65   (*xFunc)(sqlite
24c50 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
24c60 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
24c70 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29  .  void (*xStep)
24c80 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
24c90 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
24ca0 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
24cb0 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33  *xFinal)(sqlite3
24cc0 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e  _context*).);.in
24cd0 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
24ce0 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73  _function16(.  s
24cf0 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f  qlite3 *db,.  co
24d00 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74  nst void *zFunct
24d10 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e  ionName,.  int n
24d20 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74  Arg,.  int eText
24d30 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70  Rep,.  void *pAp
24d40 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e  p,.  void (*xFun
24d50 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  c)(sqlite3_conte
24d60 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
24d70 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
24d80 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65   (*xStep)(sqlite
24d90 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
24da0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
24db0 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c  .  void (*xFinal
24dc0 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
24dd0 74 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  t*).);../*.** CA
24de0 50 49 33 52 45 46 3a 20 54 65 78 74 20 45 6e 63  PI3REF: Text Enc
24df0 6f 64 69 6e 67 73 20 7b 46 31 30 32 36 37 7d 0a  odings {F10267}.
24e00 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
24e10 74 61 6e 74 20 64 65 66 69 6e 65 20 69 6e 74 65  tant define inte
24e20 67 65 72 20 63 6f 64 65 73 20 74 68 61 74 20 72  ger codes that r
24e30 65 70 72 65 73 65 6e 74 20 74 68 65 20 76 61 72  epresent the var
24e40 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63  ious.** text enc
24e50 6f 64 69 6e 67 73 20 73 75 70 70 6f 72 74 65 64  odings supported
24e60 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23   by SQLite..*/.#
24e70 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
24e80 46 38 20 20 20 20 20 20 20 20 20 20 20 31 0a 23  F8           1.#
24e90 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
24ea0 46 31 36 4c 45 20 20 20 20 20 20 20 20 32 0a 23  F16LE        2.#
24eb0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
24ec0 46 31 36 42 45 20 20 20 20 20 20 20 20 33 0a 23  F16BE        3.#
24ed0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
24ee0 46 31 36 20 20 20 20 20 20 20 20 20 20 34 20 20  F16          4  
24ef0 20 20 2f 2a 20 55 73 65 20 6e 61 74 69 76 65 20    /* Use native 
24f00 62 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64  byte order */.#d
24f10 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59  efine SQLITE_ANY
24f20 20 20 20 20 20 20 20 20 20 20 20 20 35 20 20 20              5   
24f30 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61   /* sqlite3_crea
24f40 74 65 5f 66 75 6e 63 74 69 6f 6e 20 6f 6e 6c 79  te_function only
24f50 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
24f60 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44  TE_UTF16_ALIGNED
24f70 20 20 38 20 20 20 20 2f 2a 20 73 71 6c 69 74 65    8    /* sqlite
24f80 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
24f90 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a  on only */../*.*
24fa0 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 73 6f  * CAPI3REF: Obso
24fb0 6c 65 74 65 20 46 75 6e 63 74 69 6f 6e 73 0a 2a  lete Functions.*
24fc0 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74  *.** These funct
24fd0 69 6f 6e 73 20 61 72 65 20 61 6c 6c 20 6e 6f 77  ions are all now
24fe0 20 6f 62 73 6f 6c 65 74 65 2e 20 20 49 6e 20 6f   obsolete.  In o
24ff0 72 64 65 72 20 74 6f 20 6d 61 69 6e 74 61 69 6e  rder to maintain
25000 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f  .** backwards co
25010 6d 70 61 74 69 62 69 6c 69 74 79 20 77 69 74 68  mpatibility with
25020 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20 77 65 20   older code, we 
25030 63 6f 6e 74 69 6e 75 65 20 74 6f 20 73 75 70 70  continue to supp
25040 6f 72 74 0a 2a 2a 20 74 68 65 73 65 20 66 75 6e  ort.** these fun
25050 63 74 69 6f 6e 73 2e 20 20 48 6f 77 65 76 65 72  ctions.  However
25060 2c 20 6e 65 77 20 64 65 76 65 6c 6f 70 6d 65 6e  , new developmen
25070 74 20 70 72 6f 6a 65 63 74 73 20 73 68 6f 75 6c  t projects shoul
25080 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75  d avoid.** the u
25090 73 65 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63  se of these func
250a0 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70 20  tions.  To help 
250b0 65 6e 63 6f 75 72 61 67 65 20 70 65 6f 70 6c 65  encourage people
250c0 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73 69   to avoid.** usi
250d0 6e 67 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  ng these functio
250e0 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f 74 20 67  ns, we are not g
250f0 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f 75  oing to tell you
25100 20 77 61 6e 74 20 74 68 65 79 20 64 6f 2e 0a 2a   want they do..*
25110 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 67  /.int sqlite3_ag
25120 67 72 65 67 61 74 65 5f 63 6f 75 6e 74 28 73 71  gregate_count(sq
25130 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
25140 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 70  .int sqlite3_exp
25150 69 72 65 64 28 73 71 6c 69 74 65 33 5f 73 74 6d  ired(sqlite3_stm
25160 74 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  t*);.int sqlite3
25170 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e  _transfer_bindin
25180 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  gs(sqlite3_stmt*
25190 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  , sqlite3_stmt*)
251a0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 6c  ;.int sqlite3_gl
251b0 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28 76 6f 69  obal_recover(voi
251c0 64 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  d);.void sqlite3
251d0 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e 75 70 28  _thread_cleanup(
251e0 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74  void);.int sqlit
251f0 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28  e3_memory_alarm(
25200 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71  void(*)(void*,sq
25210 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29  lite3_int64,int)
25220 2c 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69  ,void*,sqlite3_i
25230 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt64);../*.** CA
25240 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e  PI3REF: Obtainin
25250 67 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 50  g SQL Function P
25260 61 72 61 6d 65 74 65 72 20 56 61 6c 75 65 73 20  arameter Values 
25270 7b 46 31 35 31 30 30 7d 0a 2a 2a 0a 2a 2a 20 54  {F15100}.**.** T
25280 68 65 20 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d  he C-language im
25290 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
252a0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e  SQL functions an
252b0 64 20 61 67 67 72 65 67 61 74 65 73 20 75 73 65  d aggregates use
252c0 73 0a 2a 2a 20 74 68 69 73 20 73 65 74 20 6f 66  s.** this set of
252d0 20 69 6e 74 65 72 66 61 63 65 20 72 6f 75 74 69   interface routi
252e0 6e 65 73 20 74 6f 20 61 63 63 65 73 73 20 74 68  nes to access th
252f0 65 20 70 61 72 61 6d 65 74 65 72 20 76 61 6c 75  e parameter valu
25300 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e  es on.** the fun
25310 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61  ction or aggrega
25320 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46  te..**.** The xF
25330 75 6e 63 20 28 66 6f 72 20 73 63 61 6c 61 72 20  unc (for scalar 
25340 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78 53  functions) or xS
25350 74 65 70 20 28 66 6f 72 20 61 67 67 72 65 67 61  tep (for aggrega
25360 74 65 73 29 20 70 61 72 61 6d 65 74 65 72 73 0a  tes) parameters.
25370 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ** to [sqlite3_c
25380 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
25390 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
253a0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
253b0 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61  ()].** define ca
253c0 6c 6c 62 61 63 6b 73 20 74 68 61 74 20 69 6d 70  llbacks that imp
253d0 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66  lement the SQL f
253e0 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67  unctions and agg
253f0 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20  regates..** The 
25400 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
25410 20 74 68 65 73 65 20 63 61 6c 6c 62 61 63 6b 73   these callbacks
25420 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20   is an array of 
25430 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b  pointers to.** [
25440 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
25450 62 6a 65 63 74 73 2e 20 20 54 68 65 72 65 20 69  bjects.  There i
25460 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f 76  s one [sqlite3_v
25470 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72  alue] object for
25480 0a 2a 2a 20 65 61 63 68 20 70 61 72 61 6d 65 74  .** each paramet
25490 65 72 20 74 6f 20 74 68 65 20 53 51 4c 20 66 75  er to the SQL fu
254a0 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73 65 20 72  nction.  These r
254b0 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64  outines are used
254c0 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20 76   to.** extract v
254d0 61 6c 75 65 73 20 66 72 6f 6d 20 74 68 65 20 5b  alues from the [
254e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
254f0 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  bjects..**.** Th
25500 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72  ese routines wor
25510 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 20  k just like the 
25520 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 0a 2a  corresponding .*
25530 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
25540 6e 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33  n_blob | sqlite3
25550 5f 63 6f 6c 75 6d 6e 5f 2a 20 72 6f 75 74 69 6e  _column_* routin
25560 65 73 5d 20 65 78 63 65 70 74 20 74 68 61 74 20  es] except that 
25570 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75 74 69 6e  .** these routin
25580 65 73 20 74 61 6b 65 20 61 20 73 69 6e 67 6c 65  es take a single
25590 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a   [sqlite3_value*
255a0 5d 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61  ] pointer instea
255b0 64 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69  d.** of an [sqli
255c0 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74  te3_stmt*] point
255d0 65 72 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 65  er and an intege
255e0 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e  r column number.
255f0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
25600 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
25610 29 20 69 6e 74 65 72 66 61 63 65 20 65 78 74 72  ) interface extr
25620 61 63 74 73 20 61 20 55 54 46 31 36 20 73 74 72  acts a UTF16 str
25630 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61  ing.** in the na
25640 74 69 76 65 20 62 79 74 65 2d 6f 72 64 65 72 20  tive byte-order 
25650 6f 66 20 74 68 65 20 68 6f 73 74 20 6d 61 63 68  of the host mach
25660 69 6e 65 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c  ine.  The.** sql
25670 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
25680 36 62 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  6be() and sqlite
25690 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65  3_value_text16le
256a0 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  () interfaces.**
256b0 20 65 78 74 72 61 63 74 20 55 54 46 31 36 20 73   extract UTF16 s
256c0 74 72 69 6e 67 73 20 61 73 20 62 69 67 2d 65 6e  trings as big-en
256d0 64 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d  dian and little-
256e0 65 6e 64 69 61 6e 20 72 65 73 70 65 63 74 69 76  endian respectiv
256f0 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ely..**.** The s
25700 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d  qlite3_value_num
25710 65 72 69 63 5f 74 79 70 65 28 29 20 69 6e 74 65  eric_type() inte
25720 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74  rface attempts t
25730 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72  o apply.** numer
25740 69 63 20 61 66 66 69 6e 69 74 79 20 74 6f 20 74  ic affinity to t
25750 68 65 20 76 61 6c 75 65 2e 20 20 54 68 69 73 20  he value.  This 
25760 6d 65 61 6e 73 20 74 68 61 74 20 61 6e 20 61 74  means that an at
25770 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65  tempt is.** made
25780 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20   to convert the 
25790 76 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74 65  value to an inte
257a0 67 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20  ger or floating 
257b0 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75  point.  If.** su
257c0 63 68 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20  ch a conversion 
257d0 69 73 20 70 6f 73 73 69 62 6c 65 20 77 69 74 68  is possible with
257e0 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f  out loss of info
257f0 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65  rmation (in othe
25800 72 0a 2a 2a 20 77 6f 72 64 73 20 69 66 20 74 68  r.** words if th
25810 65 20 76 61 6c 75 65 20 69 73 20 61 20 73 74 72  e value is a str
25820 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c  ing that looks l
25830 69 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a  ike a number).**
25840 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 76 65 72   then the conver
25850 73 69 6f 6e 20 69 73 20 64 6f 6e 65 2e 20 20 4f  sion is done.  O
25860 74 68 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76  therwise no conv
25870 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e 20 20  ersion occurs.  
25880 54 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  The .** [SQLITE_
25890 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79  INTEGER | dataty
258a0 70 65 5d 20 61 66 74 65 72 20 63 6f 6e 76 65 72  pe] after conver
258b0 73 69 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 64  sion is returned
258c0 2e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70  ..**.** Please p
258d0 61 79 20 70 61 72 74 69 63 75 6c 61 72 20 61 74  ay particular at
258e0 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20 66  tention to the f
258f0 61 63 74 20 74 68 61 74 20 74 68 65 20 70 6f 69  act that the poi
25900 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20  nter that.** is 
25910 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73  returned from [s
25920 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f  qlite3_value_blo
25930 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76  b()], [sqlite3_v
25940 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72  alue_text()], or
25950 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  .** [sqlite3_val
25960 75 65 5f 74 65 78 74 31 36 28 29 5d 20 63 61 6e  ue_text16()] can
25970 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 20   be invalidated 
25980 62 79 20 61 20 73 75 62 73 65 71 75 65 6e 74 20  by a subsequent 
25990 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
259a0 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28  te3_value_bytes(
259b0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  )], [sqlite3_val
259c0 75 65 5f 62 79 74 65 73 31 36 28 29 5d 2c 20 5b  ue_bytes16()], [
259d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
259e0 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71  xt()],.** or [sq
259f0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
25a00 31 36 28 29 5d 2e 20 20 0a 2a 2a 0a 2a 2a 20 54  16()].  .**.** T
25a10 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75  hese routines mu
25a20 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f  st be called fro
25a30 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  m the same threa
25a40 64 20 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20  d as.** the SQL 
25a50 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 73 75  function that su
25a60 70 70 6c 69 65 64 20 74 68 65 20 73 71 6c 69 74  pplied the sqlit
25a70 65 33 5f 76 61 6c 75 65 2a 20 70 61 72 61 6d 65  e3_value* parame
25a80 74 65 72 73 2e 0a 2a 2a 20 4f 72 2c 20 69 66 20  ters..** Or, if 
25a90 74 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  the sqlite3_valu
25aa0 65 2a 20 61 72 67 75 6d 65 6e 74 20 63 6f 6d 65  e* argument come
25ab0 73 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69  s from the [sqli
25ac0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
25ad0 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ()].** interface
25ae0 2c 20 74 68 65 6e 20 74 68 65 73 65 20 72 6f 75  , then these rou
25af0 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 20  tines should be 
25b00 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
25b10 73 61 6d 65 20 74 68 72 65 61 64 0a 2a 2a 20 74  same thread.** t
25b20 68 61 74 20 72 61 6e 20 5b 73 71 6c 69 74 65 33  hat ran [sqlite3
25b30 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d  _column_value()]
25b40 2e 0a 2a 2a 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ..**.**.** INVAR
25b50 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31  IANTS:.**.** {F1
25b60 35 31 30 33 7d 20 54 68 65 20 5b 73 71 6c 69 74  5103} The [sqlit
25b70 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 56 29  e3_value_blob(V)
25b80 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76  ] interface conv
25b90 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  erts the.**     
25ba0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 76 61       [sqlite3_va
25bb0 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e  lue] object V in
25bc0 74 6f 20 61 20 62 6c 6f 62 20 61 6e 64 20 74 68  to a blob and th
25bd0 65 6e 20 72 65 74 75 72 6e 73 20 61 0a 2a 2a 20  en returns a.** 
25be0 20 20 20 20 20 20 20 20 20 70 6f 69 6e 74 65 72           pointer
25bf0 20 74 6f 20 74 68 65 20 63 6f 6e 76 65 72 74 65   to the converte
25c00 64 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b  d value..**.** {
25c10 46 31 35 31 30 36 7d 20 54 68 65 20 5b 73 71 6c  F15106} The [sql
25c20 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
25c30 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  (V)] interface r
25c40 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20  eturns the.**   
25c50 20 20 20 20 20 20 20 6e 75 6d 62 65 72 20 6f 66         number of
25c60 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 62 6c   bytes in the bl
25c70 6f 62 20 6f 72 20 73 74 72 69 6e 67 20 28 65 78  ob or string (ex
25c80 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65 0a 2a  clusive of the.*
25c90 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 20  *          zero 
25ca0 74 65 72 6d 69 6e 61 74 6f 72 20 6f 6e 20 74 68  terminator on th
25cb0 65 20 73 74 72 69 6e 67 29 20 74 68 61 74 20 77  e string) that w
25cc0 61 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  as returned by t
25cd0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d  he.**          m
25ce0 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
25cf0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  to [sqlite3_valu
25d00 65 5f 62 6c 6f 62 28 56 29 5d 20 6f 72 0a 2a 2a  e_blob(V)] or.**
25d10 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
25d20 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 56 29  e3_value_text(V)
25d30 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31 30 39  ]..**.** {F15109
25d40 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  } The [sqlite3_v
25d50 61 6c 75 65 5f 62 79 74 65 73 31 36 28 56 29 5d  alue_bytes16(V)]
25d60 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
25d70 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ns the.**       
25d80 20 20 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74     number of byt
25d90 65 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67  es in the string
25da0 20 28 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74   (exclusive of t
25db0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a  he.**          z
25dc0 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 6f  ero terminator o
25dd0 6e 20 74 68 65 20 73 74 72 69 6e 67 29 20 74 68  n the string) th
25de0 61 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 20  at was returned 
25df0 62 79 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  by the.**       
25e00 20 20 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63     most recent c
25e10 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
25e20 76 61 6c 75 65 5f 74 65 78 74 31 36 28 56 29 5d  value_text16(V)]
25e30 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  ,.**          [s
25e40 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
25e50 74 31 36 62 65 28 56 29 5d 2c 20 6f 72 20 5b 73  t16be(V)], or [s
25e60 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
25e70 74 31 36 6c 65 28 56 29 5d 2e 0a 2a 2a 0a 2a 2a  t16le(V)]..**.**
25e80 20 7b 46 31 35 31 31 32 7d 20 54 68 65 20 5b 73   {F15112} The [s
25e90 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75  qlite3_value_dou
25ea0 62 6c 65 28 56 29 5d 20 69 6e 74 65 72 66 61 63  ble(V)] interfac
25eb0 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a  e converts the.*
25ec0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
25ed0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
25ee0 74 20 56 20 69 6e 74 6f 20 61 20 66 6c 6f 61 74  t V into a float
25ef0 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20  ing point value 
25f00 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  and.**          
25f10 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f  returns a copy o
25f20 66 20 74 68 61 74 20 76 61 6c 75 65 2e 0a 2a 2a  f that value..**
25f30 0a 2a 2a 20 7b 46 31 35 31 31 35 7d 20 54 68 65  .** {F15115} The
25f40 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
25f50 69 6e 74 28 56 29 5d 20 69 6e 74 65 72 66 61 63  int(V)] interfac
25f60 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a  e converts the.*
25f70 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
25f80 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
25f90 74 20 56 20 69 6e 74 6f 20 61 20 36 34 2d 62 69  t V into a 64-bi
25fa0 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
25fb0 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20   and.**         
25fc0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6c 6f 77   returns the low
25fd0 65 72 20 33 32 20 62 69 74 73 20 6f 66 20 74 68  er 32 bits of th
25fe0 61 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a  at integer..**.*
25ff0 2a 20 7b 46 31 35 31 31 38 7d 20 54 68 65 20 5b  * {F15118} The [
26000 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e  sqlite3_value_in
26010 74 36 34 28 56 29 5d 20 69 6e 74 65 72 66 61 63  t64(V)] interfac
26020 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a  e converts the.*
26030 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
26040 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
26050 74 20 56 20 69 6e 74 6f 20 61 20 36 34 2d 62 69  t V into a 64-bi
26060 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
26070 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20   and.**         
26080 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20   returns a copy 
26090 6f 66 20 74 68 61 74 20 69 6e 74 65 67 65 72 2e  of that integer.
260a0 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31 32 31 7d 20  .**.** {F15121} 
260b0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  The [sqlite3_val
260c0 75 65 5f 74 65 78 74 28 56 29 5d 20 69 6e 74 65  ue_text(V)] inte
260d0 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74  rface converts t
260e0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
260f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
26100 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20 7a  bject V into a z
26110 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
26120 54 46 2d 38 20 0a 2a 2a 20 20 20 20 20 20 20 20  TF-8 .**        
26130 20 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74    string and ret
26140 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
26150 6f 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a  o that string..*
26160 2a 0a 2a 2a 20 7b 46 31 35 31 32 34 7d 20 54 68  *.** {F15124} Th
26170 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
26180 5f 74 65 78 74 31 36 28 56 29 5d 20 69 6e 74 65  _text16(V)] inte
26190 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74  rface converts t
261a0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
261b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
261c0 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20 7a  bject V into a z
261d0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 32  ero-terminated 2
261e0 2d 62 79 74 65 0a 2a 2a 20 20 20 20 20 20 20 20  -byte.**        
261f0 20 20 61 6c 69 67 6e 65 64 20 55 54 46 2d 31 36    aligned UTF-16
26200 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
26210 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73  er.**          s
26220 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e  tring and return
26230 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
26240 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  hat string..**.*
26250 2a 20 7b 46 31 35 31 32 37 7d 20 54 68 65 20 5b  * {F15127} The [
26260 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
26270 78 74 31 36 62 65 28 56 29 5d 20 69 6e 74 65 72  xt16be(V)] inter
26280 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68  face converts th
26290 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  e.**          [s
262a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
262b0 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20 7a 65  ject V into a ze
262c0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 32 2d  ro-terminated 2-
262d0 62 79 74 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  byte.**         
262e0 20 61 6c 69 67 6e 65 64 20 55 54 46 2d 31 36 20   aligned UTF-16 
262f0 62 69 67 2d 65 6e 64 69 61 6e 0a 2a 2a 20 20 20  big-endian.**   
26300 20 20 20 20 20 20 20 73 74 72 69 6e 67 20 61 6e         string an
26310 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  d returns a poin
26320 74 65 72 20 74 6f 20 74 68 61 74 20 73 74 72 69  ter to that stri
26330 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31 33  ng..**.** {F1513
26340 30 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  0} The [sqlite3_
26350 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 56  value_text16le(V
26360 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e  )] interface con
26370 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20  verts the.**    
26380 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 76        [sqlite3_v
26390 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69  alue] object V i
263a0 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69  nto a zero-termi
263b0 6e 61 74 65 64 20 32 2d 62 79 74 65 0a 2a 2a 20  nated 2-byte.** 
263c0 20 20 20 20 20 20 20 20 20 61 6c 69 67 6e 65 64           aligned
263d0 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 2d 65   UTF-16 little-e
263e0 6e 64 69 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20  ndian.**        
263f0 20 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74    string and ret
26400 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
26410 6f 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a  o that string..*
26420 2a 0a 2a 2a 20 7b 46 31 35 31 33 33 7d 20 54 68  *.** {F15133} Th
26430 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
26440 5f 74 79 70 65 28 56 29 5d 20 69 6e 74 65 72 66  _type(V)] interf
26450 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20  ace returns.**  
26460 20 20 20 20 20 20 20 20 6f 6e 65 20 6f 66 20 5b          one of [
26470 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2c 20 5b 53  SQLITE_NULL], [S
26480 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 20  QLITE_INTEGER], 
26490 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 0a  [SQLITE_FLOAT],.
264a0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c  **          [SQL
264b0 49 54 45 5f 54 45 58 54 5d 2c 20 6f 72 20 5b 53  ITE_TEXT], or [S
264c0 51 4c 49 54 45 5f 42 4c 4f 42 5d 20 61 73 20 61  QLITE_BLOB] as a
264d0 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72 0a 2a  ppropriate for.*
264e0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b  *          the [
264f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
26500 62 6a 65 63 74 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b  bject V..**.** {
26510 46 31 35 31 33 36 7d 20 54 68 65 20 5b 73 71 6c  F15136} The [sql
26520 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72  ite3_value_numer
26530 69 63 5f 74 79 70 65 28 56 29 5d 20 69 6e 74 65  ic_type(V)] inte
26540 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 0a 2a  rface converts.*
26550 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b  *          the [
26560 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
26570 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 65 69 74  bject V into eit
26580 68 65 72 20 61 6e 20 69 6e 74 65 67 65 72 20 6f  her an integer o
26590 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20  r.**          a 
265a0 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76  floating point v
265b0 61 6c 75 65 20 69 66 20 69 74 20 63 61 6e 20 64  alue if it can d
265c0 6f 20 73 6f 20 77 69 74 68 6f 75 74 20 6c 6f 73  o so without los
265d0 73 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20  s of.**         
265e0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2c 20 61 6e   information, an
265f0 64 20 72 65 74 75 72 6e 73 20 6f 6e 65 20 6f 66  d returns one of
26600 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2c 0a   [SQLITE_NULL],.
26610 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c  **          [SQL
26620 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 20 5b 53  ITE_INTEGER], [S
26630 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53  QLITE_FLOAT], [S
26640 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 6f 72 0a  QLITE_TEXT], or.
26650 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c  **          [SQL
26660 49 54 45 5f 42 4c 4f 42 5d 20 61 73 20 61 70 70  ITE_BLOB] as app
26670 72 6f 70 72 69 61 74 65 20 66 6f 72 0a 2a 2a 20  ropriate for.** 
26680 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 73 71           the [sq
26690 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
266a0 65 63 74 20 56 20 61 66 74 65 72 20 74 68 65 20  ect V after the 
266b0 63 6f 6e 76 65 72 73 69 6f 6e 20 61 74 74 65 6d  conversion attem
266c0 70 74 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69  pt..*/.const voi
266d0 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  d *sqlite3_value
266e0 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 76 61  _blob(sqlite3_va
266f0 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
26700 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 73  e3_value_bytes(s
26710 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
26720 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
26730 65 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65  e_bytes16(sqlite
26740 33 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f 75 62 6c  3_value*);.doubl
26750 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  e sqlite3_value_
26760 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 76  double(sqlite3_v
26770 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
26780 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 73 71  te3_value_int(sq
26790 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 73  lite3_value*);.s
267a0 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
267b0 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34  ite3_value_int64
267c0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
267d0 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64  ;.const unsigned
267e0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76   char *sqlite3_v
267f0 61 6c 75 65 5f 74 65 78 74 28 73 71 6c 69 74 65  alue_text(sqlite
26800 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74  3_value*);.const
26810 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76   void *sqlite3_v
26820 61 6c 75 65 5f 74 65 78 74 31 36 28 73 71 6c 69  alue_text16(sqli
26830 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e  te3_value*);.con
26840 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
26850 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28  _value_text16le(
26860 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
26870 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
26880 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
26890 36 62 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  6be(sqlite3_valu
268a0 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
268b0 5f 76 61 6c 75 65 5f 74 79 70 65 28 73 71 6c 69  _value_type(sqli
268c0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
268d0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e   sqlite3_value_n
268e0 75 6d 65 72 69 63 5f 74 79 70 65 28 73 71 6c 69  umeric_type(sqli
268f0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a  te3_value*);../*
26900 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62  .** CAPI3REF: Ob
26910 74 61 69 6e 20 41 67 67 72 65 67 61 74 65 20 46  tain Aggregate F
26920 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20  unction Context 
26930 7b 46 31 36 32 31 30 7d 0a 2a 2a 0a 2a 2a 20 54  {F16210}.**.** T
26940 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
26950 6e 20 6f 66 20 61 67 67 72 65 67 61 74 65 20 53  n of aggregate S
26960 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65  QL functions use
26970 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f   this routine to
26980 20 61 6c 6c 6f 63 61 74 65 0a 2a 2a 20 61 20 73   allocate.** a s
26990 74 72 75 63 74 75 72 65 20 66 6f 72 20 73 74 6f  tructure for sto
269a0 72 69 6e 67 20 74 68 65 69 72 20 73 74 61 74 65  ring their state
269b0 2e 20 20 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .  .** The first
269c0 20 74 69 6d 65 20 74 68 65 20 73 71 6c 69 74 65   time the sqlite
269d0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
269e0 65 78 74 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ext() routine is
269f0 0a 2a 2a 20 69 73 20 63 61 6c 6c 65 64 20 66 6f  .** is called fo
26a00 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 61  r a particular a
26a10 67 67 72 65 67 61 74 65 2c 20 53 51 4c 69 74 65  ggregate, SQLite
26a20 20 61 6c 6c 6f 63 61 74 65 73 20 6e 42 79 74 65   allocates nByte
26a30 73 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 7a  s of memory.** z
26a40 65 72 6f 73 20 74 68 61 74 20 6d 65 6d 6f 72 79  eros that memory
26a50 2c 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20  , and returns a 
26a60 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 2e 0a 2a  pointer to it..*
26a70 2a 20 4f 6e 20 73 65 63 6f 6e 64 20 61 6e 64 20  * On second and 
26a80 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
26a90 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67 67 72   to sqlite3_aggr
26aa0 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 0a  egate_context().
26ab0 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  ** for the same 
26ac0 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69  aggregate functi
26ad0 6f 6e 20 69 6e 64 65 78 2c 20 74 68 65 20 73 61  on index, the sa
26ae0 6d 65 20 62 75 66 66 65 72 20 69 73 20 72 65 74  me buffer is ret
26af0 75 72 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 69 6d  urned..** The im
26b00 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20  plementation.** 
26b10 6f 66 20 74 68 65 20 61 67 67 72 65 67 61 74 65  of the aggregate
26b20 20 63 61 6e 20 75 73 65 20 74 68 65 20 72 65 74   can use the ret
26b30 75 72 6e 65 64 20 62 75 66 66 65 72 20 74 6f 20  urned buffer to 
26b40 61 63 63 75 6d 75 6c 61 74 65 20 64 61 74 61 2e  accumulate data.
26b50 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 61 75  .**.** SQLite au
26b60 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65  tomatically free
26b70 73 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20  s the allocated 
26b80 62 75 66 66 65 72 20 77 68 65 6e 20 74 68 65 20  buffer when the 
26b90 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 71 75 65  aggregate.** que
26ba0 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a  ry concludes..**
26bb0 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61  .** The first pa
26bc0 72 61 6d 65 74 65 72 20 73 68 6f 75 6c 64 20 62  rameter should b
26bd0 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  e a copy of the 
26be0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
26bf0 74 65 78 74 20 7c 20 53 51 4c 20 66 75 6e 63 74  text | SQL funct
26c00 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68 61  ion context] tha
26c10 74 20 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a  t is the first.*
26c20 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  * parameter to t
26c30 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74  he callback rout
26c40 69 6e 65 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  ine that impleme
26c50 6e 74 73 20 74 68 65 20 61 67 67 72 65 67 61 74  nts the aggregat
26c60 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  e.** function..*
26c70 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
26c80 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  e must be called
26c90 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74   from the same t
26ca0 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a  hread in which.*
26cb0 2a 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20  * the aggregate 
26cc0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  SQL function is 
26cd0 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49  running..**.** I
26ce0 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
26cf0 20 7b 46 31 36 32 31 31 7d 20 54 68 65 20 66 69   {F16211} The fi
26d00 72 73 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  rst invocation o
26d10 66 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65  f [sqlite3_aggre
26d20 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e  gate_context(C,N
26d30 29 5d 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20  )] for.**       
26d40 20 20 20 61 20 70 61 72 74 69 63 75 6c 61 72 20     a particular 
26d50 69 6e 73 74 61 6e 63 65 20 6f 66 20 61 6e 20 61  instance of an a
26d60 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f  ggregate functio
26d70 6e 20 28 66 6f 72 20 61 20 70 61 72 74 69 63 75  n (for a particu
26d80 6c 61 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  lar.**          
26d90 63 6f 6e 74 65 78 74 20 43 29 20 63 61 75 73 65  context C) cause
26da0 73 20 53 51 4c 69 74 65 20 74 6f 20 61 6c 6c 6f  s SQLite to allo
26db0 63 61 74 69 6f 6e 20 4e 20 62 79 74 65 73 20 6f  cation N bytes o
26dc0 66 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 20 20 20  f memory,.**    
26dd0 20 20 20 20 20 20 7a 65 72 6f 20 74 68 61 74 20        zero that 
26de0 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 75  memory, and retu
26df0 72 6e 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  rn a pointer to 
26e00 74 68 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 65 64  the allocationed
26e10 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 65 6d  .**          mem
26e20 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32  ory..**.** {F162
26e30 31 33 7d 20 49 66 20 61 20 6d 65 6d 6f 72 79 20  13} If a memory 
26e40 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72  allocation error
26e50 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 0a 2a   occurs during.*
26e60 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
26e70 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
26e80 6e 74 65 78 74 28 43 2c 4e 29 5d 20 74 68 65 6e  ntext(C,N)] then
26e90 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 72 65   the function re
26ea0 74 75 72 6e 73 20 30 2e 0a 2a 2a 0a 2a 2a 20 7b  turns 0..**.** {
26eb0 46 31 36 32 31 35 7d 20 53 65 63 6f 6e 64 20 61  F16215} Second a
26ec0 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e  nd subsequent in
26ed0 76 6f 63 61 74 69 6f 6e 73 20 6f 66 0a 2a 2a 20  vocations of.** 
26ee0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
26ef0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
26f00 65 78 74 28 43 2c 4e 29 5d 20 66 6f 72 20 74 68  ext(C,N)] for th
26f10 65 20 73 61 6d 65 20 63 6f 6e 74 65 78 74 20 70  e same context p
26f20 6f 69 6e 74 65 72 20 43 0a 2a 2a 20 20 20 20 20  ointer C.**     
26f30 20 20 20 20 20 69 67 6e 6f 72 65 20 74 68 65 20       ignore the 
26f40 4e 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20  N parameter and 
26f50 72 65 74 75 72 6e 20 61 20 70 6f 69 6e 74 65 72  return a pointer
26f60 20 74 6f 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20   to the same.** 
26f70 20 20 20 20 20 20 20 20 20 62 6c 6f 63 6b 20 6f           block o
26f80 66 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65  f memory returne
26f90 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 69  d by the first i
26fa0 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  nvocation..**.**
26fb0 20 7b 46 31 36 32 31 37 7d 20 54 68 65 20 6d 65   {F16217} The me
26fc0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 64 20 62  mory allocated b
26fd0 79 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65  y [sqlite3_aggre
26fe0 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e  gate_context(C,N
26ff0 29 5d 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20  )] is.**        
27000 20 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20    automatically 
27010 66 72 65 65 64 20 6f 6e 20 74 68 65 20 6e 65 78  freed on the nex
27020 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
27030 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20 20  e3_reset()].**  
27040 20 20 20 20 20 20 20 20 6f 72 20 5b 73 71 6c 69          or [sqli
27050 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
27060 66 6f 72 20 74 68 65 20 5b 70 72 65 70 61 72 65  for the [prepare
27070 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 63 6f 6e  d statement] con
27080 74 61 69 6e 69 6e 67 0a 2a 2a 20 20 20 20 20 20  taining.**      
27090 20 20 20 20 74 68 65 20 61 67 67 72 65 67 61 74      the aggregat
270a0 65 20 66 75 6e 63 74 69 6f 6e 20 61 73 73 6f 63  e function assoc
270b0 69 61 74 65 64 20 77 69 74 68 20 63 6f 6e 74 65  iated with conte
270c0 78 74 20 43 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73  xt C..*/.void *s
270d0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
270e0 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69 74 65 33  _context(sqlite3
270f0 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e  _context*, int n
27100 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  Bytes);../*.** C
27110 41 50 49 33 52 45 46 3a 20 55 73 65 72 20 44 61  API3REF: User Da
27120 74 61 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73  ta For Functions
27130 20 7b 46 31 36 32 34 30 7d 0a 2a 2a 0a 2a 2a 20   {F16240}.**.** 
27140 54 68 65 20 73 71 6c 69 74 65 33 5f 75 73 65 72  The sqlite3_user
27150 5f 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63  _data() interfac
27160 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79  e returns a copy
27170 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74   of.** the point
27180 65 72 20 74 68 61 74 20 77 61 73 20 74 68 65 20  er that was the 
27190 70 55 73 65 72 44 61 74 61 20 70 61 72 61 6d 65  pUserData parame
271a0 74 65 72 20 28 74 68 65 20 35 74 68 20 70 61 72  ter (the 5th par
271b0 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68  ameter).** of th
271c0 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  e the [sqlite3_c
271d0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
271e0 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
271f0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
27200 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20  n16()] routines 
27210 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a  that originally.
27220 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68  ** registered th
27230 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65  e application de
27240 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20  fined function. 
27250 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73  {END}.**.** This
27260 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65   routine must be
27270 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
27280 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20   same thread in 
27290 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 70 70  which.** the app
272a0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
272b0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
272c0 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  ning..**.** INVA
272d0 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  RIANTS:.**.** {F
272e0 31 36 32 34 33 7d 20 54 68 65 20 5b 73 71 6c 69  16243} The [sqli
272f0 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 43 29  te3_user_data(C)
27300 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
27310 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  rns a copy of th
27320 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 50 20  e.**          P 
27330 70 6f 69 6e 74 65 72 20 66 72 6f 6d 20 74 68 65  pointer from the
27340 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
27350 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c  _function(D,X,N,
27360 45 2c 50 2c 46 2c 53 2c 4c 29 5d 0a 2a 2a 20 20  E,P,F,S,L)].**  
27370 20 20 20 20 20 20 20 20 6f 72 20 5b 73 71 6c 69          or [sqli
27380 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
27390 69 6f 6e 31 36 28 44 2c 58 2c 4e 2c 45 2c 50 2c  ion16(D,X,N,E,P,
273a0 46 2c 53 2c 4c 29 5d 20 63 61 6c 6c 20 74 68 61  F,S,L)] call tha
273b0 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  t.**          re
273c0 67 69 73 74 65 72 65 64 20 74 68 65 20 53 51 4c  gistered the SQL
273d0 20 66 75 6e 63 74 69 6f 6e 20 61 73 73 6f 63 69   function associ
273e0 61 74 65 64 20 77 69 74 68 20 0a 2a 2a 20 20 20  ated with .**   
273f0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
27400 63 6f 6e 74 65 78 74 5d 20 43 2e 0a 2a 2f 0a 76  context] C..*/.v
27410 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 73 65  oid *sqlite3_use
27420 72 5f 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63  r_data(sqlite3_c
27430 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  ontext*);../*.**
27440 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74   CAPI3REF: Funct
27450 69 6f 6e 20 41 75 78 69 6c 69 61 72 79 20 44 61  ion Auxiliary Da
27460 74 61 20 7b 46 31 36 32 37 30 7d 0a 2a 2a 0a 2a  ta {F16270}.**.*
27470 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  * The following 
27480 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61  two functions ma
27490 79 20 62 65 20 75 73 65 64 20 62 79 20 73 63 61  y be used by sca
274a0 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  lar SQL function
274b0 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74  s to.** associat
274c0 65 20 6d 65 74 61 2d 64 61 74 61 20 77 69 74 68  e meta-data with
274d0 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 73   argument values
274e0 2e 20 49 66 20 74 68 65 20 73 61 6d 65 20 76 61  . If the same va
274f0 6c 75 65 20 69 73 20 70 61 73 73 65 64 20 74 6f  lue is passed to
27500 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76  .** multiple inv
27510 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ocations of the 
27520 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  same SQL functio
27530 6e 20 64 75 72 69 6e 67 20 71 75 65 72 79 20 65  n during query e
27540 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a  xecution, under.
27550 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 74  ** some circumst
27560 61 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63 69  ances the associ
27570 61 74 65 64 20 6d 65 74 61 2d 64 61 74 61 20 6d  ated meta-data m
27580 61 79 20 62 65 20 70 72 65 73 65 72 76 65 64 2e  ay be preserved.
27590 20 54 68 69 73 20 6d 61 79 0a 2a 2a 20 62 65 20   This may.** be 
275a0 75 73 65 64 2c 20 66 6f 72 20 65 78 61 6d 70 6c  used, for exampl
275b0 65 2c 20 74 6f 20 61 64 64 20 61 20 72 65 67 75  e, to add a regu
275c0 6c 61 72 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d  lar-expression m
275d0 61 74 63 68 69 6e 67 20 73 63 61 6c 61 72 0a 2a  atching scalar.*
275e0 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20  * function. The 
275f0 63 6f 6d 70 69 6c 65 64 20 76 65 72 73 69 6f 6e  compiled version
27600 20 6f 66 20 74 68 65 20 72 65 67 75 6c 61 72 20   of the regular 
27610 65 78 70 72 65 73 73 69 6f 6e 20 69 73 20 73 74  expression is st
27620 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61 2d  ored as.** meta-
27630 64 61 74 61 20 61 73 73 6f 63 69 61 74 65 64 20  data associated 
27640 77 69 74 68 20 74 68 65 20 53 51 4c 20 76 61 6c  with the SQL val
27650 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  ue passed as the
27660 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73   regular express
27670 69 6f 6e 0a 2a 2a 20 70 61 74 74 65 72 6e 2e 20  ion.** pattern. 
27680 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 72 65   The compiled re
27690 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e  gular expression
276a0 20 63 61 6e 20 62 65 20 72 65 75 73 65 64 20 6f   can be reused o
276b0 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e  n multiple.** in
276c0 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  vocations of the
276d0 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 73   same function s
276e0 6f 20 74 68 61 74 20 74 68 65 20 6f 72 69 67 69  o that the origi
276f0 6e 61 6c 20 70 61 74 74 65 72 6e 20 73 74 72 69  nal pattern stri
27700 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 6e  ng.** does not n
27710 65 65 64 20 74 6f 20 62 65 20 72 65 63 6f 6d 70  eed to be recomp
27720 69 6c 65 64 20 6f 6e 20 65 61 63 68 20 69 6e 76  iled on each inv
27730 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  ocation..**.** T
27740 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  he sqlite3_get_a
27750 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61  uxdata() interfa
27760 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
27770 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 74 61  nter to the meta
27780 2d 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61  -data.** associa
27790 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74  ted by the sqlit
277a0 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
277b0 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 74   function with t
277c0 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a  he Nth argument.
277d0 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74 68 65 20  ** value to the 
277e0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
277f0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  ned function..**
27800 20 49 66 20 6e 6f 20 6d 65 74 61 2d 64 61 74 61   If no meta-data
27810 20 68 61 73 20 62 65 65 6e 20 65 76 65 72 20 62   has been ever b
27820 65 65 6e 20 73 65 74 20 66 6f 72 20 74 68 65 20  een set for the 
27830 4e 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  Nth.** argument 
27840 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 2c  of the function,
27850 20 6f 72 20 69 66 20 74 68 65 20 63 6f 6f 72 65   or if the coore
27860 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f  sponding functio
27870 6e 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 68  n parameter.** h
27880 61 73 20 63 68 61 6e 67 65 64 20 73 69 6e 63 65  as changed since
27890 20 74 68 65 20 6d 65 74 61 2d 64 61 74 61 20 77   the meta-data w
278a0 61 73 20 73 65 74 2c 20 74 68 65 6e 20 73 71 6c  as set, then sql
278b0 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
278c0 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20  ().** returns a 
278d0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
278e0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
278f0 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e  set_auxdata() in
27900 74 65 72 66 61 63 65 20 73 61 76 65 73 20 74 68  terface saves th
27910 65 20 6d 65 74 61 2d 64 61 74 61 0a 2a 2a 20 70  e meta-data.** p
27920 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 69 74 73  ointed to by its
27930 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 61   3rd parameter a
27940 73 20 74 68 65 20 6d 65 74 61 2d 64 61 74 61 20  s the meta-data 
27950 66 6f 72 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20  for the N-th.** 
27960 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20  argument of the 
27970 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
27980 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 20 53  ned function.  S
27990 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c  ubsequent.** cal
279a0 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 67 65  ls to sqlite3_ge
279b0 74 5f 61 75 78 64 61 74 61 28 29 20 6d 69 67 68  t_auxdata() migh
279c0 74 20 72 65 74 75 72 6e 20 74 68 69 73 20 64 61  t return this da
279d0 74 61 2c 20 69 66 20 69 74 20 68 61 73 0a 2a 2a  ta, if it has.**
279e0 20 6e 6f 74 20 62 65 65 6e 20 64 65 73 74 72 6f   not been destro
279f0 79 65 64 2e 20 0a 2a 2a 20 49 66 20 69 74 20 69  yed. .** If it i
27a00 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69  s not NULL, SQLi
27a10 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74  te will invoke t
27a20 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 0a 2a  he destructor .*
27a30 2a 20 66 75 6e 63 74 69 6f 6e 20 67 69 76 65 6e  * function given
27a40 20 62 79 20 74 68 65 20 34 74 68 20 70 61 72 61   by the 4th para
27a50 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
27a60 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 6f  _set_auxdata() o
27a70 6e 0a 2a 2a 20 74 68 65 20 6d 65 74 61 2d 64 61  n.** the meta-da
27a80 74 61 20 77 68 65 6e 20 74 68 65 20 63 6f 72 72  ta when the corr
27a90 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74 69  esponding functi
27aa0 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 63 68 61  on parameter cha
27ab0 6e 67 65 73 0a 2a 2a 20 6f 72 20 77 68 65 6e 20  nges.** or when 
27ac0 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
27ad0 74 20 63 6f 6d 70 6c 65 74 65 73 2c 20 77 68 69  t completes, whi
27ae0 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72  chever comes fir
27af0 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  st..**.** SQLite
27b00 20 69 73 20 66 72 65 65 20 74 6f 20 63 61 6c 6c   is free to call
27b10 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
27b20 61 6e 64 20 64 72 6f 70 20 6d 65 74 61 2d 64 61  and drop meta-da
27b30 74 61 20 6f 6e 0a 2a 2a 20 61 6e 79 20 70 61 72  ta on.** any par
27b40 61 6d 65 74 65 72 20 6f 66 20 61 6e 79 20 66 75  ameter of any fu
27b50 6e 63 74 69 6f 6e 20 61 74 20 61 6e 79 20 74 69  nction at any ti
27b60 6d 65 2e 20 20 54 68 65 20 6f 6e 6c 79 20 67 75  me.  The only gu
27b70 61 72 61 6e 74 65 65 0a 2a 2a 20 69 73 20 74 68  arantee.** is th
27b80 61 74 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  at the destructo
27b90 72 20 77 69 6c 6c 20 62 65 20 63 61 6c 6c 65 64  r will be called
27ba0 20 62 65 66 6f 72 65 20 74 68 65 20 6d 65 74 61   before the meta
27bb0 64 61 74 61 20 69 73 0a 2a 2a 20 64 72 6f 70 70  data is.** dropp
27bc0 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 70 72 61  ed..**.** In pra
27bd0 63 74 69 63 65 2c 20 6d 65 74 61 2d 64 61 74 61  ctice, meta-data
27be0 20 69 73 20 70 72 65 73 65 72 76 65 64 20 62 65   is preserved be
27bf0 74 77 65 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63  tween function c
27c00 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 65 78 70 72  alls for.** expr
27c10 65 73 73 69 6f 6e 73 20 74 68 61 74 20 61 72 65  essions that are
27c20 20 63 6f 6e 73 74 61 6e 74 20 61 74 20 63 6f 6d   constant at com
27c30 70 69 6c 65 20 74 69 6d 65 2e 20 54 68 69 73 20  pile time. This 
27c40 69 6e 63 6c 75 64 65 73 20 6c 69 74 65 72 61 6c  includes literal
27c50 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64 20 53  .** values and S
27c60 51 4c 20 76 61 72 69 61 62 6c 65 73 2e 0a 2a 2a  QL variables..**
27c70 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
27c80 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  es must be calle
27c90 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
27ca0 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a  thread in which.
27cb0 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  ** the SQL funct
27cc0 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ion is running..
27cd0 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
27ce0 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32 37 32 7d  :.**.** {F16272}
27cf0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 67 65   The [sqlite3_ge
27d00 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 29 5d 20  t_auxdata(C,N)] 
27d10 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
27d20 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 20  s a pointer.**  
27d30 20 20 20 20 20 20 20 20 74 6f 20 6d 65 74 61 64          to metad
27d40 61 74 61 20 61 73 73 6f 63 69 61 74 65 64 20 77  ata associated w
27d50 69 74 68 20 74 68 65 20 4e 74 68 20 70 61 72 61  ith the Nth para
27d60 6d 65 74 65 72 20 6f 66 20 74 68 65 20 53 51 4c  meter of the SQL
27d70 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20 20   function.**    
27d80 20 20 20 20 20 20 77 68 6f 73 65 20 63 6f 6e 74        whose cont
27d90 65 78 74 20 69 73 20 43 2c 20 6f 72 20 4e 55 4c  ext is C, or NUL
27da0 4c 20 69 66 20 74 68 65 72 65 20 69 73 20 6e 6f  L if there is no
27db0 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63 69   metadata associ
27dc0 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  ated.**         
27dd0 20 77 69 74 68 20 74 68 61 74 20 70 61 72 61 6d   with that param
27de0 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  eter..**.** {F16
27df0 32 37 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  274} The [sqlite
27e00 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c  3_set_auxdata(C,
27e10 4e 2c 50 2c 44 29 5d 20 69 6e 74 65 72 66 61 63  N,P,D)] interfac
27e20 65 20 61 73 73 69 67 6e 73 20 61 20 6d 65 74 61  e assigns a meta
27e30 64 61 74 61 0a 2a 2a 20 20 20 20 20 20 20 20 20  data.**         
27e40 20 70 6f 69 6e 74 65 72 20 50 20 74 6f 20 74 68   pointer P to th
27e50 65 20 4e 74 68 20 70 61 72 61 6d 65 74 65 72 20  e Nth parameter 
27e60 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  of the SQL funct
27e70 69 6f 6e 20 77 69 74 68 20 63 6f 6e 74 65 78 74  ion with context
27e80 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 43 2e 0a  .**          C..
27e90 2a 2a 0a 2a 2a 20 7b 46 31 36 32 37 36 7d 20 53  **.** {F16276} S
27ea0 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b  QLite will invok
27eb0 65 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  e the destructor
27ec0 20 44 20 77 69 74 68 20 61 20 73 69 6e 67 6c 65   D with a single
27ed0 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 20 20 20   argument.**    
27ee0 20 20 20 20 20 20 77 68 69 63 68 20 69 73 20 74        which is t
27ef0 68 65 20 6d 65 74 61 64 61 74 61 20 70 6f 69 6e  he metadata poin
27f00 74 65 72 20 50 20 66 6f 6c 6c 6f 77 69 6e 67 20  ter P following 
27f10 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 20 20 20  a call to.**    
27f20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73        [sqlite3_s
27f30 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50  et_auxdata(C,N,P
27f40 2c 44 29 5d 20 77 68 65 6e 20 53 51 4c 69 74 65  ,D)] when SQLite
27f50 20 63 65 61 73 65 73 20 74 6f 20 68 6f 6c 64 0a   ceases to hold.
27f60 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
27f70 6d 65 74 61 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20  metadata..**.** 
27f80 7b 46 31 36 32 37 37 7d 20 53 51 4c 69 74 65 20  {F16277} SQLite 
27f90 63 65 61 73 65 73 20 74 6f 20 68 6f 6c 64 20 6d  ceases to hold m
27fa0 65 74 61 64 61 74 61 20 66 6f 72 20 61 6e 20 53  etadata for an S
27fb0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61  QL function para
27fc0 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  meter.**        
27fd0 20 20 77 68 65 6e 20 74 68 65 20 76 61 6c 75 65    when the value
27fe0 20 6f 66 20 74 68 61 74 20 70 61 72 61 6d 65 74   of that paramet
27ff0 65 72 20 63 68 61 6e 67 65 73 2e 0a 2a 2a 0a 2a  er changes..**.*
28000 2a 20 7b 46 31 36 32 37 38 7d 20 57 68 65 6e 20  * {F16278} When 
28010 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78  [sqlite3_set_aux
28020 64 61 74 61 28 43 2c 4e 2c 50 2c 44 29 5d 20 69  data(C,N,P,D)] i
28030 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20 64  s invoked, the d
28040 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 20 20 20  estructor.**    
28050 20 20 20 20 20 20 69 73 20 63 61 6c 6c 65 64 20        is called 
28060 66 6f 72 20 61 6e 79 20 70 72 69 6f 72 20 6d 65  for any prior me
28070 74 61 64 61 74 61 20 61 73 73 6f 63 69 61 74 65  tadata associate
28080 64 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20  d with the same 
28090 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20  function.**     
280a0 20 20 20 20 20 63 6f 6e 74 65 78 74 20 43 20 61       context C a
280b0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 4e 2e 0a  nd parameter N..
280c0 2a 2a 0a 2a 2a 20 7b 46 31 36 32 37 39 7d 20 53  **.** {F16279} S
280d0 51 4c 69 74 65 20 77 69 6c 6c 20 63 61 6c 6c 20  QLite will call 
280e0 64 65 73 74 72 75 63 74 6f 72 73 20 66 6f 72 20  destructors for 
280f0 61 6e 79 20 6d 65 74 61 64 61 74 61 20 69 74 20  any metadata it 
28100 69 73 20 68 6f 6c 64 69 6e 67 0a 2a 2a 20 20 20  is holding.**   
28110 20 20 20 20 20 20 20 69 6e 20 61 20 70 61 72 74         in a part
28120 69 63 75 6c 61 72 20 5b 70 72 65 70 61 72 65 64  icular [prepared
28130 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 77 68   statement] S wh
28140 65 6e 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20  en either.**    
28150 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72        [sqlite3_r
28160 65 73 65 74 28 53 29 5d 20 6f 72 20 5b 73 71 6c  eset(S)] or [sql
28170 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29  ite3_finalize(S)
28180 5d 20 69 73 20 63 61 6c 6c 65 64 2e 0a 2a 2f 0a  ] is called..*/.
28190 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 67 65  void *sqlite3_ge
281a0 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65  t_auxdata(sqlite
281b0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20  3_context*, int 
281c0 4e 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  N);.void sqlite3
281d0 5f 73 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c  _set_auxdata(sql
281e0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
281f0 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69  nt N, void*, voi
28200 64 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a  d (*)(void*));..
28210 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
28220 20 43 6f 6e 73 74 61 6e 74 73 20 44 65 66 69 6e   Constants Defin
28230 69 6e 67 20 53 70 65 63 69 61 6c 20 44 65 73 74  ing Special Dest
28240 72 75 63 74 6f 72 20 42 65 68 61 76 69 6f 72 20  ructor Behavior 
28250 7b 46 31 30 32 38 30 7d 0a 2a 2a 0a 2a 2a 20 54  {F10280}.**.** T
28260 68 65 73 65 20 61 72 65 20 73 70 65 63 69 61 6c  hese are special
28270 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 64   value for the d
28280 65 73 74 72 75 63 74 6f 72 20 74 68 61 74 20 69  estructor that i
28290 73 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 74  s passed in as t
282a0 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75  he.** final argu
282b0 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65 73  ment to routines
282c0 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72   like [sqlite3_r
282d0 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20  esult_blob()].  
282e0 49 66 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  If the destructo
282f0 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73  r.** argument is
28300 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20   SQLITE_STATIC, 
28310 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  it means that th
28320 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65  e content pointe
28330 72 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a  r is constant.**
28340 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72 20   and will never 
28350 63 68 61 6e 67 65 2e 20 20 49 74 20 64 6f 65 73  change.  It does
28360 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20   not need to be 
28370 64 65 73 74 72 6f 79 65 64 2e 20 20 54 68 65 20  destroyed.  The 
28380 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e 53  .** SQLITE_TRANS
28390 49 45 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e 73  IENT value means
283a0 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e   that the conten
283b0 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 68  t will likely ch
283c0 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e  ange in.** the n
283d0 65 61 72 20 66 75 74 75 72 65 20 61 6e 64 20 74  ear future and t
283e0 68 61 74 20 53 51 4c 69 74 65 20 73 68 6f 75 6c  hat SQLite shoul
283f0 64 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20 70  d make its own p
28400 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 0a 2a  rivate copy of.*
28410 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 62 65  * the content be
28420 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a  fore returning..
28430 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 64 65  **.** The typede
28440 66 20 69 73 20 6e 65 63 65 73 73 61 72 79 20 74  f is necessary t
28450 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70 72  o work around pr
28460 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72 74 61 69  oblems in certai
28470 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c 65  n.** C++ compile
28480 72 73 2e 20 20 53 65 65 20 74 69 63 6b 65 74 20  rs.  See ticket 
28490 23 32 31 39 31 2e 0a 2a 2f 0a 74 79 70 65 64 65  #2191..*/.typede
284a0 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33  f void (*sqlite3
284b0 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65  _destructor_type
284c0 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e  )(void*);.#defin
284d0 65 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 20  e SQLITE_STATIC 
284e0 20 20 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64       ((sqlite3_d
284f0 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 30  estructor_type)0
28500 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
28510 5f 54 52 41 4e 53 49 45 4e 54 20 20 20 28 28 73  _TRANSIENT   ((s
28520 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f  qlite3_destructo
28530 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a  r_type)-1)../*.*
28540 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 74  * CAPI3REF: Sett
28550 69 6e 67 20 54 68 65 20 52 65 73 75 6c 74 20 4f  ing The Result O
28560 66 20 41 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f  f An SQL Functio
28570 6e 20 7b 46 31 36 34 30 30 7d 0a 2a 2a 0a 2a 2a  n {F16400}.**.**
28580 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
28590 61 72 65 20 75 73 65 64 20 62 79 20 74 68 65 20  are used by the 
285a0 78 46 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20  xFunc or xFinal 
285b0 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a  callbacks that.*
285c0 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20  * implement SQL 
285d0 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67  functions and ag
285e0 67 72 65 67 61 74 65 73 2e 20 20 53 65 65 0a 2a  gregates.  See.*
285f0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  * [sqlite3_creat
28600 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e  e_function()] an
28610 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  d [sqlite3_creat
28620 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a  e_function16()].
28630 2a 2a 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  ** for additiona
28640 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  l information..*
28650 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74  *.** These funct
28660 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79 20 6d  ions work very m
28670 75 63 68 20 6c 69 6b 65 20 74 68 65 20 0a 2a 2a  uch like the .**
28680 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
28690 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69  lob | sqlite3_bi
286a0 6e 64 5f 2a 5d 20 66 61 6d 69 6c 79 20 6f 66 20  nd_*] family of 
286b0 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 64 0a 2a  functions used.*
286c0 2a 20 74 6f 20 62 69 6e 64 20 76 61 6c 75 65 73  * to bind values
286d0 20 74 6f 20 68 6f 73 74 20 70 61 72 61 6d 65 74   to host paramet
286e0 65 72 73 20 69 6e 20 70 72 65 70 61 72 65 64 20  ers in prepared 
286f0 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52  statements..** R
28700 65 66 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 5b  efer to the.** [
28710 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
28720 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  b | sqlite3_bind
28730 5f 2a 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  _* documentation
28740 5d 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f  ] for.** additio
28750 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  nal information.
28760 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
28770 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29  e3_result_blob()
28780 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
28790 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a  the result from.
287a0 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  ** an applicatio
287b0 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n defined functi
287c0 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 42 4c 4f  on to be the BLO
287d0 42 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20  B whose content 
287e0 69 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f  is pointed.** to
287f0 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 70   by the second p
28800 61 72 61 6d 65 74 65 72 20 61 6e 64 20 77 68 69  arameter and whi
28810 63 68 20 69 73 20 4e 20 62 79 74 65 73 20 6c 6f  ch is N bytes lo
28820 6e 67 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  ng where N is th
28830 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d  e.** third param
28840 65 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20 73 71  eter. .** The sq
28850 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72  lite3_result_zer
28860 6f 62 6c 6f 62 28 29 20 69 6e 65 72 66 61 63 65  oblob() inerface
28870 73 20 73 65 74 20 74 68 65 20 72 65 73 75 6c 74  s set the result
28880 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69   of.** the appli
28890 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66  cation defined f
288a0 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20  unction to be a 
288b0 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e 67 20  BLOB containing 
288c0 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79 74 65  all zero.** byte
288d0 73 20 61 6e 64 20 4e 20 62 79 74 65 73 20 69 6e  s and N bytes in
288e0 20 73 69 7a 65 2c 20 77 68 65 72 65 20 4e 20 69   size, where N i
288f0 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  s the value of t
28900 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
28910 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
28920 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c  te3_result_doubl
28930 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  e() interface se
28940 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 66 72  ts the result fr
28950 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61  om.** an applica
28960 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e  tion defined fun
28970 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 66 6c  ction to be a fl
28980 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
28990 75 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20  ue specified.** 
289a0 62 79 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d  by its 2nd argum
289b0 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ent..**.** The s
289c0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
289d0 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ror() and sqlite
289e0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
289f0 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  () functions.** 
28a00 63 61 75 73 65 20 74 68 65 20 69 6d 70 6c 65 6d  cause the implem
28a10 65 6e 74 65 64 20 53 51 4c 20 66 75 6e 63 74 69  ented SQL functi
28a20 6f 6e 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65  on to throw an e
28a30 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20 53 51 4c  xception..** SQL
28a40 69 74 65 20 75 73 65 73 20 74 68 65 20 73 74 72  ite uses the str
28a50 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  ing pointed to b
28a60 79 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70 61 72  y the.** 2nd par
28a70 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65  ameter of sqlite
28a80 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
28a90 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
28aa0 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20  lt_error16().** 
28ab0 61 73 20 74 68 65 20 74 65 78 74 20 6f 66 20 61  as the text of a
28ac0 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e  n error message.
28ad0 20 20 53 51 4c 69 74 65 20 69 6e 74 65 72 70 72    SQLite interpr
28ae0 65 74 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a  ets the error.**
28af0 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20   message string 
28b00 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73  from sqlite3_res
28b10 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 73 20 55  ult_error() as U
28b20 54 46 38 2e 20 53 51 4c 69 74 65 0a 2a 2a 20 69  TF8. SQLite.** i
28b30 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 73 74  nterprets the st
28b40 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65  ring from sqlite
28b50 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
28b60 28 29 20 61 73 20 55 54 46 31 36 20 69 6e 20 6e  () as UTF16 in n
28b70 61 74 69 76 65 0a 2a 2a 20 62 79 74 65 20 6f 72  ative.** byte or
28b80 64 65 72 2e 20 20 49 66 20 74 68 65 20 74 68 69  der.  If the thi
28b90 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
28ba0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
28bb0 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  rror().** or sql
28bc0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
28bd0 72 31 36 28 29 20 69 73 20 6e 65 67 61 74 69 76  r16() is negativ
28be0 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61  e then SQLite ta
28bf0 6b 65 73 20 61 73 20 74 68 65 20 65 72 72 6f 72  kes as the error
28c00 0a 2a 2a 20 6d 65 73 73 61 67 65 20 61 6c 6c 20  .** message all 
28c10 74 65 78 74 20 75 70 20 74 68 72 6f 75 67 68 20  text up through 
28c20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63  the first zero c
28c30 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 66 20  haracter..** If 
28c40 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
28c50 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
28c60 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72  esult_error() or
28c70 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75  .** sqlite3_resu
28c80 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20  lt_error16() is 
28c90 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 74 68 65  non-negative the
28ca0 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74  n SQLite takes t
28cb0 68 61 74 20 6d 61 6e 79 0a 2a 2a 20 62 79 74 65  hat many.** byte
28cc0 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72  s (not character
28cd0 73 29 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20  s) from the 2nd 
28ce0 70 61 72 61 6d 65 74 65 72 20 61 73 20 74 68 65  parameter as the
28cf0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a   error message..
28d00 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
28d10 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e  esult_error() an
28d20 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
28d30 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 72 6f  _error16().** ro
28d40 75 74 69 6e 65 73 20 6d 61 6b 65 20 61 20 63 6f  utines make a co
28d50 70 79 20 70 72 69 76 61 74 65 20 63 6f 70 79 20  py private copy 
28d60 6f 66 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  of the error mes
28d70 73 61 67 65 20 74 65 78 74 20 62 65 66 6f 72 65  sage text before
28d80 0a 2a 2a 20 74 68 65 79 20 72 65 74 75 72 6e 2e  .** they return.
28d90 20 20 48 65 6e 63 65 2c 20 74 68 65 20 63 61 6c    Hence, the cal
28da0 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61  ling function ca
28db0 6e 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f 72 0a  n deallocate or.
28dc0 2a 2a 20 6d 6f 64 69 66 79 20 74 68 65 20 74 65  ** modify the te
28dd0 78 74 20 61 66 74 65 72 20 74 68 65 79 20 72 65  xt after they re
28de0 74 75 72 6e 20 77 69 74 68 6f 75 74 20 68 61 72  turn without har
28df0 6d 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  m..** The sqlite
28e00 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63  3_result_error_c
28e10 6f 64 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 63  ode() function c
28e20 68 61 6e 67 65 73 20 74 68 65 20 65 72 72 6f 72  hanges the error
28e30 20 63 6f 64 65 0a 2a 2a 20 72 65 74 75 72 6e 65   code.** returne
28e40 64 20 62 79 20 53 51 4c 69 74 65 20 61 73 20 61  d by SQLite as a
28e50 20 72 65 73 75 6c 74 20 6f 66 20 61 6e 20 65 72   result of an er
28e60 72 6f 72 20 69 6e 20 61 20 66 75 6e 63 74 69 6f  ror in a functio
28e70 6e 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 0a  n.  By default,.
28e80 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64  ** the error cod
28e90 65 20 69 73 20 53 51 4c 49 54 45 5f 45 52 52 4f  e is SQLITE_ERRO
28ea0 52 2e 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  R. .**.** The sq
28eb0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 6f 6f  lite3_result_too
28ec0 62 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20  big() interface 
28ed0 63 61 75 73 65 73 20 53 51 4c 69 74 65 0a 2a 2a  causes SQLite.**
28ee0 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 72 72   to throw an err
28ef0 6f 72 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68  or indicating th
28f00 61 74 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42  at a string or B
28f10 4c 4f 42 20 69 73 20 74 6f 20 6c 6f 6e 67 0a 2a  LOB is to long.*
28f20 2a 20 74 6f 20 72 65 70 72 65 73 65 6e 74 2e 20  * to represent. 
28f30 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
28f40 75 6c 74 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65  ult_nomem() inte
28f50 72 66 61 63 65 0a 2a 2a 20 63 61 75 73 65 73 20  rface.** causes 
28f60 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20  SQLite to throw 
28f70 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 69 6e 64  an exception ind
28f80 69 63 61 74 69 6e 67 20 74 68 61 74 20 74 68 65  icating that the
28f90 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c   a.** memory all
28fa0 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65 64 2e 0a  ocation failed..
28fb0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
28fc0 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 29 20 69  3_result_int() i
28fd0 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
28fe0 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a  e return value.*
28ff0 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  * of the applica
29000 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
29010 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20  ction to be the 
29020 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  32-bit signed in
29030 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67  teger.** value g
29040 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20  iven in the 2nd 
29050 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65  argument..** The
29060 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
29070 69 6e 74 36 34 28 29 20 69 6e 74 65 72 66 61 63  int64() interfac
29080 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72  e sets the retur
29090 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68  n value.** of th
290a0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
290b0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
290c0 6f 20 62 65 20 74 68 65 20 36 34 2d 62 69 74 20  o be the 64-bit 
290d0 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a  signed integer.*
290e0 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e  * value given in
290f0 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e   the 2nd argumen
29100 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  t..**.** The sql
29110 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c  ite3_result_null
29120 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
29130 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  s the return val
29140 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70  ue.** of the app
29150 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
29160 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
29170 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  NULL..**.** The 
29180 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
29190 65 78 74 28 29 2c 20 73 71 6c 69 74 65 33 5f 72  ext(), sqlite3_r
291a0 65 73 75 6c 74 5f 74 65 78 74 31 36 28 29 2c 20  esult_text16(), 
291b0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75  .** sqlite3_resu
291c0 6c 74 5f 74 65 78 74 31 36 6c 65 28 29 2c 20 61  lt_text16le(), a
291d0 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  nd sqlite3_resul
291e0 74 5f 74 65 78 74 31 36 62 65 28 29 20 69 6e 74  t_text16be() int
291f0 65 72 66 61 63 65 73 0a 2a 2a 20 73 65 74 20 74  erfaces.** set t
29200 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
29210 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
29220 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
29230 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 61 20 74  ion to be.** a t
29240 65 78 74 20 73 74 72 69 6e 67 20 77 68 69 63 68  ext string which
29250 20 69 73 20 72 65 70 72 65 73 65 6e 74 65 64 20   is represented 
29260 61 73 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36  as UTF-8, UTF-16
29270 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
29280 65 72 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69  er,.** UTF-16 li
29290 74 74 6c 65 20 65 6e 64 69 61 6e 2c 20 6f 72 20  ttle endian, or 
292a0 55 54 46 2d 31 36 20 62 69 67 20 65 6e 64 69 61  UTF-16 big endia
292b0 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  n, respectively.
292c0 0a 2a 2a 20 53 51 4c 69 74 65 20 74 61 6b 65 73  .** SQLite takes
292d0 20 74 68 65 20 74 65 78 74 20 72 65 73 75 6c 74   the text result
292e0 20 66 72 6f 6d 20 74 68 65 20 61 70 70 6c 69 63   from the applic
292f0 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68  ation from.** th
29300 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
29310 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  of the sqlite3_r
29320 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
29330 72 66 61 63 65 73 2e 0a 2a 2a 20 49 66 20 74 68  rfaces..** If th
29340 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
29350 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  to the sqlite3_r
29360 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
29370 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 65 67  rfaces.** is neg
29380 61 74 69 76 65 2c 20 74 68 65 6e 20 53 51 4c 69  ative, then SQLi
29390 74 65 20 74 61 6b 65 73 20 72 65 73 75 6c 74 20  te takes result 
293a0 74 65 78 74 20 66 72 6f 6d 20 74 68 65 20 32 6e  text from the 2n
293b0 64 20 70 61 72 61 6d 65 74 65 72 20 0a 2a 2a 20  d parameter .** 
293c0 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 73  through the firs
293d0 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72  t zero character
293e0 2e 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20  ..** If the 3rd 
293f0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
29400 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
29410 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
29420 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  .** is non-negat
29430 69 76 65 2c 20 74 68 65 6e 20 61 73 20 6d 61 6e  ive, then as man
29440 79 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61  y bytes (not cha
29450 72 61 63 74 65 72 73 29 20 6f 66 20 74 68 65 20  racters) of the 
29460 74 65 78 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 20  text.** pointed 
29470 74 6f 20 62 79 20 74 68 65 20 32 6e 64 20 70 61  to by the 2nd pa
29480 72 61 6d 65 74 65 72 20 61 72 65 20 74 61 6b 65  rameter are take
29490 6e 20 61 73 20 74 68 65 20 61 70 70 6c 69 63 61  n as the applica
294a0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a 20  tion-defined.** 
294b0 66 75 6e 63 74 69 6f 6e 20 72 65 73 75 6c 74 2e  function result.
294c0 0a 2a 2a 20 49 66 20 74 68 65 20 34 74 68 20 70  .** If the 4th p
294d0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
294e0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
294f0 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a  ext* interfaces.
29500 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ** or sqlite3_re
29510 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 61 20 6e  sult_blob is a n
29520 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c  on-NULL pointer,
29530 20 74 68 65 6e 20 53 51 4c 69 74 65 20 63 61 6c   then SQLite cal
29540 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75 6e 63 74  ls that.** funct
29550 69 6f 6e 20 61 73 20 74 68 65 20 64 65 73 74 72  ion as the destr
29560 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 74 65 78  uctor on the tex
29570 74 20 6f 72 20 62 6c 6f 62 20 72 65 73 75 6c 74  t or blob result
29580 20 77 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20   when it has.** 
29590 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74  finished using t
295a0 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 49  hat result..** I
295b0 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65  f the 4th parame
295c0 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
295d0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
295e0 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72  interfaces.** or
295f0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
29600 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65 63  blob is the spec
29610 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c  ial constant SQL
29620 49 54 45 5f 53 54 41 54 49 43 2c 20 74 68 65 6e  ITE_STATIC, then
29630 0a 2a 2a 20 53 51 4c 69 74 65 20 61 73 73 75 6d  .** SQLite assum
29640 65 73 20 74 68 61 74 20 74 68 65 20 74 65 78 74  es that the text
29650 20 6f 72 20 62 6c 6f 62 20 72 65 73 75 6c 74 20   or blob result 
29660 69 73 20 63 6f 6e 73 74 61 6e 74 20 73 70 61 63  is constant spac
29670 65 20 61 6e 64 0a 2a 2a 20 64 6f 65 73 20 6e 6f  e and.** does no
29680 74 20 63 6f 70 79 20 74 68 65 20 73 70 61 63 65  t copy the space
29690 20 6f 72 20 63 61 6c 6c 20 61 20 64 65 73 74 72   or call a destr
296a0 75 63 74 6f 72 20 77 68 65 6e 20 69 74 20 68 61  uctor when it ha
296b0 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20 75 73  s.** finished us
296c0 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e  ing that result.
296d0 0a 2a 2a 20 49 66 20 74 68 65 20 34 74 68 20 70  .** If the 4th p
296e0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
296f0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
29700 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a  ext* interfaces.
29710 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ** or sqlite3_re
29720 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65  sult_blob is the
29730 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e   special constan
29740 74 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45  t SQLITE_TRANSIE
29750 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 51 4c 69 74  NT.** then SQLit
29760 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f  e makes a copy o
29770 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e 74  f the result int
29780 6f 20 73 70 61 63 65 20 6f 62 74 61 69 6e 65 64  o space obtained
29790 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73   from.** from [s
297a0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
297b0 20 62 65 66 6f 72 65 20 69 74 20 72 65 74 75 72   before it retur
297c0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ns..**.** The sq
297d0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
297e0 75 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  ue() interface s
297f0 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 6f  ets the result o
29800 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  f.** the applica
29810 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
29820 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 63 6f  ction to be a co
29830 70 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  py the [sqlite3_
29840 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74  value].** object
29850 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
29860 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e  e 2nd parameter.
29870 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33    The.** sqlite3
29880 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20  _result_value() 
29890 69 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20  interface makes 
298a0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73  a copy of the [s
298b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a  qlite3_value].**
298c0 20 73 6f 20 74 68 61 74 20 5b 73 71 6c 69 74 65   so that [sqlite
298d0 33 5f 76 61 6c 75 65 5d 20 73 70 65 63 69 66 69  3_value] specifi
298e0 65 64 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65  ed in the parame
298f0 74 65 72 20 6d 61 79 20 63 68 61 6e 67 65 20 6f  ter may change o
29900 72 0a 2a 2a 20 62 65 20 64 65 61 6c 6c 6f 63 61  r.** be dealloca
29910 74 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65  ted after sqlite
29920 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29  3_result_value()
29930 20 72 65 74 75 72 6e 73 20 77 69 74 68 6f 75 74   returns without
29940 20 68 61 72 6d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20   harm..**.** If 
29950 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  these routines a
29960 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77  re called from w
29970 69 74 68 69 6e 20 74 68 65 20 64 69 66 66 65 72  ithin the differ
29980 65 6e 74 20 74 68 72 65 61 64 20 0a 2a 2a 20 74  ent thread .** t
29990 68 61 6e 20 74 68 65 20 6f 6e 65 20 63 6f 6e 74  han the one cont
299a0 61 69 6e 69 6e 67 20 74 68 65 20 61 70 70 6c 69  aining the appli
299b0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
299c0 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 72 65 63  unction that rec
299d0 69 65 76 65 64 0a 2a 2a 20 74 68 65 20 5b 73 71  ieved.** the [sq
299e0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 70  lite3_context] p
299f0 6f 69 6e 74 65 72 2c 20 74 68 65 20 72 65 73 75  ointer, the resu
29a00 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
29a10 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  d..**.** INVARIA
29a20 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34  NTS:.**.** {F164
29a30 30 33 7d 20 54 68 65 20 64 65 66 61 75 6c 74 20  03} The default 
29a40 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f  return value fro
29a50 6d 20 61 6e 79 20 53 51 4c 20 66 75 6e 63 74 69  m any SQL functi
29a60 6f 6e 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  on is NULL..**.*
29a70 2a 20 7b 46 31 36 34 30 36 7d 20 54 68 65 20 5b  * {F16406} The [
29a80 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
29a90 6c 6f 62 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e  lob(C,V,N,D)] in
29aa0 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20  terface changes 
29ab0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
29ac0 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
29ad0 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65  function C to be
29ae0 20 61 20 62 6c 6f 62 20 74 68 61 74 20 69 73 20   a blob that is 
29af0 4e 20 62 79 74 65 73 0a 2a 2a 20 20 20 20 20 20  N bytes.**      
29b00 20 20 20 20 69 6e 20 6c 65 6e 67 74 68 20 61 6e      in length an
29b10 64 20 77 69 74 68 20 63 6f 6e 74 65 6e 74 20 70  d with content p
29b20 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 56 2e 0a  ointed to by V..
29b30 2a 2a 0a 2a 2a 20 7b 46 31 36 34 30 39 7d 20 54  **.** {F16409} T
29b40 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  he [sqlite3_resu
29b50 6c 74 5f 64 6f 75 62 6c 65 28 43 2c 56 29 5d 20  lt_double(C,V)] 
29b60 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65  interface change
29b70 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
29b80 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f    return value o
29b90 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20  f function C to 
29ba0 62 65 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20  be the floating 
29bb0 70 6f 69 6e 74 20 76 61 6c 75 65 20 56 2e 0a 2a  point value V..*
29bc0 2a 0a 2a 2a 20 7b 46 31 36 34 31 32 7d 20 54 68  *.** {F16412} Th
29bd0 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  e [sqlite3_resul
29be0 74 5f 65 72 72 6f 72 28 43 2c 56 2c 4e 29 5d 20  t_error(C,V,N)] 
29bf0 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65  interface change
29c00 73 20 74 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20  s the return.** 
29c10 20 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 6f           value o
29c20 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20  f function C to 
29c30 62 65 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20  be an exception 
29c40 77 69 74 68 20 65 72 72 6f 72 20 63 6f 64 65 0a  with error code.
29c50 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c  **          [SQL
29c60 49 54 45 5f 45 52 52 4f 52 5d 20 61 6e 64 20 61  ITE_ERROR] and a
29c70 20 55 54 46 38 20 65 72 72 6f 72 20 6d 65 73 73   UTF8 error mess
29c80 61 67 65 20 63 6f 70 69 65 64 20 66 72 6f 6d 20  age copied from 
29c90 56 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20 20  V up to the.**  
29ca0 20 20 20 20 20 20 20 20 66 69 72 73 74 20 7a 65          first ze
29cb0 72 6f 20 62 79 74 65 20 6f 72 20 75 6e 74 69 6c  ro byte or until
29cc0 20 4e 20 62 79 74 65 73 20 61 72 65 20 72 65 61   N bytes are rea
29cd0 64 20 69 66 20 4e 20 69 73 20 70 6f 73 69 74 69  d if N is positi
29ce0 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 31  ve..**.** {F1641
29cf0 35 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  5} The [sqlite3_
29d00 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 43  result_error16(C
29d10 2c 56 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  ,V,N)] interface
29d20 20 63 68 61 6e 67 65 73 20 74 68 65 20 72 65 74   changes the ret
29d30 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  urn.**          
29d40 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f  value of functio
29d50 6e 20 43 20 74 6f 20 62 65 20 61 6e 20 65 78 63  n C to be an exc
29d60 65 70 74 69 6f 6e 20 77 69 74 68 20 65 72 72 6f  eption with erro
29d70 72 20 63 6f 64 65 0a 2a 2a 20 20 20 20 20 20 20  r code.**       
29d80 20 20 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52     [SQLITE_ERROR
29d90 5d 20 61 6e 64 20 61 20 55 54 46 31 36 20 6e 61  ] and a UTF16 na
29da0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
29db0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 0a 2a 2a  error message.**
29dc0 20 20 20 20 20 20 20 20 20 20 63 6f 70 69 65 64            copied
29dd0 20 66 72 6f 6d 20 56 20 75 70 20 74 6f 20 74 68   from V up to th
29de0 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72  e first zero ter
29df0 6d 69 6e 61 74 6f 72 20 6f 72 20 75 6e 74 69 6c  minator or until
29e00 20 4e 20 62 79 74 65 73 0a 2a 2a 20 20 20 20 20   N bytes.**     
29e10 20 20 20 20 20 61 72 65 20 72 65 61 64 20 69 66       are read if
29e20 20 4e 20 69 73 20 70 6f 73 69 74 69 76 65 2e 0a   N is positive..
29e30 2a 2a 0a 2a 2a 20 7b 46 31 36 34 31 38 7d 20 54  **.** {F16418} T
29e40 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  he [sqlite3_resu
29e50 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28  lt_error_toobig(
29e60 43 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68  C)] interface ch
29e70 61 6e 67 65 73 20 74 68 65 20 72 65 74 75 72 6e  anges the return
29e80 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c  .**          val
29e90 75 65 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69  ue of the functi
29ea0 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e 20 65 78  on C to be an ex
29eb0 63 65 70 74 69 6f 6e 20 77 69 74 68 20 65 72 72  ception with err
29ec0 6f 72 20 63 6f 64 65 0a 2a 2a 20 20 20 20 20 20  or code.**      
29ed0 20 20 20 20 5b 53 51 4c 49 54 45 5f 54 4f 4f 42      [SQLITE_TOOB
29ee0 49 47 5d 20 61 6e 64 20 61 6e 20 61 70 70 72 6f  IG] and an appro
29ef0 70 72 69 61 74 65 20 65 72 72 6f 72 20 6d 65 73  priate error mes
29f00 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  sage..**.** {F16
29f10 34 32 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  421} The [sqlite
29f20 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e  3_result_error_n
29f30 6f 6d 65 6d 28 43 29 5d 20 69 6e 74 65 72 66 61  omem(C)] interfa
29f40 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 20 72  ce changes the r
29f50 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20  eturn.**        
29f60 20 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 66    value of the f
29f70 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20  unction C to be 
29f80 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 77 69 74  an exception wit
29f90 68 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20  h error code.** 
29fa0 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45           [SQLITE
29fb0 5f 4e 4f 4d 45 4d 5d 20 61 6e 64 20 61 6e 20 61  _NOMEM] and an a
29fc0 70 70 72 6f 70 72 69 61 74 65 20 65 72 72 6f 72  ppropriate error
29fd0 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20   message..**.** 
29fe0 7b 46 31 36 34 32 34 7d 20 54 68 65 20 5b 73 71  {F16424} The [sq
29ff0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
2a000 6f 72 5f 63 6f 64 65 28 43 2c 45 29 5d 20 69 6e  or_code(C,E)] in
2a010 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20  terface changes 
2a020 74 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20  the return.**   
2a030 20 20 20 20 20 20 20 76 61 6c 75 65 20 6f 66 20         value of 
2a040 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 43 20 74  the function C t
2a050 6f 20 62 65 20 61 6e 20 65 78 63 65 70 74 69 6f  o be an exceptio
2a060 6e 20 77 69 74 68 20 65 72 72 6f 72 20 63 6f 64  n with error cod
2a070 65 20 45 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20  e E..**         
2a080 20 54 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   The error messa
2a090 67 65 20 74 65 78 74 20 69 73 20 75 6e 63 68 61  ge text is uncha
2a0a0 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  nged..**.** {F16
2a0b0 34 32 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  427} The [sqlite
2a0c0 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 43 2c 56  3_result_int(C,V
2a0d0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61  )] interface cha
2a0e0 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  nges the.**     
2a0f0 20 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75       return valu
2a100 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20  e of function C 
2a110 74 6f 20 62 65 20 74 68 65 20 33 32 2d 62 69 74  to be the 32-bit
2a120 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 20 56   integer value V
2a130 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 33 30 7d  ..**.** {F16430}
2a140 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   The [sqlite3_re
2a150 73 75 6c 74 5f 69 6e 74 36 34 28 43 2c 56 29 5d  sult_int64(C,V)]
2a160 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67   interface chang
2a170 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  es the.**       
2a180 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20     return value 
2a190 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f  of function C to
2a1a0 20 62 65 20 74 68 65 20 36 34 2d 62 69 74 20 69   be the 64-bit i
2a1b0 6e 74 65 67 65 72 20 76 61 6c 75 65 20 56 2e 0a  nteger value V..
2a1c0 2a 2a 0a 2a 2a 20 7b 46 31 36 34 33 33 7d 20 54  **.** {F16433} T
2a1d0 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  he [sqlite3_resu
2a1e0 6c 74 5f 6e 75 6c 6c 28 43 29 5d 20 69 6e 74 65  lt_null(C)] inte
2a1f0 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68  rface changes th
2a200 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  e.**          re
2a210 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75  turn value of fu
2a220 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 4e  nction C to be N
2a230 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34  ULL..**.** {F164
2a240 33 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  36} The [sqlite3
2a250 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 43 2c 56  _result_text(C,V
2a260 2c 4e 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65  ,N,D)] interface
2a270 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20   changes the.** 
2a280 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20           return 
2a290 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f  value of functio
2a2a0 6e 20 43 20 74 6f 20 62 65 20 74 68 65 20 55 54  n C to be the UT
2a2b0 46 38 20 73 74 72 69 6e 67 0a 2a 2a 20 20 20 20  F8 string.**    
2a2c0 20 20 20 20 20 20 56 20 75 70 20 74 68 72 6f 75        V up throu
2a2d0 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 72  gh the first zer
2a2e0 6f 20 6f 72 20 75 6e 74 69 6c 20 4e 20 62 79 74  o or until N byt
2a2f0 65 73 20 61 72 65 20 72 65 61 64 20 69 66 20 4e  es are read if N
2a300 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20  .**          is 
2a310 70 6f 73 69 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20  positive..**.** 
2a320 7b 46 31 36 34 33 39 7d 20 54 68 65 20 5b 73 71  {F16439} The [sq
2a330 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
2a340 74 31 36 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e  t16(C,V,N,D)] in
2a350 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20  terface changes 
2a360 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
2a370 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
2a380 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65  function C to be
2a390 20 74 68 65 20 55 54 46 31 36 20 6e 61 74 69 76   the UTF16 nativ
2a3a0 65 20 62 79 74 65 20 6f 72 64 65 72 0a 2a 2a 20  e byte order.** 
2a3b0 20 20 20 20 20 20 20 20 20 73 74 72 69 6e 67 20           string 
2a3c0 20 56 20 75 70 20 74 68 72 6f 75 67 68 20 74 68   V up through th
2a3d0 65 20 66 69 72 73 74 20 7a 65 72 6f 20 6f 72 20  e first zero or 
2a3e0 75 6e 74 69 6c 20 4e 20 62 79 74 65 73 20 61 72  until N bytes ar
2a3f0 65 20 72 65 61 64 20 69 66 20 4e 0a 2a 2a 20 20  e read if N.**  
2a400 20 20 20 20 20 20 20 20 69 73 20 70 6f 73 69 74          is posit
2a410 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34  ive..**.** {F164
2a420 34 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  42} The [sqlite3
2a430 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65  _result_text16be
2a440 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74 65 72  (C,V,N,D)] inter
2a450 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65  face changes the
2a460 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74  .**          ret
2a470 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e  urn value of fun
2a480 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68  ction C to be th
2a490 65 20 55 54 46 31 36 20 62 69 67 2d 65 6e 64 69  e UTF16 big-endi
2a4a0 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73  an.**          s
2a4b0 74 72 69 6e 67 20 20 56 20 75 70 20 74 68 72 6f  tring  V up thro
2a4c0 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65  ugh the first ze
2a4d0 72 6f 20 6f 72 20 75 6e 74 69 6c 20 4e 20 62 79  ro or until N by
2a4e0 74 65 73 20 61 72 65 20 72 65 61 64 20 69 66 20  tes are read if 
2a4f0 4e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73  N.**          is
2a500 20 70 6f 73 69 74 69 76 65 2e 0a 2a 2a 0a 2a 2a   positive..**.**
2a510 20 7b 46 31 36 34 34 35 7d 20 54 68 65 20 5b 73   {F16445} The [s
2a520 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
2a530 78 74 31 36 6c 65 28 43 2c 56 2c 4e 2c 44 29 5d  xt16le(C,V,N,D)]
2a540 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67   interface chang
2a550 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  es the.**       
2a560 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20     return value 
2a570 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f  of function C to
2a580 20 62 65 20 74 68 65 20 55 54 46 31 36 20 6c 69   be the UTF16 li
2a590 74 74 6c 65 2d 65 6e 64 69 61 6e 0a 2a 2a 20 20  ttle-endian.**  
2a5a0 20 20 20 20 20 20 20 20 73 74 72 69 6e 67 20 20          string  
2a5b0 56 20 75 70 20 74 68 72 6f 75 67 68 20 74 68 65  V up through the
2a5c0 20 66 69 72 73 74 20 7a 65 72 6f 20 6f 72 20 75   first zero or u
2a5d0 6e 74 69 6c 20 4e 20 62 79 74 65 73 20 61 72 65  ntil N bytes are
2a5e0 20 72 65 61 64 20 69 66 20 4e 0a 2a 2a 20 20 20   read if N.**   
2a5f0 20 20 20 20 20 20 20 69 73 20 70 6f 73 69 74 69         is positi
2a600 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 34  ve..**.** {F1644
2a610 38 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  8} The [sqlite3_
2a620 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 43 2c 56  result_value(C,V
2a630 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61  )] interface cha
2a640 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  nges the.**     
2a650 20 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75       return valu
2a660 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20  e of function C 
2a670 74 6f 20 62 65 20 5b 73 71 6c 69 74 65 33 5f 76  to be [sqlite3_v
2a680 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 2e 0a  alue] object V..
2a690 2a 2a 0a 2a 2a 20 7b 46 31 36 34 35 31 7d 20 54  **.** {F16451} T
2a6a0 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  he [sqlite3_resu
2a6b0 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 43 2c 4e 29  lt_zeroblob(C,N)
2a6c0 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e  ] interface chan
2a6d0 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  ges the.**      
2a6e0 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65      return value
2a6f0 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74   of function C t
2a700 6f 20 62 65 20 61 6e 20 4e 2d 62 79 74 65 20 62  o be an N-byte b
2a710 6c 6f 62 20 6f 66 20 61 6c 6c 20 7a 65 72 6f 73  lob of all zeros
2a720 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 35 34 7d  ..**.** {F16454}
2a730 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   The [sqlite3_re
2a740 73 75 6c 74 5f 65 72 72 6f 72 28 29 5d 20 61 6e  sult_error()] an
2a750 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  d [sqlite3_resul
2a760 74 5f 65 72 72 6f 72 31 36 28 29 5d 0a 2a 2a 20  t_error16()].** 
2a770 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 66 61           interfa
2a780 63 65 73 20 6d 61 6b 65 20 61 20 63 6f 70 79 20  ces make a copy 
2a790 6f 66 20 74 68 65 69 72 20 65 72 72 6f 72 20 6d  of their error m
2a7a0 65 73 73 61 67 65 20 73 74 72 69 6e 67 73 20 62  essage strings b
2a7b0 65 66 6f 72 65 0a 2a 2a 20 20 20 20 20 20 20 20  efore.**        
2a7c0 20 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a    returning..**.
2a7d0 2a 2a 20 7b 46 31 36 34 35 37 7d 20 49 66 20 74  ** {F16457} If t
2a7e0 68 65 20 44 20 64 65 73 74 72 75 63 74 6f 72 20  he D destructor 
2a7f0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
2a800 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
2a810 62 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20  b(C,V,N,D)],.** 
2a820 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
2a830 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 43 2c  3_result_text(C,
2a840 56 2c 4e 2c 44 29 5d 2c 20 5b 73 71 6c 69 74 65  V,N,D)], [sqlite
2a850 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28  3_result_text16(
2a860 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20  C,V,N,D)],.**   
2a870 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
2a880 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28  result_text16be(
2a890 43 2c 56 2c 4e 2c 44 29 5d 2c 20 6f 72 0a 2a 2a  C,V,N,D)], or.**
2a8a0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
2a8b0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
2a8c0 6c 65 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 73 20  le(C,V,N,D)] is 
2a8d0 74 68 65 20 63 6f 6e 73 74 61 6e 74 20 5b 53 51  the constant [SQ
2a8e0 4c 49 54 45 5f 53 54 41 54 49 43 5d 0a 2a 2a 20  LITE_STATIC].** 
2a8f0 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 6e 6f           then no
2a900 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 65   destructor is e
2a910 76 65 72 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68  ver called on th
2a920 65 20 70 6f 69 6e 74 65 72 20 56 20 61 6e 64 20  e pointer V and 
2a930 53 51 4c 69 74 65 0a 2a 2a 20 20 20 20 20 20 20  SQLite.**       
2a940 20 20 20 61 73 73 75 6d 65 73 20 74 68 61 74 20     assumes that 
2a950 56 20 69 73 20 69 6d 6d 75 74 61 62 6c 65 2e 0a  V is immutable..
2a960 2a 2a 0a 2a 2a 20 7b 46 31 36 34 36 30 7d 20 49  **.** {F16460} I
2a970 66 20 74 68 65 20 44 20 64 65 73 74 72 75 63 74  f the D destruct
2a980 6f 72 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  or parameter to 
2a990 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
2a9a0 62 6c 6f 62 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a  blob(C,V,N,D)],.
2a9b0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
2a9c0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
2a9d0 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 5b 73 71 6c  (C,V,N,D)], [sql
2a9e0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
2a9f0 31 36 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a  16(C,V,N,D)],.**
2aa00 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
2aa10 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
2aa20 62 65 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 6f 72  be(C,V,N,D)], or
2aa30 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
2aa40 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
2aa50 74 31 36 6c 65 28 43 2c 56 2c 4e 2c 44 29 5d 20  t16le(C,V,N,D)] 
2aa60 69 73 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 0a  is the constant.
2aa70 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c  **          [SQL
2aa80 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 20 74  ITE_TRANSIENT] t
2aa90 68 65 6e 20 74 68 65 20 69 6e 74 65 72 66 61 63  hen the interfac
2aaa0 65 73 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20  es makes a copy 
2aab0 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  of the.**       
2aac0 20 20 20 63 6f 6e 74 65 6e 74 20 6f 66 20 56 20     content of V 
2aad0 61 6e 64 20 72 65 74 61 69 6e 73 20 74 68 65 20  and retains the 
2aae0 63 6f 70 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  copy..**.** {F16
2aaf0 34 36 33 7d 20 49 66 20 74 68 65 20 44 20 64 65  463} If the D de
2ab00 73 74 72 75 63 74 6f 72 20 70 61 72 61 6d 65 74  structor paramet
2ab10 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  er to [sqlite3_r
2ab20 65 73 75 6c 74 5f 62 6c 6f 62 28 43 2c 56 2c 4e  esult_blob(C,V,N
2ab30 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  ,D)],.**        
2ab40 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c    [sqlite3_resul
2ab50 74 5f 74 65 78 74 28 43 2c 56 2c 4e 2c 44 29 5d  t_text(C,V,N,D)]
2ab60 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  , [sqlite3_resul
2ab70 74 5f 74 65 78 74 31 36 28 43 2c 56 2c 4e 2c 44  t_text16(C,V,N,D
2ab80 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  )],.**          
2ab90 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
2aba0 74 65 78 74 31 36 62 65 28 43 2c 56 2c 4e 2c 44  text16be(C,V,N,D
2abb0 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20  )], or.**       
2abc0 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75     [sqlite3_resu
2abd0 6c 74 5f 74 65 78 74 31 36 6c 65 28 43 2c 56 2c  lt_text16le(C,V,
2abe0 4e 2c 44 29 5d 20 69 73 20 73 6f 6d 65 20 76 61  N,D)] is some va
2abf0 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e 0a 2a  lue other than.*
2ac00 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 63  *          the c
2ac10 6f 6e 73 74 61 6e 74 73 20 5b 53 51 4c 49 54 45  onstants [SQLITE
2ac20 5f 53 54 41 54 49 43 5d 20 61 6e 64 20 5b 53 51  _STATIC] and [SQ
2ac30 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 20  LITE_TRANSIENT] 
2ac40 74 68 65 6e 20 0a 2a 2a 20 20 20 20 20 20 20 20  then .**        
2ac50 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e    SQLite will in
2ac60 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75 63  voke the destruc
2ac70 74 6f 72 20 44 20 77 69 74 68 20 56 20 61 73 20  tor D with V as 
2ac80 69 74 73 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e  its only argumen
2ac90 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68  t.**          wh
2aca0 65 6e 20 69 74 20 68 61 73 20 66 69 6e 69 73 68  en it has finish
2acb0 65 64 20 77 69 74 68 20 74 68 65 20 56 20 76 61  ed with the V va
2acc0 6c 75 65 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  lue..*/.void sql
2acd0 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
2ace0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2acf0 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
2ad00 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
2ad10 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  d*));.void sqlit
2ad20 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65  e3_result_double
2ad30 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2ad40 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a 76 6f 69 64  *, double);.void
2ad50 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2ad60 65 72 72 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f  error(sqlite3_co
2ad70 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68  ntext*, const ch
2ad80 61 72 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20  ar*, int);.void 
2ad90 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
2ada0 72 72 6f 72 31 36 28 73 71 6c 69 74 65 33 5f 63  rror16(sqlite3_c
2adb0 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
2adc0 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64  oid*, int);.void
2add0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2ade0 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 73 71 6c  error_toobig(sql
2adf0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
2ae00 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
2ae10 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28  ult_error_nomem(
2ae20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2ae30 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
2ae40 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64  result_error_cod
2ae50 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
2ae60 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73  t*, int);.void s
2ae70 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
2ae80 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t(sqlite3_contex
2ae90 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73  t*, int);.void s
2aea0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
2aeb0 74 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  t64(sqlite3_cont
2aec0 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ext*, sqlite3_in
2aed0 74 36 34 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  t64);.void sqlit
2aee0 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 73  e3_result_null(s
2aef0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
2af00 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
2af10 65 73 75 6c 74 5f 74 65 78 74 28 73 71 6c 69 74  esult_text(sqlit
2af20 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
2af30 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 2c 20 76  st char*, int, v
2af40 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
2af50 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
2af60 75 6c 74 5f 74 65 78 74 31 36 28 73 71 6c 69 74  ult_text16(sqlit
2af70 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
2af80 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76  st void*, int, v
2af90 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
2afa0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
2afb0 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 73 71 6c  ult_text16le(sql
2afc0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
2afd0 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
2afe0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
2aff0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
2b000 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 73 71  sult_text16be(sq
2b010 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
2b020 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
2b030 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29  ,void(*)(void*))
2b040 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
2b050 65 73 75 6c 74 5f 76 61 6c 75 65 28 73 71 6c 69  esult_value(sqli
2b060 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71  te3_context*, sq
2b070 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 76  lite3_value*);.v
2b080 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
2b090 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69  lt_zeroblob(sqli
2b0a0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
2b0b0 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  t n);../*.** CAP
2b0c0 49 33 52 45 46 3a 20 44 65 66 69 6e 65 20 4e 65  I3REF: Define Ne
2b0d0 77 20 43 6f 6c 6c 61 74 69 6e 67 20 53 65 71 75  w Collating Sequ
2b0e0 65 6e 63 65 73 20 7b 46 31 36 36 30 30 7d 0a 2a  ences {F16600}.*
2b0f0 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74  *.** These funct
2b100 69 6f 6e 73 20 61 72 65 20 75 73 65 64 20 74 6f  ions are used to
2b110 20 61 64 64 20 6e 65 77 20 63 6f 6c 6c 61 74 69   add new collati
2b120 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 74 6f 20  on sequences to 
2b130 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 2a  the.** [sqlite3*
2b140 5d 20 68 61 6e 64 6c 65 20 73 70 65 63 69 66 69  ] handle specifi
2b150 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20  ed as the first 
2b160 61 72 67 75 6d 65 6e 74 2e 20 0a 2a 2a 0a 2a 2a  argument. .**.**
2b170 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   The name of the
2b180 20 6e 65 77 20 63 6f 6c 6c 61 74 69 6f 6e 20 73   new collation s
2b190 65 71 75 65 6e 63 65 20 69 73 20 73 70 65 63 69  equence is speci
2b1a0 66 69 65 64 20 61 73 20 61 20 55 54 46 2d 38 20  fied as a UTF-8 
2b1b0 73 74 72 69 6e 67 0a 2a 2a 20 66 6f 72 20 73 71  string.** for sq
2b1c0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
2b1d0 6c 61 74 69 6f 6e 28 29 20 61 6e 64 20 73 71 6c  lation() and sql
2b1e0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
2b1f0 61 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e  ation_v2().** an
2b200 64 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e  d a UTF-16 strin
2b210 67 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72  g for sqlite3_cr
2b220 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36  eate_collation16
2b230 28 29 2e 20 49 6e 20 61 6c 6c 20 63 61 73 65 73  (). In all cases
2b240 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 69 73 20  .** the name is 
2b250 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65  passed as the se
2b260 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72  cond function ar
2b270 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  gument..**.** Th
2b280 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
2b290 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66 20 74   may be one of t
2b2a0 68 65 20 63 6f 6e 73 74 61 6e 74 73 20 5b 53 51  he constants [SQ
2b2b0 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 5b  LITE_UTF8],.** [
2b2c0 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 20  SQLITE_UTF16LE] 
2b2d0 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  or [SQLITE_UTF16
2b2e0 42 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 20  BE], indicating 
2b2f0 74 68 61 74 20 74 68 65 20 75 73 65 72 2d 73 75  that the user-su
2b300 70 70 6c 69 65 64 0a 2a 2a 20 72 6f 75 74 69 6e  pplied.** routin
2b310 65 20 65 78 70 65 63 74 73 20 74 6f 20 62 65 20  e expects to be 
2b320 70 61 73 73 65 64 20 70 6f 69 6e 74 65 72 73 20  passed pointers 
2b330 74 6f 20 73 74 72 69 6e 67 73 20 65 6e 63 6f 64  to strings encod
2b340 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38 2c 0a  ed using UTF-8,.
2b350 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65  ** UTF-16 little
2b360 2d 65 6e 64 69 61 6e 20 6f 72 20 55 54 46 2d 31  -endian or UTF-1
2b370 36 20 62 69 67 2d 65 6e 64 69 61 6e 20 72 65 73  6 big-endian res
2b380 70 65 63 74 69 76 65 6c 79 2e 20 54 68 65 0a 2a  pectively. The.*
2b390 2a 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  * third argument
2b3a0 20 6d 69 67 68 74 20 61 6c 73 6f 20 62 65 20 5b   might also be [
2b3b0 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49  SQLITE_UTF16_ALI
2b3c0 47 4e 45 44 5d 20 74 6f 20 69 6e 64 69 63 61 74  GNED] to indicat
2b3d0 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 72 6f  e that.** the ro
2b3e0 75 74 69 6e 65 20 65 78 70 65 63 74 73 20 70 6f  utine expects po
2b3f0 69 6e 74 65 72 73 20 74 6f 20 31 36 2d 62 69 74  inters to 16-bit
2b400 20 77 6f 72 64 20 61 6c 69 67 6e 65 64 20 73 74   word aligned st
2b410 72 69 6e 67 73 0a 2a 2a 20 6f 66 20 55 54 46 31  rings.** of UTF1
2b420 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20  6 in the native 
2b430 62 79 74 65 20 6f 72 64 65 72 20 6f 66 20 74 68  byte order of th
2b440 65 20 68 6f 73 74 20 63 6f 6d 70 75 74 65 72 2e  e host computer.
2b450 0a 2a 2a 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72  .**.** A pointer
2b460 20 74 6f 20 74 68 65 20 75 73 65 72 20 73 75 70   to the user sup
2b470 70 6c 69 65 64 20 72 6f 75 74 69 6e 65 20 6d 75  plied routine mu
2b480 73 74 20 62 65 20 70 61 73 73 65 64 20 61 73 20  st be passed as 
2b490 74 68 65 20 66 69 66 74 68 0a 2a 2a 20 61 72 67  the fifth.** arg
2b4a0 75 6d 65 6e 74 2e 20 20 49 66 20 69 74 20 69 73  ument.  If it is
2b4b0 20 4e 55 4c 4c 2c 20 74 68 69 73 20 69 73 20 74   NULL, this is t
2b4c0 68 65 20 73 61 6d 65 20 61 73 20 64 65 6c 65 74  he same as delet
2b4d0 69 6e 67 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f  ing the collatio
2b4e0 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 28 73  n.** sequence (s
2b4f0 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61  o that SQLite ca
2b500 6e 6e 6f 74 20 63 61 6c 6c 20 69 74 20 61 6e 79  nnot call it any
2b510 6d 6f 72 65 29 2e 0a 2a 2a 20 45 61 63 68 20 74  more)..** Each t
2b520 69 6d 65 20 74 68 65 20 61 70 70 6c 69 63 61 74  ime the applicat
2b530 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20  ion.** supplied 
2b540 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f  function is invo
2b550 6b 65 64 2c 20 69 74 20 69 73 20 70 61 73 73 65  ked, it is passe
2b560 64 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  d a copy of the 
2b570 76 6f 69 64 2a 20 70 61 73 73 65 64 20 61 73 0a  void* passed as.
2b580 2a 2a 20 74 68 65 20 66 6f 75 72 74 68 20 61 72  ** the fourth ar
2b590 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
2b5a0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
2b5b0 6f 6e 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74  on() or.** sqlit
2b5c0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
2b5d0 69 6f 6e 31 36 28 29 20 61 73 20 69 74 73 20 66  ion16() as its f
2b5e0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 0a  irst parameter..
2b5f0 2a 2a 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e  **.** The remain
2b600 69 6e 67 20 61 72 67 75 6d 65 6e 74 73 20 74 6f  ing arguments to
2b610 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
2b620 2d 73 75 70 70 6c 69 65 64 20 72 6f 75 74 69 6e  -supplied routin
2b630 65 20 61 72 65 20 74 77 6f 20 73 74 72 69 6e 67  e are two string
2b640 73 2c 0a 2a 2a 20 65 61 63 68 20 72 65 70 72 65  s,.** each repre
2b650 73 65 6e 74 65 64 20 62 79 20 61 20 28 6c 65 6e  sented by a (len
2b660 67 74 68 2c 20 64 61 74 61 29 20 70 61 69 72 20  gth, data) pair 
2b670 61 6e 64 20 65 6e 63 6f 64 65 64 20 69 6e 20 74  and encoded in t
2b680 68 65 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 74  he encoding.** t
2b690 68 61 74 20 77 61 73 20 70 61 73 73 65 64 20 61  hat was passed a
2b6a0 73 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75  s the third argu
2b6b0 6d 65 6e 74 20 77 68 65 6e 20 74 68 65 20 63 6f  ment when the co
2b6c0 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
2b6d0 20 77 61 73 0a 2a 2a 20 72 65 67 69 73 74 65 72   was.** register
2b6e0 65 64 2e 20 7b 45 4e 44 7d 20 54 68 65 20 61 70  ed. {END} The ap
2b6f0 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65  plication define
2b700 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 72 6f 75 74  d collation rout
2b710 69 6e 65 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65  ine should.** re
2b720 74 75 72 6e 20 6e 65 67 61 74 69 76 65 2c 20 7a  turn negative, z
2b730 65 72 6f 20 6f 72 20 70 6f 73 69 74 69 76 65 20  ero or positive 
2b740 69 66 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20  if.** the first 
2b750 73 74 72 69 6e 67 20 69 73 20 6c 65 73 73 20 74  string is less t
2b760 68 61 6e 2c 20 65 71 75 61 6c 20 74 6f 2c 20 6f  han, equal to, o
2b770 72 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 74  r greater than t
2b780 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 73 74 72  he second.** str
2b790 69 6e 67 2e 20 69 2e 65 2e 20 28 53 54 52 49 4e  ing. i.e. (STRIN
2b7a0 47 31 20 2d 20 53 54 52 49 4e 47 32 29 2e 0a 2a  G1 - STRING2)..*
2b7b0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
2b7c0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
2b7d0 6e 5f 76 32 28 29 20 77 6f 72 6b 73 20 6c 69 6b  n_v2() works lik
2b7e0 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  e sqlite3_create
2b7f0 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20  _collation().** 
2b800 65 78 63 61 70 74 20 74 68 61 74 20 69 74 20 74  excapt that it t
2b810 61 6b 65 73 20 61 6e 20 65 78 74 72 61 20 61 72  akes an extra ar
2b820 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
2b830 61 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72  a destructor for
2b840 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f  .** the collatio
2b850 6e 2e 20 20 54 68 65 20 64 65 73 74 72 75 63 74  n.  The destruct
2b860 6f 72 20 69 73 20 63 61 6c 6c 65 64 20 77 68 65  or is called whe
2b870 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20  n the collation 
2b880 69 73 0a 2a 2a 20 64 65 73 74 72 6f 79 65 64 20  is.** destroyed 
2b890 61 6e 64 20 69 73 20 70 61 73 73 65 64 20 61 20  and is passed a 
2b8a0 63 6f 70 79 20 6f 66 20 74 68 65 20 66 6f 75 72  copy of the four
2b8b0 74 68 20 70 61 72 61 6d 65 74 65 72 20 76 6f 69  th parameter voi
2b8c0 64 2a 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 6f 66  d* pointer.** of
2b8d0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65   the sqlite3_cre
2b8e0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
2b8f0 28 29 2e 0a 2a 2a 20 43 6f 6c 6c 61 74 69 6f 6e  ()..** Collation
2b900 73 20 61 72 65 20 64 65 73 74 72 6f 79 65 64 20  s are destroyed 
2b910 77 68 65 6e 0a 2a 2a 20 74 68 65 79 20 61 72 65  when.** they are
2b920 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20 6c   overridden by l
2b930 61 74 65 72 20 63 61 6c 6c 73 20 74 6f 20 74 68  ater calls to th
2b940 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 72 65 61  e collation crea
2b950 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 0a 2a  tion functions.*
2b960 2a 20 6f 72 20 77 68 65 6e 20 74 68 65 20 5b 73  * or when the [s
2b970 71 6c 69 74 65 33 2a 5d 20 64 61 74 61 62 61 73  qlite3*] databas
2b980 65 20 68 61 6e 64 6c 65 20 69 73 20 63 6c 6f 73  e handle is clos
2b990 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
2b9a0 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a  3_close()]..**.*
2b9b0 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
2b9c0 0a 2a 2a 20 7b 46 31 36 36 30 33 7d 20 41 20 73  .** {F16603} A s
2b9d0 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74  uccessful call t
2b9e0 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  o the.**        
2b9f0 20 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74    [sqlite3_creat
2ba00 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42  e_collation_v2(B
2ba10 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 20 69 6e 74  ,X,E,P,F,D)] int
2ba20 65 72 66 61 63 65 0a 2a 2a 20 20 20 20 20 20 20  erface.**       
2ba30 20 20 20 72 65 67 69 73 74 65 72 73 20 66 75 6e     registers fun
2ba40 63 74 69 6f 6e 20 46 20 61 73 20 74 68 65 20 63  ction F as the c
2ba50 6f 6d 70 61 72 69 73 6f 6e 20 66 75 6e 63 74 69  omparison functi
2ba60 6f 6e 20 75 73 65 64 20 74 6f 0a 2a 2a 20 20 20  on used to.**   
2ba70 20 20 20 20 20 20 20 69 6d 70 6c 65 6d 65 6e 74         implement
2ba80 20 63 6f 6c 6c 61 74 69 6f 6e 20 58 20 6f 6e 20   collation X on 
2ba90 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2baa0 74 69 6f 6e 5d 20 42 20 66 6f 72 0a 2a 2a 20 20  tion] B for.**  
2bab0 20 20 20 20 20 20 20 20 64 61 74 61 62 61 73 65          database
2bac0 73 20 68 61 76 69 6e 67 20 65 6e 63 6f 64 69 6e  s having encodin
2bad0 67 20 45 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36  g E..**.** {F166
2bae0 30 34 7d 20 53 51 4c 69 74 65 20 75 6e 64 65 72  04} SQLite under
2baf0 73 74 61 6e 64 73 20 74 68 65 20 58 20 70 61 72  stands the X par
2bb00 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 20 20 20  ameter to.**    
2bb10 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63        [sqlite3_c
2bb20 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
2bb30 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d  v2(B,X,E,P,F,D)]
2bb40 20 61 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   as a zero-termi
2bb50 6e 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  nated.**        
2bb60 20 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 69    UTF-8 string i
2bb70 6e 20 77 68 69 63 68 20 63 61 73 65 20 69 73 20  n which case is 
2bb80 69 67 6e 6f 72 65 64 20 66 6f 72 20 41 53 43 49  ignored for ASCI
2bb90 49 20 63 68 61 72 61 63 74 65 72 73 20 61 6e 64  I characters and
2bba0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20  .**          is 
2bbb0 73 69 67 6e 69 66 69 63 61 6e 74 20 66 6f 72 20  significant for 
2bbc0 6e 6f 6e 2d 41 53 43 49 49 20 63 68 61 72 61 63  non-ASCII charac
2bbd0 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  ters..**.** {F16
2bbe0 36 30 36 7d 20 53 75 63 63 65 73 73 69 76 65 20  606} Successive 
2bbf0 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
2bc00 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
2bc10 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c  on_v2(B,X,E,P,F,
2bc20 44 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  D)].**          
2bc30 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 76 61  with the same va
2bc40 6c 75 65 73 20 66 6f 72 20 42 2c 20 58 2c 20 61  lues for B, X, a
2bc50 6e 64 20 45 2c 20 6f 76 65 72 72 69 64 65 20 70  nd E, override p
2bc60 72 69 6f 72 20 76 61 6c 75 65 73 0a 2a 2a 20 20  rior values.**  
2bc70 20 20 20 20 20 20 20 20 6f 66 20 50 2c 20 46 2c          of P, F,
2bc80 20 61 6e 64 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46   and D..**.** {F
2bc90 31 36 36 30 39 7d 20 54 68 65 20 64 65 73 74 72  16609} The destr
2bca0 75 63 74 6f 72 20 44 20 69 6e 20 5b 73 71 6c 69  uctor D in [sqli
2bcb0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
2bcc0 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c  tion_v2(B,X,E,P,
2bcd0 46 2c 44 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  F,D)].**        
2bce0 20 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68    is not NULL th
2bcf0 65 6e 20 69 74 20 69 73 20 63 61 6c 6c 65 64 20  en it is called 
2bd00 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 50 20  with argument P 
2bd10 77 68 65 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20  when the.**     
2bd20 20 20 20 20 20 63 6f 6c 6c 61 74 69 6e 67 20 66       collating f
2bd30 75 6e 63 74 69 6f 6e 20 69 73 20 64 72 6f 70 70  unction is dropp
2bd40 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2a  ed by SQLite..**
2bd50 0a 2a 2a 20 7b 46 31 36 36 31 32 7d 20 41 20 63  .** {F16612} A c
2bd60 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
2bd70 6e 20 69 73 20 64 72 6f 70 70 65 64 20 77 68 65  n is dropped whe
2bd80 6e 20 69 74 20 69 73 20 6f 76 65 72 6c 6f 61 64  n it is overload
2bd90 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36 31  ed..**.** {F1661
2bda0 35 7d 20 41 20 63 6f 6c 6c 61 74 69 6e 67 20 66  5} A collating f
2bdb0 75 6e 63 74 69 6f 6e 20 69 73 20 64 72 6f 70 70  unction is dropp
2bdc0 65 64 20 77 68 65 6e 20 74 68 65 20 64 61 74 61  ed when the data
2bdd0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
2bde0 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 63  **          is c
2bdf0 6c 6f 73 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  losed using [sql
2be00 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a  ite3_close()]..*
2be10 2a 0a 2a 2a 20 7b 46 31 36 36 31 38 7d 20 54 68  *.** {F16618} Th
2be20 65 20 70 6f 69 6e 74 65 72 20 50 20 69 6e 20 5b  e pointer P in [
2be30 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
2be40 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c  ollation_v2(B,X,
2be50 45 2c 50 2c 46 2c 44 29 5d 0a 2a 2a 20 20 20 20  E,P,F,D)].**    
2be60 20 20 20 20 20 20 69 73 20 70 61 73 73 65 64 20        is passed 
2be70 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 66  through as the f
2be80 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
2be90 6f 20 74 68 65 20 63 6f 6d 70 61 72 69 73 6f 6e  o the comparison
2bea0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 75 6e  .**          fun
2beb0 63 74 69 6f 6e 20 46 20 66 6f 72 20 61 6c 6c 20  ction F for all 
2bec0 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63  subsequent invoc
2bed0 61 74 69 6f 6e 73 20 6f 66 20 46 2e 0a 2a 2a 0a  ations of F..**.
2bee0 2a 2a 20 7b 46 31 36 36 32 31 7d 20 41 20 63 61  ** {F16621} A ca
2bef0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
2bf00 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
2bf10 42 2c 58 2c 45 2c 50 2c 46 29 5d 20 69 73 20 65  B,X,E,P,F)] is e
2bf20 78 61 63 74 6c 79 0a 2a 2a 20 20 20 20 20 20 20  xactly.**       
2bf30 20 20 20 74 68 65 20 73 61 6d 65 20 61 73 20 61     the same as a
2bf40 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
2bf50 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
2bf60 6f 6e 5f 76 32 28 29 5d 20 77 69 74 68 0a 2a 2a  on_v2()] with.**
2bf70 20 20 20 20 20 20 20 20 20 20 74 68 65 20 73 61            the sa
2bf80 6d 65 20 70 61 72 61 6d 65 74 65 72 73 20 61 6e  me parameters an
2bf90 64 20 61 20 4e 55 4c 4c 20 64 65 73 74 72 75 63  d a NULL destruc
2bfa0 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36  tor..**.** {F166
2bfb0 32 34 7d 20 46 6f 6c 6c 6f 77 69 6e 67 20 61 20  24} Following a 
2bfc0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2bfd0 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c 58  collation_v2(B,X
2bfe0 2c 45 2c 50 2c 46 2c 44 29 5d 2c 0a 2a 2a 20 20  ,E,P,F,D)],.**  
2bff0 20 20 20 20 20 20 20 20 53 51 4c 69 74 65 20 75          SQLite u
2c000 73 65 73 20 74 68 65 20 63 6f 6d 70 61 72 69 73  ses the comparis
2c010 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 46 20 66 6f  on function F fo
2c020 72 20 61 6c 6c 20 74 65 78 74 20 63 6f 6d 70 61  r all text compa
2c030 72 69 73 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20  rison.**        
2c040 20 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20    operations on 
2c050 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2c060 74 69 6f 6e 5d 20 42 20 6f 6e 20 74 65 78 74 20  tion] B on text 
2c070 76 61 6c 75 65 73 20 74 68 61 74 0a 2a 2a 20 20  values that.**  
2c080 20 20 20 20 20 20 20 20 75 73 65 20 74 68 65 20          use the 
2c090 63 6f 6c 6c 61 74 69 6e 67 20 73 65 71 75 65 6e  collating sequen
2c0a0 63 65 20 6e 61 6d 65 20 58 2e 0a 2a 2a 0a 2a 2a  ce name X..**.**
2c0b0 20 7b 46 31 36 36 32 37 7d 20 54 68 65 20 5b 73   {F16627} The [s
2c0c0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
2c0d0 6c 6c 61 74 69 6f 6e 31 36 28 42 2c 58 2c 45 2c  llation16(B,X,E,
2c0e0 50 2c 46 29 5d 20 77 6f 72 6b 73 20 74 68 65 20  P,F)] works the 
2c0f0 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  same.**         
2c100 20 61 73 20 5b 73 71 6c 69 74 65 33 5f 63 72 65   as [sqlite3_cre
2c110 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 42 2c  ate_collation(B,
2c120 58 2c 45 2c 50 2c 46 29 5d 20 65 78 63 65 70 74  X,E,P,F)] except
2c130 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 20 20 20   that the.**    
2c140 20 20 20 20 20 20 63 6f 6c 6c 61 74 69 6f 6e 20        collation 
2c150 6e 61 6d 65 20 58 20 69 73 20 75 6e 64 65 72 73  name X is unders
2c160 74 6f 6f 64 20 61 73 20 55 54 46 2d 31 36 20 69  tood as UTF-16 i
2c170 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  n native byte or
2c180 64 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  der.**          
2c190 69 6e 73 74 65 61 64 20 6f 66 20 55 54 46 2d 38  instead of UTF-8
2c1a0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36 33 30 7d  ..**.** {F16630}
2c1b0 20 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 63   When multiple c
2c1c0 6f 6d 70 61 72 69 73 6f 6e 20 66 75 6e 63 74 69  omparison functi
2c1d0 6f 6e 73 20 61 72 65 20 61 76 61 69 6c 61 62 6c  ons are availabl
2c1e0 65 20 66 6f 72 20 74 68 65 20 73 61 6d 65 0a 2a  e for the same.*
2c1f0 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6c 6c 61  *          colla
2c200 74 69 6e 67 20 73 65 71 75 65 6e 63 65 2c 20 53  ting sequence, S
2c210 51 4c 69 74 65 20 63 68 6f 6f 73 65 73 20 74 68  QLite chooses th
2c220 65 20 6f 6e 65 20 77 68 6f 73 65 20 74 65 78 74  e one whose text
2c230 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 20 20 20   encoding.**    
2c240 20 20 20 20 20 20 72 65 71 75 69 72 65 73 20 74        requires t
2c250 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20  he least amount 
2c260 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72  of conversion fr
2c270 6f 6d 20 74 68 65 20 64 65 66 61 75 6c 74 0a 2a  om the default.*
2c280 2a 20 20 20 20 20 20 20 20 20 20 74 65 78 74 20  *          text 
2c290 65 6e 63 6f 64 69 6e 67 20 6f 66 20 74 68 65 20  encoding of the 
2c2a0 64 61 74 61 62 61 73 65 2e 0a 2a 2f 0a 69 6e 74  database..*/.int
2c2b0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2c2c0 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20 73 71 6c  collation(.  sql
2c2d0 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20  ite3*, .  const 
2c2e0 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20  char *zName, .  
2c2f0 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20  int eTextRep, . 
2c300 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78   void*,.  int(*x
2c310 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69  Compare)(void*,i
2c320 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69  nt,const void*,i
2c330 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a  nt,const void*).
2c340 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
2c350 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
2c360 76 32 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  v2(.  sqlite3*, 
2c370 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
2c380 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65  Name, .  int eTe
2c390 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c  xtRep, .  void*,
2c3a0 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65  .  int(*xCompare
2c3b0 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
2c3c0 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  t void*,int,cons
2c3d0 74 20 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64  t void*),.  void
2c3e0 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64  (*xDestroy)(void
2c3f0 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  *).);.int sqlite
2c400 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
2c410 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a  on16(.  sqlite3*
2c420 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  , .  const char 
2c430 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65  *zName, .  int e
2c440 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64  TextRep, .  void
2c450 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61  *,.  int(*xCompa
2c460 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  re)(void*,int,co
2c470 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  nst void*,int,co
2c480 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f  nst void*).);../
2c490 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
2c4a0 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65 64 65 64 20  ollation Needed 
2c4b0 43 61 6c 6c 62 61 63 6b 73 20 7b 46 31 36 37 30  Callbacks {F1670
2c4c0 30 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 61 76 6f 69  0}.**.** To avoi
2c4d0 64 20 68 61 76 69 6e 67 20 74 6f 20 72 65 67 69  d having to regi
2c4e0 73 74 65 72 20 61 6c 6c 20 63 6f 6c 6c 61 74 69  ster all collati
2c4f0 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 62 65 66  on sequences bef
2c500 6f 72 65 20 61 20 64 61 74 61 62 61 73 65 0a 2a  ore a database.*
2c510 2a 20 63 61 6e 20 62 65 20 75 73 65 64 2c 20 61  * can be used, a
2c520 20 73 69 6e 67 6c 65 20 63 61 6c 6c 62 61 63 6b   single callback
2c530 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65   function may be
2c540 20 72 65 67 69 73 74 65 72 65 64 20 77 69 74 68   registered with
2c550 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
2c560 20 68 61 6e 64 6c 65 20 74 6f 20 62 65 20 63 61   handle to be ca
2c570 6c 6c 65 64 20 77 68 65 6e 65 76 65 72 20 61 6e  lled whenever an
2c580 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61   undefined colla
2c590 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 69 73  tion sequence is
2c5a0 0a 2a 2a 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a  .** required..**
2c5b0 0a 2a 2a 20 49 66 20 74 68 65 20 66 75 6e 63 74  .** If the funct
2c5c0 69 6f 6e 20 69 73 20 72 65 67 69 73 74 65 72 65  ion is registere
2c5d0 64 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69  d using the sqli
2c5e0 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
2c5f0 65 64 65 64 28 29 20 41 50 49 2c 0a 2a 2a 20 74  eded() API,.** t
2c600 68 65 6e 20 69 74 20 69 73 20 70 61 73 73 65 64  hen it is passed
2c610 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 75 6e   the names of un
2c620 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f  defined collatio
2c630 6e 20 73 65 71 75 65 6e 63 65 73 20 61 73 20 73  n sequences as s
2c640 74 72 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64 65  trings.** encode
2c650 64 20 69 6e 20 55 54 46 2d 38 2e 20 7b 46 31 36  d in UTF-8. {F16
2c660 37 30 33 7d 20 49 66 20 73 71 6c 69 74 65 33 5f  703} If sqlite3_
2c670 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
2c680 31 36 28 29 20 69 73 20 75 73 65 64 2c 20 74 68  16() is used, th
2c690 65 20 6e 61 6d 65 73 0a 2a 2a 20 61 72 65 20 70  e names.** are p
2c6a0 61 73 73 65 64 20 61 73 20 55 54 46 2d 31 36 20  assed as UTF-16 
2c6b0 69 6e 20 6d 61 63 68 69 6e 65 20 6e 61 74 69 76  in machine nativ
2c6c0 65 20 62 79 74 65 20 6f 72 64 65 72 2e 20 41 20  e byte order. A 
2c6d0 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72 0a 2a  call to either.*
2c6e0 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 70 6c 61  * function repla
2c6f0 63 65 73 20 61 6e 79 20 65 78 69 73 74 69 6e 67  ces any existing
2c700 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a   callback..**.**
2c710 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61   When the callba
2c720 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74  ck is invoked, t
2c730 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
2c740 74 20 70 61 73 73 65 64 20 69 73 20 61 20 63 6f  t passed is a co
2c750 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 65 63  py.** of the sec
2c760 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
2c770 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
2c780 6e 5f 6e 65 65 64 65 64 28 29 20 6f 72 0a 2a 2a  n_needed() or.**
2c790 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
2c7a0 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 2e 20 20  on_needed16().  
2c7b0 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
2c7c0 65 6e 74 20 69 73 20 74 68 65 20 64 61 74 61 62  ent is the datab
2c7d0 61 73 65 0a 2a 2a 20 68 61 6e 64 6c 65 2e 20 20  ase.** handle.  
2c7e0 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
2c7f0 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51  nt is one of [SQ
2c800 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 5b  LITE_UTF8],.** [
2c810 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c  SQLITE_UTF16BE],
2c820 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31   or [SQLITE_UTF1
2c830 36 4c 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67  6LE], indicating
2c840 20 74 68 65 20 6d 6f 73 74 0a 2a 2a 20 64 65 73   the most.** des
2c850 69 72 61 62 6c 65 20 66 6f 72 6d 20 6f 66 20 74  irable form of t
2c860 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  he collation seq
2c870 75 65 6e 63 65 20 66 75 6e 63 74 69 6f 6e 20 72  uence function r
2c880 65 71 75 69 72 65 64 2e 0a 2a 2a 20 54 68 65 20  equired..** The 
2c890 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
2c8a0 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
2c8b0 74 68 65 0a 2a 2a 20 72 65 71 75 69 72 65 64 20  the.** required 
2c8c0 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
2c8d0 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61  ce..**.** The ca
2c8e0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
2c8f0 73 68 6f 75 6c 64 20 72 65 67 69 73 74 65 72 20  should register 
2c900 74 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c 6c  the desired coll
2c910 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b  ation using.** [
2c920 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
2c930 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b 73 71  ollation()], [sq
2c940 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
2c950 6c 61 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a  lation16()], or.
2c960 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ** [sqlite3_crea
2c970 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
2c980 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  )]..**.** INVARI
2c990 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  ANTS:.**.** {F16
2c9a0 37 30 32 7d 20 41 20 73 75 63 63 65 73 73 66 75  702} A successfu
2c9b0 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  l call to [sqlit
2c9c0 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
2c9d0 64 65 64 28 44 2c 50 2c 46 29 5d 0a 2a 2a 20 20  ded(D,P,F)].**  
2c9e0 20 20 20 20 20 20 20 20 6f 72 20 5b 73 71 6c 69          or [sqli
2c9f0 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
2ca00 65 64 65 64 31 36 28 44 2c 50 2c 46 29 5d 20 63  eded16(D,P,F)] c
2ca10 61 75 73 65 73 0a 2a 2a 20 20 20 20 20 20 20 20  auses.**        
2ca20 20 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20    the [database 
2ca30 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 74 6f  connection] D to
2ca40 20 69 6e 76 6f 6b 65 20 63 61 6c 6c 62 61 63 6b   invoke callback
2ca50 20 46 20 77 69 74 68 20 66 69 72 73 74 0a 2a 2a   F with first.**
2ca60 20 20 20 20 20 20 20 20 20 20 70 61 72 61 6d 65            parame
2ca70 74 65 72 20 50 20 77 68 65 6e 65 76 65 72 20 69  ter P whenever i
2ca80 74 20 6e 65 65 64 73 20 61 20 63 6f 6d 70 61 72  t needs a compar
2ca90 69 73 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 66 6f  ison function fo
2caa0 72 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  r a.**          
2cab0 63 6f 6c 6c 61 74 69 6e 67 20 73 65 71 75 65 6e  collating sequen
2cac0 63 65 20 74 68 61 74 20 69 74 20 64 6f 65 73 20  ce that it does 
2cad0 6e 6f 74 20 6b 6e 6f 77 20 61 62 6f 75 74 2e 0a  not know about..
2cae0 2a 2a 0a 2a 2a 20 7b 46 31 36 37 30 34 7d 20 45  **.** {F16704} E
2caf0 61 63 68 20 73 75 63 63 65 73 73 66 75 6c 20 63  ach successful c
2cb00 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
2cb10 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
2cb20 28 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20  ()] or.**       
2cb30 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c     [sqlite3_coll
2cb40 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29  ation_needed16()
2cb50 5d 20 6f 76 65 72 72 69 64 65 73 20 74 68 65 20  ] overrides the 
2cb60 63 61 6c 6c 62 61 63 6b 20 72 65 67 69 73 74 65  callback registe
2cb70 72 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  red.**          
2cb80 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74  on the same [dat
2cb90 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2cba0 5d 20 62 79 20 70 72 69 6f 72 20 63 61 6c 6c 73  ] by prior calls
2cbb0 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 20 20   to either.**   
2cbc0 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65         interface
2cbd0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 37 30 36 7d  ..**.** {F16706}
2cbe0 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   The name of the
2cbf0 20 72 65 71 75 65 73 74 65 64 20 63 6f 6c 6c 61   requested colla
2cc00 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70 61  ting function pa
2cc10 73 73 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 20  ssed in the.**  
2cc20 20 20 20 20 20 20 20 20 34 74 68 20 70 61 72 61          4th para
2cc30 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c  meter to the cal
2cc40 6c 62 61 63 6b 20 69 73 20 69 6e 20 55 54 46 2d  lback is in UTF-
2cc50 38 20 69 66 20 74 68 65 20 63 61 6c 6c 62 61 63  8 if the callbac
2cc60 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 61  k.**          wa
2cc70 73 20 72 65 67 69 73 74 65 72 65 64 20 75 73 69  s registered usi
2cc80 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  ng [sqlite3_coll
2cc90 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d 20  ation_needed()] 
2cca0 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  and.**          
2ccb0 69 73 20 69 6e 20 55 54 46 2d 31 36 20 6e 61 74  is in UTF-16 nat
2ccc0 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 69  ive byte order i
2ccd0 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 77  f the callback w
2cce0 61 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  as.**          r
2ccf0 65 67 69 73 74 65 72 65 64 20 75 73 69 6e 67 20  egistered using 
2cd00 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69  [sqlite3_collati
2cd10 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 5d 2e 0a  on_needed16()]..
2cd20 2a 2a 0a 2a 2a 20 0a 2a 2f 0a 69 6e 74 20 73 71  **.** .*/.int sq
2cd30 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
2cd40 6e 65 65 64 65 64 28 0a 20 20 73 71 6c 69 74 65  needed(.  sqlite
2cd50 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 20 0a 20  3*, .  void*, . 
2cd60 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73   void(*)(void*,s
2cd70 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78  qlite3*,int eTex
2cd80 74 52 65 70 2c 63 6f 6e 73 74 20 63 68 61 72 2a  tRep,const char*
2cd90 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ).);.int sqlite3
2cda0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
2cdb0 64 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  d16(.  sqlite3*,
2cdc0 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f 69   .  void*,.  voi
2cdd0 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74  d(*)(void*,sqlit
2cde0 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70  e3*,int eTextRep
2cdf0 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b  ,const void*).);
2ce00 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20  ../*.** Specify 
2ce10 74 68 65 20 6b 65 79 20 66 6f 72 20 61 6e 20 65  the key for an e
2ce20 6e 63 72 79 70 74 65 64 20 64 61 74 61 62 61 73  ncrypted databas
2ce30 65 2e 20 20 54 68 69 73 20 72 6f 75 74 69 6e 65  e.  This routine
2ce40 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 63 61   should be.** ca
2ce50 6c 6c 65 64 20 72 69 67 68 74 20 61 66 74 65 72  lled right after
2ce60 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 2e   sqlite3_open().
2ce70 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20  .**.** The code 
2ce80 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69  to implement thi
2ce90 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61  s API is not ava
2cea0 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75  ilable in the pu
2ceb0 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20  blic release.** 
2cec0 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e  of SQLite..*/.in
2ced0 74 20 73 71 6c 69 74 65 33 5f 6b 65 79 28 0a 20  t sqlite3_key(. 
2cee0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
2cef0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2cf00 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62  /* Database to b
2cf10 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63  e rekeyed */.  c
2cf20 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c  onst void *pKey,
2cf30 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a   int nKey     /*
2cf40 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a   The key */.);..
2cf50 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65 20 74 68 65  /*.** Change the
2cf60 20 6b 65 79 20 6f 6e 20 61 6e 20 6f 70 65 6e 20   key on an open 
2cf70 64 61 74 61 62 61 73 65 2e 20 20 49 66 20 74 68  database.  If th
2cf80 65 20 63 75 72 72 65 6e 74 20 64 61 74 61 62 61  e current databa
2cf90 73 65 20 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63  se is not.** enc
2cfa0 72 79 70 74 65 64 2c 20 74 68 69 73 20 72 6f 75  rypted, this rou
2cfb0 74 69 6e 65 20 77 69 6c 6c 20 65 6e 63 72 79 70  tine will encryp
2cfc0 74 20 69 74 2e 20 20 49 66 20 70 4e 65 77 3d 3d  t it.  If pNew==
2cfd0 30 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20 74 68  0 or nNew==0, th
2cfe0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 69 73  e.** database is
2cff0 20 64 65 63 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a   decrypted..**.*
2d000 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d  * The code to im
2d010 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49  plement this API
2d020 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c   is not availabl
2d030 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20  e in the public 
2d040 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51  release.** of SQ
2d050 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  Lite..*/.int sql
2d060 69 74 65 33 5f 72 65 6b 65 79 28 0a 20 20 73 71  ite3_rekey(.  sq
2d070 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
2d080 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
2d090 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72  Database to be r
2d0a0 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73  ekeyed */.  cons
2d0b0 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e  t void *pKey, in
2d0c0 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68  t nKey     /* Th
2d0d0 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a  e new key */.);.
2d0e0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2d0f0 20 20 53 75 73 70 65 6e 64 20 45 78 65 63 75 74    Suspend Execut
2d100 69 6f 6e 20 46 6f 72 20 41 20 53 68 6f 72 74 20  ion For A Short 
2d110 54 69 6d 65 20 7b 46 31 30 35 33 30 7d 0a 2a 2a  Time {F10530}.**
2d120 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
2d130 73 6c 65 65 70 28 29 20 66 75 6e 63 74 69 6f 6e  sleep() function
2d140 0a 2a 2a 20 63 61 75 73 65 73 20 74 68 65 20 63  .** causes the c
2d150 75 72 72 65 6e 74 20 74 68 72 65 61 64 20 74 6f  urrent thread to
2d160 20 73 75 73 70 65 6e 64 20 65 78 65 63 75 74 69   suspend executi
2d170 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74 20 6c 65 61  on.** for at lea
2d180 73 74 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 6d  st a number of m
2d190 69 6c 6c 69 73 65 63 6f 6e 64 73 20 73 70 65 63  illiseconds spec
2d1a0 69 66 69 65 64 20 69 6e 20 69 74 73 20 70 61 72  ified in its par
2d1b0 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66  ameter..**.** If
2d1c0 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
2d1d0 79 73 74 65 6d 20 64 6f 65 73 20 6e 6f 74 20 73  ystem does not s
2d1e0 75 70 70 6f 72 74 20 73 6c 65 65 70 20 72 65 71  upport sleep req
2d1f0 75 65 73 74 73 20 77 69 74 68 20 0a 2a 2a 20 6d  uests with .** m
2d200 69 6c 6c 69 73 65 63 6f 6e 64 20 74 69 6d 65 20  illisecond time 
2d210 72 65 73 6f 6c 75 74 69 6f 6e 2c 20 74 68 65 6e  resolution, then
2d220 20 74 68 65 20 74 69 6d 65 20 77 69 6c 6c 20 62   the time will b
2d230 65 20 72 6f 75 6e 64 65 64 20 75 70 20 74 6f 20  e rounded up to 
2d240 0a 2a 2a 20 74 68 65 20 6e 65 61 72 65 73 74 20  .** the nearest 
2d250 73 65 63 6f 6e 64 2e 20 54 68 65 20 6e 75 6d 62  second. The numb
2d260 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e  er of millisecon
2d270 64 73 20 6f 66 20 73 6c 65 65 70 20 61 63 74 75  ds of sleep actu
2d280 61 6c 6c 79 20 0a 2a 2a 20 72 65 71 75 65 73 74  ally .** request
2d290 65 64 20 66 72 6f 6d 20 74 68 65 20 6f 70 65 72  ed from the oper
2d2a0 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 73 20  ating system is 
2d2b0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
2d2c0 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74  SQLite implement
2d2d0 73 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  s this interface
2d2e0 20 62 79 20 63 61 6c 6c 69 6e 67 20 74 68 65 20   by calling the 
2d2f0 78 53 6c 65 65 70 28 29 0a 2a 2a 20 6d 65 74 68  xSleep().** meth
2d300 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c  od of the defaul
2d310 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  t [sqlite3_vfs] 
2d320 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 4e  object..**.** IN
2d330 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
2d340 7b 46 31 30 35 33 33 7d 20 54 68 65 20 5b 73 71  {F10533} The [sq
2d350 6c 69 74 65 33 5f 73 6c 65 65 70 28 4d 29 5d 20  lite3_sleep(M)] 
2d360 69 6e 74 65 72 66 61 63 65 20 69 6e 76 6f 6b 65  interface invoke
2d370 73 20 74 68 65 20 78 53 6c 65 65 70 0a 2a 2a 20  s the xSleep.** 
2d380 20 20 20 20 20 20 20 20 20 6d 65 74 68 6f 64 20           method 
2d390 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b  of the default [
2d3a0 73 71 6c 69 74 65 33 5f 76 66 73 7c 56 46 53 5d  sqlite3_vfs|VFS]
2d3b0 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20   in order to.** 
2d3c0 20 20 20 20 20 20 20 20 20 73 75 73 70 65 6e 64           suspend
2d3d0 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68   execution of th
2d3e0 65 20 63 75 72 72 65 6e 74 20 74 68 72 65 61 64  e current thread
2d3f0 20 66 6f 72 20 61 74 20 6c 65 61 73 74 0a 2a 2a   for at least.**
2d400 20 20 20 20 20 20 20 20 20 20 4d 20 6d 69 6c 6c            M mill
2d410 69 73 65 63 6f 6e 64 73 2e 0a 2a 2a 0a 2a 2a 20  iseconds..**.** 
2d420 7b 46 31 30 35 33 36 7d 20 54 68 65 20 5b 73 71  {F10536} The [sq
2d430 6c 69 74 65 33 5f 73 6c 65 65 70 28 4d 29 5d 20  lite3_sleep(M)] 
2d440 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2d450 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  s the number of.
2d460 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 69 6c 6c  **          mill
2d470 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65  iseconds of slee
2d480 70 20 61 63 74 75 61 6c 6c 79 20 72 65 71 75 65  p actually reque
2d490 73 74 65 64 20 6f 66 20 74 68 65 20 6f 70 65 72  sted of the oper
2d4a0 61 74 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20  ating.**        
2d4b0 20 20 73 79 73 74 65 6d 2c 20 77 68 69 63 68 20    system, which 
2d4c0 6d 69 67 68 74 20 62 65 20 6c 61 72 67 65 72 20  might be larger 
2d4d0 74 68 61 6e 20 74 68 65 20 70 61 72 61 6d 65 74  than the paramet
2d4e0 65 72 20 4d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  er M..*/.int sql
2d4f0 69 74 65 33 5f 73 6c 65 65 70 28 69 6e 74 29 3b  ite3_sleep(int);
2d500 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2d510 3a 20 20 4e 61 6d 65 20 4f 66 20 54 68 65 20 46  :  Name Of The F
2d520 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20 54 65  older Holding Te
2d530 6d 70 6f 72 61 72 79 20 46 69 6c 65 73 20 7b 46  mporary Files {F
2d540 31 30 33 31 30 7d 0a 2a 2a 0a 2a 2a 20 49 66 20  10310}.**.** If 
2d550 74 68 69 73 20 67 6c 6f 62 61 6c 20 76 61 72 69  this global vari
2d560 61 62 6c 65 20 69 73 20 6d 61 64 65 20 74 6f 20  able is made to 
2d570 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e  point to a strin
2d580 67 20 77 68 69 63 68 20 69 73 0a 2a 2a 20 74 68  g which is.** th
2d590 65 20 6e 61 6d 65 20 6f 66 20 61 20 66 6f 6c 64  e name of a fold
2d5a0 65 72 20 28 61 2e 6b 61 2e 20 64 69 72 65 63 74  er (a.ka. direct
2d5b0 6f 72 79 29 2c 20 74 68 65 6e 20 61 6c 6c 20 74  ory), then all t
2d5c0 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 0a 2a  emporary files.*
2d5d0 2a 20 63 72 65 61 74 65 64 20 62 79 20 53 51 4c  * created by SQL
2d5e0 69 74 65 20 77 69 6c 6c 20 62 65 20 70 6c 61 63  ite will be plac
2d5f0 65 64 20 69 6e 20 74 68 61 74 20 64 69 72 65 63  ed in that direc
2d600 74 6f 72 79 2e 20 20 49 66 20 74 68 69 73 20 76  tory.  If this v
2d610 61 72 69 61 62 6c 65 0a 2a 2a 20 69 73 20 4e 55  ariable.** is NU
2d620 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e  LL pointer, then
2d630 20 53 51 4c 69 74 65 20 64 6f 65 73 20 61 20 73   SQLite does a s
2d640 65 61 72 63 68 20 66 6f 72 20 61 6e 20 61 70 70  earch for an app
2d650 72 6f 70 72 69 61 74 65 20 74 65 6d 70 6f 72 61  ropriate tempora
2d660 72 79 0a 2a 2a 20 66 69 6c 65 20 64 69 72 65 63  ry.** file direc
2d670 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69  tory..**.** It i
2d680 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 6d 6f  s not safe to mo
2d690 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62  dify this variab
2d6a0 6c 65 20 6f 6e 63 65 20 61 20 64 61 74 61 62 61  le once a databa
2d6b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
2d6c0 20 68 61 73 20 62 65 65 6e 20 6f 70 65 6e 65 64   has been opened
2d6d0 2e 20 20 49 74 20 69 73 20 69 6e 74 65 6e 64 65  .  It is intende
2d6e0 64 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69  d that this vari
2d6f0 61 62 6c 65 20 62 65 20 73 65 74 20 6f 6e 63 65  able be set once
2d700 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20 70  .** as part of p
2d710 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a  rocess initializ
2d720 61 74 69 6f 6e 20 61 6e 64 20 62 65 66 6f 72 65  ation and before
2d730 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65   any SQLite inte
2d740 72 66 61 63 65 0a 2a 2a 20 72 6f 75 74 69 6e 65  rface.** routine
2d750 73 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c  s have been call
2d760 20 61 6e 64 20 72 65 6d 61 69 6e 20 75 6e 63 68   and remain unch
2d770 61 6e 67 65 64 20 74 68 65 72 65 61 66 74 65 72  anged thereafter
2d780 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45  ..*/.SQLITE_EXTE
2d790 52 4e 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  RN char *sqlite3
2d7a0 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 3b  _temp_directory;
2d7b0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2d7c0 3a 20 20 54 65 73 74 20 54 6f 20 53 65 65 20 49  :  Test To See I
2d7d0 66 20 54 68 65 20 44 61 74 61 62 61 73 65 20 49  f The Database I
2d7e0 73 20 49 6e 20 41 75 74 6f 2d 43 6f 6d 6d 69 74  s In Auto-Commit
2d7f0 20 4d 6f 64 65 20 7b 46 31 32 39 33 30 7d 0a 2a   Mode {F12930}.*
2d800 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
2d810 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28  _get_autocommit(
2d820 29 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 74  ) interfaces ret
2d830 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72  urns non-zero or
2d840 0a 2a 2a 20 7a 65 72 6f 20 69 66 20 74 68 65 20  .** zero if the 
2d850 67 69 76 65 6e 20 64 61 74 61 62 61 73 65 20 63  given database c
2d860 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 72 20  onnection is or 
2d870 69 73 20 6e 6f 74 20 69 6e 20 61 75 74 6f 63 6f  is not in autoco
2d880 6d 6d 69 74 20 6d 6f 64 65 2c 0a 2a 2a 20 72 65  mmit mode,.** re
2d890 73 70 65 63 74 69 76 65 6c 79 2e 20 20 20 41 75  spectively.   Au
2d8a0 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73  tocommit mode is
2d8b0 20 6f 6e 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c   on.** by defaul
2d8c0 74 2e 20 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d  t.  Autocommit m
2d8d0 6f 64 65 20 69 73 20 64 69 73 61 62 6c 65 64 20  ode is disabled 
2d8e0 62 79 20 61 20 5b 42 45 47 49 4e 5d 20 73 74 61  by a [BEGIN] sta
2d8f0 74 65 6d 65 6e 74 2e 0a 2a 2a 20 41 75 74 6f 63  tement..** Autoc
2d900 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 72 65  ommit mode is re
2d910 65 6e 61 62 6c 65 64 20 62 79 20 61 20 5b 43 4f  enabled by a [CO
2d920 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41  MMIT] or [ROLLBA
2d930 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 63 65  CK]..**.** If ce
2d940 72 74 61 69 6e 20 6b 69 6e 64 73 20 6f 66 20 65  rtain kinds of e
2d950 72 72 6f 72 73 20 6f 63 63 75 72 20 6f 6e 20 61  rrors occur on a
2d960 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69   statement withi
2d970 6e 20 61 20 6d 75 6c 74 69 2d 73 74 61 74 65 6d  n a multi-statem
2d980 65 6e 74 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69  ent.** transacti
2d990 6f 6e 73 20 28 65 72 72 6f 72 73 20 69 6e 63 6c  ons (errors incl
2d9a0 75 64 69 6e 67 20 5b 53 51 4c 49 54 45 5f 46 55  uding [SQLITE_FU
2d9b0 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4f 45  LL], [SQLITE_IOE
2d9c0 52 52 5d 2c 20 0a 2a 2a 20 5b 53 51 4c 49 54 45  RR], .** [SQLITE
2d9d0 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53 51 4c 49 54 45  _NOMEM], [SQLITE
2d9e0 5f 42 55 53 59 5d 2c 20 61 6e 64 20 5b 53 51 4c  _BUSY], and [SQL
2d9f0 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 29 20  ITE_INTERRUPT]) 
2da00 74 68 65 6e 20 74 68 65 0a 2a 2a 20 74 72 61 6e  then the.** tran
2da10 73 61 63 74 69 6f 6e 20 6d 69 67 68 74 20 62 65  saction might be
2da20 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74   rolled back aut
2da30 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54 68 65  omatically.  The
2da40 20 6f 6e 6c 79 20 77 61 79 20 74 6f 0a 2a 2a 20   only way to.** 
2da50 66 69 6e 64 20 6f 75 74 20 69 66 20 53 51 4c 69  find out if SQLi
2da60 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  te automatically
2da70 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 74 68 65   rolled back the
2da80 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 61 66 74   transaction aft
2da90 65 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 69  er.** an error i
2daa0 73 20 74 6f 20 75 73 65 20 74 68 69 73 20 66 75  s to use this fu
2dab0 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 4e  nction..**.** IN
2dac0 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
2dad0 7b 46 31 32 39 33 31 7d 20 54 68 65 20 5b 73 71  {F12931} The [sq
2dae0 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f  lite3_get_autoco
2daf0 6d 6d 69 74 28 44 29 5d 20 69 6e 74 65 72 66 61  mmit(D)] interfa
2db00 63 65 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  ce returns non-z
2db10 65 72 6f 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20  ero or.**       
2db20 20 20 20 7a 65 72 6f 20 69 66 20 74 68 65 20 5b     zero if the [
2db30 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2db40 69 6f 6e 5d 20 44 20 69 73 20 6f 72 20 69 73 20  ion] D is or is 
2db50 6e 6f 74 20 69 6e 20 61 75 74 6f 63 6f 6d 6d 69  not in autocommi
2db60 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 6f  t.**          mo
2db70 64 65 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79  de, respectively
2db80 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 33 32 7d  ..**.** {F12932}
2db90 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65   Autocommit mode
2dba0 20 69 73 20 6f 6e 20 62 79 20 64 65 66 61 75 6c   is on by defaul
2dbb0 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 33 33  t..**.** {F12933
2dbc0 7d 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64  } Autocommit mod
2dbd0 65 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79  e is disabled by
2dbe0 20 61 20 73 75 63 63 65 73 73 66 75 6c 20 5b 42   a successful [B
2dbf0 45 47 49 4e 5d 20 73 74 61 74 65 6d 65 6e 74 2e  EGIN] statement.
2dc00 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 33 34 7d 20  .**.** {F12934} 
2dc10 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20  Autocommit mode 
2dc20 69 73 20 65 6e 61 62 6c 65 64 20 62 79 20 61 20  is enabled by a 
2dc30 73 75 63 63 65 73 73 66 75 6c 20 5b 43 4f 4d 4d  successful [COMM
2dc40 49 54 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41 43 4b  IT] or [ROLLBACK
2dc50 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74  ].**          st
2dc60 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 0a 2a 2a 0a  atement..** .**.
2dc70 2a 2a 20 4c 49 4d 49 54 41 54 49 4f 4e 53 3a 0a  ** LIMITATIONS:.
2dc80 2a 2a 2a 0a 2a 2a 20 7b 55 31 32 39 33 36 7d 20  ***.** {U12936} 
2dc90 49 66 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61  If another threa
2dca0 64 20 63 68 61 6e 67 65 73 20 74 68 65 20 61 75  d changes the au
2dcb0 74 6f 63 6f 6d 6d 69 74 20 73 74 61 74 75 73 20  tocommit status 
2dcc0 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  of the database.
2dcd0 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e 6e  **          conn
2dce0 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 69  ection while thi
2dcf0 73 20 72 6f 75 74 69 6e 65 20 69 73 20 72 75 6e  s routine is run
2dd00 6e 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72  ning, then the r
2dd10 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 20  eturn value.**  
2dd20 20 20 20 20 20 20 20 20 69 73 20 75 6e 64 65 66          is undef
2dd30 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ined..*/.int sql
2dd40 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d  ite3_get_autocom
2dd50 6d 69 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  mit(sqlite3*);..
2dd60 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2dd70 20 46 69 6e 64 20 54 68 65 20 44 61 74 61 62 61   Find The Databa
2dd80 73 65 20 48 61 6e 64 6c 65 20 4f 66 20 41 20 50  se Handle Of A P
2dd90 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
2dda0 74 20 7b 46 31 33 31 32 30 7d 0a 2a 2a 0a 2a 2a  t {F13120}.**.**
2ddb0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f   The sqlite3_db_
2ddc0 68 61 6e 64 6c 65 20 69 6e 74 65 72 66 61 63 65  handle interface
2ddd0 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20  .** returns the 
2dde0 5b 73 71 6c 69 74 65 33 2a 5d 20 64 61 74 61 62  [sqlite3*] datab
2ddf0 61 73 65 20 68 61 6e 64 6c 65 20 74 6f 20 77 68  ase handle to wh
2de00 69 63 68 20 61 0a 2a 2a 20 5b 70 72 65 70 61 72  ich a.** [prepar
2de10 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 62 65  ed statement] be
2de20 6c 6f 6e 67 73 2e 0a 2a 2a 20 54 68 65 20 64 61  longs..** The da
2de30 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 72 65  tabase handle re
2de40 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
2de50 33 5f 64 62 5f 68 61 6e 64 6c 65 0a 2a 2a 20 69  3_db_handle.** i
2de60 73 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  s the same datab
2de70 61 73 65 20 68 61 6e 64 6c 65 20 74 68 61 74 20  ase handle that 
2de80 77 61 73 0a 2a 2a 20 74 68 65 20 66 69 72 73 74  was.** the first
2de90 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
2dea0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2deb0 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76  e_v2()] or its v
2dec0 61 72 69 61 6e 74 73 0a 2a 2a 20 74 68 61 74 20  ariants.** that 
2ded0 77 61 73 20 75 73 65 64 20 74 6f 20 63 72 65 61  was used to crea
2dee0 74 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  te the statement
2def0 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 70 6c   in the first pl
2df00 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ace..**.** INVAR
2df10 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31  IANTS:.**.** {F1
2df20 33 31 32 33 7d 20 54 68 65 20 5b 73 71 6c 69 74  3123} The [sqlit
2df30 65 33 5f 64 62 5f 68 61 6e 64 6c 65 28 53 29 5d  e3_db_handle(S)]
2df40 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2df50 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  ns a pointer.** 
2df60 20 20 20 20 20 20 20 20 20 74 6f 20 74 68 65 20           to the 
2df70 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2df80 74 69 6f 6e 5d 20 61 73 73 6f 63 69 61 74 65 64  tion] associated
2df90 20 77 69 74 68 0a 2a 2a 20 20 20 20 20 20 20 20   with.**        
2dfa0 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74    [prepared stat
2dfb0 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 73 71 6c  ement] S..*/.sql
2dfc0 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 64 62  ite3 *sqlite3_db
2dfd0 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f  _handle(sqlite3_
2dfe0 73 74 6d 74 2a 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20  stmt*);.../*.** 
2dff0 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 6d 69 74  CAPI3REF: Commit
2e000 20 41 6e 64 20 52 6f 6c 6c 62 61 63 6b 20 4e 6f   And Rollback No
2e010 74 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62  tification Callb
2e020 61 63 6b 73 20 7b 46 31 32 39 35 30 7d 0a 2a 2a  acks {F12950}.**
2e030 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
2e040 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 20 69 6e  commit_hook() in
2e050 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72  terface register
2e060 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  s a callback.** 
2e070 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69  function to be i
2e080 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20  nvoked whenever 
2e090 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73  a transaction is
2e0a0 20 63 6f 6d 6d 69 74 74 65 64 2e 0a 2a 2a 20 41   committed..** A
2e0b0 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20  ny callback set 
2e0c0 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61  by a previous ca
2e0d0 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ll to sqlite3_co
2e0e0 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66  mmit_hook().** f
2e0f0 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  or the same data
2e100 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
2e110 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a  is overridden..*
2e120 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 6f  * The sqlite3_ro
2e130 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 20 69 6e  llback_hook() in
2e140 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72  terface register
2e150 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  s a callback.** 
2e160 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69  function to be i
2e170 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20  nvoked whenever 
2e180 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73  a transaction is
2e190 20 63 6f 6d 6d 69 74 74 65 64 2e 0a 2a 2a 20 41   committed..** A
2e1a0 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20  ny callback set 
2e1b0 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61  by a previous ca
2e1c0 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ll to sqlite3_co
2e1d0 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66  mmit_hook().** f
2e1e0 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  or the same data
2e1f0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
2e200 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a  is overridden..*
2e210 2a 20 54 68 65 20 70 41 72 67 20 61 72 67 75 6d  * The pArg argum
2e220 65 6e 74 20 69 73 20 70 61 73 73 65 64 20 74 68  ent is passed th
2e230 72 6f 75 67 68 0a 2a 2a 20 74 6f 20 74 68 65 20  rough.** to the 
2e240 63 61 6c 6c 62 61 63 6b 2e 20 20 49 66 20 74 68  callback.  If th
2e250 65 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 20 61 20  e callback on a 
2e260 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 66 75 6e 63  commit hook func
2e270 74 69 6f 6e 20 0a 2a 2a 20 72 65 74 75 72 6e 73  tion .** returns
2e280 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20   non-zero, then 
2e290 74 68 65 20 63 6f 6d 6d 69 74 20 69 73 20 63 6f  the commit is co
2e2a0 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20 72  nverted into a r
2e2b0 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49  ollback..**.** I
2e2c0 66 20 61 6e 6f 74 68 65 72 20 66 75 6e 63 74 69  f another functi
2e2d0 6f 6e 20 77 61 73 20 70 72 65 76 69 6f 75 73 6c  on was previousl
2e2e0 79 20 72 65 67 69 73 74 65 72 65 64 2c 20 69 74  y registered, it
2e2f0 73 0a 2a 2a 20 70 41 72 67 20 76 61 6c 75 65 20  s.** pArg value 
2e300 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74  is returned.  Ot
2e310 68 65 72 77 69 73 65 20 4e 55 4c 4c 20 69 73 20  herwise NULL is 
2e320 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
2e330 52 65 67 69 73 74 65 72 69 6e 67 20 61 20 4e 55  Registering a NU
2e340 4c 4c 20 66 75 6e 63 74 69 6f 6e 20 64 69 73 61  LL function disa
2e350 62 6c 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63  bles the callbac
2e360 6b 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 74 68 65  k..**.** For the
2e370 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69   purposes of thi
2e380 73 20 41 50 49 2c 20 61 20 74 72 61 6e 73 61 63  s API, a transac
2e390 74 69 6f 6e 20 69 73 20 73 61 69 64 20 74 6f 20  tion is said to 
2e3a0 68 61 76 65 20 62 65 65 6e 20 0a 2a 2a 20 72 6f  have been .** ro
2e3b0 6c 6c 65 64 20 62 61 63 6b 20 69 66 20 61 6e 20  lled back if an 
2e3c0 65 78 70 6c 69 63 69 74 20 22 52 4f 4c 4c 42 41  explicit "ROLLBA
2e3d0 43 4b 22 20 73 74 61 74 65 6d 65 6e 74 20 69 73  CK" statement is
2e3e0 20 65 78 65 63 75 74 65 64 2c 20 6f 72 0a 2a 2a   executed, or.**
2e3f0 20 61 6e 20 65 72 72 6f 72 20 6f 72 20 63 6f 6e   an error or con
2e400 73 74 72 61 69 6e 74 20 63 61 75 73 65 73 20 61  straint causes a
2e410 6e 20 69 6d 70 6c 69 63 69 74 20 72 6f 6c 6c 62  n implicit rollb
2e420 61 63 6b 20 74 6f 20 6f 63 63 75 72 2e 0a 2a 2a  ack to occur..**
2e430 20 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 63 61   The rollback ca
2e440 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e  llback is not in
2e450 76 6f 6b 65 64 20 69 66 20 61 20 74 72 61 6e 73  voked if a trans
2e460 61 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 61 75 74  action is.** aut
2e470 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65  omatically rolle
2e480 64 20 62 61 63 6b 20 62 65 63 61 75 73 65 20 74  d back because t
2e490 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
2e4a0 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64  ection is closed
2e4b0 2e 0a 2a 2a 20 54 68 65 20 72 6f 6c 6c 62 61 63  ..** The rollbac
2e4c0 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f  k callback is no
2e4d0 74 20 69 6e 76 6f 6b 65 64 20 69 66 20 61 20 74  t invoked if a t
2e4e0 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 0a 2a 2a  ransaction is.**
2e4f0 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62 65 63   rolled back bec
2e500 61 75 73 65 20 61 20 63 6f 6d 6d 69 74 20 63 61  ause a commit ca
2e510 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 65 64 20  llback returned 
2e520 6e 6f 6e 2d 7a 65 72 6f 2e 0a 2a 2a 20 3c 74 6f  non-zero..** <to
2e530 64 6f 3e 20 43 68 65 63 6b 20 6f 6e 20 74 68 69  do> Check on thi
2e540 73 20 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20  s </todo>.**.** 
2e550 54 68 65 73 65 20 61 72 65 20 65 78 70 65 72 69  These are experi
2e560 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66 61 63 65  mental interface
2e570 73 20 61 6e 64 20 61 72 65 20 73 75 62 6a 65 63  s and are subjec
2e580 74 20 74 6f 20 63 68 61 6e 67 65 2e 0a 2a 2a 0a  t to change..**.
2e590 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
2e5a0 2a 0a 2a 2a 20 7b 46 31 32 39 35 31 7d 20 54 68  *.** {F12951} Th
2e5b0 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69  e [sqlite3_commi
2e5c0 74 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69  t_hook(D,F,P)] i
2e5d0 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65  nterface registe
2e5e0 72 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  rs the.**       
2e5f0 20 20 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63     callback func
2e600 74 69 6f 6e 20 46 20 74 6f 20 62 65 20 69 6e 76  tion F to be inv
2e610 6f 6b 65 64 20 77 69 74 68 20 61 72 67 75 6d 65  oked with argume
2e620 6e 74 20 50 20 77 68 65 6e 65 76 65 72 0a 2a 2a  nt P whenever.**
2e630 20 20 20 20 20 20 20 20 20 20 61 20 74 72 61 6e            a tran
2e640 73 61 63 74 69 6f 6e 20 63 6f 6d 6d 69 74 73 20  saction commits 
2e650 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  on [database con
2e660 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a  nection] D..**.*
2e670 2a 20 7b 46 31 32 39 35 32 7d 20 54 68 65 20 5b  * {F12952} The [
2e680 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68  sqlite3_commit_h
2e690 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 6e 74 65  ook(D,F,P)] inte
2e6a0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
2e6b0 65 20 50 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  e P.**          
2e6c0 61 72 67 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68  argument from th
2e6d0 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  e previous call 
2e6e0 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 0a 2a  with the same .*
2e6f0 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61 74 61  *          [data
2e700 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
2e710 5d 20 44 20 2c 20 6f 72 20 4e 55 4c 4c 20 6f 6e  ] D , or NULL on
2e720 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 0a   the first call.
2e730 2a 2a 20 20 20 20 20 20 20 20 20 20 66 6f 72 20  **          for 
2e740 61 20 70 61 72 74 69 63 75 6c 61 72 20 5b 64 61  a particular [da
2e750 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2e760 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  n] D..**.** {F12
2e770 39 35 33 7d 20 45 61 63 68 20 63 61 6c 6c 20 74  953} Each call t
2e780 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69  o [sqlite3_commi
2e790 74 5f 68 6f 6f 6b 28 29 5d 20 6f 76 65 72 77 72  t_hook()] overwr
2e7a0 69 74 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63  ites the callbac
2e7b0 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  k.**          re
2e7c0 67 69 73 74 65 72 65 64 20 62 79 20 70 72 69 6f  gistered by prio
2e7d0 72 20 63 61 6c 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b  r calls..**.** {
2e7e0 46 31 32 39 35 34 7d 20 49 66 20 74 68 65 20 46  F12954} If the F
2e7f0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71   argument to [sq
2e800 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f  lite3_commit_hoo
2e810 6b 28 44 2c 46 2c 50 29 5d 20 69 73 20 4e 55 4c  k(D,F,P)] is NUL
2e820 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  L.**          th
2e830 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 68 6f  en the commit ho
2e840 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 63  ok callback is c
2e850 61 6e 63 65 6c 6c 65 64 20 61 6e 64 20 6e 6f 20  ancelled and no 
2e860 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20  callback.**     
2e870 20 20 20 20 20 69 73 20 69 6e 76 6f 6b 65 64 20       is invoked 
2e880 77 68 65 6e 20 61 20 74 72 61 6e 73 61 63 74 69  when a transacti
2e890 6f 6e 20 63 6f 6d 6d 69 74 73 2e 0a 2a 2a 0a 2a  on commits..**.*
2e8a0 2a 20 7b 46 31 32 39 35 35 7d 20 49 66 20 74 68  * {F12955} If th
2e8b0 65 20 63 6f 6d 6d 69 74 20 63 61 6c 6c 62 61 63  e commit callbac
2e8c0 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  k returns non-ze
2e8d0 72 6f 20 74 68 65 6e 20 74 68 65 20 63 6f 6d 6d  ro then the comm
2e8e0 69 74 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20  it is.**        
2e8f0 20 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f    converted into
2e900 20 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a   a rollback..**.
2e910 2a 2a 20 7b 46 31 32 39 36 31 7d 20 54 68 65 20  ** {F12961} The 
2e920 5b 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63  [sqlite3_rollbac
2e930 6b 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69  k_hook(D,F,P)] i
2e940 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65  nterface registe
2e950 72 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  rs the.**       
2e960 20 20 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63     callback func
2e970 74 69 6f 6e 20 46 20 74 6f 20 62 65 20 69 6e 76  tion F to be inv
2e980 6f 6b 65 64 20 77 69 74 68 20 61 72 67 75 6d 65  oked with argume
2e990 6e 74 20 50 20 77 68 65 6e 65 76 65 72 0a 2a 2a  nt P whenever.**
2e9a0 20 20 20 20 20 20 20 20 20 20 61 20 74 72 61 6e            a tran
2e9b0 73 61 63 74 69 6f 6e 20 72 6f 6c 6c 73 20 62 61  saction rolls ba
2e9c0 63 6b 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20  ck on [database 
2e9d0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a  connection] D..*
2e9e0 2a 0a 2a 2a 20 7b 46 31 32 39 36 32 7d 20 54 68  *.** {F12962} Th
2e9f0 65 20 5b 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62  e [sqlite3_rollb
2ea00 61 63 6b 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d  ack_hook(D,F,P)]
2ea10 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2ea20 6e 73 20 74 68 65 20 50 0a 2a 2a 20 20 20 20 20  ns the P.**     
2ea30 20 20 20 20 20 61 72 67 75 6d 65 6e 74 20 66 72       argument fr
2ea40 6f 6d 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  om the previous 
2ea50 63 61 6c 6c 20 77 69 74 68 20 74 68 65 20 73 61  call with the sa
2ea60 6d 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  me .**          
2ea70 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2ea80 74 69 6f 6e 20 5d 20 44 20 2c 20 6f 72 20 4e 55  tion ] D , or NU
2ea90 4c 4c 20 6f 6e 20 74 68 65 20 66 69 72 73 74 20  LL on the first 
2eaa0 63 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20  call.**         
2eab0 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61   for a particula
2eac0 72 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  r [database conn
2ead0 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a  ection] D..**.**
2eae0 20 7b 46 31 32 39 36 33 7d 20 45 61 63 68 20 63   {F12963} Each c
2eaf0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
2eb00 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 5d  rollback_hook()]
2eb10 20 6f 76 65 72 77 72 69 74 65 73 20 74 68 65 20   overwrites the 
2eb20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20  callback.**     
2eb30 20 20 20 20 20 72 65 67 69 73 74 65 72 65 64 20       registered 
2eb40 62 79 20 70 72 69 6f 72 20 63 61 6c 6c 73 2e 0a  by prior calls..
2eb50 2a 2a 0a 2a 2a 20 7b 46 31 32 39 36 34 7d 20 49  **.** {F12964} I
2eb60 66 20 74 68 65 20 46 20 61 72 67 75 6d 65 6e 74  f the F argument
2eb70 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 6f 6c   to [sqlite3_rol
2eb80 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c 46 2c 50  lback_hook(D,F,P
2eb90 29 5d 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20 20 20  )] is NULL.**   
2eba0 20 20 20 20 20 20 20 74 68 65 6e 20 74 68 65 20         then the 
2ebb0 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 63 61  rollback hook ca
2ebc0 6c 6c 62 61 63 6b 20 69 73 20 63 61 6e 63 65 6c  llback is cancel
2ebd0 6c 65 64 20 61 6e 64 20 6e 6f 20 63 61 6c 6c 62  led and no callb
2ebe0 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ack.**          
2ebf0 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20  is invoked when 
2ec00 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 72 6f  a transaction ro
2ec10 6c 6c 73 20 62 61 63 6b 2e 0a 2a 2f 0a 76 6f 69  lls back..*/.voi
2ec20 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69  d *sqlite3_commi
2ec30 74 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c  t_hook(sqlite3*,
2ec40 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20   int(*)(void*), 
2ec50 76 6f 69 64 2a 29 3b 0a 76 6f 69 64 20 2a 73 71  void*);.void *sq
2ec60 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68  lite3_rollback_h
2ec70 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f  ook(sqlite3*, vo
2ec80 69 64 28 2a 29 28 76 6f 69 64 20 2a 29 2c 20 76  id(*)(void *), v
2ec90 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
2eca0 50 49 33 52 45 46 3a 20 44 61 74 61 20 43 68 61  PI3REF: Data Cha
2ecb0 6e 67 65 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e  nge Notification
2ecc0 20 43 61 6c 6c 62 61 63 6b 73 20 7b 46 31 32 39   Callbacks {F129
2ecd0 37 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  70}.**.** The sq
2ece0 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f  lite3_update_hoo
2ecf0 6b 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  k() interface.**
2ed00 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c   registers a cal
2ed10 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77  lback function w
2ed20 69 74 68 20 74 68 65 20 64 61 74 61 62 61 73 65  ith the database
2ed30 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 64 65 6e   connection iden
2ed40 74 69 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a  tified by the .*
2ed50 2a 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  * first argument
2ed60 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77   to be invoked w
2ed70 68 65 6e 65 76 65 72 20 61 20 72 6f 77 20 69 73  henever a row is
2ed80 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72 74   updated, insert
2ed90 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a  ed or deleted..*
2eda0 2a 20 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73  * Any callback s
2edb0 65 74 20 62 79 20 61 20 70 72 65 76 69 6f 75 73  et by a previous
2edc0 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 66 75   call to this fu
2edd0 6e 63 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 73  nction for the s
2ede0 61 6d 65 20 0a 2a 2a 20 64 61 74 61 62 61 73 65  ame .** database
2edf0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f   connection is o
2ee00 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 0a 2a 2a  verridden..**.**
2ee10 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
2ee20 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
2ee30 72 20 74 6f 20 74 68 65 20 66 75 6e 63 74 69 6f  r to the functio
2ee40 6e 20 74 6f 20 69 6e 76 6f 6b 65 20 77 68 65 6e  n to invoke when
2ee50 20 61 20 0a 2a 2a 20 72 6f 77 20 69 73 20 75 70   a .** row is up
2ee60 64 61 74 65 64 2c 20 69 6e 73 65 72 74 65 64 20  dated, inserted 
2ee70 6f 72 20 64 65 6c 65 74 65 64 2e 20 0a 2a 2a 20  or deleted. .** 
2ee80 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
2ee90 6e 74 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  nt to the callba
2eea0 63 6b 20 69 73 0a 2a 2a 20 61 20 63 6f 70 79 20  ck is.** a copy 
2eeb0 6f 66 20 74 68 65 20 74 68 69 72 64 20 61 72 67  of the third arg
2eec0 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
2eed0 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 2e 0a  _update_hook()..
2eee0 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 63 61  ** The second ca
2eef0 6c 6c 62 61 63 6b 20 0a 2a 2a 20 61 72 67 75 6d  llback .** argum
2ef00 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53  ent is one of [S
2ef10 51 4c 49 54 45 5f 49 4e 53 45 52 54 5d 2c 20 5b  QLITE_INSERT], [
2ef20 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 6f  SQLITE_DELETE] o
2ef30 72 20 5b 53 51 4c 49 54 45 5f 55 50 44 41 54 45  r [SQLITE_UPDATE
2ef40 5d 2c 0a 2a 2a 20 64 65 70 65 6e 64 69 6e 67 20  ],.** depending 
2ef50 6f 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  on the operation
2ef60 20 74 68 61 74 20 63 61 75 73 65 64 20 74 68 65   that caused the
2ef70 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 62 65 20   callback to be 
2ef80 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 54 68 65 20  invoked..** The 
2ef90 74 68 69 72 64 20 61 6e 64 20 0a 2a 2a 20 66 6f  third and .** fo
2efa0 75 72 74 68 20 61 72 67 75 6d 65 6e 74 73 20 74  urth arguments t
2efb0 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 63  o the callback c
2efc0 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65 72 73 20  ontain pointers 
2efd0 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20  to the database 
2efe0 61 6e 64 20 0a 2a 2a 20 74 61 62 6c 65 20 6e 61  and .** table na
2eff0 6d 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  me containing th
2f000 65 20 61 66 66 65 63 74 65 64 20 72 6f 77 2e 0a  e affected row..
2f010 2a 2a 20 54 68 65 20 66 69 6e 61 6c 20 63 61 6c  ** The final cal
2f020 6c 62 61 63 6b 20 70 61 72 61 6d 65 74 65 72 20  lback parameter 
2f030 69 73 20 0a 2a 2a 20 74 68 65 20 72 6f 77 69 64  is .** the rowid
2f040 20 6f 66 20 74 68 65 20 72 6f 77 2e 0a 2a 2a 20   of the row..** 
2f050 49 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20 61  In the case of a
2f060 6e 20 75 70 64 61 74 65 2c 20 74 68 69 73 20 69  n update, this i
2f070 73 20 74 68 65 20 72 6f 77 69 64 20 61 66 74 65  s the rowid afte
2f080 72 20 0a 2a 2a 20 74 68 65 20 75 70 64 61 74 65  r .** the update
2f090 20 74 61 6b 65 73 20 70 6c 61 63 65 2e 0a 2a 2a   takes place..**
2f0a0 0a 2a 2a 20 54 68 65 20 75 70 64 61 74 65 20 68  .** The update h
2f0b0 6f 6f 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b  ook is not invok
2f0c0 65 64 20 77 68 65 6e 20 69 6e 74 65 72 6e 61 6c  ed when internal
2f0d0 20 73 79 73 74 65 6d 20 74 61 62 6c 65 73 20 61   system tables a
2f0e0 72 65 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 20 28  re.** modified (
2f0f0 69 2e 65 2e 20 73 71 6c 69 74 65 5f 6d 61 73 74  i.e. sqlite_mast
2f100 65 72 20 61 6e 64 20 73 71 6c 69 74 65 5f 73 65  er and sqlite_se
2f110 71 75 65 6e 63 65 29 2e 0a 2a 2a 0a 2a 2a 20 49  quence)..**.** I
2f120 66 20 61 6e 6f 74 68 65 72 20 66 75 6e 63 74 69  f another functi
2f130 6f 6e 20 77 61 73 20 70 72 65 76 69 6f 75 73 6c  on was previousl
2f140 79 20 72 65 67 69 73 74 65 72 65 64 2c 20 69 74  y registered, it
2f150 73 20 70 41 72 67 20 76 61 6c 75 65 0a 2a 2a 20  s pArg value.** 
2f160 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74  is returned.  Ot
2f170 68 65 72 77 69 73 65 20 4e 55 4c 4c 20 69 73 20  herwise NULL is 
2f180 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
2f190 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
2f1a0 2a 20 7b 46 31 32 39 37 31 7d 20 54 68 65 20 5b  * {F12971} The [
2f1b0 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68  sqlite3_update_h
2f1c0 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 6e 74 65  ook(D,F,P)] inte
2f1d0 72 66 61 63 65 20 63 61 75 73 65 73 20 63 61 6c  rface causes cal
2f1e0 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20  lback.**        
2f1f0 20 20 66 75 6e 63 74 69 6f 6e 20 46 20 74 6f 20    function F to 
2f200 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  be invoked with 
2f210 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
2f220 50 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 20 20  P whenever.**   
2f230 20 20 20 20 20 20 20 61 20 74 61 62 6c 65 20 72         a table r
2f240 6f 77 20 69 73 20 6d 6f 64 69 66 69 65 64 2c 20  ow is modified, 
2f250 69 6e 73 65 72 74 65 64 2c 20 6f 72 20 64 65 6c  inserted, or del
2f260 65 74 65 64 20 6f 6e 0a 2a 2a 20 20 20 20 20 20  eted on.**      
2f270 20 20 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f      [database co
2f280 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a  nnection] D..**.
2f290 2a 2a 20 7b 46 31 32 39 37 33 7d 20 54 68 65 20  ** {F12973} The 
2f2a0 5b 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f  [sqlite3_update_
2f2b0 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 6e 74  hook(D,F,P)] int
2f2c0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
2f2d0 68 65 20 76 61 6c 75 65 0a 2a 2a 20 20 20 20 20  he value.**     
2f2e0 20 20 20 20 20 6f 66 20 50 20 66 6f 72 20 74 68       of P for th
2f2f0 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  e previous call 
2f300 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74  on the same [dat
2f310 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2f320 5d 20 44 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ] D,.**         
2f330 20 6f 72 20 4e 55 4c 4c 20 66 6f 72 20 74 68 65   or NULL for the
2f340 20 66 69 72 73 74 20 63 61 6c 6c 2e 0a 2a 2a 0a   first call..**.
2f350 2a 2a 20 7b 46 31 32 39 37 35 7d 20 49 66 20 74  ** {F12975} If t
2f360 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 20 63  he update hook c
2f370 61 6c 6c 62 61 63 6b 20 46 20 69 6e 20 5b 73 71  allback F in [sq
2f380 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f  lite3_update_hoo
2f390 6b 28 44 2c 46 2c 50 29 5d 0a 2a 2a 20 20 20 20  k(D,F,P)].**    
2f3a0 20 20 20 20 20 20 69 73 20 4e 55 4c 4c 20 74 68        is NULL th
2f3b0 65 6e 20 74 68 65 20 6e 6f 20 75 70 64 61 74 65  en the no update
2f3c0 20 63 61 6c 6c 62 61 63 6b 73 20 61 72 65 20 6d   callbacks are m
2f3d0 61 64 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39  ade..**.** {F129
2f3e0 37 37 7d 20 45 61 63 68 20 63 61 6c 6c 20 74 6f  77} Each call to
2f3f0 20 5b 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65   [sqlite3_update
2f400 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 6f 76  _hook(D,F,P)] ov
2f410 65 72 72 69 64 65 73 20 70 72 69 6f 72 20 63 61  errides prior ca
2f420 6c 6c 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  lls.**          
2f430 74 6f 20 74 68 65 20 73 61 6d 65 20 69 6e 74 65  to the same inte
2f440 72 66 61 63 65 20 6f 6e 20 74 68 65 20 73 61 6d  rface on the sam
2f450 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
2f460 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a  ection] D..**.**
2f470 20 7b 46 31 32 39 37 39 7d 20 54 68 65 20 75 70   {F12979} The up
2f480 64 61 74 65 20 68 6f 6f 6b 20 63 61 6c 6c 62 61  date hook callba
2f490 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65  ck is not invoke
2f4a0 64 20 77 68 65 6e 20 69 6e 74 65 72 6e 61 6c 20  d when internal 
2f4b0 73 79 73 74 65 6d 0a 2a 2a 20 20 20 20 20 20 20  system.**       
2f4c0 20 20 20 74 61 62 6c 65 73 20 73 75 63 68 20 61     tables such a
2f4d0 73 20 73 71 6c 69 74 65 5f 6d 61 73 74 65 72 20  s sqlite_master 
2f4e0 61 6e 64 20 73 71 6c 69 74 65 5f 73 65 71 75 65  and sqlite_seque
2f4f0 6e 63 65 20 61 72 65 20 6d 6f 64 69 66 69 65 64  nce are modified
2f500 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 38 31 7d  ..**.** {F12981}
2f510 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
2f520 6d 65 74 65 72 20 74 6f 20 74 68 65 20 75 70 64  meter to the upd
2f530 61 74 65 20 63 61 6c 6c 62 61 63 6b 20 0a 2a 2a  ate callback .**
2f540 20 20 20 20 20 20 20 20 20 20 69 73 20 6f 6e 65            is one
2f550 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 53 45   of [SQLITE_INSE
2f560 52 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 44 45 4c  RT], [SQLITE_DEL
2f570 45 54 45 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ETE] or [SQLITE_
2f580 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 20 20 20 20  UPDATE],.**     
2f590 20 20 20 20 20 64 65 70 65 6e 64 69 6e 67 20 6f       depending o
2f5a0 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20  n the operation 
2f5b0 74 68 61 74 20 63 61 75 73 65 64 20 74 68 65 20  that caused the 
2f5c0 63 61 6c 6c 62 61 63 6b 20 74 6f 20 62 65 20 69  callback to be i
2f5d0 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46  nvoked..**.** {F
2f5e0 31 32 39 38 33 7d 20 54 68 65 20 74 68 69 72 64  12983} The third
2f5f0 20 61 6e 64 20 66 6f 75 72 74 68 20 61 72 67 75   and fourth argu
2f600 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 63 61 6c  ments to the cal
2f610 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 20 70 6f  lback contain po
2f620 69 6e 74 65 72 73 0a 2a 2a 20 20 20 20 20 20 20  inters.**       
2f630 20 20 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69     to zero-termi
2f640 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69  nated UTF-8 stri
2f650 6e 67 73 20 77 68 69 63 68 20 61 72 65 20 74 68  ngs which are th
2f660 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a  e names of the.*
2f670 2a 20 20 20 20 20 20 20 20 20 20 64 61 74 61 62  *          datab
2f680 61 73 65 20 61 6e 64 20 74 61 62 6c 65 20 74 68  ase and table th
2f690 61 74 20 69 73 20 62 65 69 6e 67 20 75 70 64 61  at is being upda
2f6a0 74 65 64 2e 0a 0a 2a 2a 20 7b 46 31 32 39 38 35  ted...** {F12985
2f6b0 7d 20 54 68 65 20 66 69 6e 61 6c 20 63 61 6c 6c  } The final call
2f6c0 62 61 63 6b 20 70 61 72 61 6d 65 74 65 72 20 69  back parameter i
2f6d0 73 20 74 68 65 20 72 6f 77 69 64 20 6f 66 20 74  s the rowid of t
2f6e0 68 65 20 72 6f 77 20 61 66 74 65 72 0a 2a 2a 20  he row after.** 
2f6f0 20 20 20 20 20 20 20 20 20 74 68 65 20 63 68 61           the cha
2f700 6e 67 65 20 6f 63 63 75 72 73 2e 0a 2a 2f 0a 76  nge occurs..*/.v
2f710 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 70 64  oid *sqlite3_upd
2f720 61 74 65 5f 68 6f 6f 6b 28 0a 20 20 73 71 6c 69  ate_hook(.  sqli
2f730 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29  te3*, .  void(*)
2f740 28 76 6f 69 64 20 2a 2c 69 6e 74 20 2c 63 68 61  (void *,int ,cha
2f750 72 20 63 6f 6e 73 74 20 2a 2c 63 68 61 72 20 63  r const *,char c
2f760 6f 6e 73 74 20 2a 2c 73 71 6c 69 74 65 33 5f 69  onst *,sqlite3_i
2f770 6e 74 36 34 29 2c 0a 20 20 76 6f 69 64 2a 0a 29  nt64),.  void*.)
2f780 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2f790 46 3a 20 20 45 6e 61 62 6c 65 20 4f 72 20 44 69  F:  Enable Or Di
2f7a0 73 61 62 6c 65 20 53 68 61 72 65 64 20 50 61 67  sable Shared Pag
2f7b0 65 72 20 43 61 63 68 65 20 7b 46 31 30 33 33 30  er Cache {F10330
2f7c0 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  }.**.** This rou
2f7d0 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20  tine enables or 
2f7e0 64 69 73 61 62 6c 65 73 20 74 68 65 20 73 68 61  disables the sha
2f7f0 72 69 6e 67 20 6f 66 20 74 68 65 20 64 61 74 61  ring of the data
2f800 62 61 73 65 20 63 61 63 68 65 0a 2a 2a 20 61 6e  base cache.** an
2f810 64 20 73 63 68 65 6d 61 20 64 61 74 61 20 73 74  d schema data st
2f820 72 75 63 74 75 72 65 73 20 62 65 74 77 65 65 6e  ructures between
2f830 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 74 6f 20   connections to 
2f840 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
2f850 65 2e 0a 2a 2a 20 53 68 61 72 69 6e 67 20 69 73  e..** Sharing is
2f860 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20   enabled if the 
2f870 61 72 67 75 6d 65 6e 74 20 69 73 20 74 72 75 65  argument is true
2f880 20 61 6e 64 20 64 69 73 61 62 6c 65 64 20 69 66   and disabled if
2f890 20 74 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a   the argument.**
2f8a0 20 69 73 20 66 61 6c 73 65 2e 0a 2a 2a 0a 2a 2a   is false..**.**
2f8b0 20 43 61 63 68 65 20 73 68 61 72 69 6e 67 20 69   Cache sharing i
2f8c0 73 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 64 69  s enabled and di
2f8d0 73 61 62 6c 65 64 0a 2a 2a 20 66 6f 72 20 61 6e  sabled.** for an
2f8e0 20 65 6e 74 69 72 65 20 70 72 6f 63 65 73 73 2e   entire process.
2f8f0 20 7b 45 4e 44 7d 20 54 68 69 73 20 69 73 20 61   {END} This is a
2f900 20 63 68 61 6e 67 65 20 61 73 20 6f 66 20 53 51   change as of SQ
2f910 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35  Lite version 3.5
2f920 2e 30 2e 0a 2a 2a 20 49 6e 20 70 72 69 6f 72 20  .0..** In prior 
2f930 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
2f940 74 65 2c 20 73 68 61 72 69 6e 67 20 77 61 73 0a  te, sharing was.
2f950 2a 2a 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69  ** enabled or di
2f960 73 61 62 6c 65 64 20 66 6f 72 20 65 61 63 68 20  sabled for each 
2f970 74 68 72 65 61 64 20 73 65 70 61 72 61 74 65 6c  thread separatel
2f980 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 63  y..**.** The cac
2f990 68 65 20 73 68 61 72 69 6e 67 20 6d 6f 64 65 20  he sharing mode 
2f9a0 73 65 74 20 62 79 20 74 68 69 73 20 69 6e 74 65  set by this inte
2f9b0 72 66 61 63 65 20 65 66 66 65 63 74 73 20 61 6c  rface effects al
2f9c0 6c 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20  l subsequent.** 
2f9d0 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
2f9e0 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
2f9f0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20  te3_open_v2()], 
2fa00 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  and [sqlite3_ope
2fa10 6e 31 36 28 29 5d 2e 0a 2a 2a 20 45 78 69 73 74  n16()]..** Exist
2fa20 69 6e 67 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ing database con
2fa30 6e 65 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75  nections continu
2fa40 65 20 75 73 65 20 74 68 65 20 73 68 61 72 69 6e  e use the sharin
2fa50 67 20 6d 6f 64 65 0a 2a 2a 20 74 68 61 74 20 77  g mode.** that w
2fa60 61 73 20 69 6e 20 65 66 66 65 63 74 20 61 74 20  as in effect at 
2fa70 74 68 65 20 74 69 6d 65 20 74 68 65 79 20 77 65  the time they we
2fa80 72 65 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a  re opened..**.**
2fa90 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20   Virtual tables 
2faa0 63 61 6e 6e 6f 74 20 62 65 20 75 73 65 64 20 77  cannot be used w
2fab0 69 74 68 20 61 20 73 68 61 72 65 64 20 63 61 63  ith a shared cac
2fac0 68 65 2e 20 20 20 57 68 65 6e 20 73 68 61 72 65  he.   When share
2fad0 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e  d.** cache is en
2fae0 61 62 6c 65 64 2c 20 74 68 65 20 5b 73 71 6c 69  abled, the [sqli
2faf0 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c  te3_create_modul
2fb00 65 28 29 5d 20 41 50 49 20 75 73 65 64 20 74 6f  e()] API used to
2fb10 20 72 65 67 69 73 74 65 72 0a 2a 2a 20 76 69 72   register.** vir
2fb20 74 75 61 6c 20 74 61 62 6c 65 73 20 77 69 6c 6c  tual tables will
2fb30 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20 61   always return a
2fb40 6e 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54  n error..**.** T
2fb50 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75  his routine retu
2fb60 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  rns [SQLITE_OK] 
2fb70 69 66 20 73 68 61 72 65 64 20 63 61 63 68 65 20  if shared cache 
2fb80 77 61 73 0a 2a 2a 20 65 6e 61 62 6c 65 64 20 6f  was.** enabled o
2fb90 72 20 64 69 73 61 62 6c 65 64 20 73 75 63 63 65  r disabled succe
2fba0 73 73 66 75 6c 6c 79 2e 20 20 41 6e 20 5b 65 72  ssfully.  An [er
2fbb0 72 6f 72 20 63 6f 64 65 5d 0a 2a 2a 20 69 73 20  ror code].** is 
2fbc0 72 65 74 75 72 6e 65 64 20 6f 74 68 65 72 77 69  returned otherwi
2fbd0 73 65 2e 0a 2a 2a 0a 2a 2a 20 53 68 61 72 65 64  se..**.** Shared
2fbe0 20 63 61 63 68 65 20 69 73 20 64 69 73 61 62 6c   cache is disabl
2fbf0 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 20 42  ed by default. B
2fc00 75 74 20 74 68 69 73 20 6d 69 67 68 74 20 63 68  ut this might ch
2fc10 61 6e 67 65 20 69 6e 0a 2a 2a 20 66 75 74 75 72  ange in.** futur
2fc20 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
2fc30 4c 69 74 65 2e 20 20 41 70 70 6c 69 63 61 74 69  Lite.  Applicati
2fc40 6f 6e 73 20 74 68 61 74 20 63 61 72 65 20 61 62  ons that care ab
2fc50 6f 75 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61  out shared.** ca
2fc60 63 68 65 20 73 65 74 74 69 6e 67 20 73 68 6f 75  che setting shou
2fc70 6c 64 20 73 65 74 20 69 74 20 65 78 70 6c 69 63  ld set it explic
2fc80 69 74 6c 79 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  itly..**.** INVA
2fc90 52 49 41 4e 54 53 3a 0a 2a 2a 20 0a 2a 2a 20 7b  RIANTS:.** .** {
2fca0 46 31 30 33 33 31 7d 20 41 20 73 75 63 63 65 73  F10331} A succes
2fcb0 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20  sful invocation 
2fcc0 6f 66 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62  of [sqlite3_enab
2fcd0 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28  le_shared_cache(
2fce0 42 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  B)].**          
2fcf0 77 69 6c 6c 20 65 6e 61 62 6c 65 20 6f 72 20 64  will enable or d
2fd00 69 73 61 62 6c 65 20 73 68 61 72 65 64 20 63 61  isable shared ca
2fd10 63 68 65 20 6d 6f 64 65 20 66 6f 72 20 61 6e 79  che mode for any
2fd20 20 73 75 62 73 65 71 75 65 6e 74 6c 79 0a 2a 2a   subsequently.**
2fd30 20 20 20 20 20 20 20 20 20 20 63 72 65 61 74 65            create
2fd40 64 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  d [database conn
2fd50 65 63 74 69 6f 6e 5d 20 69 6e 20 74 68 65 20 73  ection] in the s
2fd60 61 6d 65 20 70 72 6f 63 65 73 73 2e 0a 2a 2a 0a  ame process..**.
2fd70 2a 2a 20 7b 46 31 30 33 33 36 7d 20 57 68 65 6e  ** {F10336} When
2fd80 20 73 68 61 72 65 64 20 63 61 63 68 65 20 69 73   shared cache is
2fd90 20 65 6e 61 62 6c 65 64 2c 20 74 68 65 20 5b 73   enabled, the [s
2fda0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f  qlite3_create_mo
2fdb0 64 75 6c 65 28 29 5d 0a 2a 2a 20 20 20 20 20 20  dule()].**      
2fdc0 20 20 20 20 69 6e 74 65 72 66 61 63 65 20 77 69      interface wi
2fdd0 6c 6c 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  ll always return
2fde0 20 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a   an error..**.**
2fdf0 20 7b 46 31 30 33 33 37 7d 20 54 68 65 20 5b 73   {F10337} The [s
2fe00 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68  qlite3_enable_sh
2fe10 61 72 65 64 5f 63 61 63 68 65 28 42 29 5d 20 69  ared_cache(B)] i
2fe20 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2fe30 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51  .**          [SQ
2fe40 4c 49 54 45 5f 4f 4b 5d 20 69 66 20 73 68 61 72  LITE_OK] if shar
2fe50 65 64 20 63 61 63 68 65 20 77 61 73 20 65 6e 61  ed cache was ena
2fe60 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64  bled or disabled
2fe70 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 0a 2a   successfully..*
2fe80 2a 0a 2a 2a 20 7b 46 31 30 33 33 39 7d 20 53 68  *.** {F10339} Sh
2fe90 61 72 65 64 20 63 61 63 68 65 20 69 73 20 64 69  ared cache is di
2fea0 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  sabled by defaul
2feb0 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  t..*/.int sqlite
2fec0 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f  3_enable_shared_
2fed0 63 61 63 68 65 28 69 6e 74 29 3b 0a 0a 2f 2a 0a  cache(int);../*.
2fee0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 41 74  ** CAPI3REF:  At
2fef0 74 65 6d 70 74 20 54 6f 20 46 72 65 65 20 48 65  tempt To Free He
2ff00 61 70 20 4d 65 6d 6f 72 79 20 7b 46 31 37 33 34  ap Memory {F1734
2ff10 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  0}.**.** The sql
2ff20 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d  ite3_release_mem
2ff30 6f 72 79 28 29 20 69 6e 74 65 72 66 61 63 65 20  ory() interface 
2ff40 61 74 74 65 6d 70 74 73 20 74 6f 0a 2a 2a 20 66  attempts to.** f
2ff50 72 65 65 20 4e 20 62 79 74 65 73 20 6f 66 20 68  ree N bytes of h
2ff60 65 61 70 20 6d 65 6d 6f 72 79 20 62 79 20 64 65  eap memory by de
2ff70 61 6c 6c 6f 63 61 74 69 6e 67 20 6e 6f 6e 2d 65  allocating non-e
2ff80 73 73 65 6e 74 69 61 6c 20 6d 65 6d 6f 72 79 0a  ssential memory.
2ff90 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 68  ** allocations h
2ffa0 65 6c 64 20 62 79 20 74 68 65 20 64 61 74 61 62  eld by the datab
2ffb0 61 73 65 20 6c 61 62 72 61 72 79 2e 20 7b 45 4e  ase labrary. {EN
2ffc0 44 7d 20 20 4d 65 6d 6f 72 79 20 75 73 65 64 0a  D}  Memory used.
2ffd0 2a 2a 20 74 6f 20 63 61 63 68 65 20 64 61 74 61  ** to cache data
2ffe0 62 61 73 65 20 70 61 67 65 73 20 74 6f 20 69 6d  base pages to im
2fff0 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e 63  prove performanc
30000 65 20 69 73 20 61 6e 20 65 78 61 6d 70 6c 65 20  e is an example 
30010 6f 66 0a 2a 2a 20 6e 6f 6e 2d 65 73 73 65 6e 74  of.** non-essent
30020 69 61 6c 20 6d 65 6d 6f 72 79 2e 20 20 53 71 6c  ial memory.  Sql
30030 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d  ite3_release_mem
30040 6f 72 79 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a  ory() returns.**
30050 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
30060 79 74 65 73 20 61 63 74 75 61 6c 6c 79 20 66 72  ytes actually fr
30070 65 65 64 2c 20 77 68 69 63 68 20 6d 69 67 68 74  eed, which might
30080 20 62 65 20 6d 6f 72 65 20 6f 72 20 6c 65 73 73   be more or less
30090 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20 61 6d 6f  .** than the amo
300a0 75 6e 74 20 72 65 71 75 65 73 74 65 64 2e 0a 2a  unt requested..*
300b0 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
300c0 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 34 31 7d 20  .**.** {F17341} 
300d0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c  The [sqlite3_rel
300e0 65 61 73 65 5f 6d 65 6d 6f 72 79 28 4e 29 5d 20  ease_memory(N)] 
300f0 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70  interface attemp
30100 74 73 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20  ts to.**        
30110 20 20 66 72 65 65 20 4e 20 62 79 74 65 73 20 6f    free N bytes o
30120 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 62 79  f heap memory by
30130 20 64 65 61 6c 6c 6f 63 61 74 69 6e 67 20 6e 6f   deallocating no
30140 6e 2d 65 73 73 65 6e 74 69 61 6c 0a 2a 2a 20 20  n-essential.**  
30150 20 20 20 20 20 20 20 20 6d 65 6d 6f 72 79 20 61          memory a
30160 6c 6c 6f 63 61 74 69 6f 6e 73 20 68 65 6c 64 20  llocations held 
30170 62 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20  by the database 
30180 6c 61 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 7b  labrary..**.** {
30190 46 31 36 33 34 32 7d 20 54 68 65 20 5b 73 71 6c  F16342} The [sql
301a0 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d  ite3_release_mem
301b0 6f 72 79 28 4e 29 5d 20 72 65 74 75 72 6e 73 20  ory(N)] returns 
301c0 74 68 65 20 6e 75 6d 62 65 72 0a 2a 2a 20 20 20  the number.**   
301d0 20 20 20 20 20 20 20 6f 66 20 62 79 74 65 73 20         of bytes 
301e0 61 63 74 75 61 6c 6c 79 20 66 72 65 65 64 2c 20  actually freed, 
301f0 77 68 69 63 68 20 6d 69 67 68 74 20 62 65 20 6d  which might be m
30200 6f 72 65 20 6f 72 20 6c 65 73 73 0a 2a 2a 20 20  ore or less.**  
30210 20 20 20 20 20 20 20 20 74 68 61 6e 20 74 68 65          than the
30220 20 61 6d 6f 75 6e 74 20 72 65 71 75 65 73 74 65   amount requeste
30230 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  d..*/.int sqlite
30240 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79  3_release_memory
30250 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  (int);../*.** CA
30260 50 49 33 52 45 46 3a 20 20 49 6d 70 6f 73 65 20  PI3REF:  Impose 
30270 41 20 4c 69 6d 69 74 20 4f 6e 20 48 65 61 70 20  A Limit On Heap 
30280 53 69 7a 65 20 7b 46 31 37 33 35 30 7d 0a 2a 2a  Size {F17350}.**
30290 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
302a0 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28  soft_heap_limit(
302b0 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 70  ) interface.** p
302c0 6c 61 63 65 73 20 61 20 22 73 6f 66 74 22 20 6c  laces a "soft" l
302d0 69 6d 69 74 20 6f 6e 20 74 68 65 20 61 6d 6f 75  imit on the amou
302e0 6e 74 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72  nt of heap memor
302f0 79 20 74 68 61 74 20 6d 61 79 20 62 65 20 61 6c  y that may be al
30300 6c 6f 63 61 74 65 64 0a 2a 2a 20 62 79 20 53 51  located.** by SQ
30310 4c 69 74 65 2e 20 49 66 20 61 6e 20 69 6e 74 65  Lite. If an inte
30320 72 6e 61 6c 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  rnal allocation 
30330 69 73 20 72 65 71 75 65 73 74 65 64 20 0a 2a 2a  is requested .**
30340 20 74 68 61 74 20 77 6f 75 6c 64 20 65 78 63 65   that would exce
30350 65 64 20 74 68 65 20 73 6f 66 74 20 68 65 61 70  ed the soft heap
30360 20 6c 69 6d 69 74 2c 20 5b 73 71 6c 69 74 65 33   limit, [sqlite3
30370 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28  _release_memory(
30380 29 5d 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64  )] is.** invoked
30390 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d   one or more tim
303a0 65 73 20 74 6f 20 66 72 65 65 20 75 70 20 73 6f  es to free up so
303b0 6d 65 20 73 70 61 63 65 20 62 65 66 6f 72 65 20  me space before 
303c0 74 68 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  the allocation.*
303d0 2a 20 69 73 20 6d 61 64 65 2e 0a 2a 2a 0a 2a 2a  * is made..**.**
303e0 20 54 68 65 20 6c 69 6d 69 74 20 69 73 20 63 61   The limit is ca
303f0 6c 6c 65 64 20 22 73 6f 66 74 22 2c 20 62 65 63  lled "soft", bec
30400 61 75 73 65 20 69 66 0a 2a 2a 20 5b 73 71 6c 69  ause if.** [sqli
30410 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f  te3_release_memo
30420 72 79 28 29 5d 20 63 61 6e 6e 6f 74 0a 2a 2a 20  ry()] cannot.** 
30430 66 72 65 65 20 73 75 66 66 69 63 69 65 6e 74 20  free sufficient 
30440 6d 65 6d 6f 72 79 20 74 6f 20 70 72 65 76 65 6e  memory to preven
30450 74 20 74 68 65 20 6c 69 6d 69 74 20 66 72 6f 6d  t the limit from
30460 20 62 65 69 6e 67 20 65 78 63 65 65 64 65 64 2c   being exceeded,
30470 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 69  .** the memory i
30480 73 20 61 6c 6c 6f 63 61 74 65 64 20 61 6e 79 77  s allocated anyw
30490 61 79 20 61 6e 64 20 74 68 65 20 63 75 72 72 65  ay and the curre
304a0 6e 74 20 6f 70 65 72 61 74 69 6f 6e 20 70 72 6f  nt operation pro
304b0 63 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 6e  ceeds..**.** A n
304c0 65 67 61 74 69 76 65 20 6f 72 20 7a 65 72 6f 20  egative or zero 
304d0 76 61 6c 75 65 20 66 6f 72 20 4e 20 6d 65 61 6e  value for N mean
304e0 73 20 74 68 61 74 20 74 68 65 72 65 20 69 73 20  s that there is 
304f0 6e 6f 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d  no soft heap lim
30500 69 74 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  it and.** [sqlit
30510 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72  e3_release_memor
30520 79 28 29 5d 20 77 69 6c 6c 20 6f 6e 6c 79 20 62  y()] will only b
30530 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 6d 65  e called when me
30540 6d 6f 72 79 20 69 73 20 65 78 68 61 75 73 74 65  mory is exhauste
30550 64 2e 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c  d..** The defaul
30560 74 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20  t value for the 
30570 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20  soft heap limit 
30580 69 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53  is zero..**.** S
30590 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 62 65  QLite makes a be
305a0 73 74 20 65 66 66 6f 72 74 20 74 6f 20 68 6f 6e  st effort to hon
305b0 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65 61 70  or the soft heap
305c0 20 6c 69 6d 69 74 2e 20 20 0a 2a 2a 20 42 75 74   limit.  .** But
305d0 20 69 66 20 74 68 65 20 73 6f 66 74 20 68 65 61   if the soft hea
305e0 70 20 6c 69 6d 69 74 20 63 61 6e 6e 6f 74 20 68  p limit cannot h
305f0 6f 6e 6f 72 65 64 2c 20 65 78 65 63 75 74 69 6f  onored, executio
30600 6e 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 69 6e  n will.** contin
30610 75 65 20 77 69 74 68 6f 75 74 20 65 72 72 6f 72  ue without error
30620 20 6f 72 20 6e 6f 74 69 66 69 63 61 74 69 6f 6e   or notification
30630 2e 20 20 54 68 69 73 20 69 73 20 77 68 79 20 74  .  This is why t
30640 68 65 20 6c 69 6d 69 74 20 69 73 20 0a 2a 2a 20  he limit is .** 
30650 63 61 6c 6c 65 64 20 61 20 22 73 6f 66 74 22 20  called a "soft" 
30660 6c 69 6d 69 74 2e 20 20 49 74 20 69 73 20 61 64  limit.  It is ad
30670 76 69 73 6f 72 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a  visory only..**.
30680 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53 51 4c 69  ** Prior to SQLi
30690 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30  te version 3.5.0
306a0 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 6f  , this routine o
306b0 6e 6c 79 20 63 6f 6e 73 74 72 61 69 6e 65 64 20  nly constrained 
306c0 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c  the memory.** al
306d0 6c 6f 63 61 74 65 64 20 62 79 20 61 20 73 69 6e  located by a sin
306e0 67 6c 65 20 74 68 72 65 61 64 20 2d 20 74 68 65  gle thread - the
306f0 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20   same thread in 
30700 77 68 69 63 68 20 74 68 69 73 20 72 6f 75 74 69  which this routi
30710 6e 65 0a 2a 2a 20 72 75 6e 73 2e 20 20 42 65 67  ne.** runs.  Beg
30720 69 6e 6e 69 6e 67 20 77 69 74 68 20 53 51 4c 69  inning with SQLi
30730 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30  te version 3.5.0
30740 2c 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20  , the soft heap 
30750 6c 69 6d 69 74 20 69 73 0a 2a 2a 20 61 70 70 6c  limit is.** appl
30760 69 65 64 20 74 6f 20 61 6c 6c 20 74 68 72 65 61  ied to all threa
30770 64 73 2e 20 54 68 65 20 76 61 6c 75 65 20 73 70  ds. The value sp
30780 65 63 69 66 69 65 64 20 66 6f 72 20 74 68 65 20  ecified for the 
30790 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 0a  soft heap limit.
307a0 2a 2a 20 69 73 20 61 6e 20 75 70 70 65 72 20 62  ** is an upper b
307b0 6f 75 6e 64 20 6f 6e 20 74 68 65 20 74 6f 74 61  ound on the tota
307c0 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
307d0 69 6f 6e 20 66 6f 72 20 61 6c 6c 20 74 68 72 65  ion for all thre
307e0 61 64 73 2e 20 49 6e 0a 2a 2a 20 76 65 72 73 69  ads. In.** versi
307f0 6f 6e 20 33 2e 35 2e 30 20 74 68 65 72 65 20 69  on 3.5.0 there i
30800 73 20 6e 6f 20 6d 65 63 68 61 6e 69 73 6d 20 66  s no mechanism f
30810 6f 72 20 6c 69 6d 69 74 69 6e 67 20 74 68 65 20  or limiting the 
30820 68 65 61 70 20 75 73 61 67 65 20 66 6f 72 0a 2a  heap usage for.*
30830 2a 20 69 6e 64 69 76 69 64 75 61 6c 20 74 68 72  * individual thr
30840 65 61 64 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  eads..**.** INVA
30850 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  RIANTS:.**.** {F
30860 31 36 33 35 31 7d 20 54 68 65 20 5b 73 71 6c 69  16351} The [sqli
30870 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69  te3_soft_heap_li
30880 6d 69 74 28 4e 29 5d 20 69 6e 74 65 72 66 61 63  mit(N)] interfac
30890 65 20 70 6c 61 63 65 73 20 61 20 73 6f 66 74 20  e places a soft 
308a0 6c 69 6d 69 74 0a 2a 2a 20 20 20 20 20 20 20 20  limit.**        
308b0 20 20 6f 66 20 4e 20 62 79 74 65 73 20 6f 6e 20    of N bytes on 
308c0 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 68 65  the amount of he
308d0 61 70 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 6d  ap memory that m
308e0 61 79 20 62 65 20 61 6c 6c 6f 63 61 74 65 64 0a  ay be allocated.
308f0 2a 2a 20 20 20 20 20 20 20 20 20 20 75 73 69 6e  **          usin
30900 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  g [sqlite3_mallo
30910 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  c()] or [sqlite3
30920 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 61 74 20 61  _realloc()] at a
30930 6e 79 20 70 6f 69 6e 74 0a 2a 2a 20 20 20 20 20  ny point.**     
30940 20 20 20 20 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a       in time..**
30950 0a 2a 2a 20 7b 46 31 36 33 35 32 7d 20 49 66 20  .** {F16352} If 
30960 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  a call to [sqlit
30970 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20  e3_malloc()] or 
30980 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
30990 28 29 5d 20 77 6f 75 6c 64 0a 2a 2a 20 20 20 20  ()] would.**    
309a0 20 20 20 20 20 20 63 61 75 73 65 20 74 68 65 20        cause the 
309b0 74 6f 74 61 6c 20 61 6d 6f 75 6e 74 20 6f 66 20  total amount of 
309c0 61 6c 6c 6f 63 61 74 65 64 20 6d 65 6d 6f 72 79  allocated memory
309d0 20 74 6f 20 65 78 63 65 65 64 20 74 68 65 0a 2a   to exceed the.*
309e0 2a 20 20 20 20 20 20 20 20 20 20 73 6f 66 74 20  *          soft 
309f0 68 65 61 70 20 6c 69 6d 69 74 2c 20 74 68 65 6e  heap limit, then
30a00 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73   [sqlite3_releas
30a10 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 69 73 20 69  e_memory()] is i
30a20 6e 76 6f 6b 65 64 0a 2a 2a 20 20 20 20 20 20 20  nvoked.**       
30a30 20 20 20 69 6e 20 61 6e 20 61 74 74 65 6d 70 74     in an attempt
30a40 20 74 6f 20 72 65 64 75 63 65 20 74 68 65 20 6d   to reduce the m
30a50 65 6d 6f 72 79 20 75 73 61 67 65 20 70 72 69 6f  emory usage prio
30a60 72 20 74 6f 20 70 72 6f 63 65 65 64 69 6e 67 0a  r to proceeding.
30a70 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69 74 68  **          with
30a80 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
30a90 63 61 74 69 6f 6e 20 61 74 74 65 6d 70 74 2e 0a  cation attempt..
30aa0 2a 2a 0a 2a 2a 20 7b 46 31 36 33 35 33 7d 20 43  **.** {F16353} C
30ab0 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
30ac0 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73  _malloc()] or [s
30ad0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
30ae0 5d 20 74 68 61 74 20 74 72 69 67 67 65 72 0a 2a  ] that trigger.*
30af0 2a 20 20 20 20 20 20 20 20 20 20 61 74 74 65 6d  *          attem
30b00 70 74 73 20 74 6f 20 72 65 64 75 63 65 20 6d 65  pts to reduce me
30b10 6d 6f 72 79 20 75 73 61 67 65 20 74 68 72 6f 75  mory usage throu
30b20 67 68 20 74 68 65 20 73 6f 66 74 20 68 65 61 70  gh the soft heap
30b30 20 6c 69 6d 69 74 0a 2a 2a 20 20 20 20 20 20 20   limit.**       
30b40 20 20 20 6d 65 63 68 61 6e 69 73 6d 20 63 6f 6e     mechanism con
30b50 74 69 6e 75 65 20 65 76 65 6e 20 69 66 20 74 68  tinue even if th
30b60 65 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 64  e attempt to red
30b70 75 63 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20  uce memory.**   
30b80 20 20 20 20 20 20 20 75 73 61 67 65 20 69 73 20         usage is 
30b90 75 6e 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2a  unsuccessful..**
30ba0 0a 2a 2a 20 7b 46 31 36 33 35 34 7d 20 41 20 6e  .** {F16354} A n
30bb0 65 67 61 74 69 76 65 20 6f 72 20 7a 65 72 6f 20  egative or zero 
30bc0 76 61 6c 75 65 20 66 6f 72 20 4e 20 69 6e 20 61  value for N in a
30bd0 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 20 20 20 20   call to.**     
30be0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 6f       [sqlite3_so
30bf0 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 4e 29  ft_heap_limit(N)
30c00 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
30c10 72 65 20 69 73 20 6e 6f 20 73 6f 66 74 0a 2a 2a  re is no soft.**
30c20 20 20 20 20 20 20 20 20 20 20 68 65 61 70 20 6c            heap l
30c30 69 6d 69 74 20 61 6e 64 20 5b 73 71 6c 69 74 65  imit and [sqlite
30c40 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79  3_release_memory
30c50 28 29 5d 20 77 69 6c 6c 20 6f 6e 6c 79 20 62 65  ()] will only be
30c60 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c  .**          cal
30c70 6c 65 64 20 77 68 65 6e 20 6d 65 6d 6f 72 79 20  led when memory 
30c80 69 73 20 63 6f 6d 70 6c 65 74 65 6c 79 20 65 78  is completely ex
30c90 68 61 75 73 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b  hausted..**.** {
30ca0 46 31 36 33 35 35 7d 20 54 68 65 20 64 65 66 61  F16355} The defa
30cb0 75 6c 74 20 76 61 6c 75 65 20 66 6f 72 20 74 68  ult value for th
30cc0 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69  e soft heap limi
30cd0 74 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a  t is zero..**.**
30ce0 20 7b 46 31 36 33 35 38 7d 20 45 61 63 68 20 63   {F16358} Each c
30cf0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
30d00 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28  soft_heap_limit(
30d10 4e 29 5d 20 6f 76 65 72 72 69 64 65 73 20 74 68  N)] overrides th
30d20 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61  e.**          va
30d30 6c 75 65 73 20 73 65 74 20 62 79 20 61 6c 6c 20  lues set by all 
30d40 70 72 69 6f 72 20 63 61 6c 6c 73 2e 0a 2a 2f 0a  prior calls..*/.
30d50 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 6f 66  void sqlite3_sof
30d60 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 69 6e 74  t_heap_limit(int
30d70 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
30d80 45 46 3a 20 20 45 78 74 72 61 63 74 20 4d 65 74  EF:  Extract Met
30d90 61 64 61 74 61 20 41 62 6f 75 74 20 41 20 43 6f  adata About A Co
30da0 6c 75 6d 6e 20 4f 66 20 41 20 54 61 62 6c 65 20  lumn Of A Table 
30db0 7b 46 31 32 38 35 30 7d 0a 2a 2a 0a 2a 2a 20 54  {F12850}.**.** T
30dc0 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72  his routine.** r
30dd0 65 74 75 72 6e 73 20 6d 65 74 61 2d 64 61 74 61  eturns meta-data
30de0 20 61 62 6f 75 74 20 61 20 73 70 65 63 69 66 69   about a specifi
30df0 63 20 63 6f 6c 75 6d 6e 20 6f 66 20 61 20 73 70  c column of a sp
30e00 65 63 69 66 69 63 20 64 61 74 61 62 61 73 65 0a  ecific database.
30e10 2a 2a 20 74 61 62 6c 65 20 61 63 63 65 73 73 69  ** table accessi
30e20 62 6c 65 20 75 73 69 6e 67 20 74 68 65 20 63 6f  ble using the co
30e30 6e 6e 65 63 74 69 6f 6e 20 68 61 6e 64 6c 65 20  nnection handle 
30e40 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69  passed as the fi
30e50 72 73 74 20 66 75 6e 63 74 69 6f 6e 20 0a 2a 2a  rst function .**
30e60 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
30e70 20 54 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 69   The column is i
30e80 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65  dentified by the
30e90 20 73 65 63 6f 6e 64 2c 20 74 68 69 72 64 20 61   second, third a
30ea0 6e 64 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  nd fourth parame
30eb0 74 65 72 73 20 74 6f 20 0a 2a 2a 20 74 68 69 73  ters to .** this
30ec0 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 73   function. The s
30ed0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
30ee0 69 73 20 65 69 74 68 65 72 20 74 68 65 20 6e 61  is either the na
30ef0 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  me of the databa
30f00 73 65 0a 2a 2a 20 28 69 2e 65 2e 20 22 6d 61 69  se.** (i.e. "mai
30f10 6e 22 2c 20 22 74 65 6d 70 22 20 6f 72 20 61 6e  n", "temp" or an
30f20 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61   attached databa
30f30 73 65 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  se) containing t
30f40 68 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20  he specified.** 
30f50 74 61 62 6c 65 20 6f 72 20 4e 55 4c 4c 2e 20 49  table or NULL. I
30f60 66 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68  f it is NULL, th
30f70 65 6e 20 61 6c 6c 20 61 74 74 61 63 68 65 64 20  en all attached 
30f80 64 61 74 61 62 61 73 65 73 20 61 72 65 20 73 65  databases are se
30f90 61 72 63 68 65 64 0a 2a 2a 20 66 6f 72 20 74 68  arched.** for th
30fa0 65 20 74 61 62 6c 65 20 75 73 69 6e 67 20 74 68  e table using th
30fb0 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d  e same algorithm
30fc0 20 61 73 20 74 68 65 20 64 61 74 61 62 61 73 65   as the database
30fd0 20 65 6e 67 69 6e 65 20 75 73 65 73 20 74 6f 20   engine uses to 
30fe0 0a 2a 2a 20 72 65 73 6f 6c 76 65 20 75 6e 71 75  .** resolve unqu
30ff0 61 6c 69 66 69 65 64 20 74 61 62 6c 65 20 72 65  alified table re
31000 66 65 72 65 6e 63 65 73 2e 0a 2a 2a 0a 2a 2a 20  ferences..**.** 
31010 54 68 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f  The third and fo
31020 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 73 20  urth parameters 
31030 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  to this function
31040 20 61 72 65 20 74 68 65 20 74 61 62 6c 65 20 61   are the table a
31050 6e 64 20 63 6f 6c 75 6d 6e 20 0a 2a 2a 20 6e 61  nd column .** na
31060 6d 65 20 6f 66 20 74 68 65 20 64 65 73 69 72 65  me of the desire
31070 64 20 63 6f 6c 75 6d 6e 2c 20 72 65 73 70 65 63  d column, respec
31080 74 69 76 65 6c 79 2e 20 4e 65 69 74 68 65 72 20  tively. Neither 
31090 6f 66 20 74 68 65 73 65 20 70 61 72 61 6d 65 74  of these paramet
310a0 65 72 73 20 0a 2a 2a 20 6d 61 79 20 62 65 20 4e  ers .** may be N
310b0 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 4d 65 74 61 20  ULL..**.** Meta 
310c0 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72  information is r
310d0 65 74 75 72 6e 65 64 20 62 79 20 77 72 69 74 69  eturned by writi
310e0 6e 67 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79  ng to the memory
310f0 20 6c 6f 63 61 74 69 6f 6e 73 20 70 61 73 73 65   locations passe
31100 64 20 61 73 0a 2a 2a 20 74 68 65 20 35 74 68 20  d as.** the 5th 
31110 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20 70  and subsequent p
31120 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 69  arameters to thi
31130 73 20 66 75 6e 63 74 69 6f 6e 2e 20 41 6e 79 20  s function. Any 
31140 6f 66 20 74 68 65 73 65 20 0a 2a 2a 20 61 72 67  of these .** arg
31150 75 6d 65 6e 74 73 20 6d 61 79 20 62 65 20 4e 55  uments may be NU
31160 4c 4c 2c 20 69 6e 20 77 68 69 63 68 20 63 61 73  LL, in which cas
31170 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  e the correspond
31180 69 6e 67 20 65 6c 65 6d 65 6e 74 20 6f 66 20 6d  ing element of m
31190 65 74 61 20 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  eta .** informat
311a0 69 6f 6e 20 69 73 20 6f 6d 6d 69 74 74 65 64 2e  ion is ommitted.
311b0 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20  .**.** <pre>.** 
311c0 50 61 72 61 6d 65 74 65 72 20 20 20 20 20 4f 75  Parameter     Ou
311d0 74 70 75 74 20 54 79 70 65 20 20 20 20 20 20 44  tput Type      D
311e0 65 73 63 72 69 70 74 69 6f 6e 0a 2a 2a 20 2d 2d  escription.** --
311f0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
31200 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
31210 2d 0a 2a 2a 0a 2a 2a 20 20 20 35 74 68 20 20 20  -.**.**   5th   
31220 20 20 20 20 20 20 63 6f 6e 73 74 20 63 68 61 72        const char
31230 2a 20 20 20 20 20 20 44 61 74 61 20 74 79 70 65  *      Data type
31240 0a 2a 2a 20 20 20 36 74 68 20 20 20 20 20 20 20  .**   6th       
31250 20 20 63 6f 6e 73 74 20 63 68 61 72 2a 20 20 20    const char*   
31260 20 20 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 64     Name of the d
31270 65 66 61 75 6c 74 20 63 6f 6c 6c 61 74 69 6f 6e  efault collation
31280 20 73 65 71 75 65 6e 63 65 20 0a 2a 2a 20 20 20   sequence .**   
31290 37 74 68 20 20 20 20 20 20 20 20 20 69 6e 74 20  7th         int 
312a0 20 20 20 20 20 20 20 20 20 20 20 20 20 54 72 75               Tru
312b0 65 20 69 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20  e if the column 
312c0 68 61 73 20 61 20 4e 4f 54 20 4e 55 4c 4c 20 63  has a NOT NULL c
312d0 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 20 20 38  onstraint.**   8
312e0 74 68 20 20 20 20 20 20 20 20 20 69 6e 74 20 20  th         int  
312f0 20 20 20 20 20 20 20 20 20 20 20 20 54 72 75 65              True
31300 20 69 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69   if the column i
31310 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 50 52  s part of the PR
31320 49 4d 41 52 59 20 4b 45 59 0a 2a 2a 20 20 20 39  IMARY KEY.**   9
31330 74 68 20 20 20 20 20 20 20 20 20 69 6e 74 20 20  th         int  
31340 20 20 20 20 20 20 20 20 20 20 20 20 54 72 75 65              True
31350 20 69 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69   if the column i
31360 73 20 41 55 54 4f 49 4e 43 52 45 4d 45 4e 54 0a  s AUTOINCREMENT.
31370 2a 2a 20 3c 2f 70 72 65 3e 0a 2a 2a 0a 2a 2a 0a  ** </pre>.**.**.
31380 2a 2a 20 54 68 65 20 6d 65 6d 6f 72 79 20 70 6f  ** The memory po
31390 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 20  inted to by the 
313a0 63 68 61 72 61 63 74 65 72 20 70 6f 69 6e 74 65  character pointe
313b0 72 73 20 72 65 74 75 72 6e 65 64 20 66 6f 72 20  rs returned for 
313c0 74 68 65 20 0a 2a 2a 20 64 65 63 6c 61 72 61 74  the .** declarat
313d0 69 6f 6e 20 74 79 70 65 20 61 6e 64 20 63 6f 6c  ion type and col
313e0 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20  lation sequence 
313f0 69 73 20 76 61 6c 69 64 20 6f 6e 6c 79 20 75 6e  is valid only un
31400 74 69 6c 20 74 68 65 20 6e 65 78 74 20 0a 2a 2a  til the next .**
31410 20 63 61 6c 6c 20 74 6f 20 61 6e 79 20 73 71 6c   call to any sql
31420 69 74 65 20 41 50 49 20 66 75 6e 63 74 69 6f 6e  ite API function
31430 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 73  ..**.** If the s
31440 70 65 63 69 66 69 65 64 20 74 61 62 6c 65 20 69  pecified table i
31450 73 20 61 63 74 75 61 6c 6c 79 20 61 20 76 69 65  s actually a vie
31460 77 2c 20 74 68 65 6e 20 61 6e 20 65 72 72 6f 72  w, then an error
31470 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
31480 0a 2a 2a 20 49 66 20 74 68 65 20 73 70 65 63 69  .** If the speci
31490 66 69 65 64 20 63 6f 6c 75 6d 6e 20 69 73 20 22  fied column is "
314a0 72 6f 77 69 64 22 2c 20 22 6f 69 64 22 20 6f 72  rowid", "oid" or
314b0 20 22 5f 72 6f 77 69 64 5f 22 20 61 6e 64 20 61   "_rowid_" and a
314c0 6e 20 0a 2a 2a 20 49 4e 54 45 47 45 52 20 50 52  n .** INTEGER PR
314d0 49 4d 41 52 59 20 4b 45 59 20 63 6f 6c 75 6d 6e  IMARY KEY column
314e0 20 68 61 73 20 62 65 65 6e 20 65 78 70 6c 69 63   has been explic
314f0 69 74 6c 79 20 64 65 63 6c 61 72 65 64 2c 20 74  itly declared, t
31500 68 65 6e 20 74 68 65 20 6f 75 74 70 75 74 20 0a  hen the output .
31510 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 61 72  ** parameters ar
31520 65 20 73 65 74 20 66 6f 72 20 74 68 65 20 65 78  e set for the ex
31530 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65  plicitly declare
31540 64 20 63 6f 6c 75 6d 6e 2e 20 49 66 20 74 68 65  d column. If the
31550 72 65 20 69 73 20 6e 6f 0a 2a 2a 20 65 78 70 6c  re is no.** expl
31560 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20  icitly declared 
31570 49 50 4b 20 63 6f 6c 75 6d 6e 2c 20 74 68 65 6e  IPK column, then
31580 20 74 68 65 20 6f 75 74 70 75 74 20 70 61 72 61   the output para
31590 6d 65 74 65 72 73 20 61 72 65 20 73 65 74 20 61  meters are set a
315a0 73 20 0a 2a 2a 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  s .** follows:.*
315b0 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20 20  *.** <pre>.**   
315c0 20 20 64 61 74 61 20 74 79 70 65 3a 20 22 49 4e    data type: "IN
315d0 54 45 47 45 52 22 0a 2a 2a 20 20 20 20 20 63 6f  TEGER".**     co
315e0 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
315f0 3a 20 22 42 49 4e 41 52 59 22 0a 2a 2a 20 20 20  : "BINARY".**   
31600 20 20 6e 6f 74 20 6e 75 6c 6c 3a 20 30 0a 2a 2a    not null: 0.**
31610 20 20 20 20 20 70 72 69 6d 61 72 79 20 6b 65 79       primary key
31620 3a 20 31 0a 2a 2a 20 20 20 20 20 61 75 74 6f 20  : 1.**     auto 
31630 69 6e 63 72 65 6d 65 6e 74 3a 20 30 0a 2a 2a 20  increment: 0.** 
31640 3c 2f 70 72 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  </pre>.**.** Thi
31650 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 6c  s function may l
31660 6f 61 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  oad one or more 
31670 73 63 68 65 6d 61 73 20 66 72 6f 6d 20 64 61 74  schemas from dat
31680 61 62 61 73 65 20 66 69 6c 65 73 2e 20 49 66 20  abase files. If 
31690 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 6f 63 63 75  an.** error occu
316a0 72 73 20 64 75 72 69 6e 67 20 74 68 69 73 20 70  rs during this p
316b0 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 74 68  rocess, or if th
316c0 65 20 72 65 71 75 65 73 74 65 64 20 74 61 62 6c  e requested tabl
316d0 65 20 6f 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 63  e or column.** c
316e0 61 6e 6e 6f 74 20 62 65 20 66 6f 75 6e 64 2c 20  annot be found, 
316f0 61 6e 20 53 51 4c 49 54 45 20 65 72 72 6f 72 20  an SQLITE error 
31700 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64  code is returned
31710 20 61 6e 64 20 61 6e 20 65 72 72 6f 72 20 6d 65   and an error me
31720 73 73 61 67 65 0a 2a 2a 20 6c 65 66 74 20 69 6e  ssage.** left in
31730 20 74 68 65 20 64 61 74 61 62 61 73 65 20 68 61   the database ha
31740 6e 64 6c 65 20 28 74 6f 20 62 65 20 72 65 74 72  ndle (to be retr
31750 69 65 76 65 64 20 75 73 69 6e 67 20 73 71 6c 69  ieved using sqli
31760 74 65 33 5f 65 72 72 6d 73 67 28 29 29 2e 0a 2a  te3_errmsg())..*
31770 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49 20 69 73  *.** This API is
31780 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20   only available 
31790 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 20 77  if the library w
317a0 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  as compiled with
317b0 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 45   the.** SQLITE_E
317c0 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54  NABLE_COLUMN_MET
317d0 41 44 41 54 41 20 70 72 65 70 72 6f 63 65 73 73  ADATA preprocess
317e0 6f 72 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65  or symbol define
317f0 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  d..*/.int sqlite
31800 33 5f 74 61 62 6c 65 5f 63 6f 6c 75 6d 6e 5f 6d  3_table_column_m
31810 65 74 61 64 61 74 61 28 0a 20 20 73 71 6c 69 74  etadata(.  sqlit
31820 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
31830 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e 6e 65 63         /* Connec
31840 74 69 6f 6e 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  tion handle */. 
31850 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62   const char *zDb
31860 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 2f 2a 20  Name,        /* 
31870 44 61 74 61 62 61 73 65 20 6e 61 6d 65 20 6f 72  Database name or
31880 20 4e 55 4c 4c 20 2a 2f 0a 20 20 63 6f 6e 73 74   NULL */.  const
31890 20 63 68 61 72 20 2a 7a 54 61 62 6c 65 4e 61 6d   char *zTableNam
318a0 65 2c 20 20 20 20 20 2f 2a 20 54 61 62 6c 65 20  e,     /* Table 
318b0 6e 61 6d 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  name */.  const 
318c0 63 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e 4e 61 6d  char *zColumnNam
318d0 65 2c 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20  e,    /* Column 
318e0 6e 61 6d 65 20 2a 2f 0a 20 20 63 68 61 72 20 63  name */.  char c
318f0 6f 6e 73 74 20 2a 2a 70 7a 44 61 74 61 54 79 70  onst **pzDataTyp
31900 65 2c 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a  e,    /* OUTPUT:
31910 20 44 65 63 6c 61 72 65 64 20 64 61 74 61 20 74   Declared data t
31920 79 70 65 20 2a 2f 0a 20 20 63 68 61 72 20 63 6f  ype */.  char co
31930 6e 73 74 20 2a 2a 70 7a 43 6f 6c 6c 53 65 71 2c  nst **pzCollSeq,
31940 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20       /* OUTPUT: 
31950 43 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  Collation sequen
31960 63 65 20 6e 61 6d 65 20 2a 2f 0a 20 20 69 6e 74  ce name */.  int
31970 20 2a 70 4e 6f 74 4e 75 6c 6c 2c 20 20 20 20 20   *pNotNull,     
31980 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50           /* OUTP
31990 55 54 3a 20 54 72 75 65 20 69 66 20 4e 4f 54 20  UT: True if NOT 
319a0 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69 6e 74 20  NULL constraint 
319b0 65 78 69 73 74 73 20 2a 2f 0a 20 20 69 6e 74 20  exists */.  int 
319c0 2a 70 50 72 69 6d 61 72 79 4b 65 79 2c 20 20 20  *pPrimaryKey,   
319d0 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55          /* OUTPU
319e0 54 3a 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d  T: True if colum
319f0 6e 20 70 61 72 74 20 6f 66 20 50 4b 20 2a 2f 0a  n part of PK */.
31a00 20 20 69 6e 74 20 2a 70 41 75 74 6f 69 6e 63 20    int *pAutoinc 
31a10 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
31a20 20 4f 55 54 50 55 54 3a 20 54 72 75 65 20 69 66   OUTPUT: True if
31a30 20 63 6f 6c 75 6d 6e 20 69 73 20 61 75 74 6f 2d   column is auto-
31a40 69 6e 63 72 65 6d 65 6e 74 20 2a 2f 0a 29 3b 0a  increment */.);.
31a50 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
31a60 20 4c 6f 61 64 20 41 6e 20 45 78 74 65 6e 73 69   Load An Extensi
31a70 6f 6e 20 7b 46 31 32 36 30 30 7d 0a 2a 2a 0a 2a  on {F12600}.**.*
31a80 2a 20 7b 46 31 32 36 30 31 7d 20 54 68 65 20 73  * {F12601} The s
31a90 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65  qlite3_load_exte
31aa0 6e 73 69 6f 6e 28 29 20 69 6e 74 65 72 66 61 63  nsion() interfac
31ab0 65 0a 2a 2a 20 61 74 74 65 6d 70 74 73 20 74 6f  e.** attempts to
31ac0 20 6c 6f 61 64 20 61 6e 20 53 51 4c 69 74 65 20   load an SQLite 
31ad0 65 78 74 65 6e 73 69 6f 6e 20 6c 69 62 72 61 72  extension librar
31ae0 79 20 63 6f 6e 74 61 69 6e 65 64 20 69 6e 20 74  y contained in t
31af0 68 65 20 66 69 6c 65 0a 2a 2a 20 7a 46 69 6c 65  he file.** zFile
31b00 2e 20 7b 46 31 32 36 30 32 7d 20 54 68 65 20 65  . {F12602} The e
31b10 6e 74 72 79 20 70 6f 69 6e 74 20 69 73 20 7a 50  ntry point is zP
31b20 72 6f 63 2e 20 7b 46 31 32 36 30 33 7d 20 7a 50  roc. {F12603} zP
31b30 72 6f 63 20 6d 61 79 20 62 65 20 30 0a 2a 2a 20  roc may be 0.** 
31b40 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 74 68  in which case th
31b50 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 65 6e  e name of the en
31b60 74 72 79 20 70 6f 69 6e 74 20 64 65 66 61 75 6c  try point defaul
31b70 74 73 0a 2a 2a 20 74 6f 20 22 73 71 6c 69 74 65  ts.** to "sqlite
31b80 33 5f 65 78 74 65 6e 73 69 6f 6e 5f 69 6e 69 74  3_extension_init
31b90 22 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36 30 34  "..**.** {F12604
31ba0 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f  } The sqlite3_lo
31bb0 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 69  ad_extension() i
31bc0 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c 0a 2a  nterface shall.*
31bd0 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  * return [SQLITE
31be0 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20  _OK] on success 
31bf0 61 6e 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  and [SQLITE_ERRO
31c00 52 5d 20 69 66 20 73 6f 6d 65 74 68 69 6e 67 20  R] if something 
31c10 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 0a 2a  goes wrong..**.*
31c20 2a 20 7b 46 31 32 36 30 35 7d 0a 2a 2a 20 49 66  * {F12605}.** If
31c30 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
31c40 20 61 6e 64 20 70 7a 45 72 72 4d 73 67 20 69 73   and pzErrMsg is
31c50 20 6e 6f 74 20 30 2c 20 74 68 65 6e 20 74 68 65   not 0, then the
31c60 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64  .** sqlite3_load
31c70 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e 74  _extension() int
31c80 65 72 66 61 63 65 20 73 68 61 6c 6c 20 61 74 74  erface shall att
31c90 65 6d 70 74 20 74 6f 20 66 69 6c 6c 20 2a 70 7a  empt to fill *pz
31ca0 45 72 72 4d 73 67 20 77 69 74 68 20 0a 2a 2a 20  ErrMsg with .** 
31cb0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65  error message te
31cc0 78 74 20 73 74 6f 72 65 64 20 69 6e 20 6d 65 6d  xt stored in mem
31cd0 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
31ce0 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
31cf0 63 28 29 5d 2e 0a 2a 2a 20 7b 45 4e 44 7d 20 20  c()]..** {END}  
31d00 54 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63  The calling func
31d10 74 69 6f 6e 20 73 68 6f 75 6c 64 20 66 72 65 65  tion should free
31d20 20 74 68 69 73 20 6d 65 6d 6f 72 79 0a 2a 2a 20   this memory.** 
31d30 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
31d40 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a  te3_free()]..**.
31d50 2a 2a 20 7b 46 31 32 36 30 36 7d 0a 2a 2a 20 45  ** {F12606}.** E
31d60 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67  xtension loading
31d70 20 6d 75 73 74 20 62 65 20 65 6e 61 62 6c 65 64   must be enabled
31d80 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
31d90 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65  enable_load_exte
31da0 6e 73 69 6f 6e 28 29 5d 0a 2a 2a 20 70 72 69 6f  nsion()].** prio
31db0 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20 74 68 69  r to calling thi
31dc0 73 20 41 50 49 20 6f 72 20 61 6e 20 65 72 72 6f  s API or an erro
31dd0 72 20 77 69 6c 6c 20 62 65 20 72 65 74 75 72 6e  r will be return
31de0 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ed..*/.int sqlit
31df0 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  e3_load_extensio
31e00 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  n(.  sqlite3 *db
31e10 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4c 6f  ,          /* Lo
31e20 61 64 20 74 68 65 20 65 78 74 65 6e 73 69 6f 6e  ad the extension
31e30 20 69 6e 74 6f 20 74 68 69 73 20 64 61 74 61 62   into this datab
31e40 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 2a  ase connection *
31e50 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
31e60 7a 46 69 6c 65 2c 20 20 20 20 2f 2a 20 4e 61 6d  zFile,    /* Nam
31e70 65 20 6f 66 20 74 68 65 20 73 68 61 72 65 64 20  e of the shared 
31e80 6c 69 62 72 61 72 79 20 63 6f 6e 74 61 69 6e 69  library containi
31e90 6e 67 20 65 78 74 65 6e 73 69 6f 6e 20 2a 2f 0a  ng extension */.
31ea0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50    const char *zP
31eb0 72 6f 63 2c 20 20 20 20 2f 2a 20 45 6e 74 72 79  roc,    /* Entry
31ec0 20 70 6f 69 6e 74 2e 20 20 44 65 72 69 76 65 64   point.  Derived
31ed0 20 66 72 6f 6d 20 7a 46 69 6c 65 20 69 66 20 30   from zFile if 0
31ee0 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45   */.  char **pzE
31ef0 72 72 4d 73 67 20 20 20 20 20 20 20 2f 2a 20 50  rrMsg       /* P
31f00 75 74 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  ut error message
31f10 20 68 65 72 65 20 69 66 20 6e 6f 74 20 30 20 2a   here if not 0 *
31f20 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.);../*.** CAPI
31f30 33 52 45 46 3a 20 20 45 6e 61 62 6c 65 20 4f 72  3REF:  Enable Or
31f40 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e 73 69   Disable Extensi
31f50 6f 6e 20 4c 6f 61 64 69 6e 67 20 7b 46 31 32 36  on Loading {F126
31f60 32 30 7d 0a 2a 2a 0a 2a 2a 20 53 6f 20 61 73 20  20}.**.** So as 
31f70 6e 6f 74 20 74 6f 20 6f 70 65 6e 20 73 65 63 75  not to open secu
31f80 72 69 74 79 20 68 6f 6c 65 73 20 69 6e 20 6f 6c  rity holes in ol
31f90 64 65 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  der applications
31fa0 20 74 68 61 74 20 61 72 65 0a 2a 2a 20 75 6e 70   that are.** unp
31fb0 72 65 70 61 72 65 64 20 74 6f 20 64 65 61 6c 20  repared to deal 
31fc0 77 69 74 68 20 65 78 74 65 6e 73 69 6f 6e 20 6c  with extension l
31fd0 6f 61 64 69 6e 67 2c 20 61 6e 64 20 61 73 20 61  oading, and as a
31fe0 20 6d 65 61 6e 73 20 6f 66 20 64 69 73 61 62 6c   means of disabl
31ff0 69 6e 67 0a 2a 2a 20 65 78 74 65 6e 73 69 6f 6e  ing.** extension
32000 20 6c 6f 61 64 69 6e 67 20 77 68 69 6c 65 20 65   loading while e
32010 76 61 6c 75 61 74 69 6e 67 20 75 73 65 72 2d 65  valuating user-e
32020 6e 74 65 72 65 64 20 53 51 4c 2c 20 74 68 65 20  ntered SQL, the 
32030 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 41 50 49  following.** API
32040 20 69 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20   is provided to 
32050 74 75 72 6e 20 74 68 65 20 5b 73 71 6c 69 74 65  turn the [sqlite
32060 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e  3_load_extension
32070 28 29 5d 20 6d 65 63 68 61 6e 69 73 6d 20 6f 6e  ()] mechanism on
32080 20 61 6e 64 0a 2a 2a 20 6f 66 66 2e 20 20 7b 46   and.** off.  {F
32090 31 32 36 32 32 7d 20 49 74 20 69 73 20 6f 66 66  12622} It is off
320a0 20 62 79 20 64 65 66 61 75 6c 74 2e 20 7b 45 4e   by default. {EN
320b0 44 7d 20 53 65 65 20 74 69 63 6b 65 74 20 23 31  D} See ticket #1
320c0 38 36 33 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36  863..**.** {F126
320d0 32 31 7d 20 43 61 6c 6c 20 74 68 65 20 73 71 6c  21} Call the sql
320e0 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64  ite3_enable_load
320f0 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 72 6f 75  _extension() rou
32100 74 69 6e 65 0a 2a 2a 20 77 69 74 68 20 6f 6e 6f  tine.** with ono
32110 66 66 3d 3d 31 20 74 6f 20 74 75 72 6e 20 65 78  ff==1 to turn ex
32120 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20  tension loading 
32130 6f 6e 0a 2a 2a 20 61 6e 64 20 63 61 6c 6c 20 69  on.** and call i
32140 74 20 77 69 74 68 20 6f 6e 6f 66 66 3d 3d 30 20  t with onoff==0 
32150 74 6f 20 74 75 72 6e 20 69 74 20 62 61 63 6b 20  to turn it back 
32160 6f 66 66 20 61 67 61 69 6e 2e 20 7b 45 4e 44 7d  off again. {END}
32170 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
32180 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65  enable_load_exte
32190 6e 73 69 6f 6e 28 73 71 6c 69 74 65 33 20 2a 64  nsion(sqlite3 *d
321a0 62 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a  b, int onoff);..
321b0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
321c0 4d 61 6b 65 20 41 72 72 61 6e 67 65 6d 65 6e 74  Make Arrangement
321d0 73 20 54 6f 20 41 75 74 6f 6d 61 74 69 63 61 6c  s To Automatical
321e0 6c 79 20 4c 6f 61 64 20 41 6e 20 45 78 74 65 6e  ly Load An Exten
321f0 73 69 6f 6e 20 7b 46 31 32 36 34 30 7d 0a 2a 2a  sion {F12640}.**
32200 0a 2a 2a 20 7b 46 31 32 36 34 31 7d 20 54 68 69  .** {F12641} Thi
32210 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 72 65  s function.** re
32220 67 69 73 74 65 72 73 20 61 6e 20 65 78 74 65 6e  gisters an exten
32230 73 69 6f 6e 20 65 6e 74 72 79 20 70 6f 69 6e 74  sion entry point
32240 20 74 68 61 74 20 69 73 20 61 75 74 6f 6d 61 74   that is automat
32250 69 63 61 6c 6c 79 20 69 6e 76 6f 6b 65 64 0a 2a  ically invoked.*
32260 2a 20 77 68 65 6e 65 76 65 72 20 61 20 6e 65 77  * whenever a new
32270 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
32280 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 20 75  tion is opened u
32290 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
322a0 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
322b0 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72  e3_open16()], or
322c0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
322d0 32 28 29 5d 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a  2()]. {END}.**.*
322e0 2a 20 54 68 69 73 20 41 50 49 20 63 61 6e 20 62  * This API can b
322f0 65 20 69 6e 76 6f 6b 65 64 20 61 74 20 70 72 6f  e invoked at pro
32300 67 72 61 6d 20 73 74 61 72 74 75 70 20 69 6e 20  gram startup in 
32310 6f 72 64 65 72 20 74 6f 20 72 65 67 69 73 74 65  order to registe
32320 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  r.** one or more
32330 20 73 74 61 74 69 63 61 6c 6c 79 20 6c 69 6e 6b   statically link
32340 65 64 20 65 78 74 65 6e 73 69 6f 6e 73 20 74 68  ed extensions th
32350 61 74 20 77 69 6c 6c 20 62 65 20 61 76 61 69 6c  at will be avail
32360 61 62 6c 65 0a 2a 2a 20 74 6f 20 61 6c 6c 20 6e  able.** to all n
32370 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ew database conn
32380 65 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 7b  ections..**.** {
32390 46 31 32 36 34 32 7d 20 44 75 70 6c 69 63 61 74  F12642} Duplicat
323a0 65 20 65 78 74 65 6e 73 69 6f 6e 73 20 61 72 65  e extensions are
323b0 20 64 65 74 65 63 74 65 64 20 73 6f 20 63 61 6c   detected so cal
323c0 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e  ling this routin
323d0 65 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 69  e multiple.** ti
323e0 6d 65 73 20 77 69 74 68 20 74 68 65 20 73 61 6d  mes with the sam
323f0 65 20 65 78 74 65 6e 73 69 6f 6e 20 69 73 20 68  e extension is h
32400 61 72 6d 6c 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 7b  armless..**.** {
32410 46 31 32 36 34 33 7d 20 54 68 69 73 20 72 6f 75  F12643} This rou
32420 74 69 6e 65 20 73 74 6f 72 65 73 20 61 20 70 6f  tine stores a po
32430 69 6e 74 65 72 20 74 6f 20 74 68 65 20 65 78 74  inter to the ext
32440 65 6e 73 69 6f 6e 20 69 6e 20 61 6e 20 61 72 72  ension in an arr
32450 61 79 0a 2a 2a 20 74 68 61 74 20 69 73 20 6f 62  ay.** that is ob
32460 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69  tained from sqli
32470 74 65 5f 6d 61 6c 6c 6f 63 28 29 2e 20 7b 45 4e  te_malloc(). {EN
32480 44 7d 20 49 66 20 79 6f 75 20 72 75 6e 20 61 20  D} If you run a 
32490 6d 65 6d 6f 72 79 20 6c 65 61 6b 0a 2a 2a 20 63  memory leak.** c
324a0 68 65 63 6b 65 72 20 6f 6e 20 79 6f 75 72 20 70  hecker on your p
324b0 72 6f 67 72 61 6d 20 61 6e 64 20 69 74 20 72 65  rogram and it re
324c0 70 6f 72 74 73 20 61 20 6c 65 61 6b 20 62 65 63  ports a leak bec
324d0 61 75 73 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20  ause of this.** 
324e0 61 72 72 61 79 2c 20 74 68 65 6e 20 69 6e 76 6f  array, then invo
324f0 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ke [sqlite3_rese
32500 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e  t_auto_extension
32510 28 29 5d 20 70 72 69 6f 72 0a 2a 2a 20 74 6f 20  ()] prior.** to 
32520 73 68 75 74 64 6f 77 6e 20 74 6f 20 66 72 65 65  shutdown to free
32530 20 74 68 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 0a   the memory..**.
32540 2a 2a 20 7b 46 31 32 36 34 34 7d 20 41 75 74 6f  ** {F12644} Auto
32550 6d 61 74 69 63 20 65 78 74 65 6e 73 69 6f 6e 73  matic extensions
32560 20 61 70 70 6c 79 20 61 63 72 6f 73 73 20 61 6c   apply across al
32570 6c 20 74 68 72 65 61 64 73 2e 20 7b 45 4e 44 7d  l threads. {END}
32580 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65  .**.** This inte
32590 72 66 61 63 65 20 69 73 20 65 78 70 65 72 69 6d  rface is experim
325a0 65 6e 74 61 6c 20 61 6e 64 20 69 73 20 73 75 62  ental and is sub
325b0 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 6f  ject to change o
325c0 72 0a 2a 2a 20 72 65 6d 6f 76 61 6c 20 69 6e 20  r.** removal in 
325d0 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
325e0 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e  of SQLite..*/.in
325f0 74 20 73 71 6c 69 74 65 33 5f 61 75 74 6f 5f 65  t sqlite3_auto_e
32600 78 74 65 6e 73 69 6f 6e 28 76 6f 69 64 20 2a 78  xtension(void *x
32610 45 6e 74 72 79 50 6f 69 6e 74 29 3b 0a 0a 0a 2f  EntryPoint);.../
32620 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
32630 65 73 65 74 20 41 75 74 6f 6d 61 74 69 63 20 45  eset Automatic E
32640 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e 67  xtension Loading
32650 20 7b 46 31 32 36 36 30 7d 0a 2a 2a 0a 2a 2a 20   {F12660}.**.** 
32660 7b 46 31 32 36 36 31 7d 20 54 68 69 73 20 66 75  {F12661} This fu
32670 6e 63 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 20  nction disables 
32680 61 6c 6c 20 70 72 65 76 69 6f 75 73 6c 79 20 72  all previously r
32690 65 67 69 73 74 65 72 65 64 0a 2a 2a 20 61 75 74  egistered.** aut
326a0 6f 6d 61 74 69 63 20 65 78 74 65 6e 73 69 6f 6e  omatic extension
326b0 73 2e 20 7b 45 4e 44 7d 20 20 54 68 69 73 0a 2a  s. {END}  This.*
326c0 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73  * routine undoes
326d0 20 74 68 65 20 65 66 66 65 63 74 20 6f 66 20 61   the effect of a
326e0 6c 6c 20 70 72 69 6f 72 20 5b 73 71 6c 69 74 65  ll prior [sqlite
326f0 33 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e  3_auto_extension
32700 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 2e 0a 2a 2a  ()].** calls..**
32710 0a 2a 2a 20 7b 46 31 32 36 36 32 7d 20 54 68 69  .** {F12662} Thi
32720 73 20 63 61 6c 6c 20 64 69 73 61 62 6c 65 64 20  s call disabled 
32730 61 75 74 6f 6d 61 74 69 63 20 65 78 74 65 6e 73  automatic extens
32740 69 6f 6e 73 20 69 6e 20 61 6c 6c 20 74 68 72 65  ions in all thre
32750 61 64 73 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a  ads. {END}.**.**
32760 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   This interface 
32770 69 73 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20  is experimental 
32780 61 6e 64 20 69 73 20 73 75 62 6a 65 63 74 20 74  and is subject t
32790 6f 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 72  o change or.** r
327a0 65 6d 6f 76 61 6c 20 69 6e 20 66 75 74 75 72 65  emoval in future
327b0 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
327c0 69 74 65 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  ite..*/.void sql
327d0 69 74 65 33 5f 72 65 73 65 74 5f 61 75 74 6f 5f  ite3_reset_auto_
327e0 65 78 74 65 6e 73 69 6f 6e 28 76 6f 69 64 29 3b  extension(void);
327f0 0a 0a 0a 2f 2a 0a 2a 2a 2a 2a 2a 2a 20 45 58 50  .../*.****** EXP
32800 45 52 49 4d 45 4e 54 41 4c 20 2d 20 73 75 62 6a  ERIMENTAL - subj
32810 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 77 69  ect to change wi
32820 74 68 6f 75 74 20 6e 6f 74 69 63 65 20 2a 2a 2a  thout notice ***
32830 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2a 0a 2a  ***********.**.*
32840 2a 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20  * The interface 
32850 74 6f 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74  to the virtual-t
32860 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 69  able mechanism i
32870 73 20 63 75 72 72 65 6e 74 6c 79 20 63 6f 6e 73  s currently cons
32880 69 64 65 72 65 64 0a 2a 2a 20 74 6f 20 62 65 20  idered.** to be 
32890 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 54  experimental.  T
328a0 68 65 20 69 6e 74 65 72 66 61 63 65 20 6d 69 67  he interface mig
328b0 68 74 20 63 68 61 6e 67 65 20 69 6e 20 69 6e 63  ht change in inc
328c0 6f 6d 70 61 74 69 62 6c 65 20 77 61 79 73 2e 0a  ompatible ways..
328d0 2a 2a 20 49 66 20 74 68 69 73 20 69 73 20 61 20  ** If this is a 
328e0 70 72 6f 62 6c 65 6d 20 66 6f 72 20 79 6f 75 2c  problem for you,
328f0 20 64 6f 20 6e 6f 74 20 75 73 65 20 74 68 65 20   do not use the 
32900 69 6e 74 65 72 66 61 63 65 20 61 74 20 74 68 69  interface at thi
32910 73 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57 68  s time..**.** Wh
32920 65 6e 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74  en the virtual-t
32930 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 73  able mechanism s
32940 74 61 62 6c 69 7a 65 73 2c 20 77 65 20 77 69 6c  tablizes, we wil
32950 6c 20 64 65 63 6c 61 72 65 20 74 68 65 0a 2a 2a  l declare the.**
32960 20 69 6e 74 65 72 66 61 63 65 20 66 69 78 65 64   interface fixed
32970 2c 20 73 75 70 70 6f 72 74 20 69 74 20 69 6e 64  , support it ind
32980 65 66 69 6e 69 74 65 6c 79 2c 20 61 6e 64 20 72  efinitely, and r
32990 65 6d 6f 76 65 20 74 68 69 73 20 63 6f 6d 6d 65  emove this comme
329a0 6e 74 2e 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 53 74  nt..*/../*.** St
329b0 72 75 63 74 75 72 65 73 20 75 73 65 64 20 62 79  ructures used by
329c0 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62   the virtual tab
329d0 6c 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2f 0a  le interface.*/.
329e0 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
329f0 71 6c 69 74 65 33 5f 76 74 61 62 20 73 71 6c 69  qlite3_vtab sqli
32a00 74 65 33 5f 76 74 61 62 3b 0a 74 79 70 65 64 65  te3_vtab;.typede
32a10 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
32a20 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73 71 6c 69  _index_info sqli
32a30 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 3b 0a  te3_index_info;.
32a40 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
32a50 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
32a60 6f 72 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  or sqlite3_vtab_
32a70 63 75 72 73 6f 72 3b 0a 74 79 70 65 64 65 66 20  cursor;.typedef 
32a80 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d  struct sqlite3_m
32a90 6f 64 75 6c 65 20 73 71 6c 69 74 65 33 5f 6d 6f  odule sqlite3_mo
32aa0 64 75 6c 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  dule;../*.** CAP
32ab0 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54  I3REF: Virtual T
32ac0 61 62 6c 65 20 4f 62 6a 65 63 74 20 7b 46 31 38  able Object {F18
32ad0 30 30 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  000}.** KEYWORDS
32ae0 3a 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65  : sqlite3_module
32af0 0a 2a 2a 0a 2a 2a 20 41 20 6d 6f 64 75 6c 65 20  .**.** A module 
32b00 69 73 20 61 20 63 6c 61 73 73 20 6f 66 20 76 69  is a class of vi
32b10 72 74 75 61 6c 20 74 61 62 6c 65 73 2e 20 20 45  rtual tables.  E
32b20 61 63 68 20 6d 6f 64 75 6c 65 20 69 73 20 64 65  ach module is de
32b30 66 69 6e 65 64 0a 2a 2a 20 62 79 20 61 6e 20 69  fined.** by an i
32b40 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 66  nstance of the f
32b50 6f 6c 6c 6f 77 69 6e 67 20 73 74 72 75 63 74 75  ollowing structu
32b60 72 65 2e 20 20 54 68 69 73 20 73 74 72 75 63 74  re.  This struct
32b70 75 72 65 20 63 6f 6e 73 69 73 74 73 0a 2a 2a 20  ure consists.** 
32b80 6d 6f 73 74 6c 79 20 6f 66 20 6d 65 74 68 6f 64  mostly of method
32b90 73 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65  s for the module
32ba0 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69  ..*/.struct sqli
32bb0 74 65 33 5f 6d 6f 64 75 6c 65 20 7b 0a 20 20 69  te3_module {.  i
32bc0 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69  nt iVersion;.  i
32bd0 6e 74 20 28 2a 78 43 72 65 61 74 65 29 28 73 71  nt (*xCreate)(sq
32be0 6c 69 74 65 33 2a 2c 20 76 6f 69 64 20 2a 70 41  lite3*, void *pA
32bf0 75 78 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  ux,.            
32c00 20 20 20 69 6e 74 20 61 72 67 63 2c 20 63 6f 6e     int argc, con
32c10 73 74 20 63 68 61 72 20 2a 63 6f 6e 73 74 2a 61  st char *const*a
32c20 72 67 76 2c 0a 20 20 20 20 20 20 20 20 20 20 20  rgv,.           
32c30 20 20 20 20 73 71 6c 69 74 65 33 5f 76 74 61 62      sqlite3_vtab
32c40 20 2a 2a 70 70 56 54 61 62 2c 20 63 68 61 72 2a   **ppVTab, char*
32c50 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6e  *);.  int (*xCon
32c60 6e 65 63 74 29 28 73 71 6c 69 74 65 33 2a 2c 20  nect)(sqlite3*, 
32c70 76 6f 69 64 20 2a 70 41 75 78 2c 0a 20 20 20 20  void *pAux,.    
32c80 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 61             int a
32c90 72 67 63 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  rgc, const char 
32ca0 2a 63 6f 6e 73 74 2a 61 72 67 76 2c 0a 20 20 20  *const*argv,.   
32cb0 20 20 20 20 20 20 20 20 20 20 20 20 73 71 6c 69              sqli
32cc0 74 65 33 5f 76 74 61 62 20 2a 2a 70 70 56 54 61  te3_vtab **ppVTa
32cd0 62 2c 20 63 68 61 72 2a 2a 29 3b 0a 20 20 69 6e  b, char**);.  in
32ce0 74 20 28 2a 78 42 65 73 74 49 6e 64 65 78 29 28  t (*xBestIndex)(
32cf0 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56  sqlite3_vtab *pV
32d00 54 61 62 2c 20 73 71 6c 69 74 65 33 5f 69 6e 64  Tab, sqlite3_ind
32d10 65 78 5f 69 6e 66 6f 2a 29 3b 0a 20 20 69 6e 74  ex_info*);.  int
32d20 20 28 2a 78 44 69 73 63 6f 6e 6e 65 63 74 29 28   (*xDisconnect)(
32d30 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56  sqlite3_vtab *pV
32d40 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44  Tab);.  int (*xD
32d50 65 73 74 72 6f 79 29 28 73 71 6c 69 74 65 33 5f  estroy)(sqlite3_
32d60 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20  vtab *pVTab);.  
32d70 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c  int (*xOpen)(sql
32d80 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62  ite3_vtab *pVTab
32d90 2c 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63  , sqlite3_vtab_c
32da0 75 72 73 6f 72 20 2a 2a 70 70 43 75 72 73 6f 72  ursor **ppCursor
32db0 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73  );.  int (*xClos
32dc0 65 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  e)(sqlite3_vtab_
32dd0 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20  cursor*);.  int 
32de0 28 2a 78 46 69 6c 74 65 72 29 28 73 71 6c 69 74  (*xFilter)(sqlit
32df0 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c  e3_vtab_cursor*,
32e00 20 69 6e 74 20 69 64 78 4e 75 6d 2c 20 63 6f 6e   int idxNum, con
32e10 73 74 20 63 68 61 72 20 2a 69 64 78 53 74 72 2c  st char *idxStr,
32e20 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
32e30 20 69 6e 74 20 61 72 67 63 2c 20 73 71 6c 69 74   int argc, sqlit
32e40 65 33 5f 76 61 6c 75 65 20 2a 2a 61 72 67 76 29  e3_value **argv)
32e50 3b 0a 20 20 69 6e 74 20 28 2a 78 4e 65 78 74 29  ;.  int (*xNext)
32e60 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75  (sqlite3_vtab_cu
32e70 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  rsor*);.  int (*
32e80 78 45 6f 66 29 28 73 71 6c 69 74 65 33 5f 76 74  xEof)(sqlite3_vt
32e90 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69  ab_cursor*);.  i
32ea0 6e 74 20 28 2a 78 43 6f 6c 75 6d 6e 29 28 73 71  nt (*xColumn)(sq
32eb0 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f  lite3_vtab_curso
32ec0 72 2a 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  r*, sqlite3_cont
32ed0 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e  ext*, int);.  in
32ee0 74 20 28 2a 78 52 6f 77 69 64 29 28 73 71 6c 69  t (*xRowid)(sqli
32ef0 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a  te3_vtab_cursor*
32f00 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
32f10 2a 70 52 6f 77 69 64 29 3b 0a 20 20 69 6e 74 20  *pRowid);.  int 
32f20 28 2a 78 55 70 64 61 74 65 29 28 73 71 6c 69 74  (*xUpdate)(sqlit
32f30 65 33 5f 76 74 61 62 20 2a 2c 20 69 6e 74 2c 20  e3_vtab *, int, 
32f40 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 2a  sqlite3_value **
32f50 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
32f60 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 42 65 67  *);.  int (*xBeg
32f70 69 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  in)(sqlite3_vtab
32f80 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20   *pVTab);.  int 
32f90 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33  (*xSync)(sqlite3
32fa0 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20  _vtab *pVTab);. 
32fb0 20 69 6e 74 20 28 2a 78 43 6f 6d 6d 69 74 29 28   int (*xCommit)(
32fc0 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56  sqlite3_vtab *pV
32fd0 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52  Tab);.  int (*xR
32fe0 6f 6c 6c 62 61 63 6b 29 28 73 71 6c 69 74 65 33  ollback)(sqlite3
32ff0 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20  _vtab *pVTab);. 
33000 20 69 6e 74 20 28 2a 78 46 69 6e 64 46 75 6e 63   int (*xFindFunc
33010 74 69 6f 6e 29 28 73 71 6c 69 74 65 33 5f 76 74  tion)(sqlite3_vt
33020 61 62 20 2a 70 56 74 61 62 2c 20 69 6e 74 20 6e  ab *pVtab, int n
33030 41 72 67 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  Arg, const char 
33040 2a 7a 4e 61 6d 65 2c 0a 20 20 20 20 20 20 20 20  *zName,.        
33050 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76                 v
33060 6f 69 64 20 28 2a 2a 70 78 46 75 6e 63 29 28 73  oid (**pxFunc)(s
33070 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
33080 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
33090 65 2a 2a 29 2c 0a 20 20 20 20 20 20 20 20 20 20  e**),.          
330a0 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69               voi
330b0 64 20 2a 2a 70 70 41 72 67 29 3b 0a 0a 20 20 69  d **ppArg);..  i
330c0 6e 74 20 28 2a 78 52 65 6e 61 6d 65 29 28 73 71  nt (*xRename)(sq
330d0 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74 61  lite3_vtab *pVta
330e0 62 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  b, const char *z
330f0 4e 65 77 29 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  New);.};../*.** 
33100 43 41 50 49 33 52 45 46 3a 20 56 69 72 74 75 61  CAPI3REF: Virtua
33110 6c 20 54 61 62 6c 65 20 49 6e 64 65 78 69 6e 67  l Table Indexing
33120 20 49 6e 66 6f 72 6d 61 74 69 6f 6e 20 7b 46 31   Information {F1
33130 38 31 30 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  8100}.** KEYWORD
33140 53 3a 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78  S: sqlite3_index
33150 5f 69 6e 66 6f 0a 2a 2a 0a 2a 2a 20 54 68 65 20  _info.**.** The 
33160 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e  sqlite3_index_in
33170 66 6f 20 73 74 72 75 63 74 75 72 65 20 61 6e 64  fo structure and
33180 20 69 74 73 20 73 75 62 73 74 72 75 63 74 75 72   its substructur
33190 65 73 20 69 73 20 75 73 65 64 20 74 6f 0a 2a 2a  es is used to.**
331a0 20 70 61 73 73 20 69 6e 66 6f 72 6d 61 74 69 6f   pass informatio
331b0 6e 20 69 6e 74 6f 20 61 6e 64 20 72 65 63 65 69  n into and recei
331c0 76 65 20 74 68 65 20 72 65 70 6c 79 20 66 72 6f  ve the reply fro
331d0 6d 20 74 68 65 20 78 42 65 73 74 49 6e 64 65 78  m the xBestIndex
331e0 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e  .** method of an
331f0 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 2e   sqlite3_module.
33200 20 20 54 68 65 20 66 69 65 6c 64 73 20 75 6e 64    The fields und
33210 65 72 20 2a 2a 49 6e 70 75 74 73 2a 2a 20 61 72  er **Inputs** ar
33220 65 20 74 68 65 0a 2a 2a 20 69 6e 70 75 74 73 20  e the.** inputs 
33230 74 6f 20 78 42 65 73 74 49 6e 64 65 78 20 61 6e  to xBestIndex an
33240 64 20 61 72 65 20 72 65 61 64 2d 6f 6e 6c 79 2e  d are read-only.
33250 20 20 78 42 65 73 74 49 6e 64 65 78 20 69 6e 73    xBestIndex ins
33260 65 72 74 73 20 69 74 73 0a 2a 2a 20 72 65 73 75  erts its.** resu
33270 6c 74 73 20 69 6e 74 6f 20 74 68 65 20 2a 2a 4f  lts into the **O
33280 75 74 70 75 74 73 2a 2a 20 66 69 65 6c 64 73 2e  utputs** fields.
33290 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 43 6f 6e 73  .**.** The aCons
332a0 74 72 61 69 6e 74 5b 5d 20 61 72 72 61 79 20 72  traint[] array r
332b0 65 63 6f 72 64 73 20 57 48 45 52 45 20 63 6c 61  ecords WHERE cla
332c0 75 73 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20  use constraints 
332d0 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 3a 0a  of the.** form:.
332e0 2a 2a 0a 2a 2a 20 20 20 20 20 20 20 20 20 63 6f  **.**         co
332f0 6c 75 6d 6e 20 4f 50 20 65 78 70 72 0a 2a 2a 0a  lumn OP expr.**.
33300 2a 2a 20 57 68 65 72 65 20 4f 50 20 69 73 20 3d  ** Where OP is =
33310 2c 20 26 6c 74 3b 2c 20 26 6c 74 3b 3d 2c 20 26  , &lt;, &lt;=, &
33320 67 74 3b 2c 20 6f 72 20 26 67 74 3b 3d 2e 20 20  gt;, or &gt;=.  
33330 0a 2a 2a 20 54 68 65 20 70 61 72 74 69 63 75 6c  .** The particul
33340 61 72 20 6f 70 65 72 61 74 6f 72 20 69 73 20 73  ar operator is s
33350 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 43 6f 6e  tored.** in aCon
33360 73 74 72 61 69 6e 74 5b 5d 2e 6f 70 2e 20 20 54  straint[].op.  T
33370 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20  he index of the 
33380 63 6f 6c 75 6d 6e 20 69 73 20 73 74 6f 72 65 64  column is stored
33390 20 69 6e 20 0a 2a 2a 20 61 43 6f 6e 73 74 72 61   in .** aConstra
333a0 69 6e 74 5b 5d 2e 69 43 6f 6c 75 6d 6e 2e 20 20  int[].iColumn.  
333b0 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 75 73  aConstraint[].us
333c0 61 62 6c 65 20 69 73 20 54 52 55 45 20 69 66 20  able is TRUE if 
333d0 74 68 65 0a 2a 2a 20 65 78 70 72 20 6f 6e 20 74  the.** expr on t
333e0 68 65 20 72 69 67 68 74 2d 68 61 6e 64 20 73 69  he right-hand si
333f0 64 65 20 63 61 6e 20 62 65 20 65 76 61 6c 75 61  de can be evalua
33400 74 65 64 20 28 61 6e 64 20 74 68 75 73 20 74 68  ted (and thus th
33410 65 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20  e constraint.** 
33420 69 73 20 75 73 61 62 6c 65 29 20 61 6e 64 20 66  is usable) and f
33430 61 6c 73 65 20 69 66 20 69 74 20 63 61 6e 6e 6f  alse if it canno
33440 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 70 74  t..**.** The opt
33450 69 6d 69 7a 65 72 20 61 75 74 6f 6d 61 74 69 63  imizer automatic
33460 61 6c 6c 79 20 69 6e 76 65 72 74 73 20 74 65 72  ally inverts ter
33470 6d 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22  ms of the form "
33480 65 78 70 72 20 4f 50 20 63 6f 6c 75 6d 6e 22 0a  expr OP column".
33490 2a 2a 20 61 6e 64 20 6d 61 6b 65 73 20 6f 74 68  ** and makes oth
334a0 65 72 20 73 69 6d 70 6c 69 66 69 63 61 74 69 6f  er simplificatio
334b0 6e 73 20 74 6f 20 74 68 65 20 57 48 45 52 45 20  ns to the WHERE 
334c0 63 6c 61 75 73 65 20 69 6e 20 61 6e 20 61 74 74  clause in an att
334d0 65 6d 70 74 20 74 6f 0a 2a 2a 20 67 65 74 20 61  empt to.** get a
334e0 73 20 6d 61 6e 79 20 57 48 45 52 45 20 63 6c 61  s many WHERE cla
334f0 75 73 65 20 74 65 72 6d 73 20 69 6e 74 6f 20 74  use terms into t
33500 68 65 20 66 6f 72 6d 20 73 68 6f 77 6e 20 61 62  he form shown ab
33510 6f 76 65 20 61 73 20 70 6f 73 73 69 62 6c 65 2e  ove as possible.
33520 0a 2a 2a 20 54 68 65 20 61 43 6f 6e 73 74 72 61  .** The aConstra
33530 69 6e 74 5b 5d 20 61 72 72 61 79 20 6f 6e 6c 79  int[] array only
33540 20 72 65 70 6f 72 74 73 20 57 48 45 52 45 20 63   reports WHERE c
33550 6c 61 75 73 65 20 74 65 72 6d 73 20 69 6e 20 74  lause terms in t
33560 68 65 20 63 6f 72 72 65 63 74 0a 2a 2a 20 66 6f  he correct.** fo
33570 72 6d 20 74 68 61 74 20 72 65 66 65 72 20 74 6f  rm that refer to
33580 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20   the particular 
33590 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 62 65  virtual table be
335a0 69 6e 67 20 71 75 65 72 69 65 64 2e 0a 2a 2a 0a  ing queried..**.
335b0 2a 2a 20 49 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  ** Information a
335c0 62 6f 75 74 20 74 68 65 20 4f 52 44 45 52 20 42  bout the ORDER B
335d0 59 20 63 6c 61 75 73 65 20 69 73 20 73 74 6f 72  Y clause is stor
335e0 65 64 20 69 6e 20 61 4f 72 64 65 72 42 79 5b 5d  ed in aOrderBy[]
335f0 2e 0a 2a 2a 20 45 61 63 68 20 74 65 72 6d 20 6f  ..** Each term o
33600 66 20 61 4f 72 64 65 72 42 79 20 72 65 63 6f 72  f aOrderBy recor
33610 64 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  ds a column of t
33620 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75  he ORDER BY clau
33630 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 42  se..**.** The xB
33640 65 73 74 49 6e 64 65 78 20 6d 65 74 68 6f 64 20  estIndex method 
33650 6d 75 73 74 20 66 69 6c 6c 20 61 43 6f 6e 73 74  must fill aConst
33660 72 61 69 6e 74 55 73 61 67 65 5b 5d 20 77 69 74  raintUsage[] wit
33670 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a  h information.**
33680 20 61 62 6f 75 74 20 77 68 61 74 20 70 61 72 61   about what para
33690 6d 65 74 65 72 73 20 74 6f 20 70 61 73 73 20 74  meters to pass t
336a0 6f 20 78 46 69 6c 74 65 72 2e 20 20 49 66 20 61  o xFilter.  If a
336b0 72 67 76 49 6e 64 65 78 3e 30 20 74 68 65 6e 0a  rgvIndex>0 then.
336c0 2a 2a 20 74 68 65 20 72 69 67 68 74 2d 68 61 6e  ** the right-han
336d0 64 20 73 69 64 65 20 6f 66 20 74 68 65 20 63 6f  d side of the co
336e0 72 72 65 73 70 6f 6e 64 69 6e 67 20 61 43 6f 6e  rresponding aCon
336f0 73 74 72 61 69 6e 74 5b 5d 20 69 73 20 65 76 61  straint[] is eva
33700 6c 75 61 74 65 64 0a 2a 2a 20 61 6e 64 20 62 65  luated.** and be
33710 63 6f 6d 65 73 20 74 68 65 20 61 72 67 76 49 6e  comes the argvIn
33720 64 65 78 2d 74 68 20 65 6e 74 72 79 20 69 6e 20  dex-th entry in 
33730 61 72 67 76 2e 20 20 49 66 20 61 43 6f 6e 73 74  argv.  If aConst
33740 72 61 69 6e 74 55 73 61 67 65 5b 5d 2e 6f 6d 69  raintUsage[].omi
33750 74 0a 2a 2a 20 69 73 20 74 72 75 65 2c 20 74 68  t.** is true, th
33760 65 6e 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e  en the constrain
33770 74 20 69 73 20 61 73 73 75 6d 65 64 20 74 6f 20  t is assumed to 
33780 62 65 20 66 75 6c 6c 79 20 68 61 6e 64 6c 65 64  be fully handled
33790 20 62 79 20 74 68 65 0a 2a 2a 20 76 69 72 74 75   by the.** virtu
337a0 61 6c 20 74 61 62 6c 65 20 61 6e 64 20 69 73 20  al table and is 
337b0 6e 6f 74 20 63 68 65 63 6b 65 64 20 61 67 61 69  not checked agai
337c0 6e 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a  n by SQLite..**.
337d0 2a 2a 20 54 68 65 20 69 64 78 4e 75 6d 20 61 6e  ** The idxNum an
337e0 64 20 69 64 78 50 74 72 20 76 61 6c 75 65 73 20  d idxPtr values 
337f0 61 72 65 20 72 65 63 6f 72 64 65 64 20 61 6e 64  are recorded and
33800 20 70 61 73 73 65 64 20 69 6e 74 6f 20 78 46 69   passed into xFi
33810 6c 74 65 72 2e 0a 2a 2a 20 73 71 6c 69 74 65 33  lter..** sqlite3
33820 5f 66 72 65 65 28 29 20 69 73 20 75 73 65 64 20  _free() is used 
33830 74 6f 20 66 72 65 65 20 69 64 78 50 74 72 20 69  to free idxPtr i
33840 66 20 6e 65 65 64 54 6f 46 72 65 65 49 64 78 50  f needToFreeIdxP
33850 74 72 20 69 73 20 74 72 75 65 2e 0a 2a 2a 0a 2a  tr is true..**.*
33860 2a 20 54 68 65 20 6f 72 64 65 72 42 79 43 6f 6e  * The orderByCon
33870 73 75 6d 65 64 20 6d 65 61 6e 73 20 74 68 61 74  sumed means that
33880 20 6f 75 74 70 75 74 20 66 72 6f 6d 20 78 46 69   output from xFi
33890 6c 74 65 72 20 77 69 6c 6c 20 6f 63 63 75 72 20  lter will occur 
338a0 69 6e 0a 2a 2a 20 74 68 65 20 63 6f 72 72 65 63  in.** the correc
338b0 74 20 6f 72 64 65 72 20 74 6f 20 73 61 74 69 73  t order to satis
338c0 66 79 20 74 68 65 20 4f 52 44 45 52 20 42 59 20  fy the ORDER BY 
338d0 63 6c 61 75 73 65 20 73 6f 20 74 68 61 74 20 6e  clause so that n
338e0 6f 20 73 65 70 61 72 61 74 65 0a 2a 2a 20 73 6f  o separate.** so
338f0 72 74 69 6e 67 20 73 74 65 70 20 69 73 20 72 65  rting step is re
33900 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  quired..**.** Th
33910 65 20 65 73 74 69 6d 61 74 65 64 43 6f 73 74 20  e estimatedCost 
33920 76 61 6c 75 65 20 69 73 20 61 6e 20 65 73 74 69  value is an esti
33930 6d 61 74 65 20 6f 66 20 74 68 65 20 63 6f 73 74  mate of the cost
33940 20 6f 66 20 64 6f 69 6e 67 20 74 68 65 0a 2a 2a   of doing the.**
33950 20 70 61 72 74 69 63 75 6c 61 72 20 6c 6f 6f 6b   particular look
33960 75 70 2e 20 20 41 20 66 75 6c 6c 20 73 63 61 6e  up.  A full scan
33970 20 6f 66 20 61 20 74 61 62 6c 65 20 77 69 74 68   of a table with
33980 20 4e 20 65 6e 74 72 69 65 73 20 73 68 6f 75 6c   N entries shoul
33990 64 20 68 61 76 65 0a 2a 2a 20 61 20 63 6f 73 74  d have.** a cost
339a0 20 6f 66 20 4e 2e 20 20 41 20 62 69 6e 61 72 79   of N.  A binary
339b0 20 73 65 61 72 63 68 20 6f 66 20 61 20 74 61 62   search of a tab
339c0 6c 65 20 6f 66 20 4e 20 65 6e 74 72 69 65 73 20  le of N entries 
339d0 73 68 6f 75 6c 64 20 68 61 76 65 20 61 0a 2a 2a  should have a.**
339e0 20 63 6f 73 74 20 6f 66 20 61 70 70 72 6f 78 69   cost of approxi
339f0 6d 61 74 65 6c 79 20 6c 6f 67 28 4e 29 2e 0a 2a  mately log(N)..*
33a00 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  /.struct sqlite3
33a10 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 7b 0a 20 20  _index_info {.  
33a20 2f 2a 20 49 6e 70 75 74 73 20 2a 2f 0a 20 20 69  /* Inputs */.  i
33a30 6e 74 20 6e 43 6f 6e 73 74 72 61 69 6e 74 3b 20  nt nConstraint; 
33a40 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d            /* Num
33a50 62 65 72 20 6f 66 20 65 6e 74 72 69 65 73 20 69  ber of entries i
33a60 6e 20 61 43 6f 6e 73 74 72 61 69 6e 74 20 2a 2f  n aConstraint */
33a70 0a 20 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  .  struct sqlite
33a80 33 5f 69 6e 64 65 78 5f 63 6f 6e 73 74 72 61 69  3_index_constrai
33a90 6e 74 20 7b 0a 20 20 20 20 20 69 6e 74 20 69 43  nt {.     int iC
33aa0 6f 6c 75 6d 6e 3b 20 20 20 20 20 20 20 20 20 20  olumn;          
33ab0 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6f 6e      /* Column on
33ac0 20 6c 65 66 74 2d 68 61 6e 64 20 73 69 64 65 20   left-hand side 
33ad0 6f 66 20 63 6f 6e 73 74 72 61 69 6e 74 20 2a 2f  of constraint */
33ae0 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63  .     unsigned c
33af0 68 61 72 20 6f 70 3b 20 20 20 20 20 20 20 20 20  har op;         
33b00 2f 2a 20 43 6f 6e 73 74 72 61 69 6e 74 20 6f 70  /* Constraint op
33b10 65 72 61 74 6f 72 20 2a 2f 0a 20 20 20 20 20 75  erator */.     u
33b20 6e 73 69 67 6e 65 64 20 63 68 61 72 20 75 73 61  nsigned char usa
33b30 62 6c 65 3b 20 20 20 20 20 2f 2a 20 54 72 75 65  ble;     /* True
33b40 20 69 66 20 74 68 69 73 20 63 6f 6e 73 74 72 61   if this constra
33b50 69 6e 74 20 69 73 20 75 73 61 62 6c 65 20 2a 2f  int is usable */
33b60 0a 20 20 20 20 20 69 6e 74 20 69 54 65 72 6d 4f  .     int iTermO
33b70 66 66 73 65 74 3b 20 20 20 20 20 20 20 20 20 20  ffset;          
33b80 2f 2a 20 55 73 65 64 20 69 6e 74 65 72 6e 61 6c  /* Used internal
33b90 6c 79 20 2d 20 78 42 65 73 74 49 6e 64 65 78 20  ly - xBestIndex 
33ba0 73 68 6f 75 6c 64 20 69 67 6e 6f 72 65 20 2a 2f  should ignore */
33bb0 0a 20 20 7d 20 2a 61 43 6f 6e 73 74 72 61 69 6e  .  } *aConstrain
33bc0 74 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  t;            /*
33bd0 20 54 61 62 6c 65 20 6f 66 20 57 48 45 52 45 20   Table of WHERE 
33be0 63 6c 61 75 73 65 20 63 6f 6e 73 74 72 61 69 6e  clause constrain
33bf0 74 73 20 2a 2f 0a 20 20 69 6e 74 20 6e 4f 72 64  ts */.  int nOrd
33c00 65 72 42 79 3b 20 20 20 20 20 20 20 20 20 20 20  erBy;           
33c10 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20     /* Number of 
33c20 74 65 72 6d 73 20 69 6e 20 74 68 65 20 4f 52 44  terms in the ORD
33c30 45 52 20 42 59 20 63 6c 61 75 73 65 20 2a 2f 0a  ER BY clause */.
33c40 20 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33    struct sqlite3
33c50 5f 69 6e 64 65 78 5f 6f 72 64 65 72 62 79 20 7b  _index_orderby {
33c60 0a 20 20 20 20 20 69 6e 74 20 69 43 6f 6c 75 6d  .     int iColum
33c70 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  n;              
33c80 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72  /* Column number
33c90 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e 65   */.     unsigne
33ca0 64 20 63 68 61 72 20 64 65 73 63 3b 20 20 20 20  d char desc;    
33cb0 20 20 20 2f 2a 20 54 72 75 65 20 66 6f 72 20 44     /* True for D
33cc0 45 53 43 2e 20 20 46 61 6c 73 65 20 66 6f 72 20  ESC.  False for 
33cd0 41 53 43 2e 20 2a 2f 0a 20 20 7d 20 2a 61 4f 72  ASC. */.  } *aOr
33ce0 64 65 72 42 79 3b 20 20 20 20 20 20 20 20 20 20  derBy;          
33cf0 20 20 20 20 20 2f 2a 20 54 68 65 20 4f 52 44 45       /* The ORDE
33d00 52 20 42 59 20 63 6c 61 75 73 65 20 2a 2f 0a 0a  R BY clause */..
33d10 20 20 2f 2a 20 4f 75 74 70 75 74 73 20 2a 2f 0a    /* Outputs */.
33d20 20 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33    struct sqlite3
33d30 5f 69 6e 64 65 78 5f 63 6f 6e 73 74 72 61 69 6e  _index_constrain
33d40 74 5f 75 73 61 67 65 20 7b 0a 20 20 20 20 69 6e  t_usage {.    in
33d50 74 20 61 72 67 76 49 6e 64 65 78 3b 20 20 20 20  t argvIndex;    
33d60 20 20 20 20 20 20 20 2f 2a 20 69 66 20 3e 30 2c         /* if >0,
33d70 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 70   constraint is p
33d80 61 72 74 20 6f 66 20 61 72 67 76 20 74 6f 20 78  art of argv to x
33d90 46 69 6c 74 65 72 20 2a 2f 0a 20 20 20 20 75 6e  Filter */.    un
33da0 73 69 67 6e 65 64 20 63 68 61 72 20 6f 6d 69 74  signed char omit
33db0 3b 20 20 20 20 20 20 2f 2a 20 44 6f 20 6e 6f 74  ;      /* Do not
33dc0 20 63 6f 64 65 20 61 20 74 65 73 74 20 66 6f 72   code a test for
33dd0 20 74 68 69 73 20 63 6f 6e 73 74 72 61 69 6e 74   this constraint
33de0 20 2a 2f 0a 20 20 7d 20 2a 61 43 6f 6e 73 74 72   */.  } *aConstr
33df0 61 69 6e 74 55 73 61 67 65 3b 0a 20 20 69 6e 74  aintUsage;.  int
33e00 20 69 64 78 4e 75 6d 3b 20 20 20 20 20 20 20 20   idxNum;        
33e10 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65          /* Numbe
33e20 72 20 75 73 65 64 20 74 6f 20 69 64 65 6e 74 69  r used to identi
33e30 66 79 20 74 68 65 20 69 6e 64 65 78 20 2a 2f 0a  fy the index */.
33e40 20 20 63 68 61 72 20 2a 69 64 78 53 74 72 3b 20    char *idxStr; 
33e50 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
33e60 53 74 72 69 6e 67 2c 20 70 6f 73 73 69 62 6c 79  String, possibly
33e70 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73   obtained from s
33e80 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 20 2a 2f  qlite3_malloc */
33e90 0a 20 20 69 6e 74 20 6e 65 65 64 54 6f 46 72 65  .  int needToFre
33ea0 65 49 64 78 53 74 72 3b 20 20 20 20 20 20 2f 2a  eIdxStr;      /*
33eb0 20 46 72 65 65 20 69 64 78 53 74 72 20 75 73 69   Free idxStr usi
33ec0 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  ng sqlite3_free(
33ed0 29 20 69 66 20 74 72 75 65 20 2a 2f 0a 20 20 69  ) if true */.  i
33ee0 6e 74 20 6f 72 64 65 72 42 79 43 6f 6e 73 75 6d  nt orderByConsum
33ef0 65 64 3b 20 20 20 20 20 20 20 2f 2a 20 54 72 75  ed;       /* Tru
33f00 65 20 69 66 20 6f 75 74 70 75 74 20 69 73 20 61  e if output is a
33f10 6c 72 65 61 64 79 20 6f 72 64 65 72 65 64 20 2a  lready ordered *
33f20 2f 0a 20 20 64 6f 75 62 6c 65 20 65 73 74 69 6d  /.  double estim
33f30 61 74 65 64 43 6f 73 74 3b 20 20 20 20 20 20 2f  atedCost;      /
33f40 2a 20 45 73 74 69 6d 61 74 65 64 20 63 6f 73 74  * Estimated cost
33f50 20 6f 66 20 75 73 69 6e 67 20 74 68 69 73 20 69   of using this i
33f60 6e 64 65 78 20 2a 2f 0a 7d 3b 0a 23 64 65 66 69  ndex */.};.#defi
33f70 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f  ne SQLITE_INDEX_
33f80 43 4f 4e 53 54 52 41 49 4e 54 5f 45 51 20 20 20  CONSTRAINT_EQ   
33f90 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
33fa0 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49  E_INDEX_CONSTRAI
33fb0 4e 54 5f 47 54 20 20 20 20 34 0a 23 64 65 66 69  NT_GT    4.#defi
33fc0 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f  ne SQLITE_INDEX_
33fd0 43 4f 4e 53 54 52 41 49 4e 54 5f 4c 45 20 20 20  CONSTRAINT_LE   
33fe0 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   8.#define SQLIT
33ff0 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49  E_INDEX_CONSTRAI
34000 4e 54 5f 4c 54 20 20 20 20 31 36 0a 23 64 65 66  NT_LT    16.#def
34010 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58  ine SQLITE_INDEX
34020 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 47 45 20 20  _CONSTRAINT_GE  
34030 20 20 33 32 0a 23 64 65 66 69 6e 65 20 53 51 4c    32.#define SQL
34040 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52  ITE_INDEX_CONSTR
34050 41 49 4e 54 5f 4d 41 54 43 48 20 36 34 0a 0a 2f  AINT_MATCH 64../
34060 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
34070 65 67 69 73 74 65 72 20 41 20 56 69 72 74 75 61  egister A Virtua
34080 6c 20 54 61 62 6c 65 20 49 6d 70 6c 65 6d 65 6e  l Table Implemen
34090 74 61 74 69 6f 6e 20 7b 46 31 38 32 30 30 7d 0a  tation {F18200}.
340a0 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
340b0 6e 65 20 69 73 20 75 73 65 64 20 74 6f 20 72 65  ne is used to re
340c0 67 69 73 74 65 72 20 61 20 6e 65 77 20 6d 6f 64  gister a new mod
340d0 75 6c 65 20 6e 61 6d 65 20 77 69 74 68 20 61 6e  ule name with an
340e0 20 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 6e 6e 65   SQLite.** conne
340f0 63 74 69 6f 6e 2e 20 20 4d 6f 64 75 6c 65 20 6e  ction.  Module n
34100 61 6d 65 73 20 6d 75 73 74 20 62 65 20 72 65 67  ames must be reg
34110 69 73 74 65 72 65 64 20 62 65 66 6f 72 65 20 63  istered before c
34120 72 65 61 74 69 6e 67 20 6e 65 77 0a 2a 2a 20 76  reating new.** v
34130 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 6f 6e  irtual tables on
34140 20 74 68 65 20 6d 6f 64 75 6c 65 2c 20 6f 72 20   the module, or 
34150 62 65 66 6f 72 65 20 75 73 69 6e 67 20 70 72 65  before using pre
34160 65 78 69 73 74 69 6e 67 20 76 69 72 74 75 61 6c  existing virtual
34170 0a 2a 2a 20 74 61 62 6c 65 73 20 6f 66 20 74 68  .** tables of th
34180 65 20 6d 6f 64 75 6c 65 2e 0a 2a 2f 0a 69 6e 74  e module..*/.int
34190 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
341a0 6d 6f 64 75 6c 65 28 0a 20 20 73 71 6c 69 74 65  module(.  sqlite
341b0 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
341c0 20 20 20 20 20 2f 2a 20 53 51 4c 69 74 65 20 63       /* SQLite c
341d0 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 72 65 67  onnection to reg
341e0 69 73 74 65 72 20 6d 6f 64 75 6c 65 20 77 69 74  ister module wit
341f0 68 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  h */.  const cha
34200 72 20 2a 7a 4e 61 6d 65 2c 20 20 20 20 20 20 20  r *zName,       
34210 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65    /* Name of the
34220 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 63 6f 6e   module */.  con
34230 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c  st sqlite3_modul
34240 65 20 2a 2c 20 20 20 20 2f 2a 20 4d 65 74 68 6f  e *,    /* Metho
34250 64 73 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c  ds for the modul
34260 65 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 20 20 20  e */.  void *   
34270 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
34280 20 20 2f 2a 20 43 6c 69 65 6e 74 20 64 61 74 61    /* Client data
34290 20 66 6f 72 20 78 43 72 65 61 74 65 2f 78 43 6f   for xCreate/xCo
342a0 6e 6e 65 63 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a  nnect */.);../*.
342b0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 67  ** CAPI3REF: Reg
342c0 69 73 74 65 72 20 41 20 56 69 72 74 75 61 6c 20  ister A Virtual 
342d0 54 61 62 6c 65 20 49 6d 70 6c 65 6d 65 6e 74 61  Table Implementa
342e0 74 69 6f 6e 20 7b 46 31 38 32 31 30 7d 0a 2a 2a  tion {F18210}.**
342f0 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
34300 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f   is identical to
34310 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65   the sqlite3_cre
34320 61 74 65 5f 6d 6f 64 75 6c 65 28 29 20 6d 65 74  ate_module() met
34330 68 6f 64 20 61 62 6f 76 65 2c 0a 2a 2a 20 65 78  hod above,.** ex
34340 63 65 70 74 20 74 68 61 74 20 69 74 20 61 6c 6c  cept that it all
34350 6f 77 73 20 61 20 64 65 73 74 72 75 63 74 6f 72  ows a destructor
34360 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
34370 73 70 65 63 69 66 69 65 64 2e 20 49 74 20 69 73  specified. It is
34380 0a 2a 2a 20 65 76 65 6e 20 6d 6f 72 65 20 65 78  .** even more ex
34390 70 65 72 69 6d 65 6e 74 61 6c 20 74 68 61 6e 20  perimental than 
343a0 74 68 65 20 72 65 73 74 20 6f 66 20 74 68 65 20  the rest of the 
343b0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 41  virtual tables A
343c0 50 49 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  PI..*/.int sqlit
343d0 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65  e3_create_module
343e0 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v2(.  sqlite3 *
343f0 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  db,             
34400 20 20 2f 2a 20 53 51 4c 69 74 65 20 63 6f 6e 6e    /* SQLite conn
34410 65 63 74 69 6f 6e 20 74 6f 20 72 65 67 69 73 74  ection to regist
34420 65 72 20 6d 6f 64 75 6c 65 20 77 69 74 68 20 2a  er module with *
34430 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
34440 7a 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 20 2f  zName,         /
34450 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 6d 6f  * Name of the mo
34460 64 75 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  dule */.  const 
34470 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 2a  sqlite3_module *
34480 2c 20 20 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20  ,    /* Methods 
34490 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a  for the module *
344a0 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20  /.  void *,     
344b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
344c0 2a 20 43 6c 69 65 6e 74 20 64 61 74 61 20 66 6f  * Client data fo
344d0 72 20 78 43 72 65 61 74 65 2f 78 43 6f 6e 6e 65  r xCreate/xConne
344e0 63 74 20 2a 2f 0a 20 20 76 6f 69 64 28 2a 78 44  ct */.  void(*xD
344f0 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 20 20  estroy)(void*)  
34500 20 20 20 2f 2a 20 4d 6f 64 75 6c 65 20 64 65 73     /* Module des
34510 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e  tructor function
34520 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.);../*.** CA
34530 50 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20  PI3REF: Virtual 
34540 54 61 62 6c 65 20 49 6e 73 74 61 6e 63 65 20 4f  Table Instance O
34550 62 6a 65 63 74 20 7b 46 31 38 30 31 30 7d 0a 2a  bject {F18010}.*
34560 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69  * KEYWORDS: sqli
34570 74 65 33 5f 76 74 61 62 0a 2a 2a 0a 2a 2a 20 45  te3_vtab.**.** E
34580 76 65 72 79 20 6d 6f 64 75 6c 65 20 69 6d 70 6c  very module impl
34590 65 6d 65 6e 74 61 74 69 6f 6e 20 75 73 65 73 20  ementation uses 
345a0 61 20 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68  a subclass of th
345b0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 72 75  e following stru
345c0 63 74 75 72 65 0a 2a 2a 20 74 6f 20 64 65 73 63  cture.** to desc
345d0 72 69 62 65 20 61 20 70 61 72 74 69 63 75 6c 61  ribe a particula
345e0 72 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  r instance of th
345f0 65 20 6d 6f 64 75 6c 65 2e 20 20 45 61 63 68 20  e module.  Each 
34600 73 75 62 63 6c 61 73 73 20 77 69 6c 6c 0a 2a 2a  subclass will.**
34610 20 62 65 20 74 61 69 6c 6f 72 65 64 20 74 6f 20   be tailored to 
34620 74 68 65 20 73 70 65 63 69 66 69 63 20 6e 65 65  the specific nee
34630 64 73 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65  ds of the module
34640 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e   implementation.
34650 20 20 20 54 68 65 0a 2a 2a 20 70 75 72 70 6f 73     The.** purpos
34660 65 20 6f 66 20 74 68 69 73 20 73 75 70 65 72 63  e of this superc
34670 6c 61 73 73 20 69 73 20 74 6f 20 64 65 66 69 6e  lass is to defin
34680 65 20 63 65 72 74 61 69 6e 20 66 69 65 6c 64 73  e certain fields
34690 20 74 68 61 74 20 61 72 65 20 63 6f 6d 6d 6f 6e   that are common
346a0 0a 2a 2a 20 74 6f 20 61 6c 6c 20 6d 6f 64 75 6c  .** to all modul
346b0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
346c0 73 2e 0a 2a 2a 0a 2a 2a 20 56 69 72 74 75 61 6c  s..**.** Virtual
346d0 20 74 61 62 6c 65 73 20 6d 65 74 68 6f 64 73 20   tables methods 
346e0 63 61 6e 20 73 65 74 20 61 6e 20 65 72 72 6f 72  can set an error
346f0 20 6d 65 73 73 61 67 65 20 62 79 20 61 73 73 69   message by assi
34700 67 6e 69 6e 67 20 61 0a 2a 2a 20 73 74 72 69 6e  gning a.** strin
34710 67 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  g obtained from 
34720 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
34730 29 20 74 6f 20 7a 45 72 72 4d 73 67 2e 20 20 54  ) to zErrMsg.  T
34740 68 65 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64  he method should
34750 0a 2a 2a 20 74 61 6b 65 20 63 61 72 65 20 74 68  .** take care th
34760 61 74 20 61 6e 79 20 70 72 69 6f 72 20 73 74 72  at any prior str
34770 69 6e 67 20 69 73 20 66 72 65 65 64 20 62 79 20  ing is freed by 
34780 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  a call to sqlite
34790 33 5f 66 72 65 65 28 29 0a 2a 2a 20 70 72 69 6f  3_free().** prio
347a0 72 20 74 6f 20 61 73 73 69 67 6e 69 6e 67 20 61  r to assigning a
347b0 20 6e 65 77 20 73 74 72 69 6e 67 20 74 6f 20 7a   new string to z
347c0 45 72 72 4d 73 67 2e 20 20 41 66 74 65 72 20 74  ErrMsg.  After t
347d0 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
347e0 0a 2a 2a 20 69 73 20 64 65 6c 69 76 65 72 65 64  .** is delivered
347f0 20 75 70 20 74 6f 20 74 68 65 20 63 6c 69 65 6e   up to the clien
34800 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74  t application, t
34810 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62  he string will b
34820 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a  e automatically.
34830 2a 2a 20 66 72 65 65 64 20 62 79 20 73 71 6c 69  ** freed by sqli
34840 74 65 33 5f 66 72 65 65 28 29 20 61 6e 64 20 74  te3_free() and t
34850 68 65 20 7a 45 72 72 4d 73 67 20 66 69 65 6c 64  he zErrMsg field
34860 20 77 69 6c 6c 20 62 65 20 7a 65 72 6f 65 64 2e   will be zeroed.
34870 20 20 4e 6f 74 65 0a 2a 2a 20 74 68 61 74 20 73    Note.** that s
34880 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29  qlite3_mprintf()
34890 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 66 72 65   and sqlite3_fre
348a0 65 28 29 20 61 72 65 20 75 73 65 64 20 6f 6e 20  e() are used on 
348b0 74 68 65 20 7a 45 72 72 4d 73 67 20 66 69 65 6c  the zErrMsg fiel
348c0 64 0a 2a 2a 20 73 69 6e 63 65 20 76 69 72 74 75  d.** since virtu
348d0 61 6c 20 74 61 62 6c 65 73 20 61 72 65 20 63 6f  al tables are co
348e0 6d 6d 6f 6e 6c 79 20 69 6d 70 6c 65 6d 65 6e 74  mmonly implement
348f0 65 64 20 69 6e 20 6c 6f 61 64 61 62 6c 65 20 65  ed in loadable e
34900 78 74 65 6e 73 69 6f 6e 73 20 77 68 69 63 68 0a  xtensions which.
34910 2a 2a 20 64 6f 20 6e 6f 74 20 68 61 76 65 20 61  ** do not have a
34920 63 63 65 73 73 20 74 6f 20 73 71 6c 69 74 65 33  ccess to sqlite3
34930 4d 50 72 69 6e 74 66 28 29 20 6f 72 20 73 71 6c  MPrintf() or sql
34940 69 74 65 33 46 72 65 65 28 29 2e 0a 2a 2f 0a 73  ite3Free()..*/.s
34950 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 74  truct sqlite3_vt
34960 61 62 20 7b 0a 20 20 63 6f 6e 73 74 20 73 71 6c  ab {.  const sql
34970 69 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 70 4d 6f  ite3_module *pMo
34980 64 75 6c 65 3b 20 20 2f 2a 20 54 68 65 20 6d 6f  dule;  /* The mo
34990 64 75 6c 65 20 66 6f 72 20 74 68 69 73 20 76 69  dule for this vi
349a0 72 74 75 61 6c 20 74 61 62 6c 65 20 2a 2f 0a 20  rtual table */. 
349b0 20 69 6e 74 20 6e 52 65 66 3b 20 20 20 20 20 20   int nRef;      
349c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
349d0 20 2f 2a 20 55 73 65 64 20 69 6e 74 65 72 6e 61   /* Used interna
349e0 6c 6c 79 20 2a 2f 0a 20 20 63 68 61 72 20 2a 7a  lly */.  char *z
349f0 45 72 72 4d 73 67 3b 20 20 20 20 20 20 20 20 20  ErrMsg;         
34a00 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f           /* Erro
34a10 72 20 6d 65 73 73 61 67 65 20 66 72 6f 6d 20 73  r message from s
34a20 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29  qlite3_mprintf()
34a30 20 2a 2f 0a 20 20 2f 2a 20 56 69 72 74 75 61 6c   */.  /* Virtual
34a40 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74   table implement
34a50 61 74 69 6f 6e 73 20 77 69 6c 6c 20 74 79 70 69  ations will typi
34a60 63 61 6c 6c 79 20 61 64 64 20 61 64 64 69 74 69  cally add additi
34a70 6f 6e 61 6c 20 66 69 65 6c 64 73 20 2a 2f 0a 7d  onal fields */.}
34a80 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
34a90 46 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65  F: Virtual Table
34aa0 20 43 75 72 73 6f 72 20 4f 62 6a 65 63 74 20 20   Cursor Object  
34ab0 7b 46 31 38 30 32 30 7d 0a 2a 2a 20 4b 45 59 57  {F18020}.** KEYW
34ac0 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76 74  ORDS: sqlite3_vt
34ad0 61 62 5f 63 75 72 73 6f 72 0a 2a 2a 0a 2a 2a 20  ab_cursor.**.** 
34ae0 45 76 65 72 79 20 6d 6f 64 75 6c 65 20 69 6d 70  Every module imp
34af0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 75 73 65 73  lementation uses
34b00 20 61 20 73 75 62 63 6c 61 73 73 20 6f 66 20 74   a subclass of t
34b10 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 72  he following str
34b20 75 63 74 75 72 65 0a 2a 2a 20 74 6f 20 64 65 73  ucture.** to des
34b30 63 72 69 62 65 20 63 75 72 73 6f 72 73 20 74 68  cribe cursors th
34b40 61 74 20 70 6f 69 6e 74 20 69 6e 74 6f 20 74 68  at point into th
34b50 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  e virtual table 
34b60 61 6e 64 20 61 72 65 20 75 73 65 64 0a 2a 2a 20  and are used.** 
34b70 74 6f 20 6c 6f 6f 70 20 74 68 72 6f 75 67 68 20  to loop through 
34b80 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c  the virtual tabl
34b90 65 2e 20 20 43 75 72 73 6f 72 73 20 61 72 65 20  e.  Cursors are 
34ba0 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 74 68  created using th
34bb0 65 0a 2a 2a 20 78 4f 70 65 6e 20 6d 65 74 68 6f  e.** xOpen metho
34bc0 64 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 2e  d of the module.
34bd0 20 20 45 61 63 68 20 6d 6f 64 75 6c 65 20 69 6d    Each module im
34be0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c  plementation wil
34bf0 6c 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20  l define.** the 
34c00 63 6f 6e 74 65 6e 74 20 6f 66 20 61 20 63 75 72  content of a cur
34c10 73 6f 72 20 73 74 72 75 63 74 75 72 65 20 74 6f  sor structure to
34c20 20 73 75 69 74 20 69 74 73 20 6f 77 6e 20 6e 65   suit its own ne
34c30 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  eds..**.** This 
34c40 73 75 70 65 72 63 6c 61 73 73 20 65 78 69 73 74  superclass exist
34c50 73 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 64 65  s in order to de
34c60 66 69 6e 65 20 66 69 65 6c 64 73 20 6f 66 20 74  fine fields of t
34c70 68 65 20 63 75 72 73 6f 72 20 74 68 61 74 0a 2a  he cursor that.*
34c80 2a 20 61 72 65 20 63 6f 6d 6d 6f 6e 20 74 6f 20  * are common to 
34c90 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  all implementati
34ca0 6f 6e 73 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73  ons..*/.struct s
34cb0 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
34cc0 6f 72 20 7b 0a 20 20 73 71 6c 69 74 65 33 5f 76  or {.  sqlite3_v
34cd0 74 61 62 20 2a 70 56 74 61 62 3b 20 20 20 20 20  tab *pVtab;     
34ce0 20 2f 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c   /* Virtual tabl
34cf0 65 20 6f 66 20 74 68 69 73 20 63 75 72 73 6f 72  e of this cursor
34d00 20 2a 2f 0a 20 20 2f 2a 20 56 69 72 74 75 61 6c   */.  /* Virtual
34d10 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74   table implement
34d20 61 74 69 6f 6e 73 20 77 69 6c 6c 20 74 79 70 69  ations will typi
34d30 63 61 6c 6c 79 20 61 64 64 20 61 64 64 69 74 69  cally add additi
34d40 6f 6e 61 6c 20 66 69 65 6c 64 73 20 2a 2f 0a 7d  onal fields */.}
34d50 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
34d60 46 3a 20 44 65 63 6c 61 72 65 20 54 68 65 20 53  F: Declare The S
34d70 63 68 65 6d 61 20 4f 66 20 41 20 56 69 72 74 75  chema Of A Virtu
34d80 61 6c 20 54 61 62 6c 65 20 7b 46 31 38 32 38 30  al Table {F18280
34d90 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 43 72 65  }.**.** The xCre
34da0 61 74 65 20 61 6e 64 20 78 43 6f 6e 6e 65 63 74  ate and xConnect
34db0 20 6d 65 74 68 6f 64 73 20 6f 66 20 61 20 6d 6f   methods of a mo
34dc0 64 75 6c 65 20 75 73 65 20 74 68 65 20 66 6f 6c  dule use the fol
34dd0 6c 6f 77 69 6e 67 20 41 50 49 0a 2a 2a 20 74 6f  lowing API.** to
34de0 20 64 65 63 6c 61 72 65 20 74 68 65 20 66 6f 72   declare the for
34df0 6d 61 74 20 28 74 68 65 20 6e 61 6d 65 73 20 61  mat (the names a
34e00 6e 64 20 64 61 74 61 74 79 70 65 73 20 6f 66 20  nd datatypes of 
34e10 74 68 65 20 63 6f 6c 75 6d 6e 73 29 20 6f 66 0a  the columns) of.
34e20 2a 2a 20 74 68 65 20 76 69 72 74 75 61 6c 20 74  ** the virtual t
34e30 61 62 6c 65 73 20 74 68 65 79 20 69 6d 70 6c 65  ables they imple
34e40 6d 65 6e 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ment..*/.int sql
34e50 69 74 65 33 5f 64 65 63 6c 61 72 65 5f 76 74 61  ite3_declare_vta
34e60 62 28 73 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73  b(sqlite3*, cons
34e70 74 20 63 68 61 72 20 2a 7a 43 72 65 61 74 65 54  t char *zCreateT
34e80 61 62 6c 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  able);../*.** CA
34e90 50 49 33 52 45 46 3a 20 4f 76 65 72 6c 6f 61 64  PI3REF: Overload
34ea0 20 41 20 46 75 6e 63 74 69 6f 6e 20 46 6f 72 20   A Function For 
34eb0 41 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20  A Virtual Table 
34ec0 7b 46 31 38 33 30 30 7d 0a 2a 2a 0a 2a 2a 20 56  {F18300}.**.** V
34ed0 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 63 61  irtual tables ca
34ee0 6e 20 70 72 6f 76 69 64 65 20 61 6c 74 65 72 6e  n provide altern
34ef0 61 74 69 76 65 20 69 6d 70 6c 65 6d 65 6e 74 61  ative implementa
34f00 74 69 6f 6e 73 20 6f 66 20 66 75 6e 63 74 69 6f  tions of functio
34f10 6e 73 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 20  ns.** using the 
34f20 78 46 69 6e 64 46 75 6e 63 74 69 6f 6e 20 6d 65  xFindFunction me
34f30 74 68 6f 64 2e 20 20 42 75 74 20 67 6c 6f 62 61  thod.  But globa
34f40 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 74 68  l versions of th
34f50 6f 73 65 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a  ose functions.**
34f60 20 6d 75 73 74 20 65 78 69 73 74 20 69 6e 20 6f   must exist in o
34f70 72 64 65 72 20 74 6f 20 62 65 20 6f 76 65 72 6c  rder to be overl
34f80 6f 61 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  oaded..**.** Thi
34f90 73 20 41 50 49 20 6d 61 6b 65 73 20 73 75 72 65  s API makes sure
34fa0 20 61 20 67 6c 6f 62 61 6c 20 76 65 72 73 69 6f   a global versio
34fb0 6e 20 6f 66 20 61 20 66 75 6e 63 74 69 6f 6e 20  n of a function 
34fc0 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61  with a particula
34fd0 72 0a 2a 2a 20 6e 61 6d 65 20 61 6e 64 20 6e 75  r.** name and nu
34fe0 6d 62 65 72 20 6f 66 20 70 61 72 61 6d 65 74 65  mber of paramete
34ff0 72 73 20 65 78 69 73 74 73 2e 20 20 49 66 20 6e  rs exists.  If n
35000 6f 20 73 75 63 68 20 66 75 6e 63 74 69 6f 6e 20  o such function 
35010 65 78 69 73 74 73 0a 2a 2a 20 62 65 66 6f 72 65  exists.** before
35020 20 74 68 69 73 20 41 50 49 20 69 73 20 63 61 6c   this API is cal
35030 6c 65 64 2c 20 61 20 6e 65 77 20 66 75 6e 63 74  led, a new funct
35040 69 6f 6e 20 69 73 20 63 72 65 61 74 65 64 2e 20  ion is created. 
35050 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   The implementat
35060 69 6f 6e 0a 2a 2a 20 6f 66 20 74 68 65 20 6e 65  ion.** of the ne
35070 77 20 66 75 6e 63 74 69 6f 6e 20 61 6c 77 61 79  w function alway
35080 73 20 63 61 75 73 65 73 20 61 6e 20 65 78 63 65  s causes an exce
35090 70 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 72 6f  ption to be thro
350a0 77 6e 2e 20 20 53 6f 0a 2a 2a 20 74 68 65 20 6e  wn.  So.** the n
350b0 65 77 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 6e  ew function is n
350c0 6f 74 20 67 6f 6f 64 20 66 6f 72 20 61 6e 79 74  ot good for anyt
350d0 68 69 6e 67 20 62 79 20 69 74 73 65 6c 66 2e 20  hing by itself. 
350e0 20 49 74 73 20 6f 6e 6c 79 0a 2a 2a 20 70 75 72   Its only.** pur
350f0 70 6f 73 65 20 69 73 20 74 6f 20 62 65 20 61 20  pose is to be a 
35100 70 6c 61 63 65 2d 68 6f 6c 64 65 72 20 66 75 6e  place-holder fun
35110 63 74 69 6f 6e 20 74 68 61 74 20 63 61 6e 20 62  ction that can b
35120 65 20 6f 76 65 72 6c 6f 61 64 65 64 0a 2a 2a 20  e overloaded.** 
35130 62 79 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  by virtual table
35140 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50  s..**.** This AP
35150 49 20 73 68 6f 75 6c 64 20 62 65 20 63 6f 6e 73  I should be cons
35160 69 64 65 72 65 64 20 70 61 72 74 20 6f 66 20 74  idered part of t
35170 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  he virtual table
35180 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 77   interface,.** w
35190 68 69 63 68 20 69 73 20 65 78 70 65 72 69 6d 65  hich is experime
351a0 6e 74 61 6c 20 61 6e 64 20 73 75 62 6a 65 63 74  ntal and subject
351b0 20 74 6f 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 69   to change..*/.i
351c0 6e 74 20 73 71 6c 69 74 65 33 5f 6f 76 65 72 6c  nt sqlite3_overl
351d0 6f 61 64 5f 66 75 6e 63 74 69 6f 6e 28 73 71 6c  oad_function(sql
351e0 69 74 65 33 2a 2c 20 63 6f 6e 73 74 20 63 68 61  ite3*, const cha
351f0 72 20 2a 7a 46 75 6e 63 4e 61 6d 65 2c 20 69 6e  r *zFuncName, in
35200 74 20 6e 41 72 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t nArg);../*.** 
35210 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f  The interface to
35220 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62   the virtual-tab
35230 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 64 65 66  le mechanism def
35240 69 6e 65 64 20 61 62 6f 76 65 20 28 62 61 63 6b  ined above (back
35250 20 75 70 0a 2a 2a 20 74 6f 20 61 20 63 6f 6d 6d   up.** to a comm
35260 65 6e 74 20 72 65 6d 61 72 6b 61 62 6c 79 20 73  ent remarkably s
35270 69 6d 69 6c 61 72 20 74 6f 20 74 68 69 73 20 6f  imilar to this o
35280 6e 65 29 20 69 73 20 63 75 72 72 65 6e 74 6c 79  ne) is currently
35290 20 63 6f 6e 73 69 64 65 72 65 64 0a 2a 2a 20 74   considered.** t
352a0 6f 20 62 65 20 65 78 70 65 72 69 6d 65 6e 74 61  o be experimenta
352b0 6c 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61 63  l.  The interfac
352c0 65 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69  e might change i
352d0 6e 20 69 6e 63 6f 6d 70 61 74 69 62 6c 65 20 77  n incompatible w
352e0 61 79 73 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20  ays..** If this 
352f0 69 73 20 61 20 70 72 6f 62 6c 65 6d 20 66 6f 72  is a problem for
35300 20 79 6f 75 2c 20 64 6f 20 6e 6f 74 20 75 73 65   you, do not use
35310 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 61   the interface a
35320 74 20 74 68 69 73 20 74 69 6d 65 2e 0a 2a 2a 0a  t this time..**.
35330 2a 2a 20 57 68 65 6e 20 74 68 65 20 76 69 72 74  ** When the virt
35340 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e  ual-table mechan
35350 69 73 6d 20 73 74 61 62 69 6c 69 7a 65 73 2c 20  ism stabilizes, 
35360 77 65 20 77 69 6c 6c 20 64 65 63 6c 61 72 65 20  we will declare 
35370 74 68 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  the.** interface
35380 20 66 69 78 65 64 2c 20 73 75 70 70 6f 72 74 20   fixed, support 
35390 69 74 20 69 6e 64 65 66 69 6e 69 74 65 6c 79 2c  it indefinitely,
353a0 20 61 6e 64 20 72 65 6d 6f 76 65 20 74 68 69 73   and remove this
353b0 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 2a   comment..**.***
353c0 2a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c  *** EXPERIMENTAL
353d0 20 2d 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68   - subject to ch
353e0 61 6e 67 65 20 77 69 74 68 6f 75 74 20 6e 6f 74  ange without not
353f0 69 63 65 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ice ************
35400 2a 2a 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  **.*/../*.** CAP
35410 49 33 52 45 46 3a 20 41 20 48 61 6e 64 6c 65 20  I3REF: A Handle 
35420 54 6f 20 41 6e 20 4f 70 65 6e 20 42 4c 4f 42 20  To An Open BLOB 
35430 7b 46 31 37 38 30 30 7d 0a 2a 2a 0a 2a 2a 20 41  {F17800}.**.** A
35440 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
35450 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73  is object repres
35460 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 42 4c 4f  ents an open BLO
35470 42 20 6f 6e 20 77 68 69 63 68 0a 2a 2a 20 69 6e  B on which.** in
35480 63 72 65 6d 65 6e 74 61 6c 20 49 2f 4f 20 63 61  cremental I/O ca
35490 6e 20 62 65 20 70 72 65 66 6f 72 6d 65 64 2e 0a  n be preformed..
354a0 2a 2a 20 4f 62 6a 65 63 74 73 20 6f 66 20 74 68  ** Objects of th
354b0 69 73 20 74 79 70 65 20 61 72 65 20 63 72 65 61  is type are crea
354c0 74 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ted by.** [sqlit
354d0 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20  e3_blob_open()] 
354e0 61 6e 64 20 64 65 73 74 72 6f 79 65 64 20 62 79  and destroyed by
354f0 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63   [sqlite3_blob_c
35500 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  lose()]..** The 
35510 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65  [sqlite3_blob_re
35520 61 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ad()] and [sqlit
35530 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29 5d  e3_blob_write()]
35540 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 63   interfaces.** c
35550 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65  an be used to re
35560 61 64 20 6f 72 20 77 72 69 74 65 20 73 6d 61 6c  ad or write smal
35570 6c 20 73 75 62 73 65 63 74 69 6f 6e 73 20 6f 66  l subsections of
35580 20 74 68 65 20 62 6c 6f 62 2e 0a 2a 2a 20 54 68   the blob..** Th
35590 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  e [sqlite3_blob_
355a0 62 79 74 65 73 28 29 5d 20 69 6e 74 65 72 66 61  bytes()] interfa
355b0 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 73  ce returns the s
355c0 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 62 6c  ize of the.** bl
355d0 6f 62 20 69 6e 20 62 79 74 65 73 2e 0a 2a 2f 0a  ob in bytes..*/.
355e0 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
355f0 71 6c 69 74 65 33 5f 62 6c 6f 62 20 73 71 6c 69  qlite3_blob sqli
35600 74 65 33 5f 62 6c 6f 62 3b 0a 0a 2f 2a 0a 2a 2a  te3_blob;../*.**
35610 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 20   CAPI3REF: Open 
35620 41 20 42 4c 4f 42 20 46 6f 72 20 49 6e 63 72 65  A BLOB For Incre
35630 6d 65 6e 74 61 6c 20 49 2f 4f 20 7b 46 31 37 38  mental I/O {F178
35640 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  10}.**.** This i
35650 6e 74 65 72 66 61 63 65 73 20 6f 70 65 6e 73 20  nterfaces opens 
35660 61 20 68 61 6e 64 6c 65 20 74 6f 20 74 68 65 20  a handle to the 
35670 62 6c 6f 62 20 6c 6f 63 61 74 65 64 0a 2a 2a 20  blob located.** 
35680 69 6e 20 72 6f 77 20 69 52 6f 77 2c 2c 20 63 6f  in row iRow,, co
35690 6c 75 6d 6e 20 7a 43 6f 6c 75 6d 6e 2c 20 74 61  lumn zColumn, ta
356a0 62 6c 65 20 7a 54 61 62 6c 65 20 69 6e 20 64 61  ble zTable in da
356b0 74 61 62 61 73 65 20 7a 44 62 3b 0a 2a 2a 20 69  tabase zDb;.** i
356c0 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 20  n other words,  
356d0 74 68 65 20 73 61 6d 65 20 62 6c 6f 62 20 74 68  the same blob th
356e0 61 74 20 77 6f 75 6c 64 20 62 65 20 73 65 6c 65  at would be sele
356f0 63 74 65 64 20 62 79 3a 0a 2a 2a 0a 2a 2a 20 3c  cted by:.**.** <
35700 70 72 65 3e 0a 2a 2a 20 20 20 20 20 53 45 4c 45  pre>.**     SELE
35710 43 54 20 7a 43 6f 6c 75 6d 6e 20 46 52 4f 4d 20  CT zColumn FROM 
35720 7a 44 62 2e 7a 54 61 62 6c 65 20 57 48 45 52 45  zDb.zTable WHERE
35730 20 72 6f 77 69 64 20 3d 20 69 52 6f 77 3b 0a 2a   rowid = iRow;.*
35740 2a 20 3c 2f 70 72 65 3e 20 7b 45 4e 44 7d 0a 2a  * </pre> {END}.*
35750 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66 6c 61 67  *.** If the flag
35760 73 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e  s parameter is n
35770 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 62 6c 6f  on-zero, the blo
35780 62 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  b is opened for 
35790 0a 2a 2a 20 72 65 61 64 20 61 6e 64 20 77 72 69  .** read and wri
357a0 74 65 20 61 63 63 65 73 73 2e 20 49 66 20 69 74  te access. If it
357b0 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 20 62 6c   is zero, the bl
357c0 6f 62 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72  ob is opened for
357d0 20 72 65 61 64 20 0a 2a 2a 20 61 63 63 65 73 73   read .** access
357e0 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63 65  ..**.** On succe
357f0 73 73 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  ss, [SQLITE_OK] 
35800 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20  is returned and 
35810 74 68 65 20 6e 65 77 20 0a 2a 2a 20 5b 73 71 6c  the new .** [sql
35820 69 74 65 33 5f 62 6c 6f 62 20 7c 20 62 6c 6f 62  ite3_blob | blob
35830 20 68 61 6e 64 6c 65 5d 20 69 73 20 77 72 69 74   handle] is writ
35840 74 65 6e 20 74 6f 20 2a 70 70 42 6c 6f 62 2e 20  ten to *ppBlob. 
35850 0a 2a 2a 20 4f 74 68 65 72 77 69 73 65 20 61 6e  .** Otherwise an
35860 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72   error code is r
35870 65 74 75 72 6e 65 64 20 61 6e 64 20 0a 2a 2a 20  eturned and .** 
35880 61 6e 79 20 76 61 6c 75 65 20 77 72 69 74 74 65  any value writte
35890 6e 20 74 6f 20 2a 70 70 42 6c 6f 62 20 73 68 6f  n to *ppBlob sho
358a0 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20  uld not be used 
358b0 62 79 20 74 68 65 20 63 61 6c 6c 65 72 2e 0a 2a  by the caller..*
358c0 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  * This function 
358d0 73 65 74 73 20 74 68 65 20 64 61 74 61 62 61 73  sets the databas
358e0 65 2d 68 61 6e 64 6c 65 20 65 72 72 6f 72 20 63  e-handle error c
358f0 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65 0a  ode and message.
35900 2a 2a 20 61 63 63 65 73 73 69 62 6c 65 20 76 69  ** accessible vi
35910 61 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  a [sqlite3_errco
35920 64 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  de()] and [sqlit
35930 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a  e3_errmsg()]..**
35940 20 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a   .** INVARIANTS:
35950 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 38 31 33 7d 20  .**.** {F17813} 
35960 41 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e 76  A successful inv
35970 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b  ocation of the [
35980 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65  sqlite3_blob_ope
35990 6e 28 44 2c 42 2c 54 2c 43 2c 52 2c 46 2c 50 29  n(D,B,T,C,R,F,P)
359a0 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  ].**          in
359b0 74 65 72 66 61 63 65 20 6f 70 65 6e 73 20 61 6e  terface opens an
359c0 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5d 20   [sqlite3_blob] 
359d0 6f 62 6a 65 63 74 20 50 20 6f 6e 20 74 68 65 20  object P on the 
359e0 62 6c 6f 62 0a 2a 2a 20 20 20 20 20 20 20 20 20  blob.**         
359f0 20 69 6e 20 63 6f 6c 75 6d 6e 20 43 20 6f 66 20   in column C of 
35a00 74 61 62 6c 65 20 54 20 69 6e 20 64 61 74 61 62  table T in datab
35a10 61 73 65 20 42 20 6f 6e 20 5b 64 61 74 61 62 61  ase B on [databa
35a20 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
35a30 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 38 31 34 7d  ..**.** {F17814}
35a40 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e   A successful in
35a50 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c  vocation of [sql
35a60 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 44  ite3_blob_open(D
35a70 2c 2e 2e 2e 29 5d 20 73 74 61 72 74 73 0a 2a 2a  ,...)] starts.**
35a80 20 20 20 20 20 20 20 20 20 20 61 20 6e 65 77 20            a new 
35a90 74 72 61 6e 73 61 63 74 69 6f 6e 20 6f 6e 20 5b  transaction on [
35aa0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
35ab0 69 6f 6e 5d 20 44 20 69 66 20 74 68 61 74 20 63  ion] D if that c
35ac0 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20  onnection.**    
35ad0 20 20 20 20 20 20 69 73 20 6e 6f 74 20 61 6c 72        is not alr
35ae0 65 61 64 79 20 69 6e 20 61 20 74 72 61 6e 73 61  eady in a transa
35af0 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  ction..**.** {F1
35b00 37 38 31 36 7d 20 54 68 65 20 5b 73 71 6c 69 74  7816} The [sqlit
35b10 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 44 2c 42  e3_blob_open(D,B
35b20 2c 54 2c 43 2c 52 2c 46 2c 50 29 5d 20 69 6e 74  ,T,C,R,F,P)] int
35b30 65 72 66 61 63 65 20 6f 70 65 6e 73 20 74 68 65  erface opens the
35b40 20 62 6c 6f 62 0a 2a 2a 20 20 20 20 20 20 20 20   blob.**        
35b50 20 20 66 6f 72 20 72 65 61 64 20 61 6e 64 20 77    for read and w
35b60 72 69 74 65 20 61 63 63 65 73 73 20 69 66 20 61  rite access if a
35b70 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 46  nd only if the F
35b80 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20   parameter.**   
35b90 20 20 20 20 20 20 20 69 73 20 6e 6f 6e 2d 7a 65         is non-ze
35ba0 72 6f 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 38 31  ro..**.** {F1781
35bb0 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  9} The [sqlite3_
35bc0 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20 69 6e 74  blob_open()] int
35bd0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 5b  erface returns [
35be0 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 0a 2a  SQLITE_OK] on .*
35bf0 2a 20 20 20 20 20 20 20 20 20 20 73 75 63 63 65  *          succe
35c00 73 73 20 61 6e 64 20 61 6e 20 61 70 70 72 6f 70  ss and an approp
35c10 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64  riate [error cod
35c20 65 5d 20 6f 6e 20 66 61 69 6c 75 72 65 2e 0a 2a  e] on failure..*
35c30 2a 0a 2a 2a 20 7b 46 31 37 38 32 31 7d 20 49 66  *.** {F17821} If
35c40 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
35c50 20 64 75 72 69 6e 67 20 65 76 61 6c 75 61 74 69   during evaluati
35c60 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 62  on of [sqlite3_b
35c70 6c 6f 62 5f 6f 70 65 6e 28 44 2c 2e 2e 2e 29 5d  lob_open(D,...)]
35c80 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
35c90 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  n subsequent cal
35ca0 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65  ls to [sqlite3_e
35cb0 72 72 63 6f 64 65 28 44 29 5d 2c 0a 2a 2a 20 20  rrcode(D)],.**  
35cc0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
35cd0 5f 65 72 72 6d 73 67 28 44 29 5d 2c 20 61 6e 64  _errmsg(D)], and
35ce0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
35cf0 31 36 28 44 29 5d 20 77 69 6c 6c 20 72 65 74 75  16(D)] will retu
35d00 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  rn.**          i
35d10 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 70 70 72 6f  nformation appro
35d20 70 72 61 74 65 20 66 6f 72 20 74 68 61 74 20 65  prate for that e
35d30 72 72 6f 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  rror..*/.int sql
35d40 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 0a  ite3_blob_open(.
35d50 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 63 6f    sqlite3*,.  co
35d60 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 2c 0a 20  nst char *zDb,. 
35d70 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 54 61   const char *zTa
35d80 62 6c 65 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61  ble,.  const cha
35d90 72 20 2a 7a 43 6f 6c 75 6d 6e 2c 0a 20 20 73 71  r *zColumn,.  sq
35da0 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 52 6f 77  lite3_int64 iRow
35db0 2c 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 0a 20  ,.  int flags,. 
35dc0 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 2a   sqlite3_blob **
35dd0 70 70 42 6c 6f 62 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  ppBlob.);../*.**
35de0 20 43 41 50 49 33 52 45 46 3a 20 20 43 6c 6f 73   CAPI3REF:  Clos
35df0 65 20 41 20 42 4c 4f 42 20 48 61 6e 64 6c 65 20  e A BLOB Handle 
35e00 7b 46 31 37 38 33 30 7d 0a 2a 2a 0a 2a 2a 20 43  {F17830}.**.** C
35e10 6c 6f 73 65 20 61 6e 20 6f 70 65 6e 20 5b 73 71  lose an open [sq
35e20 6c 69 74 65 33 5f 62 6c 6f 62 20 7c 20 62 6c 6f  lite3_blob | blo
35e30 62 20 68 61 6e 64 6c 65 5d 2e 0a 2a 2a 0a 2a 2a  b handle]..**.**
35e40 20 43 6c 6f 73 69 6e 67 20 61 20 42 4c 4f 42 20   Closing a BLOB 
35e50 73 68 61 6c 6c 20 63 61 75 73 65 20 74 68 65 20  shall cause the 
35e60 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74  current transact
35e70 69 6f 6e 20 74 6f 20 63 6f 6d 6d 69 74 0a 2a 2a  ion to commit.**
35e80 20 69 66 20 74 68 65 72 65 20 61 72 65 20 6e 6f   if there are no
35e90 20 6f 74 68 65 72 20 42 4c 4f 42 73 2c 20 6e 6f   other BLOBs, no
35ea0 20 70 65 6e 64 69 6e 67 20 70 72 65 70 61 72 65   pending prepare
35eb0 64 20 73 74 61 74 65 6d 65 6e 74 73 2c 20 61 6e  d statements, an
35ec0 64 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  d the.** databas
35ed0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
35ee0 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f  in autocommit mo
35ef0 64 65 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 77 72  de..** If any wr
35f00 69 74 65 73 20 77 65 72 65 20 6d 61 64 65 20 74  ites were made t
35f10 6f 20 74 68 65 20 42 4c 4f 42 2c 20 74 68 65 79  o the BLOB, they
35f20 20 6d 69 67 68 74 20 62 65 20 68 65 6c 64 20 69   might be held i
35f30 6e 20 63 61 63 68 65 0a 2a 2a 20 75 6e 74 69 6c  n cache.** until
35f40 20 74 68 65 20 63 6c 6f 73 65 20 6f 70 65 72 61   the close opera
35f50 74 69 6f 6e 20 69 66 20 74 68 65 79 20 77 69 6c  tion if they wil
35f60 6c 20 66 69 74 2e 20 7b 45 4e 44 7d 0a 2a 2a 20  l fit. {END}.** 
35f70 43 6c 6f 73 69 6e 67 20 74 68 65 20 42 4c 4f 42  Closing the BLOB
35f80 20 6f 66 74 65 6e 20 66 6f 72 63 65 73 20 74 68   often forces th
35f90 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f 75 74  e changes.** out
35fa0 20 74 6f 20 64 69 73 6b 20 61 6e 64 20 73 6f 20   to disk and so 
35fb0 69 66 20 61 6e 79 20 49 2f 4f 20 65 72 72 6f 72  if any I/O error
35fc0 73 20 6f 63 63 75 72 2c 20 74 68 65 79 20 77 69  s occur, they wi
35fd0 6c 6c 20 6c 69 6b 65 6c 79 20 6f 63 63 75 72 0a  ll likely occur.
35fe0 2a 2a 20 61 74 20 74 68 65 20 74 69 6d 65 20 77  ** at the time w
35ff0 68 65 6e 20 74 68 65 20 42 4c 4f 42 20 69 73 20  hen the BLOB is 
36000 63 6c 6f 73 65 64 2e 20 20 7b 46 31 37 38 33 33  closed.  {F17833
36010 7d 20 41 6e 79 20 65 72 72 6f 72 73 20 74 68 61  } Any errors tha
36020 74 20 6f 63 63 75 72 20 64 75 72 69 6e 67 0a 2a  t occur during.*
36030 2a 20 63 6c 6f 73 69 6e 67 20 61 72 65 20 72 65  * closing are re
36040 70 6f 72 74 65 64 20 61 73 20 61 20 6e 6f 6e 2d  ported as a non-
36050 7a 65 72 6f 20 72 65 74 75 72 6e 20 76 61 6c 75  zero return valu
36060 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 42 4c 4f  e..**.** The BLO
36070 42 20 69 73 20 63 6c 6f 73 65 64 20 75 6e 63 6f  B is closed unco
36080 6e 64 69 74 69 6f 6e 61 6c 6c 79 2e 20 20 45 76  nditionally.  Ev
36090 65 6e 20 69 66 20 74 68 69 73 20 72 6f 75 74 69  en if this routi
360a0 6e 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e  ne returns.** an
360b0 20 65 72 72 6f 72 20 63 6f 64 65 2c 20 74 68 65   error code, the
360c0 20 42 4c 4f 42 20 69 73 20 73 74 69 6c 6c 20 63   BLOB is still c
360d0 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  losed..**.** INV
360e0 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
360f0 46 31 37 38 33 33 7d 20 54 68 65 20 5b 73 71 6c  F17833} The [sql
36100 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28  ite3_blob_close(
36110 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6c  P)] interface cl
36120 6f 73 65 73 20 61 6e 0a 2a 2a 20 20 20 20 20 20  oses an.**      
36130 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f      [sqlite3_blo
36140 62 5d 20 6f 62 6a 65 63 74 20 50 20 70 72 65 76  b] object P prev
36150 69 6f 75 73 6c 79 20 6f 70 65 6e 65 64 20 75 73  iously opened us
36160 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ing.**          
36170 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70  [sqlite3_blob_op
36180 65 6e 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  en()]..**.** {F1
36190 37 38 33 36 7d 20 43 6c 6f 73 69 6e 67 20 61 6e  7836} Closing an
361a0 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5d 20   [sqlite3_blob] 
361b0 6f 62 6a 65 63 74 20 75 73 69 6e 67 0a 2a 2a 20  object using.** 
361c0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
361d0 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 20  3_blob_close()] 
361e0 73 68 61 6c 6c 20 63 61 75 73 65 20 74 68 65 20  shall cause the 
361f0 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74  current transact
36200 69 6f 6e 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20  ion to.**       
36210 20 20 20 63 6f 6d 6d 69 74 20 69 66 20 74 68 65     commit if the
36220 72 65 20 61 72 65 20 6e 6f 20 6f 74 68 65 72 20  re are no other 
36230 6f 70 65 6e 20 5b 73 71 6c 69 74 65 33 5f 62 6c  open [sqlite3_bl
36240 6f 62 5d 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 20  ob] objects.**  
36250 20 20 20 20 20 20 20 20 6f 72 20 5b 70 72 65 70          or [prep
36260 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
36270 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61   on the same [da
36280 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
36290 6e 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20  n] and.**       
362a0 20 20 20 74 68 65 20 5b 64 61 74 61 62 61 73 65     the [database
362b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20   connection] is 
362c0 69 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  in.**          [
362d0 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f  sqlite3_get_auto
362e0 63 6f 6d 6d 69 74 20 7c 20 61 75 74 6f 63 6f 6d  commit | autocom
362f0 6d 69 74 20 6d 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a  mit mode]..**.**
36300 20 7b 46 31 37 38 33 39 7d 20 54 68 65 20 5b 73   {F17839} The [s
36310 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73  qlite3_blob_clos
36320 65 28 50 29 5d 20 69 6e 74 65 72 66 61 63 65 73  e(P)] interfaces
36330 20 63 6c 6f 73 65 73 20 74 68 65 20 0a 2a 2a 20   closes the .** 
36340 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
36350 33 5f 62 6c 6f 62 5d 20 6f 62 6a 65 63 74 20 50  3_blob] object P
36360 20 75 6e 63 6f 6e 64 69 74 69 6f 6e 61 6c 6c 79   unconditionally
36370 2c 20 65 76 65 6e 20 69 66 0a 2a 2a 20 20 20 20  , even if.**    
36380 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62        [sqlite3_b
36390 6c 6f 62 5f 63 6c 6f 73 65 28 50 29 5d 20 72 65  lob_close(P)] re
363a0 74 75 72 6e 73 20 73 6f 6d 65 74 68 69 6e 67 20  turns something 
363b0 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
363c0 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 20 20 20 20 20  TE_OK]..**      
363d0 20 20 20 20 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69      .*/.int sqli
363e0 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 73  te3_blob_close(s
363f0 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 29 3b 0a  qlite3_blob *);.
36400 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
36410 20 20 52 65 74 75 72 6e 20 54 68 65 20 53 69 7a    Return The Siz
36420 65 20 4f 66 20 41 6e 20 4f 70 65 6e 20 42 4c 4f  e Of An Open BLO
36430 42 20 7b 46 31 37 38 34 30 7d 0a 2a 2a 0a 2a 2a  B {F17840}.**.**
36440 20 52 65 74 75 72 6e 20 74 68 65 20 73 69 7a 65   Return the size
36450 20 69 6e 20 62 79 74 65 73 20 6f 66 20 74 68 65   in bytes of the
36460 20 62 6c 6f 62 20 61 63 63 65 73 73 69 62 6c 65   blob accessible
36470 20 76 69 61 20 74 68 65 20 6f 70 65 6e 20 0a 2a   via the open .*
36480 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5d  * [sqlite3_blob]
36490 20 6f 62 6a 65 63 74 20 69 6e 20 69 74 73 20 6f   object in its o
364a0 6e 6c 79 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  nly argument..**
364b0 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
364c0 2a 2a 0a 2a 2a 20 7b 46 31 37 38 34 33 7d 20 54  **.** {F17843} T
364d0 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  he [sqlite3_blob
364e0 5f 62 79 74 65 73 28 50 29 5d 20 69 6e 74 65 72  _bytes(P)] inter
364f0 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
36500 20 73 69 7a 65 0a 2a 2a 20 20 20 20 20 20 20 20   size.**        
36510 20 20 69 6e 20 62 79 74 65 73 20 6f 66 20 74 68    in bytes of th
36520 65 20 42 4c 4f 42 20 74 68 61 74 20 74 68 65 20  e BLOB that the 
36530 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5d 20 6f  [sqlite3_blob] o
36540 62 6a 65 63 74 20 50 0a 2a 2a 20 20 20 20 20 20  bject P.**      
36550 20 20 20 20 72 65 66 65 72 73 20 74 6f 2e 0a 2a      refers to..*
36560 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c  /.int sqlite3_bl
36570 6f 62 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33  ob_bytes(sqlite3
36580 5f 62 6c 6f 62 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  _blob *);../*.**
36590 20 43 41 50 49 33 52 45 46 3a 20 20 52 65 61 64   CAPI3REF:  Read
365a0 20 44 61 74 61 20 46 72 6f 6d 20 41 20 42 4c 4f   Data From A BLO
365b0 42 20 49 6e 63 72 65 6d 65 6e 74 61 6c 6c 79 20  B Incrementally 
365c0 7b 46 31 37 38 35 30 7d 0a 2a 2a 0a 2a 2a 20 54  {F17850}.**.** T
365d0 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  his function is 
365e0 75 73 65 64 20 74 6f 20 72 65 61 64 20 64 61 74  used to read dat
365f0 61 20 66 72 6f 6d 20 61 6e 20 6f 70 65 6e 20 0a  a from an open .
36600 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  ** [sqlite3_blob
36610 20 7c 20 62 6c 6f 62 2d 68 61 6e 64 6c 65 5d 20   | blob-handle] 
36620 69 6e 74 6f 20 61 20 63 61 6c 6c 65 72 20 73 75  into a caller su
36630 70 70 6c 69 65 64 20 62 75 66 66 65 72 2e 0a 2a  pplied buffer..*
36640 2a 20 4e 20 62 79 74 65 73 20 6f 66 20 64 61 74  * N bytes of dat
36650 61 20 61 72 65 20 63 6f 70 69 65 64 20 69 6e 74  a are copied int
36660 6f 20 62 75 66 66 65 72 0a 2a 2a 20 5a 20 66 72  o buffer.** Z fr
36670 6f 6d 20 74 68 65 20 6f 70 65 6e 20 62 6c 6f 62  om the open blob
36680 2c 20 73 74 61 72 74 69 6e 67 20 61 74 20 6f 66  , starting at of
36690 66 73 65 74 20 69 4f 66 66 73 65 74 2e 0a 2a 2a  fset iOffset..**
366a0 0a 2a 2a 20 49 66 20 6f 66 66 73 65 74 20 69 4f  .** If offset iO
366b0 66 66 73 65 74 20 69 73 20 6c 65 73 73 20 74 68  ffset is less th
366c0 61 6e 20 4e 20 62 79 74 65 73 20 66 72 6f 6d 20  an N bytes from 
366d0 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 62  the end of the b
366e0 6c 6f 62 2c 20 0a 2a 2a 20 5b 53 51 4c 49 54 45  lob, .** [SQLITE
366f0 5f 45 52 52 4f 52 5d 20 69 73 20 72 65 74 75 72  _ERROR] is retur
36700 6e 65 64 20 61 6e 64 20 6e 6f 20 64 61 74 61 20  ned and no data 
36710 69 73 20 72 65 61 64 2e 20 20 49 66 20 4e 20 6f  is read.  If N o
36720 72 20 69 4f 66 66 73 65 74 20 69 73 0a 2a 2a 20  r iOffset is.** 
36730 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 20 5b  less than zero [
36740 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 73  SQLITE_ERROR] is
36750 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f   returned and no
36760 20 64 61 74 61 20 69 73 20 72 65 61 64 2e 0a 2a   data is read..*
36770 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73 2c  *.** On success,
36780 20 53 51 4c 49 54 45 5f 4f 4b 20 69 73 20 72 65   SQLITE_OK is re
36790 74 75 72 6e 65 64 2e 20 4f 74 68 65 72 77 69 73  turned. Otherwis
367a0 65 2c 20 61 6e 20 0a 2a 2a 20 5b 65 72 72 6f 72  e, an .** [error
367b0 20 63 6f 64 65 5d 20 6f 72 20 61 6e 20 5b 65 78   code] or an [ex
367c0 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64  tended error cod
367d0 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  e] is returned..
367e0 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
367f0 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 38 35 33 7d  :.**.** {F17853}
36800 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c   The [sqlite3_bl
36810 6f 62 5f 72 65 61 64 28 50 2c 5a 2c 4e 2c 58 29  ob_read(P,Z,N,X)
36820 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 61 64  ] interface read
36830 73 20 4e 20 62 79 74 65 73 0a 2a 2a 20 20 20 20  s N bytes.**    
36840 20 20 20 20 20 20 62 65 67 69 6e 6e 69 6e 67 20        beginning 
36850 61 74 20 6f 66 66 73 65 74 20 58 20 66 72 6f 6d  at offset X from
36860 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
36870 20 62 6c 6f 62 20 74 68 61 74 20 5b 73 71 6c 69   blob that [sqli
36880 74 65 33 5f 62 6c 6f 62 5d 20 6f 62 6a 65 63 74  te3_blob] object
36890 20 50 20 72 65 66 65 72 73 20 74 6f 0a 2a 2a 20   P refers to.** 
368a0 20 20 20 20 20 20 20 20 20 61 6e 64 20 77 72 69           and wri
368b0 74 65 73 20 74 68 6f 73 65 20 4e 20 62 79 74 65  tes those N byte
368c0 73 20 69 6e 74 6f 20 62 75 66 66 65 72 20 5a 2e  s into buffer Z.
368d0 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 38 35 36 7d 20  .**.** {F17856} 
368e0 49 6e 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  In [sqlite3_blob
368f0 5f 72 65 61 64 28 50 2c 5a 2c 4e 2c 58 29 5d 20  _read(P,Z,N,X)] 
36900 69 66 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  if the size of t
36910 68 65 20 62 6c 6f 62 0a 2a 2a 20 20 20 20 20 20  he blob.**      
36920 20 20 20 20 69 73 20 6c 65 73 73 20 74 68 61 6e      is less than
36930 20 4e 2b 58 20 62 79 74 65 73 2c 20 74 68 65 6e   N+X bytes, then
36940 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 72 65   the function re
36950 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 45 52  turns [SQLITE_ER
36960 52 4f 52 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ROR].**         
36970 20 61 6e 64 20 6e 6f 74 68 69 6e 67 20 69 73 20   and nothing is 
36980 72 65 61 64 20 66 72 6f 6d 20 74 68 65 20 62 6c  read from the bl
36990 6f 62 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 38 35  ob..**.** {F1785
369a0 39 7d 20 49 6e 20 5b 73 71 6c 69 74 65 33 5f 62  9} In [sqlite3_b
369b0 6c 6f 62 5f 72 65 61 64 28 50 2c 5a 2c 4e 2c 58  lob_read(P,Z,N,X
369c0 29 5d 20 69 66 20 58 20 6f 72 20 4e 20 69 73 20  )] if X or N is 
369d0 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 0a 2a  less than zero.*
369e0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20  *          then 
369f0 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  the function ret
36a00 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 45 52 52  urns [SQLITE_ERR
36a10 4f 52 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  OR].**          
36a20 61 6e 64 20 6e 6f 74 68 69 6e 67 20 69 73 20 72  and nothing is r
36a30 65 61 64 20 66 72 6f 6d 20 74 68 65 20 62 6c 6f  ead from the blo
36a40 62 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 38 36 32  b..**.** {F17862
36a50 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  } The [sqlite3_b
36a60 6c 6f 62 5f 72 65 61 64 28 50 2c 5a 2c 4e 2c 58  lob_read(P,Z,N,X
36a70 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
36a80 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
36a90 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 66 20  .**          if 
36aa0 4e 20 62 79 74 65 73 20 77 68 65 72 65 20 73 75  N bytes where su
36ab0 63 63 65 73 73 66 75 6c 6c 79 20 72 65 61 64 20  ccessfully read 
36ac0 69 6e 74 6f 20 62 75 66 66 65 72 20 5a 2e 0a 2a  into buffer Z..*
36ad0 2a 0a 2a 2a 20 7b 46 31 37 38 36 35 7d 20 49 66  *.** {F17865} If
36ae0 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20 72   the requested r
36af0 65 61 64 20 63 6f 75 6c 64 20 6e 6f 74 20 62 65  ead could not be
36b00 20 63 6f 6d 70 6c 65 74 65 64 2c 0a 2a 2a 20 20   completed,.**  
36b10 20 20 20 20 20 20 20 20 74 68 65 20 5b 73 71 6c          the [sql
36b20 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 50  ite3_blob_read(P
36b30 2c 5a 2c 4e 2c 58 29 5d 20 69 6e 74 65 72 66 61  ,Z,N,X)] interfa
36b40 63 65 20 72 65 74 75 72 6e 73 20 61 6e 0a 2a 2a  ce returns an.**
36b50 20 20 20 20 20 20 20 20 20 20 61 70 70 72 6f 70            approp
36b60 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64  riate [error cod
36b70 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20  e] or [extended 
36b80 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a  error code]..**.
36b90 2a 2a 20 7b 46 31 37 38 36 38 7d 20 49 66 20 61  ** {F17868} If a
36ba0 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64  n error occurs d
36bb0 75 72 69 6e 67 20 65 76 61 6c 75 61 74 69 6f 6e  uring evaluation
36bc0 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f   of [sqlite3_blo
36bd0 62 5f 72 65 61 64 28 44 2c 2e 2e 2e 29 5d 0a 2a  b_read(D,...)].*
36be0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20  *          then 
36bf0 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
36c00 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72   to [sqlite3_err
36c10 63 6f 64 65 28 44 29 5d 2c 0a 2a 2a 20 20 20 20  code(D)],.**    
36c20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 65        [sqlite3_e
36c30 72 72 6d 73 67 28 44 29 5d 2c 20 61 6e 64 20 5b  rrmsg(D)], and [
36c40 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
36c50 28 44 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  (D)] will return
36c60 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 66  .**          inf
36c70 6f 72 6d 61 74 69 6f 6e 20 61 70 70 72 6f 70 72  ormation appropr
36c80 61 74 65 20 66 6f 72 20 74 68 61 74 20 65 72 72  ate for that err
36c90 6f 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  or..*/.int sqlit
36ca0 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 73 71 6c  e3_blob_read(sql
36cb0 69 74 65 33 5f 62 6c 6f 62 20 2a 2c 20 76 6f 69  ite3_blob *, voi
36cc0 64 20 2a 5a 2c 20 69 6e 74 20 4e 2c 20 69 6e 74  d *Z, int N, int
36cd0 20 69 4f 66 66 73 65 74 29 3b 0a 0a 2f 2a 0a 2a   iOffset);../*.*
36ce0 2a 20 43 41 50 49 33 52 45 46 3a 20 20 57 72 69  * CAPI3REF:  Wri
36cf0 74 65 20 44 61 74 61 20 49 6e 74 6f 20 41 20 42  te Data Into A B
36d00 4c 4f 42 20 49 6e 63 72 65 6d 65 6e 74 61 6c 6c  LOB Incrementall
36d10 79 20 7b 46 31 37 38 37 30 7d 0a 2a 2a 0a 2a 2a  y {F17870}.**.**
36d20 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69   This function i
36d30 73 20 75 73 65 64 20 74 6f 20 77 72 69 74 65 20  s used to write 
36d40 64 61 74 61 20 69 6e 74 6f 20 61 6e 20 6f 70 65  data into an ope
36d50 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  n .** [sqlite3_b
36d60 6c 6f 62 20 7c 20 62 6c 6f 62 2d 68 61 6e 64 6c  lob | blob-handl
36d70 65 5d 20 66 72 6f 6d 20 61 20 75 73 65 72 20 73  e] from a user s
36d80 75 70 70 6c 69 65 64 20 62 75 66 66 65 72 2e 0a  upplied buffer..
36d90 2a 2a 20 6e 20 62 79 74 65 73 20 6f 66 20 64 61  ** n bytes of da
36da0 74 61 20 61 72 65 20 63 6f 70 69 65 64 20 66 72  ta are copied fr
36db0 6f 6d 20 74 68 65 20 62 75 66 66 65 72 0a 2a 2a  om the buffer.**
36dc0 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 7a   pointed to by z
36dd0 20 69 6e 74 6f 20 74 68 65 20 6f 70 65 6e 20 62   into the open b
36de0 6c 6f 62 2c 20 73 74 61 72 74 69 6e 67 20 61 74  lob, starting at
36df0 20 6f 66 66 73 65 74 20 69 4f 66 66 73 65 74 2e   offset iOffset.
36e00 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 73  .**.** If the [s
36e10 71 6c 69 74 65 33 5f 62 6c 6f 62 20 7c 20 62 6c  qlite3_blob | bl
36e20 6f 62 2d 68 61 6e 64 6c 65 5d 20 70 61 73 73 65  ob-handle] passe
36e30 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61  d as the first a
36e40 72 67 75 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 6e  rgument.** was n
36e50 6f 74 20 6f 70 65 6e 65 64 20 66 6f 72 20 77 72  ot opened for wr
36e60 69 74 69 6e 67 20 28 74 68 65 20 66 6c 61 67 73  iting (the flags
36e70 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
36e80 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e  qlite3_blob_open
36e90 28 29 5d 0a 2a 2a 2a 20 77 61 73 20 7a 65 72 6f  ()].*** was zero
36ea0 29 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  ), this function
36eb0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
36ec0 5f 52 45 41 44 4f 4e 4c 59 5d 2e 0a 2a 2a 0a 2a  _READONLY]..**.*
36ed0 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  * This function 
36ee0 6d 61 79 20 6f 6e 6c 79 20 6d 6f 64 69 66 79 20  may only modify 
36ef0 74 68 65 20 63 6f 6e 74 65 6e 74 73 20 6f 66 20  the contents of 
36f00 74 68 65 20 62 6c 6f 62 3b 20 69 74 20 69 73 0a  the blob; it is.
36f10 2a 2a 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  ** not possible 
36f20 74 6f 20 69 6e 63 72 65 61 73 65 20 74 68 65 20  to increase the 
36f30 73 69 7a 65 20 6f 66 20 61 20 62 6c 6f 62 20 75  size of a blob u
36f40 73 69 6e 67 20 74 68 69 73 20 41 50 49 2e 0a 2a  sing this API..*
36f50 2a 20 49 66 20 6f 66 66 73 65 74 20 69 4f 66 66  * If offset iOff
36f60 73 65 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e  set is less than
36f70 20 6e 20 62 79 74 65 73 20 66 72 6f 6d 20 74 68   n bytes from th
36f80 65 20 65 6e 64 20 6f 66 20 74 68 65 20 62 6c 6f  e end of the blo
36f90 62 2c 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45  b, .** [SQLITE_E
36fa0 52 52 4f 52 5d 20 69 73 20 72 65 74 75 72 6e 65  RROR] is returne
36fb0 64 20 61 6e 64 20 6e 6f 20 64 61 74 61 20 69 73  d and no data is
36fc0 20 77 72 69 74 74 65 6e 2e 20 20 49 66 20 6e 20   written.  If n 
36fd0 69 73 0a 2a 2a 20 6c 65 73 73 20 74 68 61 6e 20  is.** less than 
36fe0 7a 65 72 6f 20 5b 53 51 4c 49 54 45 5f 45 52 52  zero [SQLITE_ERR
36ff0 4f 52 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  OR] is returned 
37000 61 6e 64 20 6e 6f 20 64 61 74 61 20 69 73 20 77  and no data is w
37010 72 69 74 74 65 6e 2e 0a 2a 2a 0a 2a 2a 20 4f 6e  ritten..**.** On
37020 20 73 75 63 63 65 73 73 2c 20 53 51 4c 49 54 45   success, SQLITE
37030 5f 4f 4b 20 69 73 20 72 65 74 75 72 6e 65 64 2e  _OK is returned.
37040 20 4f 74 68 65 72 77 69 73 65 2c 20 61 6e 20 0a   Otherwise, an .
37050 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  ** [error code] 
37060 6f 72 20 61 6e 20 5b 65 78 74 65 6e 64 65 64 20  or an [extended 
37070 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
37080 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  eturned..**.** I
37090 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
370a0 20 7b 46 31 37 38 37 33 7d 20 54 68 65 20 5b 73   {F17873} The [s
370b0 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74  qlite3_blob_writ
370c0 65 28 50 2c 5a 2c 4e 2c 58 29 5d 20 69 6e 74 65  e(P,Z,N,X)] inte
370d0 72 66 61 63 65 20 77 72 69 74 65 73 20 4e 20 62  rface writes N b
370e0 79 74 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  ytes.**         
370f0 20 66 72 6f 6d 20 62 75 66 66 65 72 20 5a 20 69   from buffer Z i
37100 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  nto.**          
37110 74 68 65 20 62 6c 6f 62 20 74 68 61 74 20 5b 73  the blob that [s
37120 71 6c 69 74 65 33 5f 62 6c 6f 62 5d 20 6f 62 6a  qlite3_blob] obj
37130 65 63 74 20 50 20 72 65 66 65 72 73 20 74 6f 0a  ect P refers to.
37140 2a 2a 20 20 20 20 20 20 20 20 20 20 62 65 67 69  **          begi
37150 6e 6e 69 6e 67 20 61 74 20 61 6e 20 6f 66 66 73  nning at an offs
37160 65 74 20 6f 66 20 58 20 69 6e 74 6f 20 74 68 65  et of X into the
37170 20 62 6c 6f 62 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31   blob..**.** {F1
37180 37 38 37 35 7d 20 54 68 65 20 5b 73 71 6c 69 74  7875} The [sqlit
37190 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 50 2c  e3_blob_write(P,
371a0 5a 2c 4e 2c 58 29 5d 20 69 6e 74 65 72 66 61 63  Z,N,X)] interfac
371b0 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20  e returns.**    
371c0 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 52 45        [SQLITE_RE
371d0 41 44 4f 4e 4c 59 5d 20 69 66 20 74 68 65 20 5b  ADONLY] if the [
371e0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5d 20 6f 62  sqlite3_blob] ob
371f0 6a 65 63 74 20 50 20 77 61 73 0a 2a 2a 20 20 20  ject P was.**   
37200 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
37210 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 6f 70 65 6e  blob_open | open
37220 65 64 5d 20 66 6f 72 20 72 65 61 64 69 6e 67 20  ed] for reading 
37230 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37  only..**.** {F17
37240 38 37 36 7d 20 49 6e 20 5b 73 71 6c 69 74 65 33  876} In [sqlite3
37250 5f 62 6c 6f 62 5f 77 72 69 74 65 28 50 2c 5a 2c  _blob_write(P,Z,
37260 4e 2c 58 29 5d 20 69 66 20 74 68 65 20 73 69 7a  N,X)] if the siz
37270 65 20 6f 66 20 74 68 65 20 62 6c 6f 62 0a 2a 2a  e of the blob.**
37280 20 20 20 20 20 20 20 20 20 20 69 73 20 6c 65 73            is les
37290 73 20 74 68 61 6e 20 4e 2b 58 20 62 79 74 65 73  s than N+X bytes
372a0 2c 20 74 68 65 6e 20 74 68 65 20 66 75 6e 63 74  , then the funct
372b0 69 6f 6e 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ion returns [SQL
372c0 49 54 45 5f 45 52 52 4f 52 5d 0a 2a 2a 20 20 20  ITE_ERROR].**   
372d0 20 20 20 20 20 20 20 61 6e 64 20 6e 6f 74 68 69         and nothi
372e0 6e 67 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e  ng is written in
372f0 74 6f 20 74 68 65 20 62 6c 6f 62 2e 0a 2a 2a 0a  to the blob..**.
37300 2a 2a 20 7b 46 31 37 38 37 39 7d 20 49 6e 20 5b  ** {F17879} In [
37310 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69  sqlite3_blob_wri
37320 74 65 28 50 2c 5a 2c 4e 2c 58 29 5d 20 69 66 20  te(P,Z,N,X)] if 
37330 58 20 6f 72 20 4e 20 69 73 20 6c 65 73 73 20 74  X or N is less t
37340 68 61 6e 20 7a 65 72 6f 0a 2a 2a 20 20 20 20 20  han zero.**     
37350 20 20 20 20 20 74 68 65 6e 20 74 68 65 20 66 75       then the fu
37360 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 5b  nction returns [
37370 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 0a 2a 2a  SQLITE_ERROR].**
37380 20 20 20 20 20 20 20 20 20 20 61 6e 64 20 6e 6f            and no
37390 74 68 69 6e 67 20 69 73 20 77 72 69 74 74 65 6e  thing is written
373a0 20 69 6e 74 6f 20 74 68 65 20 62 6c 6f 62 2e 0a   into the blob..
373b0 2a 2a 0a 2a 2a 20 7b 46 31 37 38 38 32 7d 20 54  **.** {F17882} T
373c0 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  he [sqlite3_blob
373d0 5f 77 72 69 74 65 28 50 2c 5a 2c 4e 2c 58 29 5d  _write(P,Z,N,X)]
373e0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
373f0 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 0a 2a  ns [SQLITE_OK].*
37400 2a 20 20 20 20 20 20 20 20 20 20 69 66 20 4e 20  *          if N 
37410 62 79 74 65 73 20 77 68 65 72 65 20 73 75 63 63  bytes where succ
37420 65 73 73 66 75 6c 6c 79 20 77 72 69 74 74 65 6e  essfully written
37430 20 69 6e 74 6f 20 62 6c 6f 62 2e 0a 2a 2a 0a 2a   into blob..**.*
37440 2a 20 7b 46 31 37 38 38 35 7d 20 49 66 20 74 68  * {F17885} If th
37450 65 20 72 65 71 75 65 73 74 65 64 20 77 72 69 74  e requested writ
37460 65 20 63 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63  e could not be c
37470 6f 6d 70 6c 65 74 65 64 2c 0a 2a 2a 20 20 20 20  ompleted,.**    
37480 20 20 20 20 20 20 74 68 65 20 5b 73 71 6c 69 74        the [sqlit
37490 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 50 2c  e3_blob_write(P,
374a0 5a 2c 4e 2c 58 29 5d 20 69 6e 74 65 72 66 61 63  Z,N,X)] interfac
374b0 65 20 72 65 74 75 72 6e 73 20 61 6e 0a 2a 2a 20  e returns an.** 
374c0 20 20 20 20 20 20 20 20 20 61 70 70 72 6f 70 72           appropr
374d0 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65  iate [error code
374e0 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65  ] or [extended e
374f0 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a  rror code]..**.*
37500 2a 20 7b 46 31 37 38 38 38 7d 20 49 66 20 61 6e  * {F17888} If an
37510 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75   error occurs du
37520 72 69 6e 67 20 65 76 61 6c 75 61 74 69 6f 6e 20  ring evaluation 
37530 6f 66 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  of [sqlite3_blob
37540 5f 77 72 69 74 65 28 44 2c 2e 2e 2e 29 5d 0a 2a  _write(D,...)].*
37550 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20  *          then 
37560 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
37570 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72   to [sqlite3_err
37580 63 6f 64 65 28 44 29 5d 2c 0a 2a 2a 20 20 20 20  code(D)],.**    
37590 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 65        [sqlite3_e
375a0 72 72 6d 73 67 28 44 29 5d 2c 20 61 6e 64 20 5b  rrmsg(D)], and [
375b0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
375c0 28 44 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  (D)] will return
375d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 66  .**          inf
375e0 6f 72 6d 61 74 69 6f 6e 20 61 70 70 72 6f 70 72  ormation appropr
375f0 61 74 65 20 66 6f 72 20 74 68 61 74 20 65 72 72  ate for that err
37600 6f 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  or..*/.int sqlit
37610 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 73 71  e3_blob_write(sq
37620 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 2c 20 63 6f  lite3_blob *, co
37630 6e 73 74 20 76 6f 69 64 20 2a 7a 2c 20 69 6e 74  nst void *z, int
37640 20 6e 2c 20 69 6e 74 20 69 4f 66 66 73 65 74 29   n, int iOffset)
37650 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
37660 46 3a 20 20 56 69 72 74 75 61 6c 20 46 69 6c 65  F:  Virtual File
37670 20 53 79 73 74 65 6d 20 4f 62 6a 65 63 74 73 20   System Objects 
37680 7b 46 31 31 32 30 30 7d 0a 2a 2a 0a 2a 2a 20 41  {F11200}.**.** A
37690 20 76 69 72 74 75 61 6c 20 66 69 6c 65 73 79 73   virtual filesys
376a0 74 65 6d 20 28 56 46 53 29 20 69 73 20 61 6e 20  tem (VFS) is an 
376b0 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
376c0 6a 65 63 74 0a 2a 2a 20 74 68 61 74 20 53 51 4c  ject.** that SQL
376d0 69 74 65 20 75 73 65 73 20 74 6f 20 69 6e 74 65  ite uses to inte
376e0 72 61 63 74 0a 2a 2a 20 77 69 74 68 20 74 68 65  ract.** with the
376f0 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72   underlying oper
37700 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 4d  ating system.  M
37710 6f 73 74 20 53 51 4c 69 74 65 20 62 75 69 6c 64  ost SQLite build
37720 73 20 63 6f 6d 65 20 77 69 74 68 20 61 0a 2a 2a  s come with a.**
37730 20 73 69 6e 67 6c 65 20 64 65 66 61 75 6c 74 20   single default 
37740 56 46 53 20 74 68 61 74 20 69 73 20 61 70 70 72  VFS that is appr
37750 6f 70 72 69 61 74 65 20 66 6f 72 20 74 68 65 20  opriate for the 
37760 68 6f 73 74 20 63 6f 6d 70 75 74 65 72 2e 0a 2a  host computer..*
37770 2a 20 4e 65 77 20 56 46 53 65 73 20 63 61 6e 20  * New VFSes can 
37780 62 65 20 72 65 67 69 73 74 65 72 65 64 20 61 6e  be registered an
37790 64 20 65 78 69 73 74 69 6e 67 20 56 46 53 65 73  d existing VFSes
377a0 20 63 61 6e 20 62 65 20 75 6e 72 65 67 69 73 74   can be unregist
377b0 65 72 65 64 2e 0a 2a 2a 20 54 68 65 20 66 6f 6c  ered..** The fol
377c0 6c 6f 77 69 6e 67 20 69 6e 74 65 72 66 61 63 65  lowing interface
377d0 73 20 61 72 65 20 70 72 6f 76 69 64 65 64 2e 0a  s are provided..
377e0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
377f0 33 5f 76 66 73 5f 66 69 6e 64 28 29 20 69 6e 74  3_vfs_find() int
37800 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
37810 20 70 6f 69 6e 74 65 72 20 74 6f 20 0a 2a 2a 20   pointer to .** 
37820 61 20 56 46 53 20 67 69 76 65 6e 20 69 74 73 20  a VFS given its 
37830 6e 61 6d 65 2e 20 20 4e 61 6d 65 73 20 61 72 65  name.  Names are
37840 20 63 61 73 65 20 73 65 6e 73 69 74 69 76 65 2e   case sensitive.
37850 0a 2a 2a 20 4e 61 6d 65 73 20 61 72 65 20 7a 65  .** Names are ze
37860 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
37870 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20  F-8 strings..** 
37880 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 6d  If there is no m
37890 61 74 63 68 2c 20 61 20 4e 55 4c 4c 0a 2a 2a 20  atch, a NULL.** 
378a0 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72  pointer is retur
378b0 6e 65 64 2e 20 20 49 66 20 7a 56 66 73 4e 61 6d  ned.  If zVfsNam
378c0 65 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74  e is NULL then t
378d0 68 65 20 64 65 66 61 75 6c 74 20 0a 2a 2a 20 56  he default .** V
378e0 46 53 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  FS is returned. 
378f0 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 56 46 53 65 73  .**.** New VFSes
37900 20 61 72 65 20 72 65 67 69 73 74 65 72 65 64 20   are registered 
37910 77 69 74 68 20 73 71 6c 69 74 65 33 5f 76 66 73  with sqlite3_vfs
37920 5f 72 65 67 69 73 74 65 72 28 29 2e 0a 2a 2a 20  _register()..** 
37930 45 61 63 68 20 6e 65 77 20 56 46 53 20 62 65 63  Each new VFS bec
37940 6f 6d 65 73 20 74 68 65 20 64 65 66 61 75 6c 74  omes the default
37950 20 56 46 53 20 69 66 20 74 68 65 20 6d 61 6b 65   VFS if the make
37960 44 66 6c 74 20 66 6c 61 67 20 69 73 20 73 65 74  Dflt flag is set
37970 2e 0a 2a 2a 20 54 68 65 20 73 61 6d 65 20 56 46  ..** The same VF
37980 53 20 63 61 6e 20 62 65 20 72 65 67 69 73 74 65  S can be registe
37990 72 65 64 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d  red multiple tim
379a0 65 73 20 77 69 74 68 6f 75 74 20 69 6e 6a 75 72  es without injur
379b0 79 2e 0a 2a 2a 20 54 6f 20 6d 61 6b 65 20 61 6e  y..** To make an
379c0 20 65 78 69 73 74 69 6e 67 20 56 46 53 20 69 6e   existing VFS in
379d0 74 6f 20 74 68 65 20 64 65 66 61 75 6c 74 20 56  to the default V
379e0 46 53 2c 20 72 65 67 69 73 74 65 72 20 69 74 20  FS, register it 
379f0 61 67 61 69 6e 0a 2a 2a 20 77 69 74 68 20 74 68  again.** with th
37a00 65 20 6d 61 6b 65 44 66 6c 74 20 66 6c 61 67 20  e makeDflt flag 
37a10 73 65 74 2e 20 20 49 66 20 74 77 6f 20 64 69 66  set.  If two dif
37a20 66 65 72 65 6e 74 20 56 46 53 65 73 20 77 69 74  ferent VFSes wit
37a30 68 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20 6e 61  h the.** same na
37a40 6d 65 20 61 72 65 20 72 65 67 69 73 74 65 72 65  me are registere
37a50 64 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  d, the behavior 
37a60 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 49  is undefined.  I
37a70 66 20 61 0a 2a 2a 20 56 46 53 20 69 73 20 72 65  f a.** VFS is re
37a80 67 69 73 74 65 72 65 64 20 77 69 74 68 20 61 20  gistered with a 
37a90 6e 61 6d 65 20 74 68 61 74 20 69 73 20 4e 55 4c  name that is NUL
37aa0 4c 20 6f 72 20 61 6e 20 65 6d 70 74 79 20 73 74  L or an empty st
37ab0 72 69 6e 67 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  ring,.** then th
37ac0 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e  e behavior is un
37ad0 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a 20  defined..** .** 
37ae0 55 6e 72 65 67 69 73 74 65 72 20 61 20 56 46 53  Unregister a VFS
37af0 20 77 69 74 68 20 74 68 65 20 73 71 6c 69 74 65   with the sqlite
37b00 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72  3_vfs_unregister
37b10 28 29 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  () interface..**
37b20 20 49 66 20 74 68 65 20 64 65 66 61 75 6c 74 20   If the default 
37b30 56 46 53 20 69 73 20 75 6e 72 65 67 69 73 74 65  VFS is unregiste
37b40 72 65 64 2c 20 61 6e 6f 74 68 65 72 20 56 46 53  red, another VFS
37b50 20 69 73 20 63 68 6f 73 65 6e 20 61 73 0a 2a 2a   is chosen as.**
37b60 20 74 68 65 20 64 65 66 61 75 6c 74 2e 20 20 54   the default.  T
37b70 68 65 20 63 68 6f 69 63 65 20 66 6f 72 20 74 68  he choice for th
37b80 65 20 6e 65 77 20 56 46 53 20 69 73 20 61 72 62  e new VFS is arb
37b90 69 74 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 4e  itrary..**.** IN
37ba0 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
37bb0 7b 46 31 31 32 30 33 7d 20 54 68 65 20 5b 73 71  {F11203} The [sq
37bc0 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 4e  lite3_vfs_find(N
37bd0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
37be0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
37bf0 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  o the.**        
37c00 20 20 72 65 67 69 73 74 65 72 65 64 20 5b 73 71    registered [sq
37c10 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
37c20 74 20 77 68 6f 73 65 20 6e 61 6d 65 20 65 78 61  t whose name exa
37c30 63 74 6c 79 20 6d 61 74 63 68 65 73 0a 2a 2a 20  ctly matches.** 
37c40 20 20 20 20 20 20 20 20 20 74 68 65 20 7a 65 72           the zer
37c50 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
37c60 2d 38 20 73 74 72 69 6e 67 20 4e 2c 20 6f 72 20  -8 string N, or 
37c70 69 74 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20  it returns NULL 
37c80 69 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  if.**          t
37c90 68 65 72 65 20 69 73 20 6e 6f 20 6d 61 74 63 68  here is no match
37ca0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 32 30 36 7d  ..**.** {F11206}
37cb0 20 49 66 20 74 68 65 20 4e 20 70 61 72 61 6d 65   If the N parame
37cc0 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
37cd0 76 66 73 5f 66 69 6e 64 28 4e 29 5d 20 69 73 20  vfs_find(N)] is 
37ce0 4e 55 4c 4c 20 74 68 65 6e 0a 2a 2a 20 20 20 20  NULL then.**    
37cf0 20 20 20 20 20 20 74 68 65 20 66 75 6e 63 74 69        the functi
37d00 6f 6e 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  on returns a poi
37d10 6e 74 65 72 20 74 6f 20 74 68 65 20 64 65 66 61  nter to the defa
37d20 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  ult [sqlite3_vfs
37d30 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 62  ].**          ob
37d40 6a 65 63 74 20 69 66 20 74 68 65 72 65 20 69 73  ject if there is
37d50 20 6f 6e 65 2c 20 6f 72 20 4e 55 4c 4c 20 69 66   one, or NULL if
37d60 20 74 68 65 72 65 20 69 73 20 6e 6f 20 64 65 66   there is no def
37d70 61 75 6c 74 20 0a 2a 2a 20 20 20 20 20 20 20 20  ault .**        
37d80 20 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20    [sqlite3_vfs] 
37d90 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46  object..**.** {F
37da0 31 31 32 30 39 7d 20 54 68 65 20 5b 73 71 6c 69  11209} The [sqli
37db0 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72  te3_vfs_register
37dc0 28 50 2c 46 29 5d 20 69 6e 74 65 72 66 61 63 65  (P,F)] interface
37dd0 20 72 65 67 69 73 74 65 72 73 20 74 68 65 0a 2a   registers the.*
37de0 2a 20 20 20 20 20 20 20 20 20 20 77 65 6c 6c 2d  *          well-
37df0 66 6f 72 6d 65 64 20 5b 73 71 6c 69 74 65 33 5f  formed [sqlite3_
37e00 76 66 73 5d 20 6f 62 6a 65 63 74 20 50 20 75 73  vfs] object P us
37e10 69 6e 67 20 74 68 65 20 6e 61 6d 65 20 67 69 76  ing the name giv
37e20 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62  en.**          b
37e30 79 20 74 68 65 20 7a 4e 61 6d 65 20 66 69 65 6c  y the zName fiel
37e40 64 20 6f 66 20 74 68 65 20 6f 62 6a 65 63 74 2e  d of the object.
37e50 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 32 31 32 7d 20  .**.** {F11212} 
37e60 55 73 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74  Using the [sqlit
37e70 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28  e3_vfs_register(
37e80 50 2c 46 29 5d 20 69 6e 74 65 72 66 61 63 65 20  P,F)] interface 
37e90 74 6f 20 72 65 67 69 73 74 65 72 0a 2a 2a 20 20  to register.**  
37ea0 20 20 20 20 20 20 20 20 74 68 65 20 73 61 6d 65          the same
37eb0 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
37ec0 62 6a 65 63 74 20 6d 75 6c 74 69 70 6c 65 20 74  bject multiple t
37ed0 69 6d 65 73 20 69 73 20 61 20 68 61 72 6d 6c 65  imes is a harmle
37ee0 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20  ss no-op..**.** 
37ef0 7b 46 31 31 32 31 35 7d 20 54 68 65 20 5b 73 71  {F11215} The [sq
37f00 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74  lite3_vfs_regist
37f10 65 72 28 50 2c 46 29 5d 20 69 6e 74 65 72 66 61  er(P,F)] interfa
37f20 63 65 20 6d 61 6b 65 73 20 74 68 65 0a 2a 2a 20  ce makes the.** 
37f30 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 73 71           the [sq
37f40 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
37f50 74 20 50 20 74 68 65 20 64 65 66 61 75 6c 74 20  t P the default 
37f60 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
37f70 6a 65 63 74 0a 2a 2a 20 20 20 20 20 20 20 20 20  ject.**         
37f80 20 69 66 20 46 20 69 73 20 6e 6f 6e 2d 7a 65 72   if F is non-zer
37f90 6f 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 32 31 38  o..**.** {F11218
37fa0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  } The [sqlite3_v
37fb0 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 50 29  fs_unregister(P)
37fc0 5d 20 69 6e 74 65 72 66 61 63 65 20 75 6e 72 65  ] interface unre
37fd0 67 69 73 74 65 72 73 20 74 68 65 0a 2a 2a 20 20  gisters the.**  
37fe0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
37ff0 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 50 20 73  _vfs] object P s
38000 6f 20 74 68 61 74 20 69 74 20 69 73 20 6e 6f 20  o that it is no 
38010 6c 6f 6e 67 65 72 20 72 65 74 75 72 6e 65 64 20  longer returned 
38020 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73  by.**          s
38030 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
38040 74 6f 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f  to [sqlite3_vfs_
38050 66 69 6e 64 28 29 5d 2e 0a 2a 2f 0a 73 71 6c 69  find()]..*/.sqli
38060 74 65 33 5f 76 66 73 20 2a 73 71 6c 69 74 65 33  te3_vfs *sqlite3
38070 5f 76 66 73 5f 66 69 6e 64 28 63 6f 6e 73 74 20  _vfs_find(const 
38080 63 68 61 72 20 2a 7a 56 66 73 4e 61 6d 65 29 3b  char *zVfsName);
38090 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 66 73  .int sqlite3_vfs
380a0 5f 72 65 67 69 73 74 65 72 28 73 71 6c 69 74 65  _register(sqlite
380b0 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 61 6b 65  3_vfs*, int make
380c0 44 66 6c 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74  Dflt);.int sqlit
380d0 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65  e3_vfs_unregiste
380e0 72 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 29 3b  r(sqlite3_vfs*);
380f0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
38100 3a 20 4d 75 74 65 78 65 73 20 7b 46 31 37 30 30  : Mutexes {F1700
38110 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  0}.**.** The SQL
38120 69 74 65 20 63 6f 72 65 20 75 73 65 73 20 74 68  ite core uses th
38130 65 73 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72  ese routines for
38140 20 74 68 72 65 61 64 0a 2a 2a 20 73 79 6e 63 68   thread.** synch
38150 72 6f 6e 69 7a 61 74 69 6f 6e 2e 20 20 54 68 6f  ronization.  Tho
38160 75 67 68 20 74 68 65 79 20 61 72 65 20 69 6e 74  ugh they are int
38170 65 6e 64 65 64 20 66 6f 72 20 69 6e 74 65 72 6e  ended for intern
38180 61 6c 0a 2a 2a 20 75 73 65 20 62 79 20 53 51 4c  al.** use by SQL
38190 69 74 65 2c 20 63 6f 64 65 20 74 68 61 74 20 6c  ite, code that l
381a0 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 53 51 4c  inks against SQL
381b0 69 74 65 20 69 73 0a 2a 2a 20 70 65 72 6d 69 74  ite is.** permit
381c0 74 65 64 20 74 6f 20 75 73 65 20 61 6e 79 20 6f  ted to use any o
381d0 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
381e0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69  ..**.** The SQLi
381f0 74 65 20 73 6f 75 72 63 65 20 63 6f 64 65 20 63  te source code c
38200 6f 6e 74 61 69 6e 73 20 6d 75 6c 74 69 70 6c 65  ontains multiple
38210 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
38220 20 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 6d 75   .** of these mu
38230 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 20 20 41  tex routines.  A
38240 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 69 6d  n appropriate im
38250 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20  plementation.** 
38260 69 73 20 73 65 6c 65 63 74 65 64 20 61 75 74 6f  is selected auto
38270 6d 61 74 69 63 61 6c 6c 79 20 61 74 20 63 6f 6d  matically at com
38280 70 69 6c 65 2d 74 69 6d 65 2e 20 20 54 68 65 20  pile-time.  The 
38290 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 69 6d 70  following.** imp
382a0 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 61 72 65  lementations are
382b0 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68   available in th
382c0 65 20 53 51 4c 69 74 65 20 63 6f 72 65 3a 0a 2a  e SQLite core:.*
382d0 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
382e0 3e 20 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  >   SQLITE_MUTEX
382f0 5f 4f 53 32 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53  _OS2.** <li>   S
38300 51 4c 49 54 45 5f 4d 55 54 45 58 5f 50 54 48 52  QLITE_MUTEX_PTHR
38310 45 41 44 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51  EAD.** <li>   SQ
38320 4c 49 54 45 5f 4d 55 54 45 58 5f 57 33 32 0a 2a  LITE_MUTEX_W32.*
38330 2a 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f  * <li>   SQLITE_
38340 4d 55 54 45 58 5f 4e 4f 4f 50 0a 2a 2a 20 3c 2f  MUTEX_NOOP.** </
38350 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  ul>.**.** The SQ
38360 4c 49 54 45 5f 4d 55 54 45 58 5f 4e 4f 4f 50 20  LITE_MUTEX_NOOP 
38370 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
38380 73 20 61 20 73 65 74 20 6f 66 20 72 6f 75 74 69  s a set of routi
38390 6e 65 73 20 0a 2a 2a 20 74 68 61 74 20 64 6f 65  nes .** that doe
383a0 73 20 6e 6f 20 72 65 61 6c 20 6c 6f 63 6b 69 6e  s no real lockin
383b0 67 20 61 6e 64 20 69 73 20 61 70 70 72 6f 70 72  g and is appropr
383c0 69 61 74 65 20 66 6f 72 20 75 73 65 20 69 6e 20  iate for use in 
383d0 0a 2a 2a 20 61 20 73 69 6e 67 6c 65 2d 74 68 72  .** a single-thr
383e0 65 61 64 65 64 20 61 70 70 6c 69 63 61 74 69 6f  eaded applicatio
383f0 6e 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4d  n.  The SQLITE_M
38400 55 54 45 58 5f 4f 53 32 2c 0a 2a 2a 20 53 51 4c  UTEX_OS2,.** SQL
38410 49 54 45 5f 4d 55 54 45 58 5f 50 54 48 52 45 41  ITE_MUTEX_PTHREA
38420 44 2c 20 61 6e 64 20 53 51 4c 49 54 45 5f 4d 55  D, and SQLITE_MU
38430 54 45 58 5f 57 33 32 20 69 6d 70 6c 65 6d 65 6e  TEX_W32 implemen
38440 74 61 74 69 6f 6e 73 0a 2a 2a 20 61 72 65 20 61  tations.** are a
38450 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72 20 75  ppropriate for u
38460 73 65 20 6f 6e 20 6f 73 2f 32 2c 20 75 6e 69 78  se on os/2, unix
38470 2c 20 61 6e 64 20 77 69 6e 64 6f 77 73 2e 0a 2a  , and windows..*
38480 2a 20 0a 2a 2a 20 49 66 20 53 51 4c 69 74 65 20  * .** If SQLite 
38490 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
384a0 20 74 68 65 20 53 51 4c 49 54 45 5f 4d 55 54 45   the SQLITE_MUTE
384b0 58 5f 41 50 50 44 45 46 20 70 72 65 70 72 6f 63  X_APPDEF preproc
384c0 65 73 73 6f 72 0a 2a 2a 20 6d 61 63 72 6f 20 64  essor.** macro d
384d0 65 66 69 6e 65 64 20 28 77 69 74 68 20 22 2d 44  efined (with "-D
384e0 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 41 50 50  SQLITE_MUTEX_APP
384f0 44 45 46 3d 31 22 29 2c 20 74 68 65 6e 20 6e 6f  DEF=1"), then no
38500 20 6d 75 74 65 78 0a 2a 2a 20 69 6d 70 6c 65 6d   mutex.** implem
38510 65 6e 74 61 74 69 6f 6e 20 69 73 20 69 6e 63 6c  entation is incl
38520 75 64 65 64 20 77 69 74 68 20 74 68 65 20 6c 69  uded with the li
38530 62 72 61 72 79 2e 20 20 54 68 65 0a 2a 2a 20 6d  brary.  The.** m
38540 75 74 65 78 20 69 6e 74 65 72 66 61 63 65 20 72  utex interface r
38550 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20  outines defined 
38560 68 65 72 65 20 62 65 63 6f 6d 65 20 65 78 74 65  here become exte
38570 72 6e 61 6c 0a 2a 2a 20 72 65 66 65 72 65 6e 63  rnal.** referenc
38580 65 73 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65  es in the SQLite
38590 20 6c 69 62 72 61 72 79 20 66 6f 72 20 77 68 69   library for whi
385a0 63 68 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ch implementatio
385b0 6e 73 0a 2a 2a 20 6d 75 73 74 20 62 65 20 70 72  ns.** must be pr
385c0 6f 76 69 64 65 64 20 62 79 20 74 68 65 20 61 70  ovided by the ap
385d0 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 69 73  plication.  This
385e0 20 66 61 63 69 6c 69 74 79 20 61 6c 6c 6f 77 73   facility allows
385f0 20 61 6e 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69   an.** applicati
38600 6f 6e 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67  on that links ag
38610 61 69 6e 73 74 20 53 51 4c 69 74 65 20 74 6f 20  ainst SQLite to 
38620 70 72 6f 76 69 64 65 20 69 74 73 20 6f 77 6e 20  provide its own 
38630 6d 75 74 65 78 0a 2a 2a 20 69 6d 70 6c 65 6d 65  mutex.** impleme
38640 6e 74 61 74 69 6f 6e 20 77 69 74 68 6f 75 74 20  ntation without 
38650 68 61 76 69 6e 67 20 74 6f 20 6d 6f 64 69 66 79  having to modify
38660 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   the SQLite core
38670 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 30 31 31 7d  ..**.** {F17011}
38680 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74   The sqlite3_mut
38690 65 78 5f 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69  ex_alloc() routi
386a0 6e 65 20 61 6c 6c 6f 63 61 74 65 73 20 61 20 6e  ne allocates a n
386b0 65 77 0a 2a 2a 20 6d 75 74 65 78 20 61 6e 64 20  ew.** mutex and 
386c0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
386d0 72 20 74 6f 20 69 74 2e 20 7b 46 31 37 30 31 32  r to it. {F17012
386e0 7d 20 49 66 20 69 74 20 72 65 74 75 72 6e 73 20  } If it returns 
386f0 4e 55 4c 4c 0a 2a 2a 20 74 68 61 74 20 6d 65 61  NULL.** that mea
38700 6e 73 20 74 68 61 74 20 61 20 6d 75 74 65 78 20  ns that a mutex 
38710 63 6f 75 6c 64 20 6e 6f 74 20 62 65 20 61 6c 6c  could not be all
38720 6f 63 61 74 65 64 2e 20 7b 46 31 37 30 31 33 7d  ocated. {F17013}
38730 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20   SQLite.** will 
38740 75 6e 77 69 6e 64 20 69 74 73 20 73 74 61 63 6b  unwind its stack
38750 20 61 6e 64 20 72 65 74 75 72 6e 20 61 6e 20 65   and return an e
38760 72 72 6f 72 2e 20 7b 46 31 37 30 31 34 7d 20 54  rror. {F17014} T
38770 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74  he argument.** t
38780 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  o sqlite3_mutex_
38790 61 6c 6c 6f 63 28 29 20 69 73 20 6f 6e 65 20 6f  alloc() is one o
387a0 66 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20  f these integer 
387b0 63 6f 6e 73 74 61 6e 74 73 3a 0a 2a 2a 0a 2a 2a  constants:.**.**
387c0 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53   <ul>.** <li>  S
387d0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54  QLITE_MUTEX_FAST
387e0 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
387f0 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56 45  _MUTEX_RECURSIVE
38800 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
38810 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 41  _MUTEX_STATIC_MA
38820 53 54 45 52 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51  STER.** <li>  SQ
38830 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
38840 43 5f 4d 45 4d 0a 2a 2a 20 3c 6c 69 3e 20 20 53  C_MEM.** <li>  S
38850 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54  QLITE_MUTEX_STAT
38860 49 43 5f 4d 45 4d 32 0a 2a 2a 20 3c 6c 69 3e 20  IC_MEM2.** <li> 
38870 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54   SQLITE_MUTEX_ST
38880 41 54 49 43 5f 50 52 4e 47 0a 2a 2a 20 3c 6c 69  ATIC_PRNG.** <li
38890 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  >  SQLITE_MUTEX_
388a0 53 54 41 54 49 43 5f 4c 52 55 0a 2a 2a 20 3c 2f  STATIC_LRU.** </
388b0 75 6c 3e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20  ul> {END}.**.** 
388c0 7b 46 31 37 30 31 35 7d 20 54 68 65 20 66 69 72  {F17015} The fir
388d0 73 74 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73  st two constants
388e0 20 63 61 75 73 65 20 73 71 6c 69 74 65 33 5f 6d   cause sqlite3_m
388f0 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20 74 6f 20  utex_alloc() to 
38900 63 72 65 61 74 65 0a 2a 2a 20 61 20 6e 65 77 20  create.** a new 
38910 6d 75 74 65 78 2e 20 20 54 68 65 20 6e 65 77 20  mutex.  The new 
38920 6d 75 74 65 78 20 69 73 20 72 65 63 75 72 73 69  mutex is recursi
38930 76 65 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 4d  ve when SQLITE_M
38940 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 0a 2a  UTEX_RECURSIVE.*
38950 2a 20 69 73 20 75 73 65 64 20 62 75 74 20 6e 6f  * is used but no
38960 74 20 6e 65 63 65 73 73 61 72 69 6c 79 20 73 6f  t necessarily so
38970 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 4d 55 54   when SQLITE_MUT
38980 45 58 5f 46 41 53 54 20 69 73 20 75 73 65 64 2e  EX_FAST is used.
38990 20 7b 45 4e 44 7d 0a 2a 2a 20 54 68 65 20 6d 75   {END}.** The mu
389a0 74 65 78 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  tex implementati
389b0 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  on does not need
389c0 20 74 6f 20 6d 61 6b 65 20 61 20 64 69 73 74 69   to make a disti
389d0 6e 63 74 6