/ Hex Artifact Content
Login

Artifact b18c4cb006f16237aa044200ddd6a16cf4b7457c:


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 38 20 32 30 30 38 2f  in,v 1.298 2008/
05f0: 30 33 2f 32 30 20 31 38 3a 30 30 3a 34 39 20 64  03/20 18:00:49 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 50 73 65 75 64 6f 2d 52 61 6e 64  REF: Pseudo-Rand
10d90 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 72 61  om Number Genera
10da0 74 6f 72 20 7b 46 31 37 33 39 30 7d 0a 2a 2a 0a  tor {F17390}.**.
10db0 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69  ** SQLite contai
10dc0 6e 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74  ns a high-qualit
10dd0 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20  y pseudo-random 
10de0 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72  number generator
10df0 20 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a   (PRNG) used to.
10e00 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d  ** select random
10e10 20 52 4f 57 49 44 73 20 77 68 65 6e 20 69 6e 73   ROWIDs when ins
10e20 65 72 74 69 6e 67 20 6e 65 77 20 72 65 63 6f 72  erting new recor
10e30 64 73 20 69 6e 74 6f 20 61 20 74 61 62 6c 65 20  ds into a table 
10e40 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20  that.** already 
10e50 75 73 65 73 20 74 68 65 20 6c 61 72 67 65 73 74  uses the largest
10e60 20 70 6f 73 73 69 62 6c 65 20 52 4f 57 49 44 2e   possible ROWID.
10e70 20 20 54 68 65 20 50 52 4e 47 20 69 73 20 61 6c    The PRNG is al
10e80 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74  so used for.** t
10e90 68 65 20 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64  he build-in rand
10ea0 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62  om() and randomb
10eb0 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e 63 74 69  lob() SQL functi
10ec0 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e 74 65 72  ons.  This inter
10ed0 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61  face allows.** a
10ee0 70 70 6c 69 61 74 69 6f 6e 73 20 74 6f 20 61 63  ppliations to ac
10ef0 63 65 73 73 20 74 68 65 20 73 61 6d 65 20 50 52  cess the same PR
10f00 4e 47 20 66 6f 72 20 6f 74 68 65 72 20 70 75 72  NG for other pur
10f10 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63  poses..**.** A c
10f20 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74  all to this rout
10f30 69 6e 65 20 73 74 6f 72 65 73 20 4e 20 62 79 74  ine stores N byt
10f40 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73  es of randomness
10f50 20 69 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a   into buffer P..
10f60 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
10f70 74 69 6d 65 20 74 68 69 73 20 72 6f 75 74 69 6e  time this routin
10f80 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 65 69  e is invoked (ei
10f90 74 68 65 72 20 69 6e 74 65 72 6e 61 6c 6c 79 20  ther internally 
10fa0 6f 72 20 62 79 0a 2a 2a 20 74 68 65 20 61 70 70  or by.** the app
10fb0 6c 69 63 61 74 69 6f 6e 29 20 74 68 65 20 50 52  lication) the PR
10fc0 4e 47 20 69 73 20 73 65 65 64 65 64 20 75 73 69  NG is seeded usi
10fd0 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62  ng randomness ob
10fe0 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 74  tained.** from t
10ff0 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d  he xRandomness m
11000 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66  ethod of the def
11010 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
11020 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 4f 6e  s] object..** On
11030 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20   all subsequent 
11040 69 6e 76 6f 63 61 74 69 6f 6e 73 2c 20 74 68 65  invocations, the
11050 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65   pseudo-randomne
11060 73 73 20 69 73 20 67 65 6e 65 72 61 74 65 64 0a  ss is generated.
11070 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61 6e  ** internally an
11080 64 20 77 69 74 68 6f 75 74 20 72 65 63 6f 75 72  d without recour
11090 73 65 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  se to the [sqlit
110a0 65 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d 6e  e3_vfs] xRandomn
110b0 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a  ess.** method..*
110c0 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
110d0 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 39 32 7d 20  .**.** {F17392} 
110e0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 61 6e  The [sqlite3_ran
110f0 64 6f 6d 6e 65 73 73 28 4e 2c 50 29 5d 20 69 6e  domness(N,P)] in
11100 74 65 72 66 61 63 65 20 77 72 69 74 65 73 20 4e  terface writes N
11110 20 62 79 74 65 73 20 6f 66 0a 2a 2a 20 20 20 20   bytes of.**    
11120 20 20 20 20 20 20 68 69 67 68 2d 71 75 61 6c 69        high-quali
11130 74 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d  ty pseudo-random
11140 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66 65 72  ness into buffer
11150 20 50 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69   P..*/.void sqli
11160 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69  te3_randomness(i
11170 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a  nt N, void *P);.
11180 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
11190 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75   Compile-Time Au
111a0 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c  thorization Call
111b0 62 61 63 6b 73 20 7b 46 31 32 35 30 30 7d 0a 2a  backs {F12500}.*
111c0 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
111d0 65 20 72 65 67 69 73 74 65 72 73 20 61 20 61 75  e registers a au
111e0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
111f0 6b 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75  k with a particu
11200 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  lar.** [database
11210 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75   connection], su
11220 70 70 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69  pplied in the fi
11230 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  rst argument..**
11240 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   The authorizer 
11250 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
11260 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61 74 65  ked as SQL state
11270 6d 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20  ments are being 
11280 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b  compiled.** by [
11290 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
112a0 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e  )] or its varian
112b0 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ts [sqlite3_prep
112c0 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73  are_v2()],.** [s
112d0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
112e0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
112f0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
11300 2e 20 20 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a  .  At various.**
11310 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74   points during t
11320 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70  he compilation p
11330 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63  rocess, as logic
11340 20 69 73 20 62 65 69 6e 67 20 63 72 65 61 74 65   is being create
11350 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20  d.** to perform 
11360 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c  various actions,
11370 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
11380 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
11390 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66  ked to.** see if
113a0 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61   those actions a
113b0 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 54 68 65  re allowed.  The
113c0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
113d0 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72  back should.** r
113e0 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b  eturn [SQLITE_OK
113f0 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61  ] to allow the a
11400 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49  ction, [SQLITE_I
11410 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c  GNORE] to disall
11420 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66  ow the.** specif
11430 69 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c  ic action but al
11440 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61 74  low the SQL stat
11450 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75  ement to continu
11460 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69  e to be.** compi
11470 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  led, or [SQLITE_
11480 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 74  DENY] to cause t
11490 68 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73 74  he entire SQL st
114a0 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a  atement to be.**
114b0 20 72 65 6a 65 63 74 65 64 20 77 69 74 68 20 61   rejected with a
114c0 6e 20 65 72 72 6f 72 2e 20 20 20 49 66 20 74 68  n error.   If th
114d0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
114e0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a  lback returns.**
114f0 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72   any value other
11500 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47   than [SQLITE_IG
11510 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f  NORE], [SQLITE_O
11520 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  K], or [SQLITE_D
11530 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 5b 73 71  ENY].** then [sq
11540 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
11550 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e  ()] or equivalen
11560 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67  t call that trig
11570 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 75 74  gered.** the aut
11580 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69  horizer will fai
11590 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20  l with an error 
115a0 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57  message..**.** W
115b0 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
115c0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
115d0 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73  _OK], that means
115e0 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a   the operation.*
115f0 2a 20 72 65 71 75 65 73 74 65 64 20 69 73 20 6f  * requested is o
11600 6b 2e 20 20 57 68 65 6e 20 74 68 65 20 63 61 6c  k.  When the cal
11610 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53  lback returns [S
11620 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65  QLITE_DENY], the
11630 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
11640 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71  pare_v2()] or eq
11650 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68  uivalent call th
11660 61 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65  at triggered the
11670 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 77  .** authorizer w
11680 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e  ill fail with an
11690 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 65   error message e
116a0 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a  xplaining that.*
116b0 2a 20 61 63 63 65 73 73 20 69 73 20 64 65 6e 69  * access is deni
116c0 65 64 2e 20 20 49 66 20 74 68 65 20 61 75 74 68  ed.  If the auth
116d0 6f 72 69 7a 65 72 20 63 6f 64 65 20 69 73 20 5b  orizer code is [
116e0 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20  SQLITE_READ].** 
116f0 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  and the callback
11700 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
11710 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68  _IGNORE] then th
11720 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
11730 74 61 74 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d  tatement] statem
11740 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74  ent is construct
11750 65 64 20 74 6f 20 73 75 62 73 74 69 74 75 74 65  ed to substitute
11760 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65  .** a NULL value
11770 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65   in place of the
11780 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68   table column th
11790 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a  at would have.**
117a0 20 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53   been read if [S
117b0 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65  QLITE_OK] had be
117c0 65 6e 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68  en returned.  Th
117d0 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  e [SQLITE_IGNORE
117e0 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e 20  ].** return can 
117f0 62 65 20 75 73 65 64 20 74 6f 20 64 65 6e 79 20  be used to deny 
11800 61 6e 20 75 6e 74 72 75 73 74 65 64 20 75 73 65  an untrusted use
11810 72 20 61 63 63 65 73 73 20 74 6f 20 69 6e 64 69  r access to indi
11820 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e  vidual.** column
11830 73 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a  s of a table..**
11840 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61  .** The first pa
11850 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61  rameter to the a
11860 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
11870 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 0a  ck is a copy of.
11880 2a 2a 20 74 68 65 20 74 68 69 72 64 20 70 61 72  ** the third par
11890 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
118a0 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
118b0 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61 63 65  izer() interface
118c0 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
118d0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
118e0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
118f0 69 6e 74 65 67 65 72 20 0a 2a 2a 20 5b 53 51 4c  integer .** [SQL
11900 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f  ITE_COPY | actio
11910 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65  n code] that spe
11920 63 69 66 69 65 73 20 74 68 65 20 70 61 72 74 69  cifies the parti
11930 63 75 6c 61 72 20 61 63 74 69 6f 6e 0a 2a 2a 20  cular action.** 
11940 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64  to be authorized
11950 2e 20 54 68 65 20 74 68 69 72 64 20 74 68 72 6f  . The third thro
11960 75 67 68 20 73 69 78 74 68 0a 2a 2a 20 70 61 72  ugh sixth.** par
11970 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20 63  ameters to the c
11980 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65 72 6f  allback are zero
11990 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69  -terminated stri
119a0 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e  ngs that contain
119b0 20 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20   .** additional 
119c0 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68  details about th
119d0 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  e action to be a
119e0 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a  uthorized..**.**
119f0 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 69   An authorizer i
11a00 73 20 75 73 65 64 20 77 68 65 6e 20 5b 73 71 6c  s used when [sql
11a10 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70  ite3_prepare | p
11a20 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c  reparing].** SQL
11a30 20 73 74 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d   statements from
11a40 20 61 6e 20 75 6e 74 72 75 73 74 65 64 0a 2a 2a   an untrusted.**
11a50 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73 75   source, to ensu
11a60 72 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 20  re that the SQL 
11a70 73 74 61 74 65 6d 65 6e 74 73 20 64 6f 20 6e 6f  statements do no
11a80 74 20 74 72 79 20 74 6f 20 61 63 63 65 73 73 20  t try to access 
11a90 64 61 74 61 0a 2a 2a 20 74 68 61 74 20 74 68 65  data.** that the
11aa0 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65  y are not allowe
11ab0 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61  d to see, or tha
11ac0 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 20 74 72  t they do not tr
11ad0 79 20 74 6f 0a 2a 2a 20 65 78 65 63 75 74 65 20  y to.** execute 
11ae0 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d  malicious statem
11af0 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67 65  ents that damage
11b00 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 20   the database.  
11b10 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20  For.** example, 
11b20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  an application m
11b30 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20  ay allow a user 
11b40 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72 61  to enter arbitra
11b50 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65  ry.** SQL querie
11b60 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e  s for evaluation
11b70 20 62 79 20 61 20 64 61 74 61 62 61 73 65 2e 20   by a database. 
11b80 20 42 75 74 20 74 68 65 20 61 70 70 6c 69 63 61   But the applica
11b90 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74  tion does.** not
11ba0 20 77 61 6e 74 20 74 68 65 20 75 73 65 72 20 74   want the user t
11bb0 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b  o be able to mak
11bc0 65 20 61 72 62 69 74 72 61 72 79 20 63 68 61 6e  e arbitrary chan
11bd0 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61  ges to the.** da
11be0 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68  tabase.  An auth
11bf0 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65  orizer could the
11c00 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63  n be put in plac
11c10 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75  e while the.** u
11c20 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20  ser-entered SQL 
11c30 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65  is being [sqlite
11c40 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70  3_prepare | prep
11c50 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69  ared] that.** di
11c60 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69  sallows everythi
11c70 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43  ng except [SELEC
11c80 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  T] statements..*
11c90 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e  *.** Application
11ca0 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70  s that need to p
11cb0 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20  rocess SQL from 
11cc0 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65  untrusted source
11cd0 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20  s.** might also 
11ce0 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e  consider lowerin
11cf0 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74  g resource limit
11d00 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  s using [sqlite3
11d10 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64  _limit()].** and
11d20 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61   limiting databa
11d30 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68  se size using th
11d40 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e  e [max_page_coun
11d50 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69  t] [PRAGMA].** i
11d60 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73  n addition to us
11d70 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65  ing an authorize
11d80 72 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 6c 79 20 61 20  r..**.** Only a 
11d90 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65  single authorize
11da0 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63  r can be in plac
11db0 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20  e on a database 
11dc0 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74  connection.** at
11dd0 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63   a time.  Each c
11de0 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
11df0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76  et_authorizer ov
11e00 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70  errides the.** p
11e10 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 20 20 44  revious call.  D
11e20 69 73 61 62 6c 65 20 74 68 65 20 61 75 74 68 6f  isable the autho
11e30 72 69 7a 65 72 20 62 79 20 69 6e 73 74 61 6c 6c  rizer by install
11e40 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62  ing a NULL callb
11e50 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68  ack..** The auth
11e60 6f 72 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c  orizer is disabl
11e70 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a  ed by default..*
11e80 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74  *.** Note that t
11e90 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
11ea0 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
11eb0 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 20 0a 2a  d only during .*
11ec0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
11ed0 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72  re()] or its var
11ee0 69 61 6e 74 73 2e 20 20 41 75 74 68 6f 72 69 7a  iants.  Authoriz
11ef0 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20  ation is not.** 
11f00 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69 6e 67  performed during
11f10 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61 6c 75   statement evalu
11f20 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65  ation in [sqlite
11f30 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a  3_step()]..**.**
11f40 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
11f50 2a 2a 20 7b 46 31 32 35 30 31 7d 20 54 68 65 20  ** {F12501} The 
11f60 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
11f70 68 6f 72 69 7a 65 72 28 44 2c 2e 2e 2e 29 5d 20  horizer(D,...)] 
11f80 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74  interface regist
11f90 65 72 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20  ers a.**        
11fa0 20 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c    authorizer cal
11fb0 6c 62 61 63 6b 20 77 69 74 68 20 64 61 74 61 62  lback with datab
11fc0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44  ase connection D
11fd0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 30 32 7d  ..**.** {F12502}
11fe0 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   The authorizer 
11ff0 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
12000 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61 74 65  ked as SQL state
12010 6d 65 6e 74 73 20 61 72 65 0a 2a 2a 20 20 20 20  ments are.**    
12020 20 20 20 20 20 20 62 65 69 6e 67 20 63 6f 6d 70        being comp
12030 69 6c 65 64 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35  iled.**.** {F125
12040 30 33 7d 20 49 66 20 74 68 65 20 61 75 74 68 6f  03} If the autho
12050 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72  rizer callback r
12060 65 74 75 72 6e 73 20 61 6e 79 20 76 61 6c 75 65  eturns any value
12070 20 6f 74 68 65 72 20 74 68 61 6e 0a 2a 2a 20 20   other than.**  
12080 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f          [SQLITE_
12090 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45  IGNORE], [SQLITE
120a0 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  _OK], or [SQLITE
120b0 5f 44 45 4e 59 5d 20 74 68 65 6e 0a 2a 2a 20 20  _DENY] then.**  
120c0 20 20 20 20 20 20 20 20 74 68 65 20 5b 73 71 6c          the [sql
120d0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
120e0 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74  )] or equivalent
120f0 20 63 61 6c 6c 20 74 68 61 74 20 63 61 75 73 65   call that cause
12100 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  d.**          th
12110 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
12120 6c 62 61 63 6b 20 74 6f 20 72 75 6e 20 73 68 61  lback to run sha
12130 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 0a  ll fail with an.
12140 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c  **          [SQL
12150 49 54 45 5f 45 52 52 4f 52 5d 20 65 72 72 6f 72  ITE_ERROR] error
12160 20 63 6f 64 65 20 61 6e 64 20 61 6e 20 61 70 70   code and an app
12170 72 6f 70 72 69 61 74 65 20 65 72 72 6f 72 20 6d  ropriate error m
12180 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46  essage..**.** {F
12190 31 32 35 30 34 7d 20 57 68 65 6e 20 74 68 65 20  12504} When the 
121a0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
121b0 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ack returns [SQL
121c0 49 54 45 5f 4f 4b 5d 2c 20 74 68 65 20 6f 70 65  ITE_OK], the ope
121d0 72 61 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20  ration.**       
121e0 20 20 20 64 65 73 63 72 69 62 65 64 20 69 73 20     described is 
121f0 63 6f 64 65 64 20 6e 6f 72 6d 61 6c 6c 79 2e 0a  coded normally..
12200 2a 2a 0a 2a 2a 20 7b 46 31 32 35 30 35 7d 20 57  **.** {F12505} W
12210 68 65 6e 20 74 68 65 20 61 75 74 68 6f 72 69 7a  hen the authoriz
12220 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  er callback retu
12230 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59  rns [SQLITE_DENY
12240 5d 2c 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ], the.**       
12250 20 20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70     [sqlite3_prep
12260 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75  are_v2()] or equ
12270 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61  ivalent call tha
12280 74 20 63 61 75 73 65 64 20 74 68 65 0a 2a 2a 20  t caused the.** 
12290 20 20 20 20 20 20 20 20 20 61 75 74 68 6f 72 69           authori
122a0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20  zer callback to 
122b0 72 75 6e 20 73 68 61 6c 6c 20 66 61 69 6c 0a 2a  run shall fail.*
122c0 2a 20 20 20 20 20 20 20 20 20 20 77 69 74 68 20  *          with 
122d0 61 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  an [SQLITE_ERROR
122e0 5d 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64  ] error code and
122f0 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   an error messag
12300 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 78  e.**          ex
12310 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 20 61 63  plaining that ac
12320 63 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e 0a  cess is denied..
12330 2a 2a 0a 2a 2a 20 7b 46 31 32 35 30 36 7d 20 49  **.** {F12506} I
12340 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  f the authorizer
12350 20 63 6f 64 65 20 28 74 68 65 20 32 6e 64 20 70   code (the 2nd p
12360 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
12370 61 75 74 68 6f 72 69 7a 65 72 0a 2a 2a 20 20 20  authorizer.**   
12380 20 20 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 29         callback)
12390 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44   is [SQLITE_READ
123a0 5d 20 61 6e 64 20 74 68 65 20 61 75 74 68 6f 72  ] and the author
123b0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65  izer callback re
123c0 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20  turns.**        
123d0 20 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45    [SQLITE_IGNORE
123e0 5d 20 74 68 65 6e 20 74 68 65 20 70 72 65 70 61  ] then the prepa
123f0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69 73  red statement is
12400 20 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 0a   constructed to.
12410 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 73 65  **          inse
12420 72 74 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20  rt a NULL value 
12430 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20  in place of the 
12440 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61  table column tha
12450 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20  t would have.** 
12460 20 20 20 20 20 20 20 20 20 62 65 65 6e 20 72 65           been re
12470 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b  ad if [SQLITE_OK
12480 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74 75 72  ] had been retur
12490 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35  ned..**.** {F125
124a0 30 37 7d 20 49 66 20 74 68 65 20 61 75 74 68 6f  07} If the autho
124b0 72 69 7a 65 72 20 63 6f 64 65 20 28 74 68 65 20  rizer code (the 
124c0 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  2nd parameter to
124d0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 0a   the authorizer.
124e0 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c  **          call
124f0 62 61 63 6b 29 20 69 73 20 61 6e 79 74 68 69 6e  back) is anythin
12500 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  g other than [SQ
12510 4c 49 54 45 5f 52 45 41 44 5d 2c 20 74 68 65 6e  LITE_READ], then
12520 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 72  .**          a r
12530 65 74 75 72 6e 20 6f 66 20 5b 53 51 4c 49 54 45  eturn of [SQLITE
12540 5f 49 47 4e 4f 52 45 5d 20 68 61 73 20 74 68 65  _IGNORE] has the
12550 20 73 61 6d 65 20 65 66 66 65 63 74 20 61 73 20   same effect as 
12560 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2e 20 0a  [SQLITE_DENY]. .
12570 2a 2a 0a 2a 2a 20 7b 46 31 32 35 31 30 7d 20 54  **.** {F12510} T
12580 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
12590 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72  er to the author
125a0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
125b0 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 20 20   a copy of.**   
125c0 20 20 20 20 20 20 20 74 68 65 20 74 68 69 72 64         the third
125d0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
125e0 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  e [sqlite3_set_a
125f0 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74  uthorizer()] int
12600 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46  erface..**.** {F
12610 31 32 35 31 31 7d 20 54 68 65 20 73 65 63 6f 6e  12511} The secon
12620 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
12630 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  he callback is a
12640 6e 20 69 6e 74 65 67 65 72 20 0a 2a 2a 20 20 20  n integer .**   
12650 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 43         [SQLITE_C
12660 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64  OPY | action cod
12670 65 5d 20 74 68 61 74 20 73 70 65 63 69 66 69 65  e] that specifie
12680 73 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72  s the particular
12690 20 61 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20   action.**      
126a0 20 20 20 20 74 6f 20 62 65 20 61 75 74 68 6f 72      to be author
126b0 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  ized..**.** {F12
126c0 35 31 32 7d 20 54 68 65 20 74 68 69 72 64 20 74  512} The third t
126d0 68 72 6f 75 67 68 20 73 69 78 74 68 20 70 61 72  hrough sixth par
126e0 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20 63  ameters to the c
126f0 61 6c 6c 62 61 63 6b 20 61 72 65 0a 2a 2a 20 20  allback are.**  
12700 20 20 20 20 20 20 20 20 7a 65 72 6f 2d 74 65 72          zero-ter
12710 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20  minated strings 
12720 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 0a 2a 2a  that contain .**
12730 20 20 20 20 20 20 20 20 20 20 61 64 64 69 74 69            additi
12740 6f 6e 61 6c 20 64 65 74 61 69 6c 73 20 61 62 6f  onal details abo
12750 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20 74 6f  ut the action to
12760 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a   be authorized..
12770 2a 2a 0a 2a 2a 20 7b 46 31 32 35 32 30 7d 20 45  **.** {F12520} E
12780 61 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ach call to [sql
12790 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
127a0 7a 65 72 28 29 5d 20 6f 76 65 72 72 69 64 65 73  zer()] overrides
127b0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
127c0 20 61 6e 79 20 70 72 65 76 69 6f 75 73 6c 79 20   any previously 
127d0 69 6e 73 74 61 6c 6c 65 64 20 61 75 74 68 6f 72  installed author
127e0 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  izer..**.** {F12
127f0 35 32 31 7d 20 41 20 4e 55 4c 4c 20 61 75 74 68  521} A NULL auth
12800 6f 72 69 7a 65 72 20 6d 65 61 6e 73 20 74 68 61  orizer means tha
12810 74 20 6e 6f 20 61 75 74 68 6f 72 69 7a 61 74 69  t no authorizati
12820 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63  on.**          c
12830 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
12840 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 32  ed..**.** {F1252
12850 32 7d 20 54 68 65 20 64 65 66 61 75 6c 74 20 61  2} The default a
12860 75 74 68 6f 72 69 7a 65 72 20 69 73 20 4e 55 4c  uthorizer is NUL
12870 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  L..*/.int sqlite
12880 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
12890 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20  (.  sqlite3*,.  
128a0 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69  int (*xAuth)(voi
128b0 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61  d*,int,const cha
128c0 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63  r*,const char*,c
128d0 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74  onst char*,const
128e0 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20   char*),.  void 
128f0 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f  *pUserData.);../
12900 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41  *.** CAPI3REF: A
12910 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e  uthorizer Return
12920 20 43 6f 64 65 73 20 7b 46 31 32 35 39 30 7d 0a   Codes {F12590}.
12930 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  **.** The [sqlit
12940 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
12950 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63  r | authorizer c
12960 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
12970 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e  ] must.** return
12980 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f   either [SQLITE_
12990 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68  OK] or one of th
129a0 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74  ese two constant
129b0 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f  s in order.** to
129c0 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 20 77   signal SQLite w
129d0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
129e0 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65 72 6d  e action is perm
129f0 69 74 74 65 64 2e 20 20 53 65 65 20 74 68 65 0a  itted.  See the.
12a00 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  ** [sqlite3_set_
12a10 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74  authorizer | aut
12a20 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74  horizer document
12a30 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74  ation] for addit
12a40 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61  ional.** informa
12a50 74 69 6f 6e 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  tion..*/.#define
12a60 20 53 51 4c 49 54 45 5f 44 45 4e 59 20 20 20 31   SQLITE_DENY   1
12a70 20 20 20 2f 2a 20 41 62 6f 72 74 20 74 68 65 20     /* Abort the 
12a80 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 69  SQL statement wi
12a90 74 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23  th an error */.#
12aa0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 47  define SQLITE_IG
12ab0 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27  NORE 2   /* Don'
12ac0 74 20 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20  t allow access, 
12ad0 62 75 74 20 64 6f 6e 27 74 20 67 65 6e 65 72 61  but don't genera
12ae0 74 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a  te an error */..
12af0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
12b00 41 75 74 68 6f 72 69 7a 65 72 20 41 63 74 69 6f  Authorizer Actio
12b10 6e 20 43 6f 64 65 73 20 7b 46 31 32 35 35 30 7d  n Codes {F12550}
12b20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  .**.** The [sqli
12b30 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
12b40 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  er()] interface 
12b50 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c  registers a call
12b60 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  back function.**
12b70 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64   that is invoked
12b80 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 72 20 63   to authorizer c
12b90 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65  ertain SQL state
12ba0 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 54  ment actions.  T
12bb0 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72  he.** second par
12bc0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61  ameter to the ca
12bd0 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74  llback is an int
12be0 65 67 65 72 20 63 6f 64 65 20 74 68 61 74 20 73  eger code that s
12bf0 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 74  pecifies.** what
12c00 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67   action is being
12c10 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68   authorized.  Th
12c20 65 73 65 20 61 72 65 20 74 68 65 20 69 6e 74 65  ese are the inte
12c30 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 73  ger action codes
12c40 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 74   that.** the aut
12c50 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
12c60 20 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e 0a   may be passed..
12c70 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69  **.** These acti
12c80 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73  on code values s
12c90 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64  ignify what kind
12ca0 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73   of operation is
12cb0 20 74 6f 20 62 65 20 0a 2a 2a 20 61 75 74 68 6f   to be .** autho
12cc0 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20  rized.  The 3rd 
12cd0 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74 65  and 4th paramete
12ce0 72 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72  rs to the author
12cf0 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62  ization.** callb
12d00 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c  ack function wil
12d10 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72 73 20  l be parameters 
12d20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e  or NULL dependin
12d30 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68  g on which of th
12d40 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20  ese.** codes is 
12d50 75 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  used as the seco
12d60 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54  nd parameter.  T
12d70 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
12d80 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f   to the.** autho
12d90 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
12da0 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
12db0 65 20 64 61 74 61 62 61 73 65 20 28 22 6d 61 69  e database ("mai
12dc0 6e 22 2c 20 22 74 65 6d 70 22 2c 20 0a 2a 2a 20  n", "temp", .** 
12dd0 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61  etc.) if applica
12de0 62 6c 65 2e 20 20 54 68 65 20 36 74 68 20 70 61  ble.  The 6th pa
12df0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61  rameter to the a
12e00 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
12e10 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d  ck.** is the nam
12e20 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d  e of the inner-m
12e30 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72 20 76  ost trigger or v
12e40 69 65 77 20 74 68 61 74 20 69 73 20 72 65 73 70  iew that is resp
12e50 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74  onsible for.** t
12e60 68 65 20 61 63 63 65 73 73 20 61 74 74 65 6d 70  he access attemp
12e70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69  t or NULL if thi
12e80 73 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74  s access attempt
12e90 20 69 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f   is directly fro
12ea0 6d 20 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20  m .** top-level 
12eb0 53 51 4c 20 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20  SQL code..**.** 
12ec0 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
12ed0 2a 20 7b 46 31 32 35 35 31 7d 20 54 68 65 20 73  * {F12551} The s
12ee0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
12ef0 74 6f 20 61 6e 20 0a 2a 2a 20 20 20 20 20 20 20  to an .**       
12f00 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f     [sqlite3_set_
12f10 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74  authorizer | aut
12f20 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
12f30 20 69 73 20 61 6c 77 61 79 73 20 61 6e 20 69 6e   is always an in
12f40 74 65 67 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  teger.**        
12f50 20 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c    [SQLITE_COPY |
12f60 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 64 65   authorizer code
12f70 5d 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73  ] that specifies
12f80 20 77 68 61 74 20 61 63 74 69 6f 6e 0a 2a 2a 20   what action.** 
12f90 20 20 20 20 20 20 20 20 20 69 73 20 62 65 69 6e           is bein
12fa0 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a  g authorized..**
12fb0 0a 2a 2a 20 7b 46 31 32 35 35 32 7d 20 54 68 65  .** {F12552} The
12fc0 20 33 72 64 20 61 6e 64 20 34 74 68 20 70 61 72   3rd and 4th par
12fd0 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20 0a  ameters to the .
12fe0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
12ff0 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
13000 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 61 74  zer | authorizat
13010 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  ion callback fun
13020 63 74 69 6f 6e 5d 0a 2a 2a 20 20 20 20 20 20 20  ction].**       
13030 20 20 20 77 69 6c 6c 20 62 65 20 70 61 72 61 6d     will be param
13040 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65  eters or NULL de
13050 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63 68  pending on which
13060 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53   .**          [S
13070 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 75 74  QLITE_COPY | aut
13080 68 6f 72 69 7a 65 72 20 63 6f 64 65 5d 20 69 73  horizer code] is
13090 20 75 73 65 64 20 61 73 20 74 68 65 20 73 65 63   used as the sec
130a0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  ond parameter..*
130b0 2a 0a 2a 2a 20 7b 46 31 32 35 35 33 7d 20 54 68  *.** {F12553} Th
130c0 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 5th parameter 
130d0 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  to the.**       
130e0 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f     [sqlite3_set_
130f0 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74  authorizer | aut
13100 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
13110 5d 20 69 73 20 74 68 65 20 6e 61 6d 65 0a 2a 2a  ] is the name.**
13120 20 20 20 20 20 20 20 20 20 20 6f 66 20 74 68 65            of the
13130 20 64 61 74 61 62 61 73 65 20 28 65 78 61 6d 70   database (examp
13140 6c 65 3a 20 22 6d 61 69 6e 22 2c 20 22 74 65 6d  le: "main", "tem
13150 70 22 2c 20 65 74 63 2e 29 20 69 66 20 61 70 70  p", etc.) if app
13160 6c 69 63 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 7b  licable..**.** {
13170 46 31 32 35 35 34 7d 20 54 68 65 20 36 74 68 20  F12554} The 6th 
13180 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
13190 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
131a0 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
131b0 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65  izer | authorize
131c0 72 20 63 61 6c 6c 62 61 63 6b 5d 20 69 73 20 74  r callback] is t
131d0 68 65 20 6e 61 6d 65 0a 2a 2a 20 20 20 20 20 20  he name.**      
131e0 20 20 20 20 6f 66 20 74 68 65 20 69 6e 6e 65 72      of the inner
131f0 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72  -most trigger or
13200 20 76 69 65 77 20 74 68 61 74 20 69 73 20 72 65   view that is re
13210 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a  sponsible for.**
13220 20 20 20 20 20 20 20 20 20 20 74 68 65 20 61 63            the ac
13230 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72 20  cess attempt or 
13240 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63 63  NULL if this acc
13250 65 73 73 20 61 74 74 65 6d 70 74 20 69 73 20 64  ess attempt is d
13260 69 72 65 63 74 6c 79 20 66 72 6f 6d 20 0a 2a 2a  irectly from .**
13270 20 20 20 20 20 20 20 20 20 20 74 6f 70 2d 6c 65            top-le
13280 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f  vel SQL code..*/
13290 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ./**************
132a0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
132b0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72  ************* 3r
132c0 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34  d ************ 4
132d0 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a  th ***********/.
132e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
132f0 52 45 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20  REATE_INDEX     
13300 20 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65       1   /* Inde
13310 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
13320 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
13330 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
13340 45 41 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20  EATE_TABLE      
13350 20 20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65      2   /* Table
13360 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
13370 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
13380 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
13390 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20  ATE_TEMP_INDEX  
133a0 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20     3   /* Index 
133b0 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
133c0 4e 61 6d 65 20 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 43 52 45 41  fine SQLITE_CREA
133e0 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20  TE_TEMP_TABLE   
133f0 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e    4   /* Table N
13400 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      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 43 52 45 41 54  ine SQLITE_CREAT
13430 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20  E_TEMP_TRIGGER  
13440 20 35 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20   5   /* Trigger 
13450 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
13460 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
13470 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
13480 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20  _TEMP_VIEW      
13490 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  6   /* View Name
134a0 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
134b0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
134c0 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
134d0 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20 37  TRIGGER        7
134e0 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
134f0 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
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 43 52 45 41 54 45 5f 56   SQLITE_CREATE_V
13520 49 45 57 20 20 20 20 20 20 20 20 20 20 20 38 20  IEW           8 
13530 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
13540 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       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 44 45 4c 45 54 45 20 20 20  SQLITE_DELETE   
13570 20 20 20 20 20 20 20 20 20 20 20 20 20 39 20 20               9  
13580 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
13590 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
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 44 52 4f 50 5f 49 4e 44 45 58  QLITE_DROP_INDEX
135c0 20 20 20 20 20 20 20 20 20 20 20 31 30 20 20 20             10   
135d0 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
135e0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
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 44 52 4f 50 5f 54 41 42 4c 45 20  LITE_DROP_TABLE 
13610 20 20 20 20 20 20 20 20 20 20 31 31 20 20 20 2f            11   /
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 44 52 4f 50 5f 54 45 4d 50 5f 49 4e  ITE_DROP_TEMP_IN
13660 44 45 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a  DEX      12   /*
13670 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
13680 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table 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 54 45 4d 50 5f 54 41 42  TE_DROP_TEMP_TAB
136b0 4c 45 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20  LE      13   /* 
136c0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
136d0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
136e0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
136f0 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47  E_DROP_TEMP_TRIG
13700 47 45 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54  GER    14   /* T
13710 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
13720 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
13730 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
13740 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20  _DROP_TEMP_VIEW 
13750 20 20 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69        15   /* Vi
13760 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
13770 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
13780 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
13790 44 52 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20  DROP_TRIGGER    
137a0 20 20 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69       16   /* Tri
137b0 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
137c0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
137d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
137e0 52 4f 50 5f 56 49 45 57 20 20 20 20 20 20 20 20  ROP_VIEW        
137f0 20 20 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77      17   /* View
13800 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
13810 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
13820 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
13830 53 45 52 54 20 20 20 20 20 20 20 20 20 20 20 20  SERT            
13840 20 20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65     18   /* Table
13850 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
13860 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
13870 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41  efine SQLITE_PRA
13880 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20  GMA             
13890 20 20 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61    19   /* Pragma
138a0 20 4e 61 6d 65 20 20 20 20 20 31 73 74 20 61 72   Name     1st ar
138b0 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65  g or NULL */.#de
138c0 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
138d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
138e0 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   20   /* Table N
138f0 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20  ame      Column 
13900 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
13910 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43  ine SQLITE_SELEC
13920 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  T               
13930 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20  21   /* NULL    
13940 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20          NULL    
13950 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
13960 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41  ne SQLITE_TRANSA
13970 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32  CTION          2
13980 32 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20  2   /* NULL     
13990 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
139a0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
139b0 65 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20  e SQLITE_UPDATE 
139c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 33                23
139d0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
139e0 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d        Column Nam
139f0 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
13a00 20 53 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20   SQLITE_ATTACH  
13a10 20 20 20 20 20 20 20 20 20 20 20 20 20 32 34 20               24 
13a20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20    /* Filename   
13a30 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
13a40 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
13a50 53 51 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20  SQLITE_DETACH   
13a60 20 20 20 20 20 20 20 20 20 20 20 20 32 35 20 20              25  
13a70 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d   /* Database Nam
13a80 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20  e   NULL        
13a90 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
13aa0 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c  QLITE_ALTER_TABL
13ab0 45 20 20 20 20 20 20 20 20 20 20 32 36 20 20 20  E          26   
13ac0 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65  /* Database Name
13ad0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
13ae0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
13af0 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20  LITE_REINDEX    
13b00 20 20 20 20 20 20 20 20 20 20 32 37 20 20 20 2f            27   /
13b10 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
13b20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
13b30 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
13b40 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20  ITE_ANALYZE     
13b50 20 20 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a           28   /*
13b60 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
13b70 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
13b80 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
13b90 54 45 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45  TE_CREATE_VTABLE
13ba0 20 20 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20          29   /* 
13bb0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
13bc0 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20  Module Name     
13bd0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
13be0 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20  E_DROP_VTABLE   
13bf0 20 20 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54         30   /* T
13c00 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d  able Name      M
13c10 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a  odule Name     *
13c20 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
13c30 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20  _FUNCTION       
13c40 20 20 20 20 20 20 33 31 20 20 20 2f 2a 20 46 75        31   /* Fu
13c50 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 4e 55  nction Name   NU
13c60 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
13c70 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
13c80 43 4f 50 59 20 20 20 20 20 20 20 20 20 20 20 20  COPY            
13c90 20 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20        0   /* No 
13ca0 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 0a  longer used */..
13cb0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
13cc0 54 72 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66  Tracing And Prof
13cd0 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 20  iling Functions 
13ce0 7b 46 31 32 32 38 30 7d 0a 2a 2a 0a 2a 2a 20 54  {F12280}.**.** T
13cf0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
13d00 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20  gister callback 
13d10 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63  functions that c
13d20 61 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a  an be used for.*
13d30 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72  * tracing and pr
13d40 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63  ofiling the exec
13d50 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61  ution of SQL sta
13d60 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54  tements..**.** T
13d70 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  he callback func
13d80 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20  tion registered 
13d90 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  by sqlite3_trace
13da0 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74  () is invoked at
13db0 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65  .** various time
13dc0 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74  s when an SQL st
13dd0 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67  atement is being
13de0 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33   run by [sqlite3
13df0 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 54 68 65  _step()]..** The
13e00 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
13e10 73 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72  s a UTF-8 render
13e20 69 6e 67 20 6f 66 20 74 68 65 20 53 51 4c 20 73  ing of the SQL s
13e30 74 61 74 65 6d 65 6e 74 20 74 65 78 74 0a 2a 2a  tatement text.**
13e40 20 61 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e   as the statemen
13e50 74 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 65  t first begins e
13e60 78 65 63 75 74 69 6e 67 2e 20 20 41 64 64 69 74  xecuting.  Addit
13e70 69 6f 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20  ional callbacks 
13e80 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65 61 63 68  occur.** as each
13e90 20 74 72 69 67 67 65 72 73 75 62 70 72 6f 67 72   triggersubprogr
13ea0 61 6d 20 69 73 20 65 6e 74 65 72 65 64 2e 20 20  am is entered.  
13eb0 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f  The callbacks fo
13ec0 72 20 74 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f  r triggers.** co
13ed0 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 20 53 51  ntain a UTF-8 SQ
13ee0 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69  L comment that i
13ef0 64 65 6e 74 69 66 69 65 73 20 74 68 65 20 74 72  dentifies the tr
13f00 69 67 67 65 72 2e 0a 2a 2a 20 0a 2a 2a 20 54 68  igger..** .** Th
13f10 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
13f20 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62  ion registered b
13f30 79 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c  y sqlite3_profil
13f40 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a  e() is invoked.*
13f50 2a 20 61 73 20 65 61 63 68 20 53 51 4c 20 73 74  * as each SQL st
13f60 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73  atement finishes
13f70 2e 20 20 54 68 65 20 70 72 6f 66 69 6c 65 20 63  .  The profile c
13f80 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73  allback contains
13f90 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  .** the original
13fa0 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
13fb0 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65 20  and an estimate 
13fc0 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69  of wall-clock ti
13fd0 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e  me.** of how lon
13fe0 67 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74  g that statement
13ff0 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 0a 2a 2a   took to run..**
14000 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
14010 70 72 6f 66 69 6c 65 28 29 20 41 50 49 20 69 73  profile() API is
14020 20 63 75 72 72 65 6e 74 6c 79 20 63 6f 6e 73 69   currently consi
14030 64 65 72 65 64 20 65 78 70 65 72 69 6d 65 6e 74  dered experiment
14040 61 6c 20 61 6e 64 0a 2a 2a 20 69 73 20 73 75 62  al and.** is sub
14050 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 6f  ject to change o
14060 72 20 72 65 6d 6f 76 61 6c 20 69 6e 20 61 20 66  r removal in a f
14070 75 74 75 72 65 20 72 65 6c 65 61 73 65 2e 0a 2a  uture release..*
14080 2a 0a 2a 2a 20 54 68 65 20 74 72 69 67 67 65 72  *.** The trigger
14090 20 72 65 70 6f 72 74 69 6e 67 20 66 65 61 74 75   reporting featu
140a0 72 65 20 6f 66 20 74 68 65 20 74 72 61 63 65 20  re of the trace 
140b0 63 61 6c 6c 62 61 63 6b 20 69 73 20 63 6f 6e 73  callback is cons
140c0 69 64 65 72 65 64 0a 2a 2a 20 65 78 70 65 72 69  idered.** experi
140d0 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 20 73 75  mental and is su
140e0 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20  bject to change 
140f0 6f 72 20 72 65 6d 6f 76 61 6c 20 69 6e 20 66 75  or removal in fu
14100 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a  ture releases..*
14110 2a 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e  * Future version
14120 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68  s of SQLite migh
14130 74 20 61 6c 73 6f 20 61 64 64 20 6e 65 77 20 74  t also add new t
14140 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 20 0a 2a  race callback .*
14150 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 2e 0a 2a  * invocations..*
14160 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
14170 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 38 31 7d 20  .**.** {F12281} 
14180 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  The callback fun
14190 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64  ction registered
141a0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 74 72 61   by [sqlite3_tra
141b0 63 65 28 29 5d 20 69 73 0a 2a 2a 20 20 20 20 20  ce()] is.**     
141c0 20 20 20 20 20 77 68 65 6e 65 76 65 72 20 61 6e       whenever an
141d0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66   SQL statement f
141e0 69 72 73 74 20 62 65 67 69 6e 73 20 74 6f 20 65  irst begins to e
141f0 78 65 63 75 74 65 20 61 6e 64 0a 2a 2a 20 20 20  xecute and.**   
14200 20 20 20 20 20 20 20 77 68 65 6e 65 76 65 72 20         whenever 
14210 61 20 74 72 69 67 67 65 72 20 73 75 62 70 72 6f  a trigger subpro
14220 67 72 61 6d 20 66 69 72 73 74 20 62 65 67 69 6e  gram first begin
14230 73 20 74 6f 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20  s to run..**.** 
14240 7b 46 31 32 32 38 32 7d 20 45 61 63 68 20 63 61  {F12282} Each ca
14250 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74  ll to [sqlite3_t
14260 72 61 63 65 28 29 5d 20 6f 76 65 72 72 69 64 65  race()] override
14270 73 20 74 68 65 20 70 72 65 76 69 6f 75 73 6c 79  s the previously
14280 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 67  .**          reg
14290 69 73 74 65 72 65 64 20 74 72 61 63 65 20 63 61  istered trace ca
142a0 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 46  llback..**.** {F
142b0 31 32 32 38 33 7d 20 41 20 4e 55 4c 4c 20 74 72  12283} A NULL tr
142c0 61 63 65 20 63 61 6c 6c 62 61 63 6b 20 64 69 73  ace callback dis
142d0 61 62 6c 65 73 20 74 72 61 63 69 6e 67 2e 0a 2a  ables tracing..*
142e0 2a 0a 2a 2a 20 7b 46 31 32 32 38 34 7d 20 54 68  *.** {F12284} Th
142f0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
14300 20 74 6f 20 74 68 65 20 74 72 61 63 65 20 63 61   to the trace ca
14310 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79  llback is a copy
14320 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   of.**          
14330 74 68 65 20 70 6f 69 6e 74 65 72 20 77 68 69 63  the pointer whic
14340 68 20 77 61 73 20 74 68 65 20 33 72 64 20 61 72  h was the 3rd ar
14350 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74  gument to [sqlit
14360 65 33 5f 74 72 61 63 65 28 29 5d 2e 0a 2a 2a 0a  e3_trace()]..**.
14370 2a 2a 20 7b 46 31 32 32 38 35 7d 20 54 68 65 20  ** {F12285} The 
14380 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
14390 74 6f 20 74 68 65 20 74 72 61 63 65 20 63 61 6c  to the trace cal
143a0 6c 62 61 63 6b 20 69 73 20 61 0a 2a 2a 20 20 20  lback is a.**   
143b0 20 20 20 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d         zero-term
143c0 69 6e 61 74 65 64 20 55 54 46 38 20 73 74 72 69  inated UTF8 stri
143d0 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  ng containing th
143e0 65 20 6f 72 69 67 69 6e 61 6c 20 74 65 78 74 0a  e original text.
143f0 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 74  **          of t
14400 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
14410 20 61 73 20 69 74 20 77 61 73 20 70 61 73 73 65   as it was passe
14420 64 20 69 6e 74 6f 20 5b 73 71 6c 69 74 65 33 5f  d into [sqlite3_
14430 70 72 65 70 61 72 65 5f 76 32 28 29 5d 0a 2a 2a  prepare_v2()].**
14440 20 20 20 20 20 20 20 20 20 20 6f 72 20 74 68 65            or the
14450 20 65 71 75 69 76 61 6c 65 6e 74 2c 20 6f 72 20   equivalent, or 
14460 61 6e 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 69  an SQL comment i
14470 6e 64 69 63 61 74 69 6e 67 20 74 68 65 20 62 65  ndicating the be
14480 67 69 6e 6e 69 6e 67 0a 2a 2a 20 20 20 20 20 20  ginning.**      
14490 20 20 20 20 6f 66 20 61 20 74 72 69 67 67 65 72      of a trigger
144a0 20 73 75 62 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a   subprogram..**.
144b0 2a 2a 20 7b 46 31 32 32 38 37 7d 20 54 68 65 20  ** {F12287} The 
144c0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
144d0 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20  n registered by 
144e0 5b 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65  [sqlite3_profile
144f0 28 29 5d 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a  ()] is invoked.*
14500 2a 20 20 20 20 20 20 20 20 20 20 61 73 20 65 61  *          as ea
14510 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ch SQL statement
14520 20 66 69 6e 69 73 68 65 73 2e 0a 2a 2a 0a 2a 2a   finishes..**.**
14530 20 7b 46 31 32 32 38 38 7d 20 54 68 65 20 66 69   {F12288} The fi
14540 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
14550 20 74 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c   the profile cal
14560 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20  lback is a copy 
14570 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  of.**          t
14580 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
14590 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f   to [sqlite3_pro
145a0 66 69 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  file()]..**.** {
145b0 46 31 32 32 38 39 7d 20 54 68 65 20 73 65 63 6f  F12289} The seco
145c0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
145d0 74 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c  the profile call
145e0 62 61 63 6b 20 69 73 20 61 0a 2a 2a 20 20 20 20  back is a.**    
145f0 20 20 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69        zero-termi
14600 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69  nated UTF-8 stri
14610 6e 67 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 73  ng that contains
14620 20 74 68 65 20 63 6f 6d 70 6c 65 74 65 20 74 65   the complete te
14630 78 74 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20  xt of.**        
14640 20 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d    the SQL statem
14650 65 6e 74 20 61 73 20 69 74 20 77 61 73 20 70 72  ent as it was pr
14660 6f 63 65 73 73 65 64 20 62 79 20 5b 73 71 6c 69  ocessed by [sqli
14670 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
14680 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  ].**          or
14690 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74 2e   the equivalent.
146a0 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 39 30 7d 20  .**.** {F12290} 
146b0 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  The third parame
146c0 74 65 72 20 74 6f 20 74 68 65 20 70 72 6f 66 69  ter to the profi
146d0 6c 65 20 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  le  callback is 
146e0 61 6e 20 65 73 74 69 6d 61 74 65 0a 2a 2a 20 20  an estimate.**  
146f0 20 20 20 20 20 20 20 20 6f 66 20 74 68 65 20 6e          of the n
14700 75 6d 62 65 72 20 6f 66 20 6e 61 6e 6f 73 65 63  umber of nanosec
14710 6f 6e 64 73 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f  onds of wall-clo
14720 63 6b 20 74 69 6d 65 20 72 65 71 75 69 72 65 64  ck time required
14730 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   to.**          
14740 72 75 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74  run the SQL stat
14750 65 6d 65 6e 74 20 66 72 6f 6d 20 73 74 61 72 74  ement from start
14760 20 74 6f 20 66 69 6e 69 73 68 2e 0a 2a 2f 0a 76   to finish..*/.v
14770 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 74 72 61  oid *sqlite3_tra
14780 63 65 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69  ce(sqlite3*, voi
14790 64 28 2a 78 54 72 61 63 65 29 28 76 6f 69 64 2a  d(*xTrace)(void*
147a0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 76  ,const char*), v
147b0 6f 69 64 2a 29 3b 0a 76 6f 69 64 20 2a 73 71 6c  oid*);.void *sql
147c0 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c  ite3_profile(sql
147d0 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a  ite3*,.   void(*
147e0 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c  xProfile)(void*,
147f0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69  const char*,sqli
14800 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69  te3_uint64), voi
14810 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
14820 33 52 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67  3REF: Query Prog
14830 72 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 20 7b  ress Callbacks {
14840 46 31 32 39 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 68  F12910}.**.** Th
14850 69 73 20 72 6f 75 74 69 6e 65 20 63 6f 6e 66 69  is routine confi
14860 67 75 72 65 73 20 61 20 63 61 6c 6c 62 61 63 6b  gures a callback
14870 20 66 75 6e 63 74 69 6f 6e 20 2d 20 74 68 65 0a   function - the.
14880 2a 2a 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c  ** progress call
14890 62 61 63 6b 20 2d 20 74 68 61 74 20 69 73 20 69  back - that is i
148a0 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61  nvoked periodica
148b0 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 0a  lly during long.
148c0 2a 2a 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73  ** running calls
148d0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65   to [sqlite3_exe
148e0 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73  c()], [sqlite3_s
148f0 74 65 70 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73  tep()] and.** [s
14900 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
14910 28 29 5d 2e 20 20 20 41 6e 20 65 78 61 6d 70 6c  ()].   An exampl
14920 65 20 75 73 65 20 66 6f 72 20 74 68 69 73 20 0a  e use for this .
14930 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  ** interface is 
14940 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75 70  to keep a GUI up
14950 64 61 74 65 64 20 64 75 72 69 6e 67 20 61 20 6c  dated during a l
14960 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a  arge query..**.*
14970 2a 20 49 66 20 74 68 65 20 70 72 6f 67 72 65 73  * If the progres
14980 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  s callback retur
14990 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
149a0 20 6f 70 65 72 74 69 6f 6e 20 69 73 0a 2a 2a 20   opertion is.** 
149b0 69 6e 74 65 72 72 75 70 74 65 64 2e 20 20 54 68  interrupted.  Th
149c0 69 73 20 66 65 61 74 75 72 65 20 63 61 6e 20 62  is feature can b
149d0 65 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d  e used to implem
149e0 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c  ent a.** "Cancel
149f0 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55  " button on a GU
14a00 49 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a  I dialog box..**
14a10 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
14a20 2a 2a 0a 2a 2a 20 7b 46 31 32 39 31 31 7d 20 54  **.** {F12911} T
14a30 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  he callback func
14a40 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20  tion registered 
14a50 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 67  by [sqlite3_prog
14a60 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 29 5d 0a  ress_handler()].
14a70 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 69  **          is i
14a80 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61  nvoked periodica
14a90 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20  lly during long 
14aa0 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f  running calls to
14ab0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
14ac0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a  lite3_step()]..*
14ad0 2a 0a 2a 2a 20 7b 46 31 32 39 31 32 7d 20 54 68  *.** {F12912} Th
14ae0 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62  e progress callb
14af0 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f  ack is invoked o
14b00 6e 63 65 20 66 6f 72 20 65 76 65 72 79 20 4e 20  nce for every N 
14b10 76 69 72 74 75 61 6c 0a 2a 2a 20 20 20 20 20 20  virtual.**      
14b20 20 20 20 20 6d 61 63 68 69 6e 65 20 6f 70 63 6f      machine opco
14b30 64 65 73 2c 20 77 68 65 72 65 20 4e 20 69 73 20  des, where N is 
14b40 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
14b50 65 6e 74 20 74 6f 20 0a 2a 2a 20 20 20 20 20 20  ent to .**      
14b60 20 20 20 20 74 68 65 20 5b 73 71 6c 69 74 65 33      the [sqlite3
14b70 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65  _progress_handle
14b80 72 28 29 5d 20 63 61 6c 6c 20 74 68 61 74 20 72  r()] call that r
14b90 65 67 69 73 74 65 72 65 64 0a 2a 2a 20 20 20 20  egistered.**    
14ba0 20 20 20 20 20 20 74 68 65 20 63 61 6c 6c 62 61        the callba
14bb0 63 6b 2e 20 20 3c 74 6f 64 6f 3e 57 68 61 74 20  ck.  <todo>What 
14bc0 69 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61  if N is less tha
14bd0 6e 20 31 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a  n 1?</todo>.**.*
14be0 2a 20 7b 46 31 32 39 31 33 7d 20 54 68 65 20 70  * {F12913} The p
14bf0 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b  rogress callback
14c00 20 69 74 73 65 6c 66 20 69 73 20 69 64 65 6e 74   itself is ident
14c10 69 66 69 65 64 20 62 79 20 74 68 65 20 74 68 69  ified by the thi
14c20 72 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  rd.**          a
14c30 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69  rgument to [sqli
14c40 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e  te3_progress_han
14c50 64 6c 65 72 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  dler()]..**.** {
14c60 46 31 32 39 31 34 7d 20 54 68 65 20 66 6f 75 72  F12914} The four
14c70 74 68 20 61 72 67 75 6d 65 6e 74 20 5b 73 71 6c  th argument [sql
14c80 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61  ite3_progress_ha
14c90 6e 64 6c 65 72 28 29 5d 20 69 73 20 61 0a 2a 2a  ndler()] is a.**
14ca0 2a 20 20 20 20 20 20 20 20 20 76 6f 69 64 20 70  *         void p
14cb0 6f 69 6e 74 65 72 20 70 61 73 73 65 64 20 74 6f  ointer passed to
14cc0 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 61   the progress ca
14cd0 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20  llback.**       
14ce0 20 20 20 66 75 6e 63 74 69 6f 6e 20 65 61 63 68     function each
14cf0 20 74 69 6d 65 20 69 74 20 69 73 20 69 6e 76 6f   time it is invo
14d00 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39  ked..**.** {F129
14d10 31 35 7d 20 49 66 20 61 20 63 61 6c 6c 20 74 6f  15} If a call to
14d20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
14d30 5d 20 72 65 73 75 6c 74 73 20 69 6e 20 66 65 77  ] results in few
14d40 65 72 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20  er than.**      
14d50 20 20 20 20 4e 20 6f 70 63 6f 64 65 73 20 62 65      N opcodes be
14d60 69 6e 67 20 65 78 65 63 75 74 65 64 2c 0a 2a 2a  ing executed,.**
14d70 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 74            then t
14d80 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c  he progress call
14d90 62 61 63 6b 20 69 73 20 6e 65 76 65 72 20 69 6e  back is never in
14da0 76 6f 6b 65 64 2e 20 7b 45 4e 44 7d 0a 2a 2a 20  voked. {END}.** 
14db0 0a 2a 2a 20 7b 46 31 32 39 31 36 7d 20 45 76 65  .** {F12916} Eve
14dc0 72 79 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ry call to [sqli
14dd0 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e  te3_progress_han
14de0 64 6c 65 72 28 29 5d 0a 2a 2a 20 20 20 20 20 20  dler()].**      
14df0 20 20 20 20 6f 76 65 72 77 72 69 74 65 73 20 61      overwrites a
14e00 6e 79 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65  ny previously re
14e10 67 69 73 74 65 72 65 20 70 72 6f 67 72 65 73 73  gistere progress
14e20 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20   handler..**.** 
14e30 7b 46 31 32 39 31 37 7d 20 49 66 20 74 68 65 20  {F12917} If the 
14e40 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
14e50 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c   callback is NUL
14e60 4c 20 74 68 65 6e 20 6e 6f 20 70 72 6f 67 72 65  L then no progre
14e70 73 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 68  ss.**          h
14e80 61 6e 64 6c 65 72 20 69 73 20 69 6e 76 6f 6b 65  andler is invoke
14e90 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 31 38  d..**.** {F12918
14ea0 7d 20 49 66 20 74 68 65 20 70 72 6f 67 72 65 73  } If the progres
14eb0 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  s callback retur
14ec0 6e 73 20 61 20 72 65 73 75 6c 74 20 6f 74 68 65  ns a result othe
14ed0 72 20 74 68 61 6e 20 30 2c 20 74 68 65 6e 0a 2a  r than 0, then.*
14ee0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 62  *          the b
14ef0 65 68 61 76 69 6f 72 20 69 73 20 61 20 69 66 20  ehavior is a if 
14f00 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75  [sqlite3_interru
14f10 70 74 28 29 5d 20 68 61 64 20 62 65 65 6e 20 63  pt()] had been c
14f20 61 6c 6c 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73  alled..*/.void s
14f30 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f  qlite3_progress_
14f40 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a  handler(sqlite3*
14f50 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f  , int, int(*)(vo
14f60 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  id*), void*);../
14f70 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
14f80 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74  pening A New Dat
14f90 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
14fa0 20 7b 46 31 32 37 30 30 7d 0a 2a 2a 0a 2a 2a 20   {F12700}.**.** 
14fb0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f  These routines o
14fc0 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61  pen an SQLite da
14fd0 74 61 62 61 73 65 20 66 69 6c 65 20 77 68 6f 73  tabase file whos
14fe0 65 20 6e 61 6d 65 0a 2a 2a 20 69 73 20 67 69 76  e name.** is giv
14ff0 65 6e 20 62 79 20 74 68 65 20 66 69 6c 65 6e 61  en by the filena
15000 6d 65 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20  me argument..** 
15010 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  The filename arg
15020 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70 72  ument is interpr
15030 65 74 65 64 20 61 73 20 55 54 46 2d 38 0a 2a 2a  eted as UTF-8.**
15040 20 66 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70   for [sqlite3_op
15050 65 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  en()] and [sqlit
15060 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 61 6e  e3_open_v2()] an
15070 64 20 61 73 20 55 54 46 2d 31 36 0a 2a 2a 20 69  d as UTF-16.** i
15080 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74  n the native byt
15090 65 20 6f 72 64 65 72 20 66 6f 72 20 5b 73 71 6c  e order for [sql
150a0 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a  ite3_open16()]..
150b0 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 2a 5d  ** An [sqlite3*]
150c0 20 68 61 6e 64 6c 65 20 69 73 20 75 73 75 61 6c   handle is usual
150d0 6c 79 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a  ly returned in *
150e0 70 70 44 62 2c 20 65 76 65 6e 0a 2a 2a 20 69 66  ppDb, even.** if
150f0 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
15100 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65 78 63 65  .  The only exce
15110 70 74 69 6f 6e 20 69 73 20 69 66 20 53 51 4c 69  ption is if SQLi
15120 74 65 20 69 73 20 75 6e 61 62 6c 65 0a 2a 2a 20  te is unable.** 
15130 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f  to allocate memo
15140 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b  ry to hold the [
15150 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c  sqlite3] object,
15160 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 0a 2a 2a 20   a NULL will.** 
15170 62 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  be written into 
15180 2a 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66  *ppDb instead of
15190 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
151a0 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  e [sqlite3] obje
151b0 63 74 2e 0a 2a 2a 20 49 66 20 74 68 65 20 64 61  ct..** If the da
151c0 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
151d0 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 64   (and/or created
151e0 29 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c  ).** successfull
151f0 79 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f  y, then [SQLITE_
15200 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  OK] is returned.
15210 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e 0a 2a    Otherwise an.*
15220 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20  * error code is 
15230 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 0a 2a  returned.  The.*
15240 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  * [sqlite3_errms
15250 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  g()] or [sqlite3
15260 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 20 72 6f  _errmsg16()]  ro
15270 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75 73  utines can be us
15280 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20  ed to obtain.** 
15290 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75  an English langu
152a0 61 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e 20  age description 
152b0 6f 66 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a  of the error..**
152c0 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20  .** The default 
152d0 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 74 68 65  encoding for the
152e0 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62   database will b
152f0 65 20 55 54 46 2d 38 20 69 66 0a 2a 2a 20 5b 73  e UTF-8 if.** [s
15300 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 6f  qlite3_open()] o
15310 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  r [sqlite3_open_
15320 76 32 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20  v2()] is called 
15330 61 6e 64 0a 2a 2a 20 55 54 46 2d 31 36 20 69 6e  and.** UTF-16 in
15340 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
15350 20 6f 72 64 65 72 20 69 66 20 5b 73 71 6c 69 74   order if [sqlit
15360 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 20  e3_open16()] is 
15370 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74  used..**.** Whet
15380 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72  her or not an er
15390 72 6f 72 20 6f 63 63 75 72 73 20 77 68 65 6e 20  ror occurs when 
153a0 69 74 20 69 73 20 6f 70 65 6e 65 64 2c 20 72 65  it is opened, re
153b0 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63  sources.** assoc
153c0 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b  iated with the [
153d0 73 71 6c 69 74 65 33 2a 5d 20 68 61 6e 64 6c 65  sqlite3*] handle
153e0 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61   should be relea
153f0 73 65 64 20 62 79 20 70 61 73 73 69 6e 67 20 69  sed by passing i
15400 74 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33  t.** to [sqlite3
15410 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69  _close()] when i
15420 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72  t is no longer r
15430 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  equired..**.** T
15440 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
15450 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65  _v2()] interface
15460 20 77 6f 72 6b 73 20 6c 69 6b 65 20 5b 73 71 6c   works like [sql
15470 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 0a 2a 2a  ite3_open()] .**
15480 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20   except that it 
15490 61 63 63 63 65 70 74 73 20 74 77 6f 20 61 64 64  acccepts two add
154a0 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65  itional paramete
154b0 72 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  rs for additiona
154c0 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65  l control.** ove
154d0 72 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61  r the new databa
154e0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  se connection.  
154f0 54 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65  The flags parame
15500 74 65 72 20 63 61 6e 20 62 65 0a 2a 2a 20 6f 6e  ter can be.** on
15510 65 20 6f 66 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e  e of:.**.** <ol>
15520 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
15530 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d  E_OPEN_READONLY]
15540 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
15550 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
15560 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
15570 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
15580 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45  E] | [SQLITE_OPE
15590 4e 5f 43 52 45 41 54 45 5d 0a 2a 2a 20 3c 2f 6f  N_CREATE].** </o
155a0 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  l>.**.** The fir
155b0 73 74 20 76 61 6c 75 65 20 6f 70 65 6e 73 20 74  st value opens t
155c0 68 65 20 64 61 74 61 62 61 73 65 20 72 65 61 64  he database read
155d0 2d 6f 6e 6c 79 2e 20 0a 2a 2a 20 49 66 20 74 68  -only. .** If th
155e0 65 20 64 61 74 61 62 61 73 65 20 64 6f 65 73 20  e database does 
155f0 6e 6f 74 20 70 72 65 76 69 6f 75 73 6c 79 20 65  not previously e
15600 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69  xist, an error i
15610 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 54  s returned..** T
15620 68 65 20 73 65 63 6f 6e 64 20 6f 70 74 69 6f 6e  he second option
15630 20 6f 70 65 6e 73 0a 2a 2a 20 74 68 65 20 64 61   opens.** the da
15640 74 61 62 61 73 65 20 66 6f 72 20 72 65 61 64 69  tabase for readi
15650 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69  ng and writing i
15660 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72  f possible, or r
15670 65 61 64 69 6e 67 20 6f 6e 6c 79 20 69 66 0a 2a  eading only if.*
15680 2a 20 69 66 20 74 68 65 20 66 69 6c 65 20 69 73  * if the file is
15690 20 77 72 69 74 65 20 70 72 6f 74 65 63 74 65 64   write protected
156a0 2e 20 20 49 6e 20 65 69 74 68 65 72 20 63 61 73  .  In either cas
156b0 65 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  e the database.*
156c0 2a 20 6d 75 73 74 20 61 6c 72 65 61 64 79 20 65  * must already e
156d0 78 69 73 74 20 6f 72 20 61 6e 20 65 72 72 6f 72  xist or an error
156e0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54   is returned.  T
156f0 68 65 20 74 68 69 72 64 20 6f 70 74 69 6f 6e 0a  he third option.
15700 2a 2a 20 6f 70 65 6e 73 20 74 68 65 20 64 61 74  ** opens the dat
15710 61 62 61 73 65 20 66 6f 72 20 72 65 61 64 69 6e  abase for readin
15720 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20 61 6e  g and writing an
15730 64 20 63 72 65 61 74 65 73 20 69 74 20 69 66 20  d creates it if 
15740 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 61  it does.** not a
15750 6c 72 65 61 64 79 20 65 78 69 73 74 2e 0a 2a 2a  lready exist..**
15760 20 54 68 65 20 74 68 69 72 64 20 6f 70 74 69 6f   The third optio
15770 6e 73 20 69 73 20 62 65 68 61 76 69 6f 72 20 74  ns is behavior t
15780 68 61 74 20 69 73 20 61 6c 77 61 79 73 20 75 73  hat is always us
15790 65 64 20 66 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ed for [sqlite3_
157a0 6f 70 65 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b  open()].** and [
157b0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
157c0 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  ]..**.** If the 
157d0 66 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65  filename is ":me
157e0 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 6e 20  mory:", then an 
157f0 70 72 69 76 61 74 65 0a 2a 2a 20 69 6e 2d 6d 65  private.** in-me
15800 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20 69 73  mory database is
15810 20 63 72 65 61 74 65 64 20 66 6f 72 20 74 68 65   created for the
15820 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68   connection.  Th
15830 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20  is in-memory.** 
15840 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61  database will va
15850 6e 69 73 68 20 77 68 65 6e 20 74 68 65 20 64 61  nish when the da
15860 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
15870 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 46 75  n is closed.  Fu
15880 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20  ture.** version 
15890 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20  of SQLite might 
158a0 6d 61 6b 65 20 75 73 65 20 6f 66 20 61 64 64 69  make use of addi
158b0 74 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20 66  tional special f
158c0 69 6c 65 6e 61 6d 65 73 0a 2a 2a 20 74 68 61 74  ilenames.** that
158d0 20 62 65 67 69 6e 20 77 69 74 68 20 74 68 65 20   begin with the 
158e0 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e 20 20  ":" character.  
158f0 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  It is recommende
15900 64 20 74 68 61 74 20 0a 2a 2a 20 77 68 65 6e 20  d that .** when 
15910 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e  a database filen
15920 61 6d 65 20 72 65 61 6c 6c 79 20 64 6f 65 73 20  ame really does 
15930 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 22 3a  begin with.** ":
15940 22 20 74 68 61 74 20 79 6f 75 20 70 72 65 66 69  " that you prefi
15950 78 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77  x the filename w
15960 69 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20 6c  ith a pathname l
15970 69 6b 65 20 22 2e 2f 22 20 74 6f 0a 2a 2a 20 61  ike "./" to.** a
15980 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79 2e 0a  void ambiguity..
15990 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 6c  **.** If the fil
159a0 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d 70 74  ename is an empt
159b0 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 61  y string, then a
159c0 20 70 72 69 76 61 74 65 20 74 65 6d 70 6f 72 61   private tempora
159d0 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61  ry.** on-disk da
159e0 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63  tabase will be c
159f0 72 65 61 74 65 64 2e 20 20 54 68 69 73 20 70 72  reated.  This pr
15a00 69 76 61 74 65 20 64 61 74 61 62 61 73 65 20 77  ivate database w
15a10 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61  ill be.** automa
15a20 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20  tically deleted 
15a30 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 64  as soon as the d
15a40 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
15a50 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a  on is closed..**
15a60 0a 2a 2a 20 54 68 65 20 66 6f 75 72 74 68 20 70  .** The fourth p
15a70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
15a80 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
15a90 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
15aa0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  .** [sqlite3_vfs
15ab0 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65  ] object that de
15ac0 66 69 6e 65 73 20 74 68 65 20 6f 70 65 72 61 74  fines the operat
15ad0 69 6e 67 20 73 79 73 74 65 6d 20 0a 2a 2a 20 69  ing system .** i
15ae0 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 74 68  nterface that th
15af0 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63  e new database c
15b00 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64  onnection should
15b10 20 75 73 65 2e 20 20 49 66 20 74 68 65 0a 2a 2a   use.  If the.**
15b20 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
15b30 72 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  r is a NULL poin
15b40 74 65 72 20 74 68 65 6e 20 74 68 65 20 64 65 66  ter then the def
15b50 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
15b60 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 69 73 20  s].** object is 
15b70 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e  used..**.** <b>N
15b80 6f 74 65 20 74 6f 20 77 69 6e 64 6f 77 73 20 75  ote to windows u
15b90 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65  sers:</b>  The e
15ba0 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 66 6f 72  ncoding used for
15bb0 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72   the filename ar
15bc0 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 5b 73 71  gument.** of [sq
15bd0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 61 6e  lite3_open()] an
15be0 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  d [sqlite3_open_
15bf0 76 32 28 29 5d 20 6d 75 73 74 20 62 65 20 55 54  v2()] must be UT
15c00 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65  F-8, not whateve
15c10 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73  r.** codepage is
15c20 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e   currently defin
15c30 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63  ed.  Filenames c
15c40 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e  ontaining intern
15c50 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61  ational.** chara
15c60 63 74 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f  cters must be co
15c70 6e 76 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38  nverted to UTF-8
15c80 20 70 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e   prior to passin
15c90 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 5b  g them into.** [
15ca0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20  sqlite3_open()] 
15cb0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  or [sqlite3_open
15cc0 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e  _v2()]..**.** IN
15cd0 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
15ce0 7b 46 31 32 37 30 31 7d 20 54 68 65 20 5b 73 71  {F12701} The [sq
15cf0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b  lite3_open()], [
15d00 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
15d10 5d 2c 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20  ], and.**       
15d20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e     [sqlite3_open
15d30 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65  _v2()] interface
15d40 73 20 63 72 65 61 74 65 20 61 20 6e 65 77 0a 2a  s create a new.*
15d50 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61 74 61  *          [data
15d60 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
15d70 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
15d80 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
15d90 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 67   database file g
15da0 69 76 65 6e 20 69 6e 20 74 68 65 69 72 20 66 69  iven in their fi
15db0 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  rst parameter..*
15dc0 2a 0a 2a 2a 20 7b 46 31 32 37 30 32 7d 20 54 68  *.** {F12702} Th
15dd0 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  e filename argum
15de0 65 6e 74 20 69 73 20 69 6e 74 65 72 70 72 65 74  ent is interpret
15df0 65 64 20 61 73 20 55 54 46 2d 38 0a 2a 2a 20 20  ed as UTF-8.**  
15e00 20 20 20 20 20 20 20 20 66 6f 72 20 5b 73 71 6c          for [sql
15e10 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 61 6e 64  ite3_open()] and
15e20 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
15e30 32 28 29 5d 20 61 6e 64 20 61 73 20 55 54 46 2d  2()] and as UTF-
15e40 31 36 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  16.**          i
15e50 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74  n the native byt
15e60 65 20 6f 72 64 65 72 20 66 6f 72 20 5b 73 71 6c  e order for [sql
15e70 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a  ite3_open16()]..
15e80 2a 2a 0a 2a 2a 20 7b 46 31 32 37 30 33 7d 20 41  **.** {F12703} A
15e90 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f   successful invo
15ea0 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74  cation of [sqlit
15eb0 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c  e3_open()], [sql
15ec0 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20  ite3_open16()], 
15ed0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
15ee0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
15ef0 28 29 5d 20 77 72 69 74 65 73 20 61 20 70 6f 69  ()] writes a poi
15f00 6e 74 65 72 20 74 6f 20 61 20 6e 65 77 0a 2a 2a  nter to a new.**
15f10 20 20 20 20 20 20 20 20 20 20 5b 64 61 74 61 62            [datab
15f20 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
15f30 69 6e 74 6f 20 2a 70 70 44 62 2e 0a 2a 2a 0a 2a  into *ppDb..**.*
15f40 2a 20 7b 46 31 32 37 30 34 7d 20 54 68 65 20 5b  * {F12704} The [
15f50 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
15f60 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
15f70 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 20 20 20 20  ()], and.**     
15f80 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f 70       [sqlite3_op
15f90 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61  en_v2()] interfa
15fa0 63 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ces return [SQLI
15fb0 54 45 5f 4f 4b 5d 20 75 70 6f 6e 20 73 75 63 63  TE_OK] upon succ
15fc0 65 73 73 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ess,.**         
15fd0 20 6f 72 20 61 6e 20 61 70 70 72 6f 70 72 69 61   or an appropria
15fe0 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  te [error code] 
15ff0 6f 6e 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a  on failure..**.*
16000 2a 20 7b 46 31 32 37 30 36 7d 20 54 68 65 20 64  * {F12706} The d
16010 65 66 61 75 6c 74 20 74 65 78 74 20 65 6e 63 6f  efault text enco
16020 64 69 6e 67 20 66 6f 72 20 61 20 6e 65 77 20 64  ding for a new d
16030 61 74 61 62 61 73 65 20 63 72 65 61 74 65 64 20  atabase created 
16040 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20  using.**        
16050 20 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28    [sqlite3_open(
16060 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f  )] or [sqlite3_o
16070 70 65 6e 5f 76 32 28 29 5d 20 77 69 6c 6c 20 62  pen_v2()] will b
16080 65 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b  e UTF-8..**.** {
16090 46 31 32 37 30 37 7d 20 54 68 65 20 64 65 66 61  F12707} The defa
160a0 75 6c 74 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  ult text encodin
160b0 67 20 66 6f 72 20 61 20 6e 65 77 20 64 61 74 61  g for a new data
160c0 62 61 73 65 20 63 72 65 61 74 65 64 20 75 73 69  base created usi
160d0 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ng.**          [
160e0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
160f0 5d 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 31 36  ] will be UTF-16
16100 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 30 39 7d  ..**.** {F12709}
16110 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70   The [sqlite3_op
16120 65 6e 28 46 2c 44 29 5d 20 69 6e 74 65 72 66 61  en(F,D)] interfa
16130 63 65 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74  ce is equivalent
16140 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   to.**          
16150 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
16160 28 46 2c 44 2c 47 2c 30 29 5d 20 77 68 65 72 65  (F,D,G,0)] where
16170 20 74 68 65 20 47 20 70 61 72 61 6d 65 74 65 72   the G parameter
16180 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   is.**          
16190 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
161a0 44 57 52 49 54 45 5d 7c 5b 53 51 4c 49 54 45 5f  DWRITE]|[SQLITE_
161b0 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 0a 2a 2a  OPEN_CREATE]..**
161c0 0a 2a 2a 20 7b 46 31 32 37 31 31 7d 20 49 66 20  .** {F12711} If 
161d0 74 68 65 20 47 20 70 61 72 61 6d 65 74 65 72 20  the G parameter 
161e0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  to [sqlite3_open
161f0 5f 76 32 28 46 2c 44 2c 47 2c 56 29 5d 20 63 6f  _v2(F,D,G,V)] co
16200 6e 74 61 69 6e 73 20 74 68 65 0a 2a 2a 20 20 20  ntains the.**   
16210 20 20 20 20 20 20 20 62 69 74 20 76 61 6c 75 65         bit value
16220 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
16230 41 44 4f 4e 4c 59 5d 20 74 68 65 6e 20 74 68 65  ADONLY] then the
16240 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
16250 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ned.**          
16260 66 6f 72 20 72 65 61 64 69 6e 67 20 6f 6e 6c 79  for reading only
16270 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 31 32 7d  ..**.** {F12712}
16280 20 49 66 20 74 68 65 20 47 20 70 61 72 61 6d 65   If the G parame
16290 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
162a0 6f 70 65 6e 5f 76 32 28 46 2c 44 2c 47 2c 56 29  open_v2(F,D,G,V)
162b0 5d 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 0a 2a  ] contains the.*
162c0 2a 20 20 20 20 20 20 20 20 20 20 62 69 74 20 76  *          bit v
162d0 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  alue [SQLITE_OPE
162e0 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 74 68 65  N_READWRITE] the
162f0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  n the database i
16300 73 20 6f 70 65 6e 65 64 0a 2a 2a 20 20 20 20 20  s opened.**     
16310 20 20 20 20 20 72 65 61 64 69 6e 67 20 61 6e 64       reading and
16320 20 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73   writing if poss
16330 69 62 6c 65 2c 20 6f 72 20 66 6f 72 20 72 65 61  ible, or for rea
16340 64 69 6e 67 20 6f 6e 6c 79 20 69 66 20 74 68 65  ding only if the
16350 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c  .**          fil
16360 65 20 69 73 20 77 72 69 74 65 20 70 72 6f 74 65  e is write prote
16370 63 74 65 64 20 62 79 20 74 68 65 20 6f 70 65 72  cted by the oper
16380 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 0a 2a 2a  ating system..**
16390 0a 2a 2a 20 7b 46 31 32 37 31 33 7d 20 49 66 20  .** {F12713} If 
163a0 74 68 65 20 47 20 70 61 72 61 6d 65 74 65 72 20  the G parameter 
163b0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  to [sqlite3_open
163c0 28 76 32 28 46 2c 44 2c 47 2c 56 29 5d 20 6f 6d  (v2(F,D,G,V)] om
163d0 69 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  its the.**      
163e0 20 20 20 20 62 69 74 20 76 61 6c 75 65 20 5b 53      bit value [S
163f0 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
16400 45 5d 20 61 6e 64 20 74 68 65 20 64 61 74 61 62  E] and the datab
16410 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20  ase does not.** 
16420 20 20 20 20 20 20 20 20 20 70 72 65 76 69 6f 75           previou
16430 73 6c 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72  sly exist, an er
16440 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ror is returned.
16450 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 31 34 7d 20  .**.** {F12714} 
16460 49 66 20 74 68 65 20 47 20 70 61 72 61 6d 65 74  If the G paramet
16470 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f  er to [sqlite3_o
16480 70 65 6e 28 76 32 28 46 2c 44 2c 47 2c 56 29 5d  pen(v2(F,D,G,V)]
16490 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 0a 2a 2a   contains the.**
164a0 20 20 20 20 20 20 20 20 20 20 62 69 74 20 76 61            bit va
164b0 6c 75 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  lue [SQLITE_OPEN
164c0 5f 43 52 45 41 54 45 5d 20 61 6e 64 20 74 68 65  _CREATE] and the
164d0 20 64 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e   database does n
164e0 6f 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70  ot.**          p
164f0 72 65 76 69 6f 75 73 6c 79 20 65 78 69 73 74 2c  reviously exist,
16500 20 74 68 65 6e 20 61 6e 20 61 74 74 65 6d 70 74   then an attempt
16510 20 69 73 20 6d 61 64 65 20 74 6f 20 63 72 65 61   is made to crea
16520 74 65 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20  te and.**       
16530 20 20 20 69 6e 69 74 69 61 6c 69 7a 65 20 74 68     initialize th
16540 65 20 64 61 74 61 62 61 73 65 2e 0a 2a 2a 0a 2a  e database..**.*
16550 2a 20 7b 46 31 32 37 31 37 7d 20 49 66 20 74 68  * {F12717} If th
16560 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  e filename argum
16570 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ent to [sqlite3_
16580 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
16590 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 0a 2a 2a 20  3_open16()],.** 
165a0 20 20 20 20 20 20 20 20 20 6f 72 20 5b 73 71 6c           or [sql
165b0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20  ite3_open_v2()] 
165c0 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74  is ":memory:", t
165d0 68 65 6e 20 61 6e 20 70 72 69 76 61 74 65 2c 0a  hen an private,.
165e0 2a 2a 20 20 20 20 20 20 20 20 20 20 65 70 68 65  **          ephe
165f0 6d 65 72 61 6c 2c 20 69 6e 2d 6d 65 6d 6f 72 79  meral, in-memory
16600 20 64 61 74 61 62 61 73 65 20 69 73 20 63 72 65   database is cre
16610 61 74 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e  ated for the con
16620 6e 65 63 74 69 6f 6e 2e 0a 2a 2a 20 20 20 20 20  nection..**     
16630 20 20 20 20 20 3c 74 6f 64 6f 3e 49 73 20 53 51       <todo>Is SQ
16640 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
16650 7c 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  |SQLITE_OPEN_REA
16660 44 57 52 49 54 45 20 72 65 71 75 69 72 65 64 0a  DWRITE required.
16670 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 73  **          in s
16680 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
16690 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 7b  ?</todo>.**.** {
166a0 46 31 32 37 31 39 7d 20 49 66 20 74 68 65 20 66  F12719} If the f
166b0 69 6c 65 6e 61 6d 65 20 69 73 20 4e 55 4c 4c 20  ilename is NULL 
166c0 6f 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  or an empty stri
166d0 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61  ng, then a priva
166e0 74 65 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  te,.**          
166f0 65 70 68 65 72 6d 65 72 61 6c 20 6f 6e 2d 64 69  ephermeral on-di
16700 73 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  sk database will
16710 20 62 65 20 63 72 65 61 74 65 64 2e 0a 2a 2a 20   be created..** 
16720 20 20 20 20 20 20 20 20 20 3c 74 6f 64 6f 3e 49           <todo>I
16730 73 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52  s SQLITE_OPEN_CR
16740 45 41 54 45 7c 53 51 4c 49 54 45 5f 4f 50 45 4e  EATE|SQLITE_OPEN
16750 5f 52 45 41 44 57 52 49 54 45 20 72 65 71 75 69  _READWRITE requi
16760 72 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  red.**          
16770 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  in sqlite3_open_
16780 76 32 28 29 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a  v2()?</todo>.**.
16790 2a 2a 20 7b 46 31 32 37 32 31 7d 20 54 68 65 20  ** {F12721} The 
167a0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
167b0 74 69 6f 6e 5d 20 63 72 65 61 74 65 64 20 62 79  tion] created by
167c0 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73   .**          [s
167d0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 46  qlite3_open_v2(F
167e0 2c 44 2c 47 2c 56 29 5d 20 77 69 6c 6c 20 75 73  ,D,G,V)] will us
167f0 65 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  e the.**        
16800 20 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20    [sqlite3_vfs] 
16810 6f 62 6a 65 63 74 20 69 64 65 6e 74 69 66 69 65  object identifie
16820 64 20 62 79 20 74 68 65 20 56 20 70 61 72 61 6d  d by the V param
16830 65 74 65 72 2c 20 6f 72 0a 2a 2a 20 20 20 20 20  eter, or.**     
16840 20 20 20 20 20 74 68 65 20 64 65 66 61 75 6c 74       the default
16850 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
16860 62 6a 65 63 74 20 69 73 20 56 20 69 73 20 61 20  bject is V is a 
16870 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f  NULL pointer..*/
16880 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65  .int sqlite3_ope
16890 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  n(.  const char 
168a0 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20  *filename,   /* 
168b0 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  Database filenam
168c0 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73  e (UTF-8) */.  s
168d0 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20  qlite3 **ppDb   
168e0 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53         /* OUT: S
168f0 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20  QLite db handle 
16900 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
16910 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73  3_open16(.  cons
16920 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65  t void *filename
16930 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  ,   /* Database 
16940 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31 36  filename (UTF-16
16950 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a  ) */.  sqlite3 *
16960 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f  *ppDb          /
16970 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62  * OUT: SQLite db
16980 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e   handle */.);.in
16990 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  t sqlite3_open_v
169a0 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  2(.  const char 
169b0 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20  *filename,   /* 
169c0 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  Database filenam
169d0 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73  e (UTF-8) */.  s
169e0 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20  qlite3 **ppDb,  
169f0 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53         /* OUT: S
16a00 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20  QLite db handle 
16a10 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20  */.  int flags, 
16a20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
16a30 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74  Flags */.  const
16a40 20 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20   char *zVfs     
16a50 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46     /* Name of VF
16a60 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20  S module to use 
16a70 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
16a80 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64  I3REF: Error Cod
16a90 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73 20  es And Messages 
16aa0 7b 46 31 32 38 30 30 7d 0a 2a 2a 0a 2a 2a 20 54  {F12800}.**.** T
16ab0 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  he sqlite3_errco
16ac0 64 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  de() interface r
16ad0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72  eturns the numer
16ae0 69 63 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b  ic.** [SQLITE_OK
16af0 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20   | result code] 
16b00 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  or [SQLITE_IOERR
16b10 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64  _READ | extended
16b20 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 0a 2a 2a   result code].**
16b30 20 66 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 65   for the most re
16b40 63 65 6e 74 20 66 61 69 6c 65 64 20 73 71 6c 69  cent failed sqli
16b50 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 20 61  te3_* API call a
16b60 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74  ssociated.** wit
16b70 68 20 5b 73 71 6c 69 74 65 33 5d 20 68 61 6e 64  h [sqlite3] hand
16b80 6c 65 20 27 64 62 27 2e 20 49 66 20 61 20 70 72  le 'db'. If a pr
16b90 69 6f 72 20 41 50 49 20 63 61 6c 6c 20 66 61 69  ior API call fai
16ba0 6c 65 64 20 62 75 74 20 74 68 65 0a 2a 2a 20 6d  led but the.** m
16bb0 6f 73 74 20 72 65 63 65 6e 74 20 41 50 49 20 63  ost recent API c
16bc0 61 6c 6c 20 73 75 63 63 65 65 64 65 64 2c 20 74  all succeeded, t
16bd0 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
16be0 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 65 72 72  from sqlite3_err
16bf0 63 6f 64 65 28 29 0a 2a 2a 20 69 73 20 75 6e 64  code().** is und
16c00 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  efined..**.** Th
16c10 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67  e sqlite3_errmsg
16c20 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65  () and sqlite3_e
16c30 72 72 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e  rrmsg16() return
16c40 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67   English-languag
16c50 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64  e.** text that d
16c60 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72  escribes the err
16c70 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20 55 54  or, as either UT
16c80 46 38 20 6f 72 20 55 54 46 31 36 20 72 65 73 70  F8 or UTF16 resp
16c90 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 4d 65 6d  ectively..** Mem
16ca0 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ory to hold the 
16cb0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74  error message st
16cc0 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20  ring is managed 
16cd0 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54  internally..** T
16ce0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
16cf0 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  oes not need to 
16d00 77 6f 72 72 79 20 77 69 74 68 20 66 72 65 65 69  worry with freei
16d10 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a  ng the result..*
16d20 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 65  * However, the e
16d30 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69 67 68  rror string migh
16d40 74 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e  t be overwritten
16d50 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   or deallocated 
16d60 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74  by.** subsequent
16d70 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20   calls to other 
16d80 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
16d90 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a   functions..**.*
16da0 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
16db0 0a 2a 2a 20 7b 46 31 32 38 30 31 7d 20 54 68 65  .** {F12801} The
16dc0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64   [sqlite3_errcod
16dd0 65 28 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20  e(D)] interface 
16de0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65  returns the nume
16df0 72 69 63 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ric.**          
16e00 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 72 65 73  [SQLITE_OK | res
16e10 75 6c 74 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20  ult code] or.** 
16e20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45           [SQLITE
16e30 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 65 78  _IOERR_READ | ex
16e40 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
16e50 64 65 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  de].**          
16e60 66 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 65 63  for the most rec
16e70 65 6e 74 6c 79 20 66 61 69 6c 65 64 20 69 6e 74  ently failed int
16e80 65 72 66 61 63 65 20 63 61 6c 6c 20 61 73 73 6f  erface call asso
16e90 63 69 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20  ciated.**       
16ea0 20 20 20 77 69 74 68 20 5b 64 61 74 61 62 61 73     with [databas
16eb0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e  e connection] D.
16ec0 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 38 30 33 7d 20  .**.** {F12803} 
16ed0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  The [sqlite3_err
16ee0 6d 73 67 28 44 29 5d 20 61 6e 64 20 5b 73 71 6c  msg(D)] and [sql
16ef0 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 44 29  ite3_errmsg16(D)
16f00 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  ].**          in
16f10 74 65 72 66 61 63 65 73 20 72 65 74 75 72 6e 20  terfaces return 
16f20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65  English-language
16f30 20 74 65 78 74 20 74 68 61 74 20 64 65 73 63 72   text that descr
16f40 69 62 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  ibes.**         
16f50 20 74 68 65 20 65 72 72 6f 72 20 69 6e 20 74 68   the error in th
16f60 65 20 6d 6f 73 74 6c 79 20 72 65 63 65 6e 74 6c  e mostly recentl
16f70 79 20 66 61 69 6c 65 64 20 69 6e 74 65 72 66 61  y failed interfa
16f80 63 65 20 63 61 6c 6c 2c 0a 2a 2a 20 20 20 20 20  ce call,.**     
16f90 20 20 20 20 20 65 6e 63 6f 64 65 64 20 61 73 20       encoded as 
16fa0 65 69 74 68 65 72 20 55 54 46 38 20 6f 72 20 55  either UTF8 or U
16fb0 54 46 31 36 20 72 65 73 70 65 63 74 69 76 65 6c  TF16 respectivel
16fc0 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 38 30 37  y..**.** {F12807
16fd0 7d 20 54 68 65 20 73 74 72 69 6e 67 73 20 72 65  } The strings re
16fe0 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
16ff0 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 61 6e 64  e3_errmsg()] and
17000 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
17010 31 36 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  16()].**        
17020 20 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69    are valid unti
17030 6c 20 74 68 65 20 6e 65 78 74 20 53 51 4c 69 74  l the next SQLit
17040 65 20 69 6e 74 65 72 66 61 63 65 20 63 61 6c 6c  e interface call
17050 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 38 30 38 7d  ..**.** {F12808}
17060 20 43 61 6c 6c 73 20 74 6f 20 41 50 49 20 72 6f   Calls to API ro
17070 75 74 69 6e 65 73 20 74 68 61 74 20 64 6f 20 6e  utines that do n
17080 6f 74 20 72 65 74 75 72 6e 20 61 6e 20 65 72 72  ot return an err
17090 6f 72 20 63 6f 64 65 0a 2a 2a 20 20 20 20 20 20  or code.**      
170a0 20 20 20 20 28 65 78 61 6d 70 6c 65 3a 20 5b 73      (example: [s
170b0 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
170c0 74 28 29 5d 29 20 64 6f 20 6e 6f 74 0a 2a 2a 20  t()]) do not.** 
170d0 20 20 20 20 20 20 20 20 20 63 68 61 6e 67 65 20           change 
170e0 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 6f  the error code o
170f0 72 20 6d 65 73 73 61 67 65 20 72 65 74 75 72 6e  r message return
17100 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20  ed by.**        
17110 20 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f    [sqlite3_errco
17120 64 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  de()], [sqlite3_
17130 65 72 72 6d 73 67 28 29 5d 2c 20 6f 72 20 5b 73  errmsg()], or [s
17140 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
17150 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 38 30  )]..**.** {F1280
17160 39 7d 20 49 6e 74 65 72 66 61 63 65 73 20 74 68  9} Interfaces th
17170 61 74 20 61 72 65 20 6e 6f 74 20 61 73 73 6f 63  at are not assoc
17180 69 61 74 65 64 20 77 69 74 68 20 61 20 73 70 65  iated with a spe
17190 63 69 66 69 63 0a 2a 2a 20 20 20 20 20 20 20 20  cific.**        
171a0 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e    [database conn
171b0 65 63 74 69 6f 6e 5d 20 28 65 78 61 6d 70 6c 65  ection] (example
171c0 73 3a 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  s:.**          [
171d0 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
171e0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65  )] or [sqlite3_e
171f0 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63  nable_shared_cac
17200 68 65 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  he()].**        
17210 20 20 64 6f 20 6e 6f 74 20 63 68 61 6e 67 65 20    do not change 
17220 74 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72  the values retur
17230 6e 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20  ned by.**       
17240 20 20 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63     [sqlite3_errc
17250 6f 64 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  ode()], [sqlite3
17260 5f 65 72 72 6d 73 67 28 29 5d 2c 20 6f 72 20 5b  _errmsg()], or [
17270 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
17280 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
17290 74 65 33 5f 65 72 72 63 6f 64 65 28 73 71 6c 69  te3_errcode(sqli
172a0 74 65 33 20 2a 64 62 29 3b 0a 63 6f 6e 73 74 20  te3 *db);.const 
172b0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72  char *sqlite3_er
172c0 72 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a  rmsg(sqlite3*);.
172d0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
172e0 74 65 33 5f 65 72 72 6d 73 67 31 36 28 73 71 6c  te3_errmsg16(sql
172f0 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
17300 41 50 49 33 52 45 46 3a 20 53 51 4c 20 53 74 61  API3REF: SQL Sta
17310 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 20 7b 46  tement Object {F
17320 31 33 30 30 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52  13000}.** KEYWOR
17330 44 53 3a 20 7b 70 72 65 70 61 72 65 64 20 73 74  DS: {prepared st
17340 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72  atement} {prepar
17350 65 64 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a  ed statements}.*
17360 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65  *.** An instance
17370 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20   of this object 
17380 72 65 70 72 65 73 65 6e 74 20 73 69 6e 67 6c 65  represent single
17390 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e   SQL statements.
173a0 20 20 54 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74    This.** object
173b0 20 69 73 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e   is variously kn
173c0 6f 77 6e 20 61 73 20 61 20 22 70 72 65 70 61 72  own as a "prepar
173d0 65 64 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72  ed statement" or
173e0 20 61 20 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64   a .** "compiled
173f0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 22 20   SQL statement" 
17400 6f 72 20 73 69 6d 70 6c 79 20 61 73 20 61 20 22  or simply as a "
17410 73 74 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a 20 0a  statement"..** .
17420 2a 2a 20 54 68 65 20 6c 69 66 65 20 6f 66 20 61  ** The life of a
17430 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63   statement objec
17440 74 20 67 6f 65 73 20 73 6f 6d 65 74 68 69 6e 67  t goes something
17450 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a   like this:.**.*
17460 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43  * <ol>.** <li> C
17470 72 65 61 74 65 20 74 68 65 20 6f 62 6a 65 63 74  reate the object
17480 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
17490 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
174a0 20 61 20 72 65 6c 61 74 65 64 0a 2a 2a 20 20 20   a related.**   
174b0 20 20 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20     function..** 
174c0 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73  <li> Bind values
174d0 20 74 6f 20 68 6f 73 74 20 70 61 72 61 6d 65 74   to host paramet
174e0 65 72 73 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20  ers using.**    
174f0 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f    [sqlite3_bind_
17500 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62  blob | sqlite3_b
17510 69 6e 64 5f 2a 20 69 6e 74 65 72 66 61 63 65 73  ind_* interfaces
17520 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74  ]..** <li> Run t
17530 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e  he SQL by callin
17540 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  g [sqlite3_step(
17550 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74  )] one or more t
17560 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65  imes..** <li> Re
17570 73 65 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e  set the statemen
17580 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
17590 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67  _reset()] then g
175a0 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74  o back.**      t
175b0 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68  o step 2.  Do th
175c0 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20  is zero or more 
175d0 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44  times..** <li> D
175e0 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63  estroy the objec
175f0 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
17600 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a  _finalize()]..**
17610 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66   </ol>.**.** Ref
17620 65 72 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74  er to documentat
17630 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61  ion on individua
17640 6c 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  l methods above 
17650 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  for additional.*
17660 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  * information..*
17670 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
17680 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71   sqlite3_stmt sq
17690 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a  lite3_stmt;../*.
176a0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e  ** CAPI3REF: Run
176b0 2d 74 69 6d 65 20 4c 69 6d 69 74 73 20 7b 46 31  -time Limits {F1
176c0 32 37 36 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73  2760}.**.** This
176d0 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77   interface allow
176e0 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 76 61  s the size of va
176f0 72 69 6f 75 73 20 63 6f 6e 73 74 72 75 63 74 73  rious constructs
17700 20 74 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a   to be limited.*
17710 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f  * on a connectio
17720 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  n by connection 
17730 62 61 73 69 73 2e 20 20 54 68 65 20 66 69 72 73  basis.  The firs
17740 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  t parameter is t
17750 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  he.** [database 
17760 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73  connection] whos
17770 65 20 6c 69 6d 69 74 20 69 73 20 74 6f 20 62 65  e limit is to be
17780 20 73 65 74 20 6f 72 20 71 75 65 72 69 65 64 2e   set or queried.
17790 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20    The.** second 
177a0 70 61 72 61 6d 65 74 65 72 20 69 73 20 6f 6e 65  parameter is one
177b0 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74 20 63   of the [limit c
177c0 61 74 65 67 6f 72 69 65 73 5d 20 74 68 61 74 20  ategories] that 
177d0 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73  define a.** clas
177e0 73 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 73 20  s of constructs 
177f0 74 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d 69 74  to be size limit
17800 65 64 2e 20 20 54 68 65 20 74 68 69 72 64 20 70  ed.  The third p
17810 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a  arameter is the.
17820 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72  ** new limit for
17830 20 74 68 61 74 20 63 6f 6e 73 74 72 75 63 74 2e   that construct.
17840 20 20 54 68 65 20 66 75 6e 63 74 69 6f 6e 20 72    The function r
17850 65 74 75 72 6e 73 20 74 68 65 20 6f 6c 64 20 6c  eturns the old l
17860 69 6d 69 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  imit..**.** If t
17870 68 65 20 6e 65 77 20 6c 69 6d 69 74 20 69 73 20  he new limit is 
17880 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65  a negative numbe
17890 72 2c 20 74 68 65 20 6c 69 6d 69 74 20 69 73 20  r, the limit is 
178a0 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 46 6f  unchanged..** Fo
178b0 72 20 74 68 65 20 6c 69 6d 69 74 20 63 61 74 65  r the limit cate
178c0 67 6f 72 79 20 6f 66 20 53 51 4c 49 54 45 5f 4c  gory of SQLITE_L
178d0 49 4d 49 54 5f 58 59 5a 20 74 68 65 72 65 20 69  IMIT_XYZ there i
178e0 73 20 61 20 68 61 72 64 20 75 70 70 65 72 0a 2a  s a hard upper.*
178f0 2a 20 62 6f 75 6e 64 20 73 65 74 20 62 79 20 61  * bound set by a
17900 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 43 2d   compile-time C-
17910 70 72 65 70 72 6f 63 65 73 73 20 6d 61 63 72 6f  preprocess macro
17920 20 6e 61 6d 65 64 20 53 51 4c 49 54 45 5f 4d 41   named SQLITE_MA
17930 58 5f 58 59 5a 2e 0a 2a 2a 20 28 54 68 65 20 22  X_XYZ..** (The "
17940 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68 65 20  _LIMIT_" in the 
17950 6e 61 6d 65 20 69 73 20 63 68 61 6e 67 65 64 20  name is changed 
17960 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 0a 2a 2a 20  to "_MAX_".).** 
17970 41 74 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 72  Attempts to incr
17980 65 61 73 65 20 61 20 6c 69 6d 69 74 20 61 62 6f  ease a limit abo
17990 76 65 20 69 74 73 20 68 61 72 64 20 75 70 70 65  ve its hard uppe
179a0 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73  r bound are.** s
179b0 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65  ilently truncate
179c0 64 20 74 6f 20 74 68 65 20 68 61 72 64 20 75 70  d to the hard up
179d0 70 65 72 20 6c 69 6d 69 74 2e 0a 2a 2a 0a 2a 2a  per limit..**.**
179e0 20 52 75 6e 20 74 69 6d 65 20 6c 69 6d 69 74 73   Run time limits
179f0 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f   are intended fo
17a00 72 20 75 73 65 20 69 6e 20 61 70 70 6c 69 63 61  r use in applica
17a10 74 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61 67  tions that manag
17a20 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69 72 20  e.** both their 
17a30 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  own internal dat
17a40 61 62 61 73 65 20 61 6e 64 20 61 6c 73 6f 20 64  abase and also d
17a50 61 74 61 62 61 73 65 73 20 74 68 61 74 20 61 72  atabases that ar
17a60 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20  e controlled.** 
17a70 62 79 20 75 6e 74 72 75 73 74 65 64 20 65 78 74  by untrusted ext
17a80 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20 20  ernal sources.  
17a90 41 6e 20 65 78 61 6d 70 6c 65 20 61 70 70 6c 69  An example appli
17aa0 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20  cation might be 
17ab0 61 0a 2a 2a 20 77 65 62 62 72 6f 77 73 65 72 20  a.** webbrowser 
17ac0 74 68 61 74 20 68 61 73 20 69 74 73 20 6f 77 6e  that has its own
17ad0 20 64 61 74 61 62 61 73 65 73 20 66 6f 72 20 73   databases for s
17ae0 74 6f 72 69 6e 67 20 68 69 73 74 6f 72 79 20 61  toring history a
17af0 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74 65 20 64  nd.** separate d
17b00 61 74 61 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c  atabases control
17b10 6c 65 64 20 62 79 20 6a 61 76 61 73 63 72 69 70  led by javascrip
17b20 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 64  t applications d
17b30 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66  ownloaded.** off
17b40 20 74 68 65 20 69 6e 74 65 72 6e 65 74 2e 20 20   the internet.  
17b50 54 68 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  The internal dat
17b60 61 62 61 73 65 73 20 63 61 6e 20 62 65 20 67 69  abases can be gi
17b70 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65  ven the.** large
17b80 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d 69 74 73  , default limits
17b90 2e 20 20 44 61 74 61 62 61 73 65 73 20 6d 61 6e  .  Databases man
17ba0 61 67 65 64 20 62 79 20 65 78 74 65 72 6e 61 6c  aged by external
17bb0 20 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20   sources can.** 
17bc0 62 65 20 67 69 76 65 6e 20 6d 75 63 68 20 73 6d  be given much sm
17bd0 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64 65 73  aller limits des
17be0 69 67 6e 65 64 20 74 6f 20 70 72 65 76 65 6e 74  igned to prevent
17bf0 20 61 20 64 65 6e 69 61 6c 20 6f 66 20 73 65 72   a denial of ser
17c00 76 69 63 65 0a 2a 2a 20 61 74 74 61 63 68 2e 20  vice.** attach. 
17c10 20 44 65 76 65 6c 6f 70 65 72 73 20 6d 69 67 68   Developers migh
17c20 74 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75  t also want to u
17c30 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  se the [sqlite3_
17c40 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29  set_authorizer()
17c50 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 74  ].** interface t
17c60 6f 20 66 75 72 74 68 65 72 20 63 6f 6e 74 72 6f  o further contro
17c70 6c 20 75 6e 74 72 75 73 74 65 64 20 53 51 4c 2e  l untrusted SQL.
17c80 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68    The size of th
17c90 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 72  e database.** cr
17ca0 65 61 74 65 64 20 62 79 20 61 6e 20 75 6e 74 72  eated by an untr
17cb0 75 73 74 65 64 20 73 63 72 69 70 74 20 63 61 6e  usted script can
17cc0 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 75 73   be contained us
17cd0 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f  ing the.** [max_
17ce0 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41  page_count] [PRA
17cf0 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  GMA]..**.** This
17d00 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 63 75   interface is cu
17d10 72 72 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72  rrently consider
17d20 65 64 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20  ed experimental 
17d30 61 6e 64 20 69 73 20 73 75 62 6a 65 63 74 0a 2a  and is subject.*
17d40 2a 20 74 6f 20 63 68 61 6e 67 65 20 6f 72 20 72  * to change or r
17d50 65 6d 6f 76 61 6c 20 77 69 74 68 6f 75 74 20 70  emoval without p
17d60 72 69 6f 72 20 6e 6f 74 69 63 65 2e 0a 2a 2a 0a  rior notice..**.
17d70 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
17d80 2a 0a 2a 2a 20 7b 46 31 32 37 36 32 7d 20 41 20  *.** {F12762} A 
17d90 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20  successful call 
17da0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  to [sqlite3_limi
17db0 74 28 44 2c 43 2c 56 29 5d 20 77 68 65 72 65 20  t(D,C,V)] where 
17dc0 56 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  V is.**         
17dd0 20 70 6f 73 69 74 69 76 65 20 63 68 61 6e 67 65   positive change
17de0 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
17df0 20 20 6c 69 6d 69 74 20 6f 6e 20 74 68 65 20 73    limit on the s
17e00 69 7a 65 20 6f 66 20 63 6f 6e 73 74 72 75 63 74  ize of construct
17e10 20 43 20 69 6e 20 5b 64 61 74 61 62 61 73 65 20   C in [database 
17e20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a  connection] D.**
17e30 20 20 20 20 20 20 20 20 20 20 74 6f 20 74 68 65            to the
17e40 20 6c 65 73 73 6f 72 20 6f 66 20 56 20 61 6e 64   lessor of V and
17e50 20 74 68 65 20 68 61 72 64 20 75 70 70 65 72 20   the hard upper 
17e60 62 6f 75 6e 64 20 6f 6e 20 74 68 65 20 73 69 7a  bound on the siz
17e70 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66  e.**          of
17e80 20 43 20 74 68 61 74 20 69 73 20 73 65 74 20 61   C that is set a
17e90 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 2e 0a  t compile-time..
17ea0 2a 2a 0a 2a 2a 20 7b 46 31 32 37 36 34 7d 20 41  **.** {F12764} A
17eb0 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c   successful call
17ec0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d   to [sqlite3_lim
17ed0 69 74 28 44 2c 43 2c 56 29 5d 20 77 68 65 72 65  it(D,C,V)] where
17ee0 20 56 20 69 73 20 7a 65 72 6f 0a 2a 2a 20 20 20   V is zero.**   
17ef0 20 20 20 20 20 20 20 63 68 61 6e 67 65 73 20 74         changes t
17f00 68 65 20 6c 69 6d 69 74 20 6f 6e 20 74 68 65 20  he limit on the 
17f10 73 69 7a 65 20 6f 66 20 63 6f 6e 73 74 72 75 63  size of construc
17f20 74 20 43 20 69 6e 0a 2a 2a 20 20 20 20 20 20 20  t C in.**       
17f30 20 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e     [database con
17f40 6e 65 63 74 69 6f 6e 5d 20 44 20 74 6f 20 62 65  nection] D to be
17f50 20 74 68 65 20 68 61 72 64 20 75 70 70 65 72 20   the hard upper 
17f60 62 6f 75 6e 64 20 6f 6e 20 74 68 65 20 73 69 7a  bound on the siz
17f70 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66  e.**          of
17f80 20 43 20 74 68 61 74 20 69 73 20 73 65 74 20 61   C that is set a
17f90 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 2e 0a  t compile-time..
17fa0 2a 2a 0a 2a 2a 20 7b 46 31 32 37 36 36 7d 20 41  **.** {F12766} A
17fb0 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c   successful call
17fc0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d   to [sqlite3_lim
17fd0 69 74 28 44 2c 43 2c 56 29 5d 20 77 68 65 72 65  it(D,C,V)] where
17fe0 20 56 20 69 73 20 6e 65 67 61 74 69 76 65 0a 2a   V is negative.*
17ff0 2a 20 20 20 20 20 20 20 20 20 20 6c 65 61 76 65  *          leave
18000 73 20 74 68 65 20 73 74 61 74 65 20 6f 66 20 5b  s the state of [
18010 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
18020 69 6f 6e 5d 20 44 20 75 6e 63 68 61 6e 67 65 64  ion] D unchanged
18030 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 36 39 7d  ..**.** {F12769}
18040 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61   A successful ca
18050 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6c  ll to [sqlite3_l
18060 69 6d 69 74 28 44 2c 43 2c 56 29 5d 20 72 65 74  imit(D,C,V)] ret
18070 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  urns the.**     
18080 20 20 20 20 20 76 61 6c 75 65 20 6f 66 20 74 68       value of th
18090 65 20 6c 69 6d 69 74 20 6f 6e 20 74 68 65 20 73  e limit on the s
180a0 69 7a 65 20 6f 66 20 63 6f 6e 73 74 72 75 63 74  ize of construct
180b0 20 43 20 69 6e 0a 2a 2a 20 20 20 20 20 20 20 20   C in.**        
180c0 20 20 69 6e 20 5b 64 61 74 61 62 61 73 65 20 63    in [database c
180d0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 61 73 20  onnection] D as 
180e0 69 74 20 77 61 73 20 70 72 69 6f 72 20 74 6f 20  it was prior to 
180f0 74 68 65 20 63 61 6c 6c 2e 0a 2a 2f 0a 69 6e 74  the call..*/.int
18100 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73   sqlite3_limit(s
18110 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c  qlite3*, int id,
18120 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f   int newVal);../
18130 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
18140 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43 61  un-Time Limit Ca
18150 74 65 67 6f 72 69 65 73 20 7b 46 31 32 37 39 30  tegories {F12790
18160 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  }.** KEYWORDS: {
18170 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20  limit category} 
18180 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65  {limit categorie
18190 73 7d 0a 2a 2a 20 0a 2a 2a 20 54 68 65 73 65 20  s}.** .** These 
181a0 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65  constants define
181b0 20 76 61 72 69 6f 75 73 20 61 73 70 65 63 74 73   various aspects
181c0 20 6f 66 20 61 20 5b 64 61 74 61 62 61 73 65 20   of a [database 
181d0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 74  connection].** t
181e0 68 61 74 20 63 61 6e 20 62 65 20 6c 69 6d 69 74  hat can be limit
181f0 65 64 20 69 6e 20 73 69 7a 65 20 62 79 20 63 61  ed in size by ca
18200 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
18210 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65  limit()]..** The
18220 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65   meanings of the
18230 20 76 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20   various limits 
18240 61 72 65 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a  are as follows:.
18250 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64  **.** <dl>.** <d
18260 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  t>SQLITE_LIMIT_L
18270 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ENGTH</dt>.** <d
18280 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 69  d>The maximum si
18290 7a 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 73 74 72  ze of any.** str
182a0 69 6e 67 20 6f 72 20 62 6c 6f 62 20 6f 72 20 74  ing or blob or t
182b0 61 62 6c 65 20 72 6f 77 2e 3c 64 64 3e 0a 2a 2a  able row.<dd>.**
182c0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  .** <dt>SQLITE_L
182d0 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c  IMIT_SQL_LENGTH<
182e0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
182f0 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  maximum length o
18300 66 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  f an SQL stateme
18310 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  nt.</dd>.**.** <
18320 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
18330 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c  COLUMN</dt>.** <
18340 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
18350 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
18360 20 69 6e 20 61 20 74 61 62 6c 65 20 64 65 66 69   in a table defi
18370 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65  nition or in the
18380 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 20 6f  .** result set o
18390 66 20 61 20 53 45 4c 45 43 54 20 6f 72 20 74 68  f a SELECT or th
183a0 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
183b0 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61   of columns in a
183c0 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e  n index.** or in
183d0 20 61 6e 20 4f 52 44 45 52 20 42 59 20 6f 72 20   an ORDER BY or 
183e0 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73 65 2e  GROUP BY clause.
183f0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
18400 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50  SQLITE_LIMIT_EXP
18410 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20  R_DEPTH</dt>.** 
18420 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
18430 64 65 70 74 68 20 6f 66 20 74 68 65 20 70 61 72  depth of the par
18440 73 65 20 74 72 65 65 20 6f 6e 20 61 6e 79 20 65  se tree on any e
18450 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 0a  xpression.</dd>.
18460 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
18470 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f  _LIMIT_COMPOUND_
18480 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c  SELECT</dt>.** <
18490 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
184a0 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69  umber of terms i
184b0 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c  n a compound SEL
184c0 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f  ECT statement.</
184d0 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
184e0 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f  LITE_LIMIT_VDBE_
184f0 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  OP</dt>.** <dd>T
18500 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
18510 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f 6e  r of instruction
18520 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20 6d  s in a virtual m
18530 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a  achine program.*
18540 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d  * used to implem
18550 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74 65  ent an SQL state
18560 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ment.</dd>.**.**
18570 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49   <dt>SQLITE_LIMI
18580 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f  T_FUNCTION_ARG</
18590 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
185a0 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
185b0 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20   arguments on a 
185c0 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a  function.</dd>.*
185d0 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
185e0 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 3c 2f  LIMIT_ATTACHED</
185f0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
18600 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
18610 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61   attached databa
18620 73 65 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ses.</dd>.**.** 
18630 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
18640 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45  _LIKE_PATTERN_LE
18650 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NGTH</dt>.** <dd
18660 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e  >The maximum len
18670 67 74 68 20 6f 66 20 74 68 65 20 70 61 74 74 65  gth of the patte
18680 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  rn argument to t
18690 68 65 20 4c 49 4b 45 20 6f 72 0a 2a 2a 20 47 4c  he LIKE or.** GL
186a0 4f 42 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64  OB operators.</d
186b0 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
186c0 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42  ITE_LIMIT_VARIAB
186d0 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a  LE_NUMBER</dt>.*
186e0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
186f0 6d 20 6e 75 6d 62 65 72 20 6f 66 20 76 61 72 69  m number of vari
18700 61 62 6c 65 73 20 69 6e 20 61 6e 20 53 51 4c 20  ables in an SQL 
18710 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 63  statement that c
18720 61 6e 0a 2a 2a 20 62 65 20 62 6f 75 6e 64 2e 3c  an.** be bound.<
18730 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f  /dd>.** </dl>.*/
18740 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18750 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20 20  LIMIT_LENGTH    
18760 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
18770 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
18780 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54  _LIMIT_SQL_LENGT
18790 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
187a0 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
187b0 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20  E_LIMIT_COLUMN  
187c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
187d0 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
187e0 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45  TE_LIMIT_EXPR_DE
187f0 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20  PTH             
18800 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c     3.#define SQL
18810 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55  ITE_LIMIT_COMPOU
18820 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20  ND_SELECT       
18830 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51      4.#define SQ
18840 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f  LITE_LIMIT_VDBE_
18850 4f 50 20 20 20 20 20 20 20 20 20 20 20 20 20 20  OP              
18860 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53       5.#define S
18870 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43  QLITE_LIMIT_FUNC
18880 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 20 20  TION_ARG        
18890 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20        6.#define 
188a0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54  SQLITE_LIMIT_ATT
188b0 41 43 48 45 44 20 20 20 20 20 20 20 20 20 20 20  ACHED           
188c0 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65         7.#define
188d0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49   SQLITE_LIMIT_LI
188e0 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54  KE_PATTERN_LENGT
188f0 48 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e  H       8.#defin
18900 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  e SQLITE_LIMIT_V
18910 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20 20  ARIABLE_NUMBER  
18920 20 20 20 20 20 20 20 20 20 39 0a 0a 2f 2a 0a 2a           9../*.*
18930 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70  * CAPI3REF: Comp
18940 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53 74 61  iling An SQL Sta
18950 74 65 6d 65 6e 74 20 7b 46 31 33 30 31 30 7d 0a  tement {F13010}.
18960 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65  **.** To execute
18970 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 69   an SQL query, i
18980 74 20 6d 75 73 74 20 66 69 72 73 74 20 62 65 20  t must first be 
18990 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20  compiled into a 
189a0 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f  byte-code.** pro
189b0 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f  gram using one o
189c0 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
189d0 2e 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  . .**.** The fir
189e0 73 74 20 61 72 67 75 6d 65 6e 74 20 22 64 62 22  st argument "db"
189f0 20 69 73 20 61 6e 20 5b 64 61 74 61 62 61 73 65   is an [database
18a00 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 0a 2a 2a   connection] .**
18a10 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61   obtained from a
18a20 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 5b   prior call to [
18a30 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
18a40 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
18a50 32 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  2()].** or [sqli
18a60 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 0a  te3_open16()]. .
18a70 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72  ** The second ar
18a80 67 75 6d 65 6e 74 20 22 7a 53 71 6c 22 20 69 73  gument "zSql" is
18a90 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74   the statement t
18aa0 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65  o be compiled, e
18ab0 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69 74  ncoded.** as eit
18ac0 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46  her UTF-8 or UTF
18ad0 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69 74 65  -16.  The sqlite
18ae0 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e 64 20  3_prepare() and 
18af0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
18b00 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  v2().** interfac
18b10 65 73 20 75 73 65 73 20 55 54 46 2d 38 20 61 6e  es uses UTF-8 an
18b20 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
18b30 65 31 36 28 29 20 61 6e 64 20 73 71 6c 69 74 65  e16() and sqlite
18b40 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
18b50 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 36 2e 20  .** use UTF-16. 
18b60 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 49 66 20 74  {END}.**.** If t
18b70 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e  he nByte argumen
18b80 74 20 69 73 20 6c 65 73 73 0a 2a 2a 20 74 68 61  t is less.** tha
18b90 6e 20 7a 65 72 6f 2c 20 74 68 65 6e 20 7a 53 71  n zero, then zSq
18ba0 6c 20 69 73 20 72 65 61 64 20 75 70 20 74 6f 20  l is read up to 
18bb0 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74  the first zero t
18bc0 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66  erminator..** If
18bd0 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65   nByte is non-ne
18be0 67 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20  gative, then it 
18bf0 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e  is the maximum n
18c00 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 62 79 74  umber of .** byt
18c10 65 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71  es read from zSq
18c20 6c 2e 20 20 57 68 65 6e 20 6e 42 79 74 65 20 69  l.  When nByte i
18c30 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20  s non-negative, 
18c40 74 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69  the.** zSql stri
18c50 6e 67 20 65 6e 64 73 20 61 74 20 65 69 74 68 65  ng ends at eithe
18c60 72 20 74 68 65 20 66 69 72 73 74 20 27 5c 30 30  r the first '\00
18c70 30 27 20 6f 72 20 27 5c 75 30 30 30 30 27 20 63  0' or '\u0000' c
18c80 68 61 72 61 63 74 65 72 20 6f 72 20 0a 2a 2a 20  haracter or .** 
18c90 75 6e 74 69 6c 20 74 68 65 20 6e 42 79 74 65 2d  until the nByte-
18ca0 74 68 20 62 79 74 65 2c 20 77 68 69 63 68 65 76  th byte, whichev
18cb0 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 20  er comes first. 
18cc0 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 2a 70 7a 54  {END}.**.** *pzT
18cd0 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70  ail is made to p
18ce0 6f 69 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73  oint to the firs
18cf0 74 20 62 79 74 65 20 70 61 73 74 20 74 68 65 20  t byte past the 
18d00 65 6e 64 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69  end of the.** fi
18d10 72 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  rst SQL statemen
18d20 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73  t in zSql.  Thes
18d30 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 20  e routines only 
18d40 63 6f 6d 70 69 6c 65 73 20 74 68 65 20 66 69 72  compiles the fir
18d50 73 74 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  st.** statement 
18d60 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54  in zSql, so *pzT
18d70 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f 69 6e  ail is left poin
18d80 74 69 6e 67 20 74 6f 20 77 68 61 74 20 72 65 6d  ting to what rem
18d90 61 69 6e 73 0a 2a 2a 20 75 6e 63 6f 6d 70 69 6c  ains.** uncompil
18da0 65 64 2e 0a 2a 2a 0a 2a 2a 20 2a 70 70 53 74 6d  ed..**.** *ppStm
18db0 74 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69  t is left pointi
18dc0 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64  ng to a compiled
18dd0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
18de0 6d 65 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 62  ment] that can b
18df0 65 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73  e.** executed us
18e00 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ing [sqlite3_ste
18e10 70 28 29 5d 2e 20 20 4f 72 20 69 66 20 74 68 65  p()].  Or if the
18e20 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c 20  re is an error, 
18e30 2a 70 70 53 74 6d 74 20 69 73 0a 2a 2a 20 73 65  *ppStmt is.** se
18e40 74 20 74 6f 20 4e 55 4c 4c 2e 20 20 49 66 20 74  t to NULL.  If t
18e50 68 65 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f  he input text co
18e60 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69  ntains no SQL (i
18e70 66 20 74 68 65 20 69 6e 70 75 74 0a 2a 2a 20 69  f the input.** i
18e80 73 20 61 6e 64 20 65 6d 70 74 79 20 73 74 72 69  s and empty stri
18e90 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29  ng or a comment)
18ea0 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 69 73   then *ppStmt is
18eb0 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a   set to NULL..**
18ec0 20 7b 55 31 33 30 31 38 7d 20 54 68 65 20 63 61   {U13018} The ca
18ed0 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65 20  lling procedure 
18ee0 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
18ef0 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65 0a  or deleting the.
18f00 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20  ** compiled SQL 
18f10 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 75 73 69  statement.** usi
18f20 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ng [sqlite3_fina
18f30 6c 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74  lize()] after it
18f40 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69   has finished wi
18f50 74 68 20 69 74 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20  th it..**.** On 
18f60 73 75 63 63 65 73 73 2c 20 5b 53 51 4c 49 54 45  success, [SQLITE
18f70 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64  _OK] is returned
18f80 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20  .  Otherwise an 
18f90 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  .** [error code]
18fa0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
18fb0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
18fc0 70 72 65 70 61 72 65 5f 76 32 28 29 20 61 6e 64  prepare_v2() and
18fd0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
18fe0 31 36 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63  16_v2() interfac
18ff0 65 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d  es are.** recomm
19000 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65  ended for all ne
19010 77 20 70 72 6f 67 72 61 6d 73 2e 20 54 68 65 20  w programs. The 
19020 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72 66  two older interf
19030 61 63 65 73 20 61 72 65 20 72 65 74 61 69 6e 65  aces are retaine
19040 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61 72  d.** for backwar
19050 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
19060 2c 20 62 75 74 20 74 68 65 69 72 20 75 73 65 20  , but their use 
19070 69 73 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a  is discouraged..
19080 2a 2a 20 49 6e 20 74 68 65 20 22 76 32 22 20 69  ** In the "v2" i
19090 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 70  nterfaces, the p
190a0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
190b0 74 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74  t.** that is ret
190c0 75 72 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69  urned (the [sqli
190d0 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74  te3_stmt] object
190e0 29 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70  ) contains a cop
190f0 79 20 6f 66 20 74 68 65 20 0a 2a 2a 20 6f 72 69  y of the .** ori
19100 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20  ginal SQL text. 
19110 7b 45 4e 44 7d 20 54 68 69 73 20 63 61 75 73 65  {END} This cause
19120 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  s the [sqlite3_s
19130 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65  tep()] interface
19140 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20 61 20   to.** behave a 
19150 64 69 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74  differently in t
19160 77 6f 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c  wo ways:.**.** <
19170 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 49  ol>.** <li>.** I
19180 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73  f the database s
19190 63 68 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 69  chema changes, i
191a0 6e 73 74 65 61 64 20 6f 66 20 72 65 74 75 72 6e  nstead of return
191b0 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 45  ing [SQLITE_SCHE
191c0 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77  MA] as it.** alw
191d0 61 79 73 20 75 73 65 64 20 74 6f 20 64 6f 2c 20  ays used to do, 
191e0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
191f0 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61   will automatica
19200 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 68  lly recompile th
19210 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65  e SQL.** stateme
19220 6e 74 20 61 6e 64 20 74 72 79 20 74 6f 20 72 75  nt and try to ru
19230 6e 20 69 74 20 61 67 61 69 6e 2e 20 20 49 66 20  n it again.  If 
19240 74 68 65 20 73 63 68 65 6d 61 20 68 61 73 20 63  the schema has c
19250 68 61 6e 67 65 64 20 69 6e 0a 2a 2a 20 61 20 77  hanged in.** a w
19260 61 79 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68  ay that makes th
19270 65 20 73 74 61 74 65 6d 65 6e 74 20 6e 6f 20 6c  e statement no l
19280 6f 6e 67 65 72 20 76 61 6c 69 64 2c 20 5b 73 71  onger valid, [sq
19290 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69  lite3_step()] wi
192a0 6c 6c 20 73 74 69 6c 6c 0a 2a 2a 20 72 65 74 75  ll still.** retu
192b0 72 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d  rn [SQLITE_SCHEM
192c0 41 5d 2e 20 20 42 75 74 20 75 6e 6c 69 6b 65 20  A].  But unlike 
192d0 74 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76  the legacy behav
192e0 69 6f 72 2c 20 0a 2a 2a 20 5b 53 51 4c 49 54 45  ior, .** [SQLITE
192f0 5f 53 43 48 45 4d 41 5d 20 69 73 20 6e 6f 77 20  _SCHEMA] is now 
19300 61 20 66 61 74 61 6c 20 65 72 72 6f 72 2e 20 20  a fatal error.  
19310 43 61 6c 6c 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  Calling.** [sqli
19320 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
19330 5d 20 61 67 61 69 6e 20 77 69 6c 6c 20 6e 6f 74  ] again will not
19340 20 6d 61 6b 65 20 74 68 65 0a 2a 2a 20 65 72 72   make the.** err
19350 6f 72 20 67 6f 20 61 77 61 79 2e 20 20 4e 6f 74  or go away.  Not
19360 65 3a 20 75 73 65 20 5b 73 71 6c 69 74 65 33 5f  e: use [sqlite3_
19370 65 72 72 6d 73 67 28 29 5d 20 74 6f 20 66 69 6e  errmsg()] to fin
19380 64 20 74 68 65 20 74 65 78 74 0a 2a 2a 20 6f 66  d the text.** of
19390 20 74 68 65 20 70 61 72 73 69 6e 67 20 65 72 72   the parsing err
193a0 6f 72 20 74 68 61 74 20 72 65 73 75 6c 74 73 20  or that results 
193b0 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 53 43  in an [SQLITE_SC
193c0 48 45 4d 41 5d 20 72 65 74 75 72 6e 2e 20 7b 45  HEMA] return. {E
193d0 4e 44 7d 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a  ND}.** </li>.**.
193e0 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 57 68 65 6e 20  ** <li>.** When 
193f0 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c  an error occurs,
19400 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74   .** [sqlite3_st
19410 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  ep()] will retur
19420 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74  n one of the det
19430 61 69 6c 65 64 20 0a 2a 2a 20 5b 65 72 72 6f 72  ailed .** [error
19440 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 65   codes] or [exte
19450 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73  nded error codes
19460 5d 2e 20 0a 2a 2a 20 54 68 65 20 6c 65 67 61 63  ]. .** The legac
19470 79 20 62 65 68 61 76 69 6f 72 20 77 61 73 20 74  y behavior was t
19480 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  hat [sqlite3_ste
19490 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20  p()] would only 
194a0 72 65 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63  return a generic
194b0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  .** [SQLITE_ERRO
194c0 52 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 20 61  R] result code a
194d0 6e 64 20 79 6f 75 20 77 6f 75 6c 64 20 68 61 76  nd you would hav
194e0 65 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f  e to make a seco
194f0 6e 64 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73  nd call to.** [s
19500 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
19510 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64  in order to find
19520 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20   the underlying 
19530 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f  cause of the pro
19540 62 6c 65 6d 2e 0a 2a 2a 20 57 69 74 68 20 74 68  blem..** With th
19550 65 20 22 76 32 22 20 70 72 65 70 61 72 65 20 69  e "v2" prepare i
19560 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 75  nterfaces, the u
19570 6e 64 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e  nderlying reason
19580 20 66 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69   for the error i
19590 73 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6d  s.** returned im
195a0 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f  mediately..** </
195b0 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a  li>.** </ol>.**.
195c0 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
195d0 2a 0a 2a 2a 20 7b 46 31 33 30 31 31 7d 20 54 68  *.** {F13011} Th
195e0 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  e [sqlite3_prepa
195f0 72 65 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d  re(db,zSql,...)]
19600 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20   and.**         
19610 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
19620 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e  e_v2(db,zSql,...
19630 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 69 6e  )] interfaces in
19640 74 65 72 70 72 65 74 20 74 68 65 0a 2a 2a 20 20  terpret the.**  
19650 20 20 20 20 20 20 20 20 74 65 78 74 20 69 6e 20          text in 
19660 74 68 65 69 72 20 7a 53 71 6c 20 70 61 72 61 6d  their zSql param
19670 65 74 65 72 20 61 73 20 55 54 46 2d 38 2e 0a 2a  eter as UTF-8..*
19680 2a 0a 2a 2a 20 7b 46 31 33 30 31 32 7d 20 54 68  *.** {F13012} Th
19690 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  e [sqlite3_prepa
196a0 72 65 31 36 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e  re16(db,zSql,...
196b0 29 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20  )] and.**       
196c0 20 20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70     [sqlite3_prep
196d0 61 72 65 31 36 5f 76 32 28 64 62 2c 7a 53 71 6c  are16_v2(db,zSql
196e0 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65  ,...)] interface
196f0 73 20 69 6e 74 65 72 70 72 65 74 20 74 68 65 0a  s interpret the.
19700 2a 2a 20 20 20 20 20 20 20 20 20 20 74 65 78 74  **          text
19710 20 69 6e 20 74 68 65 69 72 20 7a 53 71 6c 20 70   in their zSql p
19720 61 72 61 6d 65 74 65 72 20 61 73 20 55 54 46 2d  arameter as UTF-
19730 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  16 in the native
19740 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a   byte order..**.
19750 2a 2a 20 7b 46 31 33 30 31 33 7d 20 49 66 20 74  ** {F13013} If t
19760 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e  he nByte argumen
19770 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72  t to [sqlite3_pr
19780 65 70 61 72 65 5f 76 32 28 64 62 2c 7a 53 71 6c  epare_v2(db,zSql
19790 2c 6e 42 79 74 65 2c 2e 2e 2e 29 5d 0a 2a 2a 20  ,nByte,...)].** 
197a0 20 20 20 20 20 20 20 20 20 61 6e 64 20 69 74 73           and its
197b0 20 76 61 72 69 61 6e 74 73 20 69 73 20 6c 65 73   variants is les
197c0 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65  s than zero, the
197d0 6e 20 53 51 4c 20 74 65 78 74 20 69 73 0a 2a 2a  n SQL text is.**
197e0 20 20 20 20 20 20 20 20 20 20 72 65 61 64 20 66            read f
197f0 72 6f 6d 20 7a 53 71 6c 20 69 73 20 72 65 61 64  rom zSql is read
19800 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74   up to the first
19810 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
19820 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 30 31 34 7d  ..**.** {F13014}
19830 20 49 66 20 74 68 65 20 6e 42 79 74 65 20 61 72   If the nByte ar
19840 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74  gument to [sqlit
19850 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 64 62  e3_prepare_v2(db
19860 2c 7a 53 71 6c 2c 6e 42 79 74 65 2c 2e 2e 2e 29  ,zSql,nByte,...)
19870 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e  ].**          an
19880 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 69  d its variants i
19890 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20  s non-negative, 
198a0 74 68 65 6e 20 6e 42 79 74 65 73 20 62 79 74 65  then nBytes byte
198b0 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53 51  s.**          SQ
198c0 4c 20 74 65 78 74 20 69 73 20 72 65 61 64 20 66  L text is read f
198d0 72 6f 6d 20 7a 53 71 6c 2e 0a 2a 2a 0a 2a 2a 20  rom zSql..**.** 
198e0 7b 46 31 33 30 31 35 7d 20 49 6e 20 5b 73 71 6c  {F13015} In [sql
198f0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
19900 64 62 2c 7a 53 71 6c 2c 4e 2c 50 2c 70 7a 54 61  db,zSql,N,P,pzTa
19910 69 6c 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72  il)] and its var
19920 69 61 6e 74 73 0a 2a 2a 20 20 20 20 20 20 20 20  iants.**        
19930 20 20 69 66 20 74 68 65 20 7a 53 71 6c 20 69 6e    if the zSql in
19940 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e  put text contain
19950 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20  s more than one 
19960 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  SQL statement.**
19970 20 20 20 20 20 20 20 20 20 20 61 6e 64 20 70 7a            and pz
19980 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  Tail is not NULL
19990 2c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69  , then *pzTail i
199a0 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20  s made to point 
199b0 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  to the.**       
199c0 20 20 20 66 69 72 73 74 20 62 79 74 65 20 70 61     first byte pa
199d0 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68  st the end of th
199e0 65 20 66 69 72 73 74 20 53 51 4c 20 73 74 61 74  e first SQL stat
199f0 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 0a 2a  ement in zSql..*
19a00 2a 20 20 20 20 20 20 20 20 20 20 3c 74 6f 64 6f  *          <todo
19a10 3e 57 68 61 74 20 64 6f 65 73 20 2a 70 7a 54 61  >What does *pzTa
19a20 69 6c 20 70 6f 69 6e 74 20 74 6f 20 69 66 20 74  il point to if t
19a30 68 65 72 65 20 69 73 20 6f 6e 65 20 73 74 61 74  here is one stat
19a40 65 6d 65 6e 74 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a  ement?</todo>.**
19a50 0a 2a 2a 20 7b 46 31 33 30 31 36 7d 20 41 20 73  .** {F13016} A s
19a60 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74  uccessful call t
19a70 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  o [sqlite3_prepa
19a80 72 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 4e 2c  re_v2(db,zSql,N,
19a90 70 70 53 74 6d 74 2c 2e 2e 2e 29 5d 0a 2a 2a 20  ppStmt,...)].** 
19aa0 20 20 20 20 20 20 20 20 20 6f 72 20 6f 6e 65 20           or one 
19ab0 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74 73 20  of its variants 
19ac0 77 72 69 74 65 73 20 69 6e 74 6f 20 2a 70 70 53  writes into *ppS
19ad0 74 6d 74 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  tmt a pointer to
19ae0 20 61 20 6e 65 77 0a 2a 2a 20 20 20 20 20 20 20   a new.**       
19af0 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61     [prepared sta
19b00 74 65 6d 65 6e 74 5d 20 6f 72 20 61 20 70 6f 69  tement] or a poi
19b10 6e 74 65 72 20 74 6f 20 4e 55 4c 4c 0a 2a 2a 20  nter to NULL.** 
19b20 20 20 20 20 20 20 20 20 20 69 66 20 7a 53 71 6c           if zSql
19b30 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 74 68 69 6e   contains nothin
19b40 67 20 6f 74 68 65 72 20 74 68 61 6e 20 77 68 69  g other than whi
19b50 74 65 73 70 61 63 65 20 6f 72 20 63 6f 6d 6d 65  tespace or comme
19b60 6e 74 73 2e 20 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  nts. .**.** {F13
19b70 30 31 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  019} The [sqlite
19b80 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
19b90 69 6e 74 65 72 66 61 63 65 20 61 6e 64 20 69 74  interface and it
19ba0 73 20 76 61 72 69 61 6e 74 73 20 72 65 74 75 72  s variants retur
19bb0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53  n.**          [S
19bc0 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 61 6e 20  QLITE_OK] or an 
19bd0 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72  appropriate [err
19be0 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 20 66 61  or code] upon fa
19bf0 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  ilure..**.** {F1
19c00 33 30 32 31 7d 20 42 65 66 6f 72 65 20 5b 73 71  3021} Before [sq
19c10 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 64 62  lite3_prepare(db
19c20 2c 7a 53 71 6c 2c 6e 42 79 74 65 2c 70 70 53 74  ,zSql,nByte,ppSt
19c30 6d 74 2c 70 7a 54 61 69 6c 29 5d 20 6f 72 20 69  mt,pzTail)] or i
19c40 74 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76  ts.**          v
19c50 61 72 69 61 6e 74 73 20 72 65 74 75 72 6e 73 20  ariants returns 
19c60 61 6e 20 65 72 72 6f 72 20 28 61 6e 79 20 76 61  an error (any va
19c70 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  lue other than [
19c80 53 51 4c 49 54 45 5f 4f 4b 5d 29 0a 2a 2a 20 20  SQLITE_OK]).**  
19c90 20 20 20 20 20 20 20 20 69 74 20 66 69 72 73 74          it first
19ca0 20 73 65 74 73 20 2a 70 70 53 74 6d 74 20 74 6f   sets *ppStmt to
19cb0 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71   NULL..*/.int sq
19cc0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 0a 20  lite3_prepare(. 
19cd0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
19ce0 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
19cf0 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
19d00 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71   const char *zSq
19d10 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
19d20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38  statement, UTF-8
19d30 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
19d40 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
19d50 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
19d60 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
19d70 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
19d80 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
19d90 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
19da0 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
19db0 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
19dc0 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
19dd0 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
19de0 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
19df0 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74  f zSql */.);.int
19e00 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
19e10 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v2(.  sqlite3 *
19e20 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
19e30 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
19e40 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
19e50 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  r *zSql,       /
19e60 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
19e70 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a   UTF-8 encoded *
19e80 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
19e90 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
19ea0 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
19eb0 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
19ec0 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
19ed0 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
19ee0 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
19ef0 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
19f00 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20   char **pzTail  
19f10 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
19f20 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
19f30 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
19f40 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  );.int sqlite3_p
19f50 72 65 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69  repare16(.  sqli
19f60 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
19f70 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
19f80 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
19f90 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20  t void *zSql,   
19fa0 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
19fb0 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63  ment, UTF-16 enc
19fc0 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
19fd0 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
19fe0 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
19ff0 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
1a000 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
1a010 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
1a020 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
1a030 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
1a040 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a   const void **pz
1a050 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
1a060 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
1a070 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
1a080 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  ql */.);.int sql
1a090 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
1a0a0 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  2(.  sqlite3 *db
1a0b0 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
1a0c0 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
1a0d0 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
1a0e0 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
1a0f0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
1a100 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f  TF-16 encoded */
1a110 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
1a120 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
1a130 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
1a140 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
1a150 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
1a160 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
1a170 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
1a180 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
1a190 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20  void **pzTail   
1a1a0 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
1a1b0 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
1a1c0 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
1a1d0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 52 45 46  ;../*.** CAPIREF
1a1e0 3a 20 52 65 74 72 69 65 76 69 6e 67 20 53 74 61  : Retrieving Sta
1a1f0 74 65 6d 65 6e 74 20 53 51 4c 20 7b 46 31 33 31  tement SQL {F131
1a200 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  00}.**.** This i
1a210 6e 74 65 72 65 66 61 63 65 20 63 61 6e 20 62 65  ntereface can be
1a220 20 75 73 65 64 20 74 6f 20 72 65 74 72 69 65 76   used to retriev
1a230 65 20 61 20 73 61 76 65 64 20 63 6f 70 79 20 6f  e a saved copy o
1a240 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a  f the original.*
1a250 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65 64 20  * SQL text used 
1a260 74 6f 20 63 72 65 61 74 65 20 61 20 5b 70 72 65  to create a [pre
1a270 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
1a280 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
1a290 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 31 30  TS:.**.** {F1310
1a2a0 31 7d 20 49 66 20 74 68 65 20 5b 70 72 65 70 61  1} If the [prepa
1a2b0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 70  red statement] p
1a2c0 61 73 73 65 64 20 61 73 20 0a 2a 2a 20 20 20 20  assed as .**    
1a2d0 20 20 20 20 20 20 74 68 65 20 61 6e 20 61 72 67        the an arg
1a2e0 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65  ument to [sqlite
1a2f0 33 5f 73 71 6c 28 29 5d 20 77 61 73 20 63 6f 6d  3_sql()] was com
1a300 70 69 6c 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  piled.**        
1a310 20 20 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67    compiled using
1a320 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33   either [sqlite3
1a330 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
1a340 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  r.**          [s
1a350 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
1a360 5f 76 32 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20  _v2()],.**      
1a370 20 20 20 20 74 68 65 6e 20 5b 73 71 6c 69 74 65      then [sqlite
1a380 33 5f 73 71 6c 28 29 5d 20 66 75 6e 63 74 69 6f  3_sql()] functio
1a390 6e 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  n returns a poin
1a3a0 74 65 72 20 74 6f 20 61 0a 2a 2a 20 20 20 20 20  ter to a.**     
1a3b0 20 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e       zero-termin
1a3c0 61 74 65 64 20 73 74 72 69 6e 67 20 63 6f 6e 74  ated string cont
1a3d0 61 69 6e 69 6e 67 20 61 20 55 54 46 2d 38 20 72  aining a UTF-8 r
1a3e0 65 6e 64 65 72 69 6e 67 0a 2a 2a 20 20 20 20 20  endering.**     
1a3f0 20 20 20 20 20 6f 66 20 74 68 65 20 6f 72 69 67       of the orig
1a400 69 6e 61 6c 20 53 51 4c 20 73 74 61 74 65 6d 65  inal SQL stateme
1a410 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 31 30  nt..**.** {F1310
1a420 32 7d 20 49 66 20 74 68 65 20 5b 70 72 65 70 61  2} If the [prepa
1a430 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 70  red statement] p
1a440 61 73 73 65 64 20 61 73 20 0a 2a 2a 20 20 20 20  assed as .**    
1a450 20 20 20 20 20 20 74 68 65 20 61 6e 20 61 72 67        the an arg
1a460 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65  ument to [sqlite
1a470 33 5f 73 71 6c 28 29 5d 20 77 61 73 20 63 6f 6d  3_sql()] was com
1a480 70 69 6c 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  piled.**        
1a490 20 20 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67    compiled using
1a4a0 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33   either [sqlite3
1a4b0 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 0a 2a  _prepare()] or.*
1a4c0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
1a4d0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
1a4e0 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  ,.**          th
1a4f0 65 6e 20 5b 73 71 6c 69 74 65 33 5f 73 71 6c 28  en [sqlite3_sql(
1a500 29 5d 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  )] function retu
1a510 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
1a520 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 31 30  er..**.** {F1310
1a530 33 7d 20 54 68 65 20 73 74 72 69 6e 67 20 72 65  3} The string re
1a540 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
1a550 65 33 5f 73 71 6c 28 53 29 5d 20 69 73 20 76 61  e3_sql(S)] is va
1a560 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 0a 2a 2a  lid until the.**
1a570 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61            [prepa
1a580 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
1a590 20 69 73 20 64 65 6c 65 74 65 64 20 75 73 69 6e   is deleted usin
1a5a0 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  g [sqlite3_final
1a5b0 69 7a 65 28 53 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73  ize(S)]..*/.cons
1a5c0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
1a5d0 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  sql(sqlite3_stmt
1a5e0 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
1a5f0 20 43 41 50 49 33 52 45 46 3a 20 20 44 79 6e 61   CAPI3REF:  Dyna
1a600 6d 69 63 61 6c 6c 79 20 54 79 70 65 64 20 56 61  mically Typed Va
1a610 6c 75 65 20 4f 62 6a 65 63 74 20 20 7b 46 31 35  lue Object  {F15
1a620 30 30 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  000}.** KEYWORDS
1a630 3a 20 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  : {protected sql
1a640 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70  ite3_value} {unp
1a650 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
1a660 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51  _value}.**.** SQ
1a670 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73 71  Lite uses the sq
1a680 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
1a690 63 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20  ct to represent 
1a6a0 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68  all values.** th
1a6b0 61 74 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64  at can be stored
1a6c0 20 69 6e 20 61 20 64 61 74 61 62 61 73 65 20 74   in a database t
1a6d0 61 62 6c 65 2e 0a 2a 2a 20 53 51 4c 69 74 65 20  able..** SQLite 
1a6e0 75 73 65 73 20 64 79 6e 61 6d 69 63 20 74 79 70  uses dynamic typ
1a6f0 69 6e 67 20 66 6f 72 20 74 68 65 20 76 61 6c 75  ing for the valu
1a700 65 73 20 69 74 20 73 74 6f 72 65 73 2e 20 20 0a  es it stores.  .
1a710 2a 2a 20 56 61 6c 75 65 73 20 73 74 6f 72 65 64  ** Values stored
1a720 20 69 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75   in sqlite3_valu
1a730 65 20 6f 62 6a 65 63 74 73 20 63 61 6e 20 62 65  e objects can be
1a740 0a 2a 2a 20 62 65 20 69 6e 74 65 67 65 72 73 2c  .** be integers,
1a750 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
1a760 76 61 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 2c  values, strings,
1a770 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e   BLOBs, or NULL.
1a780 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65  .**.** An sqlite
1a790 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d  3_value object m
1a7a0 61 79 20 62 65 20 65 69 74 68 65 72 20 22 70 72  ay be either "pr
1a7b0 6f 74 65 63 74 65 64 22 20 6f 72 20 22 75 6e 70  otected" or "unp
1a7c0 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f  rotected"..** So
1a7d0 6d 65 20 69 6e 74 65 72 66 61 63 65 73 20 72 65  me interfaces re
1a7e0 71 75 69 72 65 20 61 20 70 72 6f 74 65 63 74 65  quire a protecte
1a7f0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e  d sqlite3_value.
1a800 20 20 4f 74 68 65 72 20 69 6e 74 65 72 66 61 63    Other interfac
1a810 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70  es.** will accep
1a820 74 20 65 69 74 68 65 72 20 61 20 70 72 6f 74 65  t either a prote
1a830 63 74 65 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f  cted or an unpro
1a840 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
1a850 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69  alue..** Every i
1a860 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61 63  nterface that ac
1a870 63 65 70 74 73 20 73 71 6c 69 74 65 33 5f 76 61  cepts sqlite3_va
1a880 6c 75 65 20 61 72 67 75 6d 65 6e 74 73 20 73 70  lue arguments sp
1a890 65 63 69 66 69 65 73 20 0a 2a 2a 20 77 68 65 74  ecifies .** whet
1a8a0 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 20 72 65  her or not it re
1a8b0 71 75 69 72 65 73 20 61 20 70 72 6f 74 65 63 74  quires a protect
1a8c0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
1a8d0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d  ..**.** The term
1a8e0 73 20 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e  s "protected" an
1a8f0 64 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20  d "unprotected" 
1a900 72 65 66 65 72 20 74 6f 20 77 68 65 74 68 65 72  refer to whether
1a910 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74   or not.** a mut
1a920 65 78 20 69 73 20 68 65 6c 64 2e 20 20 41 20 69  ex is held.  A i
1a930 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 73  nternal mutex is
1a940 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f 74   held for a prot
1a950 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
1a960 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 75  _value object bu
1a970 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 65  t no mutex is he
1a980 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74  ld for an unprot
1a990 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
1a9a0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20  _value object.  
1a9b0 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
1a9c0 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e 67  piled to be sing
1a9d0 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 28  le-threaded.** (
1a9e0 77 69 74 68 20 53 51 4c 49 54 45 5f 54 48 52 45  with SQLITE_THRE
1a9f0 41 44 53 41 46 45 3d 30 20 61 6e 64 20 77 69 74  ADSAFE=0 and wit
1aa00 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61  h [sqlite3_threa
1aa10 64 73 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69  dsafe()] returni
1aa20 6e 67 20 30 29 0a 2a 2a 20 74 68 65 6e 20 74 68  ng 0).** then th
1aa30 65 72 65 20 69 73 20 6e 6f 20 64 69 73 74 69 6e  ere is no distin
1aa40 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a  ction between.**
1aa50 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75   protected and u
1aa60 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
1aa70 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
1aa80 20 61 6e 64 20 74 68 65 79 20 63 61 6e 20 62 65   and they can be
1aa90 0a 2a 2a 20 75 73 65 64 20 69 6e 74 65 72 63 68  .** used interch
1aaa0 61 6e 67 61 62 6c 65 2e 20 20 48 6f 77 65 76 65  angable.  Howeve
1aab0 72 2c 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63  r, for maximum c
1aac0 6f 64 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20  ode portability 
1aad0 69 74 0a 2a 2a 20 69 73 20 72 65 63 6f 6d 6d 65  it.** is recomme
1aae0 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63  nded that applic
1aaf0 61 74 69 6f 6e 73 20 6d 61 6b 65 20 74 68 65 20  ations make the 
1ab00 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77  distinction betw
1ab10 65 65 6e 0a 2a 2a 20 62 65 74 77 65 65 6e 20 70  een.** between p
1ab20 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70  rotected and unp
1ab30 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
1ab40 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 65  _value objects e
1ab50 76 65 6e 20 69 66 0a 2a 2a 20 74 68 65 79 20 61  ven if.** they a
1ab60 72 65 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64  re single thread
1ab70 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ed..**.** The sq
1ab80 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
1ab90 63 74 73 20 74 68 61 74 20 61 72 65 20 70 61 73  cts that are pas
1aba0 73 65 64 20 61 73 20 70 61 72 61 6d 65 74 65 72  sed as parameter
1abb0 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d  s into the.** im
1abc0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
1abd0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
1abe0 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
1abf0 73 20 61 72 65 20 70 72 6f 74 65 63 74 65 64 2e  s are protected.
1ac00 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
1ac10 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72 65 74  value object ret
1ac20 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c  urned by.** [sql
1ac30 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
1ac40 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74 65 63  e()] is unprotec
1ac50 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63  ted..** Unprotec
1ac60 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
1ac70 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e  e objects may on
1ac80 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68 0a  ly be used with.
1ac90 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  ** [sqlite3_resu
1aca0 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20  lt_value()] and 
1acb0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61  [sqlite3_bind_va
1acc0 6c 75 65 28 29 5d 2e 20 20 41 6c 6c 20 6f 74 68  lue()].  All oth
1acd0 65 72 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  er.** interfaces
1ace0 20 74 68 61 74 20 75 73 65 20 73 71 6c 69 74 65   that use sqlite
1acf0 33 5f 76 61 6c 75 65 20 72 65 71 75 69 72 65 20  3_value require 
1ad00 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
1ad10 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e  3_value objects.
1ad20 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
1ad30 63 74 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76  ct Mem sqlite3_v
1ad40 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  alue;../*.** CAP
1ad50 49 33 52 45 46 3a 20 20 53 51 4c 20 46 75 6e 63  I3REF:  SQL Func
1ad60 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a  tion Context Obj
1ad70 65 63 74 20 7b 46 31 36 30 30 31 7d 0a 2a 2a 0a  ect {F16001}.**.
1ad80 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78 74 20 69  ** The context i
1ad90 6e 20 77 68 69 63 68 20 61 6e 20 53 51 4c 20 66  n which an SQL f
1ada0 75 6e 63 74 69 6f 6e 20 65 78 65 63 75 74 65 73  unction executes
1adb0 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61 6e   is stored in an
1adc0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  .** sqlite3_cont
1add0 65 78 74 20 6f 62 6a 65 63 74 2e 20 20 41 20 70  ext object.  A p
1ade0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c  ointer to an sql
1adf0 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 20  ite3_context.** 
1ae00 6f 62 6a 65 63 74 20 69 73 20 61 6c 77 61 79 73  object is always
1ae10 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
1ae20 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   to application-
1ae30 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
1ae40 74 69 6f 6e 73 2e 0a 2a 2f 0a 74 79 70 65 64 65  tions..*/.typede
1ae50 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
1ae60 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33  _context sqlite3
1ae70 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a  _context;../*.**
1ae80 20 43 41 50 49 33 52 45 46 3a 20 20 42 69 6e 64   CAPI3REF:  Bind
1ae90 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72  ing Values To Pr
1aea0 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
1aeb0 73 20 7b 46 31 33 35 30 30 7d 0a 2a 2a 0a 2a 2a  s {F13500}.**.**
1aec0 20 49 6e 20 74 68 65 20 53 51 4c 20 73 74 72 69   In the SQL stri
1aed0 6e 67 73 20 69 6e 70 75 74 20 74 6f 20 5b 73 71  ngs input to [sq
1aee0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1aef0 28 29 5d 20 61 6e 64 20 69 74 73 0a 2a 2a 20 76  ()] and its.** v
1af00 61 72 69 61 6e 74 73 2c 20 6c 69 74 65 72 61 6c  ariants, literal
1af10 73 20 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65  s may be replace
1af20 20 62 79 20 61 20 70 61 72 61 6d 65 74 65 72 20   by a parameter 
1af30 69 6e 20 6f 6e 65 0a 2a 2a 20 6f 66 20 74 68 65  in one.** of the
1af40 73 65 20 66 6f 72 6d 73 3a 0a 2a 2a 0a 2a 2a 20  se forms:.**.** 
1af50 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a  <ul>.** <li>  ?.
1af60 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a  ** <li>  ?NNN.**
1af70 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c   <li>  :VVV.** <
1af80 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69  li>  @VVV.** <li
1af90 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e  >  $VVV.** </ul>
1afa0 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 70 61  .**.** In the pa
1afb0 72 61 6d 65 74 65 72 20 66 6f 72 6d 73 20 73 68  rameter forms sh
1afc0 6f 77 6e 20 61 62 6f 76 65 20 4e 4e 4e 20 69 73  own above NNN is
1afd0 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65   an integer lite
1afe0 72 61 6c 2c 0a 2a 2a 20 56 56 56 20 61 6c 70 68  ral,.** VVV alph
1aff0 61 2d 6e 75 6d 65 72 69 63 20 70 61 72 61 6d 65  a-numeric parame
1b000 74 65 72 20 6e 61 6d 65 2e 0a 2a 2a 20 54 68 65  ter name..** The
1b010 20 76 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65   values of these
1b020 20 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73   parameters (als
1b030 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70  o called "host p
1b040 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 0a  arameter names".
1b050 2a 2a 20 6f 72 20 22 53 51 4c 20 70 61 72 61 6d  ** or "SQL param
1b060 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62  eters").** can b
1b070 65 20 73 65 74 20 75 73 69 6e 67 20 74 68 65 20  e set using the 
1b080 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
1b090 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65   routines define
1b0a0 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  d here..**.** Th
1b0b0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
1b0c0 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
1b0d0 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
1b0e0 73 20 61 6c 77 61 79 73 0a 2a 2a 20 69 73 20 61  s always.** is a
1b0f0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
1b100 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f  [sqlite3_stmt] o
1b110 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 66  bject returned f
1b120 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  rom.** [sqlite3_
1b130 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
1b140 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20 54   its variants. T
1b150 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67  he second.** arg
1b160 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64  ument is the ind
1b170 65 78 20 6f 66 20 74 68 65 20 70 61 72 61 6d 65  ex of the parame
1b180 74 65 72 20 74 6f 20 62 65 20 73 65 74 2e 20 54  ter to be set. T
1b190 68 65 0a 2a 2a 20 66 69 72 73 74 20 70 61 72 61  he.** first para
1b1a0 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64  meter has an ind
1b1b0 65 78 20 6f 66 20 31 2e 20 20 57 68 65 6e 20 74  ex of 1.  When t
1b1c0 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a  he same named.**
1b1d0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 75 73   parameter is us
1b1e0 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63  ed more than onc
1b1f0 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75  e, second and su
1b200 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75  bsequent.** occu
1b210 72 72 65 6e 63 65 73 20 68 61 76 65 20 74 68 65  rrences have the
1b220 20 73 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74   same index as t
1b230 68 65 20 66 69 72 73 74 20 6f 63 63 75 72 72 65  he first occurre
1b240 6e 63 65 2e 20 0a 2a 2a 20 54 68 65 20 69 6e 64  nce. .** The ind
1b250 65 78 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72  ex for named par
1b260 61 6d 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c  ameters can be l
1b270 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74  ooked up using t
1b280 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  he.** [sqlite3_b
1b290 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
1b2a0 6d 65 28 29 5d 20 41 50 49 20 69 66 20 64 65 73  me()] API if des
1b2b0 69 72 65 64 2e 20 20 54 68 65 20 69 6e 64 65 78  ired.  The index
1b2c0 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70  .** for "?NNN" p
1b2d0 61 72 61 6d 65 74 65 72 73 20 69 73 20 74 68 65  arameters is the
1b2e0 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a   value of NNN..*
1b2f0 2a 20 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20  * The NNN value 
1b300 6d 75 73 74 20 62 65 20 62 65 74 77 65 65 6e 20  must be between 
1b310 31 20 61 6e 64 20 74 68 65 20 63 6f 6d 70 69 6c  1 and the compil
1b320 65 2d 74 69 6d 65 0a 2a 2a 20 70 61 72 61 6d 65  e-time.** parame
1b330 74 65 72 20 53 51 4c 49 54 45 5f 4d 41 58 5f 56  ter SQLITE_MAX_V
1b340 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20 28  ARIABLE_NUMBER (
1b350 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39  default value: 9
1b360 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  99)..**.** The t
1b370 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
1b380 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69   the value to bi
1b390 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65  nd to the parame
1b3a0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68  ter..**.** In th
1b3b0 6f 73 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  ose.** routines 
1b3c0 74 68 61 74 20 68 61 76 65 20 61 20 66 6f 75 72  that have a four
1b3d0 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73  th argument, its
1b3e0 20 76 61 6c 75 65 20 69 73 20 74 68 65 20 6e 75   value is the nu
1b3f0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a  mber of bytes.**
1b400 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65   in the paramete
1b410 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a  r.  To be clear:
1b420 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 74 68   the value is th
1b430 65 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62  e number of <u>b
1b440 79 74 65 73 3c 2f 75 3e 0a 2a 2a 20 69 6e 20 74  ytes</u>.** in t
1b450 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68  he value, not th
1b460 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72  e number of char
1b470 61 63 74 65 72 73 2e 20 20 20 54 68 65 20 6e 75  acters.   The nu
1b480 6d 62 65 72 0a 2a 2a 20 6f 66 20 62 79 74 65 73  mber.** of bytes
1b490 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64   does not includ
1b4a0 65 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69  e the zero-termi
1b4b0 6e 61 74 6f 72 20 61 74 20 74 68 65 20 65 6e 64  nator at the end
1b4c0 20 6f 66 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20   of strings..** 
1b4d0 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  If the fourth pa
1b4e0 72 61 6d 65 74 65 72 20 69 73 20 6e 65 67 61 74  rameter is negat
1b4f0 69 76 65 2c 20 74 68 65 20 6c 65 6e 67 74 68 20  ive, the length 
1b500 6f 66 20 74 68 65 20 73 74 72 69 6e 67 20 69 73  of the string is
1b510 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  .** number of by
1b520 74 65 73 20 75 70 20 74 6f 20 74 68 65 20 66 69  tes up to the fi
1b530 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  rst zero termina
1b540 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  tor..**.** The f
1b550 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f  ifth argument to
1b560 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c   sqlite3_bind_bl
1b570 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 62 69  ob(), sqlite3_bi
1b580 6e 64 5f 74 65 78 74 28 29 2c 20 61 6e 64 0a 2a  nd_text(), and.*
1b590 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  * sqlite3_bind_t
1b5a0 65 78 74 31 36 28 29 20 69 73 20 61 20 64 65 73  ext16() is a des
1b5b0 74 72 75 63 74 6f 72 20 75 73 65 64 20 74 6f 20  tructor used to 
1b5c0 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42  dispose of the B
1b5d0 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67  LOB or.** string
1b5e0 20 61 66 74 65 72 20 53 51 4c 69 74 65 20 68 61   after SQLite ha
1b5f0 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20  s finished with 
1b600 69 74 2e 20 49 66 20 74 68 65 20 66 69 66 74 68  it. If the fifth
1b610 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20   argument is.** 
1b620 74 68 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75  the special valu
1b630 65 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43  e [SQLITE_STATIC
1b640 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 61  ], then SQLite a
1b650 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a  ssumes that the.
1b660 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  ** information i
1b670 73 20 69 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d  s in static, unm
1b680 61 6e 61 67 65 64 20 73 70 61 63 65 20 61 6e 64  anaged space and
1b690 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
1b6a0 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20 49  o be freed..** I
1b6b0 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75  f the fifth argu
1b6c0 6d 65 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c  ment has the val
1b6d0 75 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53  ue [SQLITE_TRANS
1b6e0 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53  IENT], then.** S
1b6f0 51 4c 69 74 65 20 6d 61 6b 65 73 20 69 74 73 20  QLite makes its 
1b700 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79  own private copy
1b710 20 6f 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d   of the data imm
1b720 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65  ediately, before
1b730 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f  .** the sqlite3_
1b740 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
1b750 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
1b760 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  The sqlite3_bind
1b770 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74  _zeroblob() rout
1b780 69 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f 42  ine binds a BLOB
1b790 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 68 61   of length N tha
1b7a0 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 77  t.** is filled w
1b7b0 69 74 68 20 7a 65 72 6f 73 2e 20 20 41 20 7a 65  ith zeros.  A ze
1b7c0 72 6f 62 6c 6f 62 20 75 73 65 73 20 61 20 66 69  roblob uses a fi
1b7d0 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65  xed amount of me
1b7e0 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e  mory.** (just an
1b7f0 20 69 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c 64   integer to hold
1b800 20 69 74 20 73 69 7a 65 29 20 77 68 69 6c 65 20   it size) while 
1b810 69 74 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63  it is being proc
1b820 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c  essed..** Zerobl
1b830 6f 62 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64  obs are intended
1b840 20 74 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61   to serve as pla
1b850 63 65 2d 68 6f 6c 64 65 72 73 20 66 6f 72 20 42  ce-holders for B
1b860 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f  LOBs whose.** co
1b870 6e 74 65 6e 74 20 69 73 20 6c 61 74 65 72 20 77  ntent is later w
1b880 72 69 74 74 65 6e 20 75 73 69 6e 67 20 0a 2a 2a  ritten using .**
1b890 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f   [sqlite3_blob_o
1b8a0 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 20  pen | increment 
1b8b0 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e  BLOB I/O] routin
1b8c0 65 73 2e 20 41 20 6e 65 67 61 74 69 76 65 0a 2a  es. A negative.*
1b8d0 2a 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20  * value for the 
1b8e0 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73  zeroblob results
1b8f0 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74   in a zero-lengt
1b900 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 54 68  h BLOB..**.** Th
1b910 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
1b920 28 29 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74  () routines must
1b930 20 62 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72   be called after
1b940 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
1b950 70 61 72 65 5f 76 32 28 29 5d 20 28 61 6e 64 20  pare_v2()] (and 
1b960 69 74 73 20 76 61 72 69 61 6e 74 73 29 20 6f 72  its variants) or
1b970 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
1b980 29 5d 20 61 6e 64 0a 2a 2a 20 62 65 66 6f 72 65  )] and.** before
1b990 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1b9a0 5d 2e 0a 2a 2a 20 42 69 6e 64 69 6e 67 73 20 61  ]..** Bindings a
1b9b0 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62  re not cleared b
1b9c0 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  y the [sqlite3_r
1b9d0 65 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e  eset()] routine.
1b9e0 0a 2a 2a 20 55 6e 62 6f 75 6e 64 20 70 61 72 61  .** Unbound para
1b9f0 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74 65 72  meters are inter
1ba00 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a  preted as NULL..
1ba10 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
1ba20 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c  ines return [SQL
1ba30 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65  ITE_OK] on succe
1ba40 73 73 20 6f 72 20 61 6e 20 65 72 72 6f 72 20 63  ss or an error c
1ba50 6f 64 65 20 69 66 0a 2a 2a 20 61 6e 79 74 68 69  ode if.** anythi
1ba60 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 20 20  ng goes wrong.  
1ba70 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69  [SQLITE_RANGE] i
1ba80 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68  s returned if th
1ba90 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69  e parameter.** i
1baa0 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72  ndex is out of r
1bab0 61 6e 67 65 2e 20 20 5b 53 51 4c 49 54 45 5f 4e  ange.  [SQLITE_N
1bac0 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75 72 6e 65  OMEM] is returne
1bad0 64 20 69 66 20 6d 61 6c 6c 6f 63 20 66 61 69 6c  d if malloc fail
1bae0 73 2e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49  s..** [SQLITE_MI
1baf0 53 55 53 45 5d 20 6d 69 67 68 74 20 62 65 20 72  SUSE] might be r
1bb00 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 73 65  eturned if these
1bb10 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61   routines are ca
1bb20 6c 6c 65 64 20 6f 6e 20 61 0a 2a 2a 20 76 69 72  lled on a.** vir
1bb30 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 74 68 61  tual machine tha
1bb40 74 20 69 73 20 74 68 65 20 77 72 6f 6e 67 20 73  t is the wrong s
1bb50 74 61 74 65 20 6f 72 20 77 68 69 63 68 20 68 61  tate or which ha
1bb60 73 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20 66  s already been f
1bb70 69 6e 61 6c 69 7a 65 64 2e 0a 2a 2a 20 44 65 74  inalized..** Det
1bb80 65 63 74 69 6f 6e 20 6f 66 20 6d 69 73 75 73 65  ection of misuse
1bb90 20 69 73 20 75 6e 72 65 6c 69 61 62 6c 65 2e 20   is unreliable. 
1bba0 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68   Applications sh
1bbb0 6f 75 6c 64 20 6e 6f 74 20 64 65 70 65 6e 64 0a  ould not depend.
1bbc0 2a 2a 20 6f 6e 20 53 51 4c 49 54 45 5f 4d 49 53  ** on SQLITE_MIS
1bbd0 55 53 45 20 72 65 74 75 72 6e 73 2e 20 20 53 51  USE returns.  SQ
1bbe0 4c 49 54 45 5f 4d 49 53 55 53 45 20 69 73 20 69  LITE_MISUSE is i
1bbf0 6e 74 65 6e 64 65 64 20 74 6f 20 69 6e 64 69 63  ntended to indic
1bc00 61 74 65 20 61 0a 2a 2a 20 61 20 6c 6f 67 69 63  ate a.** a logic
1bc10 20 65 72 72 6f 72 20 69 6e 20 74 68 65 20 61 70   error in the ap
1bc20 70 6c 69 63 61 74 69 6f 6e 2e 20 20 46 75 74 75  plication.  Futu
1bc30 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
1bc40 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 70  QLite might.** p
1bc50 61 6e 69 63 20 72 61 74 68 65 72 20 74 68 61 6e  anic rather than
1bc60 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d   return SQLITE_M
1bc70 49 53 55 53 45 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  ISUSE..**.** See
1bc80 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
1bc90 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63  bind_parameter_c
1bca0 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  ount()],.** [sql
1bcb0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
1bcc0 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64  ter_name()], and
1bcd0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
1bce0 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
1bcf0 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  x()]..**.** INVA
1bd00 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  RIANTS:.**.** {F
1bd10 31 33 35 30 36 7d 20 54 68 65 20 5b 73 71 6c 69  13506} The [sqli
1bd20 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 53 51  te3_prepare | SQ
1bd30 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70  L statement comp
1bd40 69 6c 65 72 5d 20 72 65 63 6f 67 6e 69 7a 65 73  iler] recognizes
1bd50 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 6b  .**          tok
1bd60 65 6e 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 73  ens of the forms
1bd70 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 24   "?", "?NNN", "$
1bd80 56 56 56 22 2c 20 22 3a 56 56 56 22 2c 20 61 6e  VVV", ":VVV", an
1bd90 64 20 22 40 56 56 56 22 0a 2a 2a 20 20 20 20 20  d "@VVV".**     
1bda0 20 20 20 20 20 61 73 20 53 51 4c 20 70 61 72 61       as SQL para
1bdb0 6d 65 74 65 72 73 2c 20 77 68 65 72 65 20 4e 4e  meters, where NN
1bdc0 4e 20 69 73 20 61 6e 79 20 73 65 71 75 65 6e 63  N is any sequenc
1bdd0 65 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  e of one or more
1bde0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 69 67  .**          dig
1bdf0 69 74 73 20 61 6e 64 20 77 68 65 72 65 20 56 56  its and where VV
1be00 56 20 69 73 20 61 6e 79 20 73 65 71 75 65 6e 63  V is any sequenc
1be10 65 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  e of one or more
1be20 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c   .**          al
1be30 70 68 61 6e 75 6d 65 72 69 63 20 63 68 61 72 61  phanumeric chara
1be40 63 74 65 72 73 20 6f 72 20 22 3a 3a 22 20 6f 70  cters or "::" op
1be50 74 69 6f 6e 61 6c 6c 79 20 66 6f 6c 6c 6f 77 65  tionally followe
1be60 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20  d by.**         
1be70 20 61 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69   a string contai
1be80 6e 69 6e 67 20 6e 6f 20 73 70 61 63 65 73 20 61  ning no spaces a
1be90 6e 64 20 63 6f 6e 74 61 69 6e 65 64 20 77 69 74  nd contained wit
1bea0 68 69 6e 20 70 61 72 65 6e 74 68 65 73 65 73 2e  hin parentheses.
1beb0 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 30 39 7d 20  .**.** {F13509} 
1bec0 54 68 65 20 69 6e 69 74 69 61 6c 20 76 61 6c 75  The initial valu
1bed0 65 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61  e of an SQL para
1bee0 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 2e 0a 2a  meter is NULL..*
1bef0 2a 0a 2a 2a 20 7b 46 31 33 35 31 32 7d 20 54 68  *.** {F13512} Th
1bf00 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 22 3f  e index of an "?
1bf10 22 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  " SQL parameter 
1bf20 69 73 20 6f 6e 65 20 6c 61 72 67 65 72 20 74 68  is one larger th
1bf30 61 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  an the.**       
1bf40 20 20 20 6c 61 72 67 65 73 74 20 69 6e 64 65 78     largest index
1bf50 20 6f 66 20 53 51 4c 20 70 61 72 61 6d 65 74 65   of SQL paramete
1bf60 72 20 74 6f 20 74 68 65 20 6c 65 66 74 2c 20 6f  r to the left, o
1bf70 72 20 31 20 69 66 0a 2a 2a 20 20 20 20 20 20 20  r 1 if.**       
1bf80 20 20 20 74 68 65 20 22 3f 22 20 69 73 20 74 68     the "?" is th
1bf90 65 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70  e leftmost SQL p
1bfa0 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
1bfb0 7b 46 31 33 35 31 35 7d 20 54 68 65 20 69 6e 64  {F13515} The ind
1bfc0 65 78 20 6f 66 20 61 6e 20 22 3f 4e 4e 4e 22 20  ex of an "?NNN" 
1bfd0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73  SQL parameter is
1bfe0 20 74 68 65 20 69 6e 74 65 67 65 72 20 4e 4e 4e   the integer NNN
1bff0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 31 38 7d  ..**.** {F13518}
1c000 20 54 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e   The index of an
1c010 20 22 3a 56 56 56 22 2c 20 22 24 56 56 56 22 2c   ":VVV", "$VVV",
1c020 20 6f 72 20 22 40 56 56 56 22 20 53 51 4c 20 70   or "@VVV" SQL p
1c030 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 20  arameter is.**  
1c040 20 20 20 20 20 20 20 20 74 68 65 20 73 61 6d 65          the same
1c050 20 61 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66   as the index of
1c060 20 6c 65 66 74 6d 6f 73 74 20 6f 63 63 75 72 61   leftmost occura
1c070 6e 63 65 73 20 6f 66 20 74 68 65 20 73 61 6d 65  nces of the same
1c080 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 61 72  .**          par
1c090 61 6d 65 74 65 72 2c 20 6f 72 20 6f 6e 65 20 6d  ameter, or one m
1c0a0 6f 72 65 20 74 68 61 6e 20 74 68 65 20 6c 61 72  ore than the lar
1c0b0 67 65 73 74 20 69 6e 64 65 78 20 6f 76 65 72 20  gest index over 
1c0c0 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  all.**          
1c0d0 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68  parameters to th
1c0e0 65 20 6c 65 66 74 20 69 66 20 74 68 69 73 20 69  e left if this i
1c0f0 73 20 74 68 65 20 66 69 72 73 74 20 6f 63 63 75  s the first occu
1c100 72 72 61 6e 63 65 0a 2a 2a 20 20 20 20 20 20 20  rrance.**       
1c110 20 20 20 6f 66 20 74 68 69 73 20 70 61 72 61 6d     of this param
1c120 65 74 65 72 2c 20 6f 72 20 31 20 69 66 20 74 68  eter, or 1 if th
1c130 69 73 20 69 73 20 74 68 65 20 6c 65 66 74 6d 6f  is is the leftmo
1c140 73 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  st parameter..**
1c150 0a 2a 2a 20 7b 46 31 33 35 32 31 7d 20 54 68 65  .** {F13521} The
1c160 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1c170 65 20 7c 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  e | SQL statemen
1c180 74 20 63 6f 6d 70 69 6c 65 72 5d 20 66 61 69 6c  t compiler] fail
1c190 20 77 69 74 68 0a 2a 2a 20 20 20 20 20 20 20 20   with.**        
1c1a0 20 20 61 6e 20 5b 53 51 4c 49 54 45 5f 52 41 4e    an [SQLITE_RAN
1c1b0 47 45 5d 20 65 72 72 6f 72 20 69 66 20 74 68 65  GE] error if the
1c1c0 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c   index of an SQL
1c1d0 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20   parameter.**   
1c1e0 20 20 20 20 20 20 20 69 73 20 6c 65 73 73 20 74         is less t
1c1f0 68 61 6e 20 31 20 6f 72 20 67 72 65 61 74 65 72  han 1 or greater
1c200 20 74 68 61 6e 20 53 51 4c 49 54 45 5f 4d 41 58   than SQLITE_MAX
1c210 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52  _VARIABLE_NUMBER
1c220 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 32 34 7d  ..**.** {F13524}
1c230 20 43 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   Calls to [sqlit
1c240 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 73  e3_bind_text | s
1c250 71 6c 69 74 65 33 5f 62 69 6e 64 28 53 2c 4e 2c  qlite3_bind(S,N,
1c260 56 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20  V,...)].**      
1c270 20 20 20 20 61 73 73 6f 63 69 61 74 65 20 74 68      associate th
1c280 65 20 76 61 6c 75 65 20 56 20 77 69 74 68 20 61  e value V with a
1c290 6c 6c 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  ll SQL parameter
1c2a0 73 20 68 61 76 69 6e 67 20 61 6e 0a 2a 2a 20 20  s having an.**  
1c2b0 20 20 20 20 20 20 20 20 69 6e 64 65 78 20 6f 66          index of
1c2c0 20 4e 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61   N in the [prepa
1c2d0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
1c2e0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 32 37 7d  ..**.** {F13527}
1c2f0 20 43 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   Calls to [sqlit
1c300 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 73  e3_bind_text | s
1c310 71 6c 69 74 65 33 5f 62 69 6e 64 28 53 2c 4e 2c  qlite3_bind(S,N,
1c320 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  ...)].**        
1c330 20 20 6f 76 65 72 72 69 64 65 20 70 72 69 6f 72    override prior
1c340 20 63 61 6c 6c 73 20 77 69 74 68 20 74 68 65 20   calls with the 
1c350 73 61 6d 65 20 76 61 6c 75 65 73 20 6f 66 20 53  same values of S
1c360 20 61 6e 64 20 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 46   and N..**.** {F
1c370 31 33 35 33 30 7d 20 42 69 6e 64 69 6e 67 73 20  13530} Bindings 
1c380 65 73 74 61 62 6c 69 73 68 65 64 20 62 79 20 5b  established by [
1c390 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
1c3a0 74 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  t | sqlite3_bind
1c3b0 28 53 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20  (S,...)].**     
1c3c0 20 20 20 20 20 70 65 72 73 69 73 74 20 61 63 72       persist acr
1c3d0 6f 73 73 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  oss calls to [sq
1c3e0 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 2e  lite3_reset(S)].
1c3f0 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 33 33 7d 20  .**.** {F13533} 
1c400 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  In calls to [sql
1c410 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 53  ite3_bind_blob(S
1c420 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20 20  ,N,V,L,D)],.**  
1c430 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
1c440 5f 62 69 6e 64 5f 74 65 78 74 28 53 2c 4e 2c 56  _bind_text(S,N,V
1c450 2c 4c 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20  ,L,D)], or.**   
1c460 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
1c470 62 69 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e 2c  bind_text16(S,N,
1c480 56 2c 4c 2c 44 29 5d 20 53 51 4c 69 74 65 20 62  V,L,D)] SQLite b
1c490 69 6e 64 73 20 74 68 65 20 66 69 72 73 74 20 4c  inds the first L
1c4a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 79 74  .**          byt
1c4b0 65 73 20 6f 66 20 74 68 65 20 62 6c 6f 62 20 6f  es of the blob o
1c4c0 72 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 64  r string pointed
1c4d0 20 74 6f 20 62 79 20 56 2c 20 77 68 65 6e 20 4c   to by V, when L
1c4e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20  .**          is 
1c4f0 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2e 0a 2a 2a  non-negative..**
1c500 0a 2a 2a 20 7b 46 31 33 35 33 36 7d 20 49 6e 20  .** {F13536} In 
1c510 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
1c520 33 5f 62 69 6e 64 5f 74 65 78 74 28 53 2c 4e 2c  3_bind_text(S,N,
1c530 56 2c 4c 2c 44 29 5d 20 6f 72 0a 2a 2a 20 20 20  V,L,D)] or.**   
1c540 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
1c550 62 69 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e 2c  bind_text16(S,N,
1c560 56 2c 4c 2c 44 29 5d 20 53 51 4c 69 74 65 20 62  V,L,D)] SQLite b
1c570 69 6e 64 73 20 63 68 61 72 61 63 74 65 72 73 0a  inds characters.
1c580 2a 2a 20 20 20 20 20 20 20 20 20 20 66 72 6f 6d  **          from
1c590 20 56 20 74 68 72 6f 75 67 68 20 74 68 65 20 66   V through the f
1c5a0 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63  irst zero charac
1c5b0 74 65 72 20 77 68 65 6e 20 4c 20 69 73 20 6e 65  ter when L is ne
1c5c0 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46  gative..**.** {F
1c5d0 31 33 35 33 39 7d 20 49 6e 20 63 61 6c 6c 73 20  13539} In calls 
1c5e0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  to [sqlite3_bind
1c5f0 5f 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 2c 44 29  _blob(S,N,V,L,D)
1c600 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ],.**          [
1c610 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
1c620 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 20 6f  t(S,N,V,L,D)], o
1c630 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  r.**          [s
1c640 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
1c650 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 77  16(S,N,V,L,D)] w
1c660 68 65 6e 20 44 20 69 73 20 74 68 65 20 73 70 65  hen D is the spe
1c670 63 69 61 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20  cial.**         
1c680 20 63 6f 6e 73 74 61 6e 74 20 5b 53 51 4c 49 54   constant [SQLIT
1c690 45 5f 53 54 41 54 49 43 5d 2c 20 53 51 4c 69 74  E_STATIC], SQLit
1c6a0 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74  e assumes that t
1c6b0 68 65 20 76 61 6c 75 65 20 56 0a 2a 2a 20 20 20  he value V.**   
1c6c0 20 20 20 20 20 20 20 69 73 20 68 65 6c 64 20 69         is held i
1c6d0 6e 20 73 74 61 74 69 63 20 75 6e 6d 61 6e 61 67  n static unmanag
1c6e0 65 64 20 73 70 61 63 65 20 74 68 61 74 20 77 69  ed space that wi
1c6f0 6c 6c 20 6e 6f 74 20 63 68 61 6e 67 65 0a 2a 2a  ll not change.**
1c700 20 20 20 20 20 20 20 20 20 20 64 75 72 69 6e 67            during
1c710 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66   the lifetime of
1c720 20 74 68 65 20 62 69 6e 64 69 6e 67 2e 0a 2a 2a   the binding..**
1c730 0a 2a 2a 20 7b 46 31 33 35 34 32 7d 20 49 6e 20  .** {F13542} In 
1c740 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
1c750 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c  3_bind_blob(S,N,
1c760 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20  V,L,D)],.**     
1c770 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69       [sqlite3_bi
1c780 6e 64 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c  nd_text(S,N,V,L,
1c790 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20  D)], or.**      
1c7a0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e      [sqlite3_bin
1c7b0 64 5f 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c  d_text16(S,N,V,L
1c7c0 2c 44 29 5d 20 77 68 65 6e 20 44 20 69 73 20 74  ,D)] when D is t
1c7d0 68 65 20 73 70 65 63 69 61 6c 0a 2a 2a 20 20 20  he special.**   
1c7e0 20 20 20 20 20 20 20 63 6f 6e 73 74 61 6e 74 20         constant 
1c7f0 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e  [SQLITE_TRANSIEN
1c800 54 5d 2c 20 74 68 65 20 72 6f 75 74 69 6e 65 20  T], the routine 
1c810 6d 61 6b 65 73 20 61 20 0a 2a 2a 20 20 20 20 20  makes a .**     
1c820 20 20 20 20 20 70 72 69 76 61 74 65 20 63 6f 70       private cop
1c830 79 20 6f 66 20 56 20 76 61 6c 75 65 20 62 65 66  y of V value bef
1c840 6f 72 65 20 69 74 20 72 65 74 75 72 6e 73 2e 0a  ore it returns..
1c850 2a 2a 0a 2a 2a 20 7b 46 31 33 35 34 35 7d 20 49  **.** {F13545} I
1c860 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  n calls to [sqli
1c870 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 53 2c  te3_bind_blob(S,
1c880 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20  N,V,L,D)],.**   
1c890 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
1c8a0 62 69 6e 64 5f 74 65 78 74 28 53 2c 4e 2c 56 2c  bind_text(S,N,V,
1c8b0 4c 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20  L,D)], or.**    
1c8c0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62        [sqlite3_b
1c8d0 69 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e 2c 56  ind_text16(S,N,V
1c8e0 2c 4c 2c 44 29 5d 20 77 68 65 6e 20 44 20 69 73  ,L,D)] when D is
1c8f0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a   a pointer to.**
1c900 20 20 20 20 20 20 20 20 20 20 61 20 66 75 6e 63            a func
1c910 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 69 6e 76  tion, SQLite inv
1c920 6f 6b 65 73 20 74 68 61 74 20 66 75 6e 63 74 69  okes that functi
1c930 6f 6e 20 74 6f 20 64 65 73 74 72 6f 79 20 74 68  on to destroy th
1c940 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 56 20  e.**          V 
1c950 76 61 6c 75 65 20 61 66 74 65 72 20 69 74 20 68  value after it h
1c960 61 73 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e  as finished usin
1c970 67 20 74 68 65 20 56 20 76 61 6c 75 65 2e 0a 2a  g the V value..*
1c980 2a 0a 2a 2a 20 7b 46 31 33 35 34 38 7d 20 49 6e  *.** {F13548} In
1c990 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
1c9a0 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62  e3_bind_zeroblob
1c9b0 28 53 2c 4e 2c 56 2c 4c 29 5d 20 74 68 65 20 76  (S,N,V,L)] the v
1c9c0 61 6c 75 65 20 62 6f 75 6e 64 0a 2a 2a 20 20 20  alue bound.**   
1c9d0 20 20 20 20 20 20 20 69 73 20 61 20 62 6c 6f 62         is a blob
1c9e0 20 6f 66 20 4c 20 62 79 74 65 73 2c 20 6f 72 20   of L bytes, or 
1c9f0 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 62 6c  a zero-length bl
1ca00 6f 62 20 69 66 20 4c 20 69 73 20 6e 65 67 61 74  ob if L is negat
1ca10 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35  ive..**.** {F135
1ca20 35 31 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20  51} In calls to 
1ca30 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61  [sqlite3_bind_va
1ca40 6c 75 65 28 53 2c 4e 2c 56 29 5d 20 74 68 65 20  lue(S,N,V)] the 
1ca50 56 20 61 72 67 75 6d 65 6e 74 20 6d 61 79 0a 2a  V argument may.*
1ca60 2a 20 20 20 20 20 20 20 20 20 20 62 65 20 65 69  *          be ei
1ca70 74 68 65 72 20 61 20 5b 70 72 6f 74 65 63 74 65  ther a [protecte
1ca80 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
1ca90 20 6f 62 6a 65 63 74 20 6f 72 20 61 6e 0a 2a 2a   object or an.**
1caa0 20 20 20 20 20 20 20 20 20 20 5b 75 6e 70 72 6f            [unpro
1cab0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
1cac0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f  alue] object..*/
1cad0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
1cae0 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73  d_blob(sqlite3_s
1caf0 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
1cb00 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76   void*, int n, v
1cb10 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
1cb20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
1cb30 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
1cb40 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62  stmt*, int, doub
1cb50 6c 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  le);.int sqlite3
1cb60 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65  _bind_int(sqlite
1cb70 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e  3_stmt*, int, in
1cb80 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  t);.int sqlite3_
1cb90 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74  bind_int64(sqlit
1cba0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73  e3_stmt*, int, s
1cbb0 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69  qlite3_int64);.i
1cbc0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
1cbd0 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d  null(sqlite3_stm
1cbe0 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71  t*, int);.int sq
1cbf0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
1cc00 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
1cc10 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c  nt, const char*,
1cc20 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28   int n, void(*)(
1cc30 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c  void*));.int sql
1cc40 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
1cc50 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
1cc60 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  int, const void*
1cc70 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
1cc80 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69  oid*));.int sqli
1cc90 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73  te3_bind_value(s
1cca0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
1ccb0 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33  t, const sqlite3
1ccc0 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
1ccd0 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62  lite3_bind_zerob
1cce0 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lob(sqlite3_stmt
1ccf0 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a  *, int, int n);.
1cd00 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1cd10 20 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c 20 50   Number Of SQL P
1cd20 61 72 61 6d 65 74 65 72 73 20 7b 46 31 33 36 30  arameters {F1360
1cd30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  0}.**.** This ro
1cd40 75 74 69 6e 65 20 63 61 6e 20 62 65 20 75 73 65  utine can be use
1cd50 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75  d to find the nu
1cd60 6d 62 65 72 20 6f 66 20 53 51 4c 20 70 61 72 61  mber of SQL para
1cd70 6d 65 74 65 72 73 0a 2a 2a 20 69 6e 20 61 20 70  meters.** in a p
1cd80 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1cd90 74 2e 20 20 53 51 4c 20 70 61 72 61 6d 65 74 65  t.  SQL paramete
1cda0 72 73 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66  rs are tokens of
1cdb0 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22   the.** form "?"
1cdc0 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22  , "?NNN", ":AAA"
1cdd0 2c 20 22 24 41 41 41 22 2c 20 6f 72 20 22 40 41  , "$AAA", or "@A
1cde0 41 41 22 20 74 68 61 74 20 73 65 72 76 65 20 61  AA" that serve a
1cdf0 73 0a 2a 2a 20 70 6c 61 63 65 2d 68 6f 6c 64 65  s.** place-holde
1ce00 72 73 20 66 6f 72 20 76 61 6c 75 65 73 20 74 68  rs for values th
1ce10 61 74 20 61 72 65 20 5b 73 71 6c 69 74 65 33 5f  at are [sqlite3_
1ce20 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e  bind_blob | boun
1ce30 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61 72  d].** to the par
1ce40 61 6d 65 74 65 72 73 20 61 74 20 61 20 6c 61 74  ameters at a lat
1ce50 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 54  er time..**.** T
1ce60 68 69 73 20 72 6f 75 74 69 6e 65 20 61 63 74 75  his routine actu
1ce70 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65  ally returns the
1ce80 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 6c 61   index of the la
1ce90 72 67 65 73 74 20 70 61 72 61 6d 65 74 65 72 2e  rgest parameter.
1cea0 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d  .** For all form
1ceb0 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74  s except ?NNN, t
1cec0 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 73 70  his will corresp
1ced0 6f 6e 64 20 74 6f 20 74 68 65 20 6e 75 6d 62 65  ond to the numbe
1cee0 72 20 6f 66 0a 2a 2a 20 75 6e 69 71 75 65 20 70  r of.** unique p
1cef0 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66 20 70  arameters.  If p
1cf00 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
1cf10 20 3f 4e 4e 4e 20 61 72 65 20 75 73 65 64 2c 20   ?NNN are used, 
1cf20 74 68 65 72 65 20 6d 61 79 0a 2a 2a 20 62 65 20  there may.** be 
1cf30 67 61 70 73 20 69 6e 20 74 68 65 20 6c 69 73 74  gaps in the list
1cf40 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
1cf50 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  : [sqlite3_bind_
1cf60 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e  blob|sqlite3_bin
1cf70 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  d()],.** [sqlite
1cf80 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
1cf90 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a  _name()], and.**
1cfa0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
1cfb0 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
1cfc0 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  ]..**.** INVARIA
1cfd0 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 36  NTS:.**.** {F136
1cfe0 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  01} The [sqlite3
1cff0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
1d000 63 6f 75 6e 74 28 53 29 5d 20 69 6e 74 65 72 66  count(S)] interf
1d010 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20  ace returns.**  
1d020 20 20 20 20 20 20 20 20 74 68 65 20 6c 61 72 67          the larg
1d030 65 73 74 20 69 6e 64 65 78 20 6f 66 20 61 6c 6c  est index of all
1d040 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20   SQL parameters 
1d050 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  in the.**       
1d060 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61     [prepared sta
1d070 74 65 6d 65 6e 74 5d 20 53 2c 20 6f 72 20 30 20  tement] S, or 0 
1d080 69 66 20 53 0a 2a 2a 20 20 20 20 20 20 20 20 20  if S.**         
1d090 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c   contains no SQL
1d0a0 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a   parameters..*/.
1d0b0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
1d0c0 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
1d0d0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
1d0e0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1d0f0 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 74  : Name Of A Host
1d100 20 50 61 72 61 6d 65 74 65 72 20 7b 46 31 33 36   Parameter {F136
1d110 32 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  20}.**.** This r
1d120 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61  outine returns a
1d130 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
1d140 6e 61 6d 65 20 6f 66 20 74 68 65 20 6e 2d 74 68  name of the n-th
1d150 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65  .** SQL paramete
1d160 72 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64  r in a [prepared
1d170 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
1d180 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f  SQL parameters o
1d190 66 20 74 68 65 20 66 6f 72 6d 20 22 3a 41 41 41  f the form ":AAA
1d1a0 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22  " or "@AAA" or "
1d1b0 24 41 41 41 22 20 68 61 76 65 20 61 20 6e 61 6d  $AAA" have a nam
1d1c0 65 0a 2a 2a 20 77 68 69 63 68 20 69 73 20 74 68  e.** which is th
1d1d0 65 20 73 74 72 69 6e 67 20 22 3a 41 41 41 22 20  e string ":AAA" 
1d1e0 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 56  or "@AAA" or "$V
1d1f0 56 56 22 2e 20 0a 2a 2a 20 49 6e 20 6f 74 68 65  VV". .** In othe
1d200 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e 69  r words, the ini
1d210 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 20  tial ":" or "$" 
1d220 6f 72 20 22 40 22 0a 2a 2a 20 69 73 20 69 6e 63  or "@".** is inc
1d230 6c 75 64 65 64 20 61 73 20 70 61 72 74 20 6f 66  luded as part of
1d240 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 20 50 61   the name..** Pa
1d250 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20  rameters of the 
1d260 66 6f 72 6d 20 22 3f 22 20 6f 72 20 22 3f 4e 4e  form "?" or "?NN
1d270 4e 22 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65 2e  N" have no name.
1d280 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
1d290 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20   host parameter 
1d2a0 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20  has an index of 
1d2b0 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20  1, not 0..**.** 
1d2c0 49 66 20 74 68 65 20 76 61 6c 75 65 20 6e 20 69  If the value n i
1d2d0 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f  s out of range o
1d2e0 72 20 69 66 20 74 68 65 20 6e 2d 74 68 20 70 61  r if the n-th pa
1d2f0 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61  rameter is.** na
1d300 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c  meless, then NUL
1d310 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  L is returned.  
1d320 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
1d330 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73  ing is.** always
1d340 20 69 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e   in the UTF-8 en
1d350 63 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74  coding even if t
1d360 68 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74  he named paramet
1d370 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e  er was.** origin
1d380 61 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20 61  ally specified a
1d390 73 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c  s UTF-16 in [sql
1d3a0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
1d3b0 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
1d3c0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
1d3d0 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
1d3e0 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  : [sqlite3_bind_
1d3f0 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e  blob|sqlite3_bin
1d400 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  d()],.** [sqlite
1d410 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
1d420 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a  _count()], and.*
1d430 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
1d440 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
1d450 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  )]..**.** INVARI
1d460 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  ANTS:.**.** {F13
1d470 36 32 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  621} The [sqlite
1d480 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
1d490 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 69 6e 74 65  _name(S,N)] inte
1d4a0 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a  rface returns.**
1d4b0 20 20 20 20 20 20 20 20 20 20 61 20 55 54 46 2d            a UTF-
1d4c0 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74  8 rendering of t
1d4d0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53  he name of the S
1d4e0 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 6e 0a  QL parameter in.
1d4f0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65  **          [pre
1d500 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
1d510 20 53 20 68 61 76 69 6e 67 20 69 6e 64 65 78 20   S having index 
1d520 4e 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  N, or.**        
1d530 20 20 4e 55 4c 4c 20 69 66 20 74 68 65 72 65 20    NULL if there 
1d540 69 73 20 6e 6f 20 53 51 4c 20 70 61 72 61 6d 65  is no SQL parame
1d550 74 65 72 20 77 69 74 68 20 69 6e 64 65 78 20 4e  ter with index N
1d560 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 20 20   or if the.**   
1d570 20 20 20 20 20 20 20 70 61 72 61 6d 65 74 65 72         parameter
1d580 20 77 69 74 68 20 69 6e 64 65 78 20 4e 20 69 73   with index N is
1d590 20 61 6e 20 61 6e 6f 6e 79 6d 6f 75 73 20 70 61   an anonymous pa
1d5a0 72 61 6d 65 74 65 72 20 22 3f 22 20 6f 72 0a 2a  rameter "?" or.*
1d5b0 2a 20 20 20 20 20 20 20 20 20 20 61 20 6e 75 6d  *          a num
1d5c0 62 65 72 65 64 20 70 61 72 61 6d 65 74 65 72 20  bered parameter 
1d5d0 22 3f 4e 4e 4e 22 2e 0a 2a 2f 0a 63 6f 6e 73 74  "?NNN"..*/.const
1d5e0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 62   char *sqlite3_b
1d5f0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
1d600 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
1d610 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  , int);../*.** C
1d620 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20 4f  API3REF: Index O
1d630 66 20 41 20 50 61 72 61 6d 65 74 65 72 20 57 69  f A Parameter Wi
1d640 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65 20  th A Given Name 
1d650 7b 46 31 33 36 34 30 7d 0a 2a 2a 0a 2a 2a 20 52  {F13640}.**.** R
1d660 65 74 75 72 6e 20 74 68 65 20 69 6e 64 65 78 20  eturn the index 
1d670 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65  of an SQL parame
1d680 74 65 72 20 67 69 76 65 6e 20 69 74 73 20 6e 61  ter given its na
1d690 6d 65 2e 20 20 54 68 65 0a 2a 2a 20 69 6e 64 65  me.  The.** inde
1d6a0 78 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  x value returned
1d6b0 20 69 73 20 73 75 69 74 61 62 6c 65 20 66 6f 72   is suitable for
1d6c0 20 75 73 65 20 61 73 20 74 68 65 20 73 65 63 6f   use as the seco
1d6d0 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  nd.** parameter 
1d6e0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  to [sqlite3_bind
1d6f0 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
1d700 6e 64 28 29 5d 2e 20 20 41 20 7a 65 72 6f 0a 2a  nd()].  A zero.*
1d710 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66  * is returned if
1d720 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70 61 72   no matching par
1d730 61 6d 65 74 65 72 20 69 73 20 66 6f 75 6e 64 2e  ameter is found.
1d740 20 20 54 68 65 20 70 61 72 61 6d 65 74 65 72 0a    The parameter.
1d750 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62 65 20  ** name must be 
1d760 67 69 76 65 6e 20 69 6e 20 55 54 46 2d 38 20 65  given in UTF-8 e
1d770 76 65 6e 20 69 66 20 74 68 65 20 6f 72 69 67 69  ven if the origi
1d780 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  nal statement.**
1d790 20 77 61 73 20 70 72 65 70 61 72 65 64 20 66 72   was prepared fr
1d7a0 6f 6d 20 55 54 46 2d 31 36 20 74 65 78 74 20 75  om UTF-16 text u
1d7b0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  sing [sqlite3_pr
1d7c0 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a  epare16_v2()]..*
1d7d0 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
1d7e0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
1d7f0 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
1d800 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
1d810 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
1d820 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  unt()], and.** [
1d830 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
1d840 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e  ameter_index()].
1d850 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
1d860 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 36 34 31  S:.**.** {F13641
1d870 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  } The [sqlite3_b
1d880 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
1d890 64 65 78 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66  dex(S,N)] interf
1d8a0 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20  ace returns.**  
1d8b0 20 20 20 20 20 20 20 20 74 68 65 20 69 6e 64 65          the inde
1d8c0 78 20 6f 66 20 53 51 4c 20 70 61 72 61 6d 65 74  x of SQL paramet
1d8d0 65 72 20 69 6e 20 5b 70 72 65 70 61 72 65 64 20  er in [prepared 
1d8e0 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 20 20  statement].**   
1d8f0 20 20 20 20 20 20 20 53 20 77 68 6f 73 65 20 6e         S whose n
1d900 61 6d 65 20 6d 61 74 63 68 65 73 20 74 68 65 20  ame matches the 
1d910 55 54 46 2d 38 20 73 74 72 69 6e 67 20 4e 2c 20  UTF-8 string N, 
1d920 6f 72 20 30 20 69 66 20 74 68 65 72 65 20 69 73  or 0 if there is
1d930 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 6f 20  .**          no 
1d940 6d 61 74 63 68 2e 0a 2a 2f 0a 69 6e 74 20 73 71  match..*/.int sq
1d950 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
1d960 65 74 65 72 5f 69 6e 64 65 78 28 73 71 6c 69 74  eter_index(sqlit
1d970 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20  e3_stmt*, const 
1d980 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f  char *zName);../
1d990 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
1d9a0 65 73 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67  eset All Binding
1d9b0 73 20 4f 6e 20 41 20 50 72 65 70 61 72 65 64 20  s On A Prepared 
1d9c0 53 74 61 74 65 6d 65 6e 74 20 7b 46 31 33 36 36  Statement {F1366
1d9d0 30 7d 0a 2a 2a 0a 2a 2a 20 43 6f 6e 74 72 61 72  0}.**.** Contrar
1d9e0 79 20 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69  y to the intuiti
1d9f0 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c  on of many, [sql
1da00 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f  ite3_reset()] do
1da10 65 73 20 6e 6f 74 0a 2a 2a 20 72 65 73 65 74 20  es not.** reset 
1da20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  the [sqlite3_bin
1da30 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67  d_blob | binding
1da40 73 5d 20 6f 6e 20 61 20 0a 2a 2a 20 5b 70 72 65  s] on a .** [pre
1da50 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
1da60 2e 20 20 55 73 65 20 74 68 69 73 20 72 6f 75 74  .  Use this rout
1da70 69 6e 65 20 74 6f 0a 2a 2a 20 72 65 73 65 74 20  ine to.** reset 
1da80 61 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d 65 74  all host paramet
1da90 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a  ers to NULL..**.
1daa0 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
1dab0 2a 0a 2a 2a 20 7b 46 31 33 36 36 31 7d 20 54 68  *.** {F13661} Th
1dac0 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61 72  e [sqlite3_clear
1dad0 5f 62 69 6e 64 69 6e 67 73 28 53 29 5d 20 69 6e  _bindings(S)] in
1dae0 74 65 72 66 61 63 65 20 72 65 73 65 74 73 20 61  terface resets a
1daf0 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53  ll.**          S
1db00 51 4c 20 70 61 72 61 6d 65 74 65 72 20 62 69 6e  QL parameter bin
1db10 64 69 6e 67 73 20 69 6e 20 5b 70 72 65 70 61 72  dings in [prepar
1db20 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a  ed statement] S.
1db30 2a 2a 20 20 20 20 20 20 20 20 20 20 62 61 63 6b  **          back
1db40 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74   to NULL..*/.int
1db50 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62   sqlite3_clear_b
1db60 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f  indings(sqlite3_
1db70 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
1db80 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20  API3REF: Number 
1db90 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20  Of Columns In A 
1dba0 52 65 73 75 6c 74 20 53 65 74 20 7b 46 31 33 37  Result Set {F137
1dbb0 31 30 7d 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e  10}.**.** Return
1dbc0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
1dbd0 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65  olumns in the re
1dbe0 73 75 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65  sult set returne
1dbf0 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 5b 70 72  d by the .** [pr
1dc00 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1dc10 5d 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ]. This routine 
1dc20 72 65 74 75 72 6e 73 20 30 0a 2a 2a 20 69 66 20  returns 0.** if 
1dc30 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51 4c 20  pStmt is an SQL 
1dc40 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 64  statement that d
1dc50 6f 65 73 20 6e 6f 74 20 72 65 74 75 72 6e 20 64  oes not return d
1dc60 61 74 61 20 28 66 6f 72 20 0a 2a 2a 20 65 78 61  ata (for .** exa
1dc70 6d 70 6c 65 20 61 6e 20 55 50 44 41 54 45 29 2e  mple an UPDATE).
1dc80 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
1dc90 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 31 31  S:.**.** {F13711
1dca0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
1dcb0 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 53 29 5d 20  olumn_count(S)] 
1dcc0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
1dcd0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  s the number of.
1dce0 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6c 75  **          colu
1dcf0 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c  mns in the resul
1dd00 74 20 73 65 74 20 67 65 6e 65 72 61 74 65 64 20  t set generated 
1dd10 62 79 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  by the.**       
1dd20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61     [prepared sta
1dd30 74 65 6d 65 6e 74 5d 20 53 2c 20 6f 72 20 30 20  tement] S, or 0 
1dd40 69 66 20 53 20 64 6f 65 73 20 6e 6f 74 20 67 65  if S does not ge
1dd50 6e 65 72 61 74 65 0a 2a 2a 20 20 20 20 20 20 20  nerate.**       
1dd60 20 20 20 61 20 72 65 73 75 6c 74 20 73 65 74 2e     a result set.
1dd70 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1dd80 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c  column_count(sql
1dd90 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
1dda0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1ddb0 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73  EF: Column Names
1ddc0 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74   In A Result Set
1ddd0 20 7b 46 31 33 37 32 30 7d 0a 2a 2a 0a 2a 2a 20   {F13720}.**.** 
1dde0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
1ddf0 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 61  eturn the name a
1de00 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70 61 72  ssigned to a par
1de10 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a  ticular column.*
1de20 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20  * in the result 
1de30 73 65 74 20 6f 66 20 61 20 53 45 4c 45 43 54 20  set of a SELECT 
1de40 73 74 61 74 65 6d 65 6e 74 2e 20 20 54 68 65 20  statement.  The 
1de50 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
1de60 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  ame().** interfa
1de70 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
1de80 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74  nter to a zero-t
1de90 65 72 6d 69 6e 61 74 65 64 20 55 54 46 38 20 73  erminated UTF8 s
1dea0 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c  tring.** and sql
1deb0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
1dec0 31 36 28 29 20 72 65 74 75 72 6e 73 20 61 20 70  16() returns a p
1ded0 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f  ointer to a zero
1dee0 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55  -terminated.** U
1def0 54 46 31 36 20 73 74 72 69 6e 67 2e 20 20 54 68  TF16 string.  Th
1df00 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
1df10 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 70 72 65  r is the.** [pre
1df20 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
1df30 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73   that implements
1df40 20 74 68 65 20 53 45 4c 45 43 54 20 73 74 61 74   the SELECT stat
1df50 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 73 65  ement..** The se
1df60 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
1df70 73 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 75 6d  s the column num
1df80 62 65 72 2e 20 20 54 68 65 20 6c 65 66 74 2d 6d  ber.  The left-m
1df90 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 0a 2a 2a  ost column is.**
1dfa0 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a   number 0..**.**
1dfb0 20 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74   The returned st
1dfc0 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 20  ring pointer is 
1dfd0 76 61 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 68  valid until eith
1dfe0 65 72 20 74 68 65 20 0a 2a 2a 20 5b 70 72 65 70  er the .** [prep
1dff0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
1e000 69 73 20 64 65 73 74 72 6f 79 65 64 20 62 79 20  is destroyed by 
1e010 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
1e020 65 28 29 5d 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c  e()].** or until
1e030 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 73   the next call s
1e040 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
1e050 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  me() or sqlite3_
1e060 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 0a  column_name16().
1e070 2a 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63  ** on the same c
1e080 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  olumn..**.** If 
1e090 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1e0a0 20 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68   fails during th
1e0b0 65 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20  e processing of 
1e0c0 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a  either routine.*
1e0d0 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64  * (for example d
1e0e0 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69  uring a conversi
1e0f0 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f  on from UTF-8 to
1e100 20 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a   UTF-16) then a.
1e110 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  ** NULL pointer 
1e120 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
1e130 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 61  ** The name of a
1e140 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69   result column i
1e150 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  s the value of t
1e160 68 65 20 22 41 53 22 20 63 6c 61 75 73 65 20 66  he "AS" clause f
1e170 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d  or.** that colum
1e180 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73 20 61  n, if there is a
1e190 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66  n AS clause.  If
1e1a0 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20   there is no AS 
1e1b0 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74  clause.** then t
1e1c0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63  he name of the c
1e1d0 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69  olumn is unspeci
1e1e0 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61  fied and may cha
1e1f0 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20  nge from.** one 
1e200 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
1e210 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a  e to the next..*
1e220 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
1e230 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 32 31 7d 20  .**.** {F13721} 
1e240 41 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e 76  A successful inv
1e250 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b  ocation of the [
1e260 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
1e270 61 6d 65 28 53 2c 4e 29 5d 0a 2a 2a 20 20 20 20  ame(S,N)].**    
1e280 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 20        interface 
1e290 72 65 74 75 72 6e 73 20 74 68 65 20 6e 61 6d 65  returns the name
1e2a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20  .**          of 
1e2b0 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 28  the Nth column (
1e2c0 77 68 65 72 65 20 30 20 69 73 20 74 68 65 20 6c  where 0 is the l
1e2d0 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 29  eft-most column)
1e2e0 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20   for the.**     
1e2f0 20 20 20 20 20 72 65 73 75 6c 74 20 73 65 74 20       result set 
1e300 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  of [prepared sta
1e310 74 65 6d 65 6e 74 5d 20 53 20 61 73 20 61 0a 2a  tement] S as a.*
1e320 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 2d  *          zero-
1e330 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
1e340 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b   string..**.** {
1e350 46 31 33 37 32 33 7d 20 41 20 73 75 63 63 65 73  F13723} A succes
1e360 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20  sful invocation 
1e370 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
1e380 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 53 2c  column_name16(S,
1e390 4e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  N)].**          
1e3a0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
1e3b0 73 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 20 20  s the name.**   
1e3c0 20 20 20 20 20 20 20 6f 66 20 74 68 65 20 4e 74         of the Nt
1e3d0 68 20 63 6f 6c 75 6d 6e 20 28 77 68 65 72 65 20  h column (where 
1e3e0 30 20 69 73 20 74 68 65 20 6c 65 66 74 2d 6d 6f  0 is the left-mo
1e3f0 73 74 20 63 6f 6c 75 6d 6e 29 20 66 6f 72 20 74  st column) for t
1e400 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  he.**          r
1e410 65 73 75 6c 74 20 73 65 74 20 6f 66 20 5b 70 72  esult set of [pr
1e420 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1e430 5d 20 53 20 61 73 20 61 0a 2a 2a 20 20 20 20 20  ] S as a.**     
1e440 20 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e       zero-termin
1e450 61 74 65 64 20 55 54 46 2d 31 36 20 73 74 72 69  ated UTF-16 stri
1e460 6e 67 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  ng in the native
1e470 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a   byte order..**.
1e480 2a 2a 20 7b 46 31 33 37 32 34 7d 20 54 68 65 20  ** {F13724} The 
1e490 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
1e4a0 6e 61 6d 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  name()] and [sql
1e4b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
1e4c0 31 36 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  16()].**        
1e4d0 20 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 74    interfaces ret
1e4e0 75 72 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  urn a NULL point
1e4f0 65 72 20 69 66 20 74 68 65 79 20 61 72 65 20 75  er if they are u
1e500 6e 61 62 6c 65 20 74 6f 0a 2a 2a 20 20 20 20 20  nable to.**     
1e510 20 20 20 20 20 61 6c 6c 6f 63 61 74 65 20 6d 65       allocate me
1e520 6d 6f 72 79 20 6d 65 6d 6f 72 79 20 74 6f 20 68  mory memory to h
1e530 6f 6c 64 20 74 68 65 72 65 20 6e 6f 72 6d 61 6c  old there normal
1e540 20 72 65 74 75 72 6e 20 73 74 72 69 6e 67 73 2e   return strings.
1e550 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 32 35 7d 20  .**.** {F13725} 
1e560 49 66 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74  If the N paramet
1e570 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  er to [sqlite3_c
1e580 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 53 2c 4e 29 5d  olumn_name(S,N)]
1e590 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   or.**          
1e5a0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
1e5b0 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20 69 73 20  name16(S,N)] is 
1e5c0 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68  out of range, th
1e5d0 65 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  en the.**       
1e5e0 20 20 20 69 6e 74 65 72 66 61 63 65 73 20 72 65     interfaces re
1e5f0 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69  turns a NULL poi
1e600 6e 74 65 72 2e 0a 2a 2a 20 0a 2a 2a 20 7b 46 31  nter..** .** {F1
1e610 33 37 32 36 7d 20 54 68 65 20 73 74 72 69 6e 67  3726} The string
1e620 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  s returned by [s
1e630 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
1e640 6d 65 28 53 2c 4e 29 5d 20 61 6e 64 0a 2a 2a 20  me(S,N)] and.** 
1e650 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
1e660 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
1e670 53 2c 4e 29 5d 20 61 72 65 20 76 61 6c 69 64 20  S,N)] are valid 
1e680 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 0a 2a  until the next.*
1e690 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c 20  *          call 
1e6a0 74 6f 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e  to either routin
1e6b0 65 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20  e with the same 
1e6c0 53 20 61 6e 64 20 4e 20 70 61 72 61 6d 65 74 65  S and N paramete
1e6d0 72 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  rs.**          o
1e6e0 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33  r until [sqlite3
1e6f0 5f 66 69 6e 61 6c 69 7a 65 28 53 29 5d 20 69 73  _finalize(S)] is
1e700 20 63 61 6c 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b   called..**.** {
1e710 46 31 33 37 32 37 7d 20 57 68 65 6e 20 61 20 72  F13727} When a r
1e720 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20  esult column of 
1e730 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  a [SELECT] state
1e740 6d 65 6e 74 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a  ment contains.**
1e750 20 20 20 20 20 20 20 20 20 20 61 6e 20 41 53 20            an AS 
1e760 63 6c 61 75 73 65 2c 20 74 68 65 20 6e 61 6d 65  clause, the name
1e770 20 6f 66 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20   of that column 
1e780 69 73 20 74 68 65 20 69 6e 64 65 6e 74 69 66 69  is the indentifi
1e790 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  er.**          t
1e7a0 6f 20 74 68 65 20 72 69 67 68 74 20 6f 66 20 74  o the right of t
1e7b0 68 65 20 41 53 20 6b 65 79 77 6f 72 64 2e 0a 2a  he AS keyword..*
1e7c0 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
1e7d0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
1e7e0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
1e7f0 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76   int N);.const v
1e800 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
1e810 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  umn_name16(sqlit
1e820 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29  e3_stmt*, int N)
1e830 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1e840 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 44 61 74  F: Source Of Dat
1e850 61 20 49 6e 20 41 20 51 75 65 72 79 20 52 65 73  a In A Query Res
1e860 75 6c 74 20 7b 46 31 33 37 34 30 7d 0a 2a 2a 0a  ult {F13740}.**.
1e870 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
1e880 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65 61 6e  s provide a mean
1e890 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 77  s to determine w
1e8a0 68 61 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 77 68  hat column of wh
1e8b0 61 74 0a 2a 2a 20 74 61 62 6c 65 20 69 6e 20 77  at.** table in w
1e8c0 68 69 63 68 20 64 61 74 61 62 61 73 65 20 61 20  hich database a 
1e8d0 72 65 73 75 6c 74 20 6f 66 20 61 20 53 45 4c 45  result of a SELE
1e8e0 43 54 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d  CT statement com
1e8f0 65 73 20 66 72 6f 6d 2e 0a 2a 2a 20 54 68 65 20  es from..** The 
1e900 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61  name of the data
1e910 62 61 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72  base or table or
1e920 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72   column can be r
1e930 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69  eturned as.** ei
1e940 74 68 65 72 20 61 20 55 54 46 38 20 6f 72 20 55  ther a UTF8 or U
1e950 54 46 31 36 20 73 74 72 69 6e 67 2e 20 20 54 68  TF16 string.  Th
1e960 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f 75  e _database_ rou
1e970 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20  tines return.** 
1e980 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d  the database nam
1e990 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 72  e, the _table_ r
1e9a0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74  outines return t
1e9b0 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61  he table name, a
1e9c0 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e  nd.** the origin
1e9d0 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  _ routines retur
1e9e0 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d  n the column nam
1e9f0 65 2e 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 6e  e..** The return
1ea00 65 64 20 73 74 72 69 6e 67 20 69 73 20 76 61 6c  ed string is val
1ea10 69 64 20 75 6e 74 69 6c 0a 2a 2a 20 74 68 65 20  id until.** the 
1ea20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
1ea30 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65  ent] is destroye
1ea40 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  d using.** [sqli
1ea50 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
1ea60 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 61 6d  or until the sam
1ea70 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  e information is
1ea80 20 72 65 71 75 65 73 74 65 64 0a 2a 2a 20 61 67   requested.** ag
1ea90 61 69 6e 20 69 6e 20 61 20 64 69 66 66 65 72 65  ain in a differe
1eaa0 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a  nt encoding..**.
1eab0 2a 2a 20 54 68 65 20 6e 61 6d 65 73 20 72 65 74  ** The names ret
1eac0 75 72 6e 65 64 20 61 72 65 20 74 68 65 20 6f 72  urned are the or
1ead0 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65  iginal un-aliase
1eae0 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a  d names of the.*
1eaf0 2a 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c  * database, tabl
1eb00 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a  e, and column..*
1eb10 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  *.** The first a
1eb20 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 66  rgument to the f
1eb30 6f 6c 6c 6f 77 69 6e 67 20 63 61 6c 6c 73 20 69  ollowing calls i
1eb40 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  s a [prepared st
1eb50 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 54 68 65  atement]..** The
1eb60 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74  se functions ret
1eb70 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  urn information 
1eb80 61 62 6f 75 74 20 74 68 65 20 4e 74 68 20 63 6f  about the Nth co
1eb90 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79  lumn returned by
1eba0 20 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65   .** the stateme
1ebb0 6e 74 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74  nt, where N is t
1ebc0 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69  he second functi
1ebd0 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  on argument..**.
1ebe0 2a 2a 20 49 66 20 74 68 65 20 4e 74 68 20 63 6f  ** If the Nth co
1ebf0 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79  lumn returned by
1ec00 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
1ec10 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 0a  s an expression.
1ec20 2a 2a 20 6f 72 20 73 75 62 71 75 65 72 79 20 61  ** or subquery a
1ec30 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75  nd is not a colu
1ec40 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 61  mn value, then a
1ec50 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63  ll of these func
1ec60 74 69 6f 6e 73 0a 2a 2a 20 72 65 74 75 72 6e 20  tions.** return 
1ec70 4e 55 4c 4c 2e 20 20 54 68 65 73 65 20 72 6f 75  NULL.  These rou
1ec80 74 69 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f 20  tine might also 
1ec90 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61  return NULL if a
1eca0 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
1ecb0 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75  ation error occu
1ecc0 72 73 2e 20 20 4f 74 68 65 72 77 69 73 65 2c 20  rs.  Otherwise, 
1ecd0 74 68 65 79 20 72 65 74 75 72 6e 20 74 68 65 20  they return the 
1ece0 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  .** name of the 
1ecf0 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73  attached databas
1ed00 65 2c 20 74 61 62 6c 65 20 61 6e 64 20 63 6f 6c  e, table and col
1ed10 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79 20 72  umn that query r
1ed20 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  esult.** column 
1ed30 77 61 73 20 65 78 74 72 61 63 74 65 64 20 66 72  was extracted fr
1ed40 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 77 69 74  om..**.** As wit
1ed50 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69  h all other SQLi
1ed60 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20 70  te APIs, those p
1ed70 6f 73 74 66 69 78 65 64 20 77 69 74 68 20 22 31  ostfixed with "1
1ed80 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46  6" return.** UTF
1ed90 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 74 72 69  -16 encoded stri
1eda0 6e 67 73 2c 20 74 68 65 20 6f 74 68 65 72 20 66  ngs, the other f
1edb0 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20  unctions return 
1edc0 55 54 46 2d 38 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a  UTF-8. {END}.**.
1edd0 2a 2a 20 54 68 65 73 65 20 41 50 49 73 20 61 72  ** These APIs ar
1ede0 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65  e only available
1edf0 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 20   if the library 
1ee00 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74  was compiled wit
1ee10 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45  h the .** SQLITE
1ee20 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d  _ENABLE_COLUMN_M
1ee30 45 54 41 44 41 54 41 20 70 72 65 70 72 6f 63 65  ETADATA preproce
1ee40 73 73 6f 72 20 73 79 6d 62 6f 6c 20 64 65 66 69  ssor symbol defi
1ee50 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 55 31 33 37  ned..**.** {U137
1ee60 35 31 7d 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72  51}.** If two or
1ee70 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61   more threads ca
1ee80 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f  ll one or more o
1ee90 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
1eea0 20 61 67 61 69 6e 73 74 20 74 68 65 20 73 61 6d   against the sam
1eeb0 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74  e.** prepared st
1eec0 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75  atement and colu
1eed0 6d 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  mn at the same t
1eee0 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73  ime then the res
1eef0 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65  ults are.** unde
1ef00 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  fined..**.** INV
1ef10 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
1ef20 46 31 33 37 34 31 7d 20 54 68 65 20 5b 73 71 6c  F13741} The [sql
1ef30 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61  ite3_column_data
1ef40 62 61 73 65 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20  base_name(S,N)] 
1ef50 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
1ef60 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20  s either.**     
1ef70 20 20 20 20 20 74 68 65 20 55 54 46 2d 38 20 7a       the UTF-8 z
1ef80 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e  ero-terminated n
1ef90 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ame of the datab
1efa0 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68 20 74  ase from which t
1efb0 68 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  he .**          
1efc0 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  Nth result colum
1efd0 6e 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73  n of [prepared s
1efe0 74 61 74 65 6d 65 6e 74 5d 20 53 20 0a 2a 2a 20  tatement] S .** 
1eff0 20 20 20 20 20 20 20 20 20 69 73 20 65 78 74 72           is extr
1f000 61 63 74 65 64 2c 20 6f 72 20 4e 55 4c 4c 20 69  acted, or NULL i
1f010 66 20 74 68 65 20 74 68 65 20 4e 74 68 20 63 6f  f the the Nth co
1f020 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20 61 0a 2a  lumn of S is a.*
1f030 2a 20 20 20 20 20 20 20 20 20 20 67 65 6e 65 72  *          gener
1f040 61 6c 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72  al expression or
1f050 20 69 66 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c   if unable to al
1f060 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 0a 2a 2a  locate memory.**
1f070 20 20 20 20 20 20 20 20 20 20 74 6f 20 73 74 6f            to sto
1f080 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 20  re the name..** 
1f090 20 20 20 20 20 20 20 20 20 0a 2a 2a 20 7b 46 31           .** {F1
1f0a0 33 37 34 32 7d 20 54 68 65 20 5b 73 71 6c 69 74  3742} The [sqlit
1f0b0 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61  e3_column_databa
1f0c0 73 65 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20  se_name16(S,N)] 
1f0d0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
1f0e0 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20  s either.**     
1f0f0 20 20 20 20 20 74 68 65 20 55 54 46 2d 31 36 20       the UTF-16 
1f100 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
1f110 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65  r.**          ze
1f120 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e 61  ro-terminated na
1f130 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  me of the databa
1f140 73 65 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68  se from which th
1f150 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e  e .**          N
1f160 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  th result column
1f170 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74   of [prepared st
1f180 61 74 65 6d 65 6e 74 5d 20 53 20 0a 2a 2a 20 20  atement] S .**  
1f190 20 20 20 20 20 20 20 20 69 73 20 65 78 74 72 61          is extra
1f1a0 63 74 65 64 2c 20 6f 72 20 4e 55 4c 4c 20 69 66  cted, or NULL if
1f1b0 20 74 68 65 20 74 68 65 20 4e 74 68 20 63 6f 6c   the the Nth col
1f1c0 75 6d 6e 20 6f 66 20 53 20 69 73 20 61 0a 2a 2a  umn of S is a.**
1f1d0 20 20 20 20 20 20 20 20 20 20 67 65 6e 65 72 61            genera
1f1e0 6c 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20  l expression or 
1f1f0 69 66 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c  if unable to all
1f200 6f 63 61 74 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20  ocate memory.** 
1f210 20 20 20 20 20 20 20 20 20 74 6f 20 73 74 6f 72           to stor
1f220 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 20 20  e the name..**  
1f230 20 20 20 20 20 20 20 20 0a 2a 2a 20 7b 46 31 33          .** {F13
1f240 37 34 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  743} The [sqlite
1f250 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e  3_column_table_n
1f260 61 6d 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66  ame(S,N)] interf
1f270 61 63 65 20 72 65 74 75 72 6e 73 20 65 69 74 68  ace returns eith
1f280 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  er.**          t
1f290 68 65 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65  he UTF-8 zero-te
1f2a0 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66  rminated name of
1f2b0 20 74 68 65 20 74 61 62 6c 65 20 66 72 6f 6d 20   the table from 
1f2c0 77 68 69 63 68 20 74 68 65 20 0a 2a 2a 20 20 20  which the .**   
1f2d0 20 20 20 20 20 20 20 4e 74 68 20 72 65 73 75 6c         Nth resul
1f2e0 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 5b 70 72 65  t column of [pre
1f2f0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
1f300 20 53 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   S .**          
1f310 69 73 20 65 78 74 72 61 63 74 65 64 2c 20 6f 72  is extracted, or
1f320 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 74 68 65   NULL if the the
1f330 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 53   Nth column of S
1f340 20 69 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20   is a.**        
1f350 20 20 67 65 6e 65 72 61 6c 20 65 78 70 72 65 73    general expres
1f360 73 69 6f 6e 20 6f 72 20 69 66 20 75 6e 61 62 6c  sion or if unabl
1f370 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65  e to allocate me
1f380 6d 6f 72 79 0a 2a 2a 20 20 20 20 20 20 20 20 20  mory.**         
1f390 20 74 6f 20 73 74 6f 72 65 20 74 68 65 20 6e 61   to store the na
1f3a0 6d 65 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  me..**          
1f3b0 0a 2a 2a 20 7b 46 31 33 37 34 34 7d 20 54 68 65  .** {F13744} The
1f3c0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
1f3d0 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 53 2c  _table_name16(S,
1f3e0 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  N)] interface re
1f3f0 74 75 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20  turns either.** 
1f400 20 20 20 20 20 20 20 20 20 74 68 65 20 55 54 46           the UTF
1f410 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20  -16 native byte 
1f420 6f 72 64 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  order.**        
1f430 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65    zero-terminate
1f440 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 74 61  d name of the ta
1f450 62 6c 65 20 66 72 6f 6d 20 77 68 69 63 68 20 74  ble from which t
1f460 68 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  he .**          
1f470 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  Nth result colum
1f480 6e 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73  n of [prepared s
1f490 74 61 74 65 6d 65 6e 74 5d 20 53 20 0a 2a 2a 20  tatement] S .** 
1f4a0 20 20 20 20 20 20 20 20 20 69 73 20 65 78 74 72           is extr
1f4b0 61 63 74 65 64 2c 20 6f 72 20 4e 55 4c 4c 20 69  acted, or NULL i
1f4c0 66 20 74 68 65 20 74 68 65 20 4e 74 68 20 63 6f  f the the Nth co
1f4d0 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20 61 0a 2a  lumn of S is a.*
1f4e0 2a 20 20 20 20 20 20 20 20 20 20 67 65 6e 65 72  *          gener
1f4f0 61 6c 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72  al expression or
1f500 20 69 66 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c   if unable to al
1f510 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 0a 2a 2a  locate memory.**
1f520 20 20 20 20 20 20 20 20 20 20 74 6f 20 73 74 6f            to sto
1f530 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 20  re the name..** 
1f540 20 20 20 20 20 20 20 20 20 0a 2a 2a 20 7b 46 31           .** {F1
1f550 33 37 34 35 7d 20 54 68 65 20 5b 73 71 6c 69 74  3745} The [sqlit
1f560 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e  e3_column_origin
1f570 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 69 6e 74 65  _name(S,N)] inte
1f580 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 65 69  rface returns ei
1f590 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  ther.**         
1f5a0 20 74 68 65 20 55 54 46 2d 38 20 7a 65 72 6f 2d   the UTF-8 zero-
1f5b0 74 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20  terminated name 
1f5c0 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c  of the table col
1f5d0 75 6d 6e 20 66 72 6f 6d 20 77 68 69 63 68 20 74  umn from which t
1f5e0 68 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  he .**          
1f5f0 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  Nth result colum
1f600 6e 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73  n of [prepared s
1f610 74 61 74 65 6d 65 6e 74 5d 20 53 20 0a 2a 2a 20  tatement] S .** 
1f620 20 20 20 20 20 20 20 20 20 69 73 20 65 78 74 72           is extr
1f630 61 63 74 65 64 2c 20 6f 72 20 4e 55 4c 4c 20 69  acted, or NULL i
1f640 66 20 74 68 65 20 74 68 65 20 4e 74 68 20 63 6f  f the the Nth co
1f650 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20 61 0a 2a  lumn of S is a.*
1f660 2a 20 20 20 20 20 20 20 20 20 20 67 65 6e 65 72  *          gener
1f670 61 6c 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72  al expression or
1f680 20 69 66 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c   if unable to al
1f690 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 0a 2a 2a  locate memory.**
1f6a0 20 20 20 20 20 20 20 20 20 20 74 6f 20 73 74 6f            to sto
1f6b0 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 20  re the name..** 
1f6c0 20 20 20 20 20 20 20 20 20 0a 2a 2a 20 7b 46 31           .** {F1
1f6d0 33 37 34 36 7d 20 54 68 65 20 5b 73 71 6c 69 74  3746} The [sqlit
1f6e0 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e  e3_column_origin
1f6f0 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20 69 6e  _name16(S,N)] in
1f700 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
1f710 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20  either.**       
1f720 20 20 20 74 68 65 20 55 54 46 2d 31 36 20 6e 61     the UTF-16 na
1f730 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 0a  tive byte order.
1f740 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f  **          zero
1f750 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65  -terminated name
1f760 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f   of the table co
1f770 6c 75 6d 6e 20 66 72 6f 6d 20 77 68 69 63 68 20  lumn from which 
1f780 74 68 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  the .**         
1f790 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75   Nth result colu
1f7a0 6d 6e 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20  mn of [prepared 
1f7b0 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 0a 2a 2a  statement] S .**
1f7c0 20 20 20 20 20 20 20 20 20 20 69 73 20 65 78 74            is ext
1f7d0 72 61 63 74 65 64 2c 20 6f 72 20 4e 55 4c 4c 20  racted, or NULL 
1f7e0 69 66 20 74 68 65 20 74 68 65 20 4e 74 68 20 63  if the the Nth c
1f7f0 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20 61 0a  olumn of S is a.
1f800 2a 2a 20 20 20 20 20 20 20 20 20 20 67 65 6e 65  **          gene
1f810 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e 20 6f  ral expression o
1f820 72 20 69 66 20 75 6e 61 62 6c 65 20 74 6f 20 61  r if unable to a
1f830 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 0a 2a  llocate memory.*
1f840 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 73 74  *          to st
1f850 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a  ore the name..**
1f860 20 20 20 20 20 20 20 20 20 20 0a 2a 2a 20 7b 46            .** {F
1f870 31 33 37 34 38 7d 20 54 68 65 20 72 65 74 75 72  13748} The retur
1f880 6e 20 76 61 6c 75 65 73 20 66 72 6f 6d 0a 2a 2a  n values from.**
1f890 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
1f8a0 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61  e3_column_databa
1f8b0 73 65 5f 6e 61 6d 65 7c 63 6f 6c 75 6d 6e 20 6d  se_name|column m
1f8c0 65 74 61 64 61 74 61 20 69 6e 74 65 72 66 61 63  etadata interfac
1f8d0 65 73 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  es].**          
1f8e0 61 72 65 20 76 61 6c 69 64 0a 2a 2a 20 20 20 20  are valid.**    
1f8f0 20 20 20 20 20 20 66 6f 72 20 74 68 65 20 6c 69        for the li
1f900 66 65 74 69 6d 65 20 6f 66 20 74 68 65 20 5b 70  fetime of the [p
1f910 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1f920 74 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  t].**          o
1f930 72 20 75 6e 74 69 6c 20 74 68 65 20 65 6e 63 6f  r until the enco
1f940 64 69 6e 67 20 69 73 20 63 68 61 6e 67 65 64 20  ding is changed 
1f950 62 79 20 61 6e 6f 74 68 65 72 20 6d 65 74 61 64  by another metad
1f960 61 74 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ata.**          
1f970 69 6e 74 65 72 66 61 63 65 20 63 61 6c 6c 20 66  interface call f
1f980 6f 72 20 74 68 65 20 73 61 6d 65 20 70 72 65 70  or the same prep
1f990 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61  ared statement a
1f9a0 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a  nd column..**.**
1f9b0 20 4c 49 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a   LIMITATIONS:.**
1f9c0 0a 2a 2a 20 7b 55 31 33 37 35 31 7d 20 49 66 20  .** {U13751} If 
1f9d0 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65  two or more thre
1f9e0 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20  ads call one or 
1f9f0 6d 6f 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  more.**         
1fa00 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
1fa10 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 7c 63  _database_name|c
1fa20 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69  olumn metadata i
1fa30 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 20 20  nterfaces].**   
1fa40 20 20 20 20 20 20 20 74 68 65 20 73 61 6d 65 20         the same 
1fa50 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
1fa60 65 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c 74 20  ent] and result 
1fa70 63 6f 6c 75 6d 6e 0a 2a 2a 20 20 20 20 20 20 20  column.**       
1fa80 20 20 20 61 74 20 74 68 65 20 73 61 6d 65 20 74     at the same t
1fa90 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73  ime then the res
1faa0 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
1fab0 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  ed..*/.const cha
1fac0 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
1fad0 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 28  n_database_name(
1fae0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
1faf0 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  t);.const void *
1fb00 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
1fb10 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 73  atabase_name16(s
1fb20 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
1fb30 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  );.const char *s
1fb40 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61  qlite3_column_ta
1fb50 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  ble_name(sqlite3
1fb60 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
1fb70 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
1fb80 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61  _column_table_na
1fb90 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
1fba0 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63  t*,int);.const c
1fbb0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
1fbc0 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28  umn_origin_name(
1fbd0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
1fbe0 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  t);.const void *
1fbf0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f  sqlite3_column_o
1fc00 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c  rigin_name16(sql
1fc10 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
1fc20 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1fc30 3a 20 44 65 63 6c 61 72 65 64 20 44 61 74 61 74  : Declared Datat
1fc40 79 70 65 20 4f 66 20 41 20 51 75 65 72 79 20 52  ype Of A Query R
1fc50 65 73 75 6c 74 20 7b 46 31 33 37 36 30 7d 0a 2a  esult {F13760}.*
1fc60 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70  *.** The first p
1fc70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 5b 70  arameter is a [p
1fc80 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1fc90 74 5d 2e 20 0a 2a 2a 20 49 66 20 74 68 69 73 20  t]. .** If this 
1fca0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 53  statement is a S
1fcb0 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 20  ELECT statement 
1fcc0 61 6e 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75  and the Nth colu
1fcd0 6d 6e 20 6f 66 20 74 68 65 20 0a 2a 2a 20 72 65  mn of the .** re
1fce0 74 75 72 6e 65 64 20 72 65 73 75 6c 74 20 73 65  turned result se
1fcf0 74 20 6f 66 20 74 68 61 74 20 53 45 4c 45 43 54  t of that SELECT
1fd00 20 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75   is a table colu
1fd10 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78  mn (not an.** ex
1fd20 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71  pression or subq
1fd30 75 65 72 79 29 20 74 68 65 6e 20 74 68 65 20 64  uery) then the d
1fd40 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20  eclared type of 
1fd50 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c  the table.** col
1fd60 75 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e  umn is returned.
1fd70 20 20 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c    If the Nth col
1fd80 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c  umn of the resul
1fd90 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65  t set is an.** e
1fda0 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62  xpression or sub
1fdb0 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55  query, then a NU
1fdc0 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65  LL pointer is re
1fdd0 74 75 72 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 72  turned..** The r
1fde0 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69  eturned string i
1fdf0 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65  s always UTF-8 e
1fe00 6e 63 6f 64 65 64 2e 20 20 7b 45 4e 44 7d 20 0a  ncoded.  {END} .
1fe10 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20  ** For example, 
1fe20 69 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  in the database 
1fe30 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52  schema:.**.** CR
1fe40 45 41 54 45 20 54 41 42 4c 45 20 74 31 28 63 31  EATE TABLE t1(c1
1fe50 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a   VARIANT);.**.**
1fe60 20 41 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69   And the followi
1fe70 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d  ng statement com
1fe80 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c  piled:.**.** SEL
1fe90 45 43 54 20 63 31 20 2b 20 31 2c 20 63 31 20 46  ECT c1 + 1, c1 F
1fea0 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 54 68  ROM t1;.**.** Th
1feb0 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  en this routine 
1fec0 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65  would return the
1fed0 20 73 74 72 69 6e 67 20 22 56 41 52 49 41 4e 54   string "VARIANT
1fee0 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e 64  " for the second
1fef0 0a 2a 2a 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  .** result colum
1ff00 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20  n (i==1), and a 
1ff10 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72  NULL pointer for
1ff20 20 74 68 65 20 66 69 72 73 74 20 72 65 73 75 6c   the first resul
1ff30 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 28 69 3d 3d  t column.** (i==
1ff40 30 29 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  0)..**.** SQLite
1ff50 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 72 75   uses dynamic ru
1ff60 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e 20 20  n-time typing.  
1ff70 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73 65 20  So just because 
1ff80 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64  a column.** is d
1ff90 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74 61  eclared to conta
1ffa0 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  in a particular 
1ffb0 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65  type does not me
1ffc0 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 64  an that the.** d
1ffd0 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20 74 68  ata stored in th
1ffe0 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20  at column is of 
1fff0 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70  the declared typ
20000 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a  e.  SQLite is.**
20010 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c   strongly typed,
20020 20 62 75 74 20 74 68 65 20 74 79 70 69 6e 67 20   but the typing 
20030 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73  is dynamic not s
20040 74 61 74 69 63 2e 20 20 54 79 70 65 0a 2a 2a 20  tatic.  Type.** 
20050 69 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  is associated wi
20060 74 68 20 69 6e 64 69 76 69 64 75 61 6c 20 76 61  th individual va
20070 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 68 20 74  lues, not with t
20080 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a  he containers.**
20090 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 74 68   used to hold th
200a0 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2a 0a 2a  ose values..**.*
200b0 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
200c0 0a 2a 2a 20 7b 46 31 33 37 36 31 7d 20 20 41 20  .** {F13761}  A 
200d0 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20  successful call 
200e0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  to [sqlite3_colu
200f0 6d 6e 5f 64 65 63 6c 74 79 70 65 28 53 2c 4e 29  mn_decltype(S,N)
20100 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72  ].**           r
20110 65 74 75 72 6e 73 20 61 20 7a 65 72 6f 2d 74 65  eturns a zero-te
20120 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73  rminated UTF-8 s
20130 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67  tring containing
20140 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
20150 20 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 64    the declared d
20160 61 74 61 74 79 70 65 20 6f 66 20 74 68 65 20 74  atatype of the t
20170 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74  able column that
20180 20 61 70 70 65 61 72 73 0a 2a 2a 20 20 20 20 20   appears.**     
20190 20 20 20 20 20 20 61 73 20 74 68 65 20 4e 74 68        as the Nth
201a0 20 63 6f 6c 75 6d 6e 20 28 6e 75 6d 62 65 72 65   column (numbere
201b0 64 20 66 72 6f 6d 20 30 29 20 6f 66 20 74 68 65  d from 0) of the
201c0 20 72 65 73 75 6c 74 20 73 65 74 20 74 6f 20 74   result set to t
201d0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  he.**           
201e0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
201f0 65 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 46  ent] S..**.** {F
20200 31 33 37 36 32 7d 20 20 41 20 73 75 63 63 65 73  13762}  A succes
20210 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71  sful call to [sq
20220 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63  lite3_column_dec
20230 6c 74 79 70 65 31 36 28 53 2c 4e 29 5d 0a 2a 2a  ltype16(S,N)].**
20240 20 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72             retur
20250 6e 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  ns a zero-termin
20260 61 74 65 64 20 55 54 46 2d 31 36 20 6e 61 74 69  ated UTF-16 nati
20270 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 73 74  ve byte order st
20280 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20  ring.**         
20290 20 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65    containing the
202a0 20 64 65 63 6c 61 72 65 64 20 64 61 74 61 74 79   declared dataty
202b0 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20  pe of the table 
202c0 63 6f 6c 75 6d 6e 20 74 68 61 74 20 61 70 70 65  column that appe
202d0 61 72 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ars.**          
202e0 20 61 73 20 74 68 65 20 4e 74 68 20 63 6f 6c 75   as the Nth colu
202f0 6d 6e 20 28 6e 75 6d 62 65 72 65 64 20 66 72 6f  mn (numbered fro
20300 6d 20 30 29 20 6f 66 20 74 68 65 20 72 65 73 75  m 0) of the resu
20310 6c 74 20 73 65 74 20 74 6f 20 74 68 65 0a 2a 2a  lt set to the.**
20320 20 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70             [prep
20330 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
20340 53 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 36 33  S..**.** {F13763
20350 7d 20 20 49 66 20 4e 20 69 73 20 6c 65 73 73 20  }  If N is less 
20360 74 68 61 6e 20 30 20 6f 72 20 4e 20 69 73 20 67  than 0 or N is g
20370 72 65 61 74 65 72 20 74 68 61 6e 20 6f 72 20 65  reater than or e
20380 71 75 61 6c 20 74 6f 0a 2a 2a 20 20 20 20 20 20  qual to.**      
20390 20 20 20 20 20 74 68 65 20 6e 75 6d 62 65 72 20       the number 
203a0 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 5b 70  of columns in [p
203b0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
203c0 74 5d 20 53 0a 2a 2a 20 20 20 20 20 20 20 20 20  t] S.**         
203d0 20 20 6f 72 20 69 66 20 74 68 65 20 4e 74 68 20    or if the Nth 
203e0 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20 61  column of S is a
203f0 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20  n expression or 
20400 73 75 62 71 75 65 72 79 20 72 61 74 68 65 72 0a  subquery rather.
20410 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 68 61  **           tha
20420 6e 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  n a table column
20430 20 6f 72 20 69 66 20 61 20 6d 65 6d 6f 72 79 20   or if a memory 
20440 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75  allocation failu
20450 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  re.**           
20460 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 65 6e  occurs during en
20470 63 6f 64 69 6e 67 20 63 6f 6e 76 65 72 73 69 6f  coding conversio
20480 6e 73 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20  ns, then.**     
20490 20 20 20 20 20 20 63 61 6c 6c 73 20 74 6f 20 5b        calls to [
204a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
204b0 65 63 6c 74 79 70 65 28 53 2c 4e 29 5d 20 6f 72  ecltype(S,N)] or
204c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 73  .**           [s
204d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65  qlite3_column_de
204e0 63 6c 74 79 70 65 31 36 28 53 2c 4e 29 5d 20 72  cltype16(S,N)] r
204f0 65 74 75 72 6e 20 4e 55 4c 4c 2e 0a 2a 2f 0a 63  eturn NULL..*/.c
20500 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
20510 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79  e3_column_declty
20520 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  pe(sqlite3_stmt*
20530 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  ,int);.const voi
20540 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
20550 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 73 71 6c  n_decltype16(sql
20560 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
20570 0a 0a 2f 2a 20 0a 2a 2a 20 43 41 50 49 33 52 45  ../* .** CAPI3RE
20580 46 3a 20 20 45 76 61 6c 75 61 74 65 20 41 6e 20  F:  Evaluate An 
20590 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 7b 46  SQL Statement {F
205a0 31 33 32 30 30 7d 0a 2a 2a 0a 2a 2a 20 41 66 74  13200}.**.** Aft
205b0 65 72 20 61 6e 20 5b 70 72 65 70 61 72 65 64 20  er an [prepared 
205c0 73 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 62  statement] has b
205d0 65 65 6e 20 70 72 65 70 61 72 65 64 20 77 69 74  een prepared wit
205e0 68 20 61 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 65  h a call.** to e
205f0 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70  ither [sqlite3_p
20600 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
20610 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
20620 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 6f 20 6f  16_v2()] or to o
20630 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 65 67  ne of.** the leg
20640 61 63 79 20 69 6e 74 65 72 66 61 63 65 73 20 5b  acy interfaces [
20650 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
20660 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
20670 72 65 70 61 72 65 31 36 28 29 5d 2c 0a 2a 2a 20  repare16()],.** 
20680 74 68 65 6e 20 74 68 69 73 20 66 75 6e 63 74 69  then this functi
20690 6f 6e 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  on must be calle
206a0 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69  d one or more ti
206b0 6d 65 73 20 74 6f 20 65 76 61 6c 75 61 74 65 20  mes to evaluate 
206c0 74 68 65 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  the .** statemen
206d0 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74  t..**.** The det
206e0 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65 68 61  ails of the beha
206f0 76 69 6f 72 20 6f 66 20 74 68 69 73 20 73 71 6c  vior of this sql
20700 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 74 65  ite3_step() inte
20710 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20  rface depend.** 
20720 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65 20 73  on whether the s
20730 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70 72 65  tatement was pre
20740 70 61 72 65 64 20 75 73 69 6e 67 20 74 68 65 20  pared using the 
20750 6e 65 77 65 72 20 22 76 32 22 20 69 6e 74 65 72  newer "v2" inter
20760 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  face.** [sqlite3
20770 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
20780 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nd [sqlite3_prep
20790 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74  are16_v2()] or t
207a0 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a  he older legacy.
207b0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 5b 73 71  ** interface [sq
207c0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
207d0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
207e0 65 70 61 72 65 31 36 28 29 5d 2e 20 20 54 68 65  epare16()].  The
207f0 20 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e   use of the.** n
20800 65 77 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  ew "v2" interfac
20810 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  e is recommended
20820 20 66 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 61   for new applica
20830 74 69 6f 6e 73 20 62 75 74 20 74 68 65 20 6c 65  tions but the le
20840 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63  gacy.** interfac
20850 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20  e will continue 
20860 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e  to be supported.
20870 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 6c 61  .**.** In the la
20880 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20  gacy interface, 
20890 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
208a0 20 77 69 6c 6c 20 62 65 20 65 69 74 68 65 72 20   will be either 
208b0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 20 0a  [SQLITE_BUSY], .
208c0 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  ** [SQLITE_DONE]
208d0 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20  , [SQLITE_ROW], 
208e0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20  [SQLITE_ERROR], 
208f0 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  or [SQLITE_MISUS
20900 45 5d 2e 0a 2a 2a 20 57 69 74 68 20 74 68 65 20  E]..** With the 
20910 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 20  "v2" interface, 
20920 61 6e 79 20 6f 66 20 74 68 65 20 6f 74 68 65 72  any of the other
20930 20 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 72 65   [SQLITE_OK | re
20940 73 75 6c 74 20 63 6f 64 65 5d 0a 2a 2a 20 6f 72  sult code].** or
20950 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52   [SQLITE_IOERR_R
20960 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64 20 72  EAD | extended r
20970 65 73 75 6c 74 20 63 6f 64 65 5d 20 6d 69 67 68  esult code] migh
20980 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73  t be returned as
20990 0a 2a 2a 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20  .** well..**.** 
209a0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65  [SQLITE_BUSY] me
209b0 61 6e 73 20 74 68 61 74 20 74 68 65 20 64 61 74  ans that the dat
209c0 61 62 61 73 65 20 65 6e 67 69 6e 65 20 77 61 73  abase engine was
209d0 20 75 6e 61 62 6c 65 20 74 6f 20 61 63 71 75 69   unable to acqui
209e0 72 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  re the.** databa
209f0 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64  se locks it need
20a00 73 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e  s to do its job.
20a10 20 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65    If the stateme
20a20 6e 74 20 69 73 20 61 20 43 4f 4d 4d 49 54 0a 2a  nt is a COMMIT.*
20a30 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f 75 74 73  * or occurs outs
20a40 69 64 65 20 6f 66 20 61 6e 20 65 78 70 6c 69 63  ide of an explic
20a50 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20  it transaction, 
20a60 74 68 65 6e 20 79 6f 75 20 63 61 6e 20 72 65 74  then you can ret
20a70 72 79 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d  ry the.** statem
20a80 65 6e 74 2e 20 20 49 66 20 74 68 65 20 73 74 61  ent.  If the sta
20a90 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61 20  tement is not a 
20aa0 43 4f 4d 4d 49 54 20 61 6e 64 20 6f 63 63 75 72  COMMIT and occur
20ab0 73 20 77 69 74 68 69 6e 20 61 0a 2a 2a 20 65 78  s within a.** ex
20ac0 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69  plicit transacti
20ad0 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73 68 6f 75  on then you shou
20ae0 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20  ld rollback the 
20af0 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f  transaction befo
20b00 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67  re.** continuing
20b10 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ..**.** [SQLITE_
20b20 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61 74  DONE] means that
20b30 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68   the statement h
20b40 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63  as finished exec
20b50 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73  uting.** success
20b60 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f  fully.  sqlite3_
20b70 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f  step() should no
20b80 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69  t be called agai
20b90 6e 20 6f 6e 20 74 68 69 73 20 76 69 72 74 75 61  n on this virtua
20ba0 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69 74  l.** machine wit
20bb0 68 6f 75 74 20 66 69 72 73 74 20 63 61 6c 6c 69  hout first calli
20bc0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
20bd0 74 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68  t()] to reset th
20be0 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63  e virtual.** mac
20bf0 68 69 6e 65 20 62 61 63 6b 20 74 6f 20 69 74 73  hine back to its
20c00 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2e 0a   initial state..
20c10 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c  **.** If the SQL
20c20 20 73 74 61 74 65 6d 65 6e 74 20 62 65 69 6e 67   statement being
20c30 20 65 78 65 63 75 74 65 64 20 72 65 74 75 72 6e   executed return
20c40 73 20 61 6e 79 20 64 61 74 61 2c 20 74 68 65 6e  s any data, then
20c50 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 52 4f 57   .** [SQLITE_ROW
20c60 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 65 61  ] is returned ea
20c70 63 68 20 74 69 6d 65 20 61 20 6e 65 77 20 72 6f  ch time a new ro
20c80 77 20 6f 66 20 64 61 74 61 20 69 73 20 72 65 61  w of data is rea
20c90 64 79 0a 2a 2a 20 66 6f 72 20 70 72 6f 63 65 73  dy.** for proces
20ca0 73 69 6e 67 20 62 79 20 74 68 65 20 63 61 6c 6c  sing by the call
20cb0 65 72 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6d  er. The values m
20cc0 61 79 20 62 65 20 61 63 63 65 73 73 65 64 20 75  ay be accessed u
20cd0 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  sing.** the [sql
20ce0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20  ite3_column_int 
20cf0 7c 20 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20  | column access 
20d00 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73  functions]..** s
20d10 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 73  qlite3_step() is
20d20 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f   called again to
20d30 20 72 65 74 72 69 65 76 65 20 74 68 65 20 6e 65   retrieve the ne
20d40 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a  xt row of data..
20d50 2a 2a 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45  ** .** [SQLITE_E
20d60 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 74  RROR] means that
20d70 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f   a run-time erro
20d80 72 20 28 73 75 63 68 20 61 73 20 61 20 63 6f 6e  r (such as a con
20d90 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61  straint.** viola
20da0 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 72  tion) has occurr
20db0 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65  ed.  sqlite3_ste
20dc0 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62  p() should not b
20dd0 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f  e called again o
20de0 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72  n.** the VM. Mor
20df0 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61  e information ma
20e00 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20 63 61  y be found by ca
20e10 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65  lling [sqlite3_e
20e20 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 57 69 74  rrmsg()]..** Wit
20e30 68 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74  h the legacy int
20e40 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 73  erface, a more s
20e50 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f  pecific error co
20e60 64 65 20 28 65 78 61 6d 70 6c 65 3a 0a 2a 2a 20  de (example:.** 
20e70 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50  [SQLITE_INTERRUP
20e80 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45  T], [SQLITE_SCHE
20e90 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52  MA], [SQLITE_COR
20ea0 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f  RUPT], and so fo
20eb0 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f  rth).** can be o
20ec0 62 74 61 69 6e 65 64 20 62 79 20 63 61 6c 6c 69  btained by calli
20ed0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
20ee0 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b  t()] on the.** [
20ef0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
20f00 6e 74 5d 2e 20 20 49 6e 20 74 68 65 20 22 76 32  nt].  In the "v2
20f10 22 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20  " interface,.** 
20f20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69  the more specifi
20f30 63 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20  c error code is 
20f40 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c  returned directl
20f50 79 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65  y by sqlite3_ste
20f60 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49  p()..**.** [SQLI
20f70 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73  TE_MISUSE] means
20f80 20 74 68 61 74 20 74 68 65 20 74 68 69 73 20 72   that the this r
20f90 6f 75 74 69 6e 65 20 77 61 73 20 63 61 6c 6c 65  outine was calle
20fa0 64 20 69 6e 61 70 70 72 6f 70 72 69 61 74 65 6c  d inappropriatel
20fb0 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20 69 74  y..** Perhaps it
20fc0 20 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61   was called on a
20fd0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
20fe0 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 0a 2a  ment] that has.*
20ff0 2a 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20 5b  * already been [
21000 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
21010 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72   | finalized] or
21020 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68 61 64   on one that had
21030 20 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20   .** previously 
21040 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45  returned [SQLITE
21050 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49  _ERROR] or [SQLI
21060 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74  TE_DONE].  Or it
21070 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65   could.** be the
21080 20 63 61 73 65 20 74 68 61 74 20 74 68 65 20 73   case that the s
21090 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
210a0 6e 65 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67  nection is being
210b0 20 75 73 65 64 20 62 79 20 74 77 6f 20 6f 72 0a   used by two or.
210c0 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20  ** more threads 
210d0 61 74 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65  at the same mome
210e0 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a  nt in time..**.*
210f0 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72  * <b>Goofy Inter
21100 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 0a  face Alert:</b>.
21110 2a 2a 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79  ** In the legacy
21120 20 69 6e 74 65 72 66 61 63 65 2c 20 0a 2a 2a 20   interface, .** 
21130 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70  the sqlite3_step
21140 28 29 20 41 50 49 20 61 6c 77 61 79 73 20 72 65  () API always re
21150 74 75 72 6e 73 20 61 20 67 65 6e 65 72 69 63 20  turns a generic 
21160 65 72 72 6f 72 20 63 6f 64 65 2c 0a 2a 2a 20 5b  error code,.** [
21170 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66  SQLITE_ERROR], f
21180 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 65 72 72  ollowing any err
21190 6f 72 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  or other than [S
211a0 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 61  QLITE_BUSY].** a
211b0 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  nd [SQLITE_MISUS
211c0 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20 63 61  E].  You must ca
211d0 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ll [sqlite3_rese
211e0 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  t()] or.** [sqli
211f0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
21200 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64  in order to find
21210 20 6f 6e 65 20 6f 66 20 74 68 65 20 73 70 65 63   one of the spec
21220 69 66 69 63 0a 2a 2a 20 5b 65 72 72 6f 72 20 63  ific.** [error c
21230 6f 64 65 73 5d 20 74 68 61 74 20 62 65 74 74 65  odes] that bette
21240 72 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20  r describes the 
21250 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d  error..** We adm
21260 69 74 20 74 68 61 74 20 74 68 69 73 20 69 73 20  it that this is 
21270 61 20 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20  a goofy design. 
21280 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 68 61 73   The problem has
21290 20 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77   been fixed.** w
212a0 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74  ith the "v2" int
212b0 65 72 66 61 63 65 2e 20 20 49 66 20 79 6f 75 20  erface.  If you 
212c0 70 72 65 70 61 72 65 20 61 6c 6c 20 6f 66 20 79  prepare all of y
212d0 6f 75 72 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  our SQL statemen
212e0 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74 68  ts.** using eith
212f0 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  er [sqlite3_prep
21300 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71  are_v2()] or [sq
21310 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
21320 76 32 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a  v2()] instead.**
21330 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 20 5b   of the legacy [
21340 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
21350 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
21360 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68  prepare16()], th
21370 65 6e 20 74 68 65 20 0a 2a 2a 20 6d 6f 72 65 20  en the .** more 
21380 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20  specific [error 
21390 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75 72  codes] are retur
213a0 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20  ned directly.** 
213b0 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  by sqlite3_step(
213c0 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74  ).  The use of t
213d0 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
213e0 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  e is recommended
213f0 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
21400 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 32 30  TS:.**.** {F1320
21410 32 7d 20 20 49 66 20 5b 70 72 65 70 61 72 65 64  2}  If [prepared
21420 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 73   statement] S is
21430 20 72 65 61 64 79 20 74 6f 20 62 65 0a 2a 2a 20   ready to be.** 
21440 20 20 20 20 20 20 20 20 20 20 72 75 6e 2c 20 74            run, t
21450 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  hen [sqlite3_ste
21460 70 28 53 29 5d 20 61 64 76 61 6e 63 65 73 20 74  p(S)] advances t
21470 68 61 74 20 70 72 65 70 61 72 65 64 20 73 74 61  hat prepared sta
21480 74 65 6d 65 6e 74 0a 2a 2a 20 20 20 20 20 20 20  tement.**       
21490 20 20 20 20 75 6e 74 69 6c 20 74 6f 20 63 6f 6d      until to com
214a0 70 6c 65 74 69 6f 6e 20 6f 72 20 75 6e 74 69 6c  pletion or until
214b0 20 69 74 20 69 73 20 72 65 61 64 79 20 74 6f 20   it is ready to 
214c0 72 65 74 75 72 6e 20 61 6e 6f 74 68 65 72 0a 2a  return another.*
214d0 2a 20 20 20 20 20 20 20 20 20 20 20 72 6f 77 20  *           row 
214e0 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
214f0 74 20 6f 72 20 61 6e 20 69 6e 74 65 72 72 75 70  t or an interrup
21500 74 20 6f 72 20 72 75 6e 2d 74 69 6d 65 20 65 72  t or run-time er
21510 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a  ror occurs..**.*
21520 2a 20 7b 46 31 35 33 30 34 7d 20 20 57 68 65 6e  * {F15304}  When
21530 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69   a call to [sqli
21540 74 65 33 5f 73 74 65 70 28 53 29 5d 20 63 61 75  te3_step(S)] cau
21550 73 65 73 20 74 68 65 20 0a 2a 2a 20 20 20 20 20  ses the .**     
21560 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20        [prepared 
21570 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 74 6f 20  statement] S to 
21580 72 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f  run to completio
21590 6e 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  n,.**           
215a0 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  the function ret
215b0 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  urns [SQLITE_DON
215c0 45 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 33 30  E]..**.** {F1530
215d0 36 7d 20 20 57 68 65 6e 20 61 20 63 61 6c 6c 20  6}  When a call 
215e0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
215f0 28 53 29 5d 20 73 74 6f 70 73 20 62 65 63 61 75  (S)] stops becau
21600 73 65 20 69 74 20 69 73 20 72 65 61 64 79 0a 2a  se it is ready.*
21610 2a 20 20 20 20 20 20 20 20 20 20 20 74 6f 20 72  *           to r
21620 65 74 75 72 6e 20 61 6e 6f 74 68 65 72 20 72 6f  eturn another ro
21630 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  w of the result 
21640 73 65 74 2c 20 69 74 20 72 65 74 75 72 6e 73 0a  set, it returns.
21650 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 53 51  **           [SQ
21660 4c 49 54 45 5f 52 4f 57 5d 2e 0a 2a 2a 0a 2a 2a  LITE_ROW]..**.**
21670 20 7b 46 31 35 33 30 38 7d 20 20 49 66 20 61 20   {F15308}  If a 
21680 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
21690 5f 73 74 65 70 28 53 29 5d 20 65 6e 63 6f 75 6e  _step(S)] encoun
216a0 74 65 72 73 20 61 6e 0a 2a 2a 20 20 20 20 20 20  ters an.**      
216b0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 69 6e       [sqlite3_in
216c0 74 65 72 72 75 70 74 7c 69 6e 74 65 72 72 75 70  terrupt|interrup
216d0 74 5d 20 6f 72 20 61 20 72 75 6e 2d 74 69 6d 65  t] or a run-time
216e0 20 65 72 72 6f 72 2c 0a 2a 2a 20 20 20 20 20 20   error,.**      
216f0 20 20 20 20 20 69 74 20 72 65 74 75 72 6e 73 20       it returns 
21700 61 6e 20 61 70 70 72 6f 70 72 61 69 74 65 20 65  an appropraite e
21710 72 72 6f 72 20 63 6f 64 65 20 74 68 61 74 20 69  rror code that i
21720 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 0a 2a 2a 20  s not one of.** 
21730 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54            [SQLIT
21740 45 5f 4f 4b 5d 2c 20 5b 53 51 4c 49 54 45 5f 52  E_OK], [SQLITE_R
21750 4f 57 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OW], or [SQLITE_
21760 44 4f 4e 45 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  DONE]..**.** {F1
21770 35 33 31 30 7d 20 20 49 66 20 61 6e 20 5b 73 71  5310}  If an [sq
21780 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 7c  lite3_interrupt|
21790 69 6e 74 65 72 72 75 70 74 5d 20 6f 72 20 72 75  interrupt] or ru
217a0 6e 2d 74 69 6d 65 20 65 72 72 6f 72 0a 2a 2a 20  n-time error.** 
217b0 20 20 20 20 20 20 20 20 20 20 6f 63 63 75 72 73            occurs
217c0 20 64 75 72 69 6e 67 20 61 20 63 61 6c 6c 20 74   during a call t
217d0 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
217e0 53 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  S)].**          
217f0 20 66 6f 72 20 61 20 5b 70 72 65 70 61 72 65 64   for a [prepared
21800 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 63 72   statement] S cr
21810 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20  eated using.**  
21820 20 20 20 20 20 20 20 20 20 6c 65 67 61 63 79 20           legacy 
21830 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69  interfaces [sqli
21840 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
21850 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b  r.**           [
21860 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
21870 36 28 29 5d 20 74 68 65 6e 20 74 68 65 20 66 75  6()] then the fu
21880 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 65  nction returns e
21890 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  ither.**        
218a0 20 20 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52     [SQLITE_ERROR
218b0 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  ], [SQLITE_BUSY]
218c0 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53  , or [SQLITE_MIS
218d0 55 53 45 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  USE]..*/.int sql
218e0 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69 74 65  ite3_step(sqlite
218f0 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  3_stmt*);../*.**
21900 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65   CAPI3REF: Numbe
21910 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
21920 61 20 72 65 73 75 6c 74 20 73 65 74 20 7b 46 31  a result set {F1
21930 33 37 37 30 7d 0a 2a 2a 0a 2a 2a 20 52 65 74 75  3770}.**.** Retu
21940 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  rn the number of
21950 20 76 61 6c 75 65 73 20 69 6e 20 74 68 65 20 63   values in the c
21960 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68  urrent row of th
21970 65 20 72 65 73 75 6c 74 20 73 65 74 2e 0a 2a 2a  e result set..**
21980 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
21990 2a 2a 0a 2a 2a 20 7b 46 31 33 37 37 31 7d 20 20  **.** {F13771}  
219a0 41 66 74 65 72 20 61 20 63 61 6c 6c 20 74 6f 20  After a call to 
219b0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
219c0 5d 20 74 68 61 74 20 72 65 74 75 72 6e 73 0a 2a  ] that returns.*
219d0 2a 20 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c  *           [SQL
219e0 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 5b 73  ITE_ROW], the [s
219f0 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
21a00 74 28 53 29 5d 20 72 6f 75 74 69 6e 65 0a 2a 2a  t(S)] routine.**
21a10 20 20 20 20 20 20 20 20 20 20 20 77 69 6c 6c 20             will 
21a20 72 65 74 75 72 6e 20 74 68 65 20 73 61 6d 65 20  return the same 
21a30 76 61 6c 75 65 20 61 73 20 74 68 65 0a 2a 2a 20  value as the.** 
21a40 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
21a50 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28  e3_column_count(
21a60 53 29 5d 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  S)] function..**
21a70 0a 2a 2a 20 7b 46 31 33 37 37 32 7d 20 20 41 66  .** {F13772}  Af
21a80 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ter [sqlite3_ste
21a90 70 28 53 29 5d 20 68 61 73 20 72 65 74 75 72 6e  p(S)] has return
21aa0 65 64 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68  ed any value oth
21ab0 65 72 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20  er than.**      
21ac0 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 52 4f 57       [SQLITE_ROW
21ad0 5d 20 6f 72 20 62 65 66 6f 72 65 20 5b 73 71 6c  ] or before [sql
21ae0 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61  ite3_step(S)] ha
21af0 73 20 62 65 65 6e 20 0a 2a 2a 20 20 20 20 20 20  s been .**      
21b00 20 20 20 20 20 63 61 6c 6c 65 64 20 6f 6e 20 74       called on t
21b10 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
21b20 74 65 6d 65 6e 74 5d 20 66 6f 72 0a 2a 2a 20 20  tement] for.**  
21b30 20 20 20 20 20 20 20 20 20 74 68 65 20 66 69 72           the fir
21b40 73 74 20 74 69 6d 65 20 73 69 6e 63 65 20 69 74  st time since it
21b50 20 77 61 73 20 5b 73 71 6c 69 74 65 33 5f 70 72   was [sqlite3_pr
21b60 65 70 61 72 65 7c 70 72 65 70 61 72 65 64 5d 0a  epare|prepared].
21b70 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6f 72 20  **           or 
21b80 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 7c 72  [sqlite3_reset|r
21b90 65 73 65 74 5d 2c 20 74 68 65 20 5b 73 71 6c 69  eset], the [sqli
21ba0 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 53  te3_data_count(S
21bb0 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  )].**           
21bc0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
21bd0 7a 65 72 6f 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  zero..*/.int sql
21be0 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
21bf0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
21c00 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
21c10 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74  I3REF: Fundament
21c20 61 6c 20 44 61 74 61 74 79 70 65 73 20 7b 46 31  al Datatypes {F1
21c30 30 32 36 35 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  0265}.** KEYWORD
21c40 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a  S: SQLITE_TEXT.*
21c50 2a 0a 2a 2a 20 7b 46 31 30 32 36 36 7d 45 76 65  *.** {F10266}Eve
21c60 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51 4c 69  ry value in SQLi
21c70 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 66 69  te has one of fi
21c80 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64  ve fundamental d
21c90 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20  atatypes:.**.** 
21ca0 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d  <ul>.** <li> 64-
21cb0 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
21cc0 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69  er.** <li> 64-bi
21cd0 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e 67 20  t IEEE floating 
21ce0 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20  point number.** 
21cf0 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c  <li> string.** <
21d00 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e  li> BLOB.** <li>
21d10 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 20 7b   NULL.** </ul> {
21d20 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  END}.**.** These
21d30 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 63   constants are c
21d40 6f 64 65 73 20 66 6f 72 20 65 61 63 68 20 6f 66  odes for each of
21d50 20 74 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a   those types..**
21d60 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68  .** Note that th
21d70 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 63 6f  e SQLITE_TEXT co
21d80 6e 73 74 61 6e 74 20 77 61 73 20 61 6c 73 6f 20  nstant was also 
21d90 75 73 65 64 20 69 6e 20 53 51 4c 69 74 65 20 76  used in SQLite v
21da0 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20  ersion 2.** for 
21db0 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66  a completely dif
21dc0 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20  ferent meaning. 
21dd0 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20 6c   Software that l
21de0 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 6f 74  inks against bot
21df0 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73  h.** SQLite vers
21e00 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 65  ion 2 and SQLite
21e10 20 76 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c   version 3 shoul
21e20 64 20 75 73 65 20 53 51 4c 49 54 45 33 5f 54 45  d use SQLITE3_TE
21e30 58 54 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45  XT not.** SQLITE
21e40 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e  _TEXT..*/.#defin
21e50 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52  e SQLITE_INTEGER
21e60 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
21e70 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 64  TE_FLOAT    2.#d
21e80 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f  efine SQLITE_BLO
21e90 42 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20  B     4.#define 
21ea0 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20  SQLITE_NULL     
21eb0 35 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  5.#ifdef SQLITE_
21ec0 54 45 58 54 0a 23 20 75 6e 64 65 66 20 53 51 4c  TEXT.# undef SQL
21ed0 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23  ITE_TEXT.#else.#
21ee0 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54   define SQLITE_T
21ef0 45 58 54 20 20 20 20 20 33 0a 23 65 6e 64 69 66  EXT     3.#endif
21f00 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33  .#define SQLITE3
21f10 5f 54 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a  _TEXT     3../*.
21f20 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73  ** CAPI3REF: Res
21f30 75 6c 74 73 20 56 61 6c 75 65 73 20 46 72 6f 6d  ults Values From
21f40 20 41 20 51 75 65 72 79 20 7b 46 31 33 38 30 30   A Query {F13800
21f50 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  }.**.** These ro
21f60 75 74 69 6e 65 73 20 66 6f 72 6d 20 74 68 65 20  utines form the 
21f70 22 72 65 73 75 6c 74 20 73 65 74 20 71 75 65 72  "result set quer
21f80 79 22 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  y" interface..**
21f90 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
21fa0 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d  es return inform
21fb0 61 74 69 6f 6e 20 61 62 6f 75 74 0a 2a 2a 20 61  ation about.** a
21fc0 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f   single column o
21fd0 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 65  f the current re
21fe0 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 75  sult row of a qu
21ff0 65 72 79 2e 20 20 49 6e 20 65 76 65 72 79 0a 2a  ery.  In every.*
22000 2a 20 63 61 73 65 20 74 68 65 20 66 69 72 73 74  * case the first
22010 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70   argument is a p
22020 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 0a 2a  ointer to the .*
22030 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
22040 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 20 62  ement] that is b
22050 65 69 6e 67 0a 2a 2a 20 65 76 61 6c 75 61 74 65  eing.** evaluate
22060 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  d (the [sqlite3_
22070 73 74 6d 74 2a 5d 20 74 68 61 74 20 77 61 73 20  stmt*] that was 
22080 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 0a 2a  returned from .*
22090 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
220a0 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20  re_v2()] or one 
220b0 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74 73 29  of its variants)
220c0 20 61 6e 64 0a 2a 2a 20 74 68 65 20 73 65 63 6f   and.** the seco
220d0 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  nd argument is t
220e0 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20  he index of the 
220f0 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63 68  column for which
22100 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 0a 2a 2a   information .**
22110 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72   should be retur
22120 6e 65 64 2e 20 20 54 68 65 20 6c 65 66 74 2d 6d  ned.  The left-m
22130 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  ost column of th
22140 65 20 72 65 73 75 6c 74 20 73 65 74 0a 2a 2a 20  e result set.** 
22150 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20  has an index of 
22160 30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  0..**.** If the 
22170 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 73  SQL statement is
22180 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 70   not currently p
22190 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69 64 20  oint to a valid 
221a0 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a  row, or if the.*
221b0 2a 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 6e 64  * the column ind
221c0 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e  ex is out of ran
221d0 67 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20 69  ge, the result i
221e0 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 0a 2a 2a  s undefined. .**
221f0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
22200 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c  may only be call
22210 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 74  ed when the most
22220 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a   recent call to.
22230 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
22240 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64  ()] has returned
22250 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e   [SQLITE_ROW] an
22260 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71  d neither.** [sq
22270 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6e  lite3_reset()] n
22280 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
22290 6c 69 7a 65 28 29 5d 20 68 61 73 20 62 65 65 6e  lize()] has been
222a0 20 63 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74   call subsequent
222b0 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66  ly..** If any of
222c0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
222d0 61 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72  are called after
222e0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
222f0 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
22300 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72  3_finalize()] or
22310 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f   after [sqlite3_
22320 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75  step()] has retu
22330 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e  rned.** somethin
22340 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  g other than [SQ
22350 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72  LITE_ROW], the r
22360 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
22370 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c  ined..** If [sql
22380 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20  ite3_step()] or 
22390 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
223a0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69  ] or [sqlite3_fi
223b0 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65  nalize()].** are
223c0 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64   called from a d
223d0 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 20  ifferent thread 
223e0 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 65  while any of the
223f0 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61  se routines.** a
22400 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e  re pending, then
22410 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
22420 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 0a 2a 2a   undefined.  .**
22430 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
22440 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f  column_type() ro
22450 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 0a 2a  utine returns .*
22460 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  * [SQLITE_INTEGE
22470 52 20 7c 20 64 61 74 61 74 79 70 65 20 63 6f 64  R | datatype cod
22480 65 5d 20 66 6f 72 20 74 68 65 20 69 6e 69 74 69  e] for the initi
22490 61 6c 20 64 61 74 61 20 74 79 70 65 0a 2a 2a 20  al data type.** 
224a0 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 63 6f  of the result co
224b0 6c 75 6d 6e 2e 20 20 54 68 65 20 72 65 74 75 72  lumn.  The retur
224c0 6e 65 64 20 76 61 6c 75 65 20 69 73 20 6f 6e 65  ned value is one
224d0 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45   of [SQLITE_INTE
224e0 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  GER],.** [SQLITE
224f0 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45  _FLOAT], [SQLITE
22500 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f  _TEXT], [SQLITE_
22510 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  BLOB], or [SQLIT
22520 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61  E_NULL].  The va
22530 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  lue.** returned 
22540 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
22550 6e 5f 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79  n_type() is only
22560 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e   meaningful if n
22570 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72  o type.** conver
22580 73 69 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 72  sions have occur
22590 72 65 64 20 61 73 20 64 65 73 63 72 69 62 65 64  red as described
225a0 20 62 65 6c 6f 77 2e 20 20 41 66 74 65 72 20 61   below.  After a
225b0 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
225c0 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 72  ,.** the value r
225d0 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
225e0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
225f0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20   is undefined.  
22600 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f  Future.** versio
22610 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79  ns of SQLite may
22620 20 63 68 61 6e 67 65 20 74 68 65 20 62 65 68 61   change the beha
22630 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  vior of sqlite3_
22640 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a  column_type().**
22650 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70   following a typ
22660 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a  e conversion..**
22670 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 73 75 6c  .** If the resul
22680 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55  t is a BLOB or U
22690 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65 6e  TF-8 string then
226a0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c   the sqlite3_col
226b0 75 6d 6e 5f 62 79 74 65 73 28 29 20 0a 2a 2a 20  umn_bytes() .** 
226c0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
226d0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
226e0 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42  tes in that BLOB
226f0 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 49   or string..** I
22700 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
22710 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2c  a UTF-16 string,
22720 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
22730 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e  lumn_bytes() con
22740 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72  verts.** the str
22750 69 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e 64  ing to UTF-8 and
22760 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68   then returns th
22770 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
22780 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 73  s..** If the res
22790 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63  ult is a numeric
227a0 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69   value then sqli
227b0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
227c0 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69  () uses.** [sqli
227d0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20  te3_snprintf()] 
227e0 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20  to convert that 
227f0 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38  value to a UTF-8
22800 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75   string and retu
22810 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  rns.** the numbe
22820 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
22830 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 54 68  at string..** Th
22840 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
22850 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64   does not includ
22860 65 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69  e the zero termi
22870 6e 61 74 6f 72 20 61 74 20 74 68 65 20 65 6e 64  nator at the end
22880 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e  .** of the strin
22890 67 2e 20 20 46 6f 72 20 63 6c 61 72 69 74 79 3a  g.  For clarity:
228a0 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
228b0 6e 65 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ned is the numbe
228c0 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e  r of.** bytes in
228d0 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74   the string, not
228e0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
228f0 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a  haracters..**.**
22900 20 53 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65   Strings returne
22910 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
22920 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 20 73  umn_text() and s
22930 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
22940 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20  xt16(),.** even 
22950 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c 20 61  empty strings, a
22960 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f 20 74  re always zero t
22970 65 72 6d 69 6e 61 74 65 64 2e 20 20 54 68 65 20  erminated.  The 
22980 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20  return.** value 
22990 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c  from sqlite3_col
229a0 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61  umn_blob() for a
229b0 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 62 6c 6f   zero-length blo
229c0 62 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 72  b is an arbitrar
229d0 79 0a 2a 2a 20 70 6f 69 6e 74 65 72 2c 20 70 6f  y.** pointer, po
229e0 73 73 69 62 6c 79 20 65 76 65 6e 20 61 20 4e 55  ssibly even a NU
229f0 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
22a00 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  * The sqlite3_co
22a10 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 72  lumn_bytes16() r
22a20 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61  outine is simila
22a30 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r to sqlite3_col
22a40 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 62  umn_bytes().** b
22a50 75 74 20 6c 65 61 76 65 73 20 74 68 65 20 72 65  ut leaves the re
22a60 73 75 6c 74 20 69 6e 20 55 54 46 2d 31 36 20 69  sult in UTF-16 i
22a70 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  n native byte or
22a80 64 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 55  der instead of U
22a90 54 46 2d 38 2e 20 20 0a 2a 2a 20 54 68 65 20 7a  TF-8.  .** The z
22aa0 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69  ero terminator i
22ab0 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 64 20 69  s not included i
22ac0 6e 20 74 68 69 73 20 63 6f 75 6e 74 2e 0a 2a 2a  n this count..**
22ad0 0a 2a 2a 20 54 68 65 20 6f 62 6a 65 63 74 20 72  .** The object r
22ae0 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
22af0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
22b00 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e  ()] is an.** [un
22b10 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
22b20 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e  3_value] object.
22b30 20 20 41 6e 20 75 6e 70 72 6f 74 65 63 74 65 64    An unprotected
22b40 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
22b50 62 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c  bject.** may onl
22b60 79 20 62 65 20 75 73 65 64 20 77 69 74 68 20 5b  y be used with [
22b70 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c  sqlite3_bind_val
22b80 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ue()] and [sqlit
22b90 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
22ba0 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75  )]..** If the [u
22bb0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
22bc0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
22bd0 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
22be0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
22bf0 76 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65 64  value()] is used
22c00 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77 61   in any other wa
22c10 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c  y, including cal
22c20 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65  ls.** to routine
22c30 73 20 6c 69 6b 65 20 0a 2a 2a 20 5b 73 71 6c 69  s like .** [sqli
22c40 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d  te3_value_int()]
22c50 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  , [sqlite3_value
22c60 5f 74 65 78 74 28 29 5d 2c 20 6f 72 20 5b 73 71  _text()], or [sq
22c70 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
22c80 73 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  s()],.** then th
22c90 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e  e behavior is un
22ca0 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  defined..**.** T
22cb0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 74  hese routines at
22cc0 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 74  tempt to convert
22cd0 20 74 68 65 20 76 61 6c 75 65 20 77 68 65 72 65   the value where
22ce0 20 61 70 70 72 6f 70 72 69 61 74 65 2e 20 20 46   appropriate.  F
22cf0 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69  or.** example, i
22d00 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72  f the internal r
22d10 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73  epresentation is
22d20 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78   FLOAT and a tex
22d30 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72  t result.** is r
22d40 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74  equested, [sqlit
22d50 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69  e3_snprintf()] i
22d60 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c  s used internall
22d70 79 20 74 6f 20 64 6f 20 74 68 65 20 63 6f 6e 76  y to do the conv
22d80 65 72 73 69 6f 6e 0a 2a 2a 20 61 75 74 6f 6d 61  ersion.** automa
22d90 74 69 63 61 6c 6c 79 2e 20 20 54 68 65 20 66 6f  tically.  The fo
22da0 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 65  llowing table de
22db0 74 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 72  tails the conver
22dc0 73 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 61 72  sions that.** ar
22dd0 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a  e applied:.**.**
22de0 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a   <blockquote>.**
22df0 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22   <table border="
22e00 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20  1">.** <tr><th> 
22e10 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65  Internal<br>Type
22e20 20 3c 74 68 3e 20 52 65 71 75 65 73 74 65 64 3c   <th> Requested<
22e30 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 43 6f  br>Type <th>  Co
22e40 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c  nversion.**.** <
22e50 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20  tr><td>  NULL   
22e60 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
22e70 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30  <td> Result is 0
22e80 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
22e90 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41  LL    <td>  FLOA
22ea0 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  T    <td> Result
22eb0 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c   is 0.0.** <tr><
22ec0 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
22ed0 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
22ee0 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20   Result is NULL 
22ef0 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c  pointer.** <tr><
22f00 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
22f10 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  >   BLOB    <td>
22f20 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20   Result is NULL 
22f30 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c  pointer.** <tr><
22f40 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64  td> INTEGER  <td
22f50 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
22f60 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e   Convert from in
22f70 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a  teger to float.*
22f80 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47  * <tr><td> INTEG
22f90 45 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20  ER  <td>   TEXT 
22fa0 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65     <td> ASCII re
22fb0 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69  ndering of the i
22fc0 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  nteger.** <tr><t
22fd0 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e  d> INTEGER  <td>
22fe0 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
22ff0 53 61 6d 65 20 61 73 20 66 6f 72 20 49 4e 54 45  Same as for INTE
23000 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72  GER->TEXT.** <tr
23010 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c  ><td>  FLOAT   <
23020 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
23030 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20  d> Convert from 
23040 66 6c 6f 61 74 20 74 6f 20 69 6e 74 65 67 65 72  float to integer
23050 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c  .** <tr><td>  FL
23060 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58  OAT   <td>   TEX
23070 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20  T    <td> ASCII 
23080 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65  rendering of the
23090 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74   float.** <tr><t
230a0 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e  d>  FLOAT   <td>
230b0 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
230c0 53 61 6d 65 20 61 73 20 46 4c 4f 41 54 2d 3e 54  Same as FLOAT->T
230d0 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  EXT.** <tr><td> 
230e0 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 49 4e   TEXT    <td> IN
230f0 54 45 47 45 52 20 20 20 3c 74 64 3e 20 55 73 65  TEGER   <td> Use
23100 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c   atoi().** <tr><
23110 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64  td>  TEXT    <td
23120 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
23130 20 55 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c   Use atof().** <
23140 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20  tr><td>  TEXT   
23150 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20   <td>   BLOB    
23160 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a  <td> No change.*
23170 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42  * <tr><td>  BLOB
23180 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52      <td> INTEGER
23190 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20     <td> Convert 
231a0 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73 65  to TEXT then use
231b0 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c   atoi().** <tr><
231c0 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  td>  BLOB    <td
231d0 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
231e0 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54   Convert to TEXT
231f0 20 74 68 65 6e 20 75 73 65 20 61 74 6f 66 28 29   then use atof()
23200 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c  .** <tr><td>  BL
23210 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58  OB    <td>   TEX
23220 54 20 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20  T    <td> Add a 
23230 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20  zero terminator 
23240 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74  if needed.** </t
23250 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b  able>.** </block
23260 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  quote>.**.** The
23270 20 74 61 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b   table above mak
23280 65 73 20 72 65 66 65 72 65 6e 63 65 20 74 6f 20  es reference to 
23290 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
232a0 72 79 20 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f  ry functions ato
232b0 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28  i().** and atof(
232c0 29 2e 20 20 53 51 4c 69 74 65 20 64 6f 65 73 20  ).  SQLite does 
232d0 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73 65 20 74  not really use t
232e0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20  hese functions. 
232f0 20 49 74 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f   It has its.** o
23300 6e 20 65 71 75 61 76 61 6c 65 6e 74 20 69 6e 74  n equavalent int
23310 65 72 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e 20  ernal routines. 
23320 20 54 68 65 20 61 74 6f 69 28 29 20 61 6e 64 20   The atoi() and 
23330 61 74 6f 66 28 29 20 6e 61 6d 65 73 20 61 72 65  atof() names are
23340 0a 2a 2a 20 75 73 65 64 20 69 6e 20 74 68 65 20  .** used in the 
23350 74 61 62 6c 65 20 66 6f 72 20 62 72 65 76 69 74  table for brevit
23360 79 20 61 6e 64 20 62 65 63 61 75 73 65 20 74 68  y and because th
23370 65 79 20 61 72 65 20 66 61 6d 69 6c 69 61 72 20  ey are familiar 
23380 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 6f  to most.** C pro
23390 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  grammers..**.** 
233a0 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20 74  Note that when t
233b0 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20  ype conversions 
233c0 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 20  occur, pointers 
233d0 72 65 74 75 72 6e 65 64 20 62 79 20 70 72 69 6f  returned by prio
233e0 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71  r.** calls to sq
233f0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
23400 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  b(), sqlite3_col
23410 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f  umn_text(), and/
23420 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  or.** sqlite3_co
23430 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d 61  lumn_text16() ma
23440 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64  y be invalidated
23450 2e 20 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65  . .** Type conve
23460 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74  rsions and point
23470 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73  er invalidations
23480 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20   might occur.** 
23490 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  in the following
234a0 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75   cases:.**.** <u
234b0 6c 3e 0a 2a 2a 20 3c 6c 69 3e 3c 70 3e 20 20 54  l>.** <li><p>  T
234c0 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65  he initial conte
234d0 6e 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64  nt is a BLOB and
234e0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
234f0 74 65 78 74 28 29 20 0a 2a 2a 20 20 20 20 20 20  text() .**      
23500 20 20 20 20 6f 72 20 73 71 6c 69 74 65 33 5f 63      or sqlite3_c
23510 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69  olumn_text16() i
23520 73 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72  s called.  A zer
23530 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67  o-terminator mig
23540 68 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e  ht.**          n
23550 65 65 64 20 74 6f 20 62 65 20 61 64 64 65 64 20  eed to be added 
23560 74 6f 20 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f  to the string.</
23570 70 3e 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c  p></li>.**.** <l
23580 69 3e 3c 70 3e 20 20 54 68 65 20 69 6e 69 74 69  i><p>  The initi
23590 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54  al content is UT
235a0 46 2d 38 20 74 65 78 74 20 61 6e 64 20 73 71 6c  F-8 text and sql
235b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
235c0 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20  s16() or.**     
235d0 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c       sqlite3_col
235e0 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20  umn_text16() is 
235f0 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e  called.  The con
23600 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e  tent must be con
23610 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 20  verted.**       
23620 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 70     to UTF-16.</p
23630 3e 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  ></li>.**.** <li
23640 3e 3c 70 3e 20 20 54 68 65 20 69 6e 69 74 69 61  ><p>  The initia
23650 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46  l content is UTF
23660 2d 31 36 20 74 65 78 74 20 61 6e 64 20 73 71 6c  -16 text and sql
23670 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
23680 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20  s() or.**       
23690 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d     sqlite3_colum
236a0 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c 6c  n_text() is call
236b0 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74  ed.  The content
236c0 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74   must be convert
236d0 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  ed.**          t
236e0 6f 20 55 54 46 2d 38 2e 3c 2f 70 3e 3c 2f 6c 69  o UTF-8.</p></li
236f0 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  >.** </ul>.**.**
23700 20 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65 74   Conversions bet
23710 77 65 65 6e 20 55 54 46 2d 31 36 62 65 20 61 6e  ween UTF-16be an
23720 64 20 55 54 46 2d 31 36 6c 65 20 61 72 65 20 61  d UTF-16le are a
23730 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c  lways done in pl
23740 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f  ace and do.** no
23750 74 20 69 6e 76 61 6c 69 64 61 74 65 20 61 20 70  t invalidate a p
23760 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74 68  rior pointer, th
23770 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74  ough of course t
23780 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
23790 65 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74  e buffer.** that
237a0 20 74 68 65 20 70 72 69 6f 72 20 70 6f 69 6e 74   the prior point
237b0 65 72 20 70 6f 69 6e 74 73 20 74 6f 20 77 69 6c  er points to wil
237c0 6c 20 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69  l have been modi
237d0 66 69 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e  fied.  Other kin
237e0 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73  ds.** of convers
237f0 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20  ion are done in 
23800 70 6c 61 63 65 20 77 68 65 6e 20 69 74 20 69 73  place when it is
23810 20 70 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73   possible, but s
23820 6f 6d 65 74 69 6d 65 20 69 74 20 69 73 0a 2a 2a  ometime it is.**
23830 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e   not possible an
23840 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73  d in those cases
23850 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20   prior pointers 
23860 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e  are invalidated.
23870 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66    .**.** The saf
23880 65 73 74 20 61 6e 64 20 65 61 73 69 65 73 74 20  est and easiest 
23890 74 6f 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69  to remember poli
238a0 63 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20  cy is to invoke 
238b0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a  these routines.*
238c0 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20  * in one of the 
238d0 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a  following ways:.
238e0 2a 2a 0a 2a 2a 20 20 3c 75 6c 3e 0a 2a 2a 20 20  **.**  <ul>.**  
238f0 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  <li>sqlite3_colu
23900 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77  mn_text() follow
23910 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
23920 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69  lumn_bytes()</li
23930 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65  >.**  <li>sqlite
23940 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20  3_column_blob() 
23950 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69  followed by sqli
23960 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
23970 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e  ()</li>.**  <li>
23980 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
23990 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64  ext16() followed
239a0 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
239b0 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c 69  mn_bytes16()</li
239c0 3e 0a 2a 2a 20 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  >.**  </ul>.**.*
239d0 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  * In other words
239e0 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c  , you should cal
239f0 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  l sqlite3_column
23a00 5f 74 65 78 74 28 29 2c 20 73 71 6c 69 74 65 33  _text(), sqlite3
23a10 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 0a  _column_blob(),.
23a20 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f  ** or sqlite3_co
23a30 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 69  lumn_text16() fi
23a40 72 73 74 20 74 6f 20 66 6f 72 63 65 20 74 68 65  rst to force the
23a50 20 72 65 73 75 6c 74 20 69 6e 74 6f 20 74 68 65   result into the
23a60 20 64 65 73 69 72 65 64 0a 2a 2a 20 66 6f 72 6d   desired.** form
23a70 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20  at, then invoke 
23a80 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
23a90 79 74 65 73 28 29 20 6f 72 20 73 71 6c 69 74 65  ytes() or sqlite
23aa0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
23ab0 28 29 20 74 6f 0a 2a 2a 20 66 69 6e 64 20 74 68  () to.** find th
23ac0 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 72 65  e size of the re
23ad0 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69  sult.  Do not mi
23ae0 78 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  x call to sqlite
23af0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
23b00 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  or.** sqlite3_co
23b10 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68  lumn_blob() with
23b20 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
23b30 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
23b40 28 29 2e 20 20 41 6e 64 20 64 6f 20 6e 6f 74 0a  ().  And do not.
23b50 2a 2a 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20  ** mix calls to 
23b60 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
23b70 65 78 74 31 36 28 29 20 77 69 74 68 20 63 61 6c  ext16() with cal
23b80 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ls to sqlite3_co
23b90 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a  lumn_bytes()..**
23ba0 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 73  .** The pointers
23bb0 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 76 61   returned are va
23bc0 6c 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65  lid until a type
23bd0 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75   conversion occu
23be0 72 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62  rs as.** describ
23bf0 65 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74  ed above, or unt
23c00 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  il [sqlite3_step
23c10 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
23c20 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b  reset()] or.** [
23c30 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
23c40 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  ()] is called.  
23c50 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65  The memory space
23c60 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 74   used to hold st
23c70 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 62 6c 6f  rings.** and blo
23c80 62 73 20 69 73 20 66 72 65 65 64 20 61 75 74 6f  bs is freed auto
23c90 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c  matically.  Do <
23ca0 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 73 20 74  b>not</b> pass t
23cb0 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75  he pointers retu
23cc0 72 6e 65 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  rned.** [sqlite3
23cd0 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c  _column_blob()],
23ce0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
23cf0 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69  _text()], etc. i
23d00 6e 74 6f 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  nto .** [sqlite3
23d10 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _free()]..**.** 
23d20 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  If a memory allo
23d30 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63  cation error occ
23d40 75 72 73 20 64 75 72 69 6e 67 20 74 68 65 20 65  urs during the e
23d50 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79  valuation of any
23d60 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 72 6f 75  .** of these rou
23d70 74 69 6e 65 73 2c 20 61 20 64 65 66 61 75 6c 74  tines, a default
23d80 20 76 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e   value is return
23d90 65 64 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74  ed.  The default
23da0 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74   value.** is eit
23db0 68 65 72 20 74 68 65 20 69 6e 74 65 67 65 72 20  her the integer 
23dc0 30 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20  0, the floating 
23dd0 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30  point number 0.0
23de0 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70  , or a NULL.** p
23df0 6f 69 6e 74 65 72 2e 20 20 53 75 62 73 65 71 75  ointer.  Subsequ
23e00 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  ent calls to [sq
23e10 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d  lite3_errcode()]
23e20 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20   will return.** 
23e30 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a  [SQLITE_NOMEM]..
23e40 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
23e50 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 30 33 7d  :.**.** {F13803}
23e60 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
23e70 6c 75 6d 6e 5f 62 6c 6f 62 28 53 2c 4e 29 5d 20  lumn_blob(S,N)] 
23e80 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72  interface conver
23e90 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ts the.**       
23ea0 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e     Nth column in
23eb0 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77   the current row
23ec0 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
23ed0 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20  et for.**       
23ee0 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61     [prepared sta
23ef0 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61  tement] S into a
23f00 20 62 6c 6f 62 20 61 6e 64 20 74 68 65 6e 20 72   blob and then r
23f10 65 74 75 72 6e 73 20 61 0a 2a 2a 20 20 20 20 20  eturns a.**     
23f20 20 20 20 20 20 70 6f 69 6e 74 65 72 20 74 6f 20       pointer to 
23f30 74 68 65 20 63 6f 6e 76 65 72 74 65 64 20 76 61  the converted va
23f40 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38  lue..**.** {F138
23f50 30 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  06} The [sqlite3
23f60 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 53 2c  _column_bytes(S,
23f70 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  N)] interface re
23f80 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20  turns the.**    
23f90 20 20 20 20 20 20 6e 75 6d 62 65 72 20 6f 66 20        number of 
23fa0 62 79 74 65 73 20 69 6e 20 74 68 65 20 62 6c 6f  bytes in the blo
23fb0 62 20 6f 72 20 73 74 72 69 6e 67 20 28 65 78 63  b or string (exc
23fc0 6c 75 73 69 76 65 20 6f 66 20 74 68 65 0a 2a 2a  lusive of the.**
23fd0 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 20 74            zero t
23fe0 65 72 6d 69 6e 61 74 6f 72 20 6f 6e 20 74 68 65  erminator on the
23ff0 20 73 74 72 69 6e 67 29 20 74 68 61 74 20 77 61   string) that wa
24000 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  s returned by th
24010 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 6f  e.**          mo
24020 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74  st recent call t
24030 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  o [sqlite3_colum
24040 6e 5f 62 6c 6f 62 28 53 2c 4e 29 5d 20 6f 72 0a  n_blob(S,N)] or.
24050 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
24060 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
24070 28 53 2c 4e 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46  (S,N)]..**.** {F
24080 31 33 38 30 39 7d 20 54 68 65 20 5b 73 71 6c 69  13809} The [sqli
24090 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
240a0 31 36 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61  16(S,N)] interfa
240b0 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a  ce returns the.*
240c0 2a 20 20 20 20 20 20 20 20 20 20 6e 75 6d 62 65  *          numbe
240d0 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
240e0 65 20 73 74 72 69 6e 67 20 28 65 78 63 6c 75 73  e string (exclus
240f0 69 76 65 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20  ive of the.**   
24100 20 20 20 20 20 20 20 7a 65 72 6f 20 74 65 72 6d         zero term
24110 69 6e 61 74 6f 72 20 6f 6e 20 74 68 65 20 73 74  inator on the st
24120 72 69 6e 67 29 20 74 68 61 74 20 77 61 73 20 72  ring) that was r
24130 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a  eturned by the.*
24140 2a 20 20 20 20 20 20 20 20 20 20 6d 6f 73 74 20  *          most 
24150 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b  recent call to [
24160 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
24170 65 78 74 31 36 28 53 2c 4e 29 5d 2e 0a 2a 2a 0a  ext16(S,N)]..**.
24180 2a 2a 20 7b 46 31 33 38 31 32 7d 20 54 68 65 20  ** {F13812} The 
24190 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
241a0 64 6f 75 62 6c 65 28 53 2c 4e 29 5d 20 69 6e 74  double(S,N)] int
241b0 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20  erface converts 
241c0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
241d0 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68  Nth column in th
241e0 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66  e current row of
241f0 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
24200 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  for.**          
24210 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
24220 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20 66 6c  ent] S into a fl
24230 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
24240 75 65 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20  ue and.**       
24250 20 20 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70     returns a cop
24260 79 20 6f 66 20 74 68 61 74 20 76 61 6c 75 65 2e  y of that value.
24270 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 31 35 7d 20  .**.** {F13815} 
24280 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  The [sqlite3_col
24290 75 6d 6e 5f 69 6e 74 28 53 2c 4e 29 5d 20 69 6e  umn_int(S,N)] in
242a0 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73  terface converts
242b0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
242c0 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74   Nth column in t
242d0 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f  he current row o
242e0 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
242f0 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20   for.**         
24300 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
24310 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20 36  ment] S into a 6
24320 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  4-bit signed int
24330 65 67 65 72 20 61 6e 64 0a 2a 2a 20 20 20 20 20  eger and.**     
24340 20 20 20 20 20 72 65 74 75 72 6e 73 20 74 68 65       returns the
24350 20 6c 6f 77 65 72 20 33 32 20 62 69 74 73 20 6f   lower 32 bits o
24360 66 20 74 68 61 74 20 69 6e 74 65 67 65 72 2e 0a  f that integer..
24370 2a 2a 0a 2a 2a 20 7b 46 31 33 38 31 38 7d 20 54  **.** {F13818} T
24380 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
24390 6d 6e 5f 69 6e 74 36 34 28 53 2c 4e 29 5d 20 69  mn_int64(S,N)] i
243a0 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74  nterface convert
243b0 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
243c0 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20    Nth column in 
243d0 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20  the current row 
243e0 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
243f0 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  t for.**        
24400 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74    [prepared stat
24410 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20  ement] S into a 
24420 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  64-bit signed in
24430 74 65 67 65 72 20 61 6e 64 0a 2a 2a 20 20 20 20  teger and.**    
24440 20 20 20 20 20 20 72 65 74 75 72 6e 73 20 61 20        returns a 
24450 63 6f 70 79 20 6f 66 20 74 68 61 74 20 69 6e 74  copy of that int
24460 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  eger..**.** {F13
24470 38 32 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  821} The [sqlite
24480 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 53 2c  3_column_text(S,
24490 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f  N)] interface co
244a0 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20  nverts the.**   
244b0 20 20 20 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d         Nth colum
244c0 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74  n in the current
244d0 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75   row of the resu
244e0 6c 74 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20 20  lt set for.**   
244f0 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64         [prepared
24500 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e   statement] S in
24510 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  to a zero-termin
24520 61 74 65 64 20 55 54 46 2d 38 20 0a 2a 2a 20 20  ated UTF-8 .**  
24530 20 20 20 20 20 20 20 20 73 74 72 69 6e 67 20 61          string a
24540 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  nd returns a poi
24550 6e 74 65 72 20 74 6f 20 74 68 61 74 20 73 74 72  nter to that str
24560 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38  ing..**.** {F138
24570 32 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  24} The [sqlite3
24580 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 53  _column_text16(S
24590 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  ,N)] interface c
245a0 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20  onverts the.**  
245b0 20 20 20 20 20 20 20 20 4e 74 68 20 63 6f 6c 75          Nth colu
245c0 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e  mn in the curren
245d0 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73  t row of the res
245e0 75 6c 74 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20  ult set for.**  
245f0 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65          [prepare
24600 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69  d statement] S i
24610 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69  nto a zero-termi
24620 6e 61 74 65 64 20 32 2d 62 79 74 65 0a 2a 2a 20  nated 2-byte.** 
24630 20 20 20 20 20 20 20 20 20 61 6c 69 67 6e 65 64           aligned
24640 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62   UTF-16 native b
24650 79 74 65 20 6f 72 64 65 72 0a 2a 2a 20 20 20 20  yte order.**    
24660 20 20 20 20 20 20 73 74 72 69 6e 67 20 61 6e 64        string and
24670 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
24680 65 72 20 74 6f 20 74 68 61 74 20 73 74 72 69 6e  er to that strin
24690 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 32 37  g..**.** {F13827
246a0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
246b0 6f 6c 75 6d 6e 5f 74 79 70 65 28 53 2c 4e 29 5d  olumn_type(S,N)]
246c0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
246d0 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  ns.**          o
246e0 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4e 55  ne of [SQLITE_NU
246f0 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4e 54  LL], [SQLITE_INT
24700 45 47 45 52 5d 2c 20 5b 53 51 4c 49 54 45 5f 46  EGER], [SQLITE_F
24710 4c 4f 41 54 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  LOAT],.**       
24720 20 20 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d     [SQLITE_TEXT]
24730 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 42 4c 4f  , or [SQLITE_BLO
24740 42 5d 20 61 73 20 61 70 70 72 6f 70 72 69 61 74  B] as appropriat
24750 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  e for.**        
24760 20 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e    the Nth column
24770 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20   in the current 
24780 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c  row of the resul
24790 74 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20  t set for.**    
247a0 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20        [prepared 
247b0 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2a  statement] S..**
247c0 0a 2a 2a 20 7b 46 31 33 38 33 30 7d 20 54 68 65  .** {F13830} The
247d0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
247e0 5f 76 61 6c 75 65 28 53 2c 4e 29 5d 20 69 6e 74  _value(S,N)] int
247f0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
24800 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 6f 69  .**          poi
24810 6e 74 65 72 20 74 6f 20 61 6e 20 5b 75 6e 70 72  nter to an [unpr
24820 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
24830 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f  value] object fo
24840 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  r the.**        
24850 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20    Nth column in 
24860 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20  the current row 
24870 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
24880 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  t for.**        
24890 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74    [prepared stat
248a0 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 63 6f 6e  ement] S..*/.con
248b0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
248c0 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c  _column_blob(sql
248d0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
248e0 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  iCol);.int sqlit
248f0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
24900 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
24910 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71  nt iCol);.int sq
24920 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
24930 65 73 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  es16(sqlite3_stm
24940 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64  t*, int iCol);.d
24950 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f  ouble sqlite3_co
24960 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69  lumn_double(sqli
24970 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
24980 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  Col);.int sqlite
24990 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c  3_column_int(sql
249a0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
249b0 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69  iCol);.sqlite3_i
249c0 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c  nt64 sqlite3_col
249d0 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  umn_int64(sqlite
249e0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
249f0 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e  l);.const unsign
24a00 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  ed char *sqlite3
24a10 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c  _column_text(sql
24a20 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
24a30 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  iCol);.const voi
24a40 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
24a50 6e 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33  n_text16(sqlite3
24a60 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
24a70 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
24a80 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74  olumn_type(sqlit
24a90 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
24aa0 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c  ol);.sqlite3_val
24ab0 75 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ue *sqlite3_colu
24ac0 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33  mn_value(sqlite3
24ad0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
24ae0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
24af0 45 46 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72  EF: Destroy A Pr
24b00 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
24b10 20 4f 62 6a 65 63 74 20 7b 46 31 33 33 30 30 7d   Object {F13300}
24b20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
24b30 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 75  e3_finalize() fu
24b40 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64  nction is called
24b50 20 74 6f 20 64 65 6c 65 74 65 20 61 20 0a 2a 2a   to delete a .**
24b60 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
24b70 6d 65 6e 74 5d 2e 20 49 66 20 74 68 65 20 73 74  ment]. If the st
24b80 61 74 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 65  atement was.** e
24b90 78 65 63 75 74 65 64 20 73 75 63 63 65 73 73 66  xecuted successf
24ba0 75 6c 6c 79 2c 20 6f 72 20 6e 6f 74 20 65 78 65  ully, or not exe
24bb0 63 75 74 65 64 20 61 74 20 61 6c 6c 2c 20 74 68  cuted at all, th
24bc0 65 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 73 20  en SQLITE_OK is 
24bd0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 49 66 20  returned..** If 
24be0 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65  execution of the
24bf0 20 73 74 61 74 65 6d 65 6e 74 20 66 61 69 6c 65   statement faile
24c00 64 20 74 68 65 6e 20 61 6e 20 0a 2a 2a 20 5b 65  d then an .** [e
24c10 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 20 5b 65  rror code] or [e
24c20 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f  xtended error co
24c30 64 65 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e  de].** is return
24c40 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ed. .**.** This 
24c50 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 63  routine can be c
24c60 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 70 6f 69  alled at any poi
24c70 6e 74 20 64 75 72 69 6e 67 20 74 68 65 20 65 78  nt during the ex
24c80 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a  ecution of the.*
24c90 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
24ca0 65 6d 65 6e 74 5d 2e 20 20 49 66 20 74 68 65 20  ement].  If the 
24cb0 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20  virtual machine 
24cc0 68 61 73 20 6e 6f 74 20 0a 2a 2a 20 63 6f 6d 70  has not .** comp
24cd0 6c 65 74 65 64 20 65 78 65 63 75 74 69 6f 6e 20  leted execution 
24ce0 77 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e  when this routin
24cf0 65 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 61  e is called, tha
24d00 74 20 69 73 20 6c 69 6b 65 0a 2a 2a 20 65 6e 63  t is like.** enc
24d10 6f 75 6e 74 65 72 69 6e 67 20 61 6e 20 65 72 72  ountering an err
24d20 6f 72 20 6f 72 20 61 6e 20 69 6e 74 65 72 72 75  or or an interru
24d30 70 74 2e 20 20 28 53 65 65 20 5b 73 71 6c 69 74  pt.  (See [sqlit
24d40 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 2e  e3_interrupt()].
24d50 29 20 0a 2a 2a 20 49 6e 63 6f 6d 70 6c 65 74 65  ) .** Incomplete
24d60 20 75 70 64 61 74 65 73 20 6d 61 79 20 62 65 20   updates may be 
24d70 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 6e 64 20  rolled back and 
24d80 74 72 61 6e 73 61 63 74 69 6f 6e 73 20 63 61 6e  transactions can
24d90 63 65 6c 6c 65 64 2c 20 20 0a 2a 2a 20 64 65 70  celled,  .** dep
24da0 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 69  ending on the ci
24db0 72 63 75 6d 73 74 61 6e 63 65 73 2c 20 61 6e 64  rcumstances, and
24dc0 20 74 68 65 20 0a 2a 2a 20 5b 65 72 72 6f 72 20   the .** [error 
24dd0 63 6f 64 65 5d 20 72 65 74 75 72 6e 65 64 20 77  code] returned w
24de0 69 6c 6c 20 62 65 20 5b 53 51 4c 49 54 45 5f 41  ill be [SQLITE_A
24df0 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  BORT]..**.** INV
24e00 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
24e10 46 31 31 33 30 32 7d 20 54 68 65 20 5b 73 71 6c  F11302} The [sql
24e20 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29  ite3_finalize(S)
24e30 5d 20 69 6e 74 65 72 66 61 63 65 20 64 65 73 74  ] interface dest
24e40 72 6f 79 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  roys the.**     
24e50 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73       [prepared s
24e60 74 61 74 65 6d 65 6e 74 5d 20 53 20 61 6e 64 20  tatement] S and 
24e70 72 65 6c 65 61 73 65 73 20 61 6c 6c 0a 2a 2a 20  releases all.** 
24e80 20 20 20 20 20 20 20 20 20 6d 65 6d 6f 72 79 20           memory 
24e90 61 6e 64 20 66 69 6c 65 20 72 65 73 6f 75 72 63  and file resourc
24ea0 65 73 20 68 65 6c 64 20 62 79 20 74 68 61 74 20  es held by that 
24eb0 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46  object..**.** {F
24ec0 31 31 33 30 34 7d 20 49 66 20 74 68 65 20 6d 6f  11304} If the mo
24ed0 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74  st recent call t
24ee0 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
24ef0 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20  S)] for the.**  
24f00 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65          [prepare
24f10 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 72  d statement] S r
24f20 65 74 75 72 6e 65 64 20 61 6e 20 65 72 72 6f 72  eturned an error
24f30 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  ,.**          th
24f40 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  en [sqlite3_fina
24f50 6c 69 7a 65 28 53 29 5d 20 72 65 74 75 72 6e 73  lize(S)] returns
24f60 20 74 68 61 74 20 73 61 6d 65 20 65 72 72 6f 72   that same error
24f70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
24f80 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65  _finalize(sqlite
24f90 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
24fa0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
24fb0 20 52 65 73 65 74 20 41 20 50 72 65 70 61 72 65   Reset A Prepare
24fc0 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65  d Statement Obje
24fd0 63 74 20 7b 46 31 33 33 33 30 7d 0a 2a 2a 0a 2a  ct {F13330}.**.*
24fe0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
24ff0 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  set() function i
25000 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65  s called to rese
25010 74 20 61 20 0a 2a 2a 20 5b 70 72 65 70 61 72 65  t a .** [prepare
25020 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a  d statement] obj
25030 65 63 74 2e 0a 2a 2a 20 62 61 63 6b 20 74 6f 20  ect..** back to 
25040 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74  its initial stat
25050 65 2c 20 72 65 61 64 79 20 74 6f 20 62 65 20 72  e, ready to be r
25060 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20 41  e-executed..** A
25070 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ny SQL statement
25080 20 76 61 72 69 61 62 6c 65 73 20 74 68 61 74 20   variables that 
25090 68 61 64 20 76 61 6c 75 65 73 20 62 6f 75 6e 64  had values bound
250a0 20 74 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a   to them using.*
250b0 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  * the [sqlite3_b
250c0 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74  ind_blob | sqlit
250d0 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d  e3_bind_*() API]
250e0 20 72 65 74 61 69 6e 20 74 68 65 69 72 20 76 61   retain their va
250f0 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71  lues..** Use [sq
25100 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64  lite3_clear_bind
25110 69 6e 67 73 28 29 5d 20 74 6f 20 72 65 73 65 74  ings()] to reset
25120 20 74 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a   the bindings..*
25130 2a 0a 2a 2a 20 7b 46 31 31 33 33 32 7d 20 54 68  *.** {F11332} Th
25140 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  e [sqlite3_reset
25150 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  (S)] interface r
25160 65 73 65 74 73 20 74 68 65 20 5b 70 72 65 70 61  esets the [prepa
25170 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
25180 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 61 63  .**          bac
25190 6b 20 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69  k to the beginni
251a0 6e 67 20 6f 66 20 69 74 73 20 70 72 6f 67 72 61  ng of its progra
251b0 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 33 33 34  m..**.** {F11334
251c0 7d 20 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65  } If the most re
251d0 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  cent call to [sq
251e0 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66  lite3_step(S)] f
251f0 6f 72 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  or .**          
25200 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
25210 65 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20  ent] S returned 
25220 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20  [SQLITE_ROW] or 
25230 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a  [SQLITE_DONE],.*
25240 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 69 66  *          or if
25250 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
25260 29 5d 20 68 61 73 20 6e 65 76 65 72 20 62 65 66  )] has never bef
25270 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20  ore been called 
25280 6f 6e 20 53 2c 0a 2a 2a 20 20 20 20 20 20 20 20  on S,.**        
25290 20 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f    then [sqlite3_
252a0 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e  reset(S)] return
252b0 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a  s [SQLITE_OK]..*
252c0 2a 0a 2a 2a 20 7b 46 31 31 33 33 36 7d 20 49 66  *.** {F11336} If
252d0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
252e0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
252f0 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 0a 2a  3_step(S)] for.*
25300 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70  *          [prep
25310 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
25320 53 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65  S indicated an e
25330 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 20 20  rror, then.**   
25340 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
25350 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e  reset(S)] return
25360 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65  s an appropriate
25370 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a   [error code]..*
25380 2a 0a 2a 2a 20 7b 46 31 31 33 33 38 7d 20 54 68  *.** {F11338} Th
25390 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  e [sqlite3_reset
253a0 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64  (S)] interface d
253b0 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74  oes not change t
253c0 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 20 20 20  he values.**    
253d0 20 20 20 20 20 20 6f 66 20 61 6e 79 20 5b 73 71        of any [sq
253e0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
253f0 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 5b 70 72  bindings] on [pr
25400 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
25410 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ] S..*/.int sqli
25420 74 65 33 5f 72 65 73 65 74 28 73 71 6c 69 74 65  te3_reset(sqlite
25430 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
25440 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
25450 20 43 72 65 61 74 65 20 4f 72 20 52 65 64 65 66   Create Or Redef
25460 69 6e 65 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e  ine SQL Function
25470 73 20 7b 46 31 36 31 30 30 7d 0a 2a 2a 20 4b 45  s {F16100}.** KE
25480 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f  YWORDS: {functio
25490 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69  n creation routi
254a0 6e 65 73 7d 20 0a 2a 2a 0a 2a 2a 20 54 68 65 73  nes} .**.** Thes
254b0 65 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20  e two functions 
254c0 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e  (collectively kn
254d0 6f 77 6e 20 61 73 0a 2a 2a 20 22 66 75 6e 63 74  own as.** "funct
254e0 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75  ion creation rou
254f0 74 69 6e 65 73 22 29 20 61 72 65 20 75 73 65 64  tines") are used
25500 20 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63   to add SQL func
25510 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61  tions or aggrega
25520 74 65 73 0a 2a 2a 20 6f 72 20 74 6f 20 72 65 64  tes.** or to red
25530 65 66 69 6e 65 20 74 68 65 20 62 65 68 61 76 69  efine the behavi
25540 6f 72 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53  or of existing S
25550 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20  QL functions or 
25560 61 67 67 72 65 67 61 74 65 73 2e 20 20 54 68 65  aggregates.  The
25570 0a 2a 2a 20 64 69 66 66 65 72 65 6e 63 65 20 6f  .** difference o
25580 6e 6c 79 20 62 65 74 77 65 65 6e 20 74 68 65 20  nly between the 
25590 74 77 6f 20 69 73 20 74 68 61 74 20 74 68 65 20  two is that the 
255a0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
255b0 2c 20 74 68 65 0a 2a 2a 20 6e 61 6d 65 20 6f 66  , the.** name of
255c0 20 74 68 65 20 28 73 63 61 6c 61 72 29 20 66 75   the (scalar) fu
255d0 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67  nction or aggreg
255e0 61 74 65 2c 20 69 73 20 65 6e 63 6f 64 65 64 20  ate, is encoded 
255f0 69 6e 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20  in UTF-8 for.** 
25600 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
25610 75 6e 63 74 69 6f 6e 28 29 20 61 6e 64 20 55 54  unction() and UT
25620 46 2d 31 36 20 66 6f 72 20 73 71 6c 69 74 65 33  F-16 for sqlite3
25630 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
25640 31 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  16()..**.** The 
25650 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
25660 69 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  is the [database
25670 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20   connection] to 
25680 77 68 69 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a  which the SQL.**
25690 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20   function is to 
256a0 62 65 20 61 64 64 65 64 2e 20 20 49 66 20 61 20  be added.  If a 
256b0 73 69 6e 67 6c 65 0a 2a 2a 20 70 72 6f 67 72 61  single.** progra
256c0 6d 20 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e  m uses more than
256d0 20 6f 6e 65 20 5b 64 61 74 61 62 61 73 65 20 63   one [database c
256e0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 6e 74 65 72  onnection] inter
256f0 6e 61 6c 6c 79 2c 20 74 68 65 6e 20 53 51 4c 0a  nally, then SQL.
25700 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73  ** functions mus
25710 74 20 62 65 20 61 64 64 65 64 20 69 6e 64 69 76  t be added indiv
25720 69 64 75 61 6c 6c 79 20 74 6f 20 65 61 63 68 20  idually to each 
25730 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
25740 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tion]..**.** The
25750 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
25760 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  r is the name of
25770 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
25780 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65 64 0a  n to be created.
25790 2a 2a 20 6f 72 20 72 65 64 65 66 69 6e 65 64 2e  ** or redefined.
257a0 0a 2a 2a 20 54 68 65 20 6c 65 6e 67 74 68 20 6f  .** The length o
257b0 66 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c 69  f the name is li
257c0 6d 69 74 65 64 20 74 6f 20 32 35 35 20 62 79 74  mited to 255 byt
257d0 65 73 2c 20 65 78 63 6c 75 73 69 76 65 20 6f 66  es, exclusive of
257e0 20 74 68 65 20 0a 2a 2a 20 7a 65 72 6f 2d 74 65   the .** zero-te
257f0 72 6d 69 6e 61 74 6f 72 2e 20 20 4e 6f 74 65 20  rminator.  Note 
25800 74 68 61 74 20 74 68 65 20 6e 61 6d 65 20 6c 65  that the name le
25810 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20 69 6e  ngth limit is in
25820 20 62 79 74 65 73 2c 20 6e 6f 74 0a 2a 2a 20 63   bytes, not.** c
25830 68 61 72 61 63 74 65 72 73 2e 20 20 41 6e 79 20  haracters.  Any 
25840 61 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74  attempt to creat
25850 65 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74  e a function wit
25860 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a  h a longer name.
25870 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69  ** will result i
25880 6e 20 61 6e 20 53 51 4c 49 54 45 5f 45 52 52 4f  n an SQLITE_ERRO
25890 52 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54  R error..**.** T
258a0 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
258b0 65 72 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  er is the number
258c0 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74 68   of arguments th
258d0 61 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  at the SQL funct
258e0 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67  ion or.** aggreg
258f0 61 74 65 20 74 61 6b 65 73 2e 20 49 66 20 74 68  ate takes. If th
25900 69 73 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  is parameter is 
25910 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74  negative, then t
25920 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
25930 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20  or.** aggregate 
25940 6d 61 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d  may take any num
25950 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73  ber of arguments
25960 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 75 72  ..**.** The four
25970 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54  th parameter, eT
25980 65 78 74 52 65 70 2c 20 73 70 65 63 69 66 69 65  extRep, specifie
25990 73 20 77 68 61 74 20 0a 2a 2a 20 5b 53 51 4c 49  s what .** [SQLI
259a0 54 45 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65  TE_UTF8 | text e
259b0 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51  ncoding] this SQ
259c0 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65  L function prefe
259d0 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61  rs for.** its pa
259e0 72 61 6d 65 74 65 72 73 2e 20 20 41 6e 79 20 53  rameters.  Any S
259f0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c  QL function impl
25a00 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c  ementation shoul
25a10 64 20 62 65 20 61 62 6c 65 20 74 6f 20 77 6f 72  d be able to wor
25a20 6b 0a 2a 2a 20 77 6f 72 6b 20 77 69 74 68 20 55  k.** work with U
25a30 54 46 2d 38 2c 20 55 54 46 2d 31 36 6c 65 2c 20  TF-8, UTF-16le, 
25a40 6f 72 20 55 54 46 2d 31 36 62 65 2e 20 20 42 75  or UTF-16be.  Bu
25a50 74 20 73 6f 6d 65 20 69 6d 70 6c 65 6d 65 6e 74  t some implement
25a60 61 74 69 6f 6e 73 20 6d 61 79 20 62 65 0a 2a 2a  ations may be.**
25a70 20 6d 6f 72 65 20 65 66 66 69 63 69 65 6e 74 20   more efficient 
25a80 77 69 74 68 20 6f 6e 65 20 65 6e 63 6f 64 69 6e  with one encodin
25a90 67 20 74 68 61 6e 20 61 6e 6f 74 68 65 72 2e 20  g than another. 
25aa0 20 49 74 20 69 73 20 61 6c 6c 6f 77 65 64 20 74   It is allowed t
25ab0 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69  o.** invoke sqli
25ac0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
25ad0 69 6f 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ion() or sqlite3
25ae0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
25af0 31 36 28 29 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a  16() multiple.**
25b00 20 74 69 6d 65 73 20 77 69 74 68 20 74 68 65 20   times with the 
25b10 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 62 75  same function bu
25b20 74 20 77 69 74 68 20 64 69 66 66 65 72 65 6e 74  t with different
25b30 20 76 61 6c 75 65 73 20 6f 66 20 65 54 65 78 74   values of eText
25b40 52 65 70 2e 0a 2a 2a 20 57 68 65 6e 20 6d 75 6c  Rep..** When mul
25b50 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  tiple implementa
25b60 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d  tions of the sam
25b70 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 61  e function are a
25b80 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65  vailable, SQLite
25b90 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74 68  .** will pick th
25ba0 65 20 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c  e one that invol
25bb0 76 65 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d  ves the least am
25bc0 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 63 6f 6e  ount of data con
25bd0 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74  version..** If t
25be0 68 65 72 65 20 69 73 20 6f 6e 6c 79 20 61 20 73  here is only a s
25bf0 69 6e 67 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  ingle implementa
25c00 74 69 6f 6e 20 77 68 69 63 68 20 64 6f 65 73 20  tion which does 
25c10 6e 6f 74 20 63 61 72 65 20 77 68 61 74 0a 2a 2a  not care what.**
25c20 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 69   text encoding i
25c30 73 20 75 73 65 64 2c 20 74 68 65 6e 20 74 68 65  s used, then the
25c40 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
25c50 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 5b 53   should be.** [S
25c60 51 4c 49 54 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a  QLITE_ANY]..**.*
25c70 2a 20 54 68 65 20 66 69 66 74 68 20 70 61 72 61  * The fifth para
25c80 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72 62 69  meter is an arbi
25c90 74 72 61 72 79 20 70 6f 69 6e 74 65 72 2e 20 20  trary pointer.  
25ca0 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  The implementati
25cb0 6f 6e 0a 2a 2a 20 6f 66 20 74 68 65 20 66 75 6e  on.** of the fun
25cc0 63 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61  ction can gain a
25cd0 63 63 65 73 73 20 74 6f 20 74 68 69 73 20 70 6f  ccess to this po
25ce0 69 6e 74 65 72 20 75 73 69 6e 67 0a 2a 2a 20 5b  inter using.** [
25cf0 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74  sqlite3_user_dat
25d00 61 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  a()]..**.** The 
25d10 73 65 76 65 6e 74 68 2c 20 65 69 67 68 74 68 20  seventh, eighth 
25d20 61 6e 64 20 6e 69 6e 74 68 20 70 61 72 61 6d 65  and ninth parame
25d30 74 65 72 73 2c 20 78 46 75 6e 63 2c 20 78 53 74  ters, xFunc, xSt
25d40 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61  ep and xFinal, a
25d50 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74  re.** pointers t
25d60 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e  o C-language fun
25d70 63 74 69 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c  ctions that impl
25d80 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 0a 2a 2a  ement the SQL.**
25d90 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67   function or agg
25da0 72 65 67 61 74 65 2e 20 41 20 73 63 61 6c 61 72  regate. A scalar
25db0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65   SQL function re
25dc0 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d  quires an implem
25dd0 65 6e 74 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74  entation of.** t
25de0 68 65 20 78 46 75 6e 63 20 63 61 6c 6c 62 61 63  he xFunc callbac
25df0 6b 20 6f 6e 6c 79 2c 20 4e 55 4c 4c 20 70 6f 69  k only, NULL poi
25e00 6e 74 65 72 73 20 73 68 6f 75 6c 64 20 62 65 20  nters should be 
25e10 70 61 73 73 65 64 20 61 73 20 74 68 65 20 78 53  passed as the xS
25e20 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61  tep.** and xFina
25e30 6c 20 70 61 72 61 6d 65 74 65 72 73 2e 20 41 6e  l parameters. An
25e40 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66   aggregate SQL f
25e50 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73  unction requires
25e60 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69   an implementati
25e70 6f 6e 0a 2a 2a 20 6f 66 20 78 53 74 65 70 20 61  on.** of xStep a
25e80 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55  nd xFinal and NU
25e90 4c 4c 20 73 68 6f 75 6c 64 20 62 65 20 70 61 73  LL should be pas
25ea0 73 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 54  sed for xFunc. T
25eb0 6f 20 64 65 6c 65 74 65 20 61 6e 0a 2a 2a 20 65  o delete an.** e
25ec0 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e 63  xisting SQL func
25ed0 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74  tion or aggregat
25ee0 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 66 6f 72  e, pass NULL for
25ef0 20 61 6c 6c 20 74 68 72 65 65 20 66 75 6e 63 74   all three funct
25f00 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 2e  ion.** callback.
25f10 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 70 65 72  .**.** It is per
25f20 6d 69 74 74 65 64 20 74 6f 20 72 65 67 69 73 74  mitted to regist
25f30 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c  er multiple impl
25f40 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74  ementations of t
25f50 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74  he same.** funct
25f60 69 6f 6e 73 20 77 69 74 68 20 74 68 65 20 73 61  ions with the sa
25f70 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 69 74 68  me name but with
25f80 20 65 69 74 68 65 72 20 64 69 66 66 65 72 69 6e   either differin
25f90 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20  g numbers of.** 
25fa0 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 64 69 66  arguments or dif
25fb0 66 65 72 69 6e 67 20 70 65 72 66 65 72 72 65 64  fering perferred
25fc0 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e   text encodings.
25fd0 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73    SQLite will us
25fe0 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65  e.** the impleme
25ff0 6e 74 61 74 69 6f 6e 20 6d 6f 73 74 20 63 6c 6f  ntation most clo
26000 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68 65  sely matches the
26010 20 77 61 79 20 69 6e 20 77 68 69 63 68 20 74 68   way in which th
26020 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f  e.** SQL functio
26030 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a  n is used..**.**
26040 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
26050 2a 2a 20 7b 46 31 36 31 30 33 7d 20 54 68 65 20  ** {F16103} The 
26060 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
26070 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 69 6e  function16()] in
26080 74 65 72 66 61 63 65 20 62 65 68 61 76 65 73 20  terface behaves 
26090 65 78 61 63 74 6c 79 0a 2a 2a 20 20 20 20 20 20  exactly.**      
260a0 20 20 20 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65      like [sqlite
260b0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
260c0 6e 28 29 5d 20 69 6e 20 65 76 65 72 79 20 77 61  n()] in every wa
260d0 79 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74  y except that it
260e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74  .**          int
260f0 65 72 70 72 65 74 73 20 74 68 65 20 7a 46 75 6e  erprets the zFun
26100 63 74 69 6f 6e 4e 61 6d 65 20 61 72 67 75 6d 65  ctionName argume
26110 6e 74 20 61 73 0a 2a 2a 20 20 20 20 20 20 20 20  nt as.**        
26120 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65    zero-terminate
26130 64 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20  d UTF-16 native 
26140 62 79 74 65 20 6f 72 64 65 72 20 69 6e 73 74 65  byte order inste
26150 61 64 20 6f 66 20 61 73 20 61 0a 2a 2a 20 20 20  ad of as a.**   
26160 20 20 20 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d         zero-term
26170 69 6e 61 74 65 64 20 55 54 46 2d 38 2e 0a 2a 2a  inated UTF-8..**
26180 0a 2a 2a 20 7b 46 31 36 31 30 36 7d 20 41 20 73  .** {F16106} A s
26190 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61  uccessful invoca
261a0 74 69 6f 6e 20 6f 66 0a 2a 2a 20 20 20 20 20 20  tion of.**      
261b0 20 20 20 20 74 68 65 20 5b 73 71 6c 69 74 65 33      the [sqlite3
261c0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
261d0 28 44 2c 58 2c 4e 2c 45 2c 2e 2e 2e 29 5d 20 69  (D,X,N,E,...)] i
261e0 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65  nterface registe
261f0 72 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  rs.**          o
26200 72 20 72 65 70 6c 61 63 65 73 20 63 61 6c 6c 62  r replaces callb
26210 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 69 6e  ack functions in
26220 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
26230 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 20 20 20 20  ction] D.**     
26240 20 20 20 20 20 75 73 65 64 20 74 6f 20 69 6d 70       used to imp
26250 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66  lement the SQL f
26260 75 6e 63 74 69 6f 6e 20 6e 61 6d 65 64 20 58 20  unction named X 
26270 77 69 74 68 20 4e 20 70 61 72 61 6d 65 74 65 72  with N parameter
26280 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e  s.**          an
26290 64 20 68 61 76 69 6e 67 20 61 20 70 65 72 66 65  d having a perfe
262a0 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69  rred text encodi
262b0 6e 67 20 6f 66 20 45 2e 0a 2a 2a 0a 2a 2a 20 7b  ng of E..**.** {
262c0 46 31 36 31 30 39 7d 20 41 20 73 75 63 63 65 73  F16109} A succes
262d0 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71  sful call to [sq
262e0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
262f0 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c  ction(D,X,N,E,P,
26300 46 2c 53 2c 4c 29 5d 0a 2a 2a 20 20 20 20 20 20  F,S,L)].**      
26310 20 20 20 20 72 65 70 6c 61 63 65 73 20 74 68 65      replaces the
26320 20 50 2c 20 46 2c 20 53 2c 20 61 6e 64 20 4c 20   P, F, S, and L 
26330 76 61 6c 75 65 73 20 66 72 6f 6d 20 61 6e 79 20  values from any 
26340 70 72 69 6f 72 20 63 61 6c 6c 73 20 77 69 74 68  prior calls with
26350 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
26360 20 73 61 6d 65 20 44 2c 20 58 2c 20 4e 2c 20 61   same D, X, N, a
26370 6e 64 20 45 20 76 61 6c 75 65 73 2e 0a 2a 2a 0a  nd E values..**.
26380 2a 2a 20 7b 46 31 36 31 31 32 7d 20 54 68 65 20  ** {F16112} The 
26390 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
263a0 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 2e 2e 2e  function(D,X,...
263b0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 66 61 69  )] interface fai
263c0 6c 73 20 77 69 74 68 0a 2a 2a 20 20 20 20 20 20  ls with.**      
263d0 20 20 20 20 61 20 72 65 74 75 72 6e 20 63 6f 64      a return cod
263e0 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 45 52 52  e of [SQLITE_ERR
263f0 4f 52 5d 20 69 66 20 74 68 65 20 53 51 4c 20 66  OR] if the SQL f
26400 75 6e 63 74 69 6f 6e 20 6e 61 6d 65 20 58 20 69  unction name X i
26410 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6c 6f  s.**          lo
26420 6e 67 65 72 20 74 68 61 6e 20 32 35 35 20 62 79  nger than 255 by
26430 74 65 73 20 65 78 63 6c 75 73 69 76 65 20 6f 66  tes exclusive of
26440 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e   the zero termin
26450 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  ator..**.** {F16
26460 31 31 38 7d 20 45 69 74 68 65 72 20 46 20 6d 75  118} Either F mu
26470 73 74 20 62 65 20 4e 55 4c 4c 20 61 6e 64 20 53  st be NULL and S
26480 20 61 6e 64 20 4c 20 61 72 65 20 6e 6f 6e 2d 4e   and L are non-N
26490 55 4c 4c 20 6f 72 20 65 6c 73 65 20 46 0a 2a 2a  ULL or else F.**
264a0 20 20 20 20 20 20 20 20 20 20 69 73 20 6e 6f 6e            is non
264b0 2d 4e 55 4c 4c 20 61 6e 64 20 53 20 61 6e 64 20  -NULL and S and 
264c0 4c 20 61 72 65 20 4e 55 4c 4c 2c 20 6f 74 68 65  L are NULL, othe
264d0 72 77 69 73 65 0a 2a 2a 20 20 20 20 20 20 20 20  rwise.**        
264e0 20 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74    [sqlite3_creat
264f0 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e  e_function(D,X,N
26500 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 20 72 65 74  ,E,P,F,S,L)] ret
26510 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 45 52 52  urns [SQLITE_ERR
26520 4f 52 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31  OR]..**.** {F161
26530 32 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  21} The [sqlite3
26540 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
26550 28 44 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61  (D,...)] interfa
26560 63 65 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e  ce fails with an
26570 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 72 72  .**          err
26580 6f 72 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49  or code of [SQLI
26590 54 45 5f 42 55 53 59 5d 20 69 66 20 74 68 65 72  TE_BUSY] if ther
265a0 65 20 65 78 69 73 74 20 5b 70 72 65 70 61 72 65  e exist [prepare
265b0 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 0a 2a 2a  d statements].**
265c0 20 20 20 20 20 20 20 20 20 20 61 73 73 6f 63 69            associ
265d0 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 64  ated with the [d
265e0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
265f0 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  on] D..**.** {F1
26600 36 31 32 34 7d 20 54 68 65 20 5b 73 71 6c 69 74  6124} The [sqlit
26610 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
26620 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d 20 69  on(D,X,N,...)] i
26630 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73 20 77  nterface fails w
26640 69 74 68 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20  ith an.**       
26650 20 20 20 65 72 72 6f 72 20 63 6f 64 65 20 6f 66     error code of
26660 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
26670 69 66 20 70 61 72 61 6d 65 74 65 72 20 4e 20 28  if parameter N (
26680 73 70 65 63 69 66 79 69 6e 67 20 74 68 65 20 6e  specifying the n
26690 75 6d 62 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  umber.**        
266a0 20 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74    of arguments t
266b0 6f 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  o the SQL functi
266c0 6f 6e 20 62 65 69 6e 67 20 72 65 67 69 73 74 65  on being registe
266d0 72 65 64 29 20 69 73 20 6c 65 73 73 0a 2a 2a 20  red) is less.** 
266e0 20 20 20 20 20 20 20 20 20 74 68 61 6e 20 2d 31           than -1
266f0 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e   or greater than
26700 20 31 32 37 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36   127..**.** {F16
26710 31 32 37 7d 20 57 68 65 6e 20 4e 20 69 73 20 6e  127} When N is n
26720 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65  on-negative, the
26730 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
26740 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c  _function(D,X,N,
26750 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  ...)].**        
26760 20 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73    interface caus
26770 65 73 20 63 61 6c 6c 62 61 63 6b 73 20 74 6f 20  es callbacks to 
26780 62 65 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74  be invoked for t
26790 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 0a  he SQL function.
267a0 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 61 6d 65  **          name
267b0 64 20 58 20 77 68 65 6e 20 74 68 65 20 6e 75 6d  d X when the num
267c0 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73  ber of arguments
267d0 20 74 6f 20 74 68 65 20 53 51 4c 20 66 75 6e 63   to the SQL func
267e0 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 20  tion is.**      
267f0 20 20 20 20 65 78 61 63 74 6c 79 20 4e 2e 0a 2a      exactly N..*
26800 2a 0a 2a 2a 20 7b 46 31 36 31 33 30 7d 20 57 68  *.** {F16130} Wh
26810 65 6e 20 4e 20 69 73 20 2d 31 2c 20 74 68 65 20  en N is -1, the 
26820 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
26830 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 2e  function(D,X,N,.
26840 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ..)].**         
26850 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65   interface cause
26860 73 20 63 61 6c 6c 62 61 63 6b 73 20 74 6f 20 62  s callbacks to b
26870 65 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68  e invoked for th
26880 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 0a 2a  e SQL function.*
26890 2a 20 20 20 20 20 20 20 20 20 20 6e 61 6d 65 64  *          named
268a0 20 58 20 77 69 74 68 20 61 6e 79 20 6e 75 6d 62   X with any numb
268b0 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 2e  er of arguments.
268c0 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 33 33 7d 20  .**.** {F16133} 
268d0 57 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73  When calls to [s
268e0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
268f0 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e  nction(D,X,N,...
26900 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73  )].**          s
26910 70 65 63 69 66 79 20 6d 75 6c 74 69 70 6c 65 20  pecify multiple 
26920 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
26930 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63  of the same func
26940 74 69 6f 6e 20 58 0a 2a 2a 20 20 20 20 20 20 20  tion X.**       
26950 20 20 20 61 6e 64 20 77 68 65 6e 20 6f 6e 65 20     and when one 
26960 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 68  implementation h
26970 61 73 20 4e 3e 3d 30 20 61 6e 64 20 74 68 65 20  as N>=0 and the 
26980 6f 74 68 65 72 20 68 61 73 20 4e 3d 28 2d 31 29  other has N=(-1)
26990 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
269a0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
269b0 77 69 74 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20  with a non-zero 
269c0 4e 20 69 73 20 70 72 65 66 65 72 72 65 64 2e 0a  N is preferred..
269d0 2a 2a 0a 2a 2a 20 7b 46 31 36 31 33 36 7d 20 57  **.** {F16136} W
269e0 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  hen calls to [sq
269f0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
26a00 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 2e 2e  ction(D,X,N,E,..
26a10 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  .)].**          
26a20 73 70 65 63 69 66 79 20 6d 75 6c 74 69 70 6c 65  specify multiple
26a30 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
26a40 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e   of the same fun
26a50 63 74 69 6f 6e 20 58 20 77 69 74 68 0a 2a 2a 20  ction X with.** 
26a60 20 20 20 20 20 20 20 20 20 74 68 65 20 73 61 6d           the sam
26a70 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75  e number of argu
26a80 6d 65 6e 74 73 20 4e 20 62 75 74 20 77 69 74 68  ments N but with
26a90 20 64 69 66 66 65 72 65 6e 74 0a 2a 2a 20 20 20   different.**   
26aa0 20 20 20 20 20 20 20 65 6e 63 6f 64 69 6e 67 73         encodings
26ab0 20 45 2c 20 74 68 65 6e 20 74 68 65 20 69 6d 70   E, then the imp
26ac0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 65 72  lementation wher
26ad0 65 20 45 20 6d 61 74 63 68 65 73 20 74 68 65 0a  e E matches the.
26ae0 2a 2a 20 20 20 20 20 20 20 20 20 20 64 61 74 61  **          data
26af0 62 61 73 65 20 65 6e 63 6f 64 69 6e 67 20 69 73  base encoding is
26b00 20 70 72 65 66 65 72 72 65 64 2e 0a 2a 2a 0a 2a   preferred..**.*
26b10 2a 20 7b 46 31 36 31 33 39 7d 20 46 6f 72 20 61  * {F16139} For a
26b20 6e 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20  n aggregate SQL 
26b30 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 65 64  function created
26b40 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20   using.**       
26b50 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61     [sqlite3_crea
26b60 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c  te_function(D,X,
26b70 4e 2c 45 2c 50 2c 30 2c 53 2c 4c 29 5d 20 74 68  N,E,P,0,S,L)] th
26b80 65 20 66 69 6e 69 61 6c 69 7a 65 72 0a 2a 2a 20  e finializer.** 
26b90 20 20 20 20 20 20 20 20 20 66 75 6e 63 74 69 6f           functio
26ba0 6e 20 4c 20 77 69 6c 6c 20 61 6c 77 61 79 73 20  n L will always 
26bb0 62 65 20 69 6e 76 6f 6b 65 64 20 65 78 61 63 74  be invoked exact
26bc0 6c 79 20 6f 6e 63 65 20 69 66 20 74 68 65 0a 2a  ly once if the.*
26bd0 2a 20 20 20 20 20 20 20 20 20 20 73 74 65 70 20  *          step 
26be0 66 75 6e 63 74 69 6f 6e 20 53 20 69 73 20 63 61  function S is ca
26bf0 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  lled one or more
26c00 20 74 69 6d 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46   times..**.** {F
26c10 31 36 31 34 32 7d 20 57 68 65 6e 20 53 51 4c 69  16142} When SQLi
26c20 74 65 20 69 6e 76 6f 6b 65 73 20 65 69 74 68 65  te invokes eithe
26c30 72 20 74 68 65 20 78 46 75 6e 63 20 6f 72 20 78  r the xFunc or x
26c40 53 74 65 70 20 66 75 6e 63 74 69 6f 6e 20 6f 66  Step function of
26c50 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 20  .**          an 
26c60 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
26c70 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
26c80 20 6f 72 20 61 67 67 72 65 67 61 74 65 20 63 72   or aggregate cr
26c90 65 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  eated.**        
26ca0 20 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 72    by [sqlite3_cr
26cb0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
26cc0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63 72 65   or [sqlite3_cre
26cd0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
26ce0 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  ],.**          t
26cf0 68 65 6e 20 74 68 65 20 61 72 72 61 79 20 6f 66  hen the array of
26d00 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
26d10 20 6f 62 6a 65 63 74 73 20 70 61 73 73 65 64 20   objects passed 
26d20 61 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  as the.**       
26d30 20 20 20 74 68 69 72 64 20 70 61 72 61 6d 65 74     third paramet
26d40 65 72 20 61 72 65 20 61 6c 77 61 79 73 20 5b 70  er are always [p
26d50 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
26d60 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e  _value] objects.
26d70 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
26d80 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
26d90 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a  .  sqlite3 *db,.
26da0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46    const char *zF
26db0 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69  unctionName,.  i
26dc0 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65  nt nArg,.  int e
26dd0 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20  TextRep,.  void 
26de0 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a  *pApp,.  void (*
26df0 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63  xFunc)(sqlite3_c
26e00 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
26e10 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
26e20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71  void (*xStep)(sq
26e30 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
26e40 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
26e50 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  **),.  void (*xF
26e60 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f  inal)(sqlite3_co
26e70 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73  ntext*).);.int s
26e80 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
26e90 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69  nction16(.  sqli
26ea0 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74  te3 *db,.  const
26eb0 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f 6e   void *zFunction
26ec0 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67  Name,.  int nArg
26ed0 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70  ,.  int eTextRep
26ee0 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a  ,.  void *pApp,.
26ef0 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28    void (*xFunc)(
26f00 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
26f10 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
26f20 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
26f30 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63  xStep)(sqlite3_c
26f40 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
26f50 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
26f60 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73  void (*xFinal)(s
26f70 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
26f80 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
26f90 52 45 46 3a 20 54 65 78 74 20 45 6e 63 6f 64 69  REF: Text Encodi
26fa0 6e 67 73 20 7b 46 31 30 32 36 37 7d 0a 2a 2a 0a  ngs {F10267}.**.
26fb0 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
26fc0 74 20 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72  t define integer
26fd0 20 63 6f 64 65 73 20 74 68 61 74 20 72 65 70 72   codes that repr
26fe0 65 73 65 6e 74 20 74 68 65 20 76 61 72 69 6f 75  esent the variou
26ff0 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69  s.** text encodi
27000 6e 67 73 20 73 75 70 70 6f 72 74 65 64 20 62 79  ngs supported by
27010 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66   SQLite..*/.#def
27020 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 38 20  ine SQLITE_UTF8 
27030 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66            1.#def
27040 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
27050 4c 45 20 20 20 20 20 20 20 20 32 0a 23 64 65 66  LE        2.#def
27060 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
27070 42 45 20 20 20 20 20 20 20 20 33 0a 23 64 65 66  BE        3.#def
27080 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
27090 20 20 20 20 20 20 20 20 20 20 34 20 20 20 20 2f            4    /
270a0 2a 20 55 73 65 20 6e 61 74 69 76 65 20 62 79 74  * Use native byt
270b0 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 69  e order */.#defi
270c0 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 20  ne SQLITE_ANY   
270d0 20 20 20 20 20 20 20 20 20 35 20 20 20 20 2f 2a           5    /*
270e0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
270f0 66 75 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f  function only */
27100 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
27110 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38  UTF16_ALIGNED  8
27120 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63      /* sqlite3_c
27130 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20  reate_collation 
27140 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  only */../*.** C
27150 41 50 49 33 52 45 46 3a 20 4f 62 73 6f 6c 65 74  API3REF: Obsolet
27160 65 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a  e Functions.**.*
27170 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  * These function
27180 73 20 61 72 65 20 61 6c 6c 20 6e 6f 77 20 6f 62  s are all now ob
27190 73 6f 6c 65 74 65 2e 20 20 49 6e 20 6f 72 64 65  solete.  In orde
271a0 72 20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a  r to maintain.**
271b0 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
271c0 74 69 62 69 6c 69 74 79 20 77 69 74 68 20 6f 6c  tibility with ol
271d0 64 65 72 20 63 6f 64 65 2c 20 77 65 20 63 6f 6e  der code, we con
271e0 74 69 6e 75 65 20 74 6f 20 73 75 70 70 6f 72 74  tinue to support
271f0 0a 2a 2a 20 74 68 65 73 65 20 66 75 6e 63 74 69  .** these functi
27200 6f 6e 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e  ons.  However, n
27210 65 77 20 64 65 76 65 6c 6f 70 6d 65 6e 74 20 70  ew development p
27220 72 6f 6a 65 63 74 73 20 73 68 6f 75 6c 64 20 61  rojects should a
27230 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 65 20  void.** the use 
27240 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  of these functio
27250 6e 73 2e 20 20 54 6f 20 68 65 6c 70 20 65 6e 63  ns.  To help enc
27260 6f 75 72 61 67 65 20 70 65 6f 70 6c 65 20 74 6f  ourage people to
27270 20 61 76 6f 69 64 0a 2a 2a 20 75 73 69 6e 67 20   avoid.** using 
27280 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c  these functions,
27290 20 77 65 20 61 72 65 20 6e 6f 74 20 67 6f 69 6e   we are not goin
272a0 67 20 74 6f 20 74 65 6c 6c 20 79 6f 75 20 77 61  g to tell you wa
272b0 6e 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 69  nt they do..*/.i
272c0 6e 74 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  nt sqlite3_aggre
272d0 67 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74  gate_count(sqlit
272e0 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 69 6e  e3_context*);.in
272f0 74 20 73 71 6c 69 74 65 33 5f 65 78 70 69 72 65  t sqlite3_expire
27300 64 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  d(sqlite3_stmt*)
27310 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 72  ;.int sqlite3_tr
27320 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67 73 28  ansfer_bindings(
27330 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73  sqlite3_stmt*, s
27340 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 69  qlite3_stmt*);.i
27350 6e 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61  nt sqlite3_globa
27360 6c 5f 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b  l_recover(void);
27370 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 68  .void sqlite3_th
27380 72 65 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69  read_cleanup(voi
27390 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  d);.int sqlite3_
273a0 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69  memory_alarm(voi
273b0 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74  d(*)(void*,sqlit
273c0 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 76 6f  e3_int64,int),vo
273d0 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36  id*,sqlite3_int6
273e0 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  4);../*.** CAPI3
273f0 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53  REF: Obtaining S
27400 51 4c 20 46 75 6e 63 74 69 6f 6e 20 50 61 72 61  QL Function Para
27410 6d 65 74 65 72 20 56 61 6c 75 65 73 20 7b 46 31  meter Values {F1
27420 35 31 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20  5100}.**.** The 
27430 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c 65  C-language imple
27440 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c  mentation of SQL
27450 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61   functions and a
27460 67 67 72 65 67 61 74 65 73 20 75 73 65 73 0a 2a  ggregates uses.*
27470 2a 20 74 68 69 73 20 73 65 74 20 6f 66 20 69 6e  * this set of in
27480 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73  terface routines
27490 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 70   to access the p
274a0 61 72 61 6d 65 74 65 72 20 76 61 6c 75 65 73 20  arameter values 
274b0 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74 69  on.** the functi
274c0 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2e  on or aggregate.
274d0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63  .**.** The xFunc
274e0 20 28 66 6f 72 20 73 63 61 6c 61 72 20 66 75 6e   (for scalar fun
274f0 63 74 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 70  ctions) or xStep
27500 20 28 66 6f 72 20 61 67 67 72 65 67 61 74 65 73   (for aggregates
27510 29 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20  ) parameters.** 
27520 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  to [sqlite3_crea
27530 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61  te_function()] a
27540 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
27550 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
27560 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c 62  .** define callb
27570 61 63 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 6d  acks that implem
27580 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63  ent the SQL func
27590 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67  tions and aggreg
275a0 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20 34 74 68  ates..** The 4th
275b0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
275c0 65 73 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 73  ese callbacks is
275d0 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
275e0 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f  nters to.** [pro
275f0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
27600 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20  alue] objects.  
27610 54 68 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 71  There is one [sq
27620 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
27630 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20  ect for.** each 
27640 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
27650 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20   SQL function.  
27660 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
27670 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78  re used to.** ex
27680 74 72 61 63 74 20 76 61 6c 75 65 73 20 66 72 6f  tract values fro
27690 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  m the [sqlite3_v
276a0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  alue] objects..*
276b0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
276c0 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69  nes work only wi
276d0 74 68 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71  th [protected sq
276e0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
276f0 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74  ects..** Any att
27700 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 73  empt to use thes
27710 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e  e routines on an
27720 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
27730 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20  lite3_value].** 
27740 6f 62 6a 65 63 74 20 72 65 73 75 6c 74 73 20 69  object results i
27750 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61  n undefined beha
27760 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  vior..**.** Thes
27770 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20  e routines work 
27780 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 20 63 6f  just like the co
27790 72 72 65 73 70 6f 6e 64 69 6e 67 20 0a 2a 2a 20  rresponding .** 
277a0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
277b0 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 63  blob | sqlite3_c
277c0 6f 6c 75 6d 6e 5f 2a 20 72 6f 75 74 69 6e 65 73  olumn_* routines
277d0 5d 20 65 78 63 65 70 74 20 74 68 61 74 20 0a 2a  ] except that .*
277e0 2a 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * these routines
277f0 20 74 61 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b   take a single [
27800 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
27810 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
27820 70 6f 69 6e 74 65 72 0a 2a 2a 20 69 6e 73 74 65  pointer.** inste
27830 61 64 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65  ad of an [sqlite
27840 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72  3_stmt*] pointer
27850 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 65 72 20   and an integer 
27860 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a  column number..*
27870 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
27880 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 20  _value_text16() 
27890 69 6e 74 65 72 66 61 63 65 20 65 78 74 72 61 63  interface extrac
278a0 74 73 20 61 20 55 54 46 31 36 20 73 74 72 69 6e  ts a UTF16 strin
278b0 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74 69  g.** in the nati
278c0 76 65 20 62 79 74 65 2d 6f 72 64 65 72 20 6f 66  ve byte-order of
278d0 20 74 68 65 20 68 6f 73 74 20 6d 61 63 68 69 6e   the host machin
278e0 65 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74  e.  The.** sqlit
278f0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62  e3_value_text16b
27900 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  e() and sqlite3_
27910 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29  value_text16le()
27920 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 65   interfaces.** e
27930 78 74 72 61 63 74 20 55 54 46 31 36 20 73 74 72  xtract UTF16 str
27940 69 6e 67 73 20 61 73 20 62 69 67 2d 65 6e 64 69  ings as big-endi
27950 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e  an and little-en
27960 64 69 61 6e 20 72 65 73 70 65 63 74 69 76 65 6c  dian respectivel
27970 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  y..**.** The sql
27980 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72  ite3_value_numer
27990 69 63 5f 74 79 70 65 28 29 20 69 6e 74 65 72 66  ic_type() interf
279a0 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20  ace attempts to 
279b0 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63  apply.** numeric
279c0 20 61 66 66 69 6e 69 74 79 20 74 6f 20 74 68 65   affinity to the
279d0 20 76 61 6c 75 65 2e 20 20 54 68 69 73 20 6d 65   value.  This me
279e0 61 6e 73 20 74 68 61 74 20 61 6e 20 61 74 74 65  ans that an atte
279f0 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74  mpt is.** made t
27a00 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61  o convert the va
27a10 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  lue to an intege
27a20 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f  r or floating po
27a30 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68  int.  If.** such
27a40 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73   a conversion is
27a50 20 70 6f 73 73 69 62 6c 65 20 77 69 74 68 6f 75   possible withou
27a60 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d  t loss of inform
27a70 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65 72 0a  ation (in other.
27a80 2a 2a 20 77 6f 72 64 73 20 69 66 20 74 68 65 20  ** words if the 
27a90 76 61 6c 75 65 20 69 73 20 61 20 73 74 72 69 6e  value is a strin
27aa0 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b  g that looks lik
27ab0 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74  e a number).** t
27ac0 68 65 6e 20 74 68 65 20 63 6f 6e 76 65 72 73 69  hen the conversi
27ad0 6f 6e 20 69 73 20 64 6f 6e 65 2e 20 20 4f 74 68  on is done.  Oth
27ae0 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72  erwise no conver
27af0 73 69 6f 6e 20 6f 63 63 75 72 73 2e 20 20 54 68  sion occurs.  Th
27b00 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e  e .** [SQLITE_IN
27b10 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65  TEGER | datatype
27b20 5d 20 61 66 74 65 72 20 63 6f 6e 76 65 72 73 69  ] after conversi
27b30 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  on is returned..
27b40 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61 79  **.** Please pay
27b50 20 70 61 72 74 69 63 75 6c 61 72 20 61 74 74 65   particular atte
27b60 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20 66 61 63  ntion to the fac
27b70 74 20 74 68 61 74 20 74 68 65 20 70 6f 69 6e 74  t that the point
27b80 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 72 65  er that.** is re
27b90 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  turned from [sql
27ba0 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28  ite3_value_blob(
27bb0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  )], [sqlite3_val
27bc0 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a  ue_text()], or.*
27bd0 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  * [sqlite3_value
27be0 5f 74 65 78 74 31 36 28 29 5d 20 63 61 6e 20 62  _text16()] can b
27bf0 65 20 69 6e 76 61 6c 69 64 61 74 65 64 20 62 79  e invalidated by
27c00 20 61 20 73 75 62 73 65 71 75 65 6e 74 20 63 61   a subsequent ca
27c10 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
27c20 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d  3_value_bytes()]
27c30 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  , [sqlite3_value
27c40 5f 62 79 74 65 73 31 36 28 29 5d 2c 20 5b 73 71  _bytes16()], [sq
27c50 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
27c60 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  ()],.** or [sqli
27c70 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
27c80 28 29 5d 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65  ()].  .**.** The
27c90 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74  se routines must
27ca0 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
27cb0 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
27cc0 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75  as.** the SQL fu
27cd0 6e 63 74 69 6f 6e 20 74 68 61 74 20 73 75 70 70  nction that supp
27ce0 6c 69 65 64 20 74 68 65 20 5b 73 71 6c 69 74 65  lied the [sqlite
27cf0 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65  3_value*] parame
27d00 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 0a 2a 2a 20 49  ters..**.**.** I
27d10 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
27d20 20 7b 46 31 35 31 30 33 7d 20 54 68 65 20 5b 73   {F15103} The [s
27d30 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f  qlite3_value_blo
27d40 62 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20  b(V)] interface 
27d50 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20  converts the.** 
27d60 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63           [protec
27d70 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
27d80 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f  e] object V into
27d90 20 61 20 62 6c 6f 62 20 61 6e 64 20 74 68 65 6e   a blob and then
27da0 20 72 65 74 75 72 6e 73 20 61 0a 2a 2a 20 20 20   returns a.**   
27db0 20 20 20 20 20 20 20 70 6f 69 6e 74 65 72 20 74         pointer t
27dc0 6f 20 74 68 65 20 63 6f 6e 76 65 72 74 65 64 20  o the converted 
27dd0 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  value..**.** {F1
27de0 35 31 30 36 7d 20 54 68 65 20 5b 73 71 6c 69 74  5106} The [sqlit
27df0 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 56  e3_value_bytes(V
27e00 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
27e10 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  urns the.**     
27e20 20 20 20 20 20 6e 75 6d 62 65 72 20 6f 66 20 62       number of b
27e30 79 74 65 73 20 69 6e 20 74 68 65 20 62 6c 6f 62  ytes in the blob
27e40 20 6f 72 20 73 74 72 69 6e 67 20 28 65 78 63 6c   or string (excl
27e50 75 73 69 76 65 20 6f 66 20 74 68 65 0a 2a 2a 20  usive of the.** 
27e60 20 20 20 20 20 20 20 20 20 7a 65 72 6f 20 74 65           zero te
27e70 72 6d 69 6e 61 74 6f 72 20 6f 6e 20 74 68 65 20  rminator on the 
27e80 73 74 72 69 6e 67 29 20 74 68 61 74 20 77 61 73  string) that was
27e90 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
27ea0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 6f 73  .**          mos
27eb0 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f  t recent call to
27ec0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
27ed0 62 6c 6f 62 28 56 29 5d 20 6f 72 0a 2a 2a 20 20  blob(V)] or.**  
27ee0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
27ef0 5f 76 61 6c 75 65 5f 74 65 78 74 28 56 29 5d 2e  _value_text(V)].
27f00 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31 30 39 7d 20  .**.** {F15109} 
27f10 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  The [sqlite3_val
27f20 75 65 5f 62 79 74 65 73 31 36 28 56 29 5d 20 69  ue_bytes16(V)] i
27f30 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
27f40 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
27f50 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
27f60 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 20 28   in the string (
27f70 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65  exclusive of the
27f80 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72  .**          zer
27f90 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 6f 6e 20  o terminator on 
27fa0 74 68 65 20 73 74 72 69 6e 67 29 20 74 68 61 74  the string) that
27fb0 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 62 79   was returned by
27fc0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
27fd0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c   most recent cal
27fe0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 76 61  l to [sqlite3_va
27ff0 6c 75 65 5f 74 65 78 74 31 36 28 56 29 5d 2c 0a  lue_text16(V)],.
28000 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
28010 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
28020 36 62 65 28 56 29 5d 2c 20 6f 72 20 5b 73 71 6c  6be(V)], or [sql
28030 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
28040 36 6c 65 28 56 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  6le(V)]..**.** {
28050 46 31 35 31 31 32 7d 20 54 68 65 20 5b 73 71 6c  F15112} The [sql
28060 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c  ite3_value_doubl
28070 65 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20  e(V)] interface 
28080 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20  converts the.** 
28090 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63           [protec
280a0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
280b0 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f  e] object V into
280c0 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e   a floating poin
280d0 74 20 76 61 6c 75 65 20 61 6e 64 0a 2a 2a 20 20  t value and.**  
280e0 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 73 20          returns 
280f0 61 20 63 6f 70 79 20 6f 66 20 74 68 61 74 20 76  a copy of that v
28100 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35  alue..**.** {F15
28110 31 31 35 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  115} The [sqlite
28120 33 5f 76 61 6c 75 65 5f 69 6e 74 28 56 29 5d 20  3_value_int(V)] 
28130 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72  interface conver
28140 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ts the.**       
28150 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71     [protected sq
28160 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
28170 65 63 74 20 56 20 69 6e 74 6f 20 61 20 36 34 2d  ect V into a 64-
28180 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
28190 65 72 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20  er and.**       
281a0 20 20 20 72 65 74 75 72 6e 73 20 74 68 65 20 6c     returns the l
281b0 6f 77 65 72 20 33 32 20 62 69 74 73 20 6f 66 20  ower 32 bits of 
281c0 74 68 61 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a  that integer..**
281d0 0a 2a 2a 20 7b 46 31 35 31 31 38 7d 20 54 68 65  .** {F15118} The
281e0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
281f0 69 6e 74 36 34 28 56 29 5d 20 69 6e 74 65 72 66  int64(V)] interf
28200 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65  ace converts the
28210 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
28220 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
28230 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20  value] object V 
28240 69 6e 74 6f 20 61 20 36 34 2d 62 69 74 20 73 69  into a 64-bit si
28250 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64  gned integer and
28260 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74  .**          ret
28270 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74  urns a copy of t
28280 68 61 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a  hat integer..**.
28290 2a 2a 20 7b 46 31 35 31 32 31 7d 20 54 68 65 20  ** {F15121} The 
282a0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
282b0 65 78 74 28 56 29 5d 20 69 6e 74 65 72 66 61 63  ext(V)] interfac
282c0 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a  e converts the.*
282d0 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74  *          [prot
282e0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
282f0 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e  lue] object V in
28300 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  to a zero-termin
28310 61 74 65 64 20 55 54 46 2d 38 20 0a 2a 2a 20 20  ated UTF-8 .**  
28320 20 20 20 20 20 20 20 20 73 74 72 69 6e 67 20 61          string a
28330 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  nd returns a poi
28340 6e 74 65 72 20 74 6f 20 74 68 61 74 20 73 74 72  nter to that str
28350 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31  ing..**.** {F151
28360 32 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  24} The [sqlite3
28370 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 56 29  _value_text16(V)
28380 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76  ] interface conv
28390 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  erts the.**     
283a0 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20       [protected 
283b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
283c0 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20 7a  bject V into a z
283d0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 32  ero-terminated 2
283e0 2d 62 79 74 65 0a 2a 2a 20 20 20 20 20 20 20 20  -byte.**        
283f0 20 20 61 6c 69 67 6e 65 64 20 55 54 46 2d 31 36    aligned UTF-16
28400 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
28410 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73  er.**          s
28420 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e  tring and return
28430 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
28440 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  hat string..**.*
28450 2a 20 7b 46 31 35 31 32 37 7d 20 54 68 65 20 5b  * {F15127} The [
28460 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
28470 78 74 31 36 62 65 28 56 29 5d 20 69 6e 74 65 72  xt16be(V)] inter
28480 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68  face converts th
28490 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  e.**          [p
284a0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
284b0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56  _value] object V
284c0 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72   into a zero-ter
284d0 6d 69 6e 61 74 65 64 20 32 2d 62 79 74 65 0a 2a  minated 2-byte.*
284e0 2a 20 20 20 20 20 20 20 20 20 20 61 6c 69 67 6e  *          align
284f0 65 64 20 55 54 46 2d 31 36 20 62 69 67 2d 65 6e  ed UTF-16 big-en
28500 64 69 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  dian.**         
28510 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75   string and retu
28520 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
28530 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a   that string..**
28540 0a 2a 2a 20 7b 46 31 35 31 33 30 7d 20 54 68 65  .** {F15130} The
28550 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
28560 74 65 78 74 31 36 6c 65 28 56 29 5d 20 69 6e 74  text16le(V)] int
28570 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20  erface converts 
28580 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
28590 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
285a0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
285b0 20 56 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74   V into a zero-t
285c0 65 72 6d 69 6e 61 74 65 64 20 32 2d 62 79 74 65  erminated 2-byte
285d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c 69  .**          ali
285e0 67 6e 65 64 20 55 54 46 2d 31 36 20 6c 69 74 74  gned UTF-16 litt
285f0 6c 65 2d 65 6e 64 69 61 6e 0a 2a 2a 20 20 20 20  le-endian.**    
28600 20 20 20 20 20 20 73 74 72 69 6e 67 20 61 6e 64        string and
28610 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
28620 65 72 20 74 6f 20 74 68 61 74 20 73 74 72 69 6e  er to that strin
28630 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31 33 33  g..**.** {F15133
28640 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  } The [sqlite3_v
28650 61 6c 75 65 5f 74 79 70 65 28 56 29 5d 20 69 6e  alue_type(V)] in
28660 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a  terface returns.
28670 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 6e 65 20  **          one 
28680 6f 66 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d  of [SQLITE_NULL]
28690 2c 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  , [SQLITE_INTEGE
286a0 52 5d 2c 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41  R], [SQLITE_FLOA
286b0 54 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  T],.**          
286c0 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 6f  [SQLITE_TEXT], o
286d0 72 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 20  r [SQLITE_BLOB] 
286e0 61 73 20 61 70 70 72 6f 70 72 69 61 74 65 20 66  as appropriate f
286f0 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  or.**          t
28700 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
28710 65 5d 20 6f 62 6a 65 63 74 20 56 2e 0a 2a 2a 0a  e] object V..**.
28720 2a 2a 20 7b 46 31 35 31 33 36 7d 20 54 68 65 20  ** {F15136} The 
28730 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e  [sqlite3_value_n
28740 75 6d 65 72 69 63 5f 74 79 70 65 28 56 29 5d 20  umeric_type(V)] 
28750 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72  interface conver
28760 74 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  ts.**          t
28770 68 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71  he [protected sq
28780 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
28790 65 63 74 20 56 20 69 6e 74 6f 20 65 69 74 68 65  ect V into eithe
287a0 72 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 0a  r an integer or.
287b0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 66 6c  **          a fl
287c0 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
287d0 75 65 20 69 66 20 69 74 20 63 61 6e 20 64 6f 20  ue if it can do 
287e0 73 6f 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20  so without loss 
287f0 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  of.**          i
28800 6e 66 6f 72 6d 61 74 69 6f 6e 2c 20 61 6e 64 20  nformation, and 
28810 72 65 74 75 72 6e 73 20 6f 6e 65 20 6f 66 20 5b  returns one of [
28820 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2c 0a 2a 2a  SQLITE_NULL],.**
28830 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54            [SQLIT
28840 45 5f 49 4e 54 45 47 45 52 5d 2c 20 5b 53 51 4c  E_INTEGER], [SQL
28850 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c  ITE_FLOAT], [SQL
28860 49 54 45 5f 54 45 58 54 5d 2c 20 6f 72 0a 2a 2a  ITE_TEXT], or.**
28870 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54            [SQLIT
28880 45 5f 42 4c 4f 42 5d 20 61 73 20 61 70 70 72 6f  E_BLOB] as appro
28890 70 72 69 61 74 65 20 66 6f 72 0a 2a 2a 20 20 20  priate for.**   
288a0 20 20 20 20 20 20 20 74 68 65 20 5b 70 72 6f 74         the [prot
288b0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
288c0 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 61 66  lue] object V af
288d0 74 65 72 20 74 68 65 20 63 6f 6e 76 65 72 73 69  ter the conversi
288e0 6f 6e 20 61 74 74 65 6d 70 74 2e 0a 2a 2f 0a 63  on attempt..*/.c
288f0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
28900 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71  e3_value_blob(sq
28910 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
28920 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
28930 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 76  _bytes(sqlite3_v
28940 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
28950 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31  te3_value_bytes1
28960 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  6(sqlite3_value*
28970 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65  );.double sqlite
28980 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73  3_value_double(s
28990 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
289a0 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
289b0 65 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 61  e_int(sqlite3_va
289c0 6c 75 65 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 69  lue*);.sqlite3_i
289d0 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 76 61 6c  nt64 sqlite3_val
289e0 75 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33  ue_int64(sqlite3
289f0 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20  _value*);.const 
28a00 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73  unsigned char *s
28a10 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
28a20 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t(sqlite3_value*
28a30 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
28a40 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
28a50 74 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  t16(sqlite3_valu
28a60 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  e*);.const void 
28a70 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  *sqlite3_value_t
28a80 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f  ext16le(sqlite3_
28a90 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76  value*);.const v
28aa0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  oid *sqlite3_val
28ab0 75 65 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69  ue_text16be(sqli
28ac0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
28ad0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
28ae0 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ype(sqlite3_valu
28af0 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
28b00 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74  _value_numeric_t
28b10 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ype(sqlite3_valu
28b20 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  e*);../*.** CAPI
28b30 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 67 67  3REF: Obtain Agg
28b40 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f 6e 20  regate Function 
28b50 43 6f 6e 74 65 78 74 20 7b 46 31 36 32 31 30 7d  Context {F16210}
28b60 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6d 70 6c 65  .**.** The imple
28b70 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 67 67  mentation of agg
28b80 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74  regate SQL funct
28b90 69 6f 6e 73 20 75 73 65 20 74 68 69 73 20 72 6f  ions use this ro
28ba0 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74  utine to allocat
28bb0 65 0a 2a 2a 20 61 20 73 74 72 75 63 74 75 72 65  e.** a structure
28bc0 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68 65   for storing the
28bd0 69 72 20 73 74 61 74 65 2e 20 20 0a 2a 2a 20 54  ir state.  .** T
28be0 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 68  he first time th
28bf0 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  e sqlite3_aggreg
28c00 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 72 6f  ate_context() ro
28c10 75 74 69 6e 65 20 69 73 0a 2a 2a 20 69 73 20 63  utine is.** is c
28c20 61 6c 6c 65 64 20 66 6f 72 20 61 20 70 61 72 74  alled for a part
28c30 69 63 75 6c 61 72 20 61 67 67 72 65 67 61 74 65  icular aggregate
28c40 2c 20 53 51 4c 69 74 65 20 61 6c 6c 6f 63 61 74  , SQLite allocat
28c50 65 73 20 6e 42 79 74 65 73 20 6f 66 20 6d 65 6d  es nBytes of mem
28c60 6f 72 79 0a 2a 2a 20 7a 65 72 6f 73 20 74 68 61  ory.** zeros tha
28c70 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65  t memory, and re
28c80 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
28c90 74 6f 20 69 74 2e 0a 2a 2a 20 4f 6e 20 73 65 63  to it..** On sec
28ca0 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65  ond and subseque
28cb0 6e 74 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  nt calls to sqli
28cc0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
28cd0 6e 74 65 78 74 28 29 0a 2a 2a 20 66 6f 72 20 74  ntext().** for t
28ce0 68 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 74  he same aggregat
28cf0 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 64 65 78  e function index
28d00 2c 20 74 68 65 20 73 61 6d 65 20 62 75 66 66 65  , the same buffe
28d10 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  r is returned..*
28d20 2a 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  * The implementa
28d30 74 69 6f 6e 0a 2a 2a 20 6f 66 20 74 68 65 20 61  tion.** of the a
28d40 67 67 72 65 67 61 74 65 20 63 61 6e 20 75 73 65  ggregate can use
28d50 20 74 68 65 20 72 65 74 75 72 6e 65 64 20 62 75   the returned bu
28d60 66 66 65 72 20 74 6f 20 61 63 63 75 6d 75 6c 61  ffer to accumula
28d70 74 65 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53  te data..**.** S
28d80 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61  QLite automatica
28d90 6c 6c 79 20 66 72 65 65 73 20 74 68 65 20 61 6c  lly frees the al
28da0 6c 6f 63 61 74 65 64 20 62 75 66 66 65 72 20 77  located buffer w
28db0 68 65 6e 20 74 68 65 20 61 67 67 72 65 67 61 74  hen the aggregat
28dc0 65 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6e 63 6c  e.** query concl
28dd0 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  udes..**.** The 
28de0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
28df0 73 68 6f 75 6c 64 20 62 65 20 61 20 63 6f 70 79  should be a copy
28e00 20 6f 66 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c   of the .** [sql
28e10 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53  ite3_context | S
28e20 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74  QL function cont
28e30 65 78 74 5d 20 74 68 61 74 20 69 73 20 74 68 65  ext] that is the
28e40 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65   first.** parame
28e50 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  ter to the callb
28e60 61 63 6b 20 72 6f 75 74 69 6e 65 20 74 68 61 74  ack routine that
28e70 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20   implements the 
28e80 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 66 75 6e  aggregate.** fun
28e90 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  ction..**.** Thi
28ea0 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62  s routine must b
28eb0 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
28ec0 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e  e same thread in
28ed0 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 67   which.** the ag
28ee0 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63  gregate SQL func
28ef0 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e  tion is running.
28f00 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
28f10 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32 31 31  S:.**.** {F16211
28f20 7d 20 54 68 65 20 66 69 72 73 74 20 69 6e 76 6f  } The first invo
28f30 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74  cation of [sqlit
28f40 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
28f50 74 65 78 74 28 43 2c 4e 29 5d 20 66 6f 72 0a 2a  text(C,N)] for.*
28f60 2a 20 20 20 20 20 20 20 20 20 20 61 20 70 61 72  *          a par
28f70 74 69 63 75 6c 61 72 20 69 6e 73 74 61 6e 63 65  ticular instance
28f80 20 6f 66 20 61 6e 20 61 67 67 72 65 67 61 74 65   of an aggregate
28f90 20 66 75 6e 63 74 69 6f 6e 20 28 66 6f 72 20 61   function (for a
28fa0 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 20   particular.**  
28fb0 20 20 20 20 20 20 20 20 63 6f 6e 74 65 78 74 20          context 
28fc0 43 29 20 63 61 75 73 65 73 20 53 51 4c 69 74 65  C) causes SQLite
28fd0 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 4e   to allocation N
28fe0 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79   bytes of memory
28ff0 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65  ,.**          ze
29000 72 6f 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c 20  ro that memory, 
29010 61 6e 64 20 72 65 74 75 72 6e 20 61 20 70 6f 69  and return a poi
29020 6e 74 65 72 20 74 6f 20 74 68 65 20 61 6c 6c 6f  nter to the allo
29030 63 61 74 69 6f 6e 65 64 0a 2a 2a 20 20 20 20 20  cationed.**     
29040 20 20 20 20 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 0a       memory..**.
29050 2a 2a 20 7b 46 31 36 32 31 33 7d 20 49 66 20 61  ** {F16213} If a
29060 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
29070 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  on error occurs 
29080 64 75 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20  during.**       
29090 20 20 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72     [sqlite3_aggr
290a0 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c  egate_context(C,
290b0 4e 29 5d 20 74 68 65 6e 20 74 68 65 20 66 75 6e  N)] then the fun
290c0 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 30 2e  ction returns 0.
290d0 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32 31 35 7d 20  .**.** {F16215} 
290e0 53 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65  Second and subse
290f0 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e  quent invocation
29100 73 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20  s of.**         
29110 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67   [sqlite3_aggreg
29120 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29  ate_context(C,N)
29130 5d 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 63  ] for the same c
29140 6f 6e 74 65 78 74 20 70 6f 69 6e 74 65 72 20 43  ontext pointer C
29150 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 67 6e  .**          ign
29160 6f 72 65 20 74 68 65 20 4e 20 70 61 72 61 6d 65  ore the N parame
29170 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e 20 61  ter and return a
29180 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
29190 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  same.**         
291a0 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79   block of memory
291b0 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
291c0 20 66 69 72 73 74 20 69 6e 76 6f 63 61 74 69 6f   first invocatio
291d0 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32 31 37  n..**.** {F16217
291e0 7d 20 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  } The memory all
291f0 6f 63 61 74 65 64 20 62 79 20 5b 73 71 6c 69 74  ocated by [sqlit
29200 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
29210 74 65 78 74 28 43 2c 4e 29 5d 20 69 73 0a 2a 2a  text(C,N)] is.**
29220 20 20 20 20 20 20 20 20 20 20 61 75 74 6f 6d 61            automa
29230 74 69 63 61 6c 6c 79 20 66 72 65 65 64 20 6f 6e  tically freed on
29240 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 74   the next call t
29250 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  o [sqlite3_reset
29260 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ()].**          
29270 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
29280 6c 69 7a 65 28 29 5d 20 66 6f 72 20 74 68 65 20  lize()] for the 
29290 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
292a0 65 6e 74 5d 20 63 6f 6e 74 61 69 6e 69 6e 67 0a  ent] containing.
292b0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
292c0 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69  aggregate functi
292d0 6f 6e 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  on associated wi
292e0 74 68 20 63 6f 6e 74 65 78 74 20 43 2e 0a 2a 2f  th context C..*/
292f0 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 61  .void *sqlite3_a
29300 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
29310 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
29320 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a  *, int nBytes);.
29330 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
29340 20 55 73 65 72 20 44 61 74 61 20 46 6f 72 20 46   User Data For F
29350 75 6e 63 74 69 6f 6e 73 20 7b 46 31 36 32 34 30  unctions {F16240
29360 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  }.**.** The sqli
29370 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 20  te3_user_data() 
29380 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
29390 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74  s a copy of.** t
293a0 68 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20  he pointer that 
293b0 77 61 73 20 74 68 65 20 70 55 73 65 72 44 61 74  was the pUserDat
293c0 61 20 70 61 72 61 6d 65 74 65 72 20 28 74 68 65  a parameter (the
293d0 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 29 0a   5th parameter).
293e0 2a 2a 20 6f 66 20 74 68 65 20 74 68 65 20 5b 73  ** of the the [s
293f0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
29400 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64  nction()].** and
29410 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
29420 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72  _function16()] r
29430 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69  outines that ori
29440 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73  ginally.** regis
29450 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63  tered the applic
29460 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75  ation defined fu
29470 6e 63 74 69 6f 6e 2e 20 7b 45 4e 44 7d 0a 2a 2a  nction. {END}.**
29480 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
29490 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
294a0 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68  from the same th
294b0 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a  read in which.**
294c0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
294d0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
294e0 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a  n is running..**
294f0 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
29500 2a 2a 0a 2a 2a 20 7b 46 31 36 32 34 33 7d 20 54  **.** {F16243} T
29510 68 65 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72  he [sqlite3_user
29520 5f 64 61 74 61 28 43 29 5d 20 69 6e 74 65 72 66  _data(C)] interf
29530 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f  ace returns a co
29540 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20  py of the.**    
29550 20 20 20 20 20 20 50 20 70 6f 69 6e 74 65 72 20        P pointer 
29560 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65  from the [sqlite
29570 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
29580 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c  n(D,X,N,E,P,F,S,
29590 4c 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  L)].**          
295a0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  or [sqlite3_crea
295b0 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 44 2c  te_function16(D,
295c0 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 20  X,N,E,P,F,S,L)] 
295d0 63 61 6c 6c 20 74 68 61 74 0a 2a 2a 20 20 20 20  call that.**    
295e0 20 20 20 20 20 20 72 65 67 69 73 74 65 72 65 64        registered
295f0 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
29600 6e 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  n associated wit
29610 68 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  h .**          [
29620 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d  sqlite3_context]
29630 20 43 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c   C..*/.void *sql
29640 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 73  ite3_user_data(s
29650 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
29660 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
29670 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e  F: Database Conn
29680 65 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74  ection For Funct
29690 69 6f 6e 73 20 7b 46 31 36 32 35 30 7d 0a 2a 2a  ions {F16250}.**
296a0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
296b0 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c  context_db_handl
296c0 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  e() interface re
296d0 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a  turns a copy of.
296e0 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74  ** the pointer t
296f0 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  o the [database 
29700 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 68 65  connection] (the
29710 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 29 0a   1st parameter).
29720 2a 2a 20 6f 66 20 74 68 65 20 74 68 65 20 5b 73  ** of the the [s
29730 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
29740 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64  nction()].** and
29750 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
29760 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72  _function16()] r
29770 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69  outines that ori
29780 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73  ginally.** regis
29790 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63  tered the applic
297a0 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75  ation defined fu
297b0 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 4e  nction..**.** IN
297c0 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
297d0 7b 46 31 36 32 35 33 7d 20 54 68 65 20 5b 73 71  {F16253} The [sq
297e0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62  lite3_context_db
297f0 5f 68 61 6e 64 6c 65 28 43 29 5d 20 69 6e 74 65  _handle(C)] inte
29800 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
29810 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 20  copy of the.**  
29820 20 20 20 20 20 20 20 20 44 20 70 6f 69 6e 74 65          D pointe
29830 72 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69  r from the [sqli
29840 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
29850 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c  ion(D,X,N,E,P,F,
29860 53 2c 4c 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  S,L)].**        
29870 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63 72    or [sqlite3_cr
29880 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
29890 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29  D,X,N,E,P,F,S,L)
298a0 5d 20 63 61 6c 6c 20 74 68 61 74 0a 2a 2a 20 20  ] call that.**  
298b0 20 20 20 20 20 20 20 20 72 65 67 69 73 74 65 72          register
298c0 65 64 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  ed the SQL funct
298d0 69 6f 6e 20 61 73 73 6f 63 69 61 74 65 64 20 77  ion associated w
298e0 69 74 68 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  ith .**         
298f0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   [sqlite3_contex
29900 74 5d 20 43 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33  t] C..*/.sqlite3
29910 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   *sqlite3_contex
29920 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69  t_db_handle(sqli
29930 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a  te3_context*);..
29940 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
29950 46 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c 69 61  Function Auxilia
29960 72 79 20 44 61 74 61 20 7b 46 31 36 32 37 30 7d  ry Data {F16270}
29970 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f  .**.** The follo
29980 77 69 6e 67 20 74 77 6f 20 66 75 6e 63 74 69 6f  wing two functio
29990 6e 73 20 6d 61 79 20 62 65 20 75 73 65 64 20 62  ns may be used b
299a0 79 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e  y scalar SQL fun
299b0 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73  ctions to.** ass
299c0 6f 63 69 61 74 65 20 6d 65 74 61 2d 64 61 74 61  ociate meta-data
299d0 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 76   with argument v
299e0 61 6c 75 65 73 2e 20 49 66 20 74 68 65 20 73 61  alues. If the sa
299f0 6d 65 20 76 61 6c 75 65 20 69 73 20 70 61 73 73  me value is pass
29a00 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c  ed to.** multipl
29a10 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66  e invocations of
29a20 20 74 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75   the same SQL fu
29a30 6e 63 74 69 6f 6e 20 64 75 72 69 6e 67 20 71 75  nction during qu
29a40 65 72 79 20 65 78 65 63 75 74 69 6f 6e 2c 20 75  ery execution, u
29a50 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72  nder.** some cir
29a60 63 75 6d 73 74 61 6e 63 65 73 20 74 68 65 20 61  cumstances the a
29a70 73 73 6f 63 69 61 74 65 64 20 6d 65 74 61 2d 64  ssociated meta-d
29a80 61 74 61 20 6d 61 79 20 62 65 20 70 72 65 73 65  ata may be prese
29a90 72 76 65 64 2e 20 54 68 69 73 20 6d 61 79 0a 2a  rved. This may.*
29aa0 2a 20 62 65 20 75 73 65 64 2c 20 66 6f 72 20 65  * be used, for e
29ab0 78 61 6d 70 6c 65 2c 20 74 6f 20 61 64 64 20 61  xample, to add a
29ac0 20 72 65 67 75 6c 61 72 2d 65 78 70 72 65 73 73   regular-express
29ad0 69 6f 6e 20 6d 61 74 63 68 69 6e 67 20 73 63 61  ion matching sca
29ae0 6c 61 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e  lar.** function.
29af0 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 76 65   The compiled ve
29b00 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 72 65 67  rsion of the reg
29b10 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20  ular expression 
29b20 69 73 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20  is stored as.** 
29b30 6d 65 74 61 2d 64 61 74 61 20 61 73 73 6f 63 69  meta-data associ
29b40 61 74 65 64 20 77 69 74 68 20 74 68 65 20 53 51  ated with the SQ
29b50 4c 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61  L value passed a
29b60 73 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 78  s the regular ex
29b70 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 70 61 74 74  pression.** patt
29b80 65 72 6e 2e 20 20 54 68 65 20 63 6f 6d 70 69 6c  ern.  The compil
29b90 65 64 20 72 65 67 75 6c 61 72 20 65 78 70 72 65  ed regular expre
29ba0 73 73 69 6f 6e 20 63 61 6e 20 62 65 20 72 65 75  ssion can be reu
29bb0 73 65 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a  sed on multiple.
29bc0 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f  ** invocations o
29bd0 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74  f the same funct
29be0 69 6f 6e 20 73 6f 20 74 68 61 74 20 74 68 65 20  ion so that the 
29bf0 6f 72 69 67 69 6e 61 6c 20 70 61 74 74 65 72 6e  original pattern
29c00 20 73 74 72 69 6e 67 0a 2a 2a 20 64 6f 65 73 20   string.** does 
29c10 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 72  not need to be r
29c20 65 63 6f 6d 70 69 6c 65 64 20 6f 6e 20 65 61 63  ecompiled on eac
29c30 68 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a  h invocation..**
29c40 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
29c50 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e  get_auxdata() in
29c60 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
29c70 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
29c80 20 6d 65 74 61 2d 64 61 74 61 0a 2a 2a 20 61 73   meta-data.** as
29c90 73 6f 63 69 61 74 65 64 20 62 79 20 74 68 65 20  sociated by the 
29ca0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
29cb0 61 74 61 28 29 20 66 75 6e 63 74 69 6f 6e 20 77  ata() function w
29cc0 69 74 68 20 74 68 65 20 4e 74 68 20 61 72 67 75  ith the Nth argu
29cd0 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f  ment.** value to
29ce0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
29cf0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
29d00 6e 2e 0a 2a 2a 20 49 66 20 6e 6f 20 6d 65 74 61  n..** If no meta
29d10 2d 64 61 74 61 20 68 61 73 20 62 65 65 6e 20 65  -data has been e
29d20 76 65 72 20 62 65 65 6e 20 73 65 74 20 66 6f 72  ver been set for
29d30 20 74 68 65 20 4e 74 68 0a 2a 2a 20 61 72 67 75   the Nth.** argu
29d40 6d 65 6e 74 20 6f 66 20 74 68 65 20 66 75 6e 63  ment of the func
29d50 74 69 6f 6e 2c 20 6f 72 20 69 66 20 74 68 65 20  tion, or if the 
29d60 63 6f 6f 72 65 73 70 6f 6e 64 69 6e 67 20 66 75  cooresponding fu
29d70 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72  nction parameter
29d80 0a 2a 2a 20 68 61 73 20 63 68 61 6e 67 65 64 20  .** has changed 
29d90 73 69 6e 63 65 20 74 68 65 20 6d 65 74 61 2d 64  since the meta-d
29da0 61 74 61 20 77 61 73 20 73 65 74 2c 20 74 68 65  ata was set, the
29db0 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75  n sqlite3_get_au
29dc0 78 64 61 74 61 28 29 0a 2a 2a 20 72 65 74 75 72  xdata().** retur
29dd0 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ns a NULL pointe
29de0 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  r..**.** The sql
29df0 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
29e00 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 61 76  () interface sav
29e10 65 73 20 74 68 65 20 6d 65 74 61 2d 64 61 74 61  es the meta-data
29e20 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  .** pointed to b
29e30 79 20 69 74 73 20 33 72 64 20 70 61 72 61 6d 65  y its 3rd parame
29e40 74 65 72 20 61 73 20 74 68 65 20 6d 65 74 61 2d  ter as the meta-
29e50 64 61 74 61 20 66 6f 72 20 74 68 65 20 4e 2d 74  data for the N-t
29e60 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6f 66  h.** argument of
29e70 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
29e80 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
29e90 6e 2e 20 20 53 75 62 73 65 71 75 65 6e 74 0a 2a  n.  Subsequent.*
29ea0 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  * calls to sqlit
29eb0 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29  e3_get_auxdata()
29ec0 20 6d 69 67 68 74 20 72 65 74 75 72 6e 20 74 68   might return th
29ed0 69 73 20 64 61 74 61 2c 20 69 66 20 69 74 20 68  is data, if it h
29ee0 61 73 0a 2a 2a 20 6e 6f 74 20 62 65 65 6e 20 64  as.** not been d
29ef0 65 73 74 72 6f 79 65 64 2e 20 0a 2a 2a 20 49 66  estroyed. .** If
29f00 20 69 74 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c   it is not NULL,
29f10 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76   SQLite will inv
29f20 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75 63 74  oke the destruct
29f30 6f 72 20 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  or .** function 
29f40 67 69 76 65 6e 20 62 79 20 74 68 65 20 34 74 68  given by the 4th
29f50 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
29f60 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
29f70 61 28 29 20 6f 6e 0a 2a 2a 20 74 68 65 20 6d 65  a() on.** the me
29f80 74 61 2d 64 61 74 61 20 77 68 65 6e 20 74 68 65  ta-data when the
29f90 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 66   corresponding f
29fa0 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65  unction paramete
29fb0 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f 72 20  r changes.** or 
29fc0 77 68 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61  when the SQL sta
29fd0 74 65 6d 65 6e 74 20 63 6f 6d 70 6c 65 74 65 73  tement completes
29fe0 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65  , whichever come
29ff0 73 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a 20 53  s first..**.** S
2a000 51 4c 69 74 65 20 69 73 20 66 72 65 65 20 74 6f  QLite is free to
2a010 20 63 61 6c 6c 20 74 68 65 20 64 65 73 74 72 75   call the destru
2a020 63 74 6f 72 20 61 6e 64 20 64 72 6f 70 20 6d 65  ctor and drop me
2a030 74 61 2d 64 61 74 61 20 6f 6e 0a 2a 2a 20 61 6e  ta-data on.** an
2a040 79 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 61  y parameter of a
2a050 6e 79 20 66 75 6e 63 74 69 6f 6e 20 61 74 20 61  ny function at a
2a060 6e 79 20 74 69 6d 65 2e 20 20 54 68 65 20 6f 6e  ny time.  The on
2a070 6c 79 20 67 75 61 72 61 6e 74 65 65 0a 2a 2a 20  ly guarantee.** 
2a080 69 73 20 74 68 61 74 20 74 68 65 20 64 65 73 74  is that the dest
2a090 72 75 63 74 6f 72 20 77 69 6c 6c 20 62 65 20 63  ructor will be c
2a0a0 61 6c 6c 65 64 20 62 65 66 6f 72 65 20 74 68 65  alled before the
2a0b0 20 6d 65 74 61 64 61 74 61 20 69 73 0a 2a 2a 20   metadata is.** 
2a0c0 64 72 6f 70 70 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  dropped..**.** I
2a0d0 6e 20 70 72 61 63 74 69 63 65 2c 20 6d 65 74 61  n practice, meta
2a0e0 2d 64 61 74 61 20 69 73 20 70 72 65 73 65 72 76  -data is preserv
2a0f0 65 64 20 62 65 74 77 65 65 6e 20 66 75 6e 63 74  ed between funct
2a100 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a  ion calls for.**
2a110 20 65 78 70 72 65 73 73 69 6f 6e 73 20 74 68 61   expressions tha
2a120 74 20 61 72 65 20 63 6f 6e 73 74 61 6e 74 20 61  t are constant a
2a130 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20  t compile time. 
2a140 54 68 69 73 20 69 6e 63 6c 75 64 65 73 20 6c 69  This includes li
2a150 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20  teral.** values 
2a160 61 6e 64 20 53 51 4c 20 76 61 72 69 61 62 6c 65  and SQL variable
2a170 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  s..**.** These r
2a180 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20  outines must be 
2a190 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
2a1a0 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77  same thread in w
2a1b0 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20  hich.** the SQL 
2a1c0 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
2a1d0 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ing..**.** INVAR
2a1e0 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31  IANTS:.**.** {F1
2a1f0 36 32 37 32 7d 20 54 68 65 20 5b 73 71 6c 69 74  6272} The [sqlit
2a200 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 43  e3_get_auxdata(C
2a210 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  ,N)] interface r
2a220 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
2a230 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20  .**          to 
2a240 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63 69 61  metadata associa
2a250 74 65 64 20 77 69 74 68 20 74 68 65 20 4e 74 68  ted with the Nth
2a260 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68   parameter of th
2a270 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 0a 2a  e SQL function.*
2a280 2a 20 20 20 20 20 20 20 20 20 20 77 68 6f 73 65  *          whose
2a290 20 63 6f 6e 74 65 78 74 20 69 73 20 43 2c 20 6f   context is C, o
2a2a0 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 72 65 20  r NULL if there 
2a2b0 69 73 20 6e 6f 20 6d 65 74 61 64 61 74 61 20 61  is no metadata a
2a2c0 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 20 20 20  ssociated.**    
2a2d0 20 20 20 20 20 20 77 69 74 68 20 74 68 61 74 20        with that 
2a2e0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
2a2f0 20 7b 46 31 36 32 37 34 7d 20 54 68 65 20 5b 73   {F16274} The [s
2a300 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
2a310 74 61 28 43 2c 4e 2c 50 2c 44 29 5d 20 69 6e 74  ta(C,N,P,D)] int
2a320 65 72 66 61 63 65 20 61 73 73 69 67 6e 73 20 61  erface assigns a
2a330 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 20 20 20   metadata.**    
2a340 20 20 20 20 20 20 70 6f 69 6e 74 65 72 20 50 20        pointer P 
2a350 74 6f 20 74 68 65 20 4e 74 68 20 70 61 72 61 6d  to the Nth param
2a360 65 74 65 72 20 6f 66 20 74 68 65 20 53 51 4c 20  eter of the SQL 
2a370 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 63 6f  function with co
2a380 6e 74 65 78 74 0a 2a 2a 20 20 20 20 20 20 20 20  ntext.**        
2a390 20 20 43 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32    C..**.** {F162
2a3a0 37 36 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  76} SQLite will 
2a3b0 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72  invoke the destr
2a3c0 75 63 74 6f 72 20 44 20 77 69 74 68 20 61 20 73  uctor D with a s
2a3d0 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 0a 2a  ingle argument.*
2a3e0 2a 20 20 20 20 20 20 20 20 20 20 77 68 69 63 68  *          which
2a3f0 20 69 73 20 74 68 65 20 6d 65 74 61 64 61 74 61   is the metadata
2a400 20 70 6f 69 6e 74 65 72 20 50 20 66 6f 6c 6c 6f   pointer P follo
2a410 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 0a 2a  wing a call to.*
2a420 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
2a430 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
2a440 43 2c 4e 2c 50 2c 44 29 5d 20 77 68 65 6e 20 53  C,N,P,D)] when S
2a450 51 4c 69 74 65 20 63 65 61 73 65 73 20 74 6f 20  QLite ceases to 
2a460 68 6f 6c 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  hold.**         
2a470 20 74 68 65 20 6d 65 74 61 64 61 74 61 2e 0a 2a   the metadata..*
2a480 2a 0a 2a 2a 20 7b 46 31 36 32 37 37 7d 20 53 51  *.** {F16277} SQ
2a490 4c 69 74 65 20 63 65 61 73 65 73 20 74 6f 20 68  Lite ceases to h
2a4a0 6f 6c 64 20 6d 65 74 61 64 61 74 61 20 66 6f 72  old metadata for
2a4b0 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e   an SQL function
2a4c0 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20   parameter.**   
2a4d0 20 20 20 20 20 20 20 77 68 65 6e 20 74 68 65 20         when the 
2a4e0 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20 70 61  value of that pa
2a4f0 72 61 6d 65 74 65 72 20 63 68 61 6e 67 65 73 2e  rameter changes.
2a500 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32 37 38 7d 20  .**.** {F16278} 
2a510 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 73 65  When [sqlite3_se
2a520 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c  t_auxdata(C,N,P,
2a530 44 29 5d 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20  D)] is invoked, 
2a540 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a  the destructor.*
2a550 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 63 61  *          is ca
2a560 6c 6c 65 64 20 66 6f 72 20 61 6e 79 20 70 72 69  lled for any pri
2a570 6f 72 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f  or metadata asso
2a580 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
2a590 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  same function.**
2a5a0 20 20 20 20 20 20 20 20 20 20 63 6f 6e 74 65 78            contex
2a5b0 74 20 43 20 61 6e 64 20 70 61 72 61 6d 65 74 65  t C and paramete
2a5c0 72 20 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32  r N..**.** {F162
2a5d0 37 39 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  79} SQLite will 
2a5e0 63 61 6c 6c 20 64 65 73 74 72 75 63 74 6f 72 73  call destructors
2a5f0 20 66 6f 72 20 61 6e 79 20 6d 65 74 61 64 61 74   for any metadat
2a600 61 20 69 74 20 69 73 20 68 6f 6c 64 69 6e 67 0a  a it is holding.
2a610 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 61  **          in a
2a620 20 70 61 72 74 69 63 75 6c 61 72 20 5b 70 72 65   particular [pre
2a630 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2a640 20 53 20 77 68 65 6e 20 65 69 74 68 65 72 0a 2a   S when either.*
2a650 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
2a660 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 6f 72  te3_reset(S)] or
2a670 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2a680 7a 65 28 53 29 5d 20 69 73 20 63 61 6c 6c 65 64  ze(S)] is called
2a690 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
2a6a0 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 73  e3_get_auxdata(s
2a6b0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2a6c0 20 69 6e 74 20 4e 29 3b 0a 76 6f 69 64 20 73 71   int N);.void sq
2a6d0 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
2a6e0 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  a(sqlite3_contex
2a6f0 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f 69 64 2a  t*, int N, void*
2a700 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f 69 64 2a  , void (*)(void*
2a710 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ));.../*.** CAPI
2a720 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74 73 20  3REF: Constants 
2a730 44 65 66 69 6e 69 6e 67 20 53 70 65 63 69 61 6c  Defining Special
2a740 20 44 65 73 74 72 75 63 74 6f 72 20 42 65 68 61   Destructor Beha
2a750 76 69 6f 72 20 7b 46 31 30 32 38 30 7d 0a 2a 2a  vior {F10280}.**
2a760 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 73 70  .** These are sp
2a770 65 63 69 61 6c 20 76 61 6c 75 65 20 66 6f 72 20  ecial value for 
2a780 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 74  the destructor t
2a790 68 61 74 20 69 73 20 70 61 73 73 65 64 20 69 6e  hat is passed in
2a7a0 20 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c   as the.** final
2a7b0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75   argument to rou
2a7c0 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69  tines like [sqli
2a7d0 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28  te3_result_blob(
2a7e0 29 5d 2e 20 20 49 66 20 74 68 65 20 64 65 73 74  )].  If the dest
2a7f0 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65  ructor.** argume
2a800 6e 74 20 69 73 20 53 51 4c 49 54 45 5f 53 54 41  nt is SQLITE_STA
2a810 54 49 43 2c 20 69 74 20 6d 65 61 6e 73 20 74 68  TIC, it means th
2a820 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 70  at the content p
2a830 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e 73 74 61  ointer is consta
2a840 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e  nt.** and will n
2a850 65 76 65 72 20 63 68 61 6e 67 65 2e 20 20 49 74  ever change.  It
2a860 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
2a870 6f 20 62 65 20 64 65 73 74 72 6f 79 65 64 2e 20  o be destroyed. 
2a880 20 54 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f   The .** SQLITE_
2a890 54 52 41 4e 53 49 45 4e 54 20 76 61 6c 75 65 20  TRANSIENT value 
2a8a0 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 63  means that the c
2a8b0 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65  ontent will like
2a8c0 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20  ly change in.** 
2a8d0 74 68 65 20 6e 65 61 72 20 66 75 74 75 72 65 20  the near future 
2a8e0 61 6e 64 20 74 68 61 74 20 53 51 4c 69 74 65 20  and that SQLite 
2a8f0 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73 20  should make its 
2a900 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79  own private copy
2a910 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65   of.** the conte
2a920 6e 74 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e  nt before return
2a930 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  ing..**.** The t
2a940 79 70 65 64 65 66 20 69 73 20 6e 65 63 65 73 73  ypedef is necess
2a950 61 72 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75  ary to work arou
2a960 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63  nd problems in c
2a970 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f  ertain.** C++ co
2a980 6d 70 69 6c 65 72 73 2e 20 20 53 65 65 20 74 69  mpilers.  See ti
2a990 63 6b 65 74 20 23 32 31 39 31 2e 0a 2a 2f 0a 74  cket #2191..*/.t
2a9a0 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71  ypedef void (*sq
2a9b0 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72  lite3_destructor
2a9c0 5f 74 79 70 65 29 28 76 6f 69 64 2a 29 3b 0a 23  _type)(void*);.#
2a9d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54  define SQLITE_ST
2a9e0 41 54 49 43 20 20 20 20 20 20 28 28 73 71 6c 69  ATIC      ((sqli
2a9f0 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74  te3_destructor_t
2aa00 79 70 65 29 30 29 0a 23 64 65 66 69 6e 65 20 53  ype)0).#define S
2aa10 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20  QLITE_TRANSIENT 
2aa20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74    ((sqlite3_dest
2aa30 72 75 63 74 6f 72 5f 74 79 70 65 29 2d 31 29 0a  ructor_type)-1).
2aa40 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2aa50 20 53 65 74 74 69 6e 67 20 54 68 65 20 52 65 73   Setting The Res
2aa60 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20 46 75  ult Of An SQL Fu
2aa70 6e 63 74 69 6f 6e 20 7b 46 31 36 34 30 30 7d 0a  nction {F16400}.
2aa80 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
2aa90 69 6e 65 73 20 61 72 65 20 75 73 65 64 20 62 79  ines are used by
2aaa0 20 74 68 65 20 78 46 75 6e 63 20 6f 72 20 78 46   the xFunc or xF
2aab0 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 74  inal callbacks t
2aac0 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  hat.** implement
2aad0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61   SQL functions a
2aae0 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e 20 20  nd aggregates.  
2aaf0 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  See.** [sqlite3_
2ab00 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
2ab10 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
2ab20 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
2ab30 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64 64 69  6()].** for addi
2ab40 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69  tional informati
2ab50 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  on..**.** These 
2ab60 66 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b 20 76  functions work v
2ab70 65 72 79 20 6d 75 63 68 20 6c 69 6b 65 20 74 68  ery much like th
2ab80 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  e .** [sqlite3_b
2ab90 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74  ind_blob | sqlit
2aba0 65 33 5f 62 69 6e 64 5f 2a 5d 20 66 61 6d 69 6c  e3_bind_*] famil
2abb0 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 20 75  y of functions u
2abc0 73 65 64 0a 2a 2a 20 74 6f 20 62 69 6e 64 20 76  sed.** to bind v
2abd0 61 6c 75 65 73 20 74 6f 20 68 6f 73 74 20 70 61  alues to host pa
2abe0 72 61 6d 65 74 65 72 73 20 69 6e 20 70 72 65 70  rameters in prep
2abf0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 2e  ared statements.
2ac00 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 74 68 65  .** Refer to the
2ac10 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
2ac20 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33  d_blob | sqlite3
2ac30 5f 62 69 6e 64 5f 2a 20 64 6f 63 75 6d 65 6e 74  _bind_* document
2ac40 61 74 69 6f 6e 5d 20 66 6f 72 0a 2a 2a 20 61 64  ation] for.** ad
2ac50 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
2ac60 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  tion..**.** The 
2ac70 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
2ac80 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65 20  lob() interface 
2ac90 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20  sets the result 
2aca0 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69  from.** an appli
2acb0 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66  cation defined f
2acc0 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68  unction to be th
2acd0 65 20 42 4c 4f 42 20 77 68 6f 73 65 20 63 6f 6e  e BLOB whose con
2ace0 74 65 6e 74 20 69 73 20 70 6f 69 6e 74 65 64 0a  tent is pointed.
2acf0 2a 2a 20 74 6f 20 62 79 20 74 68 65 20 73 65 63  ** to by the sec
2ad00 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e  ond parameter an
2ad10 64 20 77 68 69 63 68 20 69 73 20 4e 20 62 79 74  d which is N byt
2ad20 65 73 20 6c 6f 6e 67 20 77 68 65 72 65 20 4e 20  es long where N 
2ad30 69 73 20 74 68 65 0a 2a 2a 20 74 68 69 72 64 20  is the.** third 
2ad40 70 61 72 61 6d 65 74 65 72 2e 20 0a 2a 2a 20 54  parameter. .** T
2ad50 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
2ad60 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 69 6e 65  t_zeroblob() ine
2ad70 72 66 61 63 65 73 20 73 65 74 20 74 68 65 20 72  rfaces set the r
2ad80 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20  esult of.** the 
2ad90 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69  application defi
2ada0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
2adb0 62 65 20 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69  be a BLOB contai
2adc0 6e 69 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a  ning all zero.**
2add0 20 62 79 74 65 73 20 61 6e 64 20 4e 20 62 79 74   bytes and N byt
2ade0 65 73 20 69 6e 20 73 69 7a 65 2c 20 77 68 65 72  es in size, wher
2adf0 65 20 4e 20 69 73 20 74 68 65 20 76 61 6c 75 65  e N is the value
2ae00 20 6f 66 20 74 68 65 20 32 6e 64 20 70 61 72 61   of the 2nd para
2ae10 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  meter..**.** The
2ae20 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2ae30 64 6f 75 62 6c 65 28 29 20 69 6e 74 65 72 66 61  double() interfa
2ae40 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75  ce sets the resu
2ae50 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70  lt from.** an ap
2ae60 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65  plication define
2ae70 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
2ae80 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e   a floating poin
2ae90 74 20 76 61 6c 75 65 20 73 70 65 63 69 66 69 65  t value specifie
2aea0 64 0a 2a 2a 20 62 79 20 69 74 73 20 32 6e 64 20  d.** by its 2nd 
2aeb0 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
2aec0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
2aed0 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73  lt_error() and s
2aee0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
2aef0 72 6f 72 31 36 28 29 20 66 75 6e 63 74 69 6f 6e  ror16() function
2af00 73 0a 2a 2a 20 63 61 75 73 65 20 74 68 65 20 69  s.** cause the i
2af10 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20 66  mplemented SQL f
2af20 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77  unction to throw
2af30 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a   an exception..*
2af40 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 68  * SQLite uses th
2af50 65 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 64  e string pointed
2af60 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e   to by the.** 2n
2af70 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73  d parameter of s
2af80 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
2af90 72 6f 72 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ror() or sqlite3
2afa0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
2afb0 29 0a 2a 2a 20 61 73 20 74 68 65 20 74 65 78 74  ).** as the text
2afc0 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d 65 73   of an error mes
2afd0 73 61 67 65 2e 20 20 53 51 4c 69 74 65 20 69 6e  sage.  SQLite in
2afe0 74 65 72 70 72 65 74 73 20 74 68 65 20 65 72 72  terprets the err
2aff0 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73 74  or.** message st
2b000 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65  ring from sqlite
2b010 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
2b020 20 61 73 20 55 54 46 38 2e 20 53 51 4c 69 74 65   as UTF8. SQLite
2b030 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 73 20 74  .** interprets t
2b040 68 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73  he string from s
2b050 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
2b060 72 6f 72 31 36 28 29 20 61 73 20 55 54 46 31 36  ror16() as UTF16
2b070 20 69 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 62 79   in native.** by
2b080 74 65 20 6f 72 64 65 72 2e 20 20 49 66 20 74 68  te order.  If th
2b090 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
2b0a0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73  r to sqlite3_res
2b0b0 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f  ult_error().** o
2b0c0 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
2b0d0 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 65  _error16() is ne
2b0e0 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69  gative then SQLi
2b0f0 74 65 20 74 61 6b 65 73 20 61 73 20 74 68 65 20  te takes as the 
2b100 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65  error.** message
2b110 20 61 6c 6c 20 74 65 78 74 20 75 70 20 74 68 72   all text up thr
2b120 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a  ough the first z
2b130 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a  ero character..*
2b140 2a 20 49 66 20 74 68 65 20 74 68 69 72 64 20 70  * If the third p
2b150 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
2b160 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
2b170 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  () or.** sqlite3
2b180 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
2b190 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  ) is non-negativ
2b1a0 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61  e then SQLite ta
2b1b0 6b 65 73 20 74 68 61 74 20 6d 61 6e 79 0a 2a 2a  kes that many.**
2b1c0 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72   bytes (not char
2b1d0 61 63 74 65 72 73 29 20 66 72 6f 6d 20 74 68 65  acters) from the
2b1e0 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61   2nd parameter a
2b1f0 73 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  s the error mess
2b200 61 67 65 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69  age..** The sqli
2b210 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
2b220 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72  () and sqlite3_r
2b230 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a  esult_error16().
2b240 2a 2a 20 72 6f 75 74 69 6e 65 73 20 6d 61 6b 65  ** routines make
2b250 20 61 20 63 6f 70 79 20 70 72 69 76 61 74 65 20   a copy private 
2b260 63 6f 70 79 20 6f 66 20 74 68 65 20 65 72 72 6f  copy of the erro
2b270 72 20 6d 65 73 73 61 67 65 20 74 65 78 74 20 62  r message text b
2b280 65 66 6f 72 65 0a 2a 2a 20 74 68 65 79 20 72 65  efore.** they re
2b290 74 75 72 6e 2e 20 20 48 65 6e 63 65 2c 20 74 68  turn.  Hence, th
2b2a0 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69  e calling functi
2b2b0 6f 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63 61 74  on can deallocat
2b2c0 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79 20 74  e or.** modify t
2b2d0 68 65 20 74 65 78 74 20 61 66 74 65 72 20 74 68  he text after th
2b2e0 65 79 20 72 65 74 75 72 6e 20 77 69 74 68 6f 75  ey return withou
2b2f0 74 20 68 61 72 6d 2e 0a 2a 2a 20 54 68 65 20 73  t harm..** The s
2b300 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
2b310 72 6f 72 5f 63 6f 64 65 28 29 20 66 75 6e 63 74  ror_code() funct
2b320 69 6f 6e 20 63 68 61 6e 67 65 73 20 74 68 65 20  ion changes the 
2b330 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 65  error code.** re
2b340 74 75 72 6e 65 64 20 62 79 20 53 51 4c 69 74 65  turned by SQLite
2b350 20 61 73 20 61 20 72 65 73 75 6c 74 20 6f 66 20   as a result of 
2b360 61 6e 20 65 72 72 6f 72 20 69 6e 20 61 20 66 75  an error in a fu
2b370 6e 63 74 69 6f 6e 2e 20 20 42 79 20 64 65 66 61  nction.  By defa
2b380 75 6c 74 2c 0a 2a 2a 20 74 68 65 20 65 72 72 6f  ult,.** the erro
2b390 72 20 63 6f 64 65 20 69 73 20 53 51 4c 49 54 45  r code is SQLITE
2b3a0 5f 45 52 52 4f 52 2e 20 0a 2a 2a 0a 2a 2a 20 54  _ERROR. .**.** T
2b3b0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
2b3c0 74 5f 74 6f 6f 62 69 67 28 29 20 69 6e 74 65 72  t_toobig() inter
2b3d0 66 61 63 65 20 63 61 75 73 65 73 20 53 51 4c 69  face causes SQLi
2b3e0 74 65 0a 2a 2a 20 74 6f 20 74 68 72 6f 77 20 61  te.** to throw a
2b3f0 6e 20 65 72 72 6f 72 20 69 6e 64 69 63 61 74 69  n error indicati
2b400 6e 67 20 74 68 61 74 20 61 20 73 74 72 69 6e 67  ng that a string
2b410 20 6f 72 20 42 4c 4f 42 20 69 73 20 74 6f 20 6c   or BLOB is to l
2b420 6f 6e 67 0a 2a 2a 20 74 6f 20 72 65 70 72 65 73  ong.** to repres
2b430 65 6e 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65  ent.  The sqlite
2b440 33 5f 72 65 73 75 6c 74 5f 6e 6f 6d 65 6d 28 29  3_result_nomem()
2b450 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 63 61   interface.** ca
2b460 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74  uses SQLite to t
2b470 68 72 6f 77 20 61 6e 20 65 78 63 65 70 74 69 6f  hrow an exceptio
2b480 6e 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61  n indicating tha
2b490 74 20 74 68 65 20 61 0a 2a 2a 20 6d 65 6d 6f 72  t the a.** memor
2b4a0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69  y allocation fai
2b4b0 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  led..**.** The s
2b4c0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
2b4d0 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  t() interface se
2b4e0 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  ts the return va
2b4f0 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70  lue.** of the ap
2b500 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2b510 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
2b520 20 74 68 65 20 33 32 2d 62 69 74 20 73 69 67 6e   the 32-bit sign
2b530 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61  ed integer.** va
2b540 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65  lue given in the
2b550 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a   2nd argument..*
2b560 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
2b570 73 75 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e 74  sult_int64() int
2b580 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
2b590 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20  return value.** 
2b5a0 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
2b5b0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
2b5c0 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 36 34  ion to be the 64
2b5d0 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
2b5e0 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76  ger.** value giv
2b5f0 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72  en in the 2nd ar
2b600 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  gument..**.** Th
2b610 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
2b620 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66 61 63  _null() interfac
2b630 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72  e sets the retur
2b640 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68  n value.** of th
2b650 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
2b660 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
2b670 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  o be NULL..**.**
2b680 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
2b690 75 6c 74 5f 74 65 78 74 28 29 2c 20 73 71 6c 69  ult_text(), sqli
2b6a0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
2b6b0 36 28 29 2c 20 0a 2a 2a 20 73 71 6c 69 74 65 33  6(), .** sqlite3
2b6c0 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65  _result_text16le
2b6d0 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  (), and sqlite3_
2b6e0 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28  result_text16be(
2b6f0 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ) interfaces.** 
2b700 73 65 74 20 74 68 65 20 72 65 74 75 72 6e 20 76  set the return v
2b710 61 6c 75 65 20 6f 66 20 74 68 65 20 61 70 70 6c  alue of the appl
2b720 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2b730 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a  function to be.*
2b740 2a 20 61 20 74 65 78 74 20 73 74 72 69 6e 67 20  * a text string 
2b750 77 68 69 63 68 20 69 73 20 72 65 70 72 65 73 65  which is represe
2b760 6e 74 65 64 20 61 73 20 55 54 46 2d 38 2c 20 55  nted as UTF-8, U
2b770 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74  TF-16 native byt
2b780 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46 2d  e order,.** UTF-
2b790 31 36 20 6c 69 74 74 6c 65 20 65 6e 64 69 61 6e  16 little endian
2b7a0 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67 20  , or UTF-16 big 
2b7b0 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 74 69  endian, respecti
2b7c0 76 65 6c 79 2e 0a 2a 2a 20 53 51 4c 69 74 65 20  vely..** SQLite 
2b7d0 74 61 6b 65 73 20 74 68 65 20 74 65 78 74 20 72  takes the text r
2b7e0 65 73 75 6c 74 20 66 72 6f 6d 20 74 68 65 20 61  esult from the a
2b7f0 70 70 6c 69 63 61 74 69 6f 6e 20 66 72 6f 6d 0a  pplication from.
2b800 2a 2a 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  ** the 2nd param
2b810 65 74 65 72 20 6f 66 20 74 68 65 20 73 71 6c 69  eter of the sqli
2b820 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
2b830 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20   interfaces..** 
2b840 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  If the 3rd param
2b850 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
2b860 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
2b870 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69   interfaces.** i
2b880 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  s negative, then
2b890 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 72 65   SQLite takes re
2b8a0 73 75 6c 74 20 74 65 78 74 20 66 72 6f 6d 20 74  sult text from t
2b8b0 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
2b8c0 20 0a 2a 2a 20 74 68 72 6f 75 67 68 20 74 68 65   .** through the
2b8d0 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72   first zero char
2b8e0 61 63 74 65 72 2e 0a 2a 2a 20 49 66 20 74 68 65  acter..** If the
2b8f0 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
2b900 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  o the sqlite3_re
2b910 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
2b920 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d  faces.** is non-
2b930 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 61  negative, then a
2b940 73 20 6d 61 6e 79 20 62 79 74 65 73 20 28 6e 6f  s many bytes (no
2b950 74 20 63 68 61 72 61 63 74 65 72 73 29 20 6f 66  t characters) of
2b960 20 74 68 65 20 74 65 78 74 0a 2a 2a 20 70 6f 69   the text.** poi
2b970 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 32  nted to by the 2
2b980 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 72 65  nd parameter are
2b990 20 74 61 6b 65 6e 20 61 73 20 74 68 65 20 61 70   taken as the ap
2b9a0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2b9b0 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65  d.** function re
2b9c0 73 75 6c 74 2e 0a 2a 2a 20 49 66 20 74 68 65 20  sult..** If the 
2b9d0 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
2b9e0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
2b9f0 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
2ba00 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  aces.** or sqlit
2ba10 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69  e3_result_blob i
2ba20 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69  s a non-NULL poi
2ba30 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74  nter, then SQLit
2ba40 65 20 63 61 6c 6c 73 20 74 68 61 74 0a 2a 2a 20  e calls that.** 
2ba50 66 75 6e 63 74 69 6f 6e 20 61 73 20 74 68 65 20  function as the 
2ba60 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68  destructor on th
2ba70 65 20 74 65 78 74 20 6f 72 20 62 6c 6f 62 20 72  e text or blob r
2ba80 65 73 75 6c 74 20 77 68 65 6e 20 69 74 20 68 61  esult when it ha
2ba90 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20 75 73  s.** finished us
2baa0 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e  ing that result.
2bab0 0a 2a 2a 20 49 66 20 74 68 65 20 34 74 68 20 70  .** If the 4th p
2bac0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
2bad0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
2bae0 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a  ext* interfaces.
2baf0 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ** or sqlite3_re
2bb00 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65  sult_blob is the
2bb10 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e   special constan
2bb20 74 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c  t SQLITE_STATIC,
2bb30 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20   then.** SQLite 
2bb40 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65  assumes that the
2bb50 20 74 65 78 74 20 6f 72 20 62 6c 6f 62 20 72 65   text or blob re
2bb60 73 75 6c 74 20 69 73 20 63 6f 6e 73 74 61 6e 74  sult is constant
2bb70 20 73 70 61 63 65 20 61 6e 64 0a 2a 2a 20 64 6f   space and.** do
2bb80 65 73 20 6e 6f 74 20 63 6f 70 79 20 74 68 65 20  es not copy the 
2bb90 73 70 61 63 65 20 6f 72 20 63 61 6c 6c 20 61 20  space or call a 
2bba0 64 65 73 74 72 75 63 74 6f 72 20 77 68 65 6e 20  destructor when 
2bbb0 69 74 20 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68  it has.** finish
2bbc0 65 64 20 75 73 69 6e 67 20 74 68 61 74 20 72 65  ed using that re
2bbd0 73 75 6c 74 2e 0a 2a 2a 20 49 66 20 74 68 65 20  sult..** If the 
2bbe0 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
2bbf0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
2bc00 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
2bc10 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  aces.** or sqlit
2bc20 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69  e3_result_blob i
2bc30 73 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f  s the special co
2bc40 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 54 52  nstant SQLITE_TR
2bc50 41 4e 53 49 45 4e 54 0a 2a 2a 20 74 68 65 6e 20  ANSIENT.** then 
2bc60 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63  SQLite makes a c
2bc70 6f 70 79 20 6f 66 20 74 68 65 20 72 65 73 75 6c  opy of the resul
2bc80 74 20 69 6e 74 6f 20 73 70 61 63 65 20 6f 62 74  t into space obt
2bc90 61 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 66 72  ained from.** fr
2bca0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
2bcb0 6f 63 28 29 5d 20 62 65 66 6f 72 65 20 69 74 20  oc()] before it 
2bcc0 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54  returns..**.** T
2bcd0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
2bce0 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66  t_value() interf
2bcf0 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73  ace sets the res
2bd00 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70  ult of.** the ap
2bd10 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2bd20 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
2bd30 20 61 20 63 6f 70 79 20 74 68 65 0a 2a 2a 20 5b   a copy the.** [
2bd40 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
2bd50 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
2bd60 74 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  t specified by t
2bd70 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
2bd80 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65  .  The.** sqlite
2bd90 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29  3_result_value()
2bda0 20 69 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 73   interface makes
2bdb0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b   a copy of the [
2bdc0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a  sqlite3_value].*
2bdd0 2a 20 73 6f 20 74 68 61 74 20 5b 73 71 6c 69 74  * so that [sqlit
2bde0 65 33 5f 76 61 6c 75 65 5d 20 73 70 65 63 69 66  e3_value] specif
2bdf0 69 65 64 20 69 6e 20 74 68 65 20 70 61 72 61 6d  ied in the param
2be00 65 74 65 72 20 6d 61 79 20 63 68 61 6e 67 65 20  eter may change 
2be10 6f 72 0a 2a 2a 20 62 65 20 64 65 61 6c 6c 6f 63  or.** be dealloc
2be20 61 74 65 64 20 61 66 74 65 72 20 73 71 6c 69 74  ated after sqlit
2be30 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
2be40 29 20 72 65 74 75 72 6e 73 20 77 69 74 68 6f 75  ) returns withou
2be50 74 20 68 61 72 6d 2e 0a 2a 2a 20 41 20 5b 70 72  t harm..** A [pr
2be60 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2be70 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 6d 61  value] object ma
2be80 79 20 61 6c 77 61 79 73 20 62 65 20 75 73 65 64  y always be used
2be90 20 77 68 65 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e   where an.** [un
2bea0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2beb0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
2bec0 69 73 20 72 65 71 75 69 72 65 64 2c 20 73 6f 20  is required, so 
2bed0 65 69 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f  either.** kind o
2bee0 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  f [sqlite3_value
2bef0 5d 20 6f 62 6a 65 63 74 20 63 61 6e 20 62 65 20  ] object can be 
2bf00 75 73 65 64 20 77 69 74 68 20 74 68 69 73 20 69  used with this i
2bf10 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
2bf20 49 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  If these routine
2bf30 73 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f  s are called fro
2bf40 6d 20 77 69 74 68 69 6e 20 74 68 65 20 64 69 66  m within the dif
2bf50 66 65 72 65 6e 74 20 74 68 72 65 61 64 20 0a 2a  ferent thread .*
2bf60 2a 20 74 68 61 6e 20 74 68 65 20 6f 6e 65 20 63  * than the one c
2bf70 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61 70  ontaining the ap
2bf80 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2bf90 64 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20  d function that 
2bfa0 72 65 63 69 65 76 65 64 0a 2a 2a 20 74 68 65 20  recieved.** the 
2bfb0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  [sqlite3_context
2bfc0 5d 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 20 72  ] pointer, the r
2bfd0 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
2bfe0 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  ined..**.** INVA
2bff0 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  RIANTS:.**.** {F
2c000 31 36 34 30 33 7d 20 54 68 65 20 64 65 66 61 75  16403} The defau
2c010 6c 74 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  lt return value 
2c020 66 72 6f 6d 20 61 6e 79 20 53 51 4c 20 66 75 6e  from any SQL fun
2c030 63 74 69 6f 6e 20 69 73 20 4e 55 4c 4c 2e 0a 2a  ction is NULL..*
2c040 2a 0a 2a 2a 20 7b 46 31 36 34 30 36 7d 20 54 68  *.** {F16406} Th
2c050 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  e [sqlite3_resul
2c060 74 5f 62 6c 6f 62 28 43 2c 56 2c 4e 2c 44 29 5d  t_blob(C,V,N,D)]
2c070 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67   interface chang
2c080 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  es the.**       
2c090 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20     return value 
2c0a0 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f  of function C to
2c0b0 20 62 65 20 61 20 62 6c 6f 62 20 74 68 61 74 20   be a blob that 
2c0c0 69 73 20 4e 20 62 79 74 65 73 0a 2a 2a 20 20 20  is N bytes.**   
2c0d0 20 20 20 20 20 20 20 69 6e 20 6c 65 6e 67 74 68         in length
2c0e0 20 61 6e 64 20 77 69 74 68 20 63 6f 6e 74 65 6e   and with conten
2c0f0 74 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20  t pointed to by 
2c100 56 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 30 39  V..**.** {F16409
2c110 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  } The [sqlite3_r
2c120 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 43 2c 56  esult_double(C,V
2c130 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61  )] interface cha
2c140 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  nges the.**     
2c150 20 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75       return valu
2c160 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20  e of function C 
2c170 74 6f 20 62 65 20 74 68 65 20 66 6c 6f 61 74 69  to be the floati
2c180 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 56  ng point value V
2c190 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 31 32 7d  ..**.** {F16412}
2c1a0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   The [sqlite3_re
2c1b0 73 75 6c 74 5f 65 72 72 6f 72 28 43 2c 56 2c 4e  sult_error(C,V,N
2c1c0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61  )] interface cha
2c1d0 6e 67 65 73 20 74 68 65 20 72 65 74 75 72 6e 0a  nges the return.
2c1e0 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c 75  **          valu
2c1f0 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20  e of function C 
2c200 74 6f 20 62 65 20 61 6e 20 65 78 63 65 70 74 69  to be an excepti
2c210 6f 6e 20 77 69 74 68 20 65 72 72 6f 72 20 63 6f  on with error co
2c220 64 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  de.**          [
2c230 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 61 6e  SQLITE_ERROR] an
2c240 64 20 61 20 55 54 46 38 20 65 72 72 6f 72 20 6d  d a UTF8 error m
2c250 65 73 73 61 67 65 20 63 6f 70 69 65 64 20 66 72  essage copied fr
2c260 6f 6d 20 56 20 75 70 20 74 6f 20 74 68 65 0a 2a  om V up to the.*
2c270 2a 20 20 20 20 20 20 20 20 20 20 66 69 72 73 74  *          first
2c280 20 7a 65 72 6f 20 62 79 74 65 20 6f 72 20 75 6e   zero byte or un
2c290 74 69 6c 20 4e 20 62 79 74 65 73 20 61 72 65 20  til N bytes are 
2c2a0 72 65 61 64 20 69 66 20 4e 20 69 73 20 70 6f 73  read if N is pos
2c2b0 69 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  itive..**.** {F1
2c2c0 36 34 31 35 7d 20 54 68 65 20 5b 73 71 6c 69 74  6415} The [sqlit
2c2d0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
2c2e0 36 28 43 2c 56 2c 4e 29 5d 20 69 6e 74 65 72 66  6(C,V,N)] interf
2c2f0 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 20  ace changes the 
2c300 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20  return.**       
2c310 20 20 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63     value of func
2c320 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e 20  tion C to be an 
2c330 65 78 63 65 70 74 69 6f 6e 20 77 69 74 68 20 65  exception with e
2c340 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 20 20 20  rror code.**    
2c350 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 45 52        [SQLITE_ER
2c360 52 4f 52 5d 20 61 6e 64 20 61 20 55 54 46 31 36  ROR] and a UTF16
2c370 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
2c380 65 72 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  er error message
2c390 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 70  .**          cop
2c3a0 69 65 64 20 66 72 6f 6d 20 56 20 75 70 20 74 6f  ied from V up to
2c3b0 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
2c3c0 74 65 72 6d 69 6e 61 74 6f 72 20 6f 72 20 75 6e  terminator or un
2c3d0 74 69 6c 20 4e 20 62 79 74 65 73 0a 2a 2a 20 20  til N bytes.**  
2c3e0 20 20 20 20 20 20 20 20 61 72 65 20 72 65 61 64          are read
2c3f0 20 69 66 20 4e 20 69 73 20 70 6f 73 69 74 69 76   if N is positiv
2c400 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 31 38  e..**.** {F16418
2c410 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  } The [sqlite3_r
2c420 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62  esult_error_toob
2c430 69 67 28 43 29 5d 20 69 6e 74 65 72 66 61 63 65  ig(C)] interface
2c440 20 63 68 61 6e 67 65 73 20 74 68 65 20 72 65 74   changes the ret
2c450 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  urn.**          
2c460 76 61 6c 75 65 20 6f 66 20 74 68 65 20 66 75 6e  value of the fun
2c470 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e  ction C to be an
2c480 20 65 78 63 65 70 74 69 6f 6e 20 77 69 74 68 20   exception with 
2c490 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 20 20  error code.**   
2c4a0 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 54         [SQLITE_T
2c4b0 4f 4f 42 49 47 5d 20 61 6e 64 20 61 6e 20 61 70  OOBIG] and an ap
2c4c0 70 72 6f 70 72 69 61 74 65 20 65 72 72 6f 72 20  propriate error 
2c4d0 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 7b  message..**.** {
2c4e0 46 31 36 34 32 31 7d 20 54 68 65 20 5b 73 71 6c  F16421} The [sql
2c4f0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
2c500 72 5f 6e 6f 6d 65 6d 28 43 29 5d 20 69 6e 74 65  r_nomem(C)] inte
2c510 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68  rface changes th
2c520 65 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20  e return.**     
2c530 20 20 20 20 20 76 61 6c 75 65 20 6f 66 20 74 68       value of th
2c540 65 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20  e function C to 
2c550 62 65 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20  be an exception 
2c560 77 69 74 68 20 65 72 72 6f 72 20 63 6f 64 65 0a  with error code.
2c570 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c  **          [SQL
2c580 49 54 45 5f 4e 4f 4d 45 4d 5d 20 61 6e 64 20 61  ITE_NOMEM] and a
2c590 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 65 72  n appropriate er
2c5a0 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a  ror message..**.
2c5b0 2a 2a 20 7b 46 31 36 34 32 34 7d 20 54 68 65 20  ** {F16424} The 
2c5c0 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
2c5d0 65 72 72 6f 72 5f 63 6f 64 65 28 43 2c 45 29 5d  error_code(C,E)]
2c5e0 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67   interface chang
2c5f0 65 73 20 74 68 65 20 72 65 74 75 72 6e 0a 2a 2a  es the return.**
2c600 20 20 20 20 20 20 20 20 20 20 76 61 6c 75 65 20            value 
2c610 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  of the function 
2c620 43 20 74 6f 20 62 65 20 61 6e 20 65 78 63 65 70  C to be an excep
2c630 74 69 6f 6e 20 77 69 74 68 20 65 72 72 6f 72 20  tion with error 
2c640 63 6f 64 65 20 45 2e 0a 2a 2a 20 20 20 20 20 20  code E..**      
2c650 20 20 20 20 54 68 65 20 65 72 72 6f 72 20 6d 65      The error me
2c660 73 73 61 67 65 20 74 65 78 74 20 69 73 20 75 6e  ssage text is un
2c670 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b  changed..**.** {
2c680 46 31 36 34 32 37 7d 20 54 68 65 20 5b 73 71 6c  F16427} The [sql
2c690 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28  ite3_result_int(
2c6a0 43 2c 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20  C,V)] interface 
2c6b0 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20  changes the.**  
2c6c0 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 76          return v
2c6d0 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e  alue of function
2c6e0 20 43 20 74 6f 20 62 65 20 74 68 65 20 33 32 2d   C to be the 32-
2c6f0 62 69 74 20 69 6e 74 65 67 65 72 20 76 61 6c 75  bit integer valu
2c700 65 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34  e V..**.** {F164
2c710 33 30 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  30} The [sqlite3
2c720 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 43 2c  _result_int64(C,
2c730 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68  V)] interface ch
2c740 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20  anges the.**    
2c750 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c        return val
2c760 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43  ue of function C
2c770 20 74 6f 20 62 65 20 74 68 65 20 36 34 2d 62 69   to be the 64-bi
2c780 74 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 20  t integer value 
2c790 56 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 33 33  V..**.** {F16433
2c7a0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  } The [sqlite3_r
2c7b0 65 73 75 6c 74 5f 6e 75 6c 6c 28 43 29 5d 20 69  esult_null(C)] i
2c7c0 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73  nterface changes
2c7d0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
2c7e0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
2c7f0 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62   function C to b
2c800 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 46  e NULL..**.** {F
2c810 31 36 34 33 36 7d 20 54 68 65 20 5b 73 71 6c 69  16436} The [sqli
2c820 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28  te3_result_text(
2c830 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74 65 72 66  C,V,N,D)] interf
2c840 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a  ace changes the.
2c850 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75  **          retu
2c860 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63  rn value of func
2c870 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65  tion C to be the
2c880 20 55 54 46 38 20 73 74 72 69 6e 67 0a 2a 2a 20   UTF8 string.** 
2c890 20 20 20 20 20 20 20 20 20 56 20 75 70 20 74 68           V up th
2c8a0 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20  rough the first 
2c8b0 7a 65 72 6f 20 6f 72 20 75 6e 74 69 6c 20 4e 20  zero or until N 
2c8c0 62 79 74 65 73 20 61 72 65 20 72 65 61 64 20 69  bytes are read i
2c8d0 66 20 4e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  f N.**          
2c8e0 69 73 20 70 6f 73 69 74 69 76 65 2e 0a 2a 2a 0a  is positive..**.
2c8f0 2a 2a 20 7b 46 31 36 34 33 39 7d 20 54 68 65 20  ** {F16439} The 
2c900 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
2c910 74 65 78 74 31 36 28 43 2c 56 2c 4e 2c 44 29 5d  text16(C,V,N,D)]
2c920 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67   interface chang
2c930 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  es the.**       
2c940 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20     return value 
2c950 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f  of function C to
2c960 20 62 65 20 74 68 65 20 55 54 46 31 36 20 6e 61   be the UTF16 na
2c970 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 0a  tive byte order.
2c980 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 72 69  **          stri
2c990 6e 67 20 20 56 20 75 70 20 74 68 72 6f 75 67 68  ng  V up through
2c9a0 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
2c9b0 6f 72 20 75 6e 74 69 6c 20 4e 20 62 79 74 65 73  or until N bytes
2c9c0 20 61 72 65 20 72 65 61 64 20 69 66 20 4e 0a 2a   are read if N.*
2c9d0 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 70 6f  *          is po
2c9e0 73 69 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46  sitive..**.** {F
2c9f0 31 36 34 34 32 7d 20 54 68 65 20 5b 73 71 6c 69  16442} The [sqli
2ca00 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
2ca10 36 62 65 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e  6be(C,V,N,D)] in
2ca20 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20  terface changes 
2ca30 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
2ca40 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
2ca50 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65  function C to be
2ca60 20 74 68 65 20 55 54 46 31 36 20 62 69 67 2d 65   the UTF16 big-e
2ca70 6e 64 69 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20  ndian.**        
2ca80 20 20 73 74 72 69 6e 67 20 20 56 20 75 70 20 74    string  V up t
2ca90 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74  hrough the first
2caa0 20 7a 65 72 6f 20 6f 72 20 75 6e 74 69 6c 20 4e   zero or until N
2cab0 20 62 79 74 65 73 20 61 72 65 20 72 65 61 64 20   bytes are read 
2cac0 69 66 20 4e 0a 2a 2a 20 20 20 20 20 20 20 20 20  if N.**         
2cad0 20 69 73 20 70 6f 73 69 74 69 76 65 2e 0a 2a 2a   is positive..**
2cae0 0a 2a 2a 20 7b 46 31 36 34 34 35 7d 20 54 68 65  .** {F16445} The
2caf0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
2cb00 5f 74 65 78 74 31 36 6c 65 28 43 2c 56 2c 4e 2c  _text16le(C,V,N,
2cb10 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68  D)] interface ch
2cb20 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20  anges the.**    
2cb30 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c        return val
2cb40 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43  ue of function C
2cb50 20 74 6f 20 62 65 20 74 68 65 20 55 54 46 31 36   to be the UTF16
2cb60 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 0a 2a   little-endian.*
2cb70 2a 20 20 20 20 20 20 20 20 20 20 73 74 72 69 6e  *          strin
2cb80 67 20 20 56 20 75 70 20 74 68 72 6f 75 67 68 20  g  V up through 
2cb90 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 6f  the first zero o
2cba0 72 20 75 6e 74 69 6c 20 4e 20 62 79 74 65 73 20  r until N bytes 
2cbb0 61 72 65 20 72 65 61 64 20 69 66 20 4e 0a 2a 2a  are read if N.**
2cbc0 20 20 20 20 20 20 20 20 20 20 69 73 20 70 6f 73            is pos
2cbd0 69 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  itive..**.** {F1
2cbe0 36 34 34 38 7d 20 54 68 65 20 5b 73 71 6c 69 74  6448} The [sqlit
2cbf0 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
2cc00 43 2c 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20  C,V)] interface 
2cc10 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20  changes the.**  
2cc20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 76          return v
2cc30 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e  alue of function
2cc40 20 43 20 74 6f 20 62 65 20 5b 75 6e 70 72 6f 74   C to be [unprot
2cc50 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2cc60 6c 75 65 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  lue].**         
2cc70 20 6f 62 6a 65 63 74 20 56 2e 0a 2a 2a 0a 2a 2a   object V..**.**
2cc80 20 7b 46 31 36 34 35 31 7d 20 54 68 65 20 5b 73   {F16451} The [s
2cc90 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65  qlite3_result_ze
2cca0 72 6f 62 6c 6f 62 28 43 2c 4e 29 5d 20 69 6e 74  roblob(C,N)] int
2ccb0 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74  erface changes t
2ccc0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  he.**          r
2ccd0 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66  eturn value of f
2cce0 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20  unction C to be 
2ccf0 61 6e 20 4e 2d 62 79 74 65 20 62 6c 6f 62 20 6f  an N-byte blob o
2cd00 66 20 61 6c 6c 20 7a 65 72 6f 73 2e 0a 2a 2a 0a  f all zeros..**.
2cd10 2a 2a 20 7b 46 31 36 34 35 34 7d 20 54 68 65 20  ** {F16454} The 
2cd20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
2cd30 65 72 72 6f 72 28 29 5d 20 61 6e 64 20 5b 73 71  error()] and [sq
2cd40 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
2cd50 6f 72 31 36 28 29 5d 0a 2a 2a 20 20 20 20 20 20  or16()].**      
2cd60 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 20 6d      interfaces m
2cd70 61 6b 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68  ake a copy of th
2cd80 65 69 72 20 65 72 72 6f 72 20 6d 65 73 73 61 67  eir error messag
2cd90 65 20 73 74 72 69 6e 67 73 20 62 65 66 6f 72 65  e strings before
2cda0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74  .**          ret
2cdb0 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46  urning..**.** {F
2cdc0 31 36 34 35 37 7d 20 49 66 20 74 68 65 20 44 20  16457} If the D 
2cdd0 64 65 73 74 72 75 63 74 6f 72 20 70 61 72 61 6d  destructor param
2cde0 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
2cdf0 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 43 2c 56  _result_blob(C,V
2ce00 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20  ,N,D)],.**      
2ce10 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73      [sqlite3_res
2ce20 75 6c 74 5f 74 65 78 74 28 43 2c 56 2c 4e 2c 44  ult_text(C,V,N,D
2ce30 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  )], [sqlite3_res
2ce40 75 6c 74 5f 74 65 78 74 31 36 28 43 2c 56 2c 4e  ult_text16(C,V,N
2ce50 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  ,D)],.**        
2ce60 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c    [sqlite3_resul
2ce70 74 5f 74 65 78 74 31 36 62 65 28 43 2c 56 2c 4e  t_text16be(C,V,N
2ce80 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20  ,D)], or.**     
2ce90 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65       [sqlite3_re
2cea0 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 43 2c  sult_text16le(C,
2ceb0 56 2c 4e 2c 44 29 5d 20 69 73 20 74 68 65 20 63  V,N,D)] is the c
2cec0 6f 6e 73 74 61 6e 74 20 5b 53 51 4c 49 54 45 5f  onstant [SQLITE_
2ced0 53 54 41 54 49 43 5d 0a 2a 2a 20 20 20 20 20 20  STATIC].**      
2cee0 20 20 20 20 74 68 65 6e 20 6e 6f 20 64 65 73 74      then no dest
2cef0 72 75 63 74 6f 72 20 69 73 20 65 76 65 72 20 63  ructor is ever c
2cf00 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 70 6f 69  alled on the poi
2cf10 6e 74 65 72 20 56 20 61 6e 64 20 53 51 4c 69 74  nter V and SQLit
2cf20 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 73  e.**          as
2cf30 73 75 6d 65 73 20 74 68 61 74 20 56 20 69 73 20  sumes that V is 
2cf40 69 6d 6d 75 74 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a  immutable..**.**
2cf50 20 7b 46 31 36 34 36 30 7d 20 49 66 20 74 68 65   {F16460} If the
2cf60 20 44 20 64 65 73 74 72 75 63 74 6f 72 20 70 61   D destructor pa
2cf70 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
2cf80 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28  te3_result_blob(
2cf90 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20  C,V,N,D)],.**   
2cfa0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
2cfb0 72 65 73 75 6c 74 5f 74 65 78 74 28 43 2c 56 2c  result_text(C,V,
2cfc0 4e 2c 44 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  N,D)], [sqlite3_
2cfd0 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 43 2c  result_text16(C,
2cfe0 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20  V,N,D)],.**     
2cff0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65       [sqlite3_re
2d000 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 43 2c  sult_text16be(C,
2d010 56 2c 4e 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20  V,N,D)], or.**  
2d020 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
2d030 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65  _result_text16le
2d040 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 73 20 74 68  (C,V,N,D)] is th
2d050 65 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20 20 20  e constant.**   
2d060 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 54         [SQLITE_T
2d070 52 41 4e 53 49 45 4e 54 5d 20 74 68 65 6e 20 74  RANSIENT] then t
2d080 68 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61  he interfaces ma
2d090 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  kes a copy of th
2d0a0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f  e.**          co
2d0b0 6e 74 65 6e 74 20 6f 66 20 56 20 61 6e 64 20 72  ntent of V and r
2d0c0 65 74 61 69 6e 73 20 74 68 65 20 63 6f 70 79 2e  etains the copy.
2d0d0 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 36 33 7d 20  .**.** {F16463} 
2d0e0 49 66 20 74 68 65 20 44 20 64 65 73 74 72 75 63  If the D destruc
2d0f0 74 6f 72 20 70 61 72 61 6d 65 74 65 72 20 74 6f  tor parameter to
2d100 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
2d110 5f 62 6c 6f 62 28 43 2c 56 2c 4e 2c 44 29 5d 2c  _blob(C,V,N,D)],
2d120 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
2d130 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
2d140 74 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 5b 73 71  t(C,V,N,D)], [sq
2d150 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
2d160 74 31 36 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a  t16(C,V,N,D)],.*
2d170 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
2d180 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
2d190 36 62 65 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 6f  6be(C,V,N,D)], o
2d1a0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  r.**          [s
2d1b0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
2d1c0 78 74 31 36 6c 65 28 43 2c 56 2c 4e 2c 44 29 5d  xt16le(C,V,N,D)]
2d1d0 20 69 73 20 73 6f 6d 65 20 76 61 6c 75 65 20 6f   is some value o
2d1e0 74 68 65 72 20 74 68 61 6e 0a 2a 2a 20 20 20 20  ther than.**    
2d1f0 20 20 20 20 20 20 74 68 65 20 63 6f 6e 73 74 61        the consta
2d200 6e 74 73 20 5b 53 51 4c 49 54 45 5f 53 54 41 54  nts [SQLITE_STAT
2d210 49 43 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  IC] and [SQLITE_
2d220 54 52 41 4e 53 49 45 4e 54 5d 20 74 68 65 6e 20  TRANSIENT] then 
2d230 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53 51 4c  .**          SQL
2d240 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20  ite will invoke 
2d250 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 44  the destructor D
2d260 20 77 69 74 68 20 56 20 61 73 20 69 74 73 20 6f   with V as its o
2d270 6e 6c 79 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  nly argument.** 
2d280 20 20 20 20 20 20 20 20 20 77 68 65 6e 20 69 74           when it
2d290 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69   has finished wi
2d2a0 74 68 20 74 68 65 20 56 20 76 61 6c 75 65 2e 0a  th the V value..
2d2b0 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  */.void sqlite3_
2d2c0 72 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69  result_blob(sqli
2d2d0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
2d2e0 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20  nst void*, int, 
2d2f0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
2d300 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
2d310 73 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69  sult_double(sqli
2d320 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f  te3_context*, do
2d330 75 62 6c 65 29 3b 0a 76 6f 69 64 20 73 71 6c 69  uble);.void sqli
2d340 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
2d350 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2d360 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  *, const char*, 
2d370 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  int);.void sqlit
2d380 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
2d390 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  6(sqlite3_contex
2d3a0 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  t*, const void*,
2d3b0 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69   int);.void sqli
2d3c0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
2d3d0 5f 74 6f 6f 62 69 67 28 73 71 6c 69 74 65 33 5f  _toobig(sqlite3_
2d3e0 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20  context*);.void 
2d3f0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
2d400 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74  rror_nomem(sqlit
2d410 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f  e3_context*);.vo
2d420 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
2d430 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73 71 6c  t_error_code(sql
2d440 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
2d450 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  nt);.void sqlite
2d460 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c  3_result_int(sql
2d470 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
2d480 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  nt);.void sqlite
2d490 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 73  3_result_int64(s
2d4a0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2d4b0 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b   sqlite3_int64);
2d4c0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
2d4d0 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65  sult_null(sqlite
2d4e0 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69  3_context*);.voi
2d4f0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
2d500 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f  _text(sqlite3_co
2d510 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68  ntext*, const ch
2d520 61 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a  ar*, int, void(*
2d530 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20  )(void*));.void 
2d540 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
2d550 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 63 6f  ext16(sqlite3_co
2d560 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f  ntext*, const vo
2d570 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a  id*, int, void(*
2d580 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20  )(void*));.void 
2d590 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
2d5a0 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f  ext16le(sqlite3_
2d5b0 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
2d5c0 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28  void*, int,void(
2d5d0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64  *)(void*));.void
2d5e0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2d5f0 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33  text16be(sqlite3
2d600 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
2d610 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64   void*, int,void
2d620 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69  (*)(void*));.voi
2d630 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
2d640 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 63  _value(sqlite3_c
2d650 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33  ontext*, sqlite3
2d660 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f 69 64 20 73  _value*);.void s
2d670 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65  qlite3_result_ze
2d680 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63  roblob(sqlite3_c
2d690 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 29 3b  ontext*, int n);
2d6a0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2d6b0 3a 20 44 65 66 69 6e 65 20 4e 65 77 20 43 6f 6c  : Define New Col
2d6c0 6c 61 74 69 6e 67 20 53 65 71 75 65 6e 63 65 73  lating Sequences
2d6d0 20 7b 46 31 36 36 30 30 7d 0a 2a 2a 0a 2a 2a 20   {F16600}.**.** 
2d6e0 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
2d6f0 61 72 65 20 75 73 65 64 20 74 6f 20 61 64 64 20  are used to add 
2d700 6e 65 77 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  new collation se
2d710 71 75 65 6e 63 65 73 20 74 6f 20 74 68 65 0a 2a  quences to the.*
2d720 2a 20 5b 73 71 6c 69 74 65 33 2a 5d 20 68 61 6e  * [sqlite3*] han
2d730 64 6c 65 20 73 70 65 63 69 66 69 65 64 20 61 73  dle specified as
2d740 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
2d750 65 6e 74 2e 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ent. .**.** The 
2d760 6e 61 6d 65 20 6f 66 20 74 68 65 20 6e 65 77 20  name of the new 
2d770 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
2d780 63 65 20 69 73 20 73 70 65 63 69 66 69 65 64 20  ce is specified 
2d790 61 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e  as a UTF-8 strin
2d7a0 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33  g.** for sqlite3
2d7b0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
2d7c0 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
2d7d0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
2d7e0 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55  _v2().** and a U
2d7f0 54 46 2d 31 36 20 73 74 72 69 6e 67 20 66 6f 72  TF-16 string for
2d800 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2d810 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 20 49  collation16(). I
2d820 6e 20 61 6c 6c 20 63 61 73 65 73 0a 2a 2a 20 74  n all cases.** t
2d830 68 65 20 6e 61 6d 65 20 69 73 20 70 61 73 73 65  he name is passe
2d840 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
2d850 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e  function argumen
2d860 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69  t..**.** The thi
2d870 72 64 20 61 72 67 75 6d 65 6e 74 20 6d 61 79 20  rd argument may 
2d880 62 65 20 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f  be one of the co
2d890 6e 73 74 61 6e 74 73 20 5b 53 51 4c 49 54 45 5f  nstants [SQLITE_
2d8a0 55 54 46 38 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  UTF8],.** [SQLIT
2d8b0 45 5f 55 54 46 31 36 4c 45 5d 20 6f 72 20 5b 53  E_UTF16LE] or [S
2d8c0 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 20  QLITE_UTF16BE], 
2d8d0 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20  indicating that 
2d8e0 74 68 65 20 75 73 65 72 2d 73 75 70 70 6c 69 65  the user-supplie
2d8f0 64 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 65 78 70  d.** routine exp
2d900 65 63 74 73 20 74 6f 20 62 65 20 70 61 73 73 65  ects to be passe
2d910 64 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74  d pointers to st
2d920 72 69 6e 67 73 20 65 6e 63 6f 64 65 64 20 75 73  rings encoded us
2d930 69 6e 67 20 55 54 46 2d 38 2c 0a 2a 2a 20 55 54  ing UTF-8,.** UT
2d940 46 2d 31 36 20 6c 69 74 74 6c 65 2d 65 6e 64 69  F-16 little-endi
2d950 61 6e 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67  an or UTF-16 big
2d960 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 63 74 69  -endian respecti
2d970 76 65 6c 79 2e 20 54 68 65 0a 2a 2a 20 74 68 69  vely. The.** thi
2d980 72 64 20 61 72 67 75 6d 65 6e 74 20 6d 69 67 68  rd argument migh
2d990 74 20 61 6c 73 6f 20 62 65 20 5b 53 51 4c 49 54  t also be [SQLIT
2d9a0 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d  E_UTF16_ALIGNED]
2d9b0 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61   to indicate tha
2d9c0 74 0a 2a 2a 20 74 68 65 20 72 6f 75 74 69 6e 65  t.** the routine
2d9d0 20 65 78 70 65 63 74 73 20 70 6f 69 6e 74 65 72   expects pointer
2d9e0 73 20 74 6f 20 31 36 2d 62 69 74 20 77 6f 72 64  s to 16-bit word
2d9f0 20 61 6c 69 67 6e 65 64 20 73 74 72 69 6e 67 73   aligned strings
2da00 0a 2a 2a 20 6f 66 20 55 54 46 31 36 20 69 6e 20  .** of UTF16 in 
2da10 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  the native byte 
2da20 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73  order of the hos
2da30 74 20 63 6f 6d 70 75 74 65 72 2e 0a 2a 2a 0a 2a  t computer..**.*
2da40 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  * A pointer to t
2da50 68 65 20 75 73 65 72 20 73 75 70 70 6c 69 65 64  he user supplied
2da60 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65   routine must be
2da70 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66   passed as the f
2da80 69 66 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  ifth.** argument
2da90 2e 20 20 49 66 20 69 74 20 69 73 20 4e 55 4c 4c  .  If it is NULL
2daa0 2c 20 74 68 69 73 20 69 73 20 74 68 65 20 73 61  , this is the sa
2dab0 6d 65 20 61 73 20 64 65 6c 65 74 69 6e 67 20 74  me as deleting t
2dac0 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20  he collation.** 
2dad0 73 65 71 75 65 6e 63 65 20 28 73 6f 20 74 68 61  sequence (so tha
2dae0 74 20 53 51 4c 69 74 65 20 63 61 6e 6e 6f 74 20  t SQLite cannot 
2daf0 63 61 6c 6c 20 69 74 20 61 6e 79 6d 6f 72 65 29  call it anymore)
2db00 2e 0a 2a 2a 20 45 61 63 68 20 74 69 6d 65 20 74  ..** Each time t
2db10 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a  he application.*
2db20 2a 20 73 75 70 70 6c 69 65 64 20 66 75 6e 63 74  * supplied funct
2db30 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20  ion is invoked, 
2db40 69 74 20 69 73 20 70 61 73 73 65 64 20 61 20 63  it is passed a c
2db50 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a  opy of the void*
2db60 20 70 61 73 73 65 64 20 61 73 0a 2a 2a 20 74 68   passed as.** th
2db70 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  e fourth argumen
2db80 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65  t to sqlite3_cre
2db90 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20  ate_collation() 
2dba0 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72  or.** sqlite3_cr
2dbb0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36  eate_collation16
2dbc0 28 29 20 61 73 20 69 74 73 20 66 69 72 73 74 20  () as its first 
2dbd0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
2dbe0 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 61   The remaining a
2dbf0 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20  rguments to the 
2dc00 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70  application-supp
2dc10 6c 69 65 64 20 72 6f 75 74 69 6e 65 20 61 72 65  lied routine are
2dc20 20 74 77 6f 20 73 74 72 69 6e 67 73 2c 0a 2a 2a   two strings,.**
2dc30 20 65 61 63 68 20 72 65 70 72 65 73 65 6e 74 65   each represente
2dc40 64 20 62 79 20 61 20 28 6c 65 6e 67 74 68 2c 20  d by a (length, 
2dc50 64 61 74 61 29 20 70 61 69 72 20 61 6e 64 20 65  data) pair and e
2dc60 6e 63 6f 64 65 64 20 69 6e 20 74 68 65 20 65 6e  ncoded in the en
2dc70 63 6f 64 69 6e 67 0a 2a 2a 20 74 68 61 74 20 77  coding.** that w
2dc80 61 73 20 70 61 73 73 65 64 20 61 73 20 74 68 65  as passed as the
2dc90 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
2dca0 77 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69  when the collati
2dcb0 6f 6e 20 73 65 71 75 65 6e 63 65 20 77 61 73 0a  on sequence was.
2dcc0 2a 2a 20 72 65 67 69 73 74 65 72 65 64 2e 20 7b  ** registered. {
2dcd0 45 4e 44 7d 20 54 68 65 20 61 70 70 6c 69 63 61  END} The applica
2dce0 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 63 6f 6c  tion defined col
2dcf0 6c 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 20 73  lation routine s
2dd00 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20  hould.** return 
2dd10 6e 65 67 61 74 69 76 65 2c 20 7a 65 72 6f 20 6f  negative, zero o
2dd20 72 20 70 6f 73 69 74 69 76 65 20 69 66 0a 2a 2a  r positive if.**
2dd30 20 74 68 65 20 66 69 72 73 74 20 73 74 72 69 6e   the first strin
2dd40 67 20 69 73 20 6c 65 73 73 20 74 68 61 6e 2c 20  g is less than, 
2dd50 65 71 75 61 6c 20 74 6f 2c 20 6f 72 20 67 72 65  equal to, or gre
2dd60 61 74 65 72 20 74 68 61 6e 20 74 68 65 20 73 65  ater than the se
2dd70 63 6f 6e 64 0a 2a 2a 20 73 74 72 69 6e 67 2e 20  cond.** string. 
2dd80 69 2e 65 2e 20 28 53 54 52 49 4e 47 31 20 2d 20  i.e. (STRING1 - 
2dd90 53 54 52 49 4e 47 32 29 2e 0a 2a 2a 0a 2a 2a 20  STRING2)..**.** 
2dda0 54 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61  The sqlite3_crea
2ddb0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
2ddc0 29 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c  ) works like sql
2ddd0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
2dde0 61 74 69 6f 6e 28 29 0a 2a 2a 20 65 78 63 61 70  ation().** excap
2ddf0 74 20 74 68 61 74 20 69 74 20 74 61 6b 65 73 20  t that it takes 
2de00 61 6e 20 65 78 74 72 61 20 61 72 67 75 6d 65 6e  an extra argumen
2de10 74 20 77 68 69 63 68 20 69 73 20 61 20 64 65 73  t which is a des
2de20 74 72 75 63 74 6f 72 20 66 6f 72 0a 2a 2a 20 74  tructor for.** t
2de30 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 2e 20 20 54  he collation.  T
2de40 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73  he destructor is
2de50 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65   called when the
2de60 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 0a 2a 2a   collation is.**
2de70 20 64 65 73 74 72 6f 79 65 64 20 61 6e 64 20 69   destroyed and i
2de80 73 20 70 61 73 73 65 64 20 61 20 63 6f 70 79 20  s passed a copy 
2de90 6f 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  of the fourth pa
2dea0 72 61 6d 65 74 65 72 20 76 6f 69 64 2a 20 70 6f  rameter void* po
2deb0 69 6e 74 65 72 0a 2a 2a 20 6f 66 20 74 68 65 20  inter.** of the 
2dec0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
2ded0 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a  ollation_v2()..*
2dee0 2a 20 43 6f 6c 6c 61 74 69 6f 6e 73 20 61 72 65  * Collations are
2def0 20 64 65 73 74 72 6f 79 65 64 20 77 68 65 6e 0a   destroyed when.
2df00 2a 2a 20 74 68 65 79 20 61 72 65 20 6f 76 65 72  ** they are over
2df10 72 69 64 64 65 6e 20 62 79 20 6c 61 74 65 72 20  ridden by later 
2df20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 63 6f 6c  calls to the col
2df30 6c 61 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20  lation creation 
2df40 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 6f 72 20  functions.** or 
2df50 77 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65  when the [sqlite
2df60 33 2a 5d 20 64 61 74 61 62 61 73 65 20 68 61 6e  3*] database han
2df70 64 6c 65 20 69 73 20 63 6c 6f 73 65 64 20 75 73  dle is closed us
2df80 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f  ing [sqlite3_clo
2df90 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  se()]..**.** INV
2dfa0 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
2dfb0 46 31 36 36 30 33 7d 20 41 20 73 75 63 63 65 73  F16603} A succes
2dfc0 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 74 68 65  sful call to the
2dfd0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
2dfe0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
2dff0 6c 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c  lation_v2(B,X,E,
2e000 50 2c 46 2c 44 29 5d 20 69 6e 74 65 72 66 61 63  P,F,D)] interfac
2e010 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  e.**          re
2e020 67 69 73 74 65 72 73 20 66 75 6e 63 74 69 6f 6e  gisters function
2e030 20 46 20 61 73 20 74 68 65 20 63 6f 6d 70 61 72   F as the compar
2e040 69 73 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 75 73  ison function us
2e050 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20  ed to.**        
2e060 20 20 69 6d 70 6c 65 6d 65 6e 74 20 63 6f 6c 6c    implement coll
2e070 61 74 69 6f 6e 20 58 20 6f 6e 20 5b 64 61 74 61  ation X on [data
2e080 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
2e090 20 42 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20   B for.**       
2e0a0 20 20 20 64 61 74 61 62 61 73 65 73 20 68 61 76     databases hav
2e0b0 69 6e 67 20 65 6e 63 6f 64 69 6e 67 20 45 2e 0a  ing encoding E..
2e0c0 2a 2a 0a 2a 2a 20 7b 46 31 36 36 30 34 7d 20 53  **.** {F16604} S
2e0d0 51 4c 69 74 65 20 75 6e 64 65 72 73 74 61 6e 64  QLite understand
2e0e0 73 20 74 68 65 20 58 20 70 61 72 61 6d 65 74 65  s the X paramete
2e0f0 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20  r to.**         
2e100 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2e110 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c  _collation_v2(B,
2e120 58 2c 45 2c 50 2c 46 2c 44 29 5d 20 61 73 20 61  X,E,P,F,D)] as a
2e130 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
2e140 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 55 54 46  .**          UTF
2e150 2d 38 20 73 74 72 69 6e 67 20 69 6e 20 77 68 69  -8 string in whi
2e160 63 68 20 63 61 73 65 20 69 73 20 69 67 6e 6f 72  ch case is ignor
2e170 65 64 20 66 6f 72 20 41 53 43 49 49 20 63 68 61  ed for ASCII cha
2e180 72 61 63 74 65 72 73 20 61 6e 64 0a 2a 2a 20 20  racters and.**  
2e190 20 20 20 20 20 20 20 20 69 73 20 73 69 67 6e 69          is signi
2e1a0 66 69 63 61 6e 74 20 66 6f 72 20 6e 6f 6e 2d 41  ficant for non-A
2e1b0 53 43 49 49 20 63 68 61 72 61 63 74 65 72 73 2e  SCII characters.
2e1c0 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36 30 36 7d 20  .**.** {F16606} 
2e1d0 53 75 63 63 65 73 73 69 76 65 20 63 61 6c 6c 73  Successive calls
2e1e0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65   to [sqlite3_cre
2e1f0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
2e200 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 0a 2a  (B,X,E,P,F,D)].*
2e210 2a 20 20 20 20 20 20 20 20 20 20 77 69 74 68 20  *          with 
2e220 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65 73 20  the same values 
2e230 66 6f 72 20 42 2c 20 58 2c 20 61 6e 64 20 45 2c  for B, X, and E,
2e240 20 6f 76 65 72 72 69 64 65 20 70 72 69 6f 72 20   override prior 
2e250 76 61 6c 75 65 73 0a 2a 2a 20 20 20 20 20 20 20  values.**       
2e260 20 20 20 6f 66 20 50 2c 20 46 2c 20 61 6e 64 20     of P, F, and 
2e270 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36 30 39  D..**.** {F16609
2e280 7d 20 54 68 65 20 64 65 73 74 72 75 63 74 6f 72  } The destructor
2e290 20 44 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 63   D in [sqlite3_c
2e2a0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
2e2b0 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d  v2(B,X,E,P,F,D)]
2e2c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20  .**          is 
2e2d0 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 69 74  not NULL then it
2e2e0 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20   is called with 
2e2f0 61 72 67 75 6d 65 6e 74 20 50 20 77 68 65 6e 20  argument P when 
2e300 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
2e310 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
2e320 6f 6e 20 69 73 20 64 72 6f 70 70 65 64 20 62 79  on is dropped by
2e330 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 7b   SQLite..**.** {
2e340 46 31 36 36 31 32 7d 20 41 20 63 6f 6c 6c 61 74  F16612} A collat
2e350 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ing function is 
2e360 64 72 6f 70 70 65 64 20 77 68 65 6e 20 69 74 20  dropped when it 
2e370 69 73 20 6f 76 65 72 6c 6f 61 64 65 64 2e 0a 2a  is overloaded..*
2e380 2a 0a 2a 2a 20 7b 46 31 36 36 31 35 7d 20 41 20  *.** {F16615} A 
2e390 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
2e3a0 6f 6e 20 69 73 20 64 72 6f 70 70 65 64 20 77 68  on is dropped wh
2e3b0 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
2e3c0 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20  connection.**   
2e3d0 20 20 20 20 20 20 20 69 73 20 63 6c 6f 73 65 64         is closed
2e3e0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
2e3f0 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  close()]..**.** 
2e400 7b 46 31 36 36 31 38 7d 20 54 68 65 20 70 6f 69  {F16618} The poi
2e410 6e 74 65 72 20 50 20 69 6e 20 5b 73 71 6c 69 74  nter P in [sqlit
2e420 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
2e430 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46  ion_v2(B,X,E,P,F
2e440 2c 44 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ,D)].**         
2e450 20 69 73 20 70 61 73 73 65 64 20 74 68 72 6f 75   is passed throu
2e460 67 68 20 61 73 20 74 68 65 20 66 69 72 73 74 20  gh as the first 
2e470 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
2e480 20 63 6f 6d 70 61 72 69 73 6f 6e 0a 2a 2a 20 20   comparison.**  
2e490 20 20 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e          function
2e4a0 20 46 20 66 6f 72 20 61 6c 6c 20 73 75 62 73 65   F for all subse
2e4b0 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e  quent invocation
2e4c0 73 20 6f 66 20 46 2e 0a 2a 2a 0a 2a 2a 20 7b 46  s of F..**.** {F
2e4d0 31 36 36 32 31 7d 20 41 20 63 61 6c 6c 20 74 6f  16621} A call to
2e4e0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2e4f0 5f 63 6f 6c 6c 61 74 69 6f 6e 28 42 2c 58 2c 45  _collation(B,X,E
2e500 2c 50 2c 46 29 5d 20 69 73 20 65 78 61 63 74 6c  ,P,F)] is exactl
2e510 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  y.**          th
2e520 65 20 73 61 6d 65 20 61 73 20 61 20 63 61 6c 6c  e same as a call
2e530 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65   to [sqlite3_cre
2e540 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
2e550 28 29 5d 20 77 69 74 68 0a 2a 2a 20 20 20 20 20  ()] with.**     
2e560 20 20 20 20 20 74 68 65 20 73 61 6d 65 20 70 61       the same pa
2e570 72 61 6d 65 74 65 72 73 20 61 6e 64 20 61 20 4e  rameters and a N
2e580 55 4c 4c 20 64 65 73 74 72 75 63 74 6f 72 2e 0a  ULL destructor..
2e590 2a 2a 0a 2a 2a 20 7b 46 31 36 36 32 34 7d 20 46  **.** {F16624} F
2e5a0 6f 6c 6c 6f 77 69 6e 67 20 61 20 5b 73 71 6c 69  ollowing a [sqli
2e5b0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
2e5c0 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c  tion_v2(B,X,E,P,
2e5d0 46 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  F,D)],.**       
2e5e0 20 20 20 53 51 4c 69 74 65 20 75 73 65 73 20 74     SQLite uses t
2e5f0 68 65 20 63 6f 6d 70 61 72 69 73 6f 6e 20 66 75  he comparison fu
2e600 6e 63 74 69 6f 6e 20 46 20 66 6f 72 20 61 6c 6c  nction F for all
2e610 20 74 65 78 74 20 63 6f 6d 70 61 72 69 73 6f 6e   text comparison
2e620 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 70 65  .**          ope
2e630 72 61 74 69 6f 6e 73 20 6f 6e 20 5b 64 61 74 61  rations on [data
2e640 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
2e650 20 42 20 6f 6e 20 74 65 78 74 20 76 61 6c 75 65   B on text value
2e660 73 20 74 68 61 74 0a 2a 2a 20 20 20 20 20 20 20  s that.**       
2e670 20 20 20 75 73 65 20 74 68 65 20 63 6f 6c 6c 61     use the colla
2e680 74 69 6e 67 20 73 65 71 75 65 6e 63 65 20 6e 61  ting sequence na
2e690 6d 65 20 58 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  me X..**.** {F16
2e6a0 36 32 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  627} The [sqlite
2e6b0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
2e6c0 6f 6e 31 36 28 42 2c 58 2c 45 2c 50 2c 46 29 5d  on16(B,X,E,P,F)]
2e6d0 20 77 6f 72 6b 73 20 74 68 65 20 73 61 6d 65 0a   works the same.
2e6e0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 73 20 5b  **          as [
2e6f0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
2e700 6f 6c 6c 61 74 69 6f 6e 28 42 2c 58 2c 45 2c 50  ollation(B,X,E,P
2e710 2c 46 29 5d 20 65 78 63 65 70 74 20 74 68 61 74  ,F)] except that
2e720 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
2e730 20 63 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 20   collation name 
2e740 58 20 69 73 20 75 6e 64 65 72 73 74 6f 6f 64 20  X is understood 
2e750 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74  as UTF-16 in nat
2e760 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 0a 2a  ive byte order.*
2e770 2a 20 20 20 20 20 20 20 20 20 20 69 6e 73 74 65  *          inste
2e780 61 64 20 6f 66 20 55 54 46 2d 38 2e 0a 2a 2a 0a  ad of UTF-8..**.
2e790 2a 2a 20 7b 46 31 36 36 33 30 7d 20 57 68 65 6e  ** {F16630} When
2e7a0 20 6d 75 6c 74 69 70 6c 65 20 63 6f 6d 70 61 72   multiple compar
2e7b0 69 73 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 20 61  ison functions a
2e7c0 72 65 20 61 76 61 69 6c 61 62 6c 65 20 66 6f 72  re available for
2e7d0 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20   the same.**    
2e7e0 20 20 20 20 20 20 63 6f 6c 6c 61 74 69 6e 67 20        collating 
2e7f0 73 65 71 75 65 6e 63 65 2c 20 53 51 4c 69 74 65  sequence, SQLite
2e800 20 63 68 6f 6f 73 65 73 20 74 68 65 20 6f 6e 65   chooses the one
2e810 20 77 68 6f 73 65 20 74 65 78 74 20 65 6e 63 6f   whose text enco
2e820 64 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20  ding.**         
2e830 20 72 65 71 75 69 72 65 73 20 74 68 65 20 6c 65   requires the le
2e840 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 63 6f  ast amount of co
2e850 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20 74 68  nversion from th
2e860 65 20 64 65 66 61 75 6c 74 0a 2a 2a 20 20 20 20  e default.**    
2e870 20 20 20 20 20 20 74 65 78 74 20 65 6e 63 6f 64        text encod
2e880 69 6e 67 20 6f 66 20 74 68 65 20 64 61 74 61 62  ing of the datab
2e890 61 73 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ase..*/.int sqli
2e8a0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
2e8b0 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a  tion(.  sqlite3*
2e8c0 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  , .  const char 
2e8d0 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65  *zName, .  int e
2e8e0 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64  TextRep, .  void
2e8f0 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61  *,.  int(*xCompa
2e900 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  re)(void*,int,co
2e910 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  nst void*,int,co
2e920 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e  nst void*).);.in
2e930 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
2e940 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a 20  _collation_v2(. 
2e950 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f   sqlite3*, .  co
2e960 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
2e970 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70   .  int eTextRep
2e980 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e  , .  void*,.  in
2e990 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69  t(*xCompare)(voi
2e9a0 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
2e9b0 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
2e9c0 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65  d*),.  void(*xDe
2e9d0 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b  stroy)(void*).);
2e9e0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65  .int sqlite3_cre
2e9f0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28  ate_collation16(
2ea00 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
2ea10 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
2ea20 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52  e, .  int eTextR
2ea30 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20  ep, .  void*,.  
2ea40 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76  int(*xCompare)(v
2ea50 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
2ea60 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
2ea70 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  oid*).);../*.** 
2ea80 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c 61 74  CAPI3REF: Collat
2ea90 69 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c 6c 62  ion Needed Callb
2eaa0 61 63 6b 73 20 7b 46 31 36 37 30 30 7d 0a 2a 2a  acks {F16700}.**
2eab0 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 68 61 76  .** To avoid hav
2eac0 69 6e 67 20 74 6f 20 72 65 67 69 73 74 65 72 20  ing to register 
2ead0 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  all collation se
2eae0 71 75 65 6e 63 65 73 20 62 65 66 6f 72 65 20 61  quences before a
2eaf0 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 61 6e   database.** can
2eb00 20 62 65 20 75 73 65 64 2c 20 61 20 73 69 6e 67   be used, a sing
2eb10 6c 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  le callback func
2eb20 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 69  tion may be regi
2eb30 73 74 65 72 65 64 20 77 69 74 68 20 74 68 65 0a  stered with the.
2eb40 2a 2a 20 64 61 74 61 62 61 73 65 20 68 61 6e 64  ** database hand
2eb50 6c 65 20 74 6f 20 62 65 20 63 61 6c 6c 65 64 20  le to be called 
2eb60 77 68 65 6e 65 76 65 72 20 61 6e 20 75 6e 64 65  whenever an unde
2eb70 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20  fined collation 
2eb80 73 65 71 75 65 6e 63 65 20 69 73 0a 2a 2a 20 72  sequence is.** r
2eb90 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  equired..**.** I
2eba0 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69  f the function i
2ebb0 73 20 72 65 67 69 73 74 65 72 65 64 20 75 73 69  s registered usi
2ebc0 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  ng the sqlite3_c
2ebd0 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28  ollation_needed(
2ebe0 29 20 41 50 49 2c 0a 2a 2a 20 74 68 65 6e 20 69  ) API,.** then i
2ebf0 74 20 69 73 20 70 61 73 73 65 64 20 74 68 65 20  t is passed the 
2ec00 6e 61 6d 65 73 20 6f 66 20 75 6e 64 65 66 69 6e  names of undefin
2ec10 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  ed collation seq
2ec20 75 65 6e 63 65 73 20 61 73 20 73 74 72 69 6e 67  uences as string
2ec30 73 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 69 6e 20  s.** encoded in 
2ec40 55 54 46 2d 38 2e 20 7b 46 31 36 37 30 33 7d 20  UTF-8. {F16703} 
2ec50 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  If sqlite3_colla
2ec60 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 20  tion_needed16() 
2ec70 69 73 20 75 73 65 64 2c 20 74 68 65 20 6e 61 6d  is used, the nam
2ec80 65 73 0a 2a 2a 20 61 72 65 20 70 61 73 73 65 64  es.** are passed
2ec90 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6d 61   as UTF-16 in ma
2eca0 63 68 69 6e 65 20 6e 61 74 69 76 65 20 62 79 74  chine native byt
2ecb0 65 20 6f 72 64 65 72 2e 20 41 20 63 61 6c 6c 20  e order. A call 
2ecc0 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 66 75 6e  to either.** fun
2ecd0 63 74 69 6f 6e 20 72 65 70 6c 61 63 65 73 20 61  ction replaces a
2ece0 6e 79 20 65 78 69 73 74 69 6e 67 20 63 61 6c 6c  ny existing call
2ecf0 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  back..**.** When
2ed00 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
2ed10 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20 66 69   invoked, the fi
2ed20 72 73 74 20 61 72 67 75 6d 65 6e 74 20 70 61 73  rst argument pas
2ed30 73 65 64 20 69 73 20 61 20 63 6f 70 79 0a 2a 2a  sed is a copy.**
2ed40 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61   of the second a
2ed50 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
2ed60 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
2ed70 64 65 64 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69  ded() or.** sqli
2ed80 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
2ed90 65 64 65 64 31 36 28 29 2e 20 20 54 68 65 20 73  eded16().  The s
2eda0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69  econd argument i
2edb0 73 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  s the database.*
2edc0 2a 20 68 61 6e 64 6c 65 2e 20 20 54 68 65 20 74  * handle.  The t
2edd0 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
2ede0 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f   one of [SQLITE_
2edf0 55 54 46 38 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  UTF8],.** [SQLIT
2ee00 45 5f 55 54 46 31 36 42 45 5d 2c 20 6f 72 20 5b  E_UTF16BE], or [
2ee10 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c  SQLITE_UTF16LE],
2ee20 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 65 20   indicating the 
2ee30 6d 6f 73 74 0a 2a 2a 20 64 65 73 69 72 61 62 6c  most.** desirabl
2ee40 65 20 66 6f 72 6d 20 6f 66 20 74 68 65 20 63 6f  e form of the co
2ee50 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
2ee60 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72   function requir
2ee70 65 64 2e 0a 2a 2a 20 54 68 65 20 66 6f 75 72 74  ed..** The fourt
2ee80 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  h parameter is t
2ee90 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a  he name of the.*
2eea0 2a 20 72 65 71 75 69 72 65 64 20 63 6f 6c 6c 61  * required colla
2eeb0 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 2e 0a 2a  tion sequence..*
2eec0 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63  *.** The callbac
2eed0 6b 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c  k function shoul
2eee0 64 20 72 65 67 69 73 74 65 72 20 74 68 65 20 64  d register the d
2eef0 65 73 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e  esired collation
2ef00 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
2ef10 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
2ef20 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  ion()], [sqlite3
2ef30 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
2ef40 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73  n16()], or.** [s
2ef50 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
2ef60 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a  llation_v2()]..*
2ef70 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
2ef80 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 37 30 32 7d 20  .**.** {F16702} 
2ef90 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  A successful cal
2efa0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  l to [sqlite3_co
2efb0 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 44  llation_needed(D
2efc0 2c 50 2c 46 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ,P,F)].**       
2efd0 20 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63     or [sqlite3_c
2efe0 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31  ollation_needed1
2eff0 36 28 44 2c 50 2c 46 29 5d 20 63 61 75 73 65 73  6(D,P,F)] causes
2f000 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
2f010 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2f020 63 74 69 6f 6e 5d 20 44 20 74 6f 20 69 6e 76 6f  ction] D to invo
2f030 6b 65 20 63 61 6c 6c 62 61 63 6b 20 46 20 77 69  ke callback F wi
2f040 74 68 20 66 69 72 73 74 0a 2a 2a 20 20 20 20 20  th first.**     
2f050 20 20 20 20 20 70 61 72 61 6d 65 74 65 72 20 50       parameter P
2f060 20 77 68 65 6e 65 76 65 72 20 69 74 20 6e 65 65   whenever it nee
2f070 64 73 20 61 20 63 6f 6d 70 61 72 69 73 6f 6e 20  ds a comparison 
2f080 66 75 6e 63 74 69 6f 6e 20 66 6f 72 20 61 0a 2a  function for a.*
2f090 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6c 6c 61  *          colla
2f0a0 74 69 6e 67 20 73 65 71 75 65 6e 63 65 20 74 68  ting sequence th
2f0b0 61 74 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 6b  at it does not k
2f0c0 6e 6f 77 20 61 62 6f 75 74 2e 0a 2a 2a 0a 2a 2a  now about..**.**
2f0d0 20 7b 46 31 36 37 30 34 7d 20 45 61 63 68 20 73   {F16704} Each s
2f0e0 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74  uccessful call t
2f0f0 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  o [sqlite3_colla
2f100 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d 20 6f  tion_needed()] o
2f110 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  r.**          [s
2f120 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
2f130 5f 6e 65 65 64 65 64 31 36 28 29 5d 20 6f 76 65  _needed16()] ove
2f140 72 72 69 64 65 73 20 74 68 65 20 63 61 6c 6c 62  rrides the callb
2f150 61 63 6b 20 72 65 67 69 73 74 65 72 65 64 0a 2a  ack registered.*
2f160 2a 20 20 20 20 20 20 20 20 20 20 6f 6e 20 74 68  *          on th
2f170 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65  e same [database
2f180 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 62 79 20   connection] by 
2f190 70 72 69 6f 72 20 63 61 6c 6c 73 20 74 6f 20 65  prior calls to e
2f1a0 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  ither.**        
2f1b0 20 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a    interface..**.
2f1c0 2a 2a 20 7b 46 31 36 37 30 36 7d 20 54 68 65 20  ** {F16706} The 
2f1d0 6e 61 6d 65 20 6f 66 20 74 68 65 20 72 65 71 75  name of the requ
2f1e0 65 73 74 65 64 20 63 6f 6c 6c 61 74 69 6e 67 20  ested collating 
2f1f0 66 75 6e 63 74 69 6f 6e 20 70 61 73 73 65 64 20  function passed 
2f200 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  in the.**       
2f210 20 20 20 34 74 68 20 70 61 72 61 6d 65 74 65 72     4th parameter
2f220 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
2f230 20 69 73 20 69 6e 20 55 54 46 2d 38 20 69 66 20   is in UTF-8 if 
2f240 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  the callback.** 
2f250 20 20 20 20 20 20 20 20 20 77 61 73 20 72 65 67           was reg
2f260 69 73 74 65 72 65 64 20 75 73 69 6e 67 20 5b 73  istered using [s
2f270 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
2f280 5f 6e 65 65 64 65 64 28 29 5d 20 61 6e 64 0a 2a  _needed()] and.*
2f290 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 69 6e  *          is in
2f2a0 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62   UTF-16 native b
2f2b0 79 74 65 20 6f 72 64 65 72 20 69 66 20 74 68 65  yte order if the
2f2c0 20 63 61 6c 6c 62 61 63 6b 20 77 61 73 0a 2a 2a   callback was.**
2f2d0 20 20 20 20 20 20 20 20 20 20 72 65 67 69 73 74            regist
2f2e0 65 72 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  ered using [sqli
2f2f0 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
2f300 65 64 65 64 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a  eded16()]..**.**
2f310 20 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33   .*/.int sqlite3
2f320 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
2f330 64 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  d(.  sqlite3*, .
2f340 20 20 76 6f 69 64 2a 2c 20 0a 20 20 76 6f 69 64    void*, .  void
2f350 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65  (*)(void*,sqlite
2f360 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c  3*,int eTextRep,
2f370 63 6f 6e 73 74 20 63 68 61 72 2a 29 0a 29 3b 0a  const char*).);.
2f380 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  int sqlite3_coll
2f390 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 0a  ation_needed16(.
2f3a0 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76    sqlite3*, .  v
2f3b0 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 28 2a 29 28  oid*,.  void(*)(
2f3c0 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69  void*,sqlite3*,i
2f3d0 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73  nt eTextRep,cons
2f3e0 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a  t void*).);../*.
2f3f0 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65 20 6b  ** Specify the k
2f400 65 79 20 66 6f 72 20 61 6e 20 65 6e 63 72 79 70  ey for an encryp
2f410 74 65 64 20 64 61 74 61 62 61 73 65 2e 20 20 54  ted database.  T
2f420 68 69 73 20 72 6f 75 74 69 6e 65 20 73 68 6f 75  his routine shou
2f430 6c 64 20 62 65 0a 2a 2a 20 63 61 6c 6c 65 64 20  ld be.** called 
2f440 72 69 67 68 74 20 61 66 74 65 72 20 73 71 6c 69  right after sqli
2f450 74 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a 0a 2a  te3_open()..**.*
2f460 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d  * The code to im
2f470 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49  plement this API
2f480 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c   is not availabl
2f490 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20  e in the public 
2f4a0 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51  release.** of SQ
2f4b0 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  Lite..*/.int sql
2f4c0 69 74 65 33 5f 6b 65 79 28 0a 20 20 73 71 6c 69  ite3_key(.  sqli
2f4d0 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
2f4e0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
2f4f0 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b  tabase to be rek
2f500 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  eyed */.  const 
2f510 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20  void *pKey, int 
2f520 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20  nKey     /* The 
2f530 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  key */.);../*.**
2f540 20 43 68 61 6e 67 65 20 74 68 65 20 6b 65 79 20   Change the key 
2f550 6f 6e 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62  on an open datab
2f560 61 73 65 2e 20 20 49 66 20 74 68 65 20 63 75 72  ase.  If the cur
2f570 72 65 6e 74 20 64 61 74 61 62 61 73 65 20 69 73  rent database is
2f580 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79 70 74 65   not.** encrypte
2f590 64 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  d, this routine 
2f5a0 77 69 6c 6c 20 65 6e 63 72 79 70 74 20 69 74 2e  will encrypt it.
2f5b0 20 20 49 66 20 70 4e 65 77 3d 3d 30 20 6f 72 20    If pNew==0 or 
2f5c0 6e 4e 65 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a 20  nNew==0, the.** 
2f5d0 64 61 74 61 62 61 73 65 20 69 73 20 64 65 63 72  database is decr
2f5e0 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ypted..**.** The
2f5f0 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65   code to impleme
2f600 6e 74 20 74 68 69 73 20 41 50 49 20 69 73 20 6e  nt this API is n
2f610 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20  ot available in 
2f620 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61  the public relea
2f630 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e  se.** of SQLite.
2f640 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2f650 72 65 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33  rekey(.  sqlite3
2f660 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
2f670 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
2f680 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65  ase to be rekeye
2f690 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  d */.  const voi
2f6a0 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65  d *pKey, int nKe
2f6b0 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6e 65 77  y     /* The new
2f6c0 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a   key */.);../*.*
2f6d0 2a 20 43 41 50 49 33 52 45 46 3a 20 20 53 75 73  * CAPI3REF:  Sus
2f6e0 70 65 6e 64 20 45 78 65 63 75 74 69 6f 6e 20 46  pend Execution F
2f6f0 6f 72 20 41 20 53 68 6f 72 74 20 54 69 6d 65 20  or A Short Time 
2f700 7b 46 31 30 35 33 30 7d 0a 2a 2a 0a 2a 2a 20 54  {F10530}.**.** T
2f710 68 65 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70  he sqlite3_sleep
2f720 28 29 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63  () function.** c
2f730 61 75 73 65 73 20 74 68 65 20 63 75 72 72 65 6e  auses the curren
2f740 74 20 74 68 72 65 61 64 20 74 6f 20 73 75 73 70  t thread to susp
2f750 65 6e 64 20 65 78 65 63 75 74 69 6f 6e 0a 2a 2a  end execution.**
2f760 20 66 6f 72 20 61 74 20 6c 65 61 73 74 20 61 20   for at least a 
2f770 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73  number of millis
2f780 65 63 6f 6e 64 73 20 73 70 65 63 69 66 69 65 64  econds specified
2f790 20 69 6e 20 69 74 73 20 70 61 72 61 6d 65 74 65   in its paramete
2f7a0 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  r..**.** If the 
2f7b0 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
2f7c0 20 64 6f 65 73 20 6e 6f 74 20 73 75 70 70 6f 72   does not suppor
2f7d0 74 20 73 6c 65 65 70 20 72 65 71 75 65 73 74 73  t sleep requests
2f7e0 20 77 69 74 68 20 0a 2a 2a 20 6d 69 6c 6c 69 73   with .** millis
2f7f0 65 63 6f 6e 64 20 74 69 6d 65 20 72 65 73 6f 6c  econd time resol
2f800 75 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20  ution, then the 
2f810 74 69 6d 65 20 77 69 6c 6c 20 62 65 20 72 6f 75  time will be rou
2f820 6e 64 65 64 20 75 70 20 74 6f 20 0a 2a 2a 20 74  nded up to .** t
2f830 68 65 20 6e 65 61 72 65 73 74 20 73 65 63 6f 6e  he nearest secon
2f840 64 2e 20 54 68 65 20 6e 75 6d 62 65 72 20 6f 66  d. The number of
2f850 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66   milliseconds of
2f860 20 73 6c 65 65 70 20 61 63 74 75 61 6c 6c 79 20   sleep actually 
2f870 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 66 72  .** requested fr
2f880 6f 6d 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  om the operating
2f890 20 73 79 73 74 65 6d 20 69 73 20 72 65 74 75 72   system is retur
2f8a0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  ned..**.** SQLit
2f8b0 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 69  e implements thi
2f8c0 73 20 69 6e 74 65 72 66 61 63 65 20 62 79 20 63  s interface by c
2f8d0 61 6c 6c 69 6e 67 20 74 68 65 20 78 53 6c 65 65  alling the xSlee
2f8e0 70 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66  p().** method of
2f8f0 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71   the default [sq
2f900 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
2f910 74 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  t..**.** INVARIA
2f920 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 35  NTS:.**.** {F105
2f930 33 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  33} The [sqlite3
2f940 5f 73 6c 65 65 70 28 4d 29 5d 20 69 6e 74 65 72  _sleep(M)] inter
2f950 66 61 63 65 20 69 6e 76 6f 6b 65 73 20 74 68 65  face invokes the
2f960 20 78 53 6c 65 65 70 0a 2a 2a 20 20 20 20 20 20   xSleep.**      
2f970 20 20 20 20 6d 65 74 68 6f 64 20 6f 66 20 74 68      method of th
2f980 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  e default [sqlit
2f990 65 33 5f 76 66 73 7c 56 46 53 5d 20 69 6e 20 6f  e3_vfs|VFS] in o
2f9a0 72 64 65 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20  rder to.**      
2f9b0 20 20 20 20 73 75 73 70 65 6e 64 20 65 78 65 63      suspend exec
2f9c0 75 74 69 6f 6e 20 6f 66 20 74 68 65 20 63 75 72  ution of the cur
2f9d0 72 65 6e 74 20 74 68 72 65 61 64 20 66 6f 72 20  rent thread for 
2f9e0 61 74 20 6c 65 61 73 74 0a 2a 2a 20 20 20 20 20  at least.**     
2f9f0 20 20 20 20 20 4d 20 6d 69 6c 6c 69 73 65 63 6f       M milliseco
2fa00 6e 64 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 35  nds..**.** {F105
2fa10 33 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  36} The [sqlite3
2fa20 5f 73 6c 65 65 70 28 4d 29 5d 20 69 6e 74 65 72  _sleep(M)] inter
2fa30 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
2fa40 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 20 20   number of.**   
2fa50 20 20 20 20 20 20 20 6d 69 6c 6c 69 73 65 63 6f         milliseco
2fa60 6e 64 73 20 6f 66 20 73 6c 65 65 70 20 61 63 74  nds of sleep act
2fa70 75 61 6c 6c 79 20 72 65 71 75 65 73 74 65 64 20  ually requested 
2fa80 6f 66 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  of the operating
2fa90 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 79 73  .**          sys
2faa0 74 65 6d 2c 20 77 68 69 63 68 20 6d 69 67 68 74  tem, which might
2fab0 20 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20   be larger than 
2fac0 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 4d 2e  the parameter M.
2fad0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2fae0 73 6c 65 65 70 28 69 6e 74 29 3b 0a 0a 2f 2a 0a  sleep(int);../*.
2faf0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 4e 61  ** CAPI3REF:  Na
2fb00 6d 65 20 4f 66 20 54 68 65 20 46 6f 6c 64 65 72  me Of The Folder
2fb10 20 48 6f 6c 64 69 6e 67 20 54 65 6d 70 6f 72 61   Holding Tempora
2fb20 72 79 20 46 69 6c 65 73 20 7b 46 31 30 33 31 30  ry Files {F10310
2fb30 7d 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 69 73 20  }.**.** If this 
2fb40 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 20  global variable 
2fb50 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74  is made to point
2fb60 20 74 6f 20 61 20 73 74 72 69 6e 67 20 77 68 69   to a string whi
2fb70 63 68 20 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d  ch is.** the nam
2fb80 65 20 6f 66 20 61 20 66 6f 6c 64 65 72 20 28 61  e of a folder (a
2fb90 2e 6b 61 2e 20 64 69 72 65 63 74 6f 72 79 29 2c  .ka. directory),
2fba0 20 74 68 65 6e 20 61 6c 6c 20 74 65 6d 70 6f 72   then all tempor
2fbb0 61 72 79 20 66 69 6c 65 73 0a 2a 2a 20 63 72 65  ary files.** cre
2fbc0 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 20 77  ated by SQLite w
2fbd0 69 6c 6c 20 62 65 20 70 6c 61 63 65 64 20 69 6e  ill be placed in
2fbe0 20 74 68 61 74 20 64 69 72 65 63 74 6f 72 79 2e   that directory.
2fbf0 20 20 49 66 20 74 68 69 73 20 76 61 72 69 61 62    If this variab
2fc00 6c 65 0a 2a 2a 20 69 73 20 4e 55 4c 4c 20 70 6f  le.** is NULL po
2fc10 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69  inter, then SQLi
2fc20 74 65 20 64 6f 65 73 20 61 20 73 65 61 72 63 68  te does a search
2fc30 20 66 6f 72 20 61 6e 20 61 70 70 72 6f 70 72 69   for an appropri
2fc40 61 74 65 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a  ate temporary.**
2fc50 20 66 69 6c 65 20 64 69 72 65 63 74 6f 72 79 2e   file directory.
2fc60 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74  .**.** It is not
2fc70 20 73 61 66 65 20 74 6f 20 6d 6f 64 69 66 79 20   safe to modify 
2fc80 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 6f 6e  this variable on
2fc90 63 65 20 61 20 64 61 74 61 62 61 73 65 20 63 6f  ce a database co
2fca0 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 68 61 73 20  nnection.** has 
2fcb0 62 65 65 6e 20 6f 70 65 6e 65 64 2e 20 20 49 74  been opened.  It
2fcc0 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 68 61   is intended tha
2fcd0 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  t this variable 
2fce0 62 65 20 73 65 74 20 6f 6e 63 65 0a 2a 2a 20 61  be set once.** a
2fcf0 73 20 70 61 72 74 20 6f 66 20 70 72 6f 63 65 73  s part of proces
2fd00 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  s initialization
2fd10 20 61 6e 64 20 62 65 66 6f 72 65 20 61 6e 79 20   and before any 
2fd20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
2fd30 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 68 61 76  .** routines hav
2fd40 65 20 62 65 65 6e 20 63 61 6c 6c 20 61 6e 64 20  e been call and 
2fd50 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65 64  remain unchanged
2fd60 20 74 68 65 72 65 61 66 74 65 72 2e 0a 2a 2f 0a   thereafter..*/.
2fd70 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 63 68  SQLITE_EXTERN ch
2fd80 61 72 20 2a 73 71 6c 69 74 65 33 5f 74 65 6d 70  ar *sqlite3_temp
2fd90 5f 64 69 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a  _directory;../*.
2fda0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 54 65  ** CAPI3REF:  Te
2fdb0 73 74 20 54 6f 20 53 65 65 20 49 66 20 54 68 65  st To See If The
2fdc0 20 44 61 74 61 62 61 73 65 20 49 73 20 49 6e 20   Database Is In 
2fdd0 41 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d 6f 64 65  Auto-Commit Mode
2fde0 20 7b 46 31 32 39 33 30 7d 0a 2a 2a 0a 2a 2a 20   {F12930}.**.** 
2fdf0 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
2fe00 61 75 74 6f 63 6f 6d 6d 69 74 28 29 20 69 6e 74  autocommit() int
2fe10 65 72 66 61 63 65 73 20 72 65 74 75 72 6e 73 20  erfaces returns 
2fe20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20 7a  non-zero or.** z
2fe30 65 72 6f 20 69 66 20 74 68 65 20 67 69 76 65 6e  ero if the given
2fe40 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
2fe50 74 69 6f 6e 20 69 73 20 6f 72 20 69 73 20 6e 6f  tion is or is no
2fe60 74 20 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 20  t in autocommit 
2fe70 6d 6f 64 65 2c 0a 2a 2a 20 72 65 73 70 65 63 74  mode,.** respect
2fe80 69 76 65 6c 79 2e 20 20 20 41 75 74 6f 63 6f 6d  ively.   Autocom
2fe90 6d 69 74 20 6d 6f 64 65 20 69 73 20 6f 6e 0a 2a  mit mode is on.*
2fea0 2a 20 62 79 20 64 65 66 61 75 6c 74 2e 20 20 41  * by default.  A
2feb0 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69  utocommit mode i
2fec0 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 61 20  s disabled by a 
2fed0 5b 42 45 47 49 4e 5d 20 73 74 61 74 65 6d 65 6e  [BEGIN] statemen
2fee0 74 2e 0a 2a 2a 20 41 75 74 6f 63 6f 6d 6d 69 74  t..** Autocommit
2fef0 20 6d 6f 64 65 20 69 73 20 72 65 65 6e 61 62 6c   mode is reenabl
2ff00 65 64 20 62 79 20 61 20 5b 43 4f 4d 4d 49 54 5d  ed by a [COMMIT]
2ff10 20 6f 72 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a   or [ROLLBACK]..
2ff20 2a 2a 0a 2a 2a 20 49 66 20 63 65 72 74 61 69 6e  **.** If certain
2ff30 20 6b 69 6e 64 73 20 6f 66 20 65 72 72 6f 72 73   kinds of errors
2ff40 20 6f 63 63 75 72 20 6f 6e 20 61 20 73 74 61 74   occur on a stat
2ff50 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20 6d  ement within a m
2ff60 75 6c 74 69 2d 73 74 61 74 65 6d 65 6e 74 0a 2a  ulti-statement.*
2ff70 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 73 20 28  * transactions (
2ff80 65 72 72 6f 72 73 20 69 6e 63 6c 75 64 69 6e 67  errors including
2ff90 20 5b 53 51 4c 49 54 45 5f 46 55 4c 4c 5d 2c 20   [SQLITE_FULL], 
2ffa0 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 2c 20  [SQLITE_IOERR], 
2ffb0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45  .** [SQLITE_NOME
2ffc0 4d 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  M], [SQLITE_BUSY
2ffd0 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 49  ], and [SQLITE_I
2ffe0 4e 54 45 52 52 55 50 54 5d 29 20 74 68 65 6e 20  NTERRUPT]) then 
2fff0 74 68 65 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69  the.** transacti
30000 6f 6e 20 6d 69 67 68 74 20 62 65 20 72 6f 6c 6c  on might be roll
30010 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69  ed back automati
30020 63 61 6c 6c 79 2e 20 20 54 68 65 20 6f 6e 6c 79  cally.  The only
30030 20 77 61 79 20 74 6f 0a 2a 2a 20 66 69 6e 64 20   way to.** find 
30040 6f 75 74 20 69 66 20 53 51 4c 69 74 65 20 61 75  out if SQLite au
30050 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c  tomatically roll
30060 65 64 20 62 61 63 6b 20 74 68 65 20 74 72 61 6e  ed back the tran
30070 73 61 63 74 69 6f 6e 20 61 66 74 65 72 0a 2a 2a  saction after.**
30080 20 61 6e 20 65 72 72 6f 72 20 69 73 20 74 6f 20   an error is to 
30090 75 73 65 20 74 68 69 73 20 66 75 6e 63 74 69 6f  use this functio
300a0 6e 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  n..**.** INVARIA
300b0 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39  NTS:.**.** {F129
300c0 33 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  31} The [sqlite3
300d0 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28  _get_autocommit(
300e0 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  D)] interface re
300f0 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 6f  turns non-zero o
30100 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65  r.**          ze
30110 72 6f 20 69 66 20 74 68 65 20 5b 64 61 74 61 62  ro if the [datab
30120 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
30130 44 20 69 73 20 6f 72 20 69 73 20 6e 6f 74 20 69  D is or is not i
30140 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 0a 2a 2a 20  n autocommit.** 
30150 20 20 20 20 20 20 20 20 20 6d 6f 64 65 2c 20 72           mode, r
30160 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a  espectively..**.
30170 2a 2a 20 7b 46 31 32 39 33 32 7d 20 41 75 74 6f  ** {F12932} Auto
30180 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 6f  commit mode is o
30190 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a  n by default..**
301a0 0a 2a 2a 20 7b 46 31 32 39 33 33 7d 20 41 75 74  .** {F12933} Aut
301b0 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20  ocommit mode is 
301c0 64 69 73 61 62 6c 65 64 20 62 79 20 61 20 73 75  disabled by a su
301d0 63 63 65 73 73 66 75 6c 20 5b 42 45 47 49 4e 5d  ccessful [BEGIN]
301e0 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a   statement..**.*
301f0 2a 20 7b 46 31 32 39 33 34 7d 20 41 75 74 6f 63  * {F12934} Autoc
30200 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 65 6e  ommit mode is en
30210 61 62 6c 65 64 20 62 79 20 61 20 73 75 63 63 65  abled by a succe
30220 73 73 66 75 6c 20 5b 43 4f 4d 4d 49 54 5d 20 6f  ssful [COMMIT] o
30230 72 20 5b 52 4f 4c 4c 42 41 43 4b 5d 0a 2a 2a 20  r [ROLLBACK].** 
30240 20 20 20 20 20 20 20 20 20 73 74 61 74 65 6d 65           stateme
30250 6e 74 2e 0a 2a 2a 20 0a 2a 2a 0a 2a 2a 20 4c 49  nt..** .**.** LI
30260 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a 2a 0a 2a  MITATIONS:.***.*
30270 2a 20 7b 55 31 32 39 33 36 7d 20 49 66 20 61 6e  * {U12936} If an
30280 6f 74 68 65 72 20 74 68 72 65 61 64 20 63 68 61  other thread cha
30290 6e 67 65 73 20 74 68 65 20 61 75 74 6f 63 6f 6d  nges the autocom
302a0 6d 69 74 20 73 74 61 74 75 73 20 6f 66 20 74 68  mit status of th
302b0 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 20 20  e database.**   
302c0 20 20 20 20 20 20 20 63 6f 6e 6e 65 63 74 69 6f         connectio
302d0 6e 20 77 68 69 6c 65 20 74 68 69 73 20 72 6f 75  n while this rou
302e0 74 69 6e 65 20 69 73 20 72 75 6e 6e 69 6e 67 2c  tine is running,
302f0 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e   then the return
30300 20 76 61 6c 75 65 0a 2a 2a 20 20 20 20 20 20 20   value.**       
30310 20 20 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e     is undefined.
30320 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
30330 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 73  get_autocommit(s
30340 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
30350 20 43 41 50 49 33 52 45 46 3a 20 20 46 69 6e 64   CAPI3REF:  Find
30360 20 54 68 65 20 44 61 74 61 62 61 73 65 20 48 61   The Database Ha
30370 6e 64 6c 65 20 4f 66 20 41 20 50 72 65 70 61 72  ndle Of A Prepar
30380 65 64 20 53 74 61 74 65 6d 65 6e 74 20 7b 46 31  ed Statement {F1
30390 33 31 32 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20  3120}.**.** The 
303a0 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c  sqlite3_db_handl
303b0 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72  e interface.** r
303c0 65 74 75 72 6e 73 20 74 68 65 20 5b 73 71 6c 69  eturns the [sqli
303d0 74 65 33 2a 5d 20 64 61 74 61 62 61 73 65 20 68  te3*] database h
303e0 61 6e 64 6c 65 20 74 6f 20 77 68 69 63 68 20 61  andle to which a
303f0 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
30400 61 74 65 6d 65 6e 74 5d 20 62 65 6c 6f 6e 67 73  atement] belongs
30410 2e 0a 2a 2a 20 54 68 65 20 64 61 74 61 62 61 73  ..** The databas
30420 65 20 68 61 6e 64 6c 65 20 72 65 74 75 72 6e 65  e handle returne
30430 64 20 62 79 20 73 71 6c 69 74 65 33 5f 64 62 5f  d by sqlite3_db_
30440 68 61 6e 64 6c 65 0a 2a 2a 20 69 73 20 74 68 65  handle.** is the
30450 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 68   same database h
30460 61 6e 64 6c 65 20 74 68 61 74 20 77 61 73 0a 2a  andle that was.*
30470 2a 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  * the first argu
30480 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c  ment to the [sql
30490 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
304a0 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e  )] or its varian
304b0 74 73 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 75  ts.** that was u
304c0 73 65 64 20 74 6f 20 63 72 65 61 74 65 20 74 68  sed to create th
304d0 65 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74  e statement in t
304e0 68 65 20 66 69 72 73 74 20 70 6c 61 63 65 2e 0a  he first place..
304f0 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
30500 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 31 32 33 7d  :.**.** {F13123}
30510 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62   The [sqlite3_db
30520 5f 68 61 6e 64 6c 65 28 53 29 5d 20 69 6e 74 65  _handle(S)] inte
30530 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
30540 70 6f 69 6e 74 65 72 0a 2a 2a 20 20 20 20 20 20  pointer.**      
30550 20 20 20 20 74 6f 20 74 68 65 20 5b 64 61 74 61      to the [data
30560 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
30570 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
30580 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
30590 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
305a0 5d 20 53 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20  ] S..*/.sqlite3 
305b0 2a 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64  *sqlite3_db_hand
305c0 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  le(sqlite3_stmt*
305d0 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  );.../*.** CAPI3
305e0 52 45 46 3a 20 43 6f 6d 6d 69 74 20 41 6e 64 20  REF: Commit And 
305f0 52 6f 6c 6c 62 61 63 6b 20 4e 6f 74 69 66 69 63  Rollback Notific
30600 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 20  ation Callbacks 
30610 7b 46 31 32 39 35 30 7d 0a 2a 2a 0a 2a 2a 20 54  {F12950}.**.** T
30620 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69  he sqlite3_commi
30630 74 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61  t_hook() interfa
30640 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63  ce registers a c
30650 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74  allback.** funct
30660 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65  ion to be invoke
30670 64 20 77 68 65 6e 65 76 65 72 20 61 20 74 72 61  d whenever a tra
30680 6e 73 61 63 74 69 6f 6e 20 69 73 20 63 6f 6d 6d  nsaction is comm
30690 69 74 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 63 61  itted..** Any ca
306a0 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61 20  llback set by a 
306b0 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f  previous call to
306c0 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f   sqlite3_commit_
306d0 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68  hook().** for th
306e0 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
306f0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76  connection is ov
30700 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 54 68 65  erridden..** The
30710 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63   sqlite3_rollbac
30720 6b 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61  k_hook() interfa
30730 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63  ce registers a c
30740 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74  allback.** funct
30750 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65  ion to be invoke
30760 64 20 77 68 65 6e 65 76 65 72 20 61 20 74 72 61  d whenever a tra
30770 6e 73 61 63 74 69 6f 6e 20 69 73 20 63 6f 6d 6d  nsaction is comm
30780 69 74 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 63 61  itted..** Any ca
30790 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61 20  llback set by a 
307a0 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f  previous call to
307b0 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f   sqlite3_commit_
307c0 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68  hook().** for th
307d0 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
307e0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76  connection is ov
307f0 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 54 68 65  erridden..** The
30800 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20 69   pArg argument i
30810 73 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68  s passed through
30820 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  .** to the callb
30830 61 63 6b 2e 20 20 49 66 20 74 68 65 20 63 61 6c  ack.  If the cal
30840 6c 62 61 63 6b 20 6f 6e 20 61 20 63 6f 6d 6d 69  lback on a commi
30850 74 20 68 6f 6f 6b 20 66 75 6e 63 74 69 6f 6e 20  t hook function 
30860 0a 2a 2a 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  .** returns non-
30870 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 63  zero, then the c
30880 6f 6d 6d 69 74 20 69 73 20 63 6f 6e 76 65 72 74  ommit is convert
30890 65 64 20 69 6e 74 6f 20 61 20 72 6f 6c 6c 62 61  ed into a rollba
308a0 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f  ck..**.** If ano
308b0 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 77 61  ther function wa
308c0 73 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 67  s previously reg
308d0 69 73 74 65 72 65 64 2c 20 69 74 73 0a 2a 2a 20  istered, its.** 
308e0 70 41 72 67 20 76 61 6c 75 65 20 69 73 20 72 65  pArg value is re
308f0 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69  turned.  Otherwi
30900 73 65 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72  se NULL is retur
30910 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73  ned..**.** Regis
30920 74 65 72 69 6e 67 20 61 20 4e 55 4c 4c 20 66 75  tering a NULL fu
30930 6e 63 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 20  nction disables 
30940 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  the callback..**
30950 0a 2a 2a 20 46 6f 72 20 74 68 65 20 70 75 72 70  .** For the purp
30960 6f 73 65 73 20 6f 66 20 74 68 69 73 20 41 50 49  oses of this API
30970 2c 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  , a transaction 
30980 69 73 20 73 61 69 64 20 74 6f 20 68 61 76 65 20  is said to have 
30990 62 65 65 6e 20 0a 2a 2a 20 72 6f 6c 6c 65 64 20  been .** rolled 
309a0 62 61 63 6b 20 69 66 20 61 6e 20 65 78 70 6c 69  back if an expli
309b0 63 69 74 20 22 52 4f 4c 4c 42 41 43 4b 22 20 73  cit "ROLLBACK" s
309c0 74 61 74 65 6d 65 6e 74 20 69 73 20 65 78 65 63  tatement is exec
309d0 75 74 65 64 2c 20 6f 72 0a 2a 2a 20 61 6e 20 65  uted, or.** an e
309e0 72 72 6f 72 20 6f 72 20 63 6f 6e 73 74 72 61 69  rror or constrai
309f0 6e 74 20 63 61 75 73 65 73 20 61 6e 20 69 6d 70  nt causes an imp
30a00 6c 69 63 69 74 20 72 6f 6c 6c 62 61 63 6b 20 74  licit rollback t
30a10 6f 20 6f 63 63 75 72 2e 0a 2a 2a 20 54 68 65 20  o occur..** The 
30a20 72 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c 62 61 63  rollback callbac
30a30 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64  k is not invoked
30a40 20 69 66 20 61 20 74 72 61 6e 73 61 63 74 69 6f   if a transactio
30a50 6e 20 69 73 0a 2a 2a 20 61 75 74 6f 6d 61 74 69  n is.** automati
30a60 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63  cally rolled bac
30a70 6b 20 62 65 63 61 75 73 65 20 74 68 65 20 64 61  k because the da
30a80 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
30a90 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20  n is closed..** 
30aa0 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 63 61 6c  The rollback cal
30ab0 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76  lback is not inv
30ac0 6f 6b 65 64 20 69 66 20 61 20 74 72 61 6e 73 61  oked if a transa
30ad0 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 72 6f 6c 6c  ction is.** roll
30ae0 65 64 20 62 61 63 6b 20 62 65 63 61 75 73 65 20  ed back because 
30af0 61 20 63 6f 6d 6d 69 74 20 63 61 6c 6c 62 61 63  a commit callbac
30b00 6b 20 72 65 74 75 72 6e 65 64 20 6e 6f 6e 2d 7a  k returned non-z
30b10 65 72 6f 2e 0a 2a 2a 20 3c 74 6f 64 6f 3e 20 43  ero..** <todo> C
30b20 68 65 63 6b 20 6f 6e 20 74 68 69 73 20 3c 2f 74  heck on this </t
30b30 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  odo>.**.** These
30b40 20 61 72 65 20 65 78 70 65 72 69 6d 65 6e 74 61   are experimenta
30b50 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 6e 64  l interfaces and
30b60 20 61 72 65 20 73 75 62 6a 65 63 74 20 74 6f 20   are subject to 
30b70 63 68 61 6e 67 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e  change..**.** IN
30b80 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
30b90 7b 46 31 32 39 35 31 7d 20 54 68 65 20 5b 73 71  {F12951} The [sq
30ba0 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f  lite3_commit_hoo
30bb0 6b 28 44 2c 46 2c 50 29 5d 20 69 6e 74 65 72 66  k(D,F,P)] interf
30bc0 61 63 65 20 72 65 67 69 73 74 65 72 73 20 74 68  ace registers th
30bd0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61  e.**          ca
30be0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
30bf0 46 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20  F to be invoked 
30c00 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 50 20  with argument P 
30c10 77 68 65 6e 65 76 65 72 0a 2a 2a 20 20 20 20 20  whenever.**     
30c20 20 20 20 20 20 61 20 74 72 61 6e 73 61 63 74 69       a transacti
30c30 6f 6e 20 63 6f 6d 6d 69 74 73 20 6f 6e 20 5b 64  on commits on [d
30c40 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
30c50 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  on] D..**.** {F1
30c60 32 39 35 32 7d 20 54 68 65 20 5b 73 71 6c 69 74  2952} The [sqlit
30c70 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44  e3_commit_hook(D
30c80 2c 46 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 65  ,F,P)] interface
30c90 20 72 65 74 75 72 6e 73 20 74 68 65 20 50 0a 2a   returns the P.*
30ca0 2a 20 20 20 20 20 20 20 20 20 20 61 72 67 75 6d  *          argum
30cb0 65 6e 74 20 66 72 6f 6d 20 74 68 65 20 70 72 65  ent from the pre
30cc0 76 69 6f 75 73 20 63 61 6c 6c 20 77 69 74 68 20  vious call with 
30cd0 74 68 65 20 73 61 6d 65 20 0a 2a 2a 20 20 20 20  the same .**    
30ce0 20 20 20 20 20 20 5b 64 61 74 61 62 61 73 65 20        [database 
30cf0 63 6f 6e 6e 65 63 74 69 6f 6e 20 5d 20 44 20 2c  connection ] D ,
30d00 20 6f 72 20 4e 55 4c 4c 20 6f 6e 20 74 68 65 20   or NULL on the 
30d10 66 69 72 73 74 20 63 61 6c 6c 0a 2a 2a 20 20 20  first call.**   
30d20 20 20 20 20 20 20 20 66 6f 72 20 61 20 70 61 72         for a par
30d30 74 69 63 75 6c 61 72 20 5b 64 61 74 61 62 61 73  ticular [databas
30d40 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e  e connection] D.
30d50 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 35 33 7d 20  .**.** {F12953} 
30d60 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71  Each call to [sq
30d70 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f  lite3_commit_hoo
30d80 6b 28 29 5d 20 6f 76 65 72 77 72 69 74 65 73 20  k()] overwrites 
30d90 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  the callback.** 
30da0 20 20 20 20 20 20 20 20 20 72 65 67 69 73 74 65           registe
30db0 72 65 64 20 62 79 20 70 72 69 6f 72 20 63 61 6c  red by prior cal
30dc0 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 35  ls..**.** {F1295
30dd0 34 7d 20 49 66 20 74 68 65 20 46 20 61 72 67 75  4} If the F argu
30de0 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  ment to [sqlite3
30df0 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c 46  _commit_hook(D,F
30e00 2c 50 29 5d 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20  ,P)] is NULL.** 
30e10 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 74 68           then th
30e20 65 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 63 61  e commit hook ca
30e30 6c 6c 62 61 63 6b 20 69 73 20 63 61 6e 63 65 6c  llback is cancel
30e40 6c 65 64 20 61 6e 64 20 6e 6f 20 63 61 6c 6c 62  led and no callb
30e50 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ack.**          
30e60 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20  is invoked when 
30e70 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f  a transaction co
30e80 6d 6d 69 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  mmits..**.** {F1
30e90 32 39 35 35 7d 20 49 66 20 74 68 65 20 63 6f 6d  2955} If the com
30ea0 6d 69 74 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  mit callback ret
30eb0 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 74 68  urns non-zero th
30ec0 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 69 73  en the commit is
30ed0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e  .**          con
30ee0 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20 72 6f  verted into a ro
30ef0 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 46  llback..**.** {F
30f00 31 32 39 36 31 7d 20 54 68 65 20 5b 73 71 6c 69  12961} The [sqli
30f10 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f  te3_rollback_hoo
30f20 6b 28 44 2c 46 2c 50 29 5d 20 69 6e 74 65 72 66  k(D,F,P)] interf
30f30 61 63 65 20 72 65 67 69 73 74 65 72 73 20 74 68  ace registers th
30f40 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61  e.**          ca
30f50 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
30f60 46 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20  F to be invoked 
30f70 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 50 20  with argument P 
30f80 77 68 65 6e 65 76 65 72 0a 2a 2a 20 20 20 20 20  whenever.**     
30f90 20 20 20 20 20 61 20 74 72 61 6e 73 61 63 74 69       a transacti
30fa0 6f 6e 20 72 6f 6c 6c 73 20 62 61 63 6b 20 6f 6e  on rolls back on
30fb0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
30fc0 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20  ction] D..**.** 
30fd0 7b 46 31 32 39 36 32 7d 20 54 68 65 20 5b 73 71  {F12962} The [sq
30fe0 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68  lite3_rollback_h
30ff0 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 6e 74 65  ook(D,F,P)] inte
31000 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
31010 65 20 50 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  e P.**          
31020 61 72 67 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68  argument from th
31030 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  e previous call 
31040 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 0a 2a  with the same .*
31050 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61 74 61  *          [data
31060 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
31070 5d 20 44 20 2c 20 6f 72 20 4e 55 4c 4c 20 6f 6e  ] D , or NULL on
31080 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 0a   the first call.
31090 2a 2a 20 20 20 20 20 20 20 20 20 20 66 6f 72 20  **          for 
310a0 61 20 70 61 72 74 69 63 75 6c 61 72 20 5b 64 61  a particular [da
310b0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
310c0 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  n] D..**.** {F12
310d0 39 36 33 7d 20 45 61 63 68 20 63 61 6c 6c 20 74  963} Each call t
310e0 6f 20 5b 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62  o [sqlite3_rollb
310f0 61 63 6b 5f 68 6f 6f 6b 28 29 5d 20 6f 76 65 72  ack_hook()] over
31100 77 72 69 74 65 73 20 74 68 65 20 63 61 6c 6c 62  writes the callb
31110 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ack.**          
31120 72 65 67 69 73 74 65 72 65 64 20 62 79 20 70 72  registered by pr
31130 69 6f 72 20 63 61 6c 6c 73 2e 0a 2a 2a 0a 2a 2a  ior calls..**.**
31140 20 7b 46 31 32 39 36 34 7d 20 49 66 20 74 68 65   {F12964} If the
31150 20 46 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b   F argument to [
31160 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b  sqlite3_rollback
31170 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 73  _hook(D,F,P)] is
31180 20 4e 55 4c 4c 0a 2a 2a 20 20 20 20 20 20 20 20   NULL.**        
31190 20 20 74 68 65 6e 20 74 68 65 20 72 6f 6c 6c 62    then the rollb
311a0 61 63 6b 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63  ack hook callbac
311b0 6b 20 69 73 20 63 61 6e 63 65 6c 6c 65 64 20 61  k is cancelled a
311c0 6e 64 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 0a 2a  nd no callback.*
311d0 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 69 6e  *          is in
311e0 76 6f 6b 65 64 20 77 68 65 6e 20 61 20 74 72 61  voked when a tra
311f0 6e 73 61 63 74 69 6f 6e 20 72 6f 6c 6c 73 20 62  nsaction rolls b
31200 61 63 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  ack..*/.void *sq
31210 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f  lite3_commit_hoo
31220 6b 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28  k(sqlite3*, int(
31230 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a  *)(void*), void*
31240 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  );.void *sqlite3
31250 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 73  _rollback_hook(s
31260 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 29  qlite3*, void(*)
31270 28 76 6f 69 64 20 2a 29 2c 20 76 6f 69 64 2a 29  (void *), void*)
31280 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
31290 46 3a 20 44 61 74 61 20 43 68 61 6e 67 65 20 4e  F: Data Change N
312a0 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c  otification Call
312b0 62 61 63 6b 73 20 7b 46 31 32 39 37 30 7d 0a 2a  backs {F12970}.*
312c0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
312d0 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 20 69  _update_hook() i
312e0 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 65 67 69  nterface.** regi
312f0 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b  sters a callback
31300 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 74   function with t
31310 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
31320 65 63 74 69 6f 6e 20 69 64 65 6e 74 69 66 69 65  ection identifie
31330 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 66 69 72  d by the .** fir
31340 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 62  st argument to b
31350 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76  e invoked whenev
31360 65 72 20 61 20 72 6f 77 20 69 73 20 75 70 64 61  er a row is upda
31370 74 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72  ted, inserted or
31380 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 41 6e 79   deleted..** Any
31390 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79   callback set by
313a0 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c   a previous call
313b0 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f   to this functio
313c0 6e 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 0a  n for the same .
313d0 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
313e0 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69  ection is overri
313f0 64 64 65 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  dden..**.** The 
31400 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
31410 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
31420 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  the function to 
31430 69 6e 76 6f 6b 65 20 77 68 65 6e 20 61 20 0a 2a  invoke when a .*
31440 2a 20 72 6f 77 20 69 73 20 75 70 64 61 74 65 64  * row is updated
31450 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65  , inserted or de
31460 6c 65 74 65 64 2e 20 0a 2a 2a 20 54 68 65 20 66  leted. .** The f
31470 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
31480 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
31490 0a 2a 2a 20 61 20 63 6f 70 79 20 6f 66 20 74 68  .** a copy of th
314a0 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
314b0 20 74 6f 20 73 71 6c 69 74 65 33 5f 75 70 64 61   to sqlite3_upda
314c0 74 65 5f 68 6f 6f 6b 28 29 2e 0a 2a 2a 20 54 68  te_hook()..** Th
314d0 65 20 73 65 63 6f 6e 64 20 63 61 6c 6c 62 61 63  e second callbac
314e0 6b 20 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69  k .** argument i
314f0 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45  s one of [SQLITE
31500 5f 49 4e 53 45 52 54 5d 2c 20 5b 53 51 4c 49 54  _INSERT], [SQLIT
31510 45 5f 44 45 4c 45 54 45 5d 20 6f 72 20 5b 53 51  E_DELETE] or [SQ
31520 4c 49 54 45 5f 55 50 44 41 54 45 5d 2c 0a 2a 2a  LITE_UPDATE],.**
31530 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68   depending on th
31540 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74  e operation that
31550 20 63 61 75 73 65 64 20 74 68 65 20 63 61 6c 6c   caused the call
31560 62 61 63 6b 20 74 6f 20 62 65 20 69 6e 76 6f 6b  back to be invok
31570 65 64 2e 0a 2a 2a 20 54 68 65 20 74 68 69 72 64  ed..** The third
31580 20 61 6e 64 20 0a 2a 2a 20 66 6f 75 72 74 68 20   and .** fourth 
31590 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65  arguments to the
315a0 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69   callback contai
315b0 6e 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68  n pointers to th
315c0 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 0a  e database and .
315d0 2a 2a 20 74 61 62 6c 65 20 6e 61 6d 65 20 63 6f  ** table name co
315e0 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61 66 66  ntaining the aff
315f0 65 63 74 65 64 20 72 6f 77 2e 0a 2a 2a 20 54 68  ected row..** Th
31600 65 20 66 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b  e final callback
31610 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 0a 2a   parameter is .*
31620 2a 20 74 68 65 20 72 6f 77 69 64 20 6f 66 20 74  * the rowid of t
31630 68 65 20 72 6f 77 2e 0a 2a 2a 20 49 6e 20 74 68  he row..** In th
31640 65 20 63 61 73 65 20 6f 66 20 61 6e 20 75 70 64  e case of an upd
31650 61 74 65 2c 20 74 68 69 73 20 69 73 20 74 68 65  ate, this is the
31660 20 72 6f 77 69 64 20 61 66 74 65 72 20 0a 2a 2a   rowid after .**
31670 20 74 68 65 20 75 70 64 61 74 65 20 74 61 6b 65   the update take
31680 73 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54  s place..**.** T
31690 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 20 69  he update hook i
316a0 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77 68  s not invoked wh
316b0 65 6e 20 69 6e 74 65 72 6e 61 6c 20 73 79 73 74  en internal syst
316c0 65 6d 20 74 61 62 6c 65 73 20 61 72 65 0a 2a 2a  em tables are.**
316d0 20 6d 6f 64 69 66 69 65 64 20 28 69 2e 65 2e 20   modified (i.e. 
316e0 73 71 6c 69 74 65 5f 6d 61 73 74 65 72 20 61 6e  sqlite_master an
316f0 64 20 73 71 6c 69 74 65 5f 73 65 71 75 65 6e 63  d sqlite_sequenc
31700 65 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f  e)..**.** If ano
31710 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 77 61  ther function wa
31720 73 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 67  s previously reg
31730 69 73 74 65 72 65 64 2c 20 69 74 73 20 70 41 72  istered, its pAr
31740 67 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 72 65  g value.** is re
31750 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69  turned.  Otherwi
31760 73 65 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72  se NULL is retur
31770 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ned..**.** INVAR
31780 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31  IANTS:.**.** {F1
31790 32 39 37 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  2971} The [sqlit
317a0 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44  e3_update_hook(D
317b0 2c 46 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 65  ,F,P)] interface
317c0 20 63 61 75 73 65 73 20 63 61 6c 6c 62 61 63 6b   causes callback
317d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 75 6e  .**          fun
317e0 63 74 69 6f 6e 20 46 20 74 6f 20 62 65 20 69 6e  ction F to be in
317f0 76 6f 6b 65 64 20 77 69 74 68 20 66 69 72 73 74  voked with first
31800 20 70 61 72 61 6d 65 74 65 72 20 50 20 77 68 65   parameter P whe
31810 6e 65 76 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  never.**        
31820 20 20 61 20 74 61 62 6c 65 20 72 6f 77 20 69 73    a table row is
31830 20 6d 6f 64 69 66 69 65 64 2c 20 69 6e 73 65 72   modified, inser
31840 74 65 64 2c 20 6f 72 20 64 65 6c 65 74 65 64 20  ted, or deleted 
31850 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  on.**          [
31860 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
31870 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46  ion] D..**.** {F
31880 31 32 39 37 33 7d 20 54 68 65 20 5b 73 71 6c 69  12973} The [sqli
31890 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28  te3_update_hook(
318a0 44 2c 46 2c 50 29 5d 20 69 6e 74 65 72 66 61 63  D,F,P)] interfac
318b0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 76 61  e returns the va
318c0 6c 75 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  lue.**          
318d0 6f 66 20 50 20 66 6f 72 20 74 68 65 20 70 72 65  of P for the pre
318e0 76 69 6f 75 73 20 63 61 6c 6c 20 6f 6e 20 74 68  vious call on th
318f0 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65  e same [database
31900 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 0a   connection] D,.
31910 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 4e  **          or N
31920 55 4c 4c 20 66 6f 72 20 74 68 65 20 66 69 72 73  ULL for the firs
31930 74 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 46  t call..**.** {F
31940 31 32 39 37 35 7d 20 49 66 20 74 68 65 20 75 70  12975} If the up
31950 64 61 74 65 20 68 6f 6f 6b 20 63 61 6c 6c 62 61  date hook callba
31960 63 6b 20 46 20 69 6e 20 5b 73 71 6c 69 74 65 33  ck F in [sqlite3
31970 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44 2c 46  _update_hook(D,F
31980 2c 50 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ,P)].**         
31990 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68   is NULL then th
319a0 65 20 6e 6f 20 75 70 64 61 74 65 20 63 61 6c 6c  e no update call
319b0 62 61 63 6b 73 20 61 72 65 20 6d 61 64 65 2e 0a  backs are made..
319c0 2a 2a 0a 2a 2a 20 7b 46 31 32 39 37 37 7d 20 45  **.** {F12977} E
319d0 61 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ach call to [sql
319e0 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b  ite3_update_hook
319f0 28 44 2c 46 2c 50 29 5d 20 6f 76 65 72 72 69 64  (D,F,P)] overrid
31a00 65 73 20 70 72 69 6f 72 20 63 61 6c 6c 73 0a 2a  es prior calls.*
31a10 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 74 68  *          to th
31a20 65 20 73 61 6d 65 20 69 6e 74 65 72 66 61 63 65  e same interface
31a30 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61   on the same [da
31a40 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
31a50 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  n] D..**.** {F12
31a60 39 37 39 7d 20 54 68 65 20 75 70 64 61 74 65 20  979} The update 
31a70 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73  hook callback is
31a80 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77 68 65   not invoked whe
31a90 6e 20 69 6e 74 65 72 6e 61 6c 20 73 79 73 74 65  n internal syste
31aa0 6d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 61  m.**          ta
31ab0 62 6c 65 73 20 73 75 63 68 20 61 73 20 73 71 6c  bles such as sql
31ac0 69 74 65 5f 6d 61 73 74 65 72 20 61 6e 64 20 73  ite_master and s
31ad0 71 6c 69 74 65 5f 73 65 71 75 65 6e 63 65 20 61  qlite_sequence a
31ae0 72 65 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a  re modified..**.
31af0 2a 2a 20 7b 46 31 32 39 38 31 7d 20 54 68 65 20  ** {F12981} The 
31b00 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
31b10 20 74 6f 20 74 68 65 20 75 70 64 61 74 65 20 63   to the update c
31b20 61 6c 6c 62 61 63 6b 20 0a 2a 2a 20 20 20 20 20  allback .**     
31b30 20 20 20 20 20 69 73 20 6f 6e 65 20 6f 66 20 5b       is one of [
31b40 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 5d 2c 20  SQLITE_INSERT], 
31b50 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20  [SQLITE_DELETE] 
31b60 6f 72 20 5b 53 51 4c 49 54 45 5f 55 50 44 41 54  or [SQLITE_UPDAT
31b70 45 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  E],.**          
31b80 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  depending on the
31b90 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20   operation that 
31ba0 63 61 75 73 65 64 20 74 68 65 20 63 61 6c 6c 62  caused the callb
31bb0 61 63 6b 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65  ack to be invoke
31bc0 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 38 33  d..**.** {F12983
31bd0 7d 20 54 68 65 20 74 68 69 72 64 20 61 6e 64 20  } The third and 
31be0 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 73  fourth arguments
31bf0 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
31c00 20 63 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65 72   contain pointer
31c10 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f  s.**          to
31c20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
31c30 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73 20 77   UTF-8 strings w
31c40 68 69 63 68 20 61 72 65 20 74 68 65 20 6e 61 6d  hich are the nam
31c50 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20  es of the.**    
31c60 20 20 20 20 20 20 64 61 74 61 62 61 73 65 20 61        database a
31c70 6e 64 20 74 61 62 6c 65 20 74 68 61 74 20 69 73  nd table that is
31c80 20 62 65 69 6e 67 20 75 70 64 61 74 65 64 2e 0a   being updated..
31c90 0a 2a 2a 20 7b 46 31 32 39 38 35 7d 20 54 68 65  .** {F12985} The
31ca0 20 66 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20   final callback 
31cb0 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
31cc0 20 72 6f 77 69 64 20 6f 66 20 74 68 65 20 72 6f   rowid of the ro
31cd0 77 20 61 66 74 65 72 0a 2a 2a 20 20 20 20 20 20  w after.**      
31ce0 20 20 20 20 74 68 65 20 63 68 61 6e 67 65 20 6f      the change o
31cf0 63 63 75 72 73 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  ccurs..*/.void *
31d00 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68  sqlite3_update_h
31d10 6f 6f 6b 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  ook(.  sqlite3*,
31d20 20 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64   .  void(*)(void
31d30 20 2a 2c 69 6e 74 20 2c 63 68 61 72 20 63 6f 6e   *,int ,char con
31d40 73 74 20 2a 2c 63 68 61 72 20 63 6f 6e 73 74 20  st *,char const 
31d50 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  *,sqlite3_int64)
31d60 2c 0a 20 20 76 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a  ,.  void*.);../*
31d70 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 45  .** CAPI3REF:  E
31d80 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65  nable Or Disable
31d90 20 53 68 61 72 65 64 20 50 61 67 65 72 20 43 61   Shared Pager Ca
31da0 63 68 65 20 7b 46 31 30 33 33 30 7d 0a 2a 2a 0a  che {F10330}.**.
31db0 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
31dc0 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62  enables or disab
31dd0 6c 65 73 20 74 68 65 20 73 68 61 72 69 6e 67 20  les the sharing 
31de0 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
31df0 63 61 63 68 65 0a 2a 2a 20 61 6e 64 20 73 63 68  cache.** and sch
31e00 65 6d 61 20 64 61 74 61 20 73 74 72 75 63 74 75  ema data structu
31e10 72 65 73 20 62 65 74 77 65 65 6e 20 63 6f 6e 6e  res between conn
31e20 65 63 74 69 6f 6e 73 20 74 6f 20 74 68 65 20 73  ections to the s
31e30 61 6d 65 20 64 61 74 61 62 61 73 65 2e 0a 2a 2a  ame database..**
31e40 20 53 68 61 72 69 6e 67 20 69 73 20 65 6e 61 62   Sharing is enab
31e50 6c 65 64 20 69 66 20 74 68 65 20 61 72 67 75 6d  led if the argum
31e60 65 6e 74 20 69 73 20 74 72 75 65 20 61 6e 64 20  ent is true and 
31e70 64 69 73 61 62 6c 65 64 20 69 66 20 74 68 65 20  disabled if the 
31e80 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 69 73 20 66  argument.** is f
31e90 61 6c 73 65 2e 0a 2a 2a 0a 2a 2a 20 43 61 63 68  alse..**.** Cach
31ea0 65 20 73 68 61 72 69 6e 67 20 69 73 20 65 6e 61  e sharing is ena
31eb0 62 6c 65 64 20 61 6e 64 20 64 69 73 61 62 6c 65  bled and disable
31ec0 64 0a 2a 2a 20 66 6f 72 20 61 6e 20 65 6e 74 69  d.** for an enti
31ed0 72 65 20 70 72 6f 63 65 73 73 2e 20 7b 45 4e 44  re process. {END
31ee0 7d 20 54 68 69 73 20 69 73 20 61 20 63 68 61 6e  } This is a chan
31ef0 67 65 20 61 73 20 6f 66 20 53 51 4c 69 74 65 20  ge as of SQLite 
31f00 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2e 0a 2a  version 3.5.0..*
31f10 2a 20 49 6e 20 70 72 69 6f 72 20 76 65 72 73 69  * In prior versi
31f20 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2c 20 73  ons of SQLite, s
31f30 68 61 72 69 6e 67 20 77 61 73 0a 2a 2a 20 65 6e  haring was.** en
31f40 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65  abled or disable
31f50 64 20 66 6f 72 20 65 61 63 68 20 74 68 72 65 61  d for each threa
31f60 64 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a  d separately..**
31f70 0a 2a 2a 20 54 68 65 20 63 61 63 68 65 20 73 68  .** The cache sh
31f80 61 72 69 6e 67 20 6d 6f 64 65 20 73 65 74 20 62  aring mode set b
31f90 79 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  y this interface
31fa0 20 65 66 66 65 63 74 73 20 61 6c 6c 20 73 75 62   effects all sub
31fb0 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73  sequent.** calls
31fc0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
31fd0 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  n()], [sqlite3_o
31fe0 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20 5b  pen_v2()], and [
31ff0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
32000 5d 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 64  ]..** Existing d
32010 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
32020 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 75 73 65  ons continue use
32030 20 74 68 65 20 73 68 61 72 69 6e 67 20 6d 6f 64   the sharing mod
32040 65 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 69 6e  e.** that was in
32050 20 65 66 66 65 63 74 20 61 74 20 74 68 65 20 74   effect at the t
32060 69 6d 65 20 74 68 65 79 20 77 65 72 65 20 6f 70  ime they were op
32070 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 56 69 72 74  ened..**.** Virt
32080 75 61 6c 20 74 61 62 6c 65 73 20 63 61 6e 6e 6f  ual tables canno
32090 74 20 62 65 20 75 73 65 64 20 77 69 74 68 20 61  t be used with a
320a0 20 73 68 61 72 65 64 20 63 61 63 68 65 2e 20 20   shared cache.  
320b0 20 57 68 65 6e 20 73 68 61 72 65 64 0a 2a 2a 20   When shared.** 
320c0 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64  cache is enabled
320d0 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  , the [sqlite3_c
320e0 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 5d 20  reate_module()] 
320f0 41 50 49 20 75 73 65 64 20 74 6f 20 72 65 67 69  API used to regi
32100 73 74 65 72 0a 2a 2a 20 76 69 72 74 75 61 6c 20  ster.** virtual 
32110 74 61 62 6c 65 73 20 77 69 6c 6c 20 61 6c 77 61  tables will alwa
32120 79 73 20 72 65 74 75 72 6e 20 61 6e 20 65 72 72  ys return an err
32130 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  or..**.** This r
32140 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b  outine returns [
32150 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 20 73 68  SQLITE_OK] if sh
32160 61 72 65 64 20 63 61 63 68 65 20 77 61 73 0a 2a  ared cache was.*
32170 2a 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73  * enabled or dis
32180 61 62 6c 65 64 20 73 75 63 63 65 73 73 66 75 6c  abled successful
32190 6c 79 2e 20 20 41 6e 20 5b 65 72 72 6f 72 20 63  ly.  An [error c
321a0 6f 64 65 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72  ode].** is retur
321b0 6e 65 64 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a  ned otherwise..*
321c0 2a 0a 2a 2a 20 53 68 61 72 65 64 20 63 61 63 68  *.** Shared cach
321d0 65 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79  e is disabled by
321e0 20 64 65 66 61 75 6c 74 2e 20 42 75 74 20 74 68   default. But th
321f0 69 73 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20  is might change 
32200 69 6e 0a 2a 2a 20 66 75 74 75 72 65 20 72 65 6c  in.** future rel
32210 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  eases of SQLite.
32220 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74    Applications t
32230 68 61 74 20 63 61 72 65 20 61 62 6f 75 74 20 73  hat care about s
32240 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 73  hared.** cache s
32250 65 74 74 69 6e 67 20 73 68 6f 75 6c 64 20 73 65  etting should se
32260 74 20 69 74 20 65 78 70 6c 69 63 69 74 6c 79 2e  t it explicitly.
32270 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
32280 53 3a 0a 2a 2a 20 0a 2a 2a 20 7b 46 31 30 33 33  S:.** .** {F1033
32290 31 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20  1} A successful 
322a0 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73  invocation of [s
322b0 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68  qlite3_enable_sh
322c0 61 72 65 64 5f 63 61 63 68 65 28 42 29 5d 0a 2a  ared_cache(B)].*
322d0 2a 20 20 20 20 20 20 20 20 20 20 77 69 6c 6c 20  *          will 
322e0 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c  enable or disabl
322f0 65 20 73 68 61 72 65 64 20 63 61 63 68 65 20 6d  e shared cache m
32300 6f 64 65 20 66 6f 72 20 61 6e 79 20 73 75 62 73  ode for any subs
32310 65 71 75 65 6e 74 6c 79 0a 2a 2a 20 20 20 20 20  equently.**     
32320 20 20 20 20 20 63 72 65 61 74 65 64 20 5b 64 61       created [da
32330 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
32340 6e 5d 20 69 6e 20 74 68 65 20 73 61 6d 65 20 70  n] in the same p
32350 72 6f 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46  rocess..**.** {F
32360 31 30 33 33 36 7d 20 57 68 65 6e 20 73 68 61 72  10336} When shar
32370 65 64 20 63 61 63 68 65 20 69 73 20 65 6e 61 62  ed cache is enab
32380 6c 65 64 2c 20 74 68 65 20 5b 73 71 6c 69 74 65  led, the [sqlite
32390 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28  3_create_module(
323a0 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  )].**          i
323b0 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 61 6c  nterface will al
323c0 77 61 79 73 20 72 65 74 75 72 6e 20 61 6e 20 65  ways return an e
323d0 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 30  rror..**.** {F10
323e0 33 33 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  337} The [sqlite
323f0 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f  3_enable_shared_
32400 63 61 63 68 65 28 42 29 5d 20 69 6e 74 65 72 66  cache(B)] interf
32410 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20  ace returns.**  
32420 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f          [SQLITE_
32430 4f 4b 5d 20 69 66 20 73 68 61 72 65 64 20 63 61  OK] if shared ca
32440 63 68 65 20 77 61 73 20 65 6e 61 62 6c 65 64 20  che was enabled 
32450 6f 72 20 64 69 73 61 62 6c 65 64 20 73 75 63 63  or disabled succ
32460 65 73 73 66 75 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20  essfully..**.** 
32470 7b 46 31 30 33 33 39 7d 20 53 68 61 72 65 64 20  {F10339} Shared 
32480 63 61 63 68 65 20 69 73 20 64 69 73 61 62 6c 65  cache is disable
32490 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2f  d by default..*/
324a0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 6e 61  .int sqlite3_ena
324b0 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65  ble_shared_cache
324c0 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  (int);../*.** CA
324d0 50 49 33 52 45 46 3a 20 20 41 74 74 65 6d 70 74  PI3REF:  Attempt
324e0 20 54 6f 20 46 72 65 65 20 48 65 61 70 20 4d 65   To Free Heap Me
324f0 6d 6f 72 79 20 7b 46 31 37 33 34 30 7d 0a 2a 2a  mory {F17340}.**
32500 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
32510 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29  release_memory()
32520 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d   interface attem
32530 70 74 73 20 74 6f 0a 2a 2a 20 66 72 65 65 20 4e  pts to.** free N
32540 20 62 79 74 65 73 20 6f 66 20 68 65 61 70 20 6d   bytes of heap m
32550 65 6d 6f 72 79 20 62 79 20 64 65 61 6c 6c 6f 63  emory by dealloc
32560 61 74 69 6e 67 20 6e 6f 6e 2d 65 73 73 65 6e 74  ating non-essent
32570 69 61 6c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c  ial memory.** al
32580 6c 6f 63 61 74 69 6f 6e 73 20 68 65 6c 64 20 62  locations held b
32590 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6c  y the database l
325a0 61 62 72 61 72 79 2e 20 7b 45 4e 44 7d 20 20 4d  abrary. {END}  M
325b0 65 6d 6f 72 79 20 75 73 65 64 0a 2a 2a 20 74 6f  emory used.** to
325c0 20 63 61 63 68 65 20 64 61 74 61 62 61 73 65 20   cache database 
325d0 70 61 67 65 73 20 74 6f 20 69 6d 70 72 6f 76 65  pages to improve
325e0 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 69 73 20   performance is 
325f0 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 0a 2a 2a  an example of.**
32600 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 20 6d   non-essential m
32610 65 6d 6f 72 79 2e 20 20 53 71 6c 69 74 65 33 5f  emory.  Sqlite3_
32620 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29  release_memory()
32630 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20   returns.** the 
32640 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
32650 61 63 74 75 61 6c 6c 79 20 66 72 65 65 64 2c 20  actually freed, 
32660 77 68 69 63 68 20 6d 69 67 68 74 20 62 65 20 6d  which might be m
32670 6f 72 65 20 6f 72 20 6c 65 73 73 0a 2a 2a 20 74  ore or less.** t
32680 68 61 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20 72  han the amount r
32690 65 71 75 65 73 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  equested..**.** 
326a0 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
326b0 2a 20 7b 46 31 37 33 34 31 7d 20 54 68 65 20 5b  * {F17341} The [
326c0 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f  sqlite3_release_
326d0 6d 65 6d 6f 72 79 28 4e 29 5d 20 69 6e 74 65 72  memory(N)] inter
326e0 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f  face attempts to
326f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 72 65  .**          fre
32700 65 20 4e 20 62 79 74 65 73 20 6f 66 20 68 65 61  e N bytes of hea
32710 70 20 6d 65 6d 6f 72 79 20 62 79 20 64 65 61 6c  p memory by deal
32720 6c 6f 63 61 74 69 6e 67 20 6e 6f 6e 2d 65 73 73  locating non-ess
32730 65 6e 74 69 61 6c 0a 2a 2a 20 20 20 20 20 20 20  ential.**       
32740 20 20 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61     memory alloca
32750 74 69 6f 6e 73 20 68 65 6c 64 20 62 79 20 74 68  tions held by th
32760 65 20 64 61 74 61 62 61 73 65 20 6c 61 62 72 61  e database labra
32770 72 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 33 34  ry..**.** {F1634
32780 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  2} The [sqlite3_
32790 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 4e  release_memory(N
327a0 29 5d 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  )] returns the n
327b0 75 6d 62 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  umber.**        
327c0 20 20 6f 66 20 62 79 74 65 73 20 61 63 74 75 61    of bytes actua
327d0 6c 6c 79 20 66 72 65 65 64 2c 20 77 68 69 63 68  lly freed, which
327e0 20 6d 69 67 68 74 20 62 65 20 6d 6f 72 65 20 6f   might be more o
327f0 72 20 6c 65 73 73 0a 2a 2a 20 20 20 20 20 20 20  r less.**       
32800 20 20 20 74 68 61 6e 20 74 68 65 20 61 6d 6f 75     than the amou
32810 6e 74 20 72 65 71 75 65 73 74 65 64 2e 0a 2a 2f  nt requested..*/
32820 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6c  .int sqlite3_rel
32830 65 61 73 65 5f 6d 65 6d 6f 72 79 28 69 6e 74 29  ease_memory(int)
32840 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
32850 46 3a 20 20 49 6d 70 6f 73 65 20 41 20 4c 69 6d  F:  Impose A Lim
32860 69 74 20 4f 6e 20 48 65 61 70 20 53 69 7a 65 20  it On Heap Size 
32870 7b 46 31 37 33 35 30 7d 0a 2a 2a 0a 2a 2a 20 54  {F17350}.**.** T
32880 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f  he sqlite3_soft_
32890 68 65 61 70 5f 6c 69 6d 69 74 28 29 20 69 6e 74  heap_limit() int
328a0 65 72 66 61 63 65 0a 2a 2a 20 70 6c 61 63 65 73  erface.** places
328b0 20 61 20 22 73 6f 66 74 22 20 6c 69 6d 69 74 20   a "soft" limit 
328c0 6f 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66  on the amount of
328d0 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 74 68 61   heap memory tha
328e0 74 20 6d 61 79 20 62 65 20 61 6c 6c 6f 63 61 74  t may be allocat
328f0 65 64 0a 2a 2a 20 62 79 20 53 51 4c 69 74 65 2e  ed.** by SQLite.
32900 20 49 66 20 61 6e 20 69 6e 74 65 72 6e 61 6c 20   If an internal 
32910 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 72 65  allocation is re
32920 71 75 65 73 74 65 64 20 0a 2a 2a 20 74 68 61 74  quested .** that
32930 20 77 6f 75 6c 64 20 65 78 63 65 65 64 20 74 68   would exceed th
32940 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69  e soft heap limi
32950 74 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65  t, [sqlite3_rele
32960 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 69 73  ase_memory()] is
32970 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 6f 6e 65 20  .** invoked one 
32980 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f  or more times to
32990 20 66 72 65 65 20 75 70 20 73 6f 6d 65 20 73 70   free up some sp
329a0 61 63 65 20 62 65 66 6f 72 65 20 74 68 65 20 61  ace before the a
329b0 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 20  llocation.** is 
329c0 6d 61 64 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  made..**.** The 
329d0 6c 69 6d 69 74 20 69 73 20 63 61 6c 6c 65 64 20  limit is called 
329e0 22 73 6f 66 74 22 2c 20 62 65 63 61 75 73 65 20  "soft", because 
329f0 69 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  if.** [sqlite3_r
32a00 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d  elease_memory()]
32a10 20 63 61 6e 6e 6f 74 0a 2a 2a 20 66 72 65 65 20   cannot.** free 
32a20 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72  sufficient memor
32a30 79 20 74 6f 20 70 72 65 76 65 6e 74 20 74 68 65  y to prevent the
32a40 20 6c 69 6d 69 74 20 66 72 6f 6d 20 62 65 69 6e   limit from bein
32a50 67 20 65 78 63 65 65 64 65 64 2c 0a 2a 2a 20 74  g exceeded,.** t
32a60 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 61 6c 6c  he memory is all
32a70 6f 63 61 74 65 64 20 61 6e 79 77 61 79 20 61 6e  ocated anyway an
32a80 64 20 74 68 65 20 63 75 72 72 65 6e 74 20 6f 70  d the current op
32a90 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73  eration proceeds
32aa0 2e 0a 2a 2a 0a 2a 2a 20 41 20 6e 65 67 61 74 69  ..**.** A negati
32ab0 76 65 20 6f 72 20 7a 65 72 6f 20 76 61 6c 75 65  ve or zero value
32ac0 20 66 6f 72 20 4e 20 6d 65 61 6e 73 20 74 68 61   for N means tha
32ad0 74 20 74 68 65 72 65 20 69 73 20 6e 6f 20 73 6f  t there is no so
32ae0 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 61 6e  ft heap limit an
32af0 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  d.** [sqlite3_re
32b00 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20  lease_memory()] 
32b10 77 69 6c 6c 20 6f 6e 6c 79 20 62 65 20 63 61 6c  will only be cal
32b20 6c 65 64 20 77 68 65 6e 20 6d 65 6d 6f 72 79 20  led when memory 
32b30 69 73 20 65 78 68 61 75 73 74 65 64 2e 0a 2a 2a  is exhausted..**
32b40 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c   The default val
32b50 75 65 20 66 6f 72 20 74 68 65 20 73 6f 66 74 20  ue for the soft 
32b60 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20 7a 65  heap limit is ze
32b70 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  ro..**.** SQLite
32b80 20 6d 61 6b 65 73 20 61 20 62 65 73 74 20 65 66   makes a best ef
32b90 66 6f 72 74 20 74 6f 20 68 6f 6e 6f 72 20 74 68  fort to honor th
32ba0 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69  e soft heap limi
32bb0 74 2e 20 20 0a 2a 2a 20 42 75 74 20 69 66 20 74  t.  .** But if t
32bc0 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d  he soft heap lim
32bd0 69 74 20 63 61 6e 6e 6f 74 20 68 6f 6e 6f 72 65  it cannot honore
32be0 64 2c 20 65 78 65 63 75 74 69 6f 6e 20 77 69 6c  d, execution wil
32bf0 6c 0a 2a 2a 20 63 6f 6e 74 69 6e 75 65 20 77 69  l.** continue wi
32c00 74 68 6f 75 74 20 65 72 72 6f 72 20 6f 72 20 6e  thout error or n
32c10 6f 74 69 66 69 63 61 74 69 6f 6e 2e 20 20 54 68  otification.  Th
32c20 69 73 20 69 73 20 77 68 79 20 74 68 65 20 6c 69  is is why the li
32c30 6d 69 74 20 69 73 20 0a 2a 2a 20 63 61 6c 6c 65  mit is .** calle
32c40 64 20 61 20 22 73 6f 66 74 22 20 6c 69 6d 69 74  d a "soft" limit
32c50 2e 20 20 49 74 20 69 73 20 61 64 76 69 73 6f 72  .  It is advisor
32c60 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 50 72  y only..**.** Pr
32c70 69 6f 72 20 74 6f 20 53 51 4c 69 74 65 20 76 65  ior to SQLite ve
32c80 72 73 69 6f 6e 20 33 2e 35 2e 30 2c 20 74 68 69  rsion 3.5.0, thi
32c90 73 20 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 63  s routine only c
32ca0 6f 6e 73 74 72 61 69 6e 65 64 20 74 68 65 20 6d  onstrained the m
32cb0 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
32cc0 65 64 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74  ed by a single t
32cd0 68 72 65 61 64 20 2d 20 74 68 65 20 73 61 6d 65  hread - the same
32ce0 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68   thread in which
32cf0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a   this routine.**
32d00 20 72 75 6e 73 2e 20 20 42 65 67 69 6e 6e 69 6e   runs.  Beginnin
32d10 67 20 77 69 74 68 20 53 51 4c 69 74 65 20 76 65  g with SQLite ve
32d20 72 73 69 6f 6e 20 33 2e 35 2e 30 2c 20 74 68 65  rsion 3.5.0, the
32d30 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
32d40 20 69 73 0a 2a 2a 20 61 70 70 6c 69 65 64 20 74   is.** applied t
32d50 6f 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 20 54  o all threads. T
32d60 68 65 20 76 61 6c 75 65 20 73 70 65 63 69 66 69  he value specifi
32d70 65 64 20 66 6f 72 20 74 68 65 20 73 6f 66 74 20  ed for the soft 
32d80 68 65 61 70 20 6c 69 6d 69 74 0a 2a 2a 20 69 73  heap limit.** is
32d90 20 61 6e 20 75 70 70 65 72 20 62 6f 75 6e 64 20   an upper bound 
32da0 6f 6e 20 74 68 65 20 74 6f 74 61 6c 20 6d 65 6d  on the total mem
32db0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
32dc0 6f 72 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 20  or all threads. 
32dd0 49 6e 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 33 2e  In.** version 3.
32de0 35 2e 30 20 74 68 65 72 65 20 69 73 20 6e 6f 20  5.0 there is no 
32df0 6d 65 63 68 61 6e 69 73 6d 20 66 6f 72 20 6c 69  mechanism for li
32e00 6d 69 74 69 6e 67 20 74 68 65 20 68 65 61 70 20  miting the heap 
32e10 75 73 61 67 65 20 66 6f 72 0a 2a 2a 20 69 6e 64  usage for.** ind
32e20 69 76 69 64 75 61 6c 20 74 68 72 65 61 64 73 2e  ividual threads.
32e30 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
32e40 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 33 35 31  S:.**.** {F16351
32e50 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  } The [sqlite3_s
32e60 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 4e  oft_heap_limit(N
32e70 29 5d 20 69 6e 74 65 72 66 61 63 65 20 70 6c 61  )] interface pla
32e80 63 65 73 20 61 20 73 6f 66 74 20 6c 69 6d 69 74  ces a soft limit
32e90 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20  .**          of 
32ea0 4e 20 62 79 74 65 73 20 6f 6e 20 74 68 65 20 61  N bytes on the a
32eb0 6d 6f 75 6e 74 20 6f 66 20 68 65 61 70 20 6d 65  mount of heap me
32ec0 6d 6f 72 79 20 74 68 61 74 20 6d 61 79 20 62 65  mory that may be
32ed0 20 61 6c 6c 6f 63 61 74 65 64 0a 2a 2a 20 20 20   allocated.**   
32ee0 20 20 20 20 20 20 20 75 73 69 6e 67 20 5b 73 71         using [sq
32ef0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
32f00 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  or [sqlite3_real
32f10 6c 6f 63 28 29 5d 20 61 74 20 61 6e 79 20 70 6f  loc()] at any po
32f20 69 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  int.**          
32f30 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b  in time..**.** {
32f40 46 31 36 33 35 32 7d 20 49 66 20 61 20 63 61 6c  F16352} If a cal
32f50 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61  l to [sqlite3_ma
32f60 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69  lloc()] or [sqli
32f70 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 77  te3_realloc()] w
32f80 6f 75 6c 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  ould.**         
32f90 20 63 61 75 73 65 20 74 68 65 20 74 6f 74 61 6c   cause the total
32fa0 20 61 6d 6f 75 6e 74 20 6f 66 20 61 6c 6c 6f 63   amount of alloc
32fb0 61 74 65 64 20 6d 65 6d 6f 72 79 20 74 6f 20 65  ated memory to e
32fc0 78 63 65 65 64 20 74 68 65 0a 2a 2a 20 20 20 20  xceed the.**    
32fd0 20 20 20 20 20 20 73 6f 66 74 20 68 65 61 70 20        soft heap 
32fe0 6c 69 6d 69 74 2c 20 74 68 65 6e 20 5b 73 71 6c  limit, then [sql
32ff0 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d  ite3_release_mem
33000 6f 72 79 28 29 5d 20 69 73 20 69 6e 76 6f 6b 65  ory()] is invoke
33010 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  d.**          in
33020 20 61 6e 20 61 74 74 65 6d 70 74 20 74 6f 20 72   an attempt to r
33030 65 64 75 63 65 20 74 68 65 20 6d 65 6d 6f 72 79  educe the memory
33040 20 75 73 61 67 65 20 70 72 69 6f 72 20 74 6f 20   usage prior to 
33050 70 72 6f 63 65 65 64 69 6e 67 0a 2a 2a 20 20 20  proceeding.**   
33060 20 20 20 20 20 20 20 77 69 74 68 20 74 68 65 20         with the 
33070 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
33080 6e 20 61 74 74 65 6d 70 74 2e 0a 2a 2a 0a 2a 2a  n attempt..**.**
33090 20 7b 46 31 36 33 35 33 7d 20 43 61 6c 6c 73 20   {F16353} Calls 
330a0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  to [sqlite3_mall
330b0 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  oc()] or [sqlite
330c0 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61  3_realloc()] tha
330d0 74 20 74 72 69 67 67 65 72 0a 2a 2a 20 20 20 20  t trigger.**    
330e0 20 20 20 20 20 20 61 74 74 65 6d 70 74 73 20 74        attempts t
330f0 6f 20 72 65 64 75 63 65 20 6d 65 6d 6f 72 79 20  o reduce memory 
33100 75 73 61 67 65 20 74 68 72 6f 75 67 68 20 74 68  usage through th
33110 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69  e soft heap limi
33120 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 65  t.**          me
33130 63 68 61 6e 69 73 6d 20 63 6f 6e 74 69 6e 75 65  chanism continue
33140 20 65 76 65 6e 20 69 66 20 74 68 65 20 61 74 74   even if the att
33150 65 6d 70 74 20 74 6f 20 72 65 64 75 63 65 20 6d  empt to reduce m
33160 65 6d 6f 72 79 0a 2a 2a 20 20 20 20 20 20 20 20  emory.**        
33170 20 20 75 73 61 67 65 20 69 73 20 75 6e 73 75 63    usage is unsuc
33180 63 65 73 73 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 7b  cessful..**.** {
33190 46 31 36 33 35 34 7d 20 41 20 6e 65 67 61 74 69  F16354} A negati
331a0 76 65 20 6f 72 20 7a 65 72 6f 20 76 61 6c 75 65  ve or zero value
331b0 20 66 6f 72 20 4e 20 69 6e 20 61 20 63 61 6c 6c   for N in a call
331c0 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   to.**          
331d0 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65  [sqlite3_soft_he
331e0 61 70 5f 6c 69 6d 69 74 28 4e 29 5d 20 6d 65 61  ap_limit(N)] mea
331f0 6e 73 20 74 68 61 74 20 74 68 65 72 65 20 69 73  ns that there is
33200 20 6e 6f 20 73 6f 66 74 0a 2a 2a 20 20 20 20 20   no soft.**     
33210 20 20 20 20 20 68 65 61 70 20 6c 69 6d 69 74 20       heap limit 
33220 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c  and [sqlite3_rel
33230 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 77  ease_memory()] w
33240 69 6c 6c 20 6f 6e 6c 79 20 62 65 0a 2a 2a 20 20  ill only be.**  
33250 20 20 20 20 20 20 20 20 63 61 6c 6c 65 64 20 77          called w
33260 68 65 6e 20 6d 65 6d 6f 72 79 20 69 73 20 63 6f  hen memory is co
33270 6d 70 6c 65 74 65 6c 79 20 65 78 68 61 75 73 74  mpletely exhaust
33280 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 33 35  ed..**.** {F1635
33290 35 7d 20 54 68 65 20 64 65 66 61 75 6c 74 20 76  5} The default v
332a0 61 6c 75 65 20 66 6f 72 20 74 68 65 20 73 6f 66  alue for the sof
332b0 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20  t heap limit is 
332c0 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  zero..**.** {F16
332d0 33 35 38 7d 20 45 61 63 68 20 63 61 6c 6c 20 74  358} Each call t
332e0 6f 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f  o [sqlite3_soft_
332f0 68 65 61 70 5f 6c 69 6d 69 74 28 4e 29 5d 20 6f  heap_limit(N)] o
33300 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20  verrides the.** 
33310 20 20 20 20 20 20 20 20 20 76 61 6c 75 65 73 20           values 
33320 73 65 74 20 62 79 20 61 6c 6c 20 70 72 69 6f 72  set by all prior
33330 20 63 61 6c 6c 73 2e 0a 2a 2f 0a 76 6f 69 64 20   calls..*/.void 
33340 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61  sqlite3_soft_hea
33350 70 5f 6c 69 6d 69 74 28 69 6e 74 29 3b 0a 0a 2f  p_limit(int);../
33360 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20  *.** CAPI3REF:  
33370 45 78 74 72 61 63 74 20 4d 65 74 61 64 61 74 61  Extract Metadata
33380 20 41 62 6f 75 74 20 41 20 43 6f 6c 75 6d 6e 20   About A Column 
33390 4f 66 20 41 20 54 61 62 6c 65 20 7b 46 31 32 38  Of A Table {F128
333a0 35 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  50}.**.** This r
333b0 6f 75 74 69 6e 65 0a 2a 2a 20 72 65 74 75 72 6e  outine.** return
333c0 73 20 6d 65 74 61 2d 64 61 74 61 20 61 62 6f 75  s meta-data abou
333d0 74 20 61 20 73 70 65 63 69 66 69 63 20 63 6f 6c  t a specific col
333e0 75 6d 6e 20 6f 66 20 61 20 73 70 65 63 69 66 69  umn of a specifi
333f0 63 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 74 61  c database.** ta
33400 62 6c 65 20 61 63 63 65 73 73 69 62 6c 65 20 75  ble accessible u
33410 73 69 6e 67 20 74 68 65 20 63 6f 6e 6e 65 63 74  sing the connect
33420 69 6f 6e 20 68 61 6e 64 6c 65 20 70 61 73 73 65  ion handle passe
33430 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20 66  d as the first f
33440 75 6e 63 74 69 6f 6e 20 0a 2a 2a 20 61 72 67 75  unction .** argu
33450 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ment..**.** The 
33460 63 6f 6c 75 6d 6e 20 69 73 20 69 64 65 6e 74 69  column is identi
33470 66 69 65 64 20 62 79 20 74 68 65 20 73 65 63 6f  fied by the seco
33480 6e 64 2c 20 74 68 69 72 64 20 61 6e 64 20 66 6f  nd, third and fo
33490 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 73 20  urth parameters 
334a0 74 6f 20 0a 2a 2a 20 74 68 69 73 20 66 75 6e 63  to .** this func
334b0 74 69 6f 6e 2e 20 54 68 65 20 73 65 63 6f 6e 64  tion. The second
334c0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 65 69   parameter is ei
334d0 74 68 65 72 20 74 68 65 20 6e 61 6d 65 20 6f 66  ther the name of
334e0 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
334f0 20 28 69 2e 65 2e 20 22 6d 61 69 6e 22 2c 20 22   (i.e. "main", "
33500 74 65 6d 70 22 20 6f 72 20 61 6e 20 61 74 74 61  temp" or an atta
33510 63 68 65 64 20 64 61 74 61 62 61 73 65 29 20 63  ched database) c
33520 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 73 70  ontaining the sp
33530 65 63 69 66 69 65 64 0a 2a 2a 20 74 61 62 6c 65  ecified.** table
33540 20 6f 72 20 4e 55 4c 4c 2e 20 49 66 20 69 74 20   or NULL. If it 
33550 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 61 6c  is NULL, then al
33560 6c 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62  l attached datab
33570 61 73 65 73 20 61 72 65 20 73 65 61 72 63 68 65  ases are searche
33580 64 0a 2a 2a 20 66 6f 72 20 74 68 65 20 74 61 62  d.** for the tab
33590 6c 65 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d  le using the sam
335a0 65 20 61 6c 67 6f 72 69 74 68 6d 20 61 73 20 74  e algorithm as t
335b0 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69  he database engi
335c0 6e 65 20 75 73 65 73 20 74 6f 20 0a 2a 2a 20 72  ne uses to .** r
335d0 65 73 6f 6c 76 65 20 75 6e 71 75 61 6c 69 66 69  esolve unqualifi
335e0 65 64 20 74 61 62 6c 65 20 72 65 66 65 72 65 6e  ed table referen
335f0 63 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  ces..**.** The t
33600 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20  hird and fourth 
33610 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68  parameters to th
33620 69 73 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20  is function are 
33630 74 68 65 20 74 61 62 6c 65 20 61 6e 64 20 63 6f  the table and co
33640 6c 75 6d 6e 20 0a 2a 2a 20 6e 61 6d 65 20 6f 66  lumn .** name of
33650 20 74 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c   the desired col
33660 75 6d 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c  umn, respectivel
33670 79 2e 20 4e 65 69 74 68 65 72 20 6f 66 20 74 68  y. Neither of th
33680 65 73 65 20 70 61 72 61 6d 65 74 65 72 73 20 0a  ese parameters .
33690 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c 2e 0a  ** may be NULL..
336a0 2a 2a 0a 2a 2a 20 4d 65 74 61 20 69 6e 66 6f 72  **.** Meta infor
336b0 6d 61 74 69 6f 6e 20 69 73 20 72 65 74 75 72 6e  mation is return
336c0 65 64 20 62 79 20 77 72 69 74 69 6e 67 20 74 6f  ed by writing to
336d0 20 74 68 65 20 6d 65 6d 6f 72 79 20 6c 6f 63 61   the memory loca
336e0 74 69 6f 6e 73 20 70 61 73 73 65 64 20 61 73 0a  tions passed as.
336f0 2a 2a 20 74 68 65 20 35 74 68 20 61 6e 64 20 73  ** the 5th and s
33700 75 62 73 65 71 75 65 6e 74 20 70 61 72 61 6d 65  ubsequent parame
33710 74 65 72 73 20 74 6f 20 74 68 69 73 20 66 75 6e  ters to this fun
33720 63 74 69 6f 6e 2e 20 41 6e 79 20 6f 66 20 74 68  ction. Any of th
33730 65 73 65 20 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  ese .** argument
33740 73 20 6d 61 79 20 62 65 20 4e 55 4c 4c 2c 20 69  s may be NULL, i
33750 6e 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65  n which case the
33760 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 65   corresponding e
33770 6c 65 6d 65 6e 74 20 6f 66 20 6d 65 74 61 20 0a  lement of meta .
33780 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  ** information i
33790 73 20 6f 6d 6d 69 74 74 65 64 2e 0a 2a 2a 0a 2a  s ommitted..**.*
337a0 2a 20 3c 70 72 65 3e 0a 2a 2a 20 50 61 72 61 6d  * <pre>.** Param
337b0 65 74 65 72 20 20 20 20 20 4f 75 74 70 75 74 20  eter     Output 
337c0 54 79 70 65 20 20 20 20 20 20 44 65 73 63 72 69  Type      Descri
337d0 70 74 69 6f 6e 0a 2a 2a 20 2d 2d 2d 2d 2d 2d 2d  ption.** -------
337e0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
337f0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 0a  ------------.**.
33800 2a 2a 20 20 20 35 74 68 20 20 20 20 20 20 20 20  **   5th        
33810 20 63 6f 6e 73 74 20 63 68 61 72 2a 20 20 20 20   const char*    
33820 20 20 44 61 74 61 20 74 79 70 65 0a 2a 2a 20 20    Data type.**  
33830 20 36 74 68 20 20 20 20 20 20 20 20 20 63 6f 6e   6th         con
33840 73 74 20 63 68 61 72 2a 20 20 20 20 20 20 4e 61  st char*      Na
33850 6d 65 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c  me of the defaul
33860 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  t collation sequ
33870 65 6e 63 65 20 0a 2a 2a 20 20 20 37 74 68 20 20  ence .**   7th  
33880 20 20 20 20 20 20 20 69 6e 74 20 20 20 20 20 20         int      
33890 20 20 20 20 20 20 20 20 54 72 75 65 20 69 66 20          True if 
338a0 74 68 65 20 63 6f 6c 75 6d 6e 20 68 61 73 20 61  the column has a
338b0 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 72   NOT NULL constr
338c0 61 69 6e 74 0a 2a 2a 20 20 20 38 74 68 20 20 20  aint.**   8th   
338d0 20 20 20 20 20 20 69 6e 74 20 20 20 20 20 20 20        int       
338e0 20 20 20 20 20 20 20 54 72 75 65 20 69 66 20 74         True if t
338f0 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 70 61 72  he column is par
33900 74 20 6f 66 20 74 68 65 20 50 52 49 4d 41 52 59  t of the PRIMARY
33910 20 4b 45 59 0a 2a 2a 20 20 20 39 74 68 20 20 20   KEY.**   9th   
33920 20 20 20 20 20 20 69 6e 74 20 20 20 20 20 20 20        int       
33930 20 20 20 20 20 20 20 54 72 75 65 20 69 66 20 74         True if t
33940 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 41 55 54  he column is AUT
33950 4f 49 4e 43 52 45 4d 45 4e 54 0a 2a 2a 20 3c 2f  OINCREMENT.** </
33960 70 72 65 3e 0a 2a 2a 0a 2a 2a 0a 2a 2a 20 54 68  pre>.**.**.** Th
33970 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 64  e memory pointed
33980 20 74 6f 20 62 79 20 74 68 65 20 63 68 61 72 61   to by the chara
33990 63 74 65 72 20 70 6f 69 6e 74 65 72 73 20 72 65  cter pointers re
339a0 74 75 72 6e 65 64 20 66 6f 72 20 74 68 65 20 0a  turned for the .
339b0 2a 2a 20 64 65 63 6c 61 72 61 74 69 6f 6e 20 74  ** declaration t
339c0 79 70 65 20 61 6e 64 20 63 6f 6c 6c 61 74 69 6f  ype and collatio
339d0 6e 20 73 65 71 75 65 6e 63 65 20 69 73 20 76 61  n sequence is va
339e0 6c 69 64 20 6f 6e 6c 79 20 75 6e 74 69 6c 20 74  lid only until t
339f0 68 65 20 6e 65 78 74 20 0a 2a 2a 20 63 61 6c 6c  he next .** call
33a00 20 74 6f 20 61 6e 79 20 73 71 6c 69 74 65 20 41   to any sqlite A
33a10 50 49 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a  PI function..**.
33a20 2a 2a 20 49 66 20 74 68 65 20 73 70 65 63 69 66  ** If the specif
33a30 69 65 64 20 74 61 62 6c 65 20 69 73 20 61 63 74  ied table is act
33a40 75 61 6c 6c 79 20 61 20 76 69 65 77 2c 20 74 68  ually a view, th
33a50 65 6e 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72  en an error is r
33a60 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  eturned..**.** I
33a70 66 20 74 68 65 20 73 70 65 63 69 66 69 65 64 20  f the specified 
33a80 63 6f 6c 75 6d 6e 20 69 73 20 22 72 6f 77 69 64  column is "rowid
33a90 22 2c 20 22 6f 69 64 22 20 6f 72 20 22 5f 72 6f  ", "oid" or "_ro
33aa0 77 69 64 5f 22 20 61 6e 64 20 61 6e 20 0a 2a 2a  wid_" and an .**
33ab0 20 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59   INTEGER PRIMARY
33ac0 20 4b 45 59 20 63 6f 6c 75 6d 6e 20 68 61 73 20   KEY column has 
33ad0 62 65 65 6e 20 65 78 70 6c 69 63 69 74 6c 79 20  been explicitly 
33ae0 64 65 63 6c 61 72 65 64 2c 20 74 68 65 6e 20 74  declared, then t
33af0 68 65 20 6f 75 74 70 75 74 20 0a 2a 2a 20 70 61  he output .** pa
33b00 72 61 6d 65 74 65 72 73 20 61 72 65 20 73 65 74  rameters are set
33b10 20 66 6f 72 20 74 68 65 20 65 78 70 6c 69 63 69   for the explici
33b20 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c  tly declared col
33b30 75 6d 6e 2e 20 49 66 20 74 68 65 72 65 20 69 73  umn. If there is
33b40 20 6e 6f 0a 2a 2a 20 65 78 70 6c 69 63 69 74 6c   no.** explicitl
33b50 79 20 64 65 63 6c 61 72 65 64 20 49 50 4b 20 63  y declared IPK c
33b60 6f 6c 75 6d 6e 2c 20 74 68 65 6e 20 74 68 65 20  olumn, then the 
33b70 6f 75 74 70 75 74 20 70 61 72 61 6d 65 74 65 72  output parameter
33b80 73 20 61 72 65 20 73 65 74 20 61 73 20 0a 2a 2a  s are set as .**
33b90 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
33ba0 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 64 61 74  <pre>.**     dat
33bb0 61 20 74 79 70 65 3a 20 22 49 4e 54 45 47 45 52  a type: "INTEGER
33bc0 22 0a 2a 2a 20 20 20 20 20 63 6f 6c 6c 61 74 69  ".**     collati
33bd0 6f 6e 20 73 65 71 75 65 6e 63 65 3a 20 22 42 49  on sequence: "BI
33be0 4e 41 52 59 22 0a 2a 2a 20 20 20 20 20 6e 6f 74  NARY".**     not
33bf0 20 6e 75 6c 6c 3a 20 30 0a 2a 2a 20 20 20 20 20   null: 0.**     
33c00 70 72 69 6d 61 72 79 20 6b 65 79 3a 20 31 0a 2a  primary key: 1.*
33c10 2a 20 20 20 20 20 61 75 74 6f 20 69 6e 63 72 65  *     auto incre
33c20 6d 65 6e 74 3a 20 30 0a 2a 2a 20 3c 2f 70 72 65  ment: 0.** </pre
33c30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e  >.**.** This fun
33c40 63 74 69 6f 6e 20 6d 61 79 20 6c 6f 61 64 20 6f  ction may load o
33c50 6e 65 20 6f 72 20 6d 6f 72 65 20 73 63 68 65 6d  ne or more schem
33c60 61 73 20 66 72 6f 6d 20 64 61 74 61 62 61 73 65  as from database
33c70 20 66 69 6c 65 73 2e 20 49 66 20 61 6e 0a 2a 2a   files. If an.**
33c80 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75   error occurs du
33c90 72 69 6e 67 20 74 68 69 73 20 70 72 6f 63 65 73  ring this proces
33ca0 73 2c 20 6f 72 20 69 66 20 74 68 65 20 72 65 71  s, or if the req
33cb0 75 65 73 74 65 64 20 74 61 62 6c 65 20 6f 72 20  uested table or 
33cc0 63 6f 6c 75 6d 6e 0a 2a 2a 20 63 61 6e 6e 6f 74  column.** cannot
33cd0 20 62 65 20 66 6f 75 6e 64 2c 20 61 6e 20 53 51   be found, an SQ
33ce0 4c 49 54 45 20 65 72 72 6f 72 20 63 6f 64 65 20  LITE error code 
33cf0 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20  is returned and 
33d00 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
33d10 0a 2a 2a 20 6c 65 66 74 20 69 6e 20 74 68 65 20  .** left in the 
33d20 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  database handle 
33d30 28 74 6f 20 62 65 20 72 65 74 72 69 65 76 65 64  (to be retrieved
33d40 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33 5f 65   using sqlite3_e
33d50 72 72 6d 73 67 28 29 29 2e 0a 2a 2a 0a 2a 2a 20  rrmsg())..**.** 
33d60 54 68 69 73 20 41 50 49 20 69 73 20 6f 6e 6c 79  This API is only
33d70 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68   available if th
33d80 65 20 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f  e library was co
33d90 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a  mpiled with the.
33da0 2a 2a 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  ** SQLITE_ENABLE
33db0 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41  _COLUMN_METADATA
33dc0 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79   preprocessor sy
33dd0 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a 2a 2f  mbol defined..*/
33de0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 61 62  .int sqlite3_tab
33df0 6c 65 5f 63 6f 6c 75 6d 6e 5f 6d 65 74 61 64 61  le_column_metada
33e00 74 61 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  ta(.  sqlite3 *d
33e10 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  b,              
33e20 20 20 2f 2a 20 43 6f 6e 6e 65 63 74 69 6f 6e 20    /* Connection 
33e30 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
33e40 74 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65 2c  t char *zDbName,
33e50 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
33e60 61 73 65 20 6e 61 6d 65 20 6f 72 20 4e 55 4c 4c  ase name or NULL
33e70 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
33e80 20 2a 7a 54 61 62 6c 65 4e 61 6d 65 2c 20 20 20   *zTableName,   
33e90 20 20 2f 2a 20 54 61 62 6c 65 20 6e 61 6d 65 20    /* Table name 
33ea0 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
33eb0 2a 7a 43 6f 6c 75 6d 6e 4e 61 6d 65 2c 20 20 20  *zColumnName,   
33ec0 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 61 6d 65 20   /* Column name 
33ed0 2a 2f 0a 20 20 63 68 61 72 20 63 6f 6e 73 74 20  */.  char const 
33ee0 2a 2a 70 7a 44 61 74 61 54 79 70 65 2c 20 20 20  **pzDataType,   
33ef0 20 2f 2a 20 4f 55 54 50 55 54 3a 20 44 65 63 6c   /* OUTPUT: Decl
33f00 61 72 65 64 20 64 61 74 61 20 74 79 70 65 20 2a  ared data type *
33f10 2f 0a 20 20 63 68 61 72 20 63 6f 6e 73 74 20 2a  /.  char const *
33f20 2a 70 7a 43 6f 6c 6c 53 65 71 2c 20 20 20 20 20  *pzCollSeq,     
33f30 2f 2a 20 4f 55 54 50 55 54 3a 20 43 6f 6c 6c 61  /* OUTPUT: Colla
33f40 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 6e 61  tion sequence na
33f50 6d 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 4e 6f  me */.  int *pNo
33f60 74 4e 75 6c 6c 2c 20 20 20 20 20 20 20 20 20 20  tNull,          
33f70 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54      /* OUTPUT: T
33f80 72 75 65 20 69 66 20 4e 4f 54 20 4e 55 4c 4c 20  rue if NOT NULL 
33f90 63 6f 6e 73 74 72 61 69 6e 74 20 65 78 69 73 74  constraint exist
33fa0 73 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 50 72 69  s */.  int *pPri
33fb0 6d 61 72 79 4b 65 79 2c 20 20 20 20 20 20 20 20  maryKey,        
33fc0 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72     /* OUTPUT: Tr
33fd0 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 70 61 72  ue if column par
33fe0 74 20 6f 66 20 50 4b 20 2a 2f 0a 20 20 69 6e 74  t of PK */.  int
33ff0 20 2a 70 41 75 74 6f 69 6e 63 20 20 20 20 20 20   *pAutoinc      
34000 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50           /* OUTP
34010 55 54 3a 20 54 72 75 65 20 69 66 20 63 6f 6c 75  UT: True if colu
34020 6d 6e 20 69 73 20 61 75 74 6f 2d 69 6e 63 72 65  mn is auto-incre
34030 6d 65 6e 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a  ment */.);../*.*
34040 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 6f 61 64  * CAPI3REF: Load
34050 20 41 6e 20 45 78 74 65 6e 73 69 6f 6e 20 7b 46   An Extension {F
34060 31 32 36 30 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31  12600}.**.** {F1
34070 32 36 30 31 7d 20 54 68 65 20 73 71 6c 69 74 65  2601} The sqlite
34080 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e  3_load_extension
34090 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  () interface.** 
340a0 61 74 74 65 6d 70 74 73 20 74 6f 20 6c 6f 61 64  attempts to load
340b0 20 61 6e 20 53 51 4c 69 74 65 20 65 78 74 65 6e   an SQLite exten
340c0 73 69 6f 6e 20 6c 69 62 72 61 72 79 20 63 6f 6e  sion library con
340d0 74 61 69 6e 65 64 20 69 6e 20 74 68 65 20 66 69  tained in the fi
340e0 6c 65 0a 2a 2a 20 7a 46 69 6c 65 2e 20 7b 46 31  le.** zFile. {F1
340f0 32 36 30 32 7d 20 54 68 65 20 65 6e 74 72 79 20  2602} The entry 
34100 70 6f 69 6e 74 20 69 73 20 7a 50 72 6f 63 2e 20  point is zProc. 
34110 7b 46 31 32 36 30 33 7d 20 7a 50 72 6f 63 20 6d  {F12603} zProc m
34120 61 79 20 62 65 20 30 0a 2a 2a 20 69 6e 20 77 68  ay be 0.** in wh
34130 69 63 68 20 63 61 73 65 20 74 68 65 20 6e 61 6d  ich case the nam
34140 65 20 6f 66 20 74 68 65 20 65 6e 74 72 79 20 70  e of the entry p
34150 6f 69 6e 74 20 64 65 66 61 75 6c 74 73 0a 2a 2a  oint defaults.**
34160 20 74 6f 20 22 73 71 6c 69 74 65 33 5f 65 78 74   to "sqlite3_ext
34170 65 6e 73 69 6f 6e 5f 69 6e 69 74 22 2e 0a 2a 2a  ension_init"..**
34180 0a 2a 2a 20 7b 46 31 32 36 30 34 7d 20 54 68 65  .** {F12604} The
34190 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78   sqlite3_load_ex
341a0 74 65 6e 73 69 6f 6e 28 29 20 69 6e 74 65 72 66  tension() interf
341b0 61 63 65 20 73 68 61 6c 6c 0a 2a 2a 20 72 65 74  ace shall.** ret
341c0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  urn [SQLITE_OK] 
341d0 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20 5b  on success and [
341e0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66  SQLITE_ERROR] if
341f0 20 73 6f 6d 65 74 68 69 6e 67 20 67 6f 65 73 20   something goes 
34200 77 72 6f 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  wrong..**.** {F1
34210 32 36 30 35 7d 0a 2a 2a 20 49 66 20 61 6e 20 65  2605}.** If an e
34220 72 72 6f 72 20 6f 63 63 75 72 73 20 61 6e 64 20  rror occurs and 
34230 70 7a 45 72 72 4d 73 67 20 69 73 20 6e 6f 74 20  pzErrMsg is not 
34240 30 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 73  0, then the.** s
34250 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65  qlite3_load_exte
34260 6e 73 69 6f 6e 28 29 20 69 6e 74 65 72 66 61 63  nsion() interfac
34270 65 20 73 68 61 6c 6c 20 61 74 74 65 6d 70 74 20  e shall attempt 
34280 74 6f 20 66 69 6c 6c 20 2a 70 7a 45 72 72 4d 73  to fill *pzErrMs
34290 67 20 77 69 74 68 20 0a 2a 2a 20 65 72 72 6f 72  g with .** error
342a0 20 6d 65 73 73 61 67 65 20 74 65 78 74 20 73 74   message text st
342b0 6f 72 65 64 20 69 6e 20 6d 65 6d 6f 72 79 20 6f  ored in memory o
342c0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
342d0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e  lite3_malloc()].
342e0 0a 2a 2a 20 7b 45 4e 44 7d 20 20 54 68 65 20 63  .** {END}  The c
342f0 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  alling function 
34300 73 68 6f 75 6c 64 20 66 72 65 65 20 74 68 69 73  should free this
34310 20 6d 65 6d 6f 72 79 0a 2a 2a 20 62 79 20 63 61   memory.** by ca
34320 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  lling [sqlite3_f
34330 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46  ree()]..**.** {F
34340 31 32 36 30 36 7d 0a 2a 2a 20 45 78 74 65 6e 73  12606}.** Extens
34350 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 6d 75 73 74  ion loading must
34360 20 62 65 20 65 6e 61 62 6c 65 64 20 75 73 69 6e   be enabled usin
34370 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c  g [sqlite3_enabl
34380 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e  e_load_extension
34390 28 29 5d 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20  ()].** prior to 
343a0 63 61 6c 6c 69 6e 67 20 74 68 69 73 20 41 50 49  calling this API
343b0 20 6f 72 20 61 6e 20 65 72 72 6f 72 20 77 69 6c   or an error wil
343c0 6c 20 62 65 20 72 65 74 75 72 6e 65 64 2e 0a 2a  l be returned..*
343d0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 6f  /.int sqlite3_lo
343e0 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 0a 20 20  ad_extension(.  
343f0 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
34400 20 20 20 20 20 20 2f 2a 20 4c 6f 61 64 20 74 68        /* Load th
34410 65 20 65 78 74 65 6e 73 69 6f 6e 20 69 6e 74 6f  e extension into
34420 20 74 68 69 73 20 64 61 74 61 62 61 73 65 20 63   this database c
34430 6f 6e 6e 65 63 74 69 6f 6e 20 2a 2f 0a 20 20 63  onnection */.  c
34440 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65  onst char *zFile
34450 2c 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20  ,    /* Name of 
34460 74 68 65 20 73 68 61 72 65 64 20 6c 69 62 72 61  the shared libra
34470 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 65 78  ry containing ex
34480 74 65 6e 73 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e  tension */.  con
34490 73 74 20 63 68 61 72 20 2a 7a 50 72 6f 63 2c 20  st char *zProc, 
344a0 20 20 20 2f 2a 20 45 6e 74 72 79 20 70 6f 69 6e     /* Entry poin
344b0 74 2e 20 20 44 65 72 69 76 65 64 20 66 72 6f 6d  t.  Derived from
344c0 20 7a 46 69 6c 65 20 69 66 20 30 20 2a 2f 0a 20   zFile if 0 */. 
344d0 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 4d 73 67   char **pzErrMsg
344e0 20 20 20 20 20 20 20 2f 2a 20 50 75 74 20 65 72         /* Put er
344f0 72 6f 72 20 6d 65 73 73 61 67 65 20 68 65 72 65  ror message here
34500 20 69 66 20 6e 6f 74 20 30 20 2a 2f 0a 29 3b 0a   if not 0 */.);.
34510 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
34520 20 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61    Enable Or Disa
34530 62 6c 65 20 45 78 74 65 6e 73 69 6f 6e 20 4c 6f  ble Extension Lo
34540 61 64 69 6e 67 20 7b 46 31 32 36 32 30 7d 0a 2a  ading {F12620}.*
34550 2a 0a 2a 2a 20 53 6f 20 61 73 20 6e 6f 74 20 74  *.** So as not t
34560 6f 20 6f 70 65 6e 20 73 65 63 75 72 69 74 79 20  o open security 
34570 68 6f 6c 65 73 20 69 6e 20 6f 6c 64 65 72 20 61  holes in older a
34580 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
34590 20 61 72 65 0a 2a 2a 20 75 6e 70 72 65 70 61 72   are.** unprepar
345a0 65 64 20 74 6f 20 64 65 61 6c 20 77 69 74 68 20  ed to deal with 
345b0 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e  extension loadin
345c0 67 2c 20 61 6e 64 20 61 73 20 61 20 6d 65 61 6e  g, and as a mean
345d0 73 20 6f 66 20 64 69 73 61 62 6c 69 6e 67 0a 2a  s of disabling.*
345e0 2a 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64  * extension load
345f0 69 6e 67 20 77 68 69 6c 65 20 65 76 61 6c 75 61  ing while evalua
34600 74 69 6e 67 20 75 73 65 72 2d 65 6e 74 65 72 65  ting user-entere
34610 64 20 53 51 4c 2c 20 74 68 65 20 66 6f 6c 6c 6f  d SQL, the follo
34620 77 69 6e 67 0a 2a 2a 20 41 50 49 20 69 73 20 70  wing.** API is p
34630 72 6f 76 69 64 65 64 20 74 6f 20 74 75 72 6e 20  rovided to turn 
34640 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61  the [sqlite3_loa
34650 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 6d  d_extension()] m
34660 65 63 68 61 6e 69 73 6d 20 6f 6e 20 61 6e 64 0a  echanism on and.
34670 2a 2a 20 6f 66 66 2e 20 20 7b 46 31 32 36 32 32  ** off.  {F12622
34680 7d 20 49 74 20 69 73 20 6f 66 66 20 62 79 20 64  } It is off by d
34690 65 66 61 75 6c 74 2e 20 7b 45 4e 44 7d 20 53 65  efault. {END} Se
346a0 65 20 74 69 63 6b 65 74 20 23 31 38 36 33 2e 0a  e ticket #1863..
346b0 2a 2a 0a 2a 2a 20 7b 46 31 32 36 32 31 7d 20 43  **.** {F12621} C
346c0 61 6c 6c 20 74 68 65 20 73 71 6c 69 74 65 33 5f  all the sqlite3_
346d0 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65  enable_load_exte
346e0 6e 73 69 6f 6e 28 29 20 72 6f 75 74 69 6e 65 0a  nsion() routine.
346f0 2a 2a 20 77 69 74 68 20 6f 6e 6f 66 66 3d 3d 31  ** with onoff==1
34700 20 74 6f 20 74 75 72 6e 20 65 78 74 65 6e 73 69   to turn extensi
34710 6f 6e 20 6c 6f 61 64 69 6e 67 20 6f 6e 0a 2a 2a  on loading on.**
34720 20 61 6e 64 20 63 61 6c 6c 20 69 74 20 77 69 74   and call it wit
34730 68 20 6f 6e 6f 66 66 3d 3d 30 20 74 6f 20 74 75  h onoff==0 to tu
34740 72 6e 20 69 74 20 62 61 63 6b 20 6f 66 66 20 61  rn it back off a
34750 67 61 69 6e 2e 20 7b 45 4e 44 7d 0a 2a 2f 0a 69  gain. {END}.*/.i
34760 6e 74 20 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c  nt sqlite3_enabl
34770 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e  e_load_extension
34780 28 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 69 6e  (sqlite3 *db, in
34790 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a  t onoff);../*.**
347a0 20 43 41 50 49 33 52 45 46 3a 20 4d 61 6b 65 20   CAPI3REF: Make 
347b0 41 72 72 61 6e 67 65 6d 65 6e 74 73 20 54 6f 20  Arrangements To 
347c0 41 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 4c 6f  Automatically Lo
347d0 61 64 20 41 6e 20 45 78 74 65 6e 73 69 6f 6e 20  ad An Extension 
347e0 7b 46 31 32 36 34 30 7d 0a 2a 2a 0a 2a 2a 20 7b  {F12640}.**.** {
347f0 46 31 32 36 34 31 7d 20 54 68 69 73 20 66 75 6e  F12641} This fun
34800 63 74 69 6f 6e 0a 2a 2a 20 72 65 67 69 73 74 65  ction.** registe
34810 72 73 20 61 6e 20 65 78 74 65 6e 73 69 6f 6e 20  rs an extension 
34820 65 6e 74 72 79 20 70 6f 69 6e 74 20 74 68 61 74  entry point that
34830 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   is automaticall
34840 79 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65  y invoked.** whe
34850 6e 65 76 65 72 20 61 20 6e 65 77 20 64 61 74 61  never a new data
34860 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
34870 69 73 20 6f 70 65 6e 65 64 20 75 73 69 6e 67 0a  is opened using.
34880 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ** [sqlite3_open
34890 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
348a0 65 6e 31 36 28 29 5d 2c 20 6f 72 20 5b 73 71 6c  en16()], or [sql
348b0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e  ite3_open_v2()].
348c0 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 69   {END}.**.** Thi
348d0 73 20 41 50 49 20 63 61 6e 20 62 65 20 69 6e 76  s API can be inv
348e0 6f 6b 65 64 20 61 74 20 70 72 6f 67 72 61 6d 20  oked at program 
348f0 73 74 61 72 74 75 70 20 69 6e 20 6f 72 64 65 72  startup in order
34900 20 74 6f 20 72 65 67 69 73 74 65 72 0a 2a 2a 20   to register.** 
34910 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 73 74 61 74  one or more stat
34920 69 63 61 6c 6c 79 20 6c 69 6e 6b 65 64 20 65 78  ically linked ex
34930 74 65 6e 73 69 6f 6e 73 20 74 68 61 74 20 77 69  tensions that wi
34940 6c 6c 20 62 65 20 61 76 61 69 6c 61 62 6c 65 0a  ll be available.
34950 2a 2a 20 74 6f 20 61 6c 6c 20 6e 65 77 20 64 61  ** to all new da
34960 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
34970 6e 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36 34  ns..**.** {F1264
34980 32 7d 20 44 75 70 6c 69 63 61 74 65 20 65 78 74  2} Duplicate ext
34990 65 6e 73 69 6f 6e 73 20 61 72 65 20 64 65 74 65  ensions are dete
349a0 63 74 65 64 20 73 6f 20 63 61 6c 6c 69 6e 67 20  cted so calling 
349b0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 6c  this routine mul
349c0 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 20 77  tiple.** times w
349d0 69 74 68 20 74 68 65 20 73 61 6d 65 20 65 78 74  ith the same ext
349e0 65 6e 73 69 6f 6e 20 69 73 20 68 61 72 6d 6c 65  ension is harmle
349f0 73 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36 34  ss..**.** {F1264
34a00 33 7d 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  3} This routine 
34a10 73 74 6f 72 65 73 20 61 20 70 6f 69 6e 74 65 72  stores a pointer
34a20 20 74 6f 20 74 68 65 20 65 78 74 65 6e 73 69 6f   to the extensio
34a30 6e 20 69 6e 20 61 6e 20 61 72 72 61 79 0a 2a 2a  n in an array.**
34a40 20 74 68 61 74 20 69 73 20 6f 62 74 61 69 6e 65   that is obtaine
34a50 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 5f 6d 61  d from sqlite_ma
34a60 6c 6c 6f 63 28 29 2e 20 7b 45 4e 44 7d 20 49 66  lloc(). {END} If
34a70 20 79 6f 75 20 72 75 6e 20 61 20 6d 65 6d 6f 72   you run a memor
34a80 79 20 6c 65 61 6b 0a 2a 2a 20 63 68 65 63 6b 65  y leak.** checke
34a90 72 20 6f 6e 20 79 6f 75 72 20 70 72 6f 67 72 61  r on your progra
34aa0 6d 20 61 6e 64 20 69 74 20 72 65 70 6f 72 74 73  m and it reports
34ab0 20 61 20 6c 65 61 6b 20 62 65 63 61 75 73 65 20   a leak because 
34ac0 6f 66 20 74 68 69 73 0a 2a 2a 20 61 72 72 61 79  of this.** array
34ad0 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 5b 73  , then invoke [s
34ae0 71 6c 69 74 65 33 5f 72 65 73 65 74 5f 61 75 74  qlite3_reset_aut
34af0 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 70  o_extension()] p
34b00 72 69 6f 72 0a 2a 2a 20 74 6f 20 73 68 75 74 64  rior.** to shutd
34b10 6f 77 6e 20 74 6f 20 66 72 65 65 20 74 68 65 20  own to free the 
34b20 6d 65 6d 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46  memory..**.** {F
34b30 31 32 36 34 34 7d 20 41 75 74 6f 6d 61 74 69 63  12644} Automatic
34b40 20 65 78 74 65 6e 73 69 6f 6e 73 20 61 70 70 6c   extensions appl
34b50 79 20 61 63 72 6f 73 73 20 61 6c 6c 20 74 68 72  y across all thr
34b60 65 61 64 73 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a  eads. {END}.**.*
34b70 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65  * This interface
34b80 20 69 73 20 65 78 70 65 72 69 6d 65 6e 74 61 6c   is experimental
34b90 20 61 6e 64 20 69 73 20 73 75 62 6a 65 63 74 20   and is subject 
34ba0 74 6f 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20  to change or.** 
34bb0 72 65 6d 6f 76 61 6c 20 69 6e 20 66 75 74 75 72  removal in futur
34bc0 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
34bd0 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  Lite..*/.int sql
34be0 69 74 65 33 5f 61 75 74 6f 5f 65 78 74 65 6e 73  ite3_auto_extens
34bf0 69 6f 6e 28 76 6f 69 64 20 2a 78 45 6e 74 72 79  ion(void *xEntry
34c00 50 6f 69 6e 74 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20  Point);.../*.** 
34c10 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20  CAPI3REF: Reset 
34c20 41 75 74 6f 6d 61 74 69 63 20 45 78 74 65 6e 73  Automatic Extens
34c30 69 6f 6e 20 4c 6f 61 64 69 6e 67 20 7b 46 31 32  ion Loading {F12
34c40 36 36 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36  660}.**.** {F126
34c50 36 31 7d 20 54 68 69 73 20 66 75 6e 63 74 69 6f  61} This functio
34c60 6e 20 64 69 73 61 62 6c 65 73 20 61 6c 6c 20 70  n disables all p
34c70 72 65 76 69 6f 75 73 6c 79 20 72 65 67 69 73 74  reviously regist
34c80 65 72 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69  ered.** automati
34c90 63 20 65 78 74 65 6e 73 69 6f 6e 73 2e 20 7b 45  c extensions. {E
34ca0 4e 44 7d 20 20 54 68 69 73 0a 2a 2a 20 72 6f 75  ND}  This.** rou
34cb0 74 69 6e 65 20 75 6e 64 6f 65 73 20 74 68 65 20  tine undoes the 
34cc0 65 66 66 65 63 74 20 6f 66 20 61 6c 6c 20 70 72  effect of all pr
34cd0 69 6f 72 20 5b 73 71 6c 69 74 65 33 5f 61 75 74  ior [sqlite3_aut
34ce0 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 0a 2a  o_extension()].*
34cf0 2a 20 63 61 6c 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b  * calls..**.** {
34d00 46 31 32 36 36 32 7d 20 54 68 69 73 20 63 61 6c  F12662} This cal
34d10 6c 20 64 69 73 61 62 6c 65 64 20 61 75 74 6f 6d  l disabled autom
34d20 61 74 69 63 20 65 78 74 65 6e 73 69 6f 6e 73 20  atic extensions 
34d30 69 6e 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 20  in all threads. 
34d40 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73  {END}.**.** This
34d50 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 65 78   interface is ex
34d60 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69  perimental and i
34d70 73 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61  s subject to cha
34d80 6e 67 65 20 6f 72 0a 2a 2a 20 72 65 6d 6f 76 61  nge or.** remova
34d90 6c 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  l in future rele
34da0 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ases of SQLite..
34db0 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  */.void sqlite3_
34dc0 72 65 73 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e  reset_auto_exten
34dd0 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 0a 0a 2f 2a  sion(void);.../*
34de0 0a 2a 2a 2a 2a 2a 2a 20 45 58 50 45 52 49 4d 45  .****** EXPERIME
34df0 4e 54 41 4c 20 2d 20 73 75 62 6a 65 63 74 20 74  NTAL - subject t
34e00 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75 74  o change without
34e10 20 6e 6f 74 69 63 65 20 2a 2a 2a 2a 2a 2a 2a 2a   notice ********
34e20 2a 2a 2a 2a 2a 2a 0a 2a 2a 0a 2a 2a 20 54 68 65  ******.**.** The
34e30 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 74 68   interface to th
34e40 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20  e virtual-table 
34e50 6d 65 63 68 61 6e 69 73 6d 20 69 73 20 63 75 72  mechanism is cur
34e60 72 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 65  rently considere
34e70 64 0a 2a 2a 20 74 6f 20 62 65 20 65 78 70 65 72  d.** to be exper
34e80 69 6d 65 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e  imental.  The in
34e90 74 65 72 66 61 63 65 20 6d 69 67 68 74 20 63 68  terface might ch
34ea0 61 6e 67 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74  ange in incompat
34eb0 69 62 6c 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66  ible ways..** If
34ec0 20 74 68 69 73 20 69 73 20 61 20 70 72 6f 62 6c   this is a probl
34ed0 65 6d 20 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e  em for you, do n
34ee0 6f 74 20 75 73 65 20 74 68 65 20 69 6e 74 65 72  ot use the inter
34ef0 66 61 63 65 20 61 74 20 74 68 69 73 20 74 69 6d  face at this tim
34f00 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  e..**.** When th
34f10 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20  e virtual-table 
34f20 6d 65 63 68 61 6e 69 73 6d 20 73 74 61 62 6c 69  mechanism stabli
34f30 7a 65 73 2c 20 77 65 20 77 69 6c 6c 20 64 65 63  zes, we will dec
34f40 6c 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74 65  lare the.** inte
34f50 72 66 61 63 65 20 66 69 78 65 64 2c 20 73 75 70  rface fixed, sup
34f60 70 6f 72 74 20 69 74 20 69 6e 64 65 66 69 6e 69  port it indefini
34f70 74 65 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76 65  tely, and remove
34f80 20 74 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a   this comment..*
34f90 2f 0a 0a 2f 2a 0a 2a 2a 20 53 74 72 75 63 74 75  /../*.** Structu
34fa0 72 65 73 20 75 73 65 64 20 62 79 20 74 68 65 20  res used by the 
34fb0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6e  virtual table in
34fc0 74 65 72 66 61 63 65 0a 2a 2f 0a 74 79 70 65 64  terface.*/.typed
34fd0 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
34fe0 33 5f 76 74 61 62 20 73 71 6c 69 74 65 33 5f 76  3_vtab sqlite3_v
34ff0 74 61 62 3b 0a 74 79 70 65 64 65 66 20 73 74 72  tab;.typedef str
35000 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65  uct sqlite3_inde
35010 78 5f 69 6e 66 6f 20 73 71 6c 69 74 65 33 5f 69  x_info sqlite3_i
35020 6e 64 65 78 5f 69 6e 66 6f 3b 0a 74 79 70 65 64  ndex_info;.typed
35030 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
35040 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 73 71  3_vtab_cursor sq
35050 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f  lite3_vtab_curso
35060 72 3b 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  r;.typedef struc
35070 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65  t sqlite3_module
35080 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 3b   sqlite3_module;
35090 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
350a0 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20  : Virtual Table 
350b0 4f 62 6a 65 63 74 20 7b 46 31 38 30 30 30 7d 0a  Object {F18000}.
350c0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c  ** KEYWORDS: sql
350d0 69 74 65 33 5f 6d 6f 64 75 6c 65 0a 2a 2a 0a 2a  ite3_module.**.*
350e0 2a 20 41 20 6d 6f 64 75 6c 65 20 69 73 20 61 20  * A module is a 
350f0 63 6c 61 73 73 20 6f 66 20 76 69 72 74 75 61 6c  class of virtual
35100 20 74 61 62 6c 65 73 2e 20 20 45 61 63 68 20 6d   tables.  Each m
35110 6f 64 75 6c 65 20 69 73 20 64 65 66 69 6e 65 64  odule is defined
35120 0a 2a 2a 20 62 79 20 61 6e 20 69 6e 73 74 61 6e  .** by an instan
35130 63 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ce of the follow
35140 69 6e 67 20 73 74 72 75 63 74 75 72 65 2e 20 20  ing structure.  
35150 54 68 69 73 20 73 74 72 75 63 74 75 72 65 20 63  This structure c
35160 6f 6e 73 69 73 74 73 0a 2a 2a 20 6d 6f 73 74 6c  onsists.** mostl
35170 79 20 6f 66 20 6d 65 74 68 6f 64 73 20 66 6f 72  y of methods for
35180 20 74 68 65 20 6d 6f 64 75 6c 65 2e 0a 2a 2f 0a   the module..*/.
35190 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d  struct sqlite3_m
351a0 6f 64 75 6c 65 20 7b 0a 20 20 69 6e 74 20 69 56  odule {.  int iV
351b0 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a  ersion;.  int (*
351c0 78 43 72 65 61 74 65 29 28 73 71 6c 69 74 65 33  xCreate)(sqlite3
351d0 2a 2c 20 76 6f 69 64 20 2a 70 41 75 78 2c 0a 20  *, void *pAux,. 
351e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e                in
351f0 74 20 61 72 67 63 2c 20 63 6f 6e 73 74 20 63 68  t argc, const ch
35200 61 72 20 2a 63 6f 6e 73 74 2a 61 72 67 76 2c 0a  ar *const*argv,.
35210 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 73                 s
35220 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 2a 70 70  qlite3_vtab **pp
35230 56 54 61 62 2c 20 63 68 61 72 2a 2a 29 3b 0a 20  VTab, char**);. 
35240 20 69 6e 74 20 28 2a 78 43 6f 6e 6e 65 63 74 29   int (*xConnect)
35250 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 20  (sqlite3*, void 
35260 2a 70 41 75 78 2c 0a 20 20 20 20 20 20 20 20 20  *pAux,.         
35270 20 20 20 20 20 20 69 6e 74 20 61 72 67 63 2c 20        int argc, 
35280 63 6f 6e 73 74 20 63 68 61 72 20 2a 63 6f 6e 73  const char *cons
35290 74 2a 61 72 67 76 2c 0a 20 20 20 20 20 20 20 20  t*argv,.        
352a0 20 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 76         sqlite3_v
352b0 74 61 62 20 2a 2a 70 70 56 54 61 62 2c 20 63 68  tab **ppVTab, ch
352c0 61 72 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  ar**);.  int (*x
352d0 42 65 73 74 49 6e 64 65 78 29 28 73 71 6c 69 74  BestIndex)(sqlit
352e0 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 2c 20  e3_vtab *pVTab, 
352f0 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e  sqlite3_index_in
35300 66 6f 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44  fo*);.  int (*xD
35310 69 73 63 6f 6e 6e 65 63 74 29 28 73 71 6c 69 74  isconnect)(sqlit
35320 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b  e3_vtab *pVTab);
35330 0a 20 20 69 6e 74 20 28 2a 78 44 65 73 74 72 6f  .  int (*xDestro
35340 79 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20  y)(sqlite3_vtab 
35350 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28  *pVTab);.  int (
35360 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f  *xOpen)(sqlite3_
35370 76 74 61 62 20 2a 70 56 54 61 62 2c 20 73 71 6c  vtab *pVTab, sql
35380 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72  ite3_vtab_cursor
35390 20 2a 2a 70 70 43 75 72 73 6f 72 29 3b 0a 20 20   **ppCursor);.  
353a0 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71  int (*xClose)(sq
353b0 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f  lite3_vtab_curso
353c0 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69  r*);.  int (*xFi
353d0 6c 74 65 72 29 28 73 71 6c 69 74 65 33 5f 76 74  lter)(sqlite3_vt
353e0 61 62 5f 63 75 72 73 6f 72 2a 2c 20 69 6e 74 20  ab_cursor*, int 
353f0 69 64 78 4e 75 6d 2c 20 63 6f 6e 73 74 20 63 68  idxNum, const ch
35400 61 72 20 2a 69 64 78 53 74 72 2c 0a 20 20 20 20  ar *idxStr,.    
35410 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20              int 
35420 61 72 67 63 2c 20 73 71 6c 69 74 65 33 5f 76 61  argc, sqlite3_va
35430 6c 75 65 20 2a 2a 61 72 67 76 29 3b 0a 20 20 69  lue **argv);.  i
35440 6e 74 20 28 2a 78 4e 65 78 74 29 28 73 71 6c 69  nt (*xNext)(sqli
35450 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a  te3_vtab_cursor*
35460 29 3b 0a 20 20 69 6e 74 20 28 2a 78 45 6f 66 29  );.  int (*xEof)
35470 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75  (sqlite3_vtab_cu
35480 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  rsor*);.  int (*
35490 78 43 6f 6c 75 6d 6e 29 28 73 71 6c 69 74 65 33  xColumn)(sqlite3
354a0 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 73  _vtab_cursor*, s
354b0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
354c0 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78   int);.  int (*x
354d0 52 6f 77 69 64 29 28 73 71 6c 69 74 65 33 5f 76  Rowid)(sqlite3_v
354e0 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 73 71 6c  tab_cursor*, sql
354f0 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 52 6f 77  ite3_int64 *pRow
35500 69 64 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 70  id);.  int (*xUp
35510 64 61 74 65 29 28 73 71 6c 69 74 65 33 5f 76 74  date)(sqlite3_vt
35520 61 62 20 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74  ab *, int, sqlit
35530 65 33 5f 76 61 6c 75 65 20 2a 2a 2c 20 73 71 6c  e3_value **, sql
35540 69 74 65 33 5f 69 6e 74 36 34 20 2a 29 3b 0a 20  ite3_int64 *);. 
35550 20 69 6e 74 20 28 2a 78 42 65 67 69 6e 29 28 73   int (*xBegin)(s
35560 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54  qlite3_vtab *pVT
35570 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79  ab);.  int (*xSy
35580 6e 63 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  nc)(sqlite3_vtab
35590 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20   *pVTab);.  int 
355a0 28 2a 78 43 6f 6d 6d 69 74 29 28 73 71 6c 69 74  (*xCommit)(sqlit
355b0 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b  e3_vtab *pVTab);
355c0 0a 20 20 69 6e 74 20 28 2a 78 52 6f 6c 6c 62 61  .  int (*xRollba
355d0 63 6b 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  ck)(sqlite3_vtab
355e0 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20   *pVTab);.  int 
355f0 28 2a 78 46 69 6e 64 46 75 6e 63 74 69 6f 6e 29  (*xFindFunction)
35600 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70  (sqlite3_vtab *p
35610 56 74 61 62 2c 20 69 6e 74 20 6e 41 72 67 2c 20  Vtab, int nArg, 
35620 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
35630 65 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  e,.             
35640 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 20 28            void (
35650 2a 2a 70 78 46 75 6e 63 29 28 73 71 6c 69 74 65  **pxFunc)(sqlite
35660 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
35670 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
35680 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
35690 20 20 20 20 20 20 20 20 76 6f 69 64 20 2a 2a 70          void **p
356a0 70 41 72 67 29 3b 0a 0a 20 20 69 6e 74 20 28 2a  pArg);..  int (*
356b0 78 52 65 6e 61 6d 65 29 28 73 71 6c 69 74 65 33  xRename)(sqlite3
356c0 5f 76 74 61 62 20 2a 70 56 74 61 62 2c 20 63 6f  _vtab *pVtab, co
356d0 6e 73 74 20 63 68 61 72 20 2a 7a 4e 65 77 29 3b  nst char *zNew);
356e0 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
356f0 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61 62  REF: Virtual Tab
35700 6c 65 20 49 6e 64 65 78 69 6e 67 20 49 6e 66 6f  le Indexing Info
35710 72 6d 61 74 69 6f 6e 20 7b 46 31 38 31 30 30 7d  rmation {F18100}
35720 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71  .** KEYWORDS: sq
35730 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f  lite3_index_info
35740 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
35750 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73 74  e3_index_info st
35760 72 75 63 74 75 72 65 20 61 6e 64 20 69 74 73 20  ructure and its 
35770 73 75 62 73 74 72 75 63 74 75 72 65 73 20 69 73  substructures is
35780 20 75 73 65 64 20 74 6f 0a 2a 2a 20 70 61 73 73   used to.** pass
35790 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 6e 74   information int
357a0 6f 20 61 6e 64 20 72 65 63 65 69 76 65 20 74 68  o and receive th
357b0 65 20 72 65 70 6c 79 20 66 72 6f 6d 20 74 68 65  e reply from the
357c0 20 78 42 65 73 74 49 6e 64 65 78 0a 2a 2a 20 6d   xBestIndex.** m
357d0 65 74 68 6f 64 20 6f 66 20 61 6e 20 73 71 6c 69  ethod of an sqli
357e0 74 65 33 5f 6d 6f 64 75 6c 65 2e 20 20 54 68 65  te3_module.  The
357f0 20 66 69 65 6c 64 73 20 75 6e 64 65 72 20 2a 2a   fields under **
35800 49 6e 70 75 74 73 2a 2a 20 61 72 65 20 74 68 65  Inputs** are the
35810 0a 2a 2a 20 69 6e 70 75 74 73 20 74 6f 20 78 42  .** inputs to xB
35820 65 73 74 49 6e 64 65 78 20 61 6e 64 20 61 72 65  estIndex and are
35830 20 72 65 61 64 2d 6f 6e 6c 79 2e 20 20 78 42 65   read-only.  xBe
35840 73 74 49 6e 64 65 78 20 69 6e 73 65 72 74 73 20  stIndex inserts 
35850 69 74 73 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69  its.** results i
35860 6e 74 6f 20 74 68 65 20 2a 2a 4f 75 74 70 75 74  nto the **Output
35870 73 2a 2a 20 66 69 65 6c 64 73 2e 0a 2a 2a 0a 2a  s** fields..**.*
35880 2a 20 54 68 65 20 61 43 6f 6e 73 74 72 61 69 6e  * The aConstrain
35890 74 5b 5d 20 61 72 72 61 79 20 72 65 63 6f 72 64  t[] array record
358a0 73 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 63  s WHERE clause c
358b0 6f 6e 73 74 72 61 69 6e 74 73 20 6f 66 20 74 68  onstraints of th
358c0 65 0a 2a 2a 20 66 6f 72 6d 3a 0a 2a 2a 0a 2a 2a  e.** form:.**.**
358d0 20 20 20 20 20 20 20 20 20 63 6f 6c 75 6d 6e 20           column 
358e0 4f 50 20 65 78 70 72 0a 2a 2a 0a 2a 2a 20 57 68  OP expr.**.** Wh
358f0 65 72 65 20 4f 50 20 69 73 20 3d 2c 20 26 6c 74  ere OP is =, &lt
35900 3b 2c 20 26 6c 74 3b 3d 2c 20 26 67 74 3b 2c 20  ;, &lt;=, &gt;, 
35910 6f 72 20 26 67 74 3b 3d 2e 20 20 0a 2a 2a 20 54  or &gt;=.  .** T
35920 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 6f 70  he particular op
35930 65 72 61 74 6f 72 20 69 73 20 73 74 6f 72 65 64  erator is stored
35940 0a 2a 2a 20 69 6e 20 61 43 6f 6e 73 74 72 61 69  .** in aConstrai
35950 6e 74 5b 5d 2e 6f 70 2e 20 20 54 68 65 20 69 6e  nt[].op.  The in
35960 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d  dex of the colum
35970 6e 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 0a  n is stored in .
35980 2a 2a 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d  ** aConstraint[]
35990 2e 69 43 6f 6c 75 6d 6e 2e 20 20 61 43 6f 6e 73  .iColumn.  aCons
359a0 74 72 61 69 6e 74 5b 5d 2e 75 73 61 62 6c 65 20  traint[].usable 
359b0 69 73 20 54 52 55 45 20 69 66 20 74 68 65 0a 2a  is TRUE if the.*
359c0 2a 20 65 78 70 72 20 6f 6e 20 74 68 65 20 72 69  * expr on the ri
359d0 67 68 74 2d 68 61 6e 64 20 73 69 64 65 20 63 61  ght-hand side ca
359e0 6e 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 28  n be evaluated (
359f0 61 6e 64 20 74 68 75 73 20 74 68 65 20 63 6f 6e  and thus the con
35a00 73 74 72 61 69 6e 74 0a 2a 2a 20 69 73 20 75 73  straint.** is us
35a10 61 62 6c 65 29 20 61 6e 64 20 66 61 6c 73 65 20  able) and false 
35a20 69 66 20 69 74 20 63 61 6e 6e 6f 74 2e 0a 2a 2a  if it cannot..**
35a30 0a 2a 2a 20 54 68 65 20 6f 70 74 69 6d 69 7a 65  .** The optimize
35a40 72 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  r automatically 
35a50 69 6e 76 65 72 74 73 20 74 65 72 6d 73 20 6f 66  inverts terms of
35a60 20 74 68 65 20 66 6f 72 6d 20 22 65 78 70 72 20   the form "expr 
35a70 4f 50 20 63 6f 6c 75 6d 6e 22 0a 2a 2a 20 61 6e  OP column".** an
35a80 64 20 6d 61 6b 65 73 20 6f 74 68 65 72 20 73 69  d makes other si
35a90 6d 70 6c 69 66 69 63 61 74 69 6f 6e 73 20 74 6f  mplifications to
35aa0 20 74 68 65 20 57 48 45 52 45 20 63 6c 61 75 73   the WHERE claus
35ab0 65 20 69 6e 20 61 6e 20 61 74 74 65 6d 70 74 20  e in an attempt 
35ac0 74 6f 0a 2a 2a 20 67 65 74 20 61 73 20 6d 61 6e  to.** get as man
35ad0 79 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 74  y WHERE clause t
35ae0 65 72 6d 73 20 69 6e 74 6f 20 74 68 65 20 66 6f  erms into the fo
35af0 72 6d 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 61  rm shown above a
35b00 73 20 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a 20 54  s possible..** T
35b10 68 65 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d  he aConstraint[]
35b20 20 61 72 72 61 79 20 6f 6e 6c 79 20 72 65 70 6f   array only repo
35b30 72 74 73 20 57 48 45 52 45 20 63 6c 61 75 73 65  rts WHERE clause
35b40 20 74 65 72 6d 73 20 69 6e 20 74 68 65 20 63 6f   terms in the co
35b50 72 72 65 63 74 0a 2a 2a 20 66 6f 72 6d 20 74 68  rrect.** form th
35b60 61 74 20 72 65 66 65 72 20 74 6f 20 74 68 65 20  at refer to the 
35b70 70 61 72 74 69 63 75 6c 61 72 20 76 69 72 74 75  particular virtu
35b80 61 6c 20 74 61 62 6c 65 20 62 65 69 6e 67 20 71  al table being q
35b90 75 65 72 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e  ueried..**.** In
35ba0 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20  formation about 
35bb0 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61  the ORDER BY cla
35bc0 75 73 65 20 69 73 20 73 74 6f 72 65 64 20 69 6e  use is stored in
35bd0 20 61 4f 72 64 65 72 42 79 5b 5d 2e 0a 2a 2a 20   aOrderBy[]..** 
35be0 45 61 63 68 20 74 65 72 6d 20 6f 66 20 61 4f 72  Each term of aOr
35bf0 64 65 72 42 79 20 72 65 63 6f 72 64 73 20 61 20  derBy records a 
35c00 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 4f 52  column of the OR
35c10 44 45 52 20 42 59 20 63 6c 61 75 73 65 2e 0a 2a  DER BY clause..*
35c20 2a 0a 2a 2a 20 54 68 65 20 78 42 65 73 74 49 6e  *.** The xBestIn
35c30 64 65 78 20 6d 65 74 68 6f 64 20 6d 75 73 74 20  dex method must 
35c40 66 69 6c 6c 20 61 43 6f 6e 73 74 72 61 69 6e 74  fill aConstraint
35c50 55 73 61 67 65 5b 5d 20 77 69 74 68 20 69 6e 66  Usage[] with inf
35c60 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75  ormation.** abou
35c70 74 20 77 68 61 74 20 70 61 72 61 6d 65 74 65 72  t what parameter
35c80 73 20 74 6f 20 70 61 73 73 20 74 6f 20 78 46 69  s to pass to xFi
35c90 6c 74 65 72 2e 20 20 49 66 20 61 72 67 76 49 6e  lter.  If argvIn
35ca0 64 65 78 3e 30 20 74 68 65 6e 0a 2a 2a 20 74 68  dex>0 then.** th
35cb0 65 20 72 69 67 68 74 2d 68 61 6e 64 20 73 69 64  e right-hand sid
35cc0 65 20 6f 66 20 74 68 65 20 63 6f 72 72 65 73 70  e of the corresp
35cd0 6f 6e 64 69 6e 67 20 61 43 6f 6e 73 74 72 61 69  onding aConstrai
35ce0 6e 74 5b 5d 20 69 73 20 65 76 61 6c 75 61 74 65  nt[] is evaluate
35cf0 64 0a 2a 2a 20 61 6e 64 20 62 65 63 6f 6d 65 73  d.** and becomes
35d00 20 74 68 65 20 61 72 67 76 49 6e 64 65 78 2d 74   the argvIndex-t
35d10 68 20 65 6e 74 72 79 20 69 6e 20 61 72 67 76 2e  h entry in argv.
35d20 20 20 49 66 20 61 43 6f 6e 73 74 72 61 69 6e 74    If aConstraint
35d30 55 73 61 67 65 5b 5d 2e 6f 6d 69 74 0a 2a 2a 20  Usage[].omit.** 
35d40 69 73 20 74 72 75 65 2c 20 74 68 65 6e 20 74 68  is true, then th
35d50 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20  e constraint is 
35d60 61 73 73 75 6d 65 64 20 74 6f 20 62 65 20 66 75  assumed to be fu
35d70 6c 6c 79 20 68 61 6e 64 6c 65 64 20 62 79 20 74  lly handled by t
35d80 68 65 0a 2a 2a 20 76 69 72 74 75 61 6c 20 74 61  he.** virtual ta
35d90 62 6c 65 20 61 6e 64 20 69 73 20 6e 6f 74 20 63  ble and is not c
35da0 68 65 63 6b 65 64 20 61 67 61 69 6e 20 62 79 20  hecked again by 
35db0 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  SQLite..**.** Th
35dc0 65 20 69 64 78 4e 75 6d 20 61 6e 64 20 69 64 78  e idxNum and idx
35dd0 50 74 72 20 76 61 6c 75 65 73 20 61 72 65 20 72  Ptr values are r
35de0 65 63 6f 72 64 65 64 20 61 6e 64 20 70 61 73 73  ecorded and pass
35df0 65 64 20 69 6e 74 6f 20 78 46 69 6c 74 65 72 2e  ed into xFilter.
35e00 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65  .** sqlite3_free
35e10 28 29 20 69 73 20 75 73 65 64 20 74 6f 20 66 72  () is used to fr
35e20 65 65 20 69 64 78 50 74 72 20 69 66 20 6e 65 65  ee idxPtr if nee
35e30 64 54 6f 46 72 65 65 49 64 78 50 74 72 20 69 73  dToFreeIdxPtr is
35e40 20 74 72 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   true..**.** The
35e50 20 6f 72 64 65 72 42 79 43 6f 6e 73 75 6d 65 64   orderByConsumed
35e60 20 6d 65 61 6e 73 20 74 68 61 74 20 6f 75 74 70   means that outp
35e70 75 74 20 66 72 6f 6d 20 78 46 69 6c 74 65 72 20  ut from xFilter 
35e80 77 69 6c 6c 20 6f 63 63 75 72 20 69 6e 0a 2a 2a  will occur in.**
35e90 20 74 68 65 20 63 6f 72 72 65 63 74 20 6f 72 64   the correct ord
35ea0 65 72 20 74 6f 20 73 61 74 69 73 66 79 20 74 68  er to satisfy th
35eb0 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73  e ORDER BY claus
35ec0 65 20 73 6f 20 74 68 61 74 20 6e 6f 20 73 65 70  e so that no sep
35ed0 61 72 61 74 65 0a 2a 2a 20 73 6f 72 74 69 6e 67  arate.** sorting
35ee0 20 73 74 65 70 20 69 73 20 72 65 71 75 69 72 65   step is require
35ef0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 65 73 74  d..**.** The est
35f00 69 6d 61 74 65 64 43 6f 73 74 20 76 61 6c 75 65  imatedCost value
35f10 20 69 73 20 61 6e 20 65 73 74 69 6d 61 74 65 20   is an estimate 
35f20 6f 66 20 74 68 65 20 63 6f 73 74 20 6f 66 20 64  of the cost of d
35f30 6f 69 6e 67 20 74 68 65 0a 2a 2a 20 70 61 72 74  oing the.** part
35f40 69 63 75 6c 61 72 20 6c 6f 6f 6b 75 70 2e 20 20  icular lookup.  
35f50 41 20 66 75 6c 6c 20 73 63 61 6e 20 6f 66 20 61  A full scan of a
35f60 20 74 61 62 6c 65 20 77 69 74 68 20 4e 20 65 6e   table with N en
35f70 74 72 69 65 73 20 73 68 6f 75 6c 64 20 68 61 76  tries should hav
35f80 65 0a 2a 2a 20 61 20 63 6f 73 74 20 6f 66 20 4e  e.** a cost of N
35f90 2e 20 20 41 20 62 69 6e 61 72 79 20 73 65 61 72  .  A binary sear
35fa0 63 68 20 6f 66 20 61 20 74 61 62 6c 65 20 6f 66  ch of a table of
35fb0 20 4e 20 65 6e 74 72 69 65 73 20 73 68 6f 75 6c   N entries shoul
35fc0 64 20 68 61 76 65 20 61 0a 2a 2a 20 63 6f 73 74  d have a.** cost
35fd0 20 6f 66 20 61 70 70 72 6f 78 69 6d 61 74 65 6c   of approximatel
35fe0 79 20 6c 6f 67 28 4e 29 2e 0a 2a 2f 0a 73 74 72  y log(N)..*/.str
35ff0 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65  uct sqlite3_inde
36000 78 5f 69 6e 66 6f 20 7b 0a 20 20 2f 2a 20 49 6e  x_info {.  /* In
36010 70 75 74 73 20 2a 2f 0a 20 20 69 6e 74 20 6e 43  puts */.  int nC
36020 6f 6e 73 74 72 61 69 6e 74 3b 20 20 20 20 20 20  onstraint;      
36030 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f       /* Number o
36040 66 20 65 6e 74 72 69 65 73 20 69 6e 20 61 43 6f  f entries in aCo
36050 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 73 74  nstraint */.  st
36060 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64  ruct sqlite3_ind
36070 65 78 5f 63 6f 6e 73 74 72 61 69 6e 74 20 7b 0a  ex_constraint {.
36080 20 20 20 20 20 69 6e 74 20 69 43 6f 6c 75 6d 6e       int iColumn
36090 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ;              /
360a0 2a 20 43 6f 6c 75 6d 6e 20 6f 6e 20 6c 65 66 74  * Column on left
360b0 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20 63 6f  -hand side of co
360c0 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 20 20  nstraint */.    
360d0 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 6f   unsigned char o
360e0 70 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f  p;         /* Co
360f0 6e 73 74 72 61 69 6e 74 20 6f 70 65 72 61 74 6f  nstraint operato
36100 72 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e  r */.     unsign
36110 65 64 20 63 68 61 72 20 75 73 61 62 6c 65 3b 20  ed char usable; 
36120 20 20 20 20 2f 2a 20 54 72 75 65 20 69 66 20 74      /* True if t
36130 68 69 73 20 63 6f 6e 73 74 72 61 69 6e 74 20 69  his constraint i
36140 73 20 75 73 61 62 6c 65 20 2a 2f 0a 20 20 20 20  s usable */.    
36150 20 69 6e 74 20 69 54 65 72 6d 4f 66 66 73 65 74   int iTermOffset
36160 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 55 73  ;          /* Us
36170 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 2d 20  ed internally - 
36180 78 42 65 73 74 49 6e 64 65 78 20 73 68 6f 75 6c  xBestIndex shoul
36190 64 20 69 67 6e 6f 72 65 20 2a 2f 0a 20 20 7d 20  d ignore */.  } 
361a0 2a 61 43 6f 6e 73 74 72 61 69 6e 74 3b 20 20 20  *aConstraint;   
361b0 20 20 20 20 20 20 20 20 20 2f 2a 20 54 61 62 6c           /* Tabl
361c0 65 20 6f 66 20 57 48 45 52 45 20 63 6c 61 75 73  e of WHERE claus
361d0 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 2a 2f  e constraints */
361e0 0a 20 20 69 6e 74 20 6e 4f 72 64 65 72 42 79 3b  .  int nOrderBy;
361f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
36200 20 4e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73   Number of terms
36210 20 69 6e 20 74 68 65 20 4f 52 44 45 52 20 42 59   in the ORDER BY
36220 20 63 6c 61 75 73 65 20 2a 2f 0a 20 20 73 74 72   clause */.  str
36230 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65  uct sqlite3_inde
36240 78 5f 6f 72 64 65 72 62 79 20 7b 0a 20 20 20 20  x_orderby {.    
36250 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 20 20   int iColumn;   
36260 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f             /* Co
36270 6c 75 6d 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a 20  lumn number */. 
36280 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61      unsigned cha
36290 72 20 64 65 73 63 3b 20 20 20 20 20 20 20 2f 2a  r desc;       /*
362a0 20 54 72 75 65 20 66 6f 72 20 44 45 53 43 2e 20   True for DESC. 
362b0 20 46 61 6c 73 65 20 66 6f 72 20 41 53 43 2e 20   False for ASC. 
362c0 2a 2f 0a 20 20 7d 20 2a 61 4f 72 64 65 72 42 79  */.  } *aOrderBy
362d0 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ;               
362e0 2f 2a 20 54 68 65 20 4f 52 44 45 52 20 42 59 20  /* The ORDER BY 
362f0 63 6c 61 75 73 65 20 2a 2f 0a 0a 20 20 2f 2a 20  clause */..  /* 
36300 4f 75 74 70 75 74 73 20 2a 2f 0a 20 20 73 74 72  Outputs */.  str
36310 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65  uct sqlite3_inde
36320 78 5f 63 6f 6e 73 74 72 61 69 6e 74 5f 75 73 61  x_constraint_usa
36330 67 65 20 7b 0a 20 20 20 20 69 6e 74 20 61 72 67  ge {.    int arg
36340 76 49 6e 64 65 78 3b 20 20 20 20 20 20 20 20 20  vIndex;         
36350 20 20 2f 2a 20 69 66 20 3e 30 2c 20 63 6f 6e 73    /* if >0, cons
36360 74 72 61 69 6e 74 20 69 73 20 70 61 72 74 20 6f  traint is part o
36370 66 20 61 72 67 76 20 74 6f 20 78 46 69 6c 74 65  f argv to xFilte
36380 72 20 2a 2f 0a 20 20 20 20 75 6e 73 69 67 6e 65  r */.    unsigne
36390 64 20 63 68 61 72 20 6f 6d 69 74 3b 20 20 20 20  d char omit;    
363a0 20 20 2f 2a 20 44 6f 20 6e 6f 74 20 63 6f 64 65    /* Do not code
363b0 20 61 20 74 65 73 74 20 66 6f 72 20 74 68 69 73   a test for this
363c0 20 63 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20   constraint */. 
363d0 20 7d 20 2a 61 43 6f 6e 73 74 72 61 69 6e 74 55   } *aConstraintU
363e0 73 61 67 65 3b 0a 20 20 69 6e 74 20 69 64 78 4e  sage;.  int idxN
363f0 75 6d 3b 20 20 20 20 20 20 20 20 20 20 20 20 20  um;             
36400 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 75 73 65     /* Number use
36410 64 20 74 6f 20 69 64 65 6e 74 69 66 79 20 74 68  d to identify th
36420 65 20 69 6e 64 65 78 20 2a 2f 0a 20 20 63 68 61  e index */.  cha
36430 72 20 2a 69 64 78 53 74 72 3b 20 20 20 20 20 20  r *idxStr;      
36440 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 69 6e          /* Strin
36450 67 2c 20 70 6f 73 73 69 62 6c 79 20 6f 62 74 61  g, possibly obta
36460 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65  ined from sqlite
36470 33 5f 6d 61 6c 6c 6f 63 20 2a 2f 0a 20 20 69 6e  3_malloc */.  in
36480 74 20 6e 65 65 64 54 6f 46 72 65 65 49 64 78 53  t needToFreeIdxS
36490 74 72 3b 20 20 20 20 20 20 2f 2a 20 46 72 65 65  tr;      /* Free
364a0 20 69 64 78 53 74 72 20 75 73 69 6e 67 20 73 71   idxStr using sq
364b0 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 66 20  lite3_free() if 
364c0 74 72 75 65 20 2a 2f 0a 20 20 69 6e 74 20 6f 72  true */.  int or
364d0 64 65 72 42 79 43 6f 6e 73 75 6d 65 64 3b 20 20  derByConsumed;  
364e0 20 20 20 20 20 2f 2a 20 54 72 75 65 20 69 66 20       /* True if 
364f0 6f 75 74 70 75 74 20 69 73 20 61 6c 72 65 61 64  output is alread
36500 79 20 6f 72 64 65 72 65 64 20 2a 2f 0a 20 20 64  y ordered */.  d
36510 6f 75 62 6c 65 20 65 73 74 69 6d 61 74 65 64 43  ouble estimatedC
36520 6f 73 74 3b 20 20 20 20 20 20 2f 2a 20 45 73 74  ost;      /* Est
36530 69 6d 61 74 65 64 20 63 6f 73 74 20 6f 66 20 75  imated cost of u
36540 73 69 6e 67 20 74 68 69 73 20 69 6e 64 65 78 20  sing this index 
36550 2a 2f 0a 7d 3b 0a 23 64 65 66 69 6e 65 20 53 51  */.};.#define SQ
36560 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54  LITE_INDEX_CONST
36570 52 41 49 4e 54 5f 45 51 20 20 20 20 32 0a 23 64  RAINT_EQ    2.#d
36580 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44  efine SQLITE_IND
36590 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 47 54  EX_CONSTRAINT_GT
365a0 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51      4.#define SQ
365b0 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54  LITE_INDEX_CONST
365c0 52 41 49 4e 54 5f 4c 45 20 20 20 20 38 0a 23 64  RAINT_LE    8.#d
365d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44  efine SQLITE_IND
365e0 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4c 54  EX_CONSTRAINT_LT
365f0 20 20 20 20 31 36 0a 23 64 65 66 69 6e 65 20 53      16.#define S
36600 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53  QLITE_INDEX_CONS
36610 54 52 41 49 4e 54 5f 47 45 20 20 20 20 33 32 0a  TRAINT_GE    32.
36620 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
36630 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  NDEX_CONSTRAINT_
36640 4d 41 54 43 48 20 36 34 0a 0a 2f 2a 0a 2a 2a 20  MATCH 64../*.** 
36650 43 41 50 49 33 52 45 46 3a 20 52 65 67 69 73 74  CAPI3REF: Regist
36660 65 72 20 41 20 56 69 72 74 75 61 6c 20 54 61 62  er A Virtual Tab
36670 6c 65 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le Implementatio
36680 6e 20 7b 46 31 38 32 30 30 7d 0a 2a 2a 0a 2a 2a  n {F18200}.**.**
36690 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   This routine is
366a0 20 75 73 65 64 20 74 6f 20 72 65 67 69 73 74 65   used to registe
366b0 72 20 61 20 6e 65 77 20 6d 6f 64 75 6c 65 20 6e  r a new module n
366c0 61 6d 65 20 77 69 74 68 20 61 6e 20 53 51 4c 69  ame with an SQLi
366d0 74 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  te.** connection
366e0 2e 20 20 4d 6f 64 75 6c 65 20 6e 61 6d 65 73 20  .  Module names 
366f0 6d 75 73 74 20 62 65 20 72 65 67 69 73 74 65 72  must be register
36700 65 64 20 62 65 66 6f 72 65 20 63 72 65 61 74 69  ed before creati
36710 6e 67 20 6e 65 77 0a 2a 2a 20 76 69 72 74 75 61  ng new.** virtua
36720 6c 20 74 61 62 6c 65 73 20 6f 6e 20 74 68 65 20  l tables on the 
36730 6d 6f 64 75 6c 65 2c 20 6f 72 20 62 65 66 6f 72  module, or befor
36740 65 20 75 73 69 6e 67 20 70 72 65 65 78 69 73 74  e using preexist
36750 69 6e 67 20 76 69 72 74 75 61 6c 0a 2a 2a 20 74  ing virtual.** t
36760 61 62 6c 65 73 20 6f 66 20 74 68 65 20 6d 6f 64  ables of the mod
36770 75 6c 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ule..*/.int sqli
36780 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c  te3_create_modul
36790 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  e(.  sqlite3 *db
367a0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
367b0 2f 2a 20 53 51 4c 69 74 65 20 63 6f 6e 6e 65 63  /* SQLite connec
367c0 74 69 6f 6e 20 74 6f 20 72 65 67 69 73 74 65 72  tion to register
367d0 20 6d 6f 64 75 6c 65 20 77 69 74 68 20 2a 2f 0a   module with */.
367e0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e    const char *zN
367f0 61 6d 65 2c 20 20 20 20 20 20 20 20 20 2f 2a 20  ame,         /* 
36800 4e 61 6d 65 20 6f 66 20 74 68 65 20 6d 6f 64 75  Name of the modu
36810 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 73 71  le */.  const sq
36820 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 2c 20  lite3_module *, 
36830 20 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f     /* Methods fo
36840 72 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a  r the module */.
36850 20 20 76 6f 69 64 20 2a 20 20 20 20 20 20 20 20    void *        
36860 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
36870 43 6c 69 65 6e 74 20 64 61 74 61 20 66 6f 72 20  Client data for 
36880 78 43 72 65 61 74 65 2f 78 43 6f 6e 6e 65 63 74  xCreate/xConnect
36890 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.);../*.** CA
368a0 50 49 33 52 45 46 3a 20 52 65 67 69 73 74 65 72  PI3REF: Register
368b0 20 41 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65   A Virtual Table
368c0 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   Implementation 
368d0 7b 46 31 38 32 31 30 7d 0a 2a 2a 0a 2a 2a 20 54  {F18210}.**.** T
368e0 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 69  his routine is i
368f0 64 65 6e 74 69 63 61 6c 20 74 6f 20 74 68 65 20  dentical to the 
36900 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d  sqlite3_create_m
36910 6f 64 75 6c 65 28 29 20 6d 65 74 68 6f 64 20 61  odule() method a
36920 62 6f 76 65 2c 0a 2a 2a 20 65 78 63 65 70 74 20  bove,.** except 
36930 74 68 61 74 20 69 74 20 61 6c 6c 6f 77 73 20 61  that it allows a
36940 20 64 65 73 74 72 75 63 74 6f 72 20 66 75 6e 63   destructor func
36950 74 69 6f 6e 20 74 6f 20 62 65 20 73 70 65 63 69  tion to be speci
36960 66 69 65 64 2e 20 49 74 20 69 73 0a 2a 2a 20 65  fied. It is.** e
36970 76 65 6e 20 6d 6f 72 65 20 65 78 70 65 72 69 6d  ven more experim
36980 65 6e 74 61 6c 20 74 68 61 6e 20 74 68 65 20 72  ental than the r
36990 65 73 74 20 6f 66 20 74 68 65 20 76 69 72 74 75  est of the virtu
369a0 61 6c 20 74 61 62 6c 65 73 20 41 50 49 2e 0a 2a  al tables API..*
369b0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  /.int sqlite3_cr
369c0 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 0a  eate_module_v2(.
369d0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
369e0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
369f0 53 51 4c 69 74 65 20 63 6f 6e 6e 65 63 74 69 6f  SQLite connectio
36a00 6e 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d 6f  n to register mo
36a10 64 75 6c 65 20 77 69 74 68 20 2a 2f 0a 20 20 63  dule with */.  c
36a20 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
36a30 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d  ,         /* Nam
36a40 65 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20  e of the module 
36a50 2a 2f 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69 74  */.  const sqlit
36a60 65 33 5f 6d 6f 64 75 6c 65 20 2a 2c 20 20 20 20  e3_module *,    
36a70 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 74  /* Methods for t
36a80 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 76  he module */.  v
36a90 6f 69 64 20 2a 2c 20 20 20 20 20 20 20 20 20 20  oid *,          
36aa0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6c 69            /* Cli
36ab0 65 6e 74 20 64 61 74 61 20 66 6f 72 20 78 43 72  ent data for xCr
36ac0 65 61 74 65 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f  eate/xConnect */
36ad0 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f  .  void(*xDestro
36ae0 79 29 28 76 6f 69 64 2a 29 20 20 20 20 20 2f 2a  y)(void*)     /*
36af0 20 4d 6f 64 75 6c 65 20 64 65 73 74 72 75 63 74   Module destruct
36b00 6f 72 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 29  or function */.)
36b10 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
36b20 46 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65  F: Virtual Table
36b30 20 49 6e 73 74 61 6e 63 65 20 4f 62 6a 65 63 74   Instance Object
36b40 20 7b 46 31 38 30 31 30 7d 0a 2a 2a 20 4b 45 59   {F18010}.** KEY
36b50 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76  WORDS: sqlite3_v
36b60 74 61 62 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20  tab.**.** Every 
36b70 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  module implement
36b80 61 74 69 6f 6e 20 75 73 65 73 20 61 20 73 75 62  ation uses a sub
36b90 63 6c 61 73 73 20 6f 66 20 74 68 65 20 66 6f 6c  class of the fol
36ba0 6c 6f 77 69 6e 67 20 73 74 72 75 63 74 75 72 65  lowing structure
36bb0 0a 2a 2a 20 74 6f 20 64 65 73 63 72 69 62 65 20  .** to describe 
36bc0 61 20 70 61 72 74 69 63 75 6c 61 72 20 69 6e 73  a particular ins
36bd0 74 61 6e 63 65 20 6f 66 20 74 68 65 20 6d 6f 64  tance of the mod
36be0 75 6c 65 2e 20 20 45 61 63 68 20 73 75 62 63 6c  ule.  Each subcl
36bf0 61 73 73 20 77 69 6c 6c 0a 2a 2a 20 62 65 20 74  ass will.** be t
36c00 61 69 6c 6f 72 65 64 20 74 6f 20 74 68 65 20 73  ailored to the s
36c10 70 65 63 69 66 69 63 20 6e 65 65 64 73 20 6f 66  pecific needs of
36c20 20 74 68 65 20 6d 6f 64 75 6c 65 20 69 6d 70 6c   the module impl
36c30 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 20 54 68  ementation.   Th
36c40 65 0a 2a 2a 20 70 75 72 70 6f 73 65 20 6f 66 20  e.** purpose of 
36c50 74 68 69 73 20 73 75 70 65 72 63 6c 61 73 73 20  this superclass 
36c60 69 73 20 74 6f 20 64 65 66 69 6e 65 20 63 65 72  is to define cer
36c70 74 61 69 6e 20 66 69 65 6c 64 73 20 74 68 61 74  tain fields that
36c80 20 61 72 65 20 63 6f 6d 6d 6f 6e 0a 2a 2a 20 74   are common.** t
36c90 6f 20 61 6c 6c 20 6d 6f 64 75 6c 65 20 69 6d 70  o all module imp
36ca0 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2e 0a 2a 2a  lementations..**
36cb0 0a 2a 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c  .** Virtual tabl
36cc0 65 73 20 6d 65 74 68 6f 64 73 20 63 61 6e 20 73  es methods can s
36cd0 65 74 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73  et an error mess
36ce0 61 67 65 20 62 79 20 61 73 73 69 67 6e 69 6e 67  age by assigning
36cf0 20 61 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 62 74   a.** string obt
36d00 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74  ained from sqlit
36d10 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 74 6f 20  e3_mprintf() to 
36d20 7a 45 72 72 4d 73 67 2e 20 20 54 68 65 20 6d 65  zErrMsg.  The me
36d30 74 68 6f 64 20 73 68 6f 75 6c 64 0a 2a 2a 20 74  thod should.** t
36d40 61 6b 65 20 63 61 72 65 20 74 68 61 74 20 61 6e  ake care that an
36d50 79 20 70 72 69 6f 72 20 73 74 72 69 6e 67 20 69  y prior string i
36d60 73 20 66 72 65 65 64 20 62 79 20 61 20 63 61 6c  s freed by a cal
36d70 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65  l to sqlite3_fre
36d80 65 28 29 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20  e().** prior to 
36d90 61 73 73 69 67 6e 69 6e 67 20 61 20 6e 65 77 20  assigning a new 
36da0 73 74 72 69 6e 67 20 74 6f 20 7a 45 72 72 4d 73  string to zErrMs
36db0 67 2e 20 20 41 66 74 65 72 20 74 68 65 20 65 72  g.  After the er
36dc0 72 6f 72 20 6d 65 73 73 61 67 65 0a 2a 2a 20 69  ror message.** i
36dd0 73 20 64 65 6c 69 76 65 72 65 64 20 75 70 20 74  s delivered up t
36de0 6f 20 74 68 65 20 63 6c 69 65 6e 74 20 61 70 70  o the client app
36df0 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65 20 73 74  lication, the st
36e00 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 61 75 74  ring will be aut
36e10 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 66 72  omatically.** fr
36e20 65 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 66  eed by sqlite3_f
36e30 72 65 65 28 29 20 61 6e 64 20 74 68 65 20 7a 45  ree() and the zE
36e40 72 72 4d 73 67 20 66 69 65 6c 64 20 77 69 6c 6c  rrMsg field will
36e50 20 62 65 20 7a 65 72 6f 65 64 2e 20 20 4e 6f 74   be zeroed.  Not
36e60 65 0a 2a 2a 20 74 68 61 74 20 73 71 6c 69 74 65  e.** that sqlite
36e70 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20  3_mprintf() and 
36e80 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 61  sqlite3_free() a
36e90 72 65 20 75 73 65 64 20 6f 6e 20 74 68 65 20 7a  re used on the z
36ea0 45 72 72 4d 73 67 20 66 69 65 6c 64 0a 2a 2a 20  ErrMsg field.** 
36eb0 73 69 6e 63 65 20 76 69 72 74 75 61 6c 20 74 61  since virtual ta
36ec0 62 6c 65 73 20 61 72 65 20 63 6f 6d 6d 6f 6e 6c  bles are commonl
36ed0 79 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 69 6e  y implemented in
36ee0 20 6c 6f 61 64 61 62 6c 65 20 65 78 74 65 6e 73   loadable extens
36ef0 69 6f 6e 73 20 77 68 69 63 68 0a 2a 2a 20 64 6f  ions which.** do
36f00 20 6e 6f 74 20 68 61 76 65 20 61 63 63 65 73 73   not have access
36f10 20 74 6f 20 73 71 6c 69 74 65 33 4d 50 72 69 6e   to sqlite3MPrin
36f20 74 66 28 29 20 6f 72 20 73 71 6c 69 74 65 33 46  tf() or sqlite3F
36f30 72 65 65 28 29 2e 0a 2a 2f 0a 73 74 72 75 63 74  ree()..*/.struct
36f40 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 7b 0a   sqlite3_vtab {.
36f50 20 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f    const sqlite3_
36f60 6d 6f 64 75 6c 65 20 2a 70 4d 6f 64 75 6c 65 3b  module *pModule;
36f70 20 20 2f 2a 20 54 68 65 20 6d 6f 64 75 6c 65 20    /* The module 
36f80 66 6f 72 20 74 68 69 73 20 76 69 72 74 75 61 6c  for this virtual
36f90 20 74 61 62 6c 65 20 2a 2f 0a 20 20 69 6e 74 20   table */.  int 
36fa0 6e 52 65 66 3b 20 20 20 20 20 20 20 20 20 20 20  nRef;           
36fb0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 55              /* U
36fc0 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 2a  sed internally *
36fd0 2f 0a 20 20 63 68 61 72 20 2a 7a 45 72 72 4d 73  /.  char *zErrMs
36fe0 67 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  g;              
36ff0 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 65 73      /* Error mes
37000 73 61 67 65 20 66 72 6f 6d 20 73 71 6c 69 74 65  sage from sqlite
37010 33 5f 6d 70 72 69 6e 74 66 28 29 20 2a 2f 0a 20  3_mprintf() */. 
37020 20 2f 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c   /* Virtual tabl
37030 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
37040 73 20 77 69 6c 6c 20 74 79 70 69 63 61 6c 6c 79  s will typically
37050 20 61 64 64 20 61 64 64 69 74 69 6f 6e 61 6c 20   add additional 
37060 66 69 65 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  fields */.};../*
37070 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69  .** CAPI3REF: Vi
37080 72 74 75 61 6c 20 54 61 62 6c 65 20 43 75 72 73  rtual Table Curs
37090 6f 72 20 4f 62 6a 65 63 74 20 20 7b 46 31 38 30  or Object  {F180
370a0 32 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  20}.** KEYWORDS:
370b0 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75   sqlite3_vtab_cu
370c0 72 73 6f 72 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79  rsor.**.** Every
370d0 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e   module implemen
370e0 74 61 74 69 6f 6e 20 75 73 65 73 20 61 20 73 75  tation uses a su
370f0 62 63 6c 61 73 73 20 6f 66 20 74 68 65 20 66 6f  bclass of the fo
37100 6c 6c 6f 77 69 6e 67 20 73 74 72 75 63 74 75 72  llowing structur
37110 65 0a 2a 2a 20 74 6f 20 64 65 73 63 72 69 62 65  e.** to describe
37120 20 63 75 72 73 6f 72 73 20 74 68 61 74 20 70 6f   cursors that po
37130 69 6e 74 20 69 6e 74 6f 20 74 68 65 20 76 69 72  int into the vir
37140 74 75 61 6c 20 74 61 62 6c 65 20 61 6e 64 20 61  tual table and a
37150 72 65 20 75 73 65 64 0a 2a 2a 20 74 6f 20 6c 6f  re used.** to lo
37160 6f 70 20 74 68 72 6f 75 67 68 20 74 68 65 20 76  op through the v
37170 69 72 74 75 61 6c 20 74 61 62 6c 65 2e 20 20 43  irtual table.  C
37180 75 72 73 6f 72 73 20 61 72 65 20 63 72 65 61 74  ursors are creat
37190 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  ed using the.** 
371a0 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6f 66 20  xOpen method of 
371b0 74 68 65 20 6d 6f 64 75 6c 65 2e 20 20 45 61 63  the module.  Eac
371c0 68 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65  h module impleme
371d0 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 64 65 66  ntation will def
371e0 69 6e 65 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65  ine.** the conte
371f0 6e 74 20 6f 66 20 61 20 63 75 72 73 6f 72 20 73  nt of a cursor s
37200 74 72 75 63 74 75 72 65 20 74 6f 20 73 75 69 74  tructure to suit
37210 20 69 74 73 20 6f 77 6e 20 6e 65 65 64 73 2e 0a   its own needs..
37220 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 75 70 65 72  **.** This super
37230 63 6c 61 73 73 20 65 78 69 73 74 73 20 69 6e 20  class exists in 
37240 6f 72 64 65 72 20 74 6f 20 64 65 66 69 6e 65 20  order to define 
37250 66 69 65 6c 64 73 20 6f 66 20 74 68 65 20 63 75  fields of the cu
37260 72 73 6f 72 20 74 68 61 74 0a 2a 2a 20 61 72 65  rsor that.** are
37270 20 63 6f 6d 6d 6f 6e 20 74 6f 20 61 6c 6c 20 69   common to all i
37280 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2e 0a  mplementations..
37290 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  */.struct sqlite
372a0 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 7b 0a  3_vtab_cursor {.
372b0 20 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a    sqlite3_vtab *
372c0 70 56 74 61 62 3b 20 20 20 20 20 20 2f 2a 20 56  pVtab;      /* V
372d0 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6f 66 20  irtual table of 
372e0 74 68 69 73 20 63 75 72 73 6f 72 20 2a 2f 0a 20  this cursor */. 
372f0 20 2f 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c   /* Virtual tabl
37300 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
37310 73 20 77 69 6c 6c 20 74 79 70 69 63 61 6c 6c 79  s will typically
37320 20 61 64 64 20 61 64 64 69 74 69 6f 6e 61 6c 20   add additional 
37330 66 69 65 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  fields */.};../*
37340 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
37350 63 6c 61 72 65 20 54 68 65 20 53 63 68 65 6d 61  clare The Schema
37360 20 4f 66 20 41 20 56 69 72 74 75 61 6c 20 54 61   Of A Virtual Ta
37370 62 6c 65 20 7b 46 31 38 32 38 30 7d 0a 2a 2a 0a  ble {F18280}.**.
37380 2a 2a 20 54 68 65 20 78 43 72 65 61 74 65 20 61  ** The xCreate a
37390 6e 64 20 78 43 6f 6e 6e 65 63 74 20 6d 65 74 68  nd xConnect meth
373a0 6f 64 73 20 6f 66 20 61 20 6d 6f 64 75 6c 65 20  ods of a module 
373b0 75 73 65 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  use the followin
373c0 67 20 41 50 49 0a 2a 2a 20 74 6f 20 64 65 63 6c  g API.** to decl
373d0 61 72 65 20 74 68 65 20 66 6f 72 6d 61 74 20 28  are the format (
373e0 74 68 65 20 6e 61 6d 65 73 20 61 6e 64 20 64 61  the names and da
373f0 74 61 74 79 70 65 73 20 6f 66 20 74 68 65 20 63  tatypes of the c
37400 6f 6c 75 6d 6e 73 29 20 6f 66 0a 2a 2a 20 74 68  olumns) of.** th
37410 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73  e virtual tables
37420 20 74 68 65 79 20 69 6d 70 6c 65 6d 65 6e 74 2e   they implement.
37430 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
37440 64 65 63 6c 61 72 65 5f 76 74 61 62 28 73 71 6c  declare_vtab(sql
37450 69 74 65 33 2a 2c 20 63 6f 6e 73 74 20 63 68 61  ite3*, const cha
37460 72 20 2a 7a 43 72 65 61 74 65 54 61 62 6c 65 29  r *zCreateTable)
37470 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
37480 46 3a 20 4f 76 65 72 6c 6f 61 64 20 41 20 46 75  F: Overload A Fu
37490 6e 63 74 69 6f 6e 20 46 6f 72 20 41 20 56 69 72  nction For A Vir
374a0 74 75 61 6c 20 54 61 62 6c 65 20 7b 46 31 38 33  tual Table {F183
374b0 30 30 7d 0a 2a 2a 0a 2a 2a 20 56 69 72 74 75 61  00}.**.** Virtua
374c0 6c 20 74 61 62 6c 65 73 20 63 61 6e 20 70 72 6f  l tables can pro
374d0 76 69 64 65 20 61 6c 74 65 72 6e 61 74 69 76 65  vide alternative
374e0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
374f0 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a   of functions.**
37500 20 75 73 69 6e 67 20 74 68 65 20 78 46 69 6e 64   using the xFind
37510 46 75 6e 63 74 69 6f 6e 20 6d 65 74 68 6f 64 2e  Function method.
37520 20 20 42 75 74 20 67 6c 6f 62 61 6c 20 76 65 72    But global ver
37530 73 69 6f 6e 73 20 6f 66 20 74 68 6f 73 65 20 66  sions of those f
37540 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 6d 75 73 74  unctions.** must
37550 20 65 78 69 73 74 20 69 6e 20 6f 72 64 65 72 20   exist in order 
37560 74 6f 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64  to be overloaded
37570 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49  ..**.** This API
37580 20 6d 61 6b 65 73 20 73 75 72 65 20 61 20 67 6c   makes sure a gl
37590 6f 62 61 6c 20 76 65 72 73 69 6f 6e 20 6f 66 20  obal version of 
375a0 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20  a function with 
375b0 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20  a particular.** 
375c0 6e 61 6d 65 20 61 6e 64 20 6e 75 6d 62 65 72 20  name and number 
375d0 6f 66 20 70 61 72 61 6d 65 74 65 72 73 20 65 78  of parameters ex
375e0 69 73 74 73 2e 20 20 49 66 20 6e 6f 20 73 75 63  ists.  If no suc
375f0 68 20 66 75 6e 63 74 69 6f 6e 20 65 78 69 73 74  h function exist
37600 73 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 69 73  s.** before this
37610 20 41 50 49 20 69 73 20 63 61 6c 6c 65 64 2c 20   API is called, 
37620 61 20 6e 65 77 20 66 75 6e 63 74 69 6f 6e 20 69  a new function i
37630 73 20 63 72 65 61 74 65 64 2e 20 20 54 68 65 20  s created.  The 
37640 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a  implementation.*
37650 2a 20 6f 66 20 74 68 65 20 6e 65 77 20 66 75 6e  * of the new fun
37660 63 74 69 6f 6e 20 61 6c 77 61 79 73 20 63 61 75  ction always cau
37670 73 65 73 20 61 6e 20 65 78 63 65 70 74 69 6f 6e  ses an exception
37680 20 74 6f 20 62 65 20 74 68 72 6f 77 6e 2e 20 20   to be thrown.  
37690 53 6f 0a 2a 2a 20 74 68 65 20 6e 65 77 20 66 75  So.** the new fu
376a0 6e 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 67 6f  nction is not go
376b0 6f 64 20 66 6f 72 20 61 6e 79 74 68 69 6e 67 20  od for anything 
376c0 62 79 20 69 74 73 65 6c 66 2e 20 20 49 74 73 20  by itself.  Its 
376d0 6f 6e 6c 79 0a 2a 2a 20 70 75 72 70 6f 73 65 20  only.** purpose 
376e0 69 73 20 74 6f 20 62 65 20 61 20 70 6c 61 63 65  is to be a place
376f0 2d 68 6f 6c 64 65 72 20 66 75 6e 63 74 69 6f 6e  -holder function
37700 20 74 68 61 74 20 63 61 6e 20 62 65 20 6f 76 65   that can be ove
37710 72 6c 6f 61 64 65 64 0a 2a 2a 20 62 79 20 76 69  rloaded.** by vi
37720 72 74 75 61 6c 20 74 61 62 6c 65 73 2e 0a 2a 2a  rtual tables..**
37730 0a 2a 2a 20 54 68 69 73 20 41 50 49 20 73 68 6f  .** This API sho
37740 75 6c 64 20 62 65 20 63 6f 6e 73 69 64 65 72 65  uld be considere
37750 64 20 70 61 72 74 20 6f 66 20 74 68 65 20 76 69  d part of the vi
37760 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6e 74 65  rtual table inte
37770 72 66 61 63 65 2c 0a 2a 2a 20 77 68 69 63 68 20  rface,.** which 
37780 69 73 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20  is experimental 
37790 61 6e 64 20 73 75 62 6a 65 63 74 20 74 6f 20 63  and subject to c
377a0 68 61 6e 67 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71  hange..*/.int sq
377b0 6c 69 74 65 33 5f 6f 76 65 72 6c 6f 61 64 5f 66  lite3_overload_f
377c0 75 6e 63 74 69 6f 6e 28 73 71 6c 69 74 65 33 2a  unction(sqlite3*
377d0 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46  , const char *zF
377e0 75 6e 63 4e 61 6d 65 2c 20 69 6e 74 20 6e 41 72  uncName, int nAr
377f0 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 69  g);../*.** The i
37800 6e 74 65 72 66 61 63 65 20 74 6f 20 74 68 65 20  nterface to the 
37810 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65  virtual-table me
37820 63 68 61 6e 69 73 6d 20 64 65 66 69 6e 65 64 20  chanism defined 
37830 61 62 6f 76 65 20 28 62 61 63 6b 20 75 70 0a 2a  above (back up.*
37840 2a 20 74 6f 20 61 20 63 6f 6d 6d 65 6e 74 20 72  * to a comment r
37850 65 6d 61 72 6b 61 62 6c 79 20 73 69 6d 69 6c 61  emarkably simila
37860 72 20 74 6f 20 74 68 69 73 20 6f 6e 65 29 20 69  r to this one) i
37870 73 20 63 75 72 72 65 6e 74 6c 79 20 63 6f 6e 73  s currently cons
37880 69 64 65 72 65 64 0a 2a 2a 20 74 6f 20 62 65 20  idered.** to be 
37890 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 54  experimental.  T
378a0 68 65 20 69 6e 74 65 72 66 61 63 65 20 6d 69 67  he interface mig
378b0 68 74 20 63 68 61 6e 67 65 20 69 6e 20 69 6e 63  ht change in inc
378c0 6f 6d 70 61 74 69 62 6c 65 20 77 61 79 73 2e 0a  ompatible ways..
378d0 2a 2a 20 49 66 20 74 68 69 73 20 69 73 20 61 20  ** If this is a 
378e0 70 72 6f 62 6c 65 6d 20 66 6f 72 20 79 6f 75 2c  problem for you,
378f0 20 64 6f 20 6e 6f 74 20 75 73 65 20 74 68 65 20   do not use the 
37900 69 6e 74 65 72 66 61 63 65 20 61 74 20 74 68 69  interface at thi
37910 73 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57 68  s time..**.** Wh
37920 65 6e 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74  en the virtual-t
37930 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 73  able mechanism s
37940 74 61 62 69 6c 69 7a 65 73 2c 20 77 65 20 77 69  tabilizes, we wi
37950 6c 6c 20 64 65 63 6c 61 72 65 20 74 68 65 0a 2a  ll declare the.*
37960 2a 20 69 6e 74 65 72 66 61 63 65 20 66 69 78 65  * interface fixe
37970 64 2c 20 73 75 70 70 6f 72 74 20 69 74 20 69 6e  d, support it in
37980 64 65 66 69 6e 69 74 65 6c 79 2c 20 61 6e 64 20  definitely, and 
37990 72 65 6d 6f 76 65 20 74 68 69 73 20 63 6f 6d 6d  remove this comm
379a0 65 6e 74 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 20 45  ent..**.****** E
379b0 58 50 45 52 49 4d 45 4e 54 41 4c 20 2d 20 73 75  XPERIMENTAL - su
379c0 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20  bject to change 
379d0 77 69 74 68 6f 75 74 20 6e 6f 74 69 63 65 20 2a  without notice *
379e0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2f  *************.*/
379f0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
37a00 3a 20 41 20 48 61 6e 64 6c 65 20 54 6f 20 41 6e  : A Handle To An
37a10 20 4f 70 65 6e 20 42 4c 4f 42 20 7b 46 31 37 38   Open BLOB {F178
37a20 30 30 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  00}.**.** An ins
37a30 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
37a40 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20  ject represents 
37a50 61 6e 20 6f 70 65 6e 20 42 4c 4f 42 20 6f 6e 20  an open BLOB on 
37a60 77 68 69 63 68 0a 2a 2a 20 69 6e 63 72 65 6d 65  which.** increme
37a70 6e 74 61 6c 20 49 2f 4f 20 63 61 6e 20 62 65 20  ntal I/O can be 
37a80 70 72 65 66 6f 72 6d 65 64 2e 0a 2a 2a 20 4f 62  preformed..** Ob
37a90 6a 65 63 74 73 20 6f 66 20 74 68 69 73 20 74 79  jects of this ty
37aa0 70 65 20 61 72 65 20 63 72 65 61 74 65 64 20 62  pe are created b
37ab0 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c  y.** [sqlite3_bl
37ac0 6f 62 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20 64  ob_open()] and d
37ad0 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c  estroyed by [sql
37ae0 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28  ite3_blob_close(
37af0 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  )]..** The [sqli
37b00 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29 5d  te3_blob_read()]
37b10 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 6c   and [sqlite3_bl
37b20 6f 62 5f 77 72 69 74 65 28 29 5d 20 69 6e 74 65  ob_write()] inte
37b30 72 66 61 63 65 73 0a 2a 2a 20 63 61 6e 20 62 65  rfaces.** can be
37b40 20 75 73 65 64 20 74 6f 20 72 65 61 64 20 6f 72   used to read or
37b50 20 77 72 69 74 65 20 73 6d 61 6c 6c 20 73 75 62   write small sub
37b60 73 65 63 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  sections of the 
37b70 62 6c 6f 62 2e 0a 2a 2a 20 54 68 65 20 5b 73 71  blob..** The [sq
37b80 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73  lite3_blob_bytes
37b90 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  ()] interface re
37ba0 74 75 72 6e 73 20 74 68 65 20 73 69 7a 65 20 6f  turns the size o
37bb0 66 20 74 68 65 0a 2a 2a 20 62 6c 6f 62 20 69 6e  f the.** blob in
37bc0 20 62 79 74 65 73 2e 0a 2a 2f 0a 74 79 70 65 64   bytes..*/.typed
37bd0 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
37be0 33 5f 62 6c 6f 62 20 73 71 6c 69 74 65 33 5f 62  3_blob sqlite3_b
37bf0 6c 6f 62 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  lob;../*.** CAPI
37c00 33 52 45 46 3a 20 4f 70 65 6e 20 41 20 42 4c 4f  3REF: Open A BLO
37c10 42 20 46 6f 72 20 49 6e 63 72 65 6d 65 6e 74 61  B For Incrementa
37c20 6c 20 49 2f 4f 20 7b 46 31 37 38 31 30 7d 0a 2a  l I/O {F17810}.*
37c30 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66  *.** This interf
37c40 61 63 65 73 20 6f 70 65 6e 73 20 61 20 68 61 6e  aces opens a han
37c50 64 6c 65 20 74 6f 20 74 68 65 20 62 6c 6f 62 20  dle to the blob 
37c60 6c 6f 63 61 74 65 64 0a 2a 2a 20 69 6e 20 72 6f  located.** in ro
37c70 77 20 69 52 6f 77 2c 2c 20 63 6f 6c 75 6d 6e 20  w iRow,, column 
37c80 7a 43 6f 6c 75 6d 6e 2c 20 74 61 62 6c 65 20 7a  zColumn, table z
37c90 54 61 62 6c 65 20 69 6e 20 64 61 74 61 62 61 73  Table in databas
37ca0 65 20 7a 44 62 3b 0a 2a 2a 20 69 6e 20 6f 74 68  e zDb;.** in oth
37cb0 65 72 20 77 6f 72 64 73 2c 20 20 74 68 65 20 73  er words,  the s
37cc0 61 6d 65 20 62 6c 6f 62 20 74 68 61 74 20 77 6f  ame blob that wo
37cd0 75 6c 64 20 62 65 20 73 65 6c 65 63 74 65 64 20  uld be selected 
37ce0 62 79 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a  by:.**.** <pre>.
37cf0 2a 2a 20 20 20 20 20 53 45 4c 45 43 54 20 7a 43  **     SELECT zC
37d00 6f 6c 75 6d 6e 20 46 52 4f 4d 20 7a 44 62 2e 7a  olumn FROM zDb.z
37d10 54 61 62 6c 65 20 57 48 45 52 45 20 72 6f 77 69  Table WHERE rowi
37d20 64 20 3d 20 69 52 6f 77 3b 0a 2a 2a 20 3c 2f 70  d = iRow;.** </p
37d30 72 65 3e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20  re> {END}.**.** 
37d40 49 66 20 74 68 65 20 66 6c 61 67 73 20 70 61 72  If the flags par
37d50 61 6d 65 74 65 72 20 69 73 20 6e 6f 6e 2d 7a 65  ameter is non-ze
37d60 72 6f 2c 20 74 68 65 20 62 6c 6f 62 20 69 73 20  ro, the blob is 
37d70 6f 70 65 6e 65 64 20 66 6f 72 20 0a 2a 2a 20 72  opened for .** r
37d80 65 61 64 20 61 6e 64 20 77 72 69 74 65 20 61 63  ead and write ac
37d90 63 65 73 73 2e 20 49 66 20 69 74 20 69 73 20 7a  cess. If it is z
37da0 65 72 6f 2c 20 74 68 65 20 62 6c 6f 62 20 69 73  ero, the blob is
37db0 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64   opened for read
37dc0 20 0a 2a 2a 20 61 63 63 65 73 73 2e 0a 2a 2a 0a   .** access..**.
37dd0 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73 2c 20 5b  ** On success, [
37de0 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65  SQLITE_OK] is re
37df0 74 75 72 6e 65 64 20 61 6e 64 20 74 68 65 20 6e  turned and the n
37e00 65 77 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ew .** [sqlite3_
37e10 62 6c 6f 62 20 7c 20 62 6c 6f 62 20 68 61 6e 64  blob | blob hand
37e20 6c 65 5d 20 69 73 20 77 72 69 74 74 65 6e 20 74  le] is written t
37e30 6f 20 2a 70 70 42 6c 6f 62 2e 20 0a 2a 2a 20 4f  o *ppBlob. .** O
37e40 74 68 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f  therwise an erro
37e50 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e  r code is return
37e60 65 64 20 61 6e 64 20 0a 2a 2a 20 61 6e 79 20 76  ed and .** any v
37e70 61 6c 75 65 20 77 72 69 74 74 65 6e 20 74 6f 20  alue written to 
37e80 2a 70 70 42 6c 6f 62 20 73 68 6f 75 6c 64 20 6e  *ppBlob should n
37e90 6f 74 20 62 65 20 75 73 65 64 20 62 79 20 74 68  ot be used by th
37ea0 65 20 63 61 6c 6c 65 72 2e 0a 2a 2a 20 54 68 69  e caller..** Thi
37eb0 73 20 66 75 6e 63 74 69 6f 6e 20 73 65 74 73 20  s function sets 
37ec0 74 68 65 20 64 61 74 61 62 61 73 65 2d 68 61 6e  the database-han
37ed0 64 6c 65 20 65 72 72 6f 72 20 63 6f 64 65 20 61  dle error code a
37ee0 6e 64 20 6d 65 73 73 61 67 65 0a 2a 2a 20 61 63  nd message.** ac
37ef0 63 65 73 73 69 62 6c 65 20 76 69 61 20 5b 73 71  cessible via [sq
37f00 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d  lite3_errcode()]
37f10 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 72   and [sqlite3_er
37f20 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 0a 2a 2a 20  rmsg()]..** .** 
37f30 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
37f40 2a 20 7b 46 31 37 38 31 33 7d 20 41 20 73 75 63  * {F17813} A suc
37f50 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69  cessful invocati
37f60 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  on of the [sqlit
37f70 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 44 2c 42  e3_blob_open(D,B
37f80 2c 54 2c 43 2c 52 2c 46 2c 50 29 5d 0a 2a 2a 20  ,T,C,R,F,P)].** 
37f90 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 66 61           interfa
37fa0 63 65 20 6f 70 65 6e 73 20 61 6e 20 5b 73 71 6c  ce opens an [sql
37fb0 69 74 65 33 5f 62 6c 6f 62 5d 20 6f 62 6a 65 63  ite3_blob] objec
37fc0 74 20 50 20 6f 6e 20 74 68 65 20 62 6c 6f 62 0a  t P on the blob.
37fd0 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 63  **          in c
37fe0 6f 6c 75 6d 6e 20 43 20 6f 66 20 74 61 62 6c 65  olumn C of table
37ff0 20 54 20 69 6e 20 64 61 74 61 62 61 73 65 20 42   T in database B
38000 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f   on [database co
38010 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a  nnection] D..**.
38020 2a 2a 20 7b 46 31 37 38 31 34 7d 20 41 20 73 75  ** {F17814} A su
38030 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74  ccessful invocat
38040 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ion of [sqlite3_
38050 62 6c 6f 62 5f 6f 70 65 6e 28 44 2c 2e 2e 2e 29  blob_open(D,...)
38060 5d 20 73 74 61 72 74 73 0a 2a 2a 20 20 20 20 20  ] starts.**     
38070 20 20 20 20 20 61 20 6e 65 77 20 74 72 61 6e 73       a new trans
38080 61 63 74 69 6f 6e 20 6f 6e 20 5b 64 61 74 61 62  action on [datab
38090 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
380a0 44 20 69 66 20 74 68 61 74 20 63 6f 6e 6e 65 63  D if that connec
380b0 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  tion.**         
380c0 20 69 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 20   is not already 
380d0 69 6e 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  in a transaction
380e0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 38 31 36 7d  ..**.** {F17816}
380f0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c   The [sqlite3_bl
38100 6f 62 5f 6f 70 65 6e 28 44 2c 42 2c 54 2c 43 2c  ob_open(D,B,T,C,
38110 52 2c 46 2c 50 29 5d 20 69 6e 74 65 72 66 61 63  R,F,P)] interfac
38120 65 20 6f 70 65 6e 73 20 74 68 65 20 62 6c 6f 62  e opens the blob
38130 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 6f 72  .**          for
38140 20 72 65 61 64 20 61 6e 64 20 77 72 69 74 65 20   read and write 
38150 61 63 63 65 73 73 20 69 66 20 61 6e 64 20 6f 6e  access if and on
38160 6c 79 20 69 66 20 74 68 65 20 46 20 70 61 72 61  ly if the F para
38170 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  meter.**        
38180 20 20 69 73 20 6e 6f 6e 2d 7a 65 72 6f 2e 0a 2a    is non-zero..*
38190 2a 0a 2a 2a 20 7b 46 31 37 38 31 39 7d 20 54 68  *.** {F17819} Th
381a0 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  e [sqlite3_blob_
381b0 6f 70 65 6e 28 29 5d 20 69 6e 74 65 72 66 61 63  open()] interfac
381c0 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  e returns [SQLIT
381d0 45 5f 4f 4b 5d 20 6f 6e 20 0a 2a 2a 20 20 20 20  E_OK] on .**    
381e0 20 20 20 20 20 20 73 75 63 63 65 73 73 20 61 6e        success an
381f0 64 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65  d an appropriate
38200 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 6e   [error code] on
38210 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20   failure..**.** 
38220 7b 46 31 37 38 32 31 7d 20 49 66 20 61 6e 20 65  {F17821} If an e
38230 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69  rror occurs duri
38240 6e 67 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66  ng evaluation of
38250 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f   [sqlite3_blob_o
38260 70 65 6e 28 44 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20  pen(D,...)].**  
38270 20 20 20 20 20 20 20 20 74 68 65 6e 20 73 75 62          then sub
38280 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
38290 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64   [sqlite3_errcod
382a0 65 28 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  e(D)],.**       
382b0 20 20 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d     [sqlite3_errm
382c0 73 67 28 44 29 5d 2c 20 61 6e 64 20 5b 73 71 6c  sg(D)], and [sql
382d0 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 44 29  ite3_errmsg16(D)
382e0 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a  ] will return.**
382f0 20 20 20 20 20 20 20 20 20 20 69 6e 66 6f 72 6d            inform
38300 61 74 69 6f 6e 20 61 70 70 72 6f 70 72 61 74 65  ation approprate
38310 20 66 6f 72 20 74 68 61 74 20 65 72 72 6f 72 2e   for that error.
38320 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
38330 62 6c 6f 62 5f 6f 70 65 6e 28 0a 20 20 73 71 6c  blob_open(.  sql
38340 69 74 65 33 2a 2c 0a 20 20 63 6f 6e 73 74 20 63  ite3*,.  const c
38350 68 61 72 20 2a 7a 44 62 2c 0a 20 20 63 6f 6e 73  har *zDb,.  cons
38360 74 20 63 68 61 72 20 2a 7a 54 61 62 6c 65 2c 0a  t char *zTable,.
38370 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 43    const char *zC
38380 6f 6c 75 6d 6e 2c 0a 20 20 73 71 6c 69 74 65 33  olumn,.  sqlite3
38390 5f 69 6e 74 36 34 20 69 52 6f 77 2c 0a 20 20 69  _int64 iRow,.  i
383a0 6e 74 20 66 6c 61 67 73 2c 0a 20 20 73 71 6c 69  nt flags,.  sqli
383b0 74 65 33 5f 62 6c 6f 62 20 2a 2a 70 70 42 6c 6f  te3_blob **ppBlo
383c0 62 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  b.);../*.** CAPI
383d0 33 52 45 46 3a 20 20 43 6c 6f 73 65 20 41 20 42  3REF:  Close A B
383e0 4c 4f 42 20 48 61 6e 64 6c 65 20 7b 46 31 37 38  LOB Handle {F178
383f0 33 30 7d 0a 2a 2a 0a 2a 2a 20 43 6c 6f 73 65 20  30}.**.** Close 
38400 61 6e 20 6f 70 65 6e 20 5b 73 71 6c 69 74 65 33  an open [sqlite3
38410 5f 62 6c 6f 62 20 7c 20 62 6c 6f 62 20 68 61 6e  _blob | blob han
38420 64 6c 65 5d 2e 0a 2a 2a 0a 2a 2a 20 43 6c 6f 73  dle]..**.** Clos
38430 69 6e 67 20 61 20 42 4c 4f 42 20 73 68 61 6c 6c  ing a BLOB shall
38440 20 63 61 75 73 65 20 74 68 65 20 63 75 72 72 65   cause the curre
38450 6e 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74  nt transaction t
38460 6f 20 63 6f 6d 6d 69 74 0a 2a 2a 20 69 66 20 74  o commit.** if t
38470 68 65 72 65 20 61 72 65 20 6e 6f 20 6f 74 68 65  here are no othe
38480 72 20 42 4c 4f 42 73 2c 20 6e 6f 20 70 65 6e 64  r BLOBs, no pend
38490 69 6e 67 20 70 72 65 70 61 72 65 64 20 73 74 61  ing prepared sta
384a0 74 65 6d 65 6e 74 73 2c 20 61 6e 64 20 74 68 65  tements, and the
384b0 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
384c0 6e 65 63 74 69 6f 6e 20 69 73 20 69 6e 20 61 75  nection is in au
384d0 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 2e 0a 2a  tocommit mode..*
384e0 2a 20 49 66 20 61 6e 79 20 77 72 69 74 65 73 20  * If any writes 
384f0 77 65 72 65 20 6d 61 64 65 20 74 6f 20 74 68 65  were made to the
38500 20 42 4c 4f 42 2c 20 74 68 65 79 20 6d 69 67 68   BLOB, they migh
38510 74 20 62 65 20 68 65 6c 64 20 69 6e 20 63 61 63  t be held in cac
38520 68 65 0a 2a 2a 20 75 6e 74 69 6c 20 74 68 65 20  he.** until the 
38530 63 6c 6f 73 65 20 6f 70 65 72 61 74 69 6f 6e 20  close operation 
38540 69 66 20 74 68 65 79 20 77 69 6c 6c 20 66 69 74  if they will fit
38550 2e 20 7b 45 4e 44 7d 0a 2a 2a 20 43 6c 6f 73 69  . {END}.** Closi
38560 6e 67 20 74 68 65 20 42 4c 4f 42 20 6f 66 74 65  ng the BLOB ofte
38570 6e 20 66 6f 72 63 65 73 20 74 68 65 20 63 68 61  n forces the cha
38580 6e 67 65 73 0a 2a 2a 20 6f 75 74 20 74 6f 20 64  nges.** out to d
38590 69 73 6b 20 61 6e 64 20 73 6f 20 69 66 20 61 6e  isk and so if an
385a0 79 20 49 2f 4f 20 65 72 72 6f 72 73 20 6f 63 63  y I/O errors occ
385b0 75 72 2c 20 74 68 65 79 20 77 69 6c 6c 20 6c 69  ur, they will li
385c0 6b 65 6c 79 20 6f 63 63 75 72 0a 2a 2a 20 61 74  kely occur.** at
385d0 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e 20 74   the time when t
385e0 68 65 20 42 4c 4f 42 20 69 73 20 63 6c 6f 73 65  he BLOB is close
385f0 64 2e 20 20 7b 46 31 37 38 33 33 7d 20 41 6e 79  d.  {F17833} Any
38600 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63   errors that occ
38610 75 72 20 64 75 72 69 6e 67 0a 2a 2a 20 63 6c 6f  ur during.** clo
38620 73 69 6e 67 20 61 72 65 20 72 65 70 6f 72 74 65  sing are reporte
38630 64 20 61 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20  d as a non-zero 
38640 72 65 74 75 72 6e 20 76 61 6c 75 65 2e 0a 2a 2a  return value..**
38650 0a 2a 2a 20 54 68 65 20 42 4c 4f 42 20 69 73 20  .** The BLOB is 
38660 63 6c 6f 73 65 64 20 75 6e 63 6f 6e 64 69 74 69  closed unconditi
38670 6f 6e 61 6c 6c 79 2e 20 20 45 76 65 6e 20 69 66  onally.  Even if
38680 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   this routine re
38690 74 75 72 6e 73 0a 2a 2a 20 61 6e 20 65 72 72 6f  turns.** an erro
386a0 72 20 63 6f 64 65 2c 20 74 68 65 20 42 4c 4f 42  r code, the BLOB
386b0 20 69 73 20 73 74 69 6c 6c 20 63 6c 6f 73 65 64   is still closed
386c0 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
386d0 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 38 33  TS:.**.** {F1783
386e0 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  3} The [sqlite3_
386f0 62 6c 6f 62 5f 63 6c 6f 73 65 28 50 29 5d 20 69  blob_close(P)] i
38700 6e 74 65 72 66 61 63 65 20 63 6c 6f 73 65 73 20  nterface closes 
38710 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  an.**          [
38720 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5d 20 6f 62  sqlite3_blob] ob
38730 6a 65 63 74 20 50 20 70 72 65 76 69 6f 75 73 6c  ject P previousl
38740 79 20 6f 70 65 6e 65 64 20 75 73 69 6e 67 0a 2a  y opened using.*
38750 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
38760 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d  te3_blob_open()]
38770 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 38 33 36 7d  ..**.** {F17836}
38780 20 43 6c 6f 73 69 6e 67 20 61 6e 20 5b 73 71 6c   Closing an [sql
38790 69 74 65 33 5f 62 6c 6f 62 5d 20 6f 62 6a 65 63  ite3_blob] objec
387a0 74 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20  t using.**      
387b0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f      [sqlite3_blo
387c0 62 5f 63 6c 6f 73 65 28 29 5d 20 73 68 61 6c 6c  b_close()] shall
387d0 20 63 61 75 73 65 20 74 68 65 20 63 75 72 72 65   cause the curre
387e0 6e 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74  nt transaction t
387f0 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f  o.**          co
38800 6d 6d 69 74 20 69 66 20 74 68 65 72 65 20 61 72  mmit if there ar
38810 65 20 6e 6f 20 6f 74 68 65 72 20 6f 70 65 6e 20  e no other open 
38820 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5d 20 6f  [sqlite3_blob] o
38830 62 6a 65 63 74 73 0a 2a 2a 20 20 20 20 20 20 20  bjects.**       
38840 20 20 20 6f 72 20 5b 70 72 65 70 61 72 65 64 20     or [prepared 
38850 73 74 61 74 65 6d 65 6e 74 73 5d 20 6f 6e 20 74  statements] on t
38860 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73  he same [databas
38870 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e  e connection] an
38880 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  d.**          th
38890 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
388a0 65 63 74 69 6f 6e 5d 20 69 73 20 69 6e 0a 2a 2a  ection] is in.**
388b0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
388c0 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69  e3_get_autocommi
388d0 74 20 7c 20 61 75 74 6f 63 6f 6d 6d 69 74 20 6d  t | autocommit m
388e0 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37  ode]..**.** {F17
388f0 38 33 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  839} The [sqlite
38900 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 50 29 5d  3_blob_close(P)]
38910 20 69 6e 74 65 72 66 61 63 65 73 20 63 6c 6f 73   interfaces clos
38920 65 73 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 20  es the .**      
38930 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f      [sqlite3_blo
38940 62 5d 20 6f 62 6a 65 63 74 20 50 20 75 6e 63 6f  b] object P unco
38950 6e 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 65 76 65  nditionally, eve
38960 6e 20 69 66 0a 2a 2a 20 20 20 20 20 20 20 20 20  n if.**         
38970 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63   [sqlite3_blob_c
38980 6c 6f 73 65 28 50 29 5d 20 72 65 74 75 72 6e 73  lose(P)] returns
38990 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72   something other
389a0 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b   than [SQLITE_OK
389b0 5d 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 0a  ]..**          .
389c0 2a 2